From 4b91fd6f4c3541e5b4dec29d323c4fafac178f6d Mon Sep 17 00:00:00 2001 From: Julian Noble Date: Mon, 6 Jul 2026 12:48:09 +1000 Subject: [PATCH] add goals G-013 (raw-mode repl default) and G-014 (punk::config toml) G-013: raw input mode as the repl default - per-keystroke debug emissions (add_chunk frame, rhs editbuf view) individually gated and repl-toggleable, raw editor parity for history/cursor movement, debugrepl marked-line form retained for simple terminals with its first-word activation mechanism under review; retires the tcl 8.6 idle-prompt query residue guarded in punk::console 0.7.1. G-014: complete ::punk::config - toml files in the XDG config dir with per-named-subshell override/inherit resolution; first consumer is the G-013 editbuf-view startup default. Write-back persistence deferred. Both proposed; detail files under goals/. Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com --- GOALS.md | 12 ++++++ goals/G-013-raw-mode-default.md | 71 +++++++++++++++++++++++++++++++++ goals/G-014-punk-config-toml.md | 44 ++++++++++++++++++++ 3 files changed, 127 insertions(+) create mode 100644 goals/G-013-raw-mode-default.md create mode 100644 goals/G-014-punk-config-toml.md diff --git a/GOALS.md b/GOALS.md index ead22709..71b8eee7 100644 --- a/GOALS.md +++ b/GOALS.md @@ -121,3 +121,15 @@ Scope: src/project_layouts/, src/make.tcl, src/modules/punk/mix/ (layout instant Detail: goals/G-012-template-payload-safety.md Goal: project layouts carry no live nested VCS-config files - template .gitignore payloads are stored inert (renamed, or fauxlink-encoded) and materialized at project generation - and src/make.tcl has an explicit punkcheck-tracked step that refreshes layout payloads from their canonical sources. Acceptance: a scan of src/project_layouts finds no file named .gitignore, and git check-ignore --no-index over every layout file matches only root-.gitignore rules (nested rules provably inert); a project generated from each affected layout receives a working .gitignore whose content matches the canonical payload/target; after editing a canonical source (e.g. root .gitignore), the make.tcl template-refresh step updates the derived layout payloads (punkcheck-tracked), covering vendor/punk layouts as well as custom/_project; the previously hidden template files (layout READMEs, vendored TODO-class files) remain git-tracked without per-file force-add exceptions. + +### G-013 [proposed] Raw mode as the repl's default input mode +Scope: src/modules/punk/repl-999999.0a1.0.tm, src/modules/punk/console-999999.0a1.0.tm +Detail: goals/G-013-raw-mode-default.md +Goal: a repl launched without explicit mode configuration starts in raw input mode with a clean display - every per-keystroke debug emission behind its own repl-operable toggle - and raw editing covers the line-mode essentials (history navigation, cursor movement). +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 +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. diff --git a/goals/G-013-raw-mode-default.md b/goals/G-013-raw-mode-default.md new file mode 100644 index 00000000..36bb0971 --- /dev/null +++ b/goals/G-013-raw-mode-default.md @@ -0,0 +1,71 @@ +# G-013 Raw mode as the repl's default input mode + +Status: proposed +Scope: src/modules/punk/repl-999999.0a1.0.tm, src/modules/punk/console-999999.0a1.0.tm +Acceptance: as in root GOALS.md index (canonical). + +## Context + +Line mode is today's default because on Windows it gives OS-provided line editing +and arrow-key history for free. Raw mode is the intended default, blocked by (1) +debug output emitted with cursor-move sequences, and (2) unfinished raw editor +features. Beyond display polish, flipping the default retires the last known +reader-cooperation hole on tcl 8.6: terminal queries fired while the line-mode +reader is armed at an idle prompt are hostage-prone by design (punk::console 0.7.1 +made this fail fast rather than hang; raw default makes it work). It also removes +the line-mode type-ahead-loss window during terminal-query raw cycling +(#review, repl-999999.0a1.0.tm ~1677). + +## Debug emission inventory (as of repl 0.2.2) + +1. **add_chunk top-left frame** (repl ~1145-1173) - per-keystroke framed dump of the + overtype::renderline merge, painted at row 2 col 1. Currently ungated. This is + definitely a debug feature: it gets its own toggle, operable from within a + running repl, default off. +2. **Right-hand live editbuf view** (console_editbufview, repl ~2043, called ~2315) - + currently ungated. An important development aid for per-keystroke features + (e.g. command completion) and stays available, but behind its own separate gate. + Its startup default should ultimately come from stored configuration via + ::punk::config (see G-014) - toml-backed, independently configurable per named + subshell - with off as the built-in fallback. Longer term, once the console + framework is more complete (G-001 backends), this live view could be streamed + off-console instead - e.g. over udp to a monitoring app, or to a tk text-widget + system acting as a pseudo terminal. +3. **console_debugview** (repl ~1976) - already gated (debug_repl > 0). +4. **Marked-line form** (debug_repl_emit, repl ~2566-2599, debug_repl > 100) - emits + prefixed lines before the command result via the debugreport pseudo-channel, no + cursor addressing. Retained as the baseline debug form for simple terminals + (vt52, other console systems we implement) where complex terminal interaction + is unavailable or unwanted. + +## debugrepl activation review + +Current mechanism: first word "debugrepl" in the submitted command is intercepted +before eval; bare/N/cancel manipulate a oneshot decrementing counter whose +thresholds (>0, >100) select display layers. Review whether first-word +interception is worth retaining or whether a proper Tcl command is better: a real +command can be restricted in subshells via interp hide (aligns with G-003/G-009 +restriction mechanisms), and named toggles would replace the magic thresholds now +that gates are separate. Whatever the outcome, the marked-line output form itself +stays (see inventory item 4). + +## Approach notes + +- Cursor save/restore is a single slot, not a stack: the code already mixes + cursorsave_ and plain move_emitblock variants to avoid collisions (comment at + repl ~2031). Toggleable frames need one coherent cursor-bookkeeping policy. +- The raw chunk path calls punk::console::get_size per keystroke to position the + rhs frames (repl ~2296-2308, acknowledged 1+ms). Cache the size with explicit + invalidation; avoid any per-keystroke terminal query when no debug view is on. +- Raw editor stubs to replace: arrow-right/up and esc currently just rputs debug + notices (repl ~2477-2492); history navigation and cursor movement are the + parity items. +- Toggle startup defaults resolve through ::punk::config stored configuration when + available (G-014); built-in defaults apply when no configuration exists. + +## Alternatives considered + +- Keeping line mode as default and making idle-prompt queries cooperate with the + 8.6 parked reader - rejected: the 8.6 console driver parks a cooked ReadConsole + that a raw flip cannot rescue (established 2026-07-05); cooperation is not + achievable there, only fail-fast. diff --git a/goals/G-014-punk-config-toml.md b/goals/G-014-punk-config-toml.md new file mode 100644 index 00000000..08597b49 --- /dev/null +++ b/goals/G-014-punk-config-toml.md @@ -0,0 +1,44 @@ +# 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 +Acceptance: as in root GOALS.md index (canonical). + +## 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). + +## Approach + +- 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.