punkshell

1 Tag

229 MiB

Author	SHA1	Message	Date
Julian Noble	c1c27ea37c	G-170 achieved: launcher help depth - form narrowing, parse-true dry-run, actionable form hints (core 0.7.0, punkexe moduledoc 0.9.0, app-punkscript 1.3) User-directed activation and implementation in one arc ("Activate G-170 and continue"; proposed -> active at the user's word with the activation-freshness survey recorded - new Related lines both directions for G-167 and G-044 - -> achieved + archived on acceptance). Completes the launcher family: G-151 parse_report + G-168 selection-sound definitions + G-169 app-owned docs + this goal's consumption of all three. punkboot core 0.7.0 (both layout copies synced byte-identical: project-0.1 + modpod-template): launcher_show_help gains a tailwords parameter and returns the suggested exit code (0 for every render, 1 only for a rejected dry-run); the dispatch help arm passes the words after the subject and exits with the return. Three tail behaviours by subject: - Narrowing (any multi-form definition, display-only, any vintage): a SINGLE word exactly matching a form name, or a decimal ordinal below the form count, renders 'punk::args::usage -form <sel> <id>' - the G-150 shape (all-form synopsis retained, the selected form's argument table only). Collision rule decided and documented: in this position the form word WINS over argument interpretation (exact names + decimal ordinals only, no prefix resolution - the tighter rule minimises the shadow over the subject's own first-argument space); a file literally named like a form stays dry-runnable via a path spelling (./oneliner - the same reachability dodge G-168 recorded for a file named '-e'). - Dry-run (parse-true subjects): any other tail parses through the subject's definition exactly as make.tcl help does (G-143 shape). Accepted lines render the matched form's usage plus the punk::args::parse_report landing report (G-151 consumed directly; guarded - an older punk::args without parse_report renders the usage alone). Rejected lines emit the parse diagnosis on stderr, exit 1. The complete '-encoding <name> <scriptfile>' tclsh line raises the sanctioned two-form multipleformmatches diagnosis (the recorded G-168 LIMIT - the honest answer for that line). Parse-true = buildinfo + project parse=1 registrations (parity with dispatch BY CONSTRUCTION - dispatch parses the same id, any vintage) plus script/tclsh (declared passthrough surfaces whose G-168 definitions MODEL dispatch/app reality - their dry-run additionally requires the fence witness: at least one -regexprefail row in the definition actually served, so a pre-G-168 unfenced moduledoc snapshot - the real mixed promotion state - keeps the historic ignored-tail render instead of misdiagnosing lines whose forms double-match; probed live against the baked 0.6.1 stack). 'help' itself is deliberately NOT parse-true (its tail handling IS this dispatch). - Passthrough (shell/punk/shellspy, registrations without parse=1) and all degraded contexts (PUNKBOOT_PLAIN, missing stack, render failure): the historic accepted-and-ignored render, exit 0. Formhint un-suppression at BOTH homes (the G-169-decided split): the interim '@cmd -formhint ""' flips to the actionable template ' <punkexe> help <sub> %formname%' in the app-owned script definition (src/lib/app-punkscript/punkscript.tcl, app-punkscript/app-punkscript-docs 1.3) and the moduledoc tclsh definition (punkexe moduledoc 0.9.0) - the labels render beside each form's synopsis line and name real navigation, resolving the 0.6.1 circularity objection. Deliberately NO trailing ellipsis, diverging from make.tcl's hint shape: the display-hint honesty rule marks accepted continuations of the SAME operation, and appending words to the launcher's form word flips into the dry-run interpretation (a different operation) - the exact hinted line is the complete narrowing command. (script)::punkexe::help's @cmd/arg text documents the depth semantics (the 'accepted and ignored (reserved)' arg row cashed in as designed). Engine fact recorded: punk::args::usage takes its options BEFORE the positional id ('usage -form X $id'; the reversed order raises a values-count error) - caught by probe; layout copies synced before the fix were re-synced and cmp-verified after the last core edit. Tests: launcherhelp.test 38/38 on BOTH tclsh90 and tclsh87 - 25 existing pins unchanged (the two direct-kit trailing-word pins re-described as VINTAGE-PROOF: their assertions hold under both the historic ignored-tail core and the depth core, whatever the kit's bake vintage) + 13 new G-170 pins: narrowing by form name and ordinal, formhint labels, dry-run accept (matched form + Argument\|Source\|Value report), reject, the -encoding LIMIT, the ./oneliner collision dodge, passthrough ignored, buildinfo reject, project parse=1 accept/reject parity (same words as the dispatch-half pins launcherhelp_registration_parse_pass/_reject), the mixed-vintage fence witness, and the PUNKBOOT_PLAIN degraded twin. args subtree 337 passed / 3 pre-existing skips / 0 failed on both runtimes; punkexe subtree at the recorded baseline on both (152/4/10 - the 10 failures are the pre-existing maketclbakelist(2)/maketcllibfetch(8) set, G-139 pending user decision; maketclhelp 12/12 and scriptexec 27/27 green). A 12-probe live matrix (args level via bin/punk91 src + fake-main harness via bin/punk902z tclsh, src and no-src modes) recorded in the goal file. Minted punkexe-0.9.0.tm via make.tcl modules (mint tree, not committed by design). Kits/bootsupport/ vfscommon remain stale until the user-owned promotion + bake. Goals: G-170 entry moved to GOALS-archive.md, detail file to goals/archive/ with mechanism, decisions and verification evidence; two open Follow-ons (the coherent-set promotion - the same vfscommonupdate/bake event as G-169's line, now also carrying core 0.7.0 + punkexe 0.9.0 + app 1.3; a punkboot-moduledoc authoring hint that project definitions may carry their own formhint templates). Reference sweep: G-044 and G-167 back-pointers updated to achieved; G-044 gains the xref-flagged G-167 mirror line. src/vfs AGENTS.md launcher-help bullet and src/lib AGENTS.md app-punkscript bullet extended. goals_lint clean (80 active / 90 archived); goals_followons 74 structured lines, both new G-170 lines registered. Claude-Session: https://claude.ai/code/session_0156PuejSCGjgeGb7jiABrDU Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com	6 days ago
Julian Noble	b0c92567a3	G-151 achieved: punk::args::parse_report landing report + ansistring TRUNCATE (args 0.18.0, ansi 0.2.0) User-directed activation and implementation in one arc (proposed -> active at the user's word with the activation-freshness overlap survey recorded, -> achieved + archived on acceptance). punk::args 0.18.0 - new parse_report: the annotated SUCCESS render (the arg_error usage table's success-side sibling). One row per value-holding argument (received, or -default in effect) in declaration-section order (leaders, opts, values), columns Argument \| Source \| Value; Source carries received / received xN / default (the plain-mode twin of the colour marking: CLR(check)/CLR(parsekey_hint)); absent optionals get no row. Entry forms per acceptance: a punk::args::parse result dict, or '<arglist> withid <id>' (the parse is performed first - a rejected line raises the same validation error parse would; errorcode parity pinned). Returns: table (bordered textblock block, default), tableobject, string (plain lines; also the degraded no-textblock path), dict (machine form - never elided). The canonical demonstration pinned: {build punk95 -confirm 0} lands 'args (received x2) = -confirm 0' - a flag-like word consumed as a VALUE visibly attributed to its consuming argument (the make.tcl dry-run 'kitname = punk91 -confirm 0' class from the G-143 sessions). Display elision is type-aware, deterministic, always marked: strings single-line-ized (ansistring VIEW -lf 1 -vt 1 -sp 0 - controls and embedded ANSI render visibly so a value cannot disturb the table, real spaces stay real) then grapheme-capped with '...' + ' (len N)'; -multiple/-type list values element-capped '(+N more)'; -type dict values pair-capped '(+N pairs)'. Width cascade per the G-149 plumbing precedent: caller -valuewidth > new @cmd directive key -reportvaluewidth (documented in define -help) > built-in 48; 0 = no cap; never console-derived (the G-007 emit-then-query lesson). Row data rides the G-049 private::parse_status_build structure - no second status assembler; display-level bridging recovers the value-in-effect across the parse result's storage-key folds (-parsekey renames, aliased optionsets' last-\|-member finalopts fold) so received aliased args keep their row - engine-level rationalization recorded as a G-084 follow-on disposition. The registered two-form definition (parsed/withid) follows parse_status's structure - per-form @leaders first, then the shared @opts via a re-widened @form selection (the resolver rejects leaders declared after a form's options). punk::ansi 0.2.0 - new ansistring TRUNCATE ?-ellipsis marker? string maxgraphemes (design lean 4: the ANSI/grapheme-safe truncate primitive homes in ansistring beside RANGE/VIEW): fits => byte-identical passthrough (trailing and non-SGR codes included); truncation => RANGE-extracted prefix (merged SGR re-application per the contract documented at 0.1.4) + marker totalling exactly maxgraphemes, with an SGR reset appended before the marker when the prefix carries codes; the marker is charged against the budget and itself truncated when it alone meets/exceeds it; maxgraphemes 0 => empty string. Grapheme-count based (column-aware variant a recorded follow-on). Strict option handling (deliberately unlike VIEW's pinned silent tolerance). Ensemble export + PUNKARGS argdoc + doctools comment. Tests: new args/parsereport.test (13 - canonical attribution, entry parity, dict shape/row order/row policy, solo+multi xN multiplicity, per-type elision markers, dict-never-elided, width cascade, single-line-ization, alias bridging, bordered/tableobject renders, failure parity, bad calls, own-definition render); ansi/ansistring.test +2 TRUNCATE pins (budget/passthrough/errors; ANSI-reset + CJK + combining-cluster safety). Full punk/args subtree 331 passed / 3 pre-existing skips / 0 failed and punk/ansi subtree 73/73 - each on native tclsh90 (9.0.3) AND tclsh87; failure-side rendering unchanged per acceptance. Minted modules/punk/args-0.18.0.tm + ansi-0.2.0.tm via make.tcl modules; bootsupport/vfscommon promotion left to the next cycle - make.tcl keeps its interim one-line report (and its 4-copy 'no annotated success render yet' comment) until the promotion-gated follow-on lands. Goals: G-151 entry moved to GOALS-archive.md, detail file to goals/archive/ with verification evidence and 5 Follow-on lines (make.tcl interim-report retirement open; arg_error value-truncation via the same helpers open; storage-key rationalization => goal G-084; column-aware TRUNCATE open; word-oriented inverse view open). Activation-survey Related: lines recorded (G-166, G-084, G-167 back-pointer); reference sweep updated G-170 (sequencing lean honoured - its dry-run arm consumes this render), G-167 archive marker, G-084 back-pointer note. src/tests/modules AGENTS.md punk/args + punk/ansi bullets extended. goals_lint clean (83 active / 87 archived). Claude-Session: https://claude.ai/code/session_0156PuejSCGjgeGb7jiABrDU Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com	6 days ago
Julian Noble	7cdf5b2323	G-149 achieved: punk::args configurable multi-form synopsis hint labels (punk::args 0.17.0) The per-form hint labels rendered beside a multi-form definition's synopsis lines in the usage/arg_error table (hard-coded ' i -form N ...' previously) are now a template substituted per form: %formindex% is replaced with the form's 0-based ordinal, %formname% with its name, and an empty template suppresses the labels entirely (the cell keeps just the Synopsis: label, as single-form renders always have). Both acceptance arms landed. Definition side: new '@cmd -formhint <template>' key - rides the existing arbitrary-key cmd_info merge (no resolver change), round-trips through resolved_def, not display -deferred; documented in the define -help directive-options. Caller side: new -formhint option on arg_error (manual parser + PUNKARGS block) pulled into usage via its existing resolved_def opts pull; supplied-empty (suppress) is distinct from not-supplied (the option declares no -default, so an unsupplied usage call passes nothing through). Precedence: caller > definition > built-in default, whose template substitutes to the exact prior bytes. Motivation (G-143 origin): script-level (script) ids - make.tcl's - are unreachable from any repl, so the repl-oriented 'i' hint was not actionable there. Scope decisions pinned: single-form renders never carry hint labels; the -return string renderer has no hint column and is unchanged. Byte-identity for unconfigured definitions proven by pre/post capture diff of 'punk::args::usage ::punk::args::parse' (identical bytes, through the usage pass-through path). Tests: new formhint.test (9 tests - default labels, directive/caller/suppression matrix, parse -error path, single-form + string-renderer scope); full punk/args subtree 302/0-fail on BOTH tclsh90 9.0.3 and the punk86 kit (8.6); punk/ns subtree 115/115 (cmdhelp consumer). make.tcl help untouched until promotion (maketclhelp.test still pins the bootsupport hint). Goals: G-149 activated at user direction then flipped achieved 2026-08-05 + archived (index record newest-first, detail file to goals/archive with Progress evidence and 1 follow-on: make.tcl adoption after a bootsupport promotion => open). Activation-freshness survey recorded the G-167 relationship (same renderer surface - composition note both sides); reference sweep updated G-151/G-167 mentions; goals_lint clean, no orphaned xref pairs. punkshell 0.55.0 + CHANGELOG. Bootsupport/vfscommon snapshots unchanged until promotion + bake. Claude-Session: https://claude.ai/code/session_01QgaxV27VZkmEec7oNbEVFc Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com	7 days ago
Julian Noble	ac8e26ab20	G-167 drafted: punk::args version-delta availability - unavailable @forms for shape deltas, unavailable option names for flag deltas New proposed goal (user-approved wording, from the post-G-073 design discussion 2026-08-05): version/context deltas of a command's interface become declarable and honestly surfaced without delta computation, layered by delta kind. An @form may be declared unavailable - participating in candidacy/diagnosis, displayed annotated, tailored formunavailable rejection when only unavailable forms match, silent resolution to the available form when both match (the first sanctioned exception to G-041's no-silent-preference rule: documentation never competes with reality), -form selection displays but refuses parse. Option NAMES may be declared unavailable (the G-073 mirror at the option-name level) with pointed tailored rejection. The default render stays on available forms plus an AUTOMATED note enumerating unavailable shapes (name + authored note + navigation hint - no computed delta; user display decision relaxing the strict G-073 display-among-peers principle for shape deltas only, since named things keep per-name display via the option/choice layers). formstatus gains an additive 'available' field (G-152 contract) as the machine surface, and authoring guidance prescribes -choiceunavailable for subcommand-shaped deltas so the same concept never surfaces through two inconsistent paths. Detail file records the layered-model rationale, the silent-preference exception scope, the two-paths trap prescription, era authoring via shared -form tags (one form per version era - linear), engine seams, and the relations/overlap survey (G-073 foundation, G-166 sibling surface, G-152/G-041/G-074/G-150/G-149/G-044/G-055). Acceptance and the lsearch -stride adoption candidate are agent-derived for user review; status proposed. goals_lint clean (82 active / 85 archived). Claude-Session: https://claude.ai/code/session_01QgaxV27VZkmEec7oNbEVFc Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com	7 days ago

4 Commits (2dbf635b99a23f8fb151e06bdb68a471a1f781e6)