Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .github/instructions/memory.instructions.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
17 changes: 16 additions & 1 deletion specs/001-console-tui/contracts/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
2 changes: 2 additions & 0 deletions specs/001-console-tui/contracts/command.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
36 changes: 36 additions & 0 deletions specs/001-console-tui/data-model.md
Original file line number Diff line number Diff line change
Expand Up @@ -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<PromptField>.
- `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

Expand All @@ -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.
140 changes: 139 additions & 1 deletion specs/001-console-tui/plan.md
Original file line number Diff line number Diff line change
Expand Up @@ -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: <value>
…
y + count - 1 > field n-1: <value>
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: <value>
class: <value>
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)
Expand All @@ -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
Expand Down
18 changes: 18 additions & 0 deletions specs/001-console-tui/quickstart.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Loading
Loading