feat(setup): add truthful completion handoff

[mohanagy]

Closes no issue; this is a focused implementation slice for #204.

What changed

• adds one shared, non-secret completion model for CLI and Console first-run setup
• tells users only whether a provider-declared safe check was unavailable, available, skipped, completed, incomplete, or waiting for browser authorization
• gives a concrete manual client-adoption next step without touching any client settings
• preserves the no-generic-probe, no-token-cache, and no-client-write boundaries
• keeps the new response fields optional at public TypeScript interface boundaries for compatibility

Validation

• npm test
• npm run test:core
• npm run test:coverage
• npm run lint
• npm run typecheck
• npm run build
• npm run smoke:cli
• npm run check:pack
• npm run test:package
• focused setup/Console/docs suite: 173 passed, 1 skipped

Independent review note: Claude ultrareview was unavailable because this account has exhausted its free review quota. A read-only local Claude Code review command was run; it emitted no findings.

Summary by CodeRabbit

• New Features

  • Added a “Finish setup” summary to the console and CLI.
  • Setup now reports verification status, generated client details, and next steps.
  • Added guidance to review and merge generated client JSON, then restart or reconnect.
  • Added follow-up commands for checking configuration and connection readiness.

• Documentation

  • Updated the README and CLI documentation with setup completion behavior and troubleshooting guidance.

[coderabbitai]

📝 Walkthrough

Walkthrough

Setup completion states are standardized for CLI and console onboarding. The changes report verification results, client handoff status, configuration paths, and follow-up actions, with updated UI rendering, tests, and documentation.

Changes

Setup completion

Layer / File(s)	Summary
Completion contracts and result metadata src/setup/setup-completion.ts, src/cli/init.ts, src/cli/setup-client-entry-import.ts	Defines verification and client handoff states, formats completion messages, and propagates handoff status through initialization results.
CLI completion output src/cli/setup.ts, src/cli/setup-native-oauth.ts	Writes standardized completion output for readiness, OAuth, imported entries, skipped checks, and incomplete setup paths.
Console onboarding completion src/console/console-application-service.ts, src/console/console-dashboard-application-service.ts, src/console/console-assets.ts	Returns completion metadata from onboarding APIs and renders verification, next-action, and client handoff messages in the dashboard.
Completion validation and documentation tests/*, README.md, docs/cli.md	Adds coverage for completion states, onboarding responses, CLI transcripts, dashboard content, and post-setup guidance.

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

Sequence Diagram(s)

sequenceDiagram
  participant SetupCommand
  participant CompletionBuilder as createSetupCompletion
  participant Output as CLI or Console output
  participant Operator
  SetupCommand->>CompletionBuilder: Provide verification and client handoff states
  CompletionBuilder-->>SetupCommand: Return completion messages and next action
  SetupCommand->>Output: Render completion handoff
  Output-->>Operator: Show verification status and client adoption steps

Loading

Possibly related issues

• [Onboarding] Build a shared CLI and Console MCP setup wizard #204 — Covers the shared CLI/Console setup wizard that this PR extends with standardized completion and handoff reporting.

Possibly related PRs

• mohanagy/miftah#213 — Adds the profile readiness machinery used by the new completion verification states.
• mohanagy/miftah#215 — Introduces the client-entry import path extended here with handoff metadata.
• mohanagy/miftah#220 — Provides the native OAuth setup flow now emitting completion messaging.

Poem

A rabbit hops through setup’s door,
“Your checks ran—or maybe not before.”
Client JSON waits for a careful merge,
Then restart the path where connections surge.
With clear handoff notes in view,
The burrow knows what next to do.

---

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 27.27% 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	The title is concise and accurately summarizes the main change: adding a truthful setup completion handoff.
Description check	✅ Passed	The description covers Summary and Validation well, but it lacks the template's explicit Security impact section.
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-first-success-handoff

---

_{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 `@README.md`:
- Line 68: Document authorization-pending as an additional setup completion
outcome: update README.md lines 68-68 and docs/cli.md lines 84-86 to mention
browser authorization may still be outstanding, and update
tests/readme-product-contract.test.ts lines 63-64 to assert both documents
retain this outcome; also update line 90 as needed for the same contract.

In `@src/console/console-assets.ts`:
- Around line 89-93: Update the setup completion markup containing
setup-completion-verification, setup-completion-next-action, and
setup-completion-handoff to announce dynamically revealed completion
instructions to assistive technologies. Add a polite atomic live region or move
focus to the completion heading, while preserving the existing refresh feedback
behavior.

In `@src/setup/setup-completion.ts`:
- Around line 38-40: Update displayConfigPath and the generated command
construction to serialize both configPath and profile using platform-aware shell
argument quoting, rather than only escaping double quotes. Ensure paths
containing whitespace, dollar expansions, command substitutions, or other shell
metacharacters remain literal and safe when users paste the command.

In `@tests/setup-completion.test.ts`:
- Around line 4-84: Extend the “setup completion” tests for the remaining
verification states by adding exact createSetupCompletion assertions for
verification “complete” and CLI “incomplete”. For “incomplete”, assert the
expected retest action and message, while preserving the existing clientHandoff
contract; use representative config/profile inputs as needed.

🪄 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: b23ab027-31d5-4323-95df-092692283232

📥 Commits

Reviewing files that changed from the base of the PR and between dde7472 and 82f6e59.

📒 Files selected for processing (15)

• README.md
• docs/cli.md
• src/cli/init.ts
• src/cli/setup-client-entry-import.ts
• src/cli/setup-native-oauth.ts
• src/cli/setup.ts
• src/console/console-application-service.ts
• src/console/console-assets.ts
• src/console/console-dashboard-application-service.ts
• src/setup/setup-completion.ts
• tests/console-application-service.test.ts
• tests/console-server.test.ts
• tests/readme-product-contract.test.ts
• tests/setup-command.test.ts
• tests/setup-completion.test.ts

Dismissing the stale CodeRabbit changes request because its fresh review run on c338938 is explicitly rate limited. All four actionable threads were fixed in c338938, replied to with validation evidence, and resolved. Full local validation passed again; current-head CI remains required before merge.