[PR #15] [MERGED] [codex] Simplify REA onboarding and app targeting #1810

New issue

Closed

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

bsakaguchi commented

2026-10-16 21:11:16 +00:00

Owner

📋 Pull Request Information

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

Base: main ← Head: codex/simplify-readme-onboarding

📝 Commits (2)

fc21c9a Simplify REA onboarding and app targeting
85f178b Merge main into onboarding branch

📊 Changes

16 files changed (+602 additions, -361 deletions)

View changed files

📝 README.md (+75 -91)
📝 README_ar.md (+53 -68)
📝 README_ja.md (+61 -54)
📝 README_ko.md (+61 -54)
📝 README_zh.md (+61 -54)
📝 package.json (+10 -3)
📝 scripts/verify-package.mjs (+6 -2)
📝 skills/rea-analysis/SKILL.md (+39 -3)
📝 src/application/Doctor.ts (+6 -10)
📝 src/application/Setup.ts (+7 -1)
📝 src/cli.ts (+12 -12)
📝 src/domain/binaryTarget.ts (+97 -2)
📝 src/domain/errors.ts (+4 -4)
📝 tests/binaryTarget.test.ts (+66 -1)
📝 tests/doctor.test.ts (+13 -2)
➕ tests/readmeConsistency.test.ts (+31 -0)

📄 Description

Why

REA's onboarding still assumed that users understood program paths, binary-analysis terminology, and address-level decompilation. The packaged agent skill was also much thinner than the product workflow described in the README, and setup maintained a separate hard-coded copy that could drift.

What changed

Reframes the README around one agent request: name an app, explain what you want to understand, and optionally build a version for your project.
Adds the npx skills add morluto/rea path prominently and keeps direct CLI commands secondary.
Updates the English, Chinese, Japanese, Korean, and Arabic READMEs while contract-testing shared product facts.
Reworks the REA skill to ask for the app or goal only when missing, locate macOS apps by name, perform setup with explicit approval, investigate the requested feature, explain how conclusions were reached, and clean up afterward.
Makes setup install the canonical packaged skill instead of a hard-coded duplicate, with package verification asserting byte-for-byte identity.
Allows CLI, doctor, and MCP entry points to accept a macOS .app directly by safely resolving CFBundleExecutable from its property list.
Simplifies CLI and error language around apps while retaining the lower-level analysis contracts.
Updates npm description and discovery keywords.

The .app resolver handles XML and binary property lists, rejects unsafe executable names and symlink escapes, and then passes the resolved program through the existing executable validation path.

Verification

npm run check — 20 test files and 127 tests passed
npm run verify:package — CLI, setup, backups/readback, canonical skill, target-free MCP, and all 42 tools passed
npm pack --dry-run — 35 expected files; no generated Python bytecode
git diff --check

Real Hopper was not launched for this documentation and target-resolution change. Native .app resolution was exercised with filesystem fixtures and a read-only parse of the system Notes app during development.

_{🔄 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/15 **Author:** [@morluto](https://github.com/morluto) **Created:** 7/12/2026 **Status:** ✅ Merged **Merged:** 7/12/2026 **Merged by:** [@morluto](https://github.com/morluto) **Base:** `main` ← **Head:** `codex/simplify-readme-onboarding` --- ### 📝 Commits (2) - [`fc21c9a`](https://github.com/morluto/rea/commit/fc21c9a2d724965d35f5a987f6a93047a88f9107) Simplify REA onboarding and app targeting - [`85f178b`](https://github.com/morluto/rea/commit/85f178ba20856845a3ffb313866807a85c0f2a96) Merge main into onboarding branch ### 📊 Changes **16 files changed** (+602 additions, -361 deletions) <details> <summary>View changed files</summary> 📝 `README.md` (+75 -91) 📝 `README_ar.md` (+53 -68) 📝 `README_ja.md` (+61 -54) 📝 `README_ko.md` (+61 -54) 📝 `README_zh.md` (+61 -54) 📝 `package.json` (+10 -3) 📝 `scripts/verify-package.mjs` (+6 -2) 📝 `skills/rea-analysis/SKILL.md` (+39 -3) 📝 `src/application/Doctor.ts` (+6 -10) 📝 `src/application/Setup.ts` (+7 -1) 📝 `src/cli.ts` (+12 -12) 📝 `src/domain/binaryTarget.ts` (+97 -2) 📝 `src/domain/errors.ts` (+4 -4) 📝 `tests/binaryTarget.test.ts` (+66 -1) 📝 `tests/doctor.test.ts` (+13 -2) ➕ `tests/readmeConsistency.test.ts` (+31 -0) </details> ### 📄 Description ## Why REA's onboarding still assumed that users understood program paths, binary-analysis terminology, and address-level decompilation. The packaged agent skill was also much thinner than the product workflow described in the README, and setup maintained a separate hard-coded copy that could drift. ## What changed - Reframes the README around one agent request: name an app, explain what you want to understand, and optionally build a version for your project. - Adds the `npx skills add morluto/rea` path prominently and keeps direct CLI commands secondary. - Updates the English, Chinese, Japanese, Korean, and Arabic READMEs while contract-testing shared product facts. - Reworks the REA skill to ask for the app or goal only when missing, locate macOS apps by name, perform setup with explicit approval, investigate the requested feature, explain how conclusions were reached, and clean up afterward. - Makes setup install the canonical packaged skill instead of a hard-coded duplicate, with package verification asserting byte-for-byte identity. - Allows CLI, doctor, and MCP entry points to accept a macOS `.app` directly by safely resolving `CFBundleExecutable` from its property list. - Simplifies CLI and error language around apps while retaining the lower-level analysis contracts. - Updates npm description and discovery keywords. The `.app` resolver handles XML and binary property lists, rejects unsafe executable names and symlink escapes, and then passes the resolved program through the existing executable validation path. ## Verification - `npm run check` — 20 test files and 127 tests passed - `npm run verify:package` — CLI, setup, backups/readback, canonical skill, target-free MCP, and all 42 tools passed - `npm pack --dry-run` — 35 expected files; no generated Python bytecode - `git diff --check` Real Hopper was not launched for this documentation and target-resolution change. Native `.app` resolution was exercised with filesystem fixtures and a read-only parse of the system Notes app during development. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-16 21:11:16 +00:00