feat(setup): guide selected client entry import

[mohanagy]

Summary

• Adds a bare interactive setup choice: new or import.
• Imports exactly one entry from an explicit client configuration file, listing only validated entry names.
• Binds entry selection and conversion to one bounded, verified source snapshot.
• Keeps direct import flags compatible and documents the first-use path.

Security

• Does not scan, modify, launch, or trust the source client configuration.
• Does not print source command, argument, header, environment, or credential values.
• Retains strict imported-entry grammar and existing exclusive output publication.

Validation

• Focused setup/import and README contract tests: 161 passed, 1 skipped.
• Core suite: 415 passed, 22 skipped.
• Full serial coverage suite: 1626 passed, 27 skipped, thresholds satisfied.
• typecheck, lint, build, smoke CLI, package contract, and pack check passed.
• Local Claude Fable review completed with no remaining findings.

Summary by CodeRabbit

• New Features

  • Added a guided miftah setup experience for choosing between creating a new configuration or importing an existing MCP client entry.
  • Added interactive selection of imported entries by name or list position.
  • Added cancellation handling for EOF and Ctrl-C before any configuration is written.

• Security & Privacy

  • Import flows avoid displaying commands, arguments, headers, environment values, or credentials.
  • Existing client configuration files are not modified.

• Documentation

  • Expanded setup and import guidance, validation rules, verification behavior, and supported entry formats.

[coderabbitai]

Warning

Review limit reached

You’ve reached a temporary PR review limit under our Fair Usage Limits Policy.

Your recent review volume is higher than typical usage, so adaptive limits are currently applied.

Next review available in: 35 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: a8e189c4-504d-41df-9173-d5af2900f2de

📥 Commits

Reviewing files that changed from the base of the PR and between e0bef10 and 2623654.

📒 Files selected for processing (6)

• README.md
• docs/cli.md
• src/cli/setup.ts
• tests/preset-docs-contract.test.ts
• tests/readme-product-contract.test.ts
• tests/setup-command.test.ts

📝 Walkthrough

Walkthrough

Interactive miftah setup now offers a TTY-only new or import choice. Guided imports read one client configuration, display entry names, preserve the selected document snapshot, and publish a validated configuration without modifying or exposing source details. Documentation and tests describe and verify the flow.

Changes

Guided setup import

Layer / File(s)	Summary
Interactive import runtime src/cli/setup.ts, src/cli/setup-client-entry-import.ts	Adds interactive prompting, cancellation handling, entry selection, guided import orchestration, and document-passing into configuration publishing.
Guided flow validation tests/setup-command.test.ts, tests/readme-product-contract.test.ts	Tests new-path compatibility, numeric and named entry selection, snapshot preservation, secret omission, invalid selections, and EOF/SIGINT cancellation.
Setup documentation contract README.md, docs/cli.md, CHANGELOG.md	Documents the new-or-import wizard, no-secret import behavior, source-file protections, and updated setup constraints.

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

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant SetupCommand
  participant GuidedImport
  participant ClientConfig
  participant ImportedConfig
  User->>SetupCommand: choose import
  SetupCommand->>GuidedImport: start guided import
  GuidedImport->>ClientConfig: read and inspect entries
  User->>GuidedImport: select entry and provide setup values
  GuidedImport->>ImportedConfig: publish selected document snapshot

Loading

Possibly related PRs

• mohanagy/miftah#215 — Introduced the initial selected local MCP entry import pipeline extended by this guided flow.
• mohanagy/miftah#220 — Added related guided setup gating in runSetupCommand.
• mohanagy/miftah#240 — Expanded the credential-free remote entry import pipeline used by this setup flow.

Poem

A bunny hops through setup’s door,
“New or import?” asks once more.
Names appear, secrets stay dim,
Snapshots safely follow him.
No source file gets a change—
Click, hop, configure, arrange!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title is concise and accurately reflects the main change: guided selection for client entry import in setup.
Description check	✅ Passed	The PR description covers summary, security, and validation, and is mostly complete despite minor template/format differences.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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 unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/204-next-onboarding

---

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

[coderabbitai]

Actionable comments posted: 3

🤖 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`:
- Line 27: Add the --native-oauth flag to the documented options for miftah
setup, ensuring the command-reference row matches the existing setup
instructions that invoke this flag. If setup does not support native OAuth,
remove those instructions instead.

In `@README.md`:
- Line 66: Update the setup description’s client JSON wording to make clear that
the optional snippet is printed for review as output, not collected from the
user as input; preserve the surrounding setup flow and optional behavior.

In `@src/cli/setup.ts`:
- Around line 53-82: Update the prompt method in createInteractivePromptSession
to prioritize the cancellation promise over line.question in the Promise.race,
ensuring an already-cancelled session throws CliUsageError rather than exposing
a readline rejection. Add a regression test covering cancellation between
prompts.

🪄 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: d208635a-7b5d-45ed-bd02-0ec94c5ac50f

📥 Commits

Reviewing files that changed from the base of the PR and between 4f0f0f2 and e0bef10.

📒 Files selected for processing (7)

• CHANGELOG.md
• README.md
• docs/cli.md
• src/cli/setup-client-entry-import.ts
• src/cli/setup.ts
• tests/readme-product-contract.test.ts
• tests/setup-command.test.ts