From 687c0113d110f2a4c6e155f55413e0769bcde2ae Mon Sep 17 00:00:00 2001 From: Julian Noble Date: Wed, 8 Jul 2026 18:33:08 +1000 Subject: [PATCH] G-044 proposed: punk::args-driven repl command completion/hinting; cross-goal weaves User-approved goal for interactive command completion and hinting in the repl (raw mode primary), driven by the punk::args documentation corpus: - command-word resolution via the same doc-lookup flow as 'i' (ensembles, subcommands, ensemble parameters - characterized in cmdflow.test), argument position via the definitions (options, choices with parse-consistent prefix/deny/reserve matching, literals, multi-form awareness per G-041) - activation preserves the editbuf's literal-tab support (tab is content in this shell - completion cannot exclusively claim plain Tab; trigger scheme decided and recorded at implementation) - per-subshell completion-provider seam: the punk::args completer is the default provider; a subshell can declare an alternative or none - minimum bar is a clean disable for language subshells such as an interactive xtal session (full xtal completion out of scope, not precluded) - introspection must not execute candidate commands (arginfo principle); no per-keystroke terminal queries added when idle (G-013 approach note) Detail-file weaves from the same direction: - G-041: form candidacy should be exposed as an API accepting PARTIAL argument lists (per-form compatibility while typing) for the G-044 hinting consumer - G-043: subshell definitions gain a repl-behaviour composition aspect (completion/syntax provider); xtal-style language subshells recorded as the motivating scenario, an actual xtal session deferred to its own future goal - G-013: raw editor essentials noted as G-044's prerequisite; the editbuf literal-tab constraint recorded as a standing approach note Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com --- GOALS.md | 6 ++ goals/G-013-raw-mode-default.md | 7 +- goals/G-041-punkargs-form-matching.md | 7 ++ goals/G-043-subshell-definition-plugins.md | 9 +++ goals/G-044-repl-command-completion.md | 87 ++++++++++++++++++++++ 5 files changed, 115 insertions(+), 1 deletion(-) create mode 100644 goals/G-044-repl-command-completion.md diff --git a/GOALS.md b/GOALS.md index 8184af3f..48d02656 100644 --- a/GOALS.md +++ b/GOALS.md @@ -308,3 +308,9 @@ Scope: src/modules/punk/cap-999999.0a1.0.tm (+ new punk.subshell handler), src/m Detail: goals/G-043-subshell-definition-plugins.md Goal: a named subshell's definition - commandset imports (punk::overlay), help topics (the G-042 registry API) and config defaults - can be supplied by provider packages registered through a punk.subshell capability (punk::cap handler validating declarations) and/or declared in stored config (toml per G-014, naming already-installed commandset packages - absorbing punk::overlay's "toml configuration files for defining CLI configurations" todo), with punk::pluginmgr as the discovery/safe-interp trust layer for providers not already trusted - so entering a subshell composes its command surface and help from declarations instead of hardcoded init code. Acceptance: a provider package declaring the punk.subshell capability supplies at least a commandset binding (namespace + prefix) and a help-topic set for a named subshell, and entering that subshell composes them (prefixed commands callable, topics in 'help topics'/'i help') with quit/switch-away restoring the parent surface (no leakage); the punk.subshell punk::cap handler validates declarations (malformed declarations vetoed with a useful message); a subshell's commandset composition can equivalently be declared in stored config without a provider package (G-014 substrate), and the existing hardcoded 'dev' CLI composition keeps working unchanged; declarations for capabilities with no registered handler are discoverable (query or report - closing the silent punk.isbogus gap); punk::cap pkg_unregister leaves no stale handler state (the 'destroy api objects?' review resolved); punk::pluginmgr-based discovery/loading of a provider is either demonstrated end-to-end (including .tm module loading in the safe interp) or explicitly deferred with the remaining pluginmgr gaps recorded in the detail file; G-042's registry mechanism is consumed, not duplicated. + +### G-044 [proposed] punk::args-driven interactive command completion and hinting in the repl (raw mode primary) +Scope: src/modules/punk/repl-999999.0a1.0.tm (editbuf/reader integration, provider seam), src/modules/punk/args-999999.0a1.0.tm + src/modules/punk/ns-999999.0a1.0.tm (introspection surfaces as consumed), src/modules/punk/console-999999.0a1.0.tm (rendering) +Detail: goals/G-044-repl-command-completion.md +Goal: the interactive repl (raw mode primary) offers command completion and hinting driven by punk::args documentation - the command word resolved through the same doc-lookup flow as 'i' (ensembles, subcommands, ensemble parameters) and the argument position through the definition (options, choices with parse-consistent matching, literals, form awareness per G-041) - via an activation scheme that preserves the editbuf's literal-tab support (not exclusively plain Tab), behind a per-subshell completion-provider seam so alternative-language subshells (e.g. an interactive xtal session) can replace, augment or cleanly disable the Tcl-centric completer. +Acceptance: in a raw-mode interactive session a documented trigger (recorded in the detail file; a literal tab remains enterable into the editbuf) presents completions for command words, ensemble subcommands (resolved via the punk::ns doc-lookup flow without executing candidate commands), option flags and choice values (matching consistent with parse semantics: prefix/deny/reserve, and aliases once G-040 lands); a hint display shows the synopsis of the form(s) matching the partial input (consumes G-041's candidacy API when available - until then all-forms or form-0 display with the limitation noted is acceptable); no per-keystroke terminal queries are added when no completion display is active (G-013 approach note); the completer is a provider interface with the punk::args-driven implementation as the default - a subshell can declare an alternative provider or none, proven at minimum by a subshell with completion disabled showing no Tcl-centric interference (the xtal minimum bar; full xtal completion out of scope but not precluded by the interface); line-mode behaviour is unchanged unless a documented subset is added; G-013's raw editor essentials are a prerequisite and this goal does not weaken G-013's acceptance. diff --git a/goals/G-013-raw-mode-default.md b/goals/G-013-raw-mode-default.md index 36bb0971..db30911e 100644 --- a/goals/G-013-raw-mode-default.md +++ b/goals/G-013-raw-mode-default.md @@ -24,7 +24,9 @@ the line-mode type-ahead-loss window during terminal-query raw cycling 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. + (e.g. command completion - now goal G-044, for which this goal's raw editor + essentials are the prerequisite) 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 @@ -60,6 +62,9 @@ stays (see inventory item 4). - 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. +- The editbuf supports literal tab entry (tab is content, not only a UI gesture) - + a standing constraint that G-044's completion-activation scheme must preserve + (completion triggering cannot exclusively claim plain Tab). - Toggle startup defaults resolve through ::punk::config stored configuration when available (G-014); built-in defaults apply when no configuration exists. diff --git a/goals/G-041-punkargs-form-matching.md b/goals/G-041-punkargs-form-matching.md index f18a14c7..72f91e46 100644 --- a/goals/G-041-punkargs-form-matching.md +++ b/goals/G-041-punkargs-form-matching.md @@ -54,6 +54,13 @@ form-selection logic lands. 5. Error-message quality: a no-form-matches error should show per-form failure reasons compactly rather than only form 0's. +Downstream consumer note (2026-07-08, G-044): the interactive command-completion/hinting +goal consumes form candidacy on PARTIAL argument lists - as the user types, the hinting +display wants "which forms are still compatible with the words so far" - so the candidacy +mechanism should be exposed as an API that accepts an incomplete argument list and returns +per-form compatibility (not only an all-or-nothing full parse). Design for that consumer +when shaping step 1. + ## Alternatives considered - Documenting alternate forms as separate subhelp choiceinfo entries (the trace-style diff --git a/goals/G-043-subshell-definition-plugins.md b/goals/G-043-subshell-definition-plugins.md index 69e71e52..5367a75e 100644 --- a/goals/G-043-subshell-definition-plugins.md +++ b/goals/G-043-subshell-definition-plugins.md @@ -110,3 +110,12 @@ Phases: a punk.subshell declaration's resources are resolved. - Related review record: goals/G-042-subshell-help-topics.md "Relationship to the intended plugin facility" section (same 2026-07-08 review). +- Additional composition aspect (user direction 2026-07-08, recorded via G-044): a + subshell definition may also declare repl-behaviour aspects - at minimum a + command-completion provider (G-044's provider seam: replace, augment, or disable the + default punk::args-driven completer), potentially syntax-related behaviour later. The + motivating scenario is a language subshell such as an interactive xtal session + (https://tarray.magicsplat.com/xtal_lang.html - alternative syntax translated to Tcl): + such a subshell would compose an evaluator/commandset, its own help topics, and a + non-Tcl completion provider (or none). An actual xtal session is not owned by this + goal - when pursued it becomes its own goal built on this composition. diff --git a/goals/G-044-repl-command-completion.md b/goals/G-044-repl-command-completion.md new file mode 100644 index 00000000..41935419 --- /dev/null +++ b/goals/G-044-repl-command-completion.md @@ -0,0 +1,87 @@ +# G-044 punk::args-driven interactive command completion and hinting in the repl (raw mode primary) + +Status: proposed +Scope: src/modules/punk/repl-999999.0a1.0.tm (editbuf/reader integration, provider seam), src/modules/punk/args-999999.0a1.0.tm + src/modules/punk/ns-999999.0a1.0.tm (introspection surfaces as consumed), src/modules/punk/console-999999.0a1.0.tm (rendering) +Acceptance: in a raw-mode interactive session a documented trigger (recorded in the detail file; a literal tab remains enterable into the editbuf) presents completions for command words, ensemble subcommands (resolved via the punk::ns doc-lookup flow without executing candidate commands), option flags and choice values (matching consistent with parse semantics: prefix/deny/reserve, and aliases once G-040 lands); a hint display shows the synopsis of the form(s) matching the partial input (consumes G-041's candidacy API when available - until then all-forms or form-0 display with the limitation noted is acceptable); no per-keystroke terminal queries are added when no completion display is active (G-013 approach note); the completer is a provider interface with the punk::args-driven implementation as the default - a subshell can declare an alternative provider or none, proven at minimum by a subshell with completion disabled showing no Tcl-centric interference (the xtal minimum bar; full xtal completion out of scope but not precluded by the interface); line-mode behaviour is unchanged unless a documented subset is added; G-013's raw editor essentials are a prerequisite and this goal does not weaken G-013's acceptance. + +## Context + +User direction (2026-07-08): the raw mode repl system will use punk::args based +documentation to retrieve enough information about incomplete commands - taking note of +different forms - to provide interactive command-completion and hinting. + +Constraints stated up front: + +- The editbuf must continue to support literal tabs, so completion activation is not + purely Tab-based. (Tab is data in this shell, not only a UI gesture.) +- The Tcl/punk::args-centric completer must be able to get out of the way: the + motivating non-Tcl scenario is an interactive session for an alternative syntax such + as the xtal Tcl package (https://tarray.magicsplat.com/xtal_lang.html) running as a + subshell, perhaps with plugin-defined repl behaviour for completion/syntax. The + minimum bar for this goal is a clean disable/replace seam; actual xtal completion or + an xtal session itself is not this goal's deliverable. + +Why punk::args is the right substrate: the definitions already carry per-position +knowledge - leaders (including ensemble parameters), option names, choice sets with +prefix/deny/reserve semantics (choices.test), literal/literalprefix types, and multiple +forms - and the punk::ns doc-lookup flow (cmdwhich/cmdinfo/cmd_traverse, characterized in +cmdflow.test 2026-07-08) already resolves command words through aliases, ensembles, +subhelp choiceinfo and ensemble parameters WITHOUT executing candidate commands (the +arginfo principle: introspection must not run commands to elicit usage). + +## Approach (sketch - to be refined when activated) + +1. Introspection layer (no repl dependency, testable headless): + given a partial word-list, return a completion/hint dataset - candidate next words + (subcommands from choiceinfo, option flags, choice values, literals from -type), + plus the synopsis/form information for the current position. Sources: + punk::ns::cmdinfo for the command-word path, punk::args::get_spec for the argument + position. Choice-word matching must reuse the parser's resolution rules (the shared + choice-resolution helper planned in G-040 is the natural common code; prefix + highlighting from the usage renderer already computes minimal prefixes). + Form handling: before G-041, enumerate all forms' next-position candidates (union) + and show all/form-0 synopses with the limitation noted; when G-041's candidacy API + exists, rank/filter forms by the partial input (G-041's detail file notes the API + should accept partial argument lists for exactly this consumer). +2. Repl integration (raw mode): trigger scheme preserving literal tab - candidates to + evaluate at implementation time (decision recorded here): double-Tab, a dedicated + chord (e.g. ctrl-space), Tab-completes-only-after-non-whitespace with an escape to + insert a literal tab, or fully configurable binding via G-014 config. Hinting may be + passive (status/ghost line) independent of the completion trigger. Rendering budget: + no added per-keystroke terminal queries when idle (G-013 approach note - cache + console size with invalidation); the G-013 editbuf live-view debug gate is the + development aid for this work (G-013 debug inventory item 2). +3. Provider seam: the completion engine behind an interface (provider per subshell); + the punk::args-driven implementation is the default provider. A subshell declares an + alternative provider or none - the declaration rides the subshell-definition + composition of G-042/G-043 (a punk.subshell provider or stored-config entry may name + a completion provider alongside commandsets and help topics). Language subshells + (xtal-style: alternative syntax translated to Tcl) are the motivating consumer; an + actual interactive xtal session would be its own goal when pursued, composing a + G-043 subshell definition (commandset/evaluator, help topics, completion provider). + +## Alternatives considered + +- Command-name-only completion (readline-style over info commands) - insufficient: the + value is in argument-position awareness (subcommands, flags, choices, forms) which the + punk::args corpus already encodes. +- Executing candidate commands to discover usage - rejected: the established arginfo + principle forbids running commands for introspection (risky side effects); everything + needed is available declaratively. +- Hardcoding Tab as the only trigger - rejected per the literal-tab constraint; the + editbuf accepts tab characters as content. + +## Notes + +- Prerequisites/relations: G-013 (raw mode default + editor essentials - prerequisite; + its editbuf live view is the dev aid; its no-per-keystroke-query note is adopted), + G-041 (form candidacy on partial input - consumed when available), G-040 (choice + alias resolution shared with the parser), G-042/G-043 (per-subshell provider + declaration), G-014 (configurable trigger/bindings and per-subshell defaults). +- xtal reference: https://tarray.magicsplat.com/xtal_lang.html - an alternative syntax + for Tcl (tarray project); an interactive xtal subshell is the concrete + language-subshell scenario the provider seam must not preclude. +- The doc-lookup flow this consumes is characterized by + src/tests/modules/punk/ns/testsuites/ns/cmdflow.test (2026-07-08), including ensemble + -parameters handling; the choice semantics by + src/tests/modules/punk/args/testsuites/args/choices.test; forms by forms.test.