Context
gittensory-miner init today only creates an empty state dir with no guided setup — first-time operators must hand-author their own .env referencing GITHUB_TOKEN and MINER_CODING_AGENT_PROVIDER with no prompts and no validation until a later doctor run (or a failed live attempt). ORB has an analogous guided flow in setup-wizard.ts for GitHub App/OAuth provisioning, but AMS only needs a PAT plus a provider choice, so this wizard should be a lighter-weight, credential-and-provider-only flow, not a port of ORB's OAuth mechanics.
Dependencies
None — independently shippable. It benefits from, but does not require, the .gittensory-miner.env.example issue in this same batch as a reference for which vars to prompt for and write (the var names already exist in shipped code — driver-factory.ts, status.js). It also benefits from, but does not require, the provider-gated doctor issue in this batch, since it reruns whatever doctor currently does either way.
Requirements
- Add an opt-in
--interactive flag to the existing gittensory-miner init command; the default (non-interactive/CI) invocation of init must remain byte-for-byte unchanged.
- When
--interactive is passed, prompt the operator for GITHUB_TOKEN using masked input that is never echoed to stdout/logs, and for MINER_CODING_AGENT_PROVIDER selection from an explicit menu (claude-cli/codex-cli/agent-sdk/noop).
- Based on the selected provider, prompt for any required companion vars (model override, timeout) with sensible defaults offered and skippable.
- Write the collected values to a starter
.env file in the state dir; never print the collected GITHUB_TOKEN value back to the terminal after entry, including in any confirmation/summary screen.
- After writing the
.env file, automatically invoke the existing doctor command and print its result so the operator immediately sees whether the new configuration passes.
- Must not perform any network calls beyond what
doctor already performs today — do not silently add a live GitHub API call as part of this wizard; that capability is deliberately scoped to the separate, explicitly opt-in init --verify-token issue in this batch.
- Must not touch any autonomous-loop control-flow, kill-switch, or governor state — this is purely a config/credential-collection UX wrapper around the existing
init/doctor commands.
Deliverables / Acceptance Criteria
Test Coverage Requirements
This PR must ship with full test coverage for every changed line and branch — the repo's Codecov patch gate requires 99%+ coverage and the house standard is to aim for 100%, including both sides of every conditional/nullish-coalescing branch introduced. Add: (1) unit tests covering the new prompt-handling logic's success and failure paths (valid token entered, provider selected vs. skipped, invalid/empty token re-prompted), (2) an invariant test for "the collected GITHUB_TOKEN value is never written to stdout/logs/process output at any point after entry, including in the final summary," and (3) a regression test asserting non-interactive init behavior is byte-for-byte identical with --interactive omitted, since a wizard silently changing default behavior would itself be a regression class worth guarding against.
Codecov visibility note: packages/gittensory-miner/**, apps/gittensory-miner-ui/**, and apps/gittensory-miner-extension/** currently sit entirely outside vitest's coverage.include glob, so codecov/patch cannot measure changes there yet — closing that gap is exactly what #4864 and #4865 (in this same milestone) do. Any part of this change under packages/gittensory-engine/src/** or the repo's own src/** remains fully Codecov-instrumented as usual. Either way, this does not lower the bar: treat the 100%-including-invariants-and-regression target above as the enforced house standard regardless of what Codecov can currently see, and it becomes gate-enforced for real once #4864/#4865 ship.
Expected Outcome
A first-time operator can run one command, answer a handful of prompts, and end up with a working, doctor-validated .env — without having to hand-read source or docs to discover the required env-var names.
Links & Resources
- packages/gittensory-miner/lib/status.js (existing
doctor implementation)
- packages/gittensory-engine/src/miner/driver-factory.ts (provider resolution)
- Existing repo pattern: ORB's
setup-wizard.ts
- See the
.gittensory-miner.env.example issue in this same batch
- See the opt-in
init --verify-token issue and the provider-gated doctor issue in this same batch
- Theme: Self-host packaging & docs
Context
gittensory-miner inittoday only creates an empty state dir with no guided setup — first-time operators must hand-author their own.envreferencingGITHUB_TOKENandMINER_CODING_AGENT_PROVIDERwith no prompts and no validation until a laterdoctorrun (or a failed live attempt). ORB has an analogous guided flow insetup-wizard.tsfor GitHub App/OAuth provisioning, but AMS only needs a PAT plus a provider choice, so this wizard should be a lighter-weight, credential-and-provider-only flow, not a port of ORB's OAuth mechanics.Dependencies
None — independently shippable. It benefits from, but does not require, the
.gittensory-miner.env.exampleissue in this same batch as a reference for which vars to prompt for and write (the var names already exist in shipped code — driver-factory.ts, status.js). It also benefits from, but does not require, the provider-gateddoctorissue in this batch, since it reruns whateverdoctorcurrently does either way.Requirements
--interactiveflag to the existinggittensory-miner initcommand; the default (non-interactive/CI) invocation ofinitmust remain byte-for-byte unchanged.--interactiveis passed, prompt the operator forGITHUB_TOKENusing masked input that is never echoed to stdout/logs, and forMINER_CODING_AGENT_PROVIDERselection from an explicit menu (claude-cli/codex-cli/agent-sdk/noop)..envfile in the state dir; never print the collectedGITHUB_TOKENvalue back to the terminal after entry, including in any confirmation/summary screen..envfile, automatically invoke the existingdoctorcommand and print its result so the operator immediately sees whether the new configuration passes.doctoralready performs today — do not silently add a live GitHub API call as part of this wizard; that capability is deliberately scoped to the separate, explicitly opt-ininit --verify-tokenissue in this batch.init/doctorcommands.Deliverables / Acceptance Criteria
--interactiveflag added togittensory-miner initGITHUB_TOKEN(masked) andMINER_CODING_AGENT_PROVIDER(menu).envfile written to the state dirdoctorautomatically rerun and its output shown at the end of the wizardinitis unchangedTest Coverage Requirements
This PR must ship with full test coverage for every changed line and branch — the repo's Codecov patch gate requires 99%+ coverage and the house standard is to aim for 100%, including both sides of every conditional/nullish-coalescing branch introduced. Add: (1) unit tests covering the new prompt-handling logic's success and failure paths (valid token entered, provider selected vs. skipped, invalid/empty token re-prompted), (2) an invariant test for "the collected
GITHUB_TOKENvalue is never written to stdout/logs/process output at any point after entry, including in the final summary," and (3) a regression test asserting non-interactiveinitbehavior is byte-for-byte identical with--interactiveomitted, since a wizard silently changing default behavior would itself be a regression class worth guarding against.Codecov visibility note:
packages/gittensory-miner/**,apps/gittensory-miner-ui/**, andapps/gittensory-miner-extension/**currently sit entirely outside vitest'scoverage.includeglob, socodecov/patchcannot measure changes there yet — closing that gap is exactly what #4864 and #4865 (in this same milestone) do. Any part of this change underpackages/gittensory-engine/src/**or the repo's ownsrc/**remains fully Codecov-instrumented as usual. Either way, this does not lower the bar: treat the 100%-including-invariants-and-regression target above as the enforced house standard regardless of what Codecov can currently see, and it becomes gate-enforced for real once #4864/#4865 ship.Expected Outcome
A first-time operator can run one command, answer a handful of prompts, and end up with a working,
doctor-validated.env— without having to hand-read source or docs to discover the required env-var names.Links & Resources
doctorimplementation)setup-wizard.ts.gittensory-miner.env.exampleissue in this same batchinit --verify-tokenissue and the provider-gateddoctorissue in this same batch