From 3a32b4037f260f8aa3a4fdbf97a3cb5517a5739c Mon Sep 17 00:00:00 2001 From: Julian Noble Date: Mon, 6 Jul 2026 13:18:53 +1000 Subject: [PATCH] G-014: require tomlish module for toml parsing, punk::args docs precondition Scope gains the vendored tomlish module (canonical source in the external tomlish project space). Goal line rules out ad-hoc toml parsing; acceptance now requires the tomlish API procs punk::config consumes to carry punk::args (PUNKARGS) documentation, added upstream and re-vendored before punk::config implementation proceeds. Detail file records the 1.1.8 coverage gap: argdocs exist only on the cmdline app layer, not the library API (from_toml, to_dict, from_dict, update_tomlish_from_dict). Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com --- GOALS.md | 6 +++--- goals/G-014-punk-config-toml.md | 19 ++++++++++++++++++- 2 files changed, 21 insertions(+), 4 deletions(-) diff --git a/GOALS.md b/GOALS.md index 71b8eee7..a9ae9ea1 100644 --- a/GOALS.md +++ b/GOALS.md @@ -129,7 +129,7 @@ Goal: a repl launched without explicit mode configuration starts in raw input mo Acceptance: a default launch lands in raw mode with line mode still selectable; with debug toggles at their defaults (off unless stored configuration via ::punk::config says otherwise - see G-014), typing/editing/submitting a command emits no cursor-positioned debug output; the per-keystroke add_chunk frame and the right-hand live editbuf view are gated separately, each toggleable from within a running repl; arrow-key history navigation and left/right cursor movement work in raw mode (current stubs replaced); the marked-line debugrepl output form is retained and works on terminals without cursor addressing (e.g. vt52); the debugrepl first-word activation mechanism is reviewed and the keep/replace outcome (e.g. a proper Tcl command that interp hide can restrict in subshells) is recorded in the detail file; on tcl 8.6 a background-initiated terminal query at an idle raw-mode prompt succeeds (the residue scenario fail-fast-guarded in punk::console 0.7.1). ### G-014 [proposed] ::punk::config stored configuration: toml files with named-subshell scoping -Scope: src/modules/punk/config-0.1.tm, src/modules/punk/repl-999999.0a1.0.tm, src/modules/punk/repl/codethread-999999.0a1.0.tm +Scope: src/modules/punk/config-0.1.tm, src/modules/punk/repl-999999.0a1.0.tm, src/modules/punk/repl/codethread-999999.0a1.0.tm, src/vendormodules/tomlish-*.tm (vendored; canonical source in the external tomlish project space) Detail: goals/G-014-punk-config-toml.md -Goal: ::punk::config loads stored configuration from toml files in the XDG-located config dir and consumers resolve settings with per-named-subshell overrides, so features like the G-013 debug-view startup defaults read declared user configuration instead of hardcoded fallbacks. -Acceptance: a setting declared in a toml file under the XDG-located config dir is visible through the punk::config API at repl startup, and with no config files present built-in defaults apply with no errors beyond the existing missing-dir notice; a named subshell resolves its own overriding value for a key also defined at the parent/default scope, and a subshell with no override inherits the outer value (proven with at least one real key); at least one shipped feature (the G-013 editbuf-view startup default is the natural first) reads its default through this path rather than a hardcoded value. +Goal: ::punk::config loads stored configuration from toml files in the XDG-located config dir - parsed via the vendored tomlish module, never an ad-hoc parser - and consumers resolve settings with per-named-subshell overrides, so features like the G-013 debug-view startup defaults read declared user configuration instead of hardcoded fallbacks. +Acceptance: a setting declared in a toml file under the XDG-located config dir is visible through the punk::config API at repl startup, and with no config files present built-in defaults apply with no errors beyond the existing missing-dir notice; a named subshell resolves its own overriding value for a key also defined at the parent/default scope, and a subshell with no override inherits the outer value (proven with at least one real key); at least one shipped feature (the G-013 editbuf-view startup default is the natural first) reads its default through this path rather than a hardcoded value; all toml reading/writing in punk::config goes through the tomlish module, and the tomlish API procs punk::config consumes carry punk::args (PUNKARGS) documentation - added upstream in the tomlish project and re-vendored here before punk::config implementation proceeds. diff --git a/goals/G-014-punk-config-toml.md b/goals/G-014-punk-config-toml.md index 08597b49..08328956 100644 --- a/goals/G-014-punk-config-toml.md +++ b/goals/G-014-punk-config-toml.md @@ -1,7 +1,7 @@ # G-014 ::punk::config stored configuration: toml files with named-subshell scoping Status: proposed -Scope: src/modules/punk/config-0.1.tm, src/modules/punk/repl-999999.0a1.0.tm, src/modules/punk/repl/codethread-999999.0a1.0.tm +Scope: src/modules/punk/config-0.1.tm, src/modules/punk/repl-999999.0a1.0.tm, src/modules/punk/repl/codethread-999999.0a1.0.tm, src/vendormodules/tomlish-*.tm (vendored; canonical source in the external tomlish project space) Acceptance: as in root GOALS.md index (canonical). ## Context @@ -21,8 +21,25 @@ should be able to carry its own defaults (a subshell dedicated to developing per-keystroke features might default the editbuf view on, while the top-level shell keeps it off). +## Precondition: tomlish punk::args documentation + +All toml parsing/serialisation goes through the tomlish module - no ad-hoc toml +parsing in punk::config. tomlish is vendored (src/vendormodules/tomlish-1.1.8.tm +at time of writing, with a bootsupport copy) but its canonical source lives in a +separate project space under our control: documentation work happens upstream +there and lands here by re-vendoring, not by editing the vendored copies. + +As of 1.1.8, punk::args coverage exists only on the cmdline app layer +(tomlish::app::decode_to_typedjson, tomlish::app::encode_from_typedjson, +tomlish::app::test, and the tomlish::cmdline definition). The library API procs +punk::config would consume (e.g. tomlish::from_toml, tomlish::to_dict, +tomlish::from_dict, tomlish::update_tomlish_from_dict) have no PUNKARGS argdoc +blocks. Those procs must gain punk::args documentation upstream and the updated +tomlish be re-vendored before punk::config implementation proceeds. + ## Approach +- All toml reading/writing via the tomlish module (see precondition above). - toml files under the punk::config::dir location, organised by configset. - Resolution order: named-subshell override -> parent/default scope -> built-in default. Absence of any config files must be a fully silent, working state