Repository navigation
docs(spec): specify the console input machinery (issue #31) - #32
Merged
Merged
Conversation
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 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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
The spec-kit artifact pass for #31, produced through the
/speckit-clarifyand/speckit-planworkflows. 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
dev:mode(3 flags,disablein the middle — the reported failure),generate-template-map,servicemanager:generate-deps-for-config-factory, and every mezzio-tooling command with more than one field'', which Symfony accepts as suppliedTextInput::placeholder(), which draws only when the value is emptymezzio:routes:list(6 options, all with defaults) is the worst case; flag fields never show a description at allResolution:
Enterexecutes 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
InputOptionhas no required concept; onlyInputArgumentcarriesREQUIRED/OPTIONAL. So the console reads requiredness from$argument->isRequired()and from nowhere else, and marks those fields with*. That is whymezzio:handler:createcan be marked anduser:init-dbcannot: the latter declares its four mandatory values as optional options and asks for them insideexecute(), so the requirement lives in control flow where nothing outside the class can see it.user:init-dbis fixed in webware-usermanager (separate PR): declare the four asREQUIREDarguments and move the prompting intointeract(), whichCommand::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, theuser:init-dbcross-repo change, why console-side prompting is out of scope, and thematch-over-ifimplementation convention.research.md—R-008–R-010plus the rewrittenR-011(how a command declares a required value) andR-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 asT029–T043.T001–T026untouched,T027/T028still open..github/instructions/memory.instructions.md— thematchconvention recorded beside the named-parameters rule.Removed from the earlier revision of this PR
FR-013, the A1/A2/B prompting mechanism fork,MirroringOutput, theCommandRunnerchange, and theuser:init-db"proof case" framing. Also corrected:data-model.mdpreviously described the missing-required list as stored at refusal, which leaves a staleRequired: configFileon screen after that field is filled.Refs #31