From c44c873d87b40c0713a1d6881bbd429d5f8b0c8e Mon Sep 17 00:00:00 2001 From: Julian Noble Date: Tue, 7 Jul 2026 13:56:51 +1000 Subject: [PATCH] add goal G-030: make.tcl dogfoods punk::args; record session observations G-030 (proposed): make.tcl - the first surface a developer sees - parses subcommands/options via punk::args and showcases the tabled usage for help and argument errors; every interactive y/n prompt gains a declared flag equivalent (interactive stdin prompts as today; flag proceeds; non-interactive stdin without the flag fails fast with usage instead of hanging or half-aborting) so agents drive make.tcl with arguments rather than piped y/n; punk::args joins the bootstrap-tracked staleness set. Degradation is a hard requirement: boot stays self-contained and the repair commands (check/bootsupport/modules) keep working with plain fallback help when the bootsupport punk::args or the ANSI rendering stack is stale/unavailable - this week''s stale-fileutil and stale-textblock incidents are the cautionary tales. G-015 detail: recorded the runx -tcl result-shape observation (dict keyed {result stdout stderr}, no exitcode key unlike exec mode). G-020 detail: stamped the 2026-07-07 decision - acceptance gates on a full testable Windows system without requiring other platforms first. Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com --- GOALS.md | 6 ++ goals/G-015-script-subcommand-piped-stdin.md | 5 ++ goals/G-020-screencap-input-module.md | 8 ++- goals/G-030-maketcl-punkargs.md | 75 ++++++++++++++++++++ 4 files changed, 91 insertions(+), 3 deletions(-) create mode 100644 goals/G-030-maketcl-punkargs.md diff --git a/GOALS.md b/GOALS.md index b62a61db..a836d9b0 100644 --- a/GOALS.md +++ b/GOALS.md @@ -222,3 +222,9 @@ Scope: src/make.tcl (test-module packaging step), src/tests/ (source of truth), Detail: goals/G-029-testmodules-from-srctests.md Goal: src/tests is the single source of truth for module test suites - a punkcheck-tracked make.tcl step generates the packaged test:: #modpod modules from src/tests/modules//testsuites content, ending hand-maintenance of parallel copies under src/modules/test/; the packaged form is a distributable in its own right - a user who downloads a built module can optionally download the matching test:: and verify the module's behaviour on their own system (package require + RUN, or an executable's -app test) with no source tree or test harness required. Acceptance: a make.tcl step generates a test:: #modpod under src/modules/test/ from the corresponding src/tests testsuites (punkcheck-tracked, skipped when sources unchanged); the generated package works through the packaged path - loadable via package require test:: and runnable via its SUITE/RUN interface (e.g a built executable's -app test) - reporting the same test names and pass counts as running the same suites directly via src/tests/runtests.tcl; the consumer scenario is proven standalone: the generated package (plus the module under test and their dependencies) runs in an environment without the project source tree present; suite data files (e.g roundtrip toml files with deliberate crlf/mixed line endings) survive packaging byte-for-byte; documentation states src/tests is the source of truth and the generated modpods are build artifacts not to be hand-edited; proven end-to-end for at least one real module (tomlish, whose src/tests port and still-live modpod created the dual-copy situation, is the natural first). + +### G-030 [proposed] make.tcl dogfoods punk::args: tabled usage, declared subcommands, prompt-free flags +Scope: src/make.tcl (dispatch, help, prompts), src/bootsupport/AGENTS.md + src/modules/AGENTS.md (bootstrap-tracked staleness contract), src/modules/punk/args-999999.0a1.0.tm (only as consumed) +Detail: goals/G-030-maketcl-punkargs.md +Goal: make.tcl - the first surface a developer sees - parses its subcommands and options via punk::args and showcases the tabled usage output for help and argument errors, every interactive y/n prompt gains a declared flag equivalent so agents can drive make.tcl with arguments instead of piped input, punk::args joins the bootstrap-tracked staleness set, and the boot phase plus the environment-repair commands keep working with degraded plain help when the bootsupport punk::args (or the table-rendering stack) is stale or unavailable. +Acceptance: `tclsh src/make.tcl` and `-help` render punk::args tabled usage listing every subcommand with a summary, and `make.tcl help ` (or ` -help`) shows that subcommand's definition; invalid arguments produce a punk::args usage error rather than ad-hoc messages; every y/n prompt has a documented flag equivalent (proven at least for vfscommonupdate and the project-build confirmations: a run with the flag completes non-interactively with stdin closed) and a non-interactive stdin without the flag fails fast with usage rather than hanging or half-aborting; punk::args is added to the bootstrap-tracked buildversion set with the doc contract updated (src/bootsupport/AGENTS.md, src/modules/AGENTS.md); with bootsupport punk::args unavailable or unloadable, make.tcl still boots and `check`, `bootsupport` and `modules` remain usable with plain-text fallback help (the guarded-require degrade rule); layout make.tcl copies follow via the established sync/G-027 channels (noted, not hand-synced). diff --git a/goals/G-015-script-subcommand-piped-stdin.md b/goals/G-015-script-subcommand-piped-stdin.md index 162ab9e6..24629bb5 100644 --- a/goals/G-015-script-subcommand-piped-stdin.md +++ b/goals/G-015-script-subcommand-piped-stdin.md @@ -78,6 +78,11 @@ punk_main.tcl's `punk` subcommand case). ## Notes +- Result-shape observation (2026-07-07): `shellrun::runx -tcl` returns a dict + keyed {result stdout stderr} with NO exitcode key, unlike the exec-mode + result (exitinfo with exitcode) - callers doing `dict get $result exitcode` + error. Possibly by design for in-process eval, but the script-path work here + should document (or normalise) the result shapes agents will consume. - The eof policy machinery (PUNK_PIPE_EOF exit/interactive/heuristic) in app-punkshell (~punkshell.tcl 466-507) stays as-is for the `shell` subcommand; this goal does not change interactive-shell behaviour. diff --git a/goals/G-020-screencap-input-module.md b/goals/G-020-screencap-input-module.md index a0c728d0..bb09293c 100644 --- a/goals/G-020-screencap-input-module.md +++ b/goals/G-020-screencap-input-module.md @@ -55,9 +55,11 @@ the module is a separate development, not a refactor of it. Per-platform backend selection with capability introspection - callers ask what is supported rather than probing by failure. Echoes the G-001 pluggable pattern. -- Windows backend first and complete (acceptance gates on it). X11 and macOS - backends are in-scope follow-ons behind the same contract; their absence on a - platform must produce a clean capability-based refusal. +- Windows backend first and complete (acceptance gates on it - confirmed + 2026-07-07: a full testable system on Windows must be reachable without + first implementing the other platforms). X11 and macOS backends are + in-scope follow-ons behind the same contract; their absence on a platform + must produce a clean capability-based refusal. - Output normalization: capture lands in a Tk photo; PNG via Tk's core photo support (Img optional for other formats). File save and in-memory (base64) both supported - the G-021 consumer needs both. diff --git a/goals/G-030-maketcl-punkargs.md b/goals/G-030-maketcl-punkargs.md new file mode 100644 index 00000000..ea719ffb --- /dev/null +++ b/goals/G-030-maketcl-punkargs.md @@ -0,0 +1,75 @@ +# G-030 make.tcl dogfoods punk::args: tabled usage, declared subcommands, prompt-free flags + +Status: proposed +Scope: src/make.tcl (dispatch, help, prompts), src/bootsupport/AGENTS.md + src/modules/AGENTS.md (bootstrap-tracked staleness contract), src/modules/punk/args-999999.0a1.0.tm (only as consumed) +Acceptance: as in root GOALS.md index (canonical). + +## Context + +make.tcl is the first surface a developer meets in a punkshell-derived project, +but its command handling predates the ecosystem's own tooling: a hand-built +help text, a bare `known_commands` list, ad-hoc argument handling per +subcommand, and interactive y/n prompts (`vfscommonupdate`'s REPLACE +confirmation, the project-build confirmations, bootsupport staleness prompts). +Eating our own dogfood - punk::args definitions per subcommand with the tabled +usage rendering - both showcases the ecosystem where it is most visible and +makes the parsing declarative. + +The prompts are the practical payoff: agent-driven builds currently pipe `y` +into stdin (fragile, undiscoverable - observed 2026-07-07 while rebuilding +tomlish.exe). With punk::args parsing, prompt-free operation is just another +declared option per subcommand, and non-interactive stdin without the flag can +fail fast with usage instead of hanging on a read or half-aborting. + +Precedents already in-tree: src/tests/runtests.tcl parses via punk::args +((script)::runtests definition), and the tomlish cmdline app presents tabled +usage as its first surface. + +## Approach + +- One PUNKARGS definition per subcommand (@cmd -summary/-help + opts), plus a + top-level definition enumerating subcommands - replacing punkboot_gethelp + and the hand-maintained help strings. `make.tcl`, `make.tcl -help`, and + per-subcommand help all render through punk::args::usage. +- Prompt policy: interactive stdin -> prompt as today (default); flag supplied + (e.g. -confirm 0 / -y, naming decision recorded here) -> proceed without + prompting; non-interactive stdin without the flag -> usage error, fast. + The bootsupport staleness prompt keeps its abort/prompt/proceed + classification but gains the same flag route. +- **Degradation is a hard requirement** (the 2026-07-06/07 incidents are the + cautionary tale: a stale bundled fileutil disabled the very make.tcl step + needed to fix it). The boot phase stays self-contained; punk::args is + guarded-lazily required post-boot (the punkboot::utils pattern documented in + src/bootsupport/AGENTS.md); when unavailable, dispatch and the repair + commands (check, bootsupport, modules) keep working with plain-text fallback + help. Note the tabled rendering also pulls punk::ansi/textblock/punk::char - + exactly the modules whose same-version staleness broke shellfilter this week + - so rendering must degrade independently of parsing (punk::args plain + output when the ANSI stack is unhealthy). +- Staleness tracking: punk::args joins the bootstrap-tracked buildversion set + (currently punkcheck, punk::repo, punk::mix, punk::tdl) with the same + bump-at-least-minor-on-call-site-API-change discipline; whether the + rendering stack is also tracked or left to degrade is an implementation + decision to record here (initial lean: track punk::args only - it is the + parsing contract; rendering degrades). +- Layout copies of make.tcl follow through the existing punkcheck-tracked + sync (custom/_project) and the G-012/G-027 channels for the rest - noted in + completion reports, never hand-synced. + +## Alternatives considered + +- Ad-hoc -y flags bolted onto the current hand parsing - rejected: solves the + agent problem but leaves the first-surface help un-showcased and the parsing + divergent from the ecosystem's own conventions. +- Requiring punk::args at boot (no fallback) - rejected: make.tcl must be able + to repair the very bootsupport snapshot it loads punk::args from. + +## Notes + +- Related: G-015 (agents driving punk tooling non-interactively), G-024 + (mapvfs toml errors deserve the same declared-argument quality), G-025 (the + version-report subcommand should be born punk::args-defined), G-027 (pull + updates deliver the improved make.tcl to derived projects). +- Observation parked here from the same session: runtests/make.tcl-adjacent + tooling that returns result dicts should document their key shape (see the + runx -tcl exitcode note in G-015's detail).