[PR #577] [MERGED] feat(setup)!: expand agent integrations and verify updates #2078

New issue

Closed

opened 2026-10-16 21:13:59 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-16 21:13:59 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/577
Author: @morluto
Created: 10/5/2026
Status: ✅ Merged
Merged: 10/5/2026
Merged by: @morluto

Base: main ← Head: feat/onboarding-agent-integrations

📝 Commits (2)

da24b41 feat(setup)!: expand agent integrations and simplify onboarding
3647e91 feat(cli)!: replace upgrade with verified updates

📊 Changes

51 files changed (+3931 additions, -1358 deletions)

View changed files

📝 .github/workflows/ci.yml (+2 -0)
📝 README.md (+11 -11)
📝 README_ar.md (+4 -4)
📝 README_ja.md (+4 -4)
📝 README_ko.md (+4 -4)
📝 README_zh.md (+4 -4)
📝 docs/installation.md (+67 -34)
📝 docs/product-catalog.json (+28 -4)
📝 docs/verification/managed-conformance-manifest.json (+2 -2)
📝 docs/windows-ghidra-p0.md (+3 -1)
📝 package-lock.json (+19 -0)
📝 package.json (+3 -0)
📝 scripts/verify-package-discovery.mjs (+6 -3)
📝 scripts/verify-package-setup.mjs (+364 -24)
➕ scripts/verify-package-update.mjs (+180 -0)
📝 scripts/verify-package.mjs (+21 -5)
📝 scripts/verify-published-package.mjs (+56 -23)
📝 scripts/verify-windows-package.mjs (+126 -1)
📝 skills/reverse-engineer-anything/SKILL.md (+1 -1)
📝 src/application/ClientConfigurationDocument.ts (+115 -13)

...and 31 more files

📄 Description

Summary

REA setup now supports all 11 global agent formats in Context7's setup, and rea update installs an exact release into the existing installation and verifies its executable. Integration maintenance is returned as an unapplied plan instead of reopening onboarding.

This implements the requested onboarding audit, client-format expansion, and updater cleanup; there is no dedicated tracking issue.

Problem and expected behavior

Setup previously hid undetected agents, treated detection as intent, and could require a binary-analysis provider for an agent-only integration. Generic JSON registration could not represent OpenCode or VS Code's native MCP layouts. The updater installed a floating version without verifying the resulting executable, then reopened setup for all detected agents.

Any supported agent can now be selected on a fresh machine. Existing REA registrations establish repeat-run defaults; detection supplies context. Setup resolves the selected plan before confirmation and verifies only that scope. Updates resolve and install the same exact release through npm's configured registry and prefix, verify that installation's executable, and plan maintenance only for existing enabled REA registrations and an already installed REA skill.

Change and scope

Add OpenCode, Antigravity, GitHub Copilot CLI, and VS Code, and enable Devin. Implement native registration dialects and platform-aware paths, including environment overrides and existing OpenCode JSONC files.
Preserve JSONC comments, unrelated settings, backups, symlink behavior, and idempotency. Share registration ownership checks between discovery and uninstall.
Present agent selection first, include the guided skill with agent integrations, and offer Hopper separately. Keep approval tied to resolved paths, launchers, environment, and backup effects.
Distinguish cancellation, dry runs, and requests needing confirmation. Require all terminal-owned streams to be TTYs before starting interactive prompts.
Replace the old updater command with rea update only. Refuse unowned installations instead of creating an unrelated global installation. Keep JSON output clean and preserve actual npm and executable diagnostics.
Return the verified version, exact install command, and unapplied maintenance plan. Run the returned scoped setup command to review and approve integration changes; update itself does not write agent configuration.
Expand packaged setup, uninstall, and update checks and regenerate owning documentation and catalog metadata.

Contract and boundary impact

Semantic owner and earliest changed stage: application setup discovery, client configuration parsing, planning, verification, and installation ownership. Terminal components remain in the CLI adapter.
CLI and MCP/tool-catalog contract: setup selection, JSON diagnostics, exit statuses, and update command/results change. Analysis MCP tools are unchanged.
Provider, bridge, target-format, or platform compatibility: provider operations are unchanged. Client paths account for Windows, macOS, and Linux; updater subprocesses use cross-spawn for Windows npm launchers.
Evidence, artifact, provenance, or reconstruction contract: none.
Process execution, authorization, cleanup, or containment impact: agent-only setup no longer requires provider prerequisites. Setup still requires approval for planned writes and optional Hopper installation. Update installs REA and verifies the new entry point; its subsequent setup probe is read-only.
Generated metadata, package, or installation impact: regenerate the product catalog and derived skill/conformance digests. Add pinned jsonc-parser@3.3.1, cross-spawn@7.0.6, and development types @types/cross-spawn@6.0.6. No external runtimes or package managers are installed.

Evidence and regression coverage

Unit and boundary tests exercise registration dialects, malformed selected configs before mutation, ownership, fresh and repeat setup, provider-independent readiness, cancellation, and redirected output.
Update tests cover exact versions, invalid metadata, unknown installations, canonical/custom prefixes, wrong installed versions, complete subprocess output, actual error details, disabled and foreign integrations, and malformed/out-of-scope maintenance plans.
Packaged checks exercise JSONC preservation, backups, symlink lifecycle, recovery, uninstall, real TTY cancellation and restoration, redirected output, and actual npm release lookup/install against a local registry fixture.
The packaged update fixture gives the installed package an older version identity while retaining the new updater code, then installs the unmodified target tarball. It verifies the new executable and proves that integration maintenance leaves configuration untouched.
Compared onboarding against Context7's authoritative client registry and observed ctx7@0.5.13 setup from isolated and checkout contexts, cancelling before mutation. Reviewed Pi's authoritative update implementation for exact-version and verification behavior.
Remaining proof gaps: native Windows execution runs in CI; the Windows package verifier was exercised locally on macOS. Actual agent applications were not launched. The published-release canary has been adapted for this updater but cannot exercise the new implementation until it is published.

Representative invocations:

rea setup --client opencode --client vscode --client copilot_cli --dry-run
rea setup --client opencode --yes
rea setup --all-detected --yes
rea update --json

The interactive flow asks “Which agents should use REA?”, shows detected and configured state, and displays resolved preflight before “Apply these changes?”. Cancellation returns status: "cancelled"; dry runs return status: "planned", both with exit code 0. A successful update returns status: "updated", installedVersion, and maintenance; a planned maintenance result includes its exact command and actions.

Validation performed

npm run check:pr — passed again after rebasing onto the latest main; 345 test files, 1,937 tests passed and 1 skipped, plus static and generated-document checks.
npm run docs:generate — passed.
npm run build:cached, npm run check:fast, and 39 focused update/maintenance tests — passed after the final registry-prefix refinement.
node scripts/verify-package.mjs — passed against the packaged artifact, including setup, real TTY behavior, uninstall, MCP startup, and real npm update/verification.
node scripts/verify-windows-package.mjs — passed on macOS after the final registry-prefix refinement, including OpenCode, VS Code, Copilot, repeat setup, uninstall, and update. This is not a native Windows result; updater tests are also included in the Windows CI lane.
Script syntax, formatting, lint, document-fact, and staged diff checks — passed.

Compatibility, safety, and release

Breaking changes: unscoped setup refreshes only existing REA-owned registrations. Use --all-detected to configure every detected client. Setup JSON exposes a compact doctor summary; rea doctor remains the full diagnostic command. Cancellation and successful dry runs exit 0.
Breaking changes: remove rea upgrade without an alias; use rea update. Successful update results use status: "updated", include the verified installed version and exact command arguments, and return unapplied maintenance instead of opening setup.
Real Hopper/Ghidra and browser verification was not performed; provider runtime behavior is unchanged. Packaged verification ran on macOS arm64; native Windows coverage remains CI.
Configuration changes are additive, backed up, and verified. Uninstall removes only owned REA registrations and preserves other settings. Selected malformed configs block before earlier writes. Failed installed-version verification reports that npm completed and the installation may have changed.

Review checklist

The PR has one focused outcome and a Conventional Commit title.
The reason for no tracking issue is stated above.
Tests cover changed observable behavior and meaningful failure paths.
Owning docs and generated metadata are updated.
Representative CLI behavior is included.
The final diff was checked for secrets, unrelated cleanup, and unsupported claims.

_{🔄 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/577 **Author:** [@morluto](https://github.com/morluto) **Created:** 10/5/2026 **Status:** ✅ Merged **Merged:** 10/5/2026 **Merged by:** [@morluto](https://github.com/morluto) **Base:** `main` ← **Head:** `feat/onboarding-agent-integrations` --- ### 📝 Commits (2) - [`da24b41`](https://github.com/morluto/rea/commit/da24b41cc7b35074405fd2f2a33e2b92a53d1ae3) feat(setup)!: expand agent integrations and simplify onboarding - [`3647e91`](https://github.com/morluto/rea/commit/3647e91c9620e60dfb1141be99b41da7fdaf4924) feat(cli)!: replace upgrade with verified updates ### 📊 Changes **51 files changed** (+3931 additions, -1358 deletions) <details> <summary>View changed files</summary> 📝 `.github/workflows/ci.yml` (+2 -0) 📝 `README.md` (+11 -11) 📝 `README_ar.md` (+4 -4) 📝 `README_ja.md` (+4 -4) 📝 `README_ko.md` (+4 -4) 📝 `README_zh.md` (+4 -4) 📝 `docs/installation.md` (+67 -34) 📝 `docs/product-catalog.json` (+28 -4) 📝 `docs/verification/managed-conformance-manifest.json` (+2 -2) 📝 `docs/windows-ghidra-p0.md` (+3 -1) 📝 `package-lock.json` (+19 -0) 📝 `package.json` (+3 -0) 📝 `scripts/verify-package-discovery.mjs` (+6 -3) 📝 `scripts/verify-package-setup.mjs` (+364 -24) ➕ `scripts/verify-package-update.mjs` (+180 -0) 📝 `scripts/verify-package.mjs` (+21 -5) 📝 `scripts/verify-published-package.mjs` (+56 -23) 📝 `scripts/verify-windows-package.mjs` (+126 -1) 📝 `skills/reverse-engineer-anything/SKILL.md` (+1 -1) 📝 `src/application/ClientConfigurationDocument.ts` (+115 -13) _...and 31 more files_ </details> ### 📄 Description ## Summary REA setup now supports all 11 global agent formats in Context7's setup, and `rea update` installs an exact release into the existing installation and verifies its executable. Integration maintenance is returned as an unapplied plan instead of reopening onboarding. This implements the requested onboarding audit, client-format expansion, and updater cleanup; there is no dedicated tracking issue. ## Problem and expected behavior Setup previously hid undetected agents, treated detection as intent, and could require a binary-analysis provider for an agent-only integration. Generic JSON registration could not represent OpenCode or VS Code's native MCP layouts. The updater installed a floating version without verifying the resulting executable, then reopened setup for all detected agents. Any supported agent can now be selected on a fresh machine. Existing REA registrations establish repeat-run defaults; detection supplies context. Setup resolves the selected plan before confirmation and verifies only that scope. Updates resolve and install the same exact release through npm's configured registry and prefix, verify that installation's executable, and plan maintenance only for existing enabled REA registrations and an already installed REA skill. ## Change and scope - Add OpenCode, Antigravity, GitHub Copilot CLI, and VS Code, and enable Devin. Implement native registration dialects and platform-aware paths, including environment overrides and existing OpenCode JSONC files. - Preserve JSONC comments, unrelated settings, backups, symlink behavior, and idempotency. Share registration ownership checks between discovery and uninstall. - Present agent selection first, include the guided skill with agent integrations, and offer Hopper separately. Keep approval tied to resolved paths, launchers, environment, and backup effects. - Distinguish cancellation, dry runs, and requests needing confirmation. Require all terminal-owned streams to be TTYs before starting interactive prompts. - Replace the old updater command with `rea update` only. Refuse unowned installations instead of creating an unrelated global installation. Keep JSON output clean and preserve actual npm and executable diagnostics. - Return the verified version, exact install command, and unapplied maintenance plan. Run the returned scoped setup command to review and approve integration changes; update itself does not write agent configuration. - Expand packaged setup, uninstall, and update checks and regenerate owning documentation and catalog metadata. ## Contract and boundary impact - Semantic owner and earliest changed stage: application setup discovery, client configuration parsing, planning, verification, and installation ownership. Terminal components remain in the CLI adapter. - CLI and MCP/tool-catalog contract: setup selection, JSON diagnostics, exit statuses, and update command/results change. Analysis MCP tools are unchanged. - Provider, bridge, target-format, or platform compatibility: provider operations are unchanged. Client paths account for Windows, macOS, and Linux; updater subprocesses use cross-spawn for Windows npm launchers. - Evidence, artifact, provenance, or reconstruction contract: none. - Process execution, authorization, cleanup, or containment impact: agent-only setup no longer requires provider prerequisites. Setup still requires approval for planned writes and optional Hopper installation. Update installs REA and verifies the new entry point; its subsequent setup probe is read-only. - Generated metadata, package, or installation impact: regenerate the product catalog and derived skill/conformance digests. Add pinned `jsonc-parser@3.3.1`, `cross-spawn@7.0.6`, and development types `@types/cross-spawn@6.0.6`. No external runtimes or package managers are installed. ## Evidence and regression coverage - Unit and boundary tests exercise registration dialects, malformed selected configs before mutation, ownership, fresh and repeat setup, provider-independent readiness, cancellation, and redirected output. - Update tests cover exact versions, invalid metadata, unknown installations, canonical/custom prefixes, wrong installed versions, complete subprocess output, actual error details, disabled and foreign integrations, and malformed/out-of-scope maintenance plans. - Packaged checks exercise JSONC preservation, backups, symlink lifecycle, recovery, uninstall, real TTY cancellation and restoration, redirected output, and actual npm release lookup/install against a local registry fixture. - The packaged update fixture gives the installed package an older version identity while retaining the new updater code, then installs the unmodified target tarball. It verifies the new executable and proves that integration maintenance leaves configuration untouched. - Compared onboarding against Context7's authoritative [client registry](https://github.com/upstash/context7/blob/master/packages/cli/src/setup/agents.ts) and observed `ctx7@0.5.13 setup` from isolated and checkout contexts, cancelling before mutation. Reviewed Pi's authoritative [update implementation](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/src/package-manager-cli.ts) for exact-version and verification behavior. - Remaining proof gaps: native Windows execution runs in CI; the Windows package verifier was exercised locally on macOS. Actual agent applications were not launched. The published-release canary has been adapted for this updater but cannot exercise the new implementation until it is published. Representative invocations: ```sh rea setup --client opencode --client vscode --client copilot_cli --dry-run rea setup --client opencode --yes rea setup --all-detected --yes rea update --json ``` The interactive flow asks “Which agents should use REA?”, shows detected and configured state, and displays resolved preflight before “Apply these changes?”. Cancellation returns `status: "cancelled"`; dry runs return `status: "planned"`, both with exit code 0. A successful update returns `status: "updated"`, `installedVersion`, and `maintenance`; a planned maintenance result includes its exact command and actions. ## Validation performed - `npm run check:pr` — passed again after rebasing onto the latest main; 345 test files, 1,937 tests passed and 1 skipped, plus static and generated-document checks. - `npm run docs:generate` — passed. - `npm run build:cached`, `npm run check:fast`, and 39 focused update/maintenance tests — passed after the final registry-prefix refinement. - `node scripts/verify-package.mjs` — passed against the packaged artifact, including setup, real TTY behavior, uninstall, MCP startup, and real npm update/verification. - `node scripts/verify-windows-package.mjs` — passed on macOS after the final registry-prefix refinement, including OpenCode, VS Code, Copilot, repeat setup, uninstall, and update. This is not a native Windows result; updater tests are also included in the Windows CI lane. - Script syntax, formatting, lint, document-fact, and staged diff checks — passed. ## Compatibility, safety, and release - Breaking changes: unscoped setup refreshes only existing REA-owned registrations. Use `--all-detected` to configure every detected client. Setup JSON exposes a compact doctor summary; `rea doctor` remains the full diagnostic command. Cancellation and successful dry runs exit 0. - Breaking changes: remove `rea upgrade` without an alias; use `rea update`. Successful update results use `status: "updated"`, include the verified installed version and exact command arguments, and return unapplied maintenance instead of opening setup. - Real Hopper/Ghidra and browser verification was not performed; provider runtime behavior is unchanged. Packaged verification ran on macOS arm64; native Windows coverage remains CI. - Configuration changes are additive, backed up, and verified. Uninstall removes only owned REA registrations and preserves other settings. Selected malformed configs block before earlier writes. Failed installed-version verification reports that npm completed and the installation may have changed. ## Review checklist - [x] The PR has one focused outcome and a Conventional Commit title. - [x] The reason for no tracking issue is stated above. - [x] Tests cover changed observable behavior and meaningful failure paths. - [x] Owning docs and generated metadata are updated. - [x] Representative CLI behavior is included. - [x] The final diff was checked for secrets, unrelated cleanup, and unsupported claims. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-16 21:13:59 +00:00