[PR #306] [MERGED] feat(cli): improve setup onboarding #1942

New issue

Closed

opened 2026-10-16 21:12:43 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-16 21:12:43 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/306
Author: @morluto
Created: 7/18/2026
Status: ✅ Merged
Merged: 7/18/2026
Merged by: @morluto

Base: main ← Head: codex/improve-cli-onboarding

📝 Commits (1)

16002ff feat(cli): improve setup onboarding

📊 Changes

70 files changed (+2043 additions, -228 deletions)

View changed files

📝 README.md (+22 -1)
📝 docs/api/assets/hierarchy.js (+1 -1)
📝 docs/api/assets/navigation.js (+1 -1)
📝 docs/api/assets/search.js (+1 -1)
📝 docs/api/classes/application_PermissionAuthority.PermissionPathError.html (+1 -1)
📝 docs/api/classes/application_ProcessCaptureError.ProcessCaptureError.html (+1 -1)
📝 docs/api/classes/application_ProjectPermissionStore.ProjectPermissionStoreError.html (+1 -1)
📝 docs/api/functions/application_Doctor.systemDoctorHost.html (+1 -1)
📝 docs/api/functions/application_LinuxHopper.installLinuxHopper.html (+1 -1)
📝 docs/api/functions/application_LinuxHopper.linuxHopperBinarySupported.html (+1 -1)
➕ docs/api/functions/application_LinuxHopper.linuxHopperInstallDisclosure.html (+45 -0)
📝 docs/api/functions/application_LinuxHopper.linuxHopperLauncherPath.html (+1 -1)
📝 docs/api/functions/application_LinuxHopper.linuxPackageManagerCommands.html (+1 -1)
📝 docs/api/functions/application_LinuxHopper.linuxSharedLibrariesAvailable.html (+1 -1)
📝 docs/api/functions/application_LinuxHopper.parseLinuxDistribution.html (+1 -1)
📝 docs/api/functions/application_LinuxHopper.readLinuxDistribution.html (+1 -1)
📝 docs/api/functions/application_MacHopper.installMacHopper.html (+1 -1)
📝 docs/api/functions/application_Setup.configureJsonClient.html (+1 -1)
📝 docs/api/functions/application_Setup.configureTomlClient.html (+1 -1)
📝 docs/api/functions/application_Setup.detectClients.html (+1 -1)

...and 50 more files

📄 Description

Summary

This replaces REA's flat setup confirmation with a value-first, scroll-preserving onboarding journey inspired by PostHog Wizard's interaction grammar while retaining REA's stronger preflight and consent boundaries.

Interactive setup now:

explains what REA enables before discussing installer mechanics;
summarizes detected clients and labels actions as MCP, provider, or skill;
offers recommended, customize, and no-thanks paths;
shows durable keyboard help and append-only operation progress;
converges every selected path on an exact default-No preflight; and
finishes with verified capabilities, restart guidance, and a suggested first investigation prompt.

Problem and user impact

The previous setup path printed a mutation plan and asked one broad Continue? [Y/n] question. It did not communicate value before configuration details, expose a first-class customization path, distinguish setup modalities, or give users durable keyboard guidance. Completion was centered on attempted setup rather than the capabilities that doctor actually verified.

The application boundary also discovered some unsafe configuration state too late. A malformed or dangling client configuration could be reported during execution after another independent action had already mutated the system. Explicit unattended scope could inherit omitted capabilities, and installing Hopper could change the desired client environment after consent without representing that client update in the original plan.

Implementation

The new cliSetup adapter owns Clack rendering and cancellation while application code continues to own discovery, planning, action selection, execution, and progress events. @clack/prompts is pinned at 1.7.0; its types do not cross into the application layer.

Setup actions now carry stable IDs, operation type, target path, backup path, network origins, commands, and integrity evidence. Existing client configuration is inspected before approval, and malformed or unsafe state blocks the whole transaction before Hopper installation, skill installation, or unrelated client writes. The plan selected by the interactive adapter is the plan executed by the application.

Automation remains available through Incur and structured output:

rea setup --client codex --client cursor --skill=false --dry-run
rea setup --yes --all-detected --install-hopper --json

Explicit scope now admits only the requested clients, skill, and provider actions. Legacy unscoped rea setup --yes behavior remains compatible for this release but emits a deprecation warning. JSON, dry-run, agent, piped, and non-TTY paths do not initialize the prompt renderer.

The implementation also avoids unnecessary Homebrew probing when an earlier configured or manual Hopper launcher is already valid. Install disclosures for macOS and Linux are generated from the same release and command definitions used by execution.

Verification

npm run check
- typecheck, lint, formatting, generated-document freshness, and tests passed;
- 161 test files passed;
- 1,084 tests passed.
npm run verify:package
- verified the packed CLI and MCP lifecycle;
- verified read-only setup planning, exact explicit scope, backup/readback recovery, malformed-config blocking, unsafe-symlink refusal, and repeat setup.
Real PTY coverage exercises the value introduction, modality labels, durable keys, recommended/custom/no-thanks paths, Ctrl-C, default-No final consent, and capability-framed completion.

Real Hopper and Ghidra verification were not run because this change does not modify provider analysis protocols, target semantics, or provider lifecycle behavior.

Generated artifacts

The TypeDoc output was regenerated from the changed exported setup and installer-disclosure contracts. No MCP tool schema or catalog identity changed.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/morluto/rea/pull/306 **Author:** [@morluto](https://github.com/morluto) **Created:** 7/18/2026 **Status:** ✅ Merged **Merged:** 7/18/2026 **Merged by:** [@morluto](https://github.com/morluto) **Base:** `main` ← **Head:** `codex/improve-cli-onboarding` --- ### 📝 Commits (1) - [`16002ff`](https://github.com/morluto/rea/commit/16002ff3c216ecd91e9c28bab8de288f3b553e57) feat(cli): improve setup onboarding ### 📊 Changes **70 files changed** (+2043 additions, -228 deletions) <details> <summary>View changed files</summary> 📝 `README.md` (+22 -1) 📝 `docs/api/assets/hierarchy.js` (+1 -1) 📝 `docs/api/assets/navigation.js` (+1 -1) 📝 `docs/api/assets/search.js` (+1 -1) 📝 `docs/api/classes/application_PermissionAuthority.PermissionPathError.html` (+1 -1) 📝 `docs/api/classes/application_ProcessCaptureError.ProcessCaptureError.html` (+1 -1) 📝 `docs/api/classes/application_ProjectPermissionStore.ProjectPermissionStoreError.html` (+1 -1) 📝 `docs/api/functions/application_Doctor.systemDoctorHost.html` (+1 -1) 📝 `docs/api/functions/application_LinuxHopper.installLinuxHopper.html` (+1 -1) 📝 `docs/api/functions/application_LinuxHopper.linuxHopperBinarySupported.html` (+1 -1) ➕ `docs/api/functions/application_LinuxHopper.linuxHopperInstallDisclosure.html` (+45 -0) 📝 `docs/api/functions/application_LinuxHopper.linuxHopperLauncherPath.html` (+1 -1) 📝 `docs/api/functions/application_LinuxHopper.linuxPackageManagerCommands.html` (+1 -1) 📝 `docs/api/functions/application_LinuxHopper.linuxSharedLibrariesAvailable.html` (+1 -1) 📝 `docs/api/functions/application_LinuxHopper.parseLinuxDistribution.html` (+1 -1) 📝 `docs/api/functions/application_LinuxHopper.readLinuxDistribution.html` (+1 -1) 📝 `docs/api/functions/application_MacHopper.installMacHopper.html` (+1 -1) 📝 `docs/api/functions/application_Setup.configureJsonClient.html` (+1 -1) 📝 `docs/api/functions/application_Setup.configureTomlClient.html` (+1 -1) 📝 `docs/api/functions/application_Setup.detectClients.html` (+1 -1) _...and 50 more files_ </details> ### 📄 Description ## Summary This replaces REA's flat setup confirmation with a value-first, scroll-preserving onboarding journey inspired by PostHog Wizard's interaction grammar while retaining REA's stronger preflight and consent boundaries. Interactive setup now: - explains what REA enables before discussing installer mechanics; - summarizes detected clients and labels actions as MCP, provider, or skill; - offers recommended, customize, and no-thanks paths; - shows durable keyboard help and append-only operation progress; - converges every selected path on an exact default-No preflight; and - finishes with verified capabilities, restart guidance, and a suggested first investigation prompt. ## Problem and user impact The previous setup path printed a mutation plan and asked one broad `Continue? [Y/n]` question. It did not communicate value before configuration details, expose a first-class customization path, distinguish setup modalities, or give users durable keyboard guidance. Completion was centered on attempted setup rather than the capabilities that doctor actually verified. The application boundary also discovered some unsafe configuration state too late. A malformed or dangling client configuration could be reported during execution after another independent action had already mutated the system. Explicit unattended scope could inherit omitted capabilities, and installing Hopper could change the desired client environment after consent without representing that client update in the original plan. ## Implementation The new `cliSetup` adapter owns Clack rendering and cancellation while application code continues to own discovery, planning, action selection, execution, and progress events. `@clack/prompts` is pinned at `1.7.0`; its types do not cross into the application layer. Setup actions now carry stable IDs, operation type, target path, backup path, network origins, commands, and integrity evidence. Existing client configuration is inspected before approval, and malformed or unsafe state blocks the whole transaction before Hopper installation, skill installation, or unrelated client writes. The plan selected by the interactive adapter is the plan executed by the application. Automation remains available through Incur and structured output: ```text rea setup --client codex --client cursor --skill=false --dry-run rea setup --yes --all-detected --install-hopper --json ``` Explicit scope now admits only the requested clients, skill, and provider actions. Legacy unscoped `rea setup --yes` behavior remains compatible for this release but emits a deprecation warning. JSON, dry-run, agent, piped, and non-TTY paths do not initialize the prompt renderer. The implementation also avoids unnecessary Homebrew probing when an earlier configured or manual Hopper launcher is already valid. Install disclosures for macOS and Linux are generated from the same release and command definitions used by execution. ## Verification - `npm run check` - typecheck, lint, formatting, generated-document freshness, and tests passed; - 161 test files passed; - 1,084 tests passed. - `npm run verify:package` - verified the packed CLI and MCP lifecycle; - verified read-only setup planning, exact explicit scope, backup/readback recovery, malformed-config blocking, unsafe-symlink refusal, and repeat setup. - Real PTY coverage exercises the value introduction, modality labels, durable keys, recommended/custom/no-thanks paths, Ctrl-C, default-No final consent, and capability-framed completion. Real Hopper and Ghidra verification were not run because this change does not modify provider analysis protocols, target semantics, or provider lifecycle behavior. ## Generated artifacts The TypeDoc output was regenerated from the changed exported setup and installer-disclosure contracts. No MCP tool schema or catalog identity changed. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-16 21:12:43 +00:00