diff --git a/GOALS.md b/GOALS.md index aa45803d..acb98215 100644 --- a/GOALS.md +++ b/GOALS.md @@ -180,3 +180,21 @@ Scope: src/modules/punk/mix/commandset/repo-999999.0a1.0.tm, src/modules/punk/re Detail: goals/G-022-fossil-rename-punkshell.md Goal: the `dev repo` commandset can move and rename fossil repositories non-interactively and safely - all checkouts repointed, no phantom central config-db entries, no dangling old repo db, fossil project-name renamable with project-code unchanged - and this project's fossil repo (currently project-name 'shellspy') is renamed to 'punkshell' through that mechanism via a G-015 piped script call, not by hand. Acceptance: the commandset provides a flag-driven (no stdin prompts) move/rename operation which on a scratch repo with an open checkout: repoints every registered checkout, leaves the central config-db listing only the new path, removes or archives the old repo db file (per option), clears stale ckout: back-references, and applies a requested project-name change while preserving project-code; the GAP characterization tests in src/tests/modules/punk/mix/testsuites/repo/fossilmove.test are updated to assert the clean behaviour and pass; after G-015 is achieved, this repo's fossil db (shellspy.fossil / project-name shellspy) is renamed to punkshell via the new operation invoked through a piped `script` call, with `fossil info` in this checkout showing the new repository path and project-name and `fossil all ls` free of the old path. + +### G-023 [proposed] Version-named punk binaries per Tcl generation (versioned / dev / release-gated plain names) +Scope: src/make.tcl, src/runtime/ (mapping config - see G-024), bin/ (build outputs) +Detail: goals/G-023-version-named-binaries.md +Goal: project builds produce version-named punk executables for tcl 8.6 and tcl 9 as the project version advances - punk8---.exe / punk9---.exe per version, punk8-dev.exe / punk9-dev.exe tracking the latest build, and plain punk8.exe / punk9.exe created initially then replaced only when an actual release is tagged - tolerating the disk growth for now. +Acceptance: a project build at the current punkproject.toml version produces punk8---

.exe and punk9---

