Skip to content

docs(spec): specify the console input machinery (issue #31) - #32

Merged
tyrsson merged 3 commits into
1.0.xfrom
spec/31-input-machinery
Sep 26, 2026
Merged

tyrsson merged 3 commits into
1.0.xfrom
spec/31-input-machinery

Conversation

@tyrsson

@tyrsson tyrsson commented Sep 26, 2026 •

Copy link
Copy Markdown
Member

What

The spec-kit artifact pass for #31, produced through the /speckit-clarify and /speckit-plan workflows. Documentation only — no code changes.

The second commit corrects the first: the console-side prompting design was dropped after review, and requiredness was pinned down properly.

Scope — the three findings that actually block driving a wrapped command

Finding What it breaks
F1 Enter is positional, so it only executes from the last field dev:mode (3 flags, disable in the middle — the reported failure), generate-template-map, servicemanager:generate-deps-for-config-factory, and every mezzio-tooling command with more than one field
F2 a blank required argument is sent as '', which Symfony accepts as supplied every command with a required argument — the command runs and fails deep inside instead of the form naming what is missing
F3 the description is handed to TextInput::placeholder(), which draws only when the value is empty mezzio:routes:list (6 options, all with defaults) is the worst case; flag fields never show a description at all

Resolution: Enter executes from any field, refused while a required field is blank; blank required fields are named on the free row under the fields and focus moves to the first of them; the active field's description moves onto that same row.

Requiredness — the constraint that shapes this

InputOption has no required concept; only InputArgument carries REQUIRED/OPTIONAL. So the console reads requiredness from $argument->isRequired() and from nowhere else, and marks those fields with *. That is why mezzio:handler:create can be marked and user:init-db cannot: the latter declares its four mandatory values as optional options and asks for them inside execute(), so the requirement lives in control flow where nothing outside the class can see it.

user:init-db is fixed in webware-usermanager (separate PR): declare the four as REQUIRED arguments and move the prompting into interact(), which Command::run() calls before validating the definition — so direct CLI use keeps prompting exactly as it does today. The console needs no new machinery for it.

Artifacts

  • spec.md — corrected ## Clarifications; FR-009–FR-012, SC-006/SC-007, revised edge cases, US3 scenarios and assumptions.
  • plan.md — design record: the prompt layout and key contract, validation in the execute path, the asterisk marker, the user:init-db cross-repo change, why console-side prompting is out of scope, and the match-over-if implementation convention.
  • research.md — R-008–R-010 plus the rewritten R-011 (how a command declares a required value) and R-012 (where prompting belongs), each with rejected alternatives.
  • data-model.md — PromptField, PromptState (refused + a lookup derived from current values) and the derived status row.
  • contracts/ — the prompt key contract and the required-input rule.
  • quickstart.md — end-to-end validation steps.
  • tasks.md — Phase 8 as T029–T043. T001–T026 untouched, T027/T028 still open.
  • .github/instructions/memory.instructions.md — the match convention recorded beside the named-parameters rule.

Removed from the earlier revision of this PR

FR-013, the A1/A2/B prompting mechanism fork, MirroringOutput, the CommandRunner change, and the user:init-db "proof case" framing. Also corrected: data-model.md previously described the missing-required list as stored at refusal, which leaves a stale Required: configFile on screen after that field is filled.

Refs #31

Fold the issue #31 decisions into the spec-kit artifacts via the speckit
clarify and plan steps. No code changes.

spec.md — clarifies five decisions and adds FR-009..FR-013, SC-006/SC-007,
four edge cases, four US3 acceptance scenarios and two assumptions. FR-012
is deliberately outcome-based: a wrapped command's questions must be shown
and answerable, without prescribing how they are rendered.

plan.md — the input-machinery design record: the status row at y + count
(the row already free between the last field and the footer), the
Enter/Tab/Space/Escape contract, validation in the submit path, and the
decision to hand a command its terminal back while still capturing output.

research.md — R-008..R-011 for the key contract, validation, help-text
placement and wrapped-command prompting, each with the alternatives
rejected and why.

data-model.md — PromptField, PromptState and the derived status row, plus
the submission and omission rules.

contracts/ — the prompt key contract, and the rule that a wrapped command's
questions are never answered with defaults on the operator's behalf.

quickstart.md — four more end-to-end validation steps.

tasks.md — appends T029..T041 as Phase 8. T001..T026 keep their state and
T027/T028 stay open. Also corrects the stale "squash-merge PRs to 0.1.x"
note to 1.0.x.

Two facts drove the design:
- Application::getDefaultHelperSet() does register QuestionHelper under the
  name "question", but user:init-db constructs its own (InitDbCommand.php:143),
  so helper substitution can never be sufficient on its own.
- a wrapped command's question is invisible today because CommandRunner
  passes a BufferedOutput, not because the terminal is in raw mode —
  Psl\Terminal\Application::run() restores it in its finally block.
@codecov

codecov Bot commented Sep 26, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

Reduce the artifacts to the three findings that actually block driving a
wrapped command, and correct the errors in the previous pass.

Removed — the console-side prompting design: FR-012/FR-013 as written, the
A1/A2/B mechanism fork, MirroringOutput, the CommandRunner change, and the
user:init-db rewrite that was never needed.

Added / corrected:
- requiredness is declarable on arguments only. Symfony's InputOption has no
  required concept, so required fields are read from InputArgument::REQUIRED
  and marked with '*' in the form (FR-012, SC-007).
- required values are expressed in the definition, so user:init-db declares
  first-name/last-name/email/password as REQUIRED arguments and moves its
  prompting into interact(), which runs before the definition is validated
  and so keeps prompting on direct CLI use. That is a separate PR in
  webware-usermanager; the console needs no new machinery for it.
- the missing-required report is computed from the current field values and
  gated on PromptState::$refused, so it shrinks as fields are filled in
  rather than going stale (data-model.md corrected to match).
- 'Enter: execute' throughout, in place of 'next/confirm'.
- new implementation convention: match statements rather than chained ifs,
  recorded in plan.md, tasks.md and .github/instructions/memory.instructions.md
  alongside the named-parameters rule.

tasks.md Phase 8 restated as T029..T043 (26 done / 17 open overall);
T001..T026 untouched, T027/T028 still open.
The example showed a bare option name prefixed with '--' and a 2-space
indent, but the label is built as marker + required-column + space + name,
so an option renders with its bare name at 4 spaces. Recorded the rule
alongside it rather than leaving the example to carry the meaning.
@tyrsson
tyrsson merged commit 7b47c8d into 1.0.x Sep 26, 2026
12 checks passed
@tyrsson
tyrsson deleted the spec/31-input-machinery branch September 26, 2026 04:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant