4.6 KiB
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, src/vendormodules/tomlish-*.tm (vendored; canonical source in the external tomlish project space) 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.
Context
punk::config 0.1 already establishes the config-dir convention (XDG_CONFIG_HOME preferred, ~/.config/punk/shell fallback - see punk::config::dir) and declares toml as the config file format, with a configset/config.toml startup-file notion sketched but not implemented. Runtime configuration today is a mix of env-var derived values and hardcoded defaults; there is no path for a user to declare a setting in a file and have a feature pick it up, and no way to configure named subshells independently.
The immediate consumer motivating completion is G-013: the raw-mode debug-view toggles (notably the right-hand live editbuf view) need startup defaults that come from stored configuration rather than hardcoded values, and a named subshell 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 (beyond the existing missing-dir notice).
- Settings must be resolvable from the contexts that need them (repl thread and code interp / codethread workers), consistent with the G-007 location-transparency model.
- Ties into G-009 themed subshell profiles: a named profile is a natural configset consumer.
Alternatives considered
- Write-back (persisting a toggle changed in a running repl to the toml configset on explicit request, surviving restart) - deferred: kept out of acceptance to stop this goal sprawling; a natural follow-on goal once read-side resolution is proven.
- Reusing Tcl-native config formats (plain dict/script files) - rejected: toml is already the declared format in punk::config 0.1 and is editable/diffable by users without Tcl knowledge.
Notes
- Archived-goal references in this file: G-007 achieved 2026-07-05 (goals/archive/G-007-console-location-transparency.md).