.exe (names derived from the version, not hand-maintained) plus punk8-dev.exe / punk9-dev.exe updated to that same build; rebuilding at an unchanged version refreshes that version's binaries and -dev without touching other versions' outputs; plain punk8.exe / punk9.exe exist and are replaced only by an explicit release step - a normal build never overwrites them; the scheme is declared succinctly via the G-024 toml mapping (no per-version config edits); archival/deletion of accumulated versioned binaries is out of scope with the trigger question recorded in the detail file. + +### G-024 [proposed] mapvfs.config converted to toml (tomlish-parsed) with succinct scheme declarations +Scope: src/runtime/mapvfs.config (replaced/deprecated), src/make.tcl (parsing), src/bootsupport/modules/tomlish-*.tm (parser dependency) +Detail: goals/G-024-mapvfs-toml.md +Goal: the runtime-to-vfs-to-executable build mapping moves from the custom line format of src/runtime/mapvfs.config to a toml file parsed with the tomlish package - still supporting explicit per-executable mappings (runtime, vfs folder, output name, kit type) while also expressing generative schemes like the G-023 versioned naming in a single succinct declaration. +Acceptance: a mapvfs toml file parsed via tomlish (no ad-hoc toml parsing) drives the build: every mapping currently active in mapvfs.config is expressible and at least one existing target builds identically from the toml; the G-023 versioned/dev/release-gated output scheme is declared in one entry that expands to its outputs without enumerating versions; malformed or unresolvable entries fail the build with a clear message naming the entry; the legacy .config format is either fully migrated (old parser removed) or explicitly deprecated with documented precedence between the two files. + +### G-025 [proposed] Punk executables self-report project version and build provenance +Scope: src/vfs/_config/punk_main.tcl (subcommand dispatch), src/make.tcl (stamping build info into the vfs), src/vfs/ (stamp payload location), src/modules/punk/ (in-shell command - the single implementation) +Detail: goals/G-025-exe-selfreport.md +Goal: a punk executable reports its identity from embedded data rather than its filename - a documented subcommand prints the punkproject.toml project version it was built from plus the input runtime binary name and vfs folder name used to assemble it - with the same-named command available in the punk module so scripts running in any punk shell (including tclsh-hosted ones like `tclsh src/make.tcl shell`) get the same report in-process without exec, stamp fields reported as absent rather than fabricated when there is no stamp. +Acceptance: the build stamps project version, runtime binary name, and vfs folder name into the kit; the built executable invoked with the version-report subcommand prints those fields machine-parseably on stdout and exits 0 with no other output (G-015-compatible; no repl fallthrough); a same-named command in the punk module returns the same fields in-process (subcommand implemented as a wrapper over it - one implementation) and works from the code interp; the report distinguishes stamped provenance from live facts: a stamped kit reports its stamp, a `src`-mode or source-tree session additionally reports the live punkproject.toml version as a distinct field when it differs, and unstamped contexts (`tclsh src/make.tcl shell`, plain tclsh with punk modules) report stamp fields explicitly absent with live runtime facts (actual `info nameofexecutable`) still provided; the report is correct when the executable file has been renamed or copied; executables built before stamping existed fail gracefully with a clear message rather than fabricating values. diff --git a/goals/G-023-version-named-binaries.md b/goals/G-023-version-named-binaries.md new file mode 100644 index 00000000..56f54e59 --- /dev/null +++ b/goals/G-023-version-named-binaries.md @@ -0,0 +1,67 @@ +# G-023 Version-named punk binaries per Tcl generation (versioned / dev / release-gated plain names) + +Status: proposed +Scope: src/make.tcl, src/runtime/ (mapping config - see G-024), bin/ (build outputs) +Acceptance: as in root GOALS.md index (canonical). + +## Context + +The project version is now tracked and change-driven-bumped in punkproject.toml +(root AGENTS.md "Project Versioning"), so builds can be named after it. Today's +build outputs are fixed names declared line-by-line in src/runtime/mapvfs.config +(punksys, punk902z, ...) that encode the runtime generation informally and say +nothing about the project version they contain - which build a given exe +represents is unknowable without launching it (G-025 addresses the launching +side; this goal addresses the naming side). + +Naming scheme: + +- `punk8---.exe` / `punk9---.exe` - + produced as the version advances; a rebuild at an unchanged version refreshes + that version's binaries in place. +- `punk8-dev.exe` / `punk9-dev.exe` - always the latest build, refreshed every + build. +- `punk8.exe` / `punk9.exe` - created initially, then replaced only by an + explicit release step when an actual release is tagged. A normal build never + touches them. + +The `8`/`9` generation split matches the existing dual-generation verification +practice (bin/AGENTS.md: a Tcl 8.6 punk shell and a current Tcl 9 punk shell). + +## Approach + +- Names derive from punkproject.toml at build time - no hand-maintained + per-version config entries. The scheme is declared once, succinctly, in the + G-024 toml mapping; the expansion to concrete output names happens in + make.tcl. +- The release step that updates the plain punk8.exe/punk9.exe names should be + an explicit make.tcl action tied to release tagging, not a side effect of a + normal build. Its precise trigger (fossil/git tag presence, or a manual + subcommand) is an implementation decision to record here. +- Existing specifically-named outputs (punksys, punk902z, ...) keep working via + their explicit mappings (G-024 preserves them); the versioned scheme is + additive. + +## Space and archival + +These binaries are large. Accumulating one pair per project version is +accepted for now. Out of scope but recorded for later: a trigger mechanism for +archival/deletion (e.g. keep-latest-N per generation, prune non-release +versions older than a threshold, or move to an artifact store per G-006's +binary-artifacts repository). Revisit when the accumulation actually bites. + +## Alternatives considered + +- Encoding the version only inside the kit (G-025) and keeping fixed exe names + - rejected as insufficient alone: side-by-side versioned binaries are the + point (running/comparing multiple versions without rebuilds). +- Symlinks/hardlinks for -dev and plain names instead of copies - deferred to + implementation: Windows link semantics for running executables are fiddly; + copies are acceptable at current sizes. + +## Notes + +- Related: G-024 (scheme declared in toml mapping), G-025 (exe self-reports its + version/provenance - the complement of name-encoded versioning once files + are renamed/copied), G-006 (future artifact-store home for archived + versions), G-018/G-019 (other points on the executable-flavour spectrum). diff --git a/goals/G-024-mapvfs-toml.md b/goals/G-024-mapvfs-toml.md new file mode 100644 index 00000000..f5d74a7d --- /dev/null +++ b/goals/G-024-mapvfs-toml.md @@ -0,0 +1,65 @@ +# G-024 mapvfs.config converted to toml (tomlish-parsed) with succinct scheme declarations + +Status: proposed +Scope: src/runtime/mapvfs.config (replaced/deprecated), src/make.tcl (parsing), src/bootsupport/modules/tomlish-*.tm (parser dependency) +Acceptance: as in root GOALS.md index (canonical). + +## Context + +src/runtime/mapvfs.config maps runtime binaries and .vfs folders to named +executables in a custom line format: one line per runtime, being the runtime +filename followed by kit-configuration lists of 1-3 elements +({vfsfolder ?outputname? ?kittype?}, kittype in kit|zip|zipcat, `-` as runtime +for runtime-less .kit builds, no-entry runtimes matching same-named .vfs +folders implicitly). make.tcl parses it inline (~2795-2845). The format works +but is idiosyncratic (comment/blank handling, positional defaults), is parsed +ad hoc, and has no way to express a *scheme* - every output is one literal +mapping, which conflicts with G-023 where output names derive from the project +version at build time. + +tomlish is the project's toml parser (vendored at src/vendormodules and +src/bootsupport/modules - the bootsupport copy matters since make.tcl is build +tooling), so the replacement format is toml parsed via tomlish, consistent +with the G-014 direction of toml + tomlish for declared configuration. + +## Approach + +- A mapvfs toml file in src/runtime/ carrying two kinds of declarations: + - **Explicit mappings** - the current capability, one entry per output: + runtime, vfs folder, output name (defaulting from the vfs name), kit type. + Everything active in mapvfs.config today must be expressible. + - **Scheme declarations** - generative entries expanded by make.tcl, first + consumer being the G-023 versioned scheme: one entry per Tcl generation + declaring runtime + vfs + scheme=versioned (or similar) that expands to + punkN---

