diff --git a/.github/instructions/memory.instructions.md b/.github/instructions/memory.instructions.md index c40f3f3..b52946d 100644 --- a/.github/instructions/memory.instructions.md +++ b/.github/instructions/memory.instructions.md @@ -99,6 +99,9 @@ Tagline: Generic CLI host — owns the Symfony runtime + lazy command discovery, ## Hard requirements (all webware ecosystem work) - **Named parameters = hard requirement.** Always use named arguments (saved to global memory). +- **Conditional dispatch uses `match`, not chained `if` statements.** Discrete selection over a + known set of cases (key handling, status/state selection, mode dispatch) is written as a `match` + expression. Precedent: `CommandInputPrompter::onKey()`. - mago lint is the backstop; rules docs (reference for "what to prefer"): https://mago.carthage.software/latest/en/tools/linter/rules/ - Greenfield: **no mago baselines** — resolve every lint/analyze/guard finding at source. diff --git a/specs/001-console-tui/contracts/cli.md b/specs/001-console-tui/contracts/cli.md index 0b183f6..a7a7216 100644 --- a/specs/001-console-tui/contracts/cli.md +++ b/specs/001-console-tui/contracts/cli.md @@ -17,8 +17,23 @@ The console's own interface. ## Output - Command output and exit status are shown after invocation, then the menu returns. -- A failing command reports a non-zero status and the failure cause; the console does not crash. +- A failing command reports a non-zero status and the failure cause; the console does not crash.- A command's output is also visible while it runs, so a command that stops to ask a question does not appear to hang. +## Prompt keys (supplying a command's arguments and options) + +- `Tab` / `Down`: next field (wraps). `Up`: previous field (wraps). +- `Space`: toggle the focused flag. +- `Left` / `Right` / `Backspace` / printable characters: edit the focused value. +- `Enter`: submit — refused while any required field is blank. +- `Esc`: cancel and return to the menu without running the command. + +The row between the last field and the key hints shows the active field's description, or the +refusal message when a submission was refused. + +## Required input + +- A field the command declares as required is marked with an asterisk in the form. +- Requiredness is taken only from the command's own definition. A value declared as an option is never treated as required, because Symfony cannot declare an option required. ## Exit - The console itself exits cleanly with status 0 when quit. diff --git a/specs/001-console-tui/contracts/command.md b/specs/001-console-tui/contracts/command.md index 80a591b..6d93443 100644 --- a/specs/001-console-tui/contracts/command.md +++ b/specs/001-console-tui/contracts/command.md @@ -14,3 +14,5 @@ A Symfony Console `Command` with: - The command is invocable independently of the console and returns an exit status (`0` success, non-zero failure). - The console presents the command's name, description, arguments, and options; it does not reimplement command logic. +- A value the command treats as mandatory MUST be declared as a required argument. A requirement expressed only in control flow — an option consulted with `??` and asked for when absent — cannot be seen by the console, and can never be marked or validated. +- Prompting for values the operator did not supply belongs in the command's own `interact()`, which runs before the definition is validated and so keeps working when the command is run directly. diff --git a/specs/001-console-tui/data-model.md b/specs/001-console-tui/data-model.md index a33206b..4908f7f 100644 --- a/specs/001-console-tui/data-model.md +++ b/specs/001-console-tui/data-model.md @@ -28,11 +28,42 @@ A Symfony Console `Command`, registered in the container and mapped by name. when the operator focuses a command (the command instance is resolved lazily at that point). +### PromptField (in-memory) + +One argument or option of the selected command, rendered as an editable field. + +- `name`: string — the argument name, or the option name without its `--` prefix. +- `description`: string — the help text shown on the status row while this field is active. +- `kind`: `Argument` | `Option` | `Flag` — flags are toggled with `Space`; the others are typed. +- `required`: bool — `true` only for arguments declared required; options are never required. Drives the asterisk in the field label and the check made when Enter is pressed. +- `isArray`: bool — a comma-separated value becomes a list when the command's input is built. +- `value`: string — seeded from the declared default. +- `flagValue`: bool — seeded from a boolean default. +- `cursor`: int — edit position, clamped to the value's length. + +### PromptState (in-memory) + +- `fields`: list. +- `activeIndex`: int — wraps modulo the field count. +- `submitted`: bool. +- `cancelled`: bool. +- `refused`: bool — whether a submission has been refused, so the blank required fields are reported until they are filled in; once they are, the row goes back to the active field's description. + +### PromptStatusRow (derived, on demand) + +The single row between the last field and the footer. + +- Reports the blank required fields while `refused` is set and any remain blank; otherwise shows the active field's description. +- The report is derived from the current field values on each draw, so it shrinks as the operator fills the fields in rather than going stale. +- Precedence: the refusal report wins over the description. + ## Relationships - The command map maps one `name` to one command class (FR-005); duplicates are surfaced. - `MenuState` indexes into the list of command names. - `HelpView` is derived from a single `Command`, resolved on demand. +- `PromptState` holds one `PromptField` per argument and per option of the selected command, in that + order; the status row reads the active one. ## Discovery @@ -44,3 +75,8 @@ A Symfony Console `Command`, registered in the container and mapped by name. - A command name MUST be unique within the map (FR-006); duplicates throw `DuplicateCommandException`, never hidden. - An empty command set is valid (FR-007); the console still launches and reports it. - After a command runs or fails, the menu MUST return to a valid `MenuState` (FR-008). +- Submission is accepted only while every field with `required === true` holds a non-empty value (FR-009/FR-010). +- Every field with `required === true` is marked with an asterisk, so the requirement is visible before submission (FR-012). +- Requiredness comes from the command's definition and from nothing else; an option is never marked or treated as required, because Symfony cannot declare it so. +- A refused submission MUST run nothing, name the blank required fields, focus the first of them, and preserve every value already entered. +- Fields that are not required and left blank are omitted from the command's input, so the command's own default applies rather than an empty value being passed. diff --git a/specs/001-console-tui/plan.md b/specs/001-console-tui/plan.md index 3100228..c5d4adf 100644 --- a/specs/001-console-tui/plan.md +++ b/specs/001-console-tui/plan.md @@ -51,6 +51,141 @@ hard `require` on this package — the dependency direction is one-way No violations requiring justification. +## Design Decisions — command input machinery (issue #31) + +Added 2026-09-25. Implements FR-009…FR-012. The defects these address are recorded in issue #31; +this section is the design record for the fixes. + +### Prompt layout and the key contract + +Fields occupy rows `y … y + count - 1` and the footer is drawn at `y + count + 1`, so **row +`y + count` is already free**. That row becomes the status row — no new widget kinds, no extra +rows, and no change to the frame size. + +```text +y + 0 > field 0: +… +y + count - 1 > field n-1: +y + count status row — refusal message, else the active field's description +y + count + 1 footer — key hints +``` + +| Key | Action | +|---|---| +| `Tab`, `Down` | next field (wraps) | +| `Up` | previous field (wraps) | +| `Space` | toggle a flag field | +| `Left`, `Right`, `Backspace`, printable | edit the active text field | +| `Enter` | execute — refused if any required field is blank | +| `Esc` | cancel, back to the menu | + +Enter no longer advances the active index; navigation keeps its own keys, so the overload +disappears. Nothing becomes unreachable — `PromptState::$activeIndex` already clamps modulo the +field count. + +### Required-field validation in the submit path + +Only arguments can be required: `CommandInputPrompter::prompt()` reads `$argument->isRequired()` +for arguments and hard-codes `required: false` for options. Validation is therefore "every field +with `required === true` holds a non-empty value", evaluated when Enter is pressed, before +`toParameters()` runs. + +On refusal the console MUST NOT run the command and MUST NOT pass `''`. Today a blank required +argument is passed as an empty string, which Symfony accepts as a supplied value, so the failure +surfaces deep inside the command instead of the prompt naming what is missing — `mezzio:handler:create` +would generate a class named the empty string. The state records that a submission was refused and +moves the active index to the first blank required field; the report itself is computed from the +current field values each time the row is drawn, so it shrinks as the operator fills the fields in +rather than going stale. Every value already entered is preserved. + +`toParameters()` keeps omitting blank *optional* fields — Symfony then applies its own default, +which is the existing and correct behaviour. + +### Active-field help text + +`TextInput::placeholder()` is documented as *"text shown when value is empty"*. A description +handed to it disappears the moment the field carries a value — precisely the case a declared +default creates, since defaults are read from the definition and pre-filled into the field. The +description therefore moves off the placeholder entirely and onto the status row, rendered for the +active field whatever its value. A pending refusal message takes precedence over it, so one row +carries both meanings and the form does not grow. + +### Requiredness, and the asterisk marker + +Requiredness is declared on **arguments only**. Symfony's `InputOption` has no required concept at +all — its modes only describe whether a value is accepted — while `InputArgument` carries +`REQUIRED = 1`, `OPTIONAL = 2`, `IS_ARRAY = 4`. The console therefore reads requiredness from +`$argument->isRequired()` and from nowhere else, and marks every required argument with an +asterisk in its field label: + +```text +> * configFile: + class: + ignore-unresolved: [ ] +``` + +Field labels reserve the marker column — the asterisk for a required argument, a +space otherwise — and an option's label carries its bare name, without the `--` its +input parameter is built with. + +That is why `dev:mode` shows none (three `VALUE_NONE` flags, and options are never required) while +`mezzio:handler:create` shows one (`handler` is `InputArgument::REQUIRED`). The marker exists so +the operator can see what is mandatory without going back and forth to the command's docs or +code — the complaint that started this work. + +A command that needs a mandatory value must declare it as a required argument. A value declared as +an option with a `?? $helper->ask(...)` fallback states its requirement in control flow, where +nothing outside the class can see it — which is exactly `user:init-db`'s situation today. + +### Cross-repository change: `user:init-db` + +`user:init-db` (webware-usermanager) requires first name, last name, email and password — a user +must be created — but declares all four as optional options and asks for them inside `execute()`. +The console cannot see that, so it cannot mark or validate them. The fix belongs to that component +and is its own PR there: + +- declare the four as `InputArgument::REQUIRED`; +- move the prompting into `interact()`, filling the arguments with `setArgument()`. + +`Command::run()` runs `bind()` → `initialize()` → **`interact()`** → **`validate()`** → +`execute()`, and `interact()`'s own docblock says it "is executed before the InputDefinition is +validated. This means that this is the only place where the command can interactively ask for +values of missing required arguments." Direct CLI use therefore keeps prompting exactly as it does +today, while the definition now tells the console the values are mandatory. `--role` keeps its +`developer` default; `--drop` stays a flag. + +The console needs no new machinery for this — `*` and validate-on-Enter already read +`isRequired()`. The two changes are independent and the console work does not wait on this one. + +### Out of scope: a command's own interactive questions + +The console does not display a command's own interactive questions, and this work does not change +that. It wraps commands whose input the command declares; a command that asks its own questions is +left as it is. + +The hazard is real but narrow, and it lives in our own components. `CommandRunner` gives the +command a `BufferedOutput`, so `QuestionHelper::writePrompt()` writes into a buffer nobody flushes +and `fgets(STDIN)` then blocks with nothing on screen. It is reachable only when a value the +command consults with `??` is neither declared nor filled — for `user:init-db`, one of the four +value options left blank. Declaring them as required arguments removes the case that matters, and +the console's form then validates them like any other required field. + +Terminal state was never the cause: `Psl\Terminal\Application::run()` restores raw mode and resets +the alternate screen in its `finally`, so the terminal is normal by the time the command runs. + +Two remedies were evaluated and rejected for this scope: handing the command the terminal, and +substituting the Application's `question` helper so questions render in the TUI. Neither is needed +once requiredness is declared, and helper substitution could never be sufficient on its own — it +only sees commands that call `$this->getHelper('question')`, while `user:init-db` constructs its +own. + +### Implementation conventions + +- **Conditional dispatch uses `match`, not chained `if` statements.** Key handling, the submit / + refuse step and the status-row selection are each a discrete selection over a known set of + cases, so they are written as `match` expressions. This applies to new code and to code being + touched, and matches the precedent already set by `CommandInputPrompter::onKey()`. + ## Project Structure ### Documentation (this feature) @@ -77,7 +212,10 @@ src/ ├── Help/ │ └── HelpFormatter.php # render purpose/arguments/options ├── Prompt/ -│ └── CommandInputPrompter.php # collect inputs for a selected command +│ ├── CommandInputPrompter.php # collect inputs for a selected command +│ ├── PromptField.php # one argument/option as editable state +│ ├── PromptKeyAction.php # per-key behaviour, incl. the submit/validate step +│ └── PromptState.php # active field, submission, cancellation, missing-required list ├── Runner/ │ └── CommandRunner.php # invoke command, capture output + status ├── Container/ # CommandLoaderFactory, ApplicationFactory, MenuCommandFactory diff --git a/specs/001-console-tui/quickstart.md b/specs/001-console-tui/quickstart.md index e745a4a..a3c8b10 100644 --- a/specs/001-console-tui/quickstart.md +++ b/specs/001-console-tui/quickstart.md @@ -36,6 +36,24 @@ Validation guide — proves the feature end-to-end. Implementation details belon **Expected**: the console still launches and reports that no commands are available. +8. Fill in a command with several arguments and options, and press Enter while a middle field is + focused. + + **Expected**: the command runs — submission does not require first moving to the last field. + +9. Submit a command leaving a required argument blank. + + **Expected**: the command does not run, the blank field is named on the row above the key hints, + focus moves to it, and the values already entered are still there. + +10. Look at a field that carries a declared default. + + **Expected**: the field's description is visible even though the field is already populated. + +11. Open a command that declares a required argument. + + **Expected**: that field is marked with an asterisk, and the command's optional fields are not. + ## Success All acceptance scenarios in [spec.md](./spec.md) hold in a terminal with no manual command-list configuration. diff --git a/specs/001-console-tui/research.md b/specs/001-console-tui/research.md index 2ca8da5..f33bfe1 100644 --- a/specs/001-console-tui/research.md +++ b/specs/001-console-tui/research.md @@ -43,3 +43,34 @@ Phase 0 output — resolves the technical unknowns from the plan's Technical Con - **Decision**: Declare `symfony/console` as `^7.4 || ^8.0` — the exact range `laminas/laminas-cli` allows. Composer resolves a single shared version; webware-console owns the Symfony runtime and runs laminas-cli commands in-process, so both must agree on the major. - **Rationale**: `laminas/laminas-cli` requires `symfony/console ^7.4 || ^8.0`; `mezzio/mezzio-tooling` has no runtime `symfony/console` requirement (dev-only pin). Mirroring laminas-cli's range lets any consuming app install both packages with one joint version — no conflict whether it targets Symfony 7 or 8. - **Alternatives considered**: Single-major pin `^7.4` (works, but drags Symfony 8 apps down to 7.4); unbounded `*` (rejects nothing, loses the version guard). + +## R-008: Prompt key contract and submission + +- **Decision**: Enter is the only submit key, and it submits from any field — gated on the required fields being filled. Field movement stays on Tab/Down/Up, `Space` toggles a flag, `Esc` cancels. Enter no longer advances the active index. +- **Rationale**: FR-009. Today Enter means "next field" until the operator happens to be standing on the last field, so whether a command can be submitted depends on how many fields it declares — `dev:mode`'s flag in the middle of its list is why the habit broke there and nowhere else. One key, one action; the navigation keys are unaffected, and the active index already wraps, so no field becomes unreachable. +- **Alternatives considered**: Keep Enter as next/confirm and add a dedicated submit key (rejected — two keys for one mental model, and an extra keystroke everywhere); gate Enter on the last field but add a modifier form (rejected — the same overload with more surface). + +## R-009: Required-field validation in the submit path + +- **Decision**: required fields are validated when Enter is pressed, before `toParameters()` runs. A refusal names the blank required field(s), moves the active index to the first of them, preserves every value already entered, and does not run the command. +- **Rationale**: FR-010. A blank required argument is currently passed as `''`, which Symfony treats as a supplied value, so the failure surfaces deep inside the command rather than at the prompt — `mezzio:handler:create` would try to generate a class named the empty string. Only arguments can be required (`prompt()` hard-codes `required: false` for options), so the check is a single pass over the fields flagged `required`. +- **Alternatives considered**: mark the console's `ArrayInput` non-interactive and let Symfony reject the empty value downstream (rejected — moves the failure further from the operator, and answers any inner question with its default); render an error and re-run the command (rejected — re-running discards the operator's work). + +## R-010: Where the active field's description is drawn + +- **Decision**: on the status row at `y + count` — the row already free between the last field and the footer — for the active field only, replacing the `TextInput` placeholder. A pending refusal message takes precedence. +- **Rationale**: FR-011. `TextInput::placeholder()` is documented as "text shown when value is empty", so the description vanishes exactly when it is most needed: a declared default pre-fills the field, and `mezzio:routes:list` then shows `format: table` with no hint that `table` is legal or what the alternatives are. Reusing the free row avoids adding widget kinds or growing the form, and giving one row clear precedence avoids a second layout rule. +- **Alternatives considered**: a right-hand description column (rejected — eats the input width on narrow terminals); a description row per field (rejected — the form grows a row per field in a fixed-height frame); keeping the placeholder alongside the row (rejected — duplicated text, and the placeholder is still invisible in the case that matters). + +## R-011: How a command declares that a value is required + +- **Decision**: requiredness is read from the command's own definition, from `InputArgument::REQUIRED` alone. Every required argument is marked with an asterisk in the form; options never are. +- **Rationale**: FR-012. Symfony offers no other way to express it — `InputOption` has no required concept at all (its modes only describe whether the value is accepted), while `InputArgument` carries `REQUIRED = 1`, `OPTIONAL = 2`, `IS_ARRAY = 4`. A value a command must have is therefore declarable only as a required argument, and the console has nothing else to infer from. Marking it is what saves the operator from going back and forth to the command's docs or code, which is the complaint this work started from. +- **Alternatives considered**: inferring requiredness from "an option with no declared default" (rejected — it is wrong: `mezzio:routes:list`'s options declare no useful default yet are genuinely optional); a console-side convention for marking an option required (rejected — a private convention no other tool follows, duplicating what the definition can already express and invisible to anything that reads the definition directly). + +## R-012: Where a command's interactive prompting belongs + +- **Decision**: prompting for values the operator did not supply belongs in the command itself, in `Command::interact()`. The console does not display a wrapped command's own questions. `user:init-db` declares its four mandatory values as `REQUIRED` arguments and asks for them in `interact()`. +- **Rationale**: `Command::run()` runs `bind()` → `initialize()` → `interact()` → `validate()` → `execute()`, and `interact()`'s docblock states it "is executed before the InputDefinition is validated. This means that this is the only place where the command can interactively ask for values of missing required arguments." So the requirement becomes visible in the definition — which is what the console needs — while direct CLI use keeps prompting exactly as before, and the requirement stays with the component that owns it. +- **Alternatives considered**: handing the command the terminal so its own `QuestionHelper` works unmodified (rejected for this scope — unnecessary once requiredness is declared); substituting the Application's `question` helper so questions render in the TUI (rejected — it only sees commands that call `$this->getHelper('question')`, while `user:init-db` constructs its own, so it could never be sufficient); marking the `ArrayInput` non-interactive so Symfony answers with each question's default (rejected — a user would be created from placeholder values, which defeats the command). +- **Recorded hazard, not fixed here**: a command that consults a value with `??` and asks for it only when absent has that question written into the `BufferedOutput` the runner passes, after which `fgets(STDIN)` blocks with nothing on screen. Declaring the mandatory values as required arguments removes the case that matters. diff --git a/specs/001-console-tui/spec.md b/specs/001-console-tui/spec.md index 7bf110b..25926a2 100644 --- a/specs/001-console-tui/spec.md +++ b/specs/001-console-tui/spec.md @@ -8,6 +8,17 @@ **Input**: User description: "Build the Webware console TUI: present a menu of CLI commands from Webware components and Mezzio, show better help for each command, and invoke them." +## Clarifications + +### Session 2026-09-25 + +- Q: Should Enter submit the form from any field, moving field navigation entirely to Tab/Up/Down? → A: Enter submits from any field, but submission is refused while any required field is blank; Tab, Up and Down move between fields and remain the only way to navigate. +- Q: When the form is submitted with a required field left blank, what should happen? → A: Refuse to run, name the blank required field(s), and keep the operator in the form with every value already entered left intact. Passing an empty value through so the command fails somewhere inside is not acceptable. +- Q: Where should the active field's description be shown so it survives a field that already has a value? → A: On the spare row directly below the field list, showing the active field's description. +- Q: How should the operator be able to tell which fields a command requires, before submitting? → A: Every field the command declares as required is marked with an asterisk in the form, so the requirements are visible while it is being filled in — the operator should not have to consult the command's code or docs. +- Q: How should a value that a command genuinely requires, but that is declared as an option, be handled? → A: Symfony cannot express a required option — requiredness exists only on arguments. A command needing a mandatory value MUST declare it as a required argument. `user:init-db`'s four mandatory values are to be declared that way by its own component, with its prompting moved into `interact()`, which runs before the definition is validated and so keeps prompting on direct CLI use. +- Q: Should the console surface a wrapped command's own interactive questions? → A: No — out of scope. The console wraps commands whose input the command declares. A command that asks its own questions is left unchanged and is not this work's concern. + ## User Scenarios & Testing *(mandatory)* ### User Story 1 - Browse commands via a menu (Priority: P1) @@ -52,6 +63,10 @@ The operator selects a command, supplies the required inputs, runs it, and sees 1. **Given** a selected command that succeeds, **When** it runs, **Then** its output is shown with a success status and the console returns to the menu. 2. **Given** a selected command that fails, **When** it runs, **Then** the failure and its cause are shown and the console returns to the menu without crashing. +3. **Given** a command with several arguments and options, **When** the operator fills them in and submits from whichever field they are standing on, **Then** the command runs without the operator first having to move to the last field. +4. **Given** a command with a required field, **When** the operator submits while that field is blank, **Then** the command does not run, the blank field is named, and the operator's other entries are still there to correct. +5. **Given** a field pre-filled from a declared default, **When** the operator looks at the form, **Then** that field's description is visible even though the field is not blank. +6. **Given** a command with a required argument, **When** the operator looks at its form before submitting, **Then** that field is marked with an asterisk. --- @@ -77,6 +92,9 @@ The menu automatically reflects the commands provided by installed Webware compo - A command has a very large number of arguments or options — help MUST remain readable (e.g. grouped or scrollable). - A command takes a long time to run — the console MUST remain responsive and show that it is still working. - An operator aborts input for a command midway — the console MUST return to the menu without a partial or broken state. +- A required field is left blank at submission — the console MUST refuse to run, name the field, and keep the operator in the form with their other entries intact, rather than passing an empty value to the command. +- A field's value is seeded from a declared default — that field's description MUST stay visible, since a pre-filled value is exactly where the operator most needs to know what is allowed. +- A command needs a value but declares it as an option — the console cannot see that requirement, because requiredness can only be declared on an argument; such a command MUST declare the value as a required argument. ## Requirements *(mandatory)* @@ -90,11 +108,16 @@ The menu automatically reflects the commands provided by installed Webware compo - **FR-006**: System MUST handle duplicate command names without hiding either command or misrunning them. - **FR-007**: System MUST remain operable when no commands are available. - **FR-008**: System MUST return to the menu after a command completes or fails. +- **FR-009**: System MUST accept submission of a command's input form from any field, without the operator first having to reach a particular field. +- **FR-010**: System MUST refuse to run a command while any of its required fields is blank, MUST identify each blank required field by name, and MUST keep the operator in the form with all previously entered values preserved. +- **FR-011**: System MUST keep the active field's description visible whenever that field holds a value, including a value seeded from a declared default. +- **FR-012**: System MUST mark each field the command declares as required, so the operator can see what is mandatory before submitting. ### Key Entities *(include if feature involves data)* - **Command**: an invocable operation with a name, a short purpose, arguments, and options. - **Command map**: the discovered name => command-class registrations presented in the menu (loaded lazily via a Symfony command loader). +- **Wrapped command shape**: the arguments and options a command declares, which is what the console's input form is built from. The shapes already reachable from the menu range from a single field (`servicemanager:generate-factory-for-class`, one required argument; `acl:init-db`, one option) up to seven (`mezzio:handler:create`: one required argument, two flags, and up to four template options that appear only when a template renderer is registered), and include a command whose middle field is a flag rather than a value (`dev:mode`: `enable`, `disable`, `status`). Requiredness is declared on arguments only — Symfony has no required option — so a command that must have a value has to declare it as a required argument for the console to be able to see it. ## Success Criteria *(mandatory)* @@ -105,6 +128,8 @@ The menu automatically reflects the commands provided by installed Webware compo - **SC-003**: The help view accurately reflects every argument and option of a command. - **SC-004**: Running a command from the menu produces the same output and status as invoking it directly. - **SC-005**: An operator can complete the locate → view-help → run flow for a typical command in under 1 minute. +- **SC-006**: An operator can complete any command reachable from the menu using only Tab/Up/Down to move between fields, Space to toggle a flag, and Enter to submit — no command can only be completed by first reaching a particular field. +- **SC-007**: Every field a command declares as required is visibly marked before submission, so an operator can see what is mandatory without consulting the command's code or documentation. ## Assumptions @@ -114,3 +139,6 @@ The menu automatically reflects the commands provided by installed Webware compo - The rendering stack for the text interface is decided during planning, not in this specification. - In v1 the console focuses on the menu, help, and invocation. mezzio-tooling commands are discovered via the merged `laminas-cli` config key; fully wrapping mezzio-tooling's TUI remains a longer-term direction. - Discovered commands are component-registered commands, not arbitrary shell commands. +- The submission, required-field validation and active-field help behaviours belong to the shared input machinery, so they change for every command driven through the menu — not only the command that first exposed the defects. +- Required input is declared in the command's own definition. The console takes requiredness from there and infers it from nothing else, so a command that needs a mandatory value must declare it as a required argument. +- The console does not display a command's own interactive questions; a command whose input is not declared for the console is out of scope for this work. diff --git a/specs/001-console-tui/tasks.md b/specs/001-console-tui/tasks.md index abc0583..c4df5c4 100644 --- a/specs/001-console-tui/tasks.md +++ b/specs/001-console-tui/tasks.md @@ -114,11 +114,57 @@ - [ ] T027 [P] Update `README.md` with badges and usage - [ ] T028 Run `quickstart.md` validation end-to-end +## Phase 8: Command input machinery (issue #31) + +**Goal**: a wrapped command can be driven to completion from the menu — executed from any field, +validated before it runs, with what is required visible up front and its help text on screen. + +**Independent Test**: drive `dev:mode` (the reported failure) and +`servicemanager:generate-deps-for-config-factory` (3 fields, 2 required) through the menu. + +**Why this phase exists**: the machinery had never been exercised against a multi-field wrapped +command. `acl:init-db` (1 field) and `user:init-db` (6, filled in order) hid Findings 1 and 2; +`dev:mode`'s flag in the middle of its list is where the habit broke. Both findings affect every +command driven through the menu, not only `dev:mode`. + +**Scope note**: the console does not display a wrapped command's own interactive questions. That +was evaluated and is deliberately out of scope — see `plan.md`, "Out of scope: a command's own +interactive questions". + +### Tests for Phase 8 + +- [ ] T029 [P] [US3] Unit test execution from any field in `test/unit/Prompt/PromptKeyActionTest.php` — Enter on a middle field with every required field filled executes, and Enter no longer advances the active index +- [ ] T030 [P] [US3] Unit test the refusal path — a blank required field sets `PromptState::$refused`, moves the active index to the first blank required field, executes nothing, and leaves entered values intact +- [ ] T031 [P] [US3] Unit test the status row in `test/unit/Prompt/CommandInputPrompterTest.php` — the active field's description renders at `y + count` even when the field holds a value seeded from a default, a refusal report takes precedence, and the description is no longer passed as the placeholder +- [ ] T032 [P] [US3] Unit test the required-field report — blank required fields are named in declaration order, a blank optional field is not named, and the report shrinks as values are filled in +- [ ] T033 [P] [US3] Unit test the asterisk marker — a required argument's label carries `*`; an optional argument's and every option's does not + +### Implementation for Phase 8 + +- [ ] T034 [US3] Add `refused` and the missing-required lookup to `PromptState`, and replace `PromptKeyAction::enter()`'s positional advance with the execute-or-refuse step (FR-009/FR-010) +- [ ] T035 [US3] Render the status row at `y + count` in `CommandInputPrompter::render()` and stop passing the description as the placeholder (FR-011) +- [ ] T036 [US3] Mark required arguments with `*` in the field label (FR-012) +- [ ] T037 [US3] Re-word the footer to the new key contract: `Tab/Down: next field Up: previous field Space: toggle checkbox Enter: execute Esc: cancel` +- [ ] T038 [US3] Integration test: a multi-field command is driven through the prompter end to end +- [ ] T039 [P] Document the prompt key contract, the asterisk marker and the requiredness rule in `docs/v1/` + +### Cross-repository work — webware-usermanager (separate PR) + +- [ ] T040 [US3] Declare `user:init-db`'s `first-name`, `last-name`, `email` and `password` as `InputArgument::REQUIRED` and move its prompting into `interact()`, so the console can mark and validate them; `--role` keeps its `developer` default and `--drop` stays a flag +- [ ] T041 [US3] Cover `interact()` — arguments filled when absent and left alone when supplied — and confirm `bin/webware user:init-db` still prompts when run with no arguments + +### Verification for Phase 8 + +- [ ] T042 Walk the menu against `dev:mode` (the reported failure), `servicemanager:generate-deps-for-config-factory` in a scratch project (3 fields, 2 required, writes files), and `mezzio:routes:list` for the help text on defaulted fields +- [ ] T043 Run `mago format`/`lint`/`analyze`/`guard` and `composer test` + `composer test-integration`, closing coverage to 100% line + mutation + ## Dependencies & Execution Order ### Phase Dependencies - Setup → Foundational → User Stories (P1→P2→P3) → Polish. +- Phase 8 (input machinery) follows US3 and is independent of US2 and US4; it depends only on the + prompt machinery US3 introduced. ### User Story Dependencies @@ -156,5 +202,10 @@ US1 → US2 (help) → US3 (run) → US4 (discovery) → Polish. - Generic CLI host with zero migration knowledge; webware-migration depends on this package (one-way: migration → console). - Discovery goes through the `ConsoleInterface::class` config key; `CommandLoaderFactory` merges `config['laminas-cli']['commands']` (mezzio-tooling's key) into a lazy `ContainerCommandLoader`. - The console presents/invokes commands; it does not reimplement command logic. -- Commit after each task or group; squash-merge PRs to `0.1.x`. +- T029–T043 were appended 2026-09-25 for issue #31; no completed task (T001–T026) was rewritten. +- Requiredness is read from the command's own definition and is declarable on arguments only, so the + form marks required fields with `*` — see `plan.md`, "Design Decisions — command input machinery". +- T040/T041 land in **webware-usermanager**, not this repository. +- New and touched code uses `match` for conditional dispatch rather than chained `if` statements. +- Commit after each task or group; squash-merge PRs to `1.0.x`. - Commit author MUST be `Joey Smith `.