punkshell

1 Tag

223 MiB

Author	SHA1	Message	Date
Julian Noble	5037a9b51d	.test authoring guard-rails: testbody_lint.tcl, runtests empty-actual hint, sanction 'return $result'; fix vacuous args.test test - scriptlib/developer/testbody_lint.tcl (new): tcltest .test lint per src/tests/AGENTS.md Verification. E-level: a -body whose final command always returns empty vs a -result that cannot match empty under its -match mode; test invocations with no -body at all (vacuous pass); unbalanced-brace parse kills. W-level: uninterpretable shapes. Hand-rolled command-word splitter (the corpus '{desc}\' style is command-legal but list-illegal), namespace-eval recursion, literal {*}{...} splices, -selftest (8 fixtures) + -stats. 142 files / 1674 tests parse clean. - src/tests/runtests.tcl: FAILED reports with an empty actual and a non-empty expected append a hint= (compact) / hint : (markdown) line naming the trailing 'set result'/'return $result' convention, so the failure carries its own diagnosis. JSON reports unchanged. - src/tests/modules/punk/args/testsuites/args/args.test: the literalprefix sibling of parse_withdef_value_leading_multiple_not_greedy was passing VACUOUSLY - a missing description made the braced description word swallow -setup/-body/-cleanup/-result, so tcltest ran an empty body against the default -result "". Description restored, orphan closing brace removed; the de-vacuized test executes and passes (file 34/34). - AGENTS.md (root), src/tests/AGENTS.md, .agents/.claude tcl-runtests SKILL.md (byte-identical copies): the body-ender convention now sanctions 'return $result' alongside 'set result' (verified on 8.6 and 9.0: default -returnCodes {ok return} accepts the return form, -cleanup still runs, an explicit -returnCodes list omitting 'return' rejects it loudly); linter and hint documented. Verification: testbody_lint -selftest PASS on tclsh90s and tclsh86ts; corpus lint clean; args.test 34/34; full suite in both runner modes with runtests_parity.tcl PARITY: ok (1677 tests, 1631 pass). Residual 23 failures are pre-existing/environment, not this change: 12 maketclhelp (auto_execok tclsh Bash-env trap; pass under PowerShell), 8 maketcllibfetch + 2 maketclbakelist (reproduce identically with this runtests.tcl change stashed), core exec-14.3 (pins the pre-'-encoding' exec error message vs tcl 9.0.5). Claude-Session: https://claude.ai/code/session_016Bk571eG3prsJWYnewboW2 Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com	2 days ago
Julian Noble	a58d0117f4	Add punkpath agent skill: PATH-executable resolution + Tcl-command clash diagnosis A new .agents/skills/punkpath/SKILL.md (canonical) with a byte-identical .claude/skills/punkpath/SKILL.md copy for Claude Code discovery (verified sync with a plain diff). Models the tcl-whatis/tcl-nslist shape: a single ~0.7s side-effect-free punkshell invocation answering two questions agents guess wrong: 1. Which PATH executable a bare command name actually runs, and what shadows it (overshadowed/overshadowed_by entry-idx fields). This is the diagnostic companion to the tcl-runtests warning that bare tclsh from a Bash tool often resolves to the MSYS tclsh - the skill gets the machine-readable verdict on which copy wins instead of guessing. 2. Whether a PATH executable clashes with a Tcl command (tcl_conflicts command:match=exact\|nocase) - the 'invalid command name X' where X is X.exe on PATH (dir/sort/find/clip). Documents the -return json/text/dict forms, the -pathglob/-conflicts filters, and the -context lever (G-173: pass it for a stable conflict verdict through a wrapper/one-liner; the default-caller namespace is for interactive use). Scope kept tight to PATH-resolution and Tcl-command clash; explicitly disclaims being a general 'what is installed' tool. No root AGENTS.md index change (the .agents/skills/ entry is generic and does not list individual skills, matching the tcl-whatis/tcl-nslist/ tcl-runtests handling). Assisted-by: harness=pi; primary-model=huggingface/zai-org/GLM-5.2; api-location=huggingface.co	3 days ago
Julian Noble	9d92c11bd7	agent skills: tcl-runtests added; whatis/nslist gain the script -e quick-probe line tcl-runtests (new): agent quickstart for src/tests/runtests.tcl. Runner-interpreter policy: the zig-built suite tclsh (src/buildsuites/_build/suite_tcl90/out/bin/tclsh90s; tclsh86ts for 8.6 parity) or a bin/runtime store tclsh; a fresh checkout bootstraps via the no-tclsh 'zig build bootstrap' flow (pinned zig only, bin/punk-getzig) or by fetching prebuilt runtimes from punkbin via bin/punk-runtime - which path is the user's choice, not an agent default. Never bare 'tclsh' from an agent shell (commonly the MSYS/Git-for-Windows one - spurious failures); native tclsh preferred over punk kit exes (kit-stamped module shadowing). Plus canonical invocation/targeting forms, result-reading rules (status=warn = incomplete), agent-environment traps (NO_COLOR=1 breaks exact-SGR pins agent-side only; PowerShell-tool attached consoles; no mid-run .test edits; PUNK_SHELL_TEST_EXE for locked/stale kit exes) and .test authoring micro-traps (trailing 'set result', brace-in-comment parse death, \y-not-\b). Pointer-first: src/tests/AGENTS.md remains the authoritative harness contract. tcl-whatis/tcl-nslist: one sentence added to the Command section - the launcher one-liner form `bin/punk91 src script -e '<tcl>'` for RUNNING a snippet rather than introspecting it (behaviour checks, cross-version probes via the documented punk905/punksys kits). Facts verified live before writing: suite tclsh90s = Tcl 9.0.5 + Thread 3.0.7 and drove a focused runtests run (args dynamic.test 2/2 PASS, 5s); runtime-store tclsh9.0.5-punk/plain = 9.0.5 + Thread 3.0.7; -e forms on punk91/punk905/punksys; punk-runtime list output; PUNK_SHELL_TEST_EXE resolution in the punkexe suites. .claude/skills copies are byte-identical re-copies of the .agents canonicals (diff-verified) per the root AGENTS.md skill sync convention. Claude-Session: https://claude.ai/code/session_01Y1diJnhjUxKgEG6EwYAzxj Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com	4 days ago
Julian Noble	2a7fbafa77	tcl-whatis/tcl-nslist skills: kit Tcl-version note (punk91=9.1, punk905=9.0, punksys=8.6) The skills pinned bin/punk91 but never stated which Tcl it embeds, and the "any punkshell kit works" fallback was unqualified - Tcl-version-sensitive introspection questions (e.g. 8.6-vs-9 builtin differences) left the agent to work out kit versions unaided, in a bin/ full of non-kit exes. Add one sentence to each skill's Command section: punk91 embeds Tcl 9.1; for Tcl-version-sensitive questions, or if punk91 is unavailable, use punk905 (Tcl 9.0) or punksys (Tcl 8.6) with the same command line. Stated versions smoke-verified against the live kits (9.1b0 / 9.0.5 / 8.6.13). Canonical .agents/skills copies edited; .claude/skills re-copied and diff-verified byte-identical per the root AGENTS.md sync convention. Frontmatter descriptions untouched, so skill firing is unchanged. Claude-Session: https://claude.ai/code/session_01Y1diJnhjUxKgEG6EwYAzxj Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com	4 days ago
Julian Noble	1491d90b5f	skills: quote YAML frontmatter descriptions for strict-parser compatibility The tcl-whatis and tcl-nslist skill descriptions contained ': ' mid-string, which is illegal in a plain YAML scalar and broke frontmatter parsing in strict harnesses. Wrap both description values in double quotes (all four copies: .agents/skills and .claude/skills). Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com	3 weeks ago
Julian Noble	220de61b3d	tcl-whatis/tcl-nslist skills: directive-first triggers, lib: short invocations, pre-approved permissions The skills existed but sessions never leaned on them - grep+read wins the tool-selection contest when descriptions are phrased as information needs ("use when you need to know how to call...") rather than task triggers, and grep 'succeeds' without revealing which of the repo's coexisting module copies is loaded. Changes to convert them from available options into workflow steps: - SKILL.md descriptions rewritten task-first ("Use BEFORE reviewing, testing, editing..." / "Use BEFORE writing any new Tcl helper..."), with run-it-first wording, the multiple-module-copies rationale, and cost stated up front (one sub-1s side-effect-free invocation). - Invocations shortened to lib: script-path form (verified working, ~0.45s each): punk91 src script lib:developer/whatis\|nslist. - New caveat in both: prefer the Bash tool over PowerShell (attached console can flip colour/terminal detection in punkshell children). - AGENTS.md Repo-wide Notes entry converted from reference note to DIRECTIVE: whatis/nslist first, grep reserved for full-text searches. - .claude/settings.json: allow entries for both scripts (Bash + PowerShell, punk91/bin/punk91/./bin/punk91 prefixes) so first use is prompt-free. .claude/skills copies re-synced from canonical .agents/skills (diff-verified byte-identical). Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com	3 weeks ago
Julian Noble	4fc1d62ce2	agent skills: tcl-nslist namespace discovery; punk::ns 0.9.1 packagetails fix New scriptlib/developer/nslist.tcl backing the new cross-framework tcl-nslist agent skill (.agents/skills/ canonical, .claude/skills/ synced copy): the discovery counterpart of whatis.tcl - lists what a namespace/package actually exposes at runtime via punk::ns::get_ns_dicts (the n// machinery): child namespaces with loadable-package markers, commands classified by kind, punk::args-documented commands, -synopsis whole-namespace usage lines, -pathcommands namespace-path resolution. Auto-package-requires unloaded packages and follows ensemble commands to their implementation namespace. The tcl-whatis skill/script cross-reference it (whatis redirects with a hint when the queried name is a namespace, not a command). punk::ns 0.9.1: get_ns_dicts packagetails/packageprefixes initialization moved inside the per-namespace loop - with multiple matched namespaces (path globs, trailing **) every dict after the first carried the union of all earlier namespaces' entries, mis-marking non-package children in nslist/n// underline styling and in the returned data; a child with several deeper packages below it was appended to packageprefixes once per matching package (now once). Pinned in nslist.test (nslist_classification_multins_package_buckets_reset). Documentation-only PUNKARGS added for get_ns_dicts (returned dict keys documented) and nslist_dict; parsing stays manual. Root AGENTS.md: introspection note + scriptlib/developer inventory updated. Project version 0.15.1 + CHANGELOG entry. punk::ns suite 102/102 pass. Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com	3 weeks ago
Julian Noble	75cffe21f3	punk::args 0.12.6 + punk::ns 0.9.0: LLM-oriented usage output; tcl-whatis agent skill punk::ns 0.9.0: cmdhelp (i) gains -return text - plain-text argument documentation for machine/LLM consumption: no ANSI, no table layout, the argument section of every command form rendered in one output under a common header ('i -return text after' shows all six forms), G-041 form selection still honoured when argument words are supplied, no advisory-parse error preamble (-return dict remains the parse-status surface). Implementation delegates resolution to the -return dict recursion and renders per-form via the string renderer. punk::args 0.12.6 (user direction; string-form layout explicitly not frozen - no external consumers yet): - arg_error renders the error message + per-form match detail exactly once, BELOW the usage display (was above and below); bottom append suppressed for empty messages. - string renderer argument rows are single-line 'name TYPE:type(constraints) ?DEFAULT:'val'? ?MULTI:yes?' - type constraints parenthesize onto the base type instead of line-breaking mid-row; empty DEFAULT/MULTI labels and whitespace-only help blocks omitted. - choices render as markdown-subset bullets '- `choice` - label' with label continuations at a fixed deeper indent - choice names are now machine-distinguishable from label text without ANSI. Structural contract: column-0 lines bearing TYPE: are argument rows, indented lines are documentation, backticked bullets are choices. Table cells unchanged. New scriptlib/developer/whatis.tcl (runtime command introspection for agents): resolved name, subcommand-chain resolution via punk::ns::cmdinfo ('whatis string is'), kind, providing package + loaded version, origin file, proc definition file:line, punk::args synopsis; -body appends the runtime body with file-relative line numbers, -doc the full plain-text argdoc via cmdhelp -return text (with fallback for older punk::ns). Backing the cross-framework tcl-whatis agent skill: canonical .agents/skills/tcl-whatis/ (Agent Skills standard - pi/OpenCode/Codex) with byte-identical copy in .claude/skills/ for Claude Code; .gitignore gains !.claude/skills/ with the fossil ignore-glob comment + exception-set docs updated per the dual-VCS contract (fossil adds staged). Root AGENTS.md: .agents/skills index entry, whatis pointer in Repo-wide Notes, scriptlib/developer example. Tests: new pins cmdhelp_return_text_all_forms/_argword_form_selection/ _single_form_plain_marker (cmdhelp.test), rendering_stringmode_singleline_argrows + rendering_stringmode_choice_bullets (rendering.test); deliberate-change pin updates: errorselection.test message matches gained leading * and cmdhelp.test message pins sample the last line (message placement). Full source-tree suite 963/979 pass, sole failure the pre-existing exec-14.3 baseline; make.tcl modules clean. Project version 0.12.42 -> 0.13.0 with CHANGELOG.md entry. Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com	3 weeks ago
Julian Noble	06db38be46	agent guardrails: tclsh has no -e one-liner flag - AGENTS.md pitfall entry + claude PreToolUse deny hook Stock tclsh treats any leading-dash arg other than -encoding as argv for an interactive/stdin session: on a console it hangs at a prompt, with piped stdin it exits 0 silently ignoring the supposed one-liner. Agents habitually reach for -e (perl/python/node reflex), wasting time waiting on hung processes. - root AGENTS.md User Preferences: document the misparse, the correct patterns (temp .tcl file or script via stdin) and the defensive stdin-redirect habit - .claude/settings.json: PreToolUse hook denying Bash/PowerShell invocations of tclsh with -e, anchored to command position (start/pipe/semicolon/paren) so prose mentions in commit messages or grep args do not false-positive; corrective guidance returned to the agent - .gitignore: narrow the .claude ignore so shared settings.json is tracked while session-local files stay ignored - .fossil-settings: ignore-glob hand-derived per the no-negation rule (.claude/* wholesale + explicit fossil add of settings.json), exception set in AGENTS.md updated; fossil extras under-ignore check verified empty Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com	4 weeks ago

9 Commits (de4c69b68e8e52043bde35d5e0823cc887317940)