.exe, punkN-dev.exe and the release-gated punkN.exe + without enumerating versions. +- Validation with entry-level error reporting: a malformed or unresolvable + entry (missing runtime file, missing vfs folder, unknown kit type/scheme) + fails the build naming the offending entry - matching the current warnings + but structured. +- Legacy handling is a decision to record here: either full migration (convert + the file, delete the old parser) or a deprecation window (toml wins when + present, .config honoured with a deprecation warning). Full migration is + preferred - the file is small and repo-internal - unless project_layouts + templates complicate it (layout copies of make.tcl/mapvfs.config sync via + G-012 territory; note in completion report, do not hand-sync layouts). + +## Alternatives considered + +- Keeping the custom line format and extending it with scheme syntax - + rejected: doubles down on an ad-hoc parser exactly where the project is + standardising on toml + tomlish. +- Tcl-script config (source-able dict) - rejected for the same reason as in + G-014: toml is the declared configuration format, editable without Tcl + knowledge. + +## Notes + +- The commented-out historical entries in mapvfs.config (broken-runtime notes, + test cases) are documentation of past pitfalls - carry the useful ones into + toml comments or this file rather than losing them. +- Related: G-023 (first scheme consumer), G-014 (toml+tomlish direction and + the tomlish punk::args-documentation precondition - that precondition gates + punk::config consumption; build-tooling use here can proceed with tomlish + as-is), G-012 (layout template refresh, if layout copies of runtime config + are affected). diff --git a/goals/G-025-exe-selfreport.md b/goals/G-025-exe-selfreport.md new file mode 100644 index 00000000..51e35426 --- /dev/null +++ b/goals/G-025-exe-selfreport.md @@ -0,0 +1,82 @@ +# G-025 Punk executables self-report project version and build provenance + +Status: proposed +Scope: src/vfs/_config/punk_main.tcl (subcommand dispatch), src/make.tcl (stamping build info into the vfs), src/vfs/ (stamp payload location), src/modules/punk/ (in-shell command - the single implementation) +Acceptance: as in root GOALS.md index (canonical). + +## Context + +With G-023 producing version-named binaries, an executable's name encodes its +version - but names are mutable (copies, renames, the -dev and release-gated +plain names) and say nothing about the runtime binary or vfs folder the build +consumed. The executable should answer for itself from embedded data: a +version-report subcommand at the launch layer, and the same-named command in +the punk module for scripts already running inside a punk shell. + +The in-shell command is not merely an optimization over exec'ing out. In a +tclsh-hosted punk shell (`tclsh src/make.tcl shell` loads punk::repl directly +into the host tclsh - make.tcl ~1913) there is no punk executable to exec: +`info nameofexecutable` is the external tclsh, and invoking it with the +subcommand would be meaningless. The in-process command is the only correct +path there - hence the module command is the single implementation and the +exe subcommand is a thin dispatch wrapper over it (which is also what +guarantees the two surfaces report identically). + +## Report semantics: three distinct notions + +Only in a plainly-launched stamped kit do these coincide; the report must keep +them distinct and never fabricate: + +1. **Build stamp** - project version, runtime binary name, vfs folder name, + fixed at kit assembly by make.tcl. Absent in unstamped contexts. +2. **Live runtime facts** - actual `info nameofexecutable`, patchlevel. + Always available. +3. **Source-tree project version** - punkproject.toml, available when running + from a source tree regardless of stamping. + +Edge cases driving the acceptance clauses: + +- `tclsh src/make.tcl shell`: no stamp. Stamp fields reported explicitly + absent; live facts show the real host tclsh; the source-tree version may be + reported but flagged as live-from-punkproject.toml, not as a stamp. +- Kit launched in `src` mode (`punk902z src`): a stamp exists, but the running + code is working-tree dev modules whose punkproject.toml may be ahead of the + stamped version. Reporting only the stamp misstates what is running; only + the live version misstates provenance - report both, distinctly labelled, + when they differ. +- Plain tclsh with installed punk modules and no source tree: no stamp, no + punkproject.toml - live facts only. +- Renamed/copied executables: the report comes from the stamp, so it stays + correct whatever the file is called. +- Pre-stamping kits: the subcommand/command fails gracefully with a clear + message. + +## Approach notes + +- The command must work from the code interp (where scripts run), not just the + repl thread - trivial for static stamp data, but stated so the G-007 + location-transparency expectation is met. +- The subcommand output must be machine-parseable, exit 0, and emit nothing + else on stdout/stderr - usable through G-015 piped calls and by exec-style + callers. +- Naming (e.g. `buildinfo`) is an implementation decision: the in-shell + command name must match the subcommand name and not collide with existing + repl commands. +- Stamp location within the vfs payload is an implementation decision to + record here (candidates: a dedicated stamp file under the vfs _config, or + fields merged into an existing boot config file). + +## Alternatives considered + +- In-shell command exec'ing its own executable with the subcommand - rejected: + wrong in tclsh-hosted shells (no punk executable to call), needless process + spawn elsewhere, and two code paths that can drift. +- Reporting only the stamped version and ignoring live/source-tree context - + rejected: actively misleading in `src`-mode sessions, which are the primary + working-tree verification workflow (bin/AGENTS.md). + +## Notes + +- Related: G-023 (version-named binaries this complements), G-024 (build + mapping that will drive stamping inputs), G-015 (piped invocation of the + subcommand), G-014 (punkproject.toml reading may share tomlish plumbing).