feat(setup): guide users by connection source

[mohanagy]

Part of #204.

Summary

• starts bare interactive setup with plain-language source choices: known connector or pinned package, remote HTTPS endpoint, local executable, browser sign-in, or an existing client entry
• maps each choice onto the existing hardened configuration path; it does not add a second writer or broaden authentication behavior
• gives the local Console the same choices and safe transitions to its existing forms
• documents the flow and records it under Unreleased

Safety boundaries

• generic remote setup remains authentication-free and does not call the endpoint
• local setup remains a no-shell argument array and does not run the executable
• browser sign-in retains its endpoint-first supported OAuth discovery
• importing still requires a selected explicit client entry and never changes client settings

TDD and validation

• added the focused CLI remote-choice test before implementation; it initially failed because bare remote was rejected
• added the Console source-choice contract before implementation; it initially failed because the selector did not exist
• added the README contract before documentation changes; it initially failed on the old guided wording
• npm run lint
• npm run typecheck
• npm run build
• npm run smoke:cli
• npm run check:pack
• npm run test:package
• npm run test:core
• npm test
• npm run test:coverage

Summary by CodeRabbit

• New Features

  • Added an outcome-first setup chooser for the interactive CLI and Console.
  • Choose from connector, remote HTTPS, local executable, browser sign-in, or importing an existing client entry.
  • Improved guidance for generic remote setup, browser authentication, and optional verification.

• Documentation

  • Updated README and CLI help with the new setup options, import requirements, validation rules, and network-free initialization behavior.

[coderabbitai]

📝 Walkthrough

Walkthrough

Interactive CLI and Console setup now present outcome-first source choices for connectors, remote endpoints, local executables, browser sign-in, and client-entry import. CLI routing, Console controls, documentation, and tests were updated accordingly.

Changes

Setup source selection

Layer / File(s)	Summary
CLI guided source routing src/cli/setup.ts, tests/setup-command.test.ts, README.md, docs/cli.md, CHANGELOG.md	The guided CLI accepts expanded source choices, maps remote and local selections to presets, updates generic-remote guidance, and validates the revised prompt and import flows.
Console source chooser and validation src/console/console-assets.ts, tests/console-server.test.ts, tests/readme-product-contract.test.ts	The Console adds source-choice controls and routing for connector, remote, local, browser sign-in, and import, with tests for rendered metadata and remote selection behavior.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related PRs

• mohanagy/miftah#215: Adds the client-entry import flow that this setup chooser routes into.
• mohanagy/miftah#220: Overlaps in CLI guided setup flow selection and native OAuth handling.
• mohanagy/miftah#254: Overlaps in browser sign-in setup across the CLI and Console.

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant SetupChooser
  participant SetupFlow
  User->>SetupChooser: select a setup source
  SetupChooser->>SetupFlow: route connector, remote, local, sign-in, or import
  SetupFlow-->>User: show the selected onboarding form or status

Loading

Poem

A rabbit hops through setup’s new door,
Connector, remote, local, and more.
Browser sign-in, import in a row,
The CLI and Console now know where to go.
“Binky!” says Bun, as the source lights glow.

---

Caution

Pre-merge checks failed

Please resolve all errors before merging. Addressing warnings is optional.

• Ignore

❌ Failed checks (1 error)

Check name	Status	Explanation	Resolution
Docstring Coverage	❌ Error	Docstring coverage is 16.67% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	Clear and specific: it summarizes the source-based setup guidance change in the CLI and Console.
Description check	✅ Passed	Mostly complete: it covers summary, safety boundaries, and validation, though it lacks an explicit Security impact section and concrete command results.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/204-source-first-setup

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 4

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/cli.md`:
- Around line 76-82: Update the `miftah setup [name]` summary-table cell to
describe the current five-way guided choice: `connector`, `remote`, `local`,
`browser sign-in`, or `import`, replacing the stale `new`/`import` wording. Keep
the detailed setup behavior and surrounding table content unchanged.

In `@src/cli/setup.ts`:
- Around line 109-132: Update the answer matching in the setup prompt flow to
accept “local executable” as an alias alongside the existing local options.
Modify the conditional that returns “local” while preserving all current aliases
and behavior.

In `@src/console/console-assets.ts`:
- Around line 90-100: Update the single-select setup-source control around the
“setup-source-choice” fieldset to use radiogroup semantics: expose the group as
a radiogroup and each mutually exclusive option as a radio, preserving the
existing labels, selected state, and source-selection behavior.

In `@tests/setup-command.test.ts`:
- Around line 465-498: The setup command tests cover bare remote selection but
not the equivalent bare local routing. Add a symmetric test for
guidedSourcePrompt selecting “local” that verifies the generated configuration
uses the local-stdio preset and confirms successful setup, following the
existing remote test’s structure and assertions.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 0039489c-117c-4fe3-b896-5109a6745c5e

📥 Commits

Reviewing files that changed from the base of the PR and between b46a8ae and 34ffc30.

📒 Files selected for processing (8)

• CHANGELOG.md
• README.md
• docs/cli.md
• src/cli/setup.ts
• src/console/console-assets.ts
• tests/console-server.test.ts
• tests/readme-product-contract.test.ts
• tests/setup-command.test.ts

[mohanagy]

CodeRabbit is rate-limited on the current head (fab7ced; the PR check reports Review rate limited). Its only changes-requested review targets the prior head 34ffc30; all four actionable threads are resolved with a focused regression test or contract test, and the full local validation suite passed. I also attempted the configured local Claude review fallback, but its CLI did not return a review result within the bounded attempts, so it is not being counted as an approval. Dismissing only the stale CodeRabbit decision under the documented rate-limit exception; current-head CI remains required before merge.

CodeRabbit is rate-limited on current head fab7ced; all four actionable threads are resolved and current-head CI remains required.