Skip to content

Add gittensory-miner init --interactive first-run onboarding wizard #5176

Description

@JSONbored

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

  1. 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.
  2. 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).
  3. Based on the selected provider, prompt for any required companion vars (model override, timeout) with sensible defaults offered and skippable.
  4. 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.
  5. 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.
  6. 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.
  7. 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

  • --interactive flag added to gittensory-miner init
  • Prompts for GITHUB_TOKEN (masked) and MINER_CODING_AGENT_PROVIDER (menu)
  • Provider-specific follow-up prompts with skippable defaults
  • Starter .env file written to the state dir
  • doctor automatically rerun and its output shown at the end of the wizard
  • Non-interactive/CI invocation of init is unchanged
  • No new network calls introduced
  • README/DEPLOYMENT docs updated with a short mention of the new flag

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    gittensor:featureGittensor-scored feature linked to a feature issue — scores a 0.25x multiplier.help wantedExtra attention is needed

    Projects

    Status
    Done

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions