diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 6e133a24..7ae81fcf 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -46,7 +46,7 @@ app package from src/lib/ (app-punkshell, app-punkscript, app-repl, app-shellsp - **Package modes pick module provenance.** `internal` uses module snapshots baked into the kit at build time; `dev` loads build outputs from repo-root `modules/` and `lib/`; `src` loads the unbuilt working tree (`src/modules`, `src/lib`, `src/bootsupport`, `src/vendormodules`) with `package prefer latest` so magic-version dev modules (`999999.0a1.0`) beat stamped snapshots. `src` mode is the standard way to verify working-tree changes without a rebuild. Source: `bin/AGENTS.md` "Launch package modes". - **Static package capture (G-058, achieved).** Boot probe-loads the runtime's statically linked packages in a throwaway interp and records what each provides; every interp the shell fabricates (boot, codethread, shellthread workers) seeds `package ifneeded {load {} }` from that record, and `punk::packagepreference` resolves static-vs-bundled version-aware. Sources: `src/vfs/AGENTS.md`, `goals/archive/G-058-static-runtime-packages.md`. - **`script` subcommand (G-015, achieved).** The lean non-interactive path: default punk shell module/alias environment, no shellfilter stacks/transforms, honest exit codes, launch plumbing emits nothing on stdout/stderr (exec-style callers see only the script's own output). Supports `lib:` scriptlib resolution. App package: `src/lib/app-punkscript/`. -- **`tclsh` subcommand (G-118).** Plain-tclsh emulation with NO punk modules loaded: stock argument-form parity (`-encoding name file`; any other leading `-` argument means no script, everything stays in `::argv`; no `-e` one-liner - deliberate stock parity, see G-077 for the punk-level one-liner direction), `lib:` refused with a pointer at `script`, missing script file is a clean exit 1. On piperepl-patched runtimes (the punk family runtimes - `src/buildsuites/suite_tcl90/patches/`) the C-level machinery publishes `::tclsh` launch state (`istty`, `dorepl`, `evalinput`, `inputbuffer`, `reopened`) allowing piped input to hand over to a live console repl at eof; runtimes without the machinery evaluate piped stdin whole-buffer with honest exit codes and fail fast on console stdin. The subcommand-family contract (tclsh/script/shell/punk/shellspy) is documented as punk::args definitions in `src/modules/punk/args/moduledoc/punkexe-999999.0a1.0.tm` (ids `(script)::punkexe` + per-subcommand; view via `punk::args::usage`), consumable by the future launcher help wiring (G-032). Pipe-testable behaviour pinned by `src/tests/shell/testsuites/punkexe/tclshcmd.test`. +- **`tclsh` subcommand (G-118, achieved).** Plain-tclsh emulation with NO punk modules loaded: stock argument-form parity (`-encoding name file`; any other leading `-` argument means no script, everything stays in `::argv`; no `-e` one-liner - deliberate stock parity, see G-077 for the punk-level one-liner direction), `lib:` refused with a pointer at `script`, missing script file is a clean exit 1. On piperepl-patched runtimes (the punk family runtimes - `src/buildsuites/suite_tcl90/patches/`) the C-level machinery publishes `::tclsh` launch state (`istty`, `dorepl`, `evalinput`, `inputbuffer`, `reopened`) allowing piped input to hand over to a live console repl at eof; runtimes without the machinery evaluate piped stdin whole-buffer with honest exit codes and fail fast on console stdin. The subcommand-family contract (tclsh/script/shell/punk/shellspy) is documented as punk::args definitions in `src/modules/punk/args/moduledoc/punkexe-999999.0a1.0.tm` (ids `(script)::punkexe` + per-subcommand; view via `punk::args::usage`), consumable by the future launcher help wiring (G-032). Pipe-testable behaviour pinned by `src/tests/shell/testsuites/punkexe/tclshcmd.test`. - **`bin/` launch surface.** Built kits plus polyglot `.cmd` utilities (`punk-runtime`, `punk-getzig`, `punk-tclargs`, `dtplite`) generated from `src/scriptapps/` sources by the `punk::mix` scriptwrap machinery - outputs are never hand-edited. `bin/punk-runtime.cmd` fetches/lists/selects plain runtimes under `bin/runtime//` from the punkbin artifact server with sha1 verification. Source: `bin/AGENTS.md`. ## Interp and thread topology @@ -102,7 +102,7 @@ Mechanics here are documented as pointers only - detailed prose would be obsolet - Input mode and completion: G-013 (raw-mode default), G-044 (punk::args-driven completion). - Stored configuration and help: G-014 (punk::config toml), G-042 (subshell help topics), G-043 (subshell definition plugins). - Console err channel: G-011. -- Launch surface: G-023 (version-named binaries), G-033 (`proj:` package mode), G-077 (`-e` one-liners), G-089 (scriptlib in kits), G-112 (make.tcl subcommand rename), G-118 (tclsh subcommand review). +- Launch surface: G-023 (version-named binaries), G-033 (`proj:` package mode), G-077 (`-e` one-liners), G-089 (scriptlib in kits), G-112 (make.tcl subcommand rename). - 8.6 buildsuite family: G-099, G-100, G-101. ## Doc map - which lane holds what diff --git a/GOALS-archive.md b/GOALS-archive.md index cf38af4a..03e1d0bc 100644 --- a/GOALS-archive.md +++ b/GOALS-archive.md @@ -158,3 +158,7 @@ Acceptance: suite_tcl90 produces named artifacts for at least plain, punk, and o ### G-117 [achieved 2026-07-24] Self-describing family runtimes: embedded artifact record + metadata schema v1 → detail: goals/archive/G-117-self-describing-runtimes.md Scope: src/buildsuites/suite_tcl90/ (kit-family staging embeds the record; family_artifacts.tcl schema v1 fields + emission ordering; -Doriginurl/-Dpackager options); tools/family_check.tcl (embedded-record verification); src/scriptapps/bin/punk-runtime.* + bin/punk-runtime.cmd via rewrap ('info' action; schema-tolerant parsing); punkbin AGENTS.md (record relationship + schema/field documentation) Acceptance: kit-family embeds the record in all three members with the embed-then-hash ordering documented; family_check verifies the embedded record exists and matches probed facts; 'punk-runtime info' identifies fetched-with-sidecar and bare-renamed copies via a non-executing zip central-directory read (cooperative probe documented as fallback) and flags embedded-vs-sidecar disagreement; v1 fields documented in punkbin AGENTS.md; build_id identical embedded+sidecar; '#' field comments emitted; parsing tolerates unknown fields/absent schema (pre-v1 r1 keeps working); both payloads in parity with the roundtrip pin green; r2 re-emitted carrying the full v1 record (r1 immutable as published). + +### G-118 [achieved 2026-07-25] tclsh subcommand review: stock-parity gaps, piperepl residue, docs and console-path tests → detail: goals/archive/G-118-tclsh-subcommand-review.md +Scope: src/vfs/_config/punk_main.tcl (tclsh dispatch); src/vfs/_config/project_main.tcl (parity); src/buildsuites/suite_tcl90/patches/ (tclMain piperepl rev items); src/tests/shell/testsuites/punkexe/tclshcmd.test (coverage additions) +Acceptance: Every item in the "Issue list" section carries a recorded user decision (fix / document-as-intended / wontfix) and the decided fixes and documentation have landed; the tclsh subcommand's user-facing contract is documented in a durable doc location (not TEMP_REFERENCE); tclshcmd.test covers the decided pipe-testable behaviours; and the dorepl/console-reopen path either has a console-driven test or a recorded decision that G-106-style coverage is not required. diff --git a/GOALS.md b/GOALS.md index 5e7f5c2b..4e73344a 100644 --- a/GOALS.md +++ b/GOALS.md @@ -402,10 +402,6 @@ Detail: goals/G-115-declarative-vfs-composition.md Scope: src/buildsuites/suite_tcl90/ (build_tcltls module + crypto-backend build, sources.config + build.zig.zon source records, kit-family bi payload + metadata extension, test_gate record step); src/vfs kit payloads carrying vendored tcltls binaries (current-state reference + recorded disposition only - removal stays G-004-era work); punkbin (as eventual artifact destination via the G-067 library class); consumers punk::imap4 / punk::netbox (package require tls) as verification context Detail: goals/G-116-suite-built-tcltls.md -### G-118 [active] tclsh subcommand review: stock-parity gaps, piperepl residue, docs and console-path tests -Scope: src/vfs/_config/punk_main.tcl (tclsh dispatch); src/vfs/_config/project_main.tcl (parity); src/buildsuites/suite_tcl90/patches/ (tclMain piperepl rev items); src/tests/shell/testsuites/punkexe/tclshcmd.test (coverage additions) -Detail: goals/G-118-tclsh-subcommand-review.md - ### G-119 [proposed] punk-runtime active-vs-default freshness verdict (ahead/behind/current) Scope: src/scriptapps/bin/punk-runtime.ps1 + punk-runtime.bash (+ rewrapped bin/punk-runtime.cmd); bin/AGENTS.md (runtime-manager contract); src/tests/modules/punk/mix/testsuites/scriptwrap/ (roundtrip pin; behavioural fixture surface settled in the work) Detail: goals/G-119-runtime-active-freshness.md diff --git a/goals/G-031-componentized-kit-boot.md b/goals/G-031-componentized-kit-boot.md index 1a30b844..dc1f9b7f 100644 --- a/goals/G-031-componentized-kit-boot.md +++ b/goals/G-031-componentized-kit-boot.md @@ -84,9 +84,12 @@ permanently own - a thousand lines of boot code. boot-provided packagemode hint (for scriptlib resolution) is a boot-core interface this goal's registration model should carry - one boot "running state" surface, not per-feature side channels. -- G-118 relationship: its item-9 project_main.tcl parity duplication is - deliberately interim (recorded in G-118's decision line); this goal's boot - core is the consolidation path. +- G-118 relationship (achieved 2026-07-25 - see goals/archive/G-118-tclsh-subcommand-review.md): + its item-9 project_main.tcl parity duplication is deliberately interim + (recorded in G-118's decision line); this goal's boot core is the + consolidation path. The mirrored tclsh dispatch now lives byte-synced in + punk_main.tcl, project_main.tcl and both layout _config copies - the + duplication this goal retires. - The tomlish silent-exe incident (2026-07-07, tomlish 1.1.10 fix) is a reminder that launch-path contracts are easy to break invisibly - behaviour parity in the acceptance means exercising each dispatch case, not just diff --git a/goals/G-032-launcher-punkargs.md b/goals/G-032-launcher-punkargs.md index a379fe41..2f59efbe 100644 --- a/goals/G-032-launcher-punkargs.md +++ b/goals/G-032-launcher-punkargs.md @@ -62,12 +62,19 @@ in `-help` by registration alone. natural first parsed subcommand; exit-code semantics), G-025 (version-report subcommand born punk::args-defined), G-013 (the debugrepl activation review mentions proper-command conversions that would slot into the same pattern). -- G-118 item 10 relationship (recorded 2026-07-24 after overlap review): G-118 (active, - tclsh subcommand review) delivers its launch-subcommand-family documentation as - G-032-COMPATIBLE punk::args definitions (subcommand enumeration + contract prose as - definition help text) - the definitions become this goal's source material; the -help - rendering, subcommand option parsing, registration integration and degradation wiring - stay here. Also: G-118 item 4 shipped a file-exists pre-check in the tclsh subcommand - (clean not-found + exit 1) - precedent for this goal's open unknown-first-arg - reclassification rule (reclassify-only-when-file-exists candidate). +- G-118 item 10 relationship (recorded 2026-07-24 after overlap review; G-118 achieved + 2026-07-25 - see goals/archive/G-118-tclsh-subcommand-review.md): G-118 DELIVERED the + launch-subcommand-family documentation as G-032-COMPATIBLE punk::args definitions - + this goal's source material now exists in punk::args::moduledoc::punkexe + (src/modules/punk/args/moduledoc/punkexe-999999.0a1.0.tm): (script)::punkexe + top-level (subcommand enumeration with choicelabels, package-mode leader documented + in help text, default reclassification described) + per-subcommand + (script)::punkexe::tclsh (full contract, multi-form) and summary-level + script/shell/punk/shellspy. The -help rendering, subcommand option parsing, + registration integration and degradation wiring stay here - this goal wires the + dispatch to render/parse from those ids (punk::args 0.12.7+ resolves the + (script)::* id family through update_definitions/usage). Also: G-118 item 4 + shipped a file-exists pre-check in the tclsh subcommand (clean not-found + exit 1) + - precedent for this goal's open unknown-first-arg reclassification rule + (reclassify-only-when-file-exists candidate). - Archived-goal references in this file: G-015 achieved 2026-07-07 (goals/archive/G-015-script-subcommand-piped-stdin.md); G-030 achieved 2026-07-14 (goals/archive/G-030-maketcl-punkargs.md) - the make.tcl counterpart shipped: follow its shipped decisions (`-confirm 0|1` prompt policy, explicit `@form -synopsis`, track-parsing-degrade-rendering split, required-choice leaders for pointed choiceviolation errors). diff --git a/goals/G-077-punkexe-dash-e-oneliner.md b/goals/G-077-punkexe-dash-e-oneliner.md index c8ceaef0..07b6d2ae 100644 --- a/goals/G-077-punkexe-dash-e-oneliner.md +++ b/goals/G-077-punkexe-dash-e-oneliner.md @@ -22,9 +22,12 @@ scaffolding (argv0/argv setup, errorInfo-to-stderr, exit-code discipline). ## Notes -- G-118 relationship (recorded 2026-07-24 after overlap review; neither file - previously referenced the other): G-118 (active) settled the stock leading-dash - fallthrough this goal must not disturb - ` tclsh -e ...` deliberately - keeps stock's -e misparse (stock parity is the tclsh subcommand's contract, per - its cross-note); the one-liner instinct is served only at the top level and via - `script -e`. Its item-10 definitions (G-032-compatible) will state this boundary. +- G-118 relationship (recorded 2026-07-24 after overlap review; achieved + 2026-07-25 - see goals/archive/G-118-tclsh-subcommand-review.md): G-118 settled + the stock leading-dash fallthrough this goal must not disturb - ` tclsh + -e ...` deliberately keeps stock's -e misparse (stock parity is the tclsh + subcommand's contract); the one-liner instinct is served only at the top level + and via `script -e`. Its item-10 definitions state this boundary in the tclsh + @cmd help (punk::args::moduledoc::punkexe, id (script)::punkexe::tclsh) - when + this goal lands the top-level/`script` `-e` forms, update that boundary text to + point at the live forms. diff --git a/goals/G-120-scriptmode-std-channel-pin.md b/goals/G-120-scriptmode-std-channel-pin.md index 023bfa5f..05c05c9b 100644 --- a/goals/G-120-scriptmode-std-channel-pin.md +++ b/goals/G-120-scriptmode-std-channel-pin.md @@ -22,7 +22,8 @@ mechanism (G-101 Notes 2026-07-25) would otherwise use for in-place stdio repair Ruled out by the spike: command interception (::open/::chan origins are core), the repl interactive-EOF restart path (does not run in script mode), shellfilter stacks (app-punkscript contract has none), the piperepl tclMain patch (punk91's tclsfe -runtime is unpatched per G-118 Notes). +runtime is unpatched per G-118 Notes - achieved, see +goals/archive/G-118-tclsh-subcommand-review.md). ## Approach @@ -45,7 +46,8 @@ by absence: strip the suspected stage and re-run the recipe. ## Notes -- Related: G-118 (console-path machinery + piperepl residue territory; its Notes +- Related: G-118 (achieved 2026-07-25 - see goals/archive/G-118-tclsh-subcommand-review.md; + console-path machinery + piperepl residue territory; its Notes record punk91's runtime as unpatched, ruling out the patch as the holder); G-011 (stderr semantics - a recycled rebound stderr is a consumer of that goal's defined routing); G-090 (shellfilter/shellthread stack lifecycle audit - adjacent diff --git a/goals/G-118-tclsh-subcommand-review.md b/goals/archive/G-118-tclsh-subcommand-review.md similarity index 93% rename from goals/G-118-tclsh-subcommand-review.md rename to goals/archive/G-118-tclsh-subcommand-review.md index 2e195d11..d0ebba17 100644 --- a/goals/G-118-tclsh-subcommand-review.md +++ b/goals/archive/G-118-tclsh-subcommand-review.md @@ -1,6 +1,6 @@ # G-118 tclsh subcommand review -Status: active +Status: achieved 2026-07-25 Scope: src/vfs/_config/punk_main.tcl (tclsh dispatch); src/vfs/_config/project_main.tcl (parity); src/buildsuites/suite_tcl90/patches/ (tclMain piperepl rev items); src/tests/shell/testsuites/punkexe/tclshcmd.test (coverage additions) Goal: The 'tclsh' subcommand has a settled, documented contract - each remaining divergence from stock tclsh and from the sibling 'script' subcommand in the issue list below is either fixed or explicitly recorded as intended, the piperepl patch residue items have decisions (batched into at most one patch rev + suite rebuild), and the console-entry paths have a test-coverage decision. Acceptance: Every item in the "Issue list" section carries a recorded user decision (fix / document-as-intended / wontfix) and the decided fixes and documentation have landed; the tclsh subcommand's user-facing contract is documented in a durable doc location (not TEMP_REFERENCE); tclshcmd.test covers the decided pipe-testable behaviours; and the dorepl/console-reopen path either has a console-driven test or a recorded decision that G-106-style coverage is not required. @@ -83,3 +83,15 @@ All 11 items dispositioned by the user 2026-07-24 (activation session). Items 1 stands for non-gated tests (tclshcmd.test header + src/tests/shell/AGENTS.md updated; consoleinject.ps1 indexed in src/tests/AGENTS.md). - Remaining for acceptance: none - all 11 items dispositioned and landed/documented. +- 2026-07-25 ACHIEVED FLIP - acceptance verified in full: (1) every issue-list item + carries a recorded user decision (all 11 dispositioned 2026-07-24) with the decided + fixes landed (items 3/4/5/9 punkproject 0.20.0; items 1/7 patch rev in the G-117 + cycle r2 runtimes; leading-dash/-encoding/lib: pre-goal 0.19.0; item 10 docs + 0.20.1) and the document-as-intended items (2/6/8) recorded in the item-10 + definitions; (2) durable doc home = punk::args::moduledoc::punkexe (not + TEMP_REFERENCE), verified rendering from src, rebuilt kits and the repl code + interp; (3) tclshcmd.test covers the decided pipe-testable behaviours (19 piped + tests, 19/19 green vs punk902z + punk9_beta); (4) the dorepl/console-reopen path + HAS a console-driven test (item 11, punkconsole-gated, 21/21 with the gate on). + Kits/runtimes verified against: punk902z (dispatch), punk9_beta r2 (machinery + + console reopen), punk91 (src-mode doc rendering). No remaining manual items.