docs: clarify onboarding and align provider guidance (#745)
This commit is contained in:
N0zoM1z0
GitHub
parent
d3f498ceec
commit
5af1699103
43
README.md
43
README.md
|
|
@ -4,7 +4,7 @@
|
|||
|
||||
# REA: Reverse Engineer Anything
|
||||
|
||||
### Reverse engineer anything with agents, from app behavior down to native binaries.
|
||||
### One MCP for reverse engineering across binaries, applications, and runtime behavior.
|
||||
|
||||
**See a feature you like. Understand how it works, down to the binary level.**
|
||||
|
||||
|
|
@ -49,7 +49,7 @@ See a feature in an app that you want in your own product? Ask your agent to inv
|
|||
|
||||
REA connects your agent to tools for inspecting native binaries, JavaScript and Electron apps, .NET assemblies, and websites. You can also use the same tools from your terminal. Analysis runs locally, and results include the evidence and limitations behind each conclusion.
|
||||
|
||||
Setup configures your agent and connects it to Hopper or Ghidra. If you need an analysis tool, setup can install Hopper for you.
|
||||
Setup registers REA with your agent and installs matching workflow instructions. Native analysis can use an existing Hopper or Ghidra installation; setup can optionally install Hopper with approval. Static JavaScript analysis needs neither engine.
|
||||
|
||||
## Just ask your agent
|
||||
|
||||
|
|
@ -114,15 +114,34 @@ After setup, restart your agent and [describe the app or feature](#just-ask-your
|
|||
|
||||
REA supports Claude Code, Claude Desktop, Codex, Cursor, Gemini CLI, Windsurf, Devin, OpenCode, Antigravity, GitHub Copilot CLI, Command Code, and VS Code. Existing REA registrations are selected by default during setup; other detected agents remain unselected until chosen. Other agents can use the [manual MCP configuration](#manual-mcp-configuration).
|
||||
|
||||
### From the terminal with npx
|
||||
|
||||
After setup, run:
|
||||
### Install the skill separately
|
||||
|
||||
```bash
|
||||
npx -y rea-agents@latest doctor
|
||||
npx -y rea-agents@latest analyze /Applications/Notes.app
|
||||
npx skills add morluto/rea --skill reverse-engineer-anything
|
||||
```
|
||||
|
||||
This installs agent instructions, not MCP registration or analysis engines.
|
||||
Follow the skill's [conditional connection guide](skills/reverse-engineer-anything/SKILL.md#connect-only-when-needed):
|
||||
prepare a scoped `npx rea-agents setup` plan if registration is missing, review
|
||||
and approve its actual changes, then restart/reconnect and verify the tools.
|
||||
Guided setup above installs a version-matched skill by default. The skills.sh
|
||||
route uses repository instructions, which can be ahead of the released server;
|
||||
see [released package and main](docs/installation.md#released-package-and-main).
|
||||
|
||||
### First result from the terminal
|
||||
|
||||
For your extracted JavaScript/Electron application tree or ASAR, run:
|
||||
|
||||
```bash
|
||||
npx -y rea-agents@latest analyze-javascript-application /absolute/path/to/app --json
|
||||
```
|
||||
|
||||
Replace the path with your target (for example, `"D:/apps/example"` on Windows).
|
||||
This returns inline Evidence, recovered graph, limitations, and unknowns without
|
||||
MCP setup, Hopper, Ghidra, or executing the application. For a native app, configure
|
||||
its engine first, then use `analyze` with that app's path. Run `doctor` when you
|
||||
need diagnosis; it is not a prerequisite for each analysis.
|
||||
|
||||
### Install the rea command
|
||||
|
||||
Install the command-line interface:
|
||||
|
|
@ -144,6 +163,10 @@ Update either installation with `rea update`.
|
|||
|
||||
### Requirements
|
||||
|
||||
Static JavaScript inspection requires the Node/npm runtime only. Host and
|
||||
external-tool prerequisites depend on the selected workflow; the native
|
||||
provider guides describe their supported platforms.
|
||||
|
||||
- macOS 12 or newer
|
||||
- Ubuntu 24.04+, Fedora 41+, or 64-bit Arch Linux
|
||||
- Node.js 22.x (>=22.19), 24.x (>=24.11), or 26+
|
||||
|
|
@ -155,7 +178,7 @@ Firmware region inspection and explicit extraction use caller-supplied Binwalk a
|
|||
|
||||
Static APK analysis uses a separately supplied headless JADX JAR and Java, with no emulator or APK execution. See [Android analysis](docs/android-analysis.md) for setup, CLI/MCP operations, coverage and public test fixtures.
|
||||
|
||||
Windows Ghidra support is experimental for native x86-64 PE applications on local NTFS. The package bundles native Job Object, private-DACL, and path-admission controls. See [Windows Ghidra P0](docs/windows-ghidra-p0.md) for prerequisites and verified scope.
|
||||
Repository main includes experimental Windows x64 Ghidra support for native x86-64 PE applications on local NTFS, with bundled Job Object, private-DACL, and path-admission controls. Check the [release boundary](docs/installation.md#released-package-and-main) before expecting this from an npm package. See [Windows Ghidra P0](docs/windows-ghidra-p0.md) for prerequisites and verified scope.
|
||||
|
||||
If something is not working, run:
|
||||
|
||||
|
|
@ -330,7 +353,7 @@ The public interface describes what the agent is trying to learn. Providers deci
|
|||
|
||||
## Current status
|
||||
|
||||
REA supports native application, JavaScript, Electron, .NET, and browser investigation on macOS and Linux. Individual tools have platform and runtime prerequisites; use `rea capabilities` to check what is available on your host.
|
||||
REA supports native application, JavaScript, Electron, .NET, and browser investigation on macOS and Linux. Individual tools have platform and runtime prerequisites. `rea capabilities` and `rea providers` describe the binary-session providers and auxiliary operations; they are not an inventory of every browser, Android, or application workflow. Use the connected MCP tool list and `binary_session` tool availability for the full MCP surface, and the relevant guide for each tool's prerequisites. Repository main can be ahead of [the npm release](docs/installation.md#released-package-and-main).
|
||||
|
||||
Static Android APK inspection is verified on Linux with headless JADX; see [Android analysis](docs/android-analysis.md) for its separate prerequisites and coverage.
|
||||
|
||||
|
|
@ -345,7 +368,7 @@ Static Android APK inspection is verified on Linux with headless JADX; see [Andr
|
|||
- **Open questions:** Track unresolved findings, contradictions, and follow-up probes. Reconstruction checks report pass, fail, or unknown rather than treating missing evidence as a pass.
|
||||
- **Guided workflows:** Start six [MCP investigation workflows](docs/mcp-prompts.md) with suggestions based on your current session.
|
||||
|
||||
Windows Ghidra P0 supports the read-only native x86-64 PE boundary on local NTFS. Hopper-only features, such as GUI controls and annotations, are not available through Ghidra.
|
||||
Windows x64 Ghidra P0 supports native, non-managed, non-DLL x86-64 PE applications on fixed local NTFS with 25 read-only operations. Linux/macOS Ghidra additionally supports atomic session-scoped function names and entry comments. Ghidra has no GUI controls; Windows P0 has no mutation authority.
|
||||
|
||||
### Website observation with CDP
|
||||
|
||||
|
|
|
|||
45
README_ar.md
45
README_ar.md
|
|
@ -98,15 +98,29 @@ npx rea-agents setup
|
|||
|
||||
يمكن تشغيل Hopper في الوضع التجريبي. إذا ظهرت رسالة عند التشغيل الأول، فاختر التجربة أو أدخل ترخيصًا موجودًا.
|
||||
|
||||
### الاستخدام من الطرفية
|
||||
|
||||
بعد الإعداد، شغّل:
|
||||
### Skill instructions and a first CLI result
|
||||
|
||||
```bash
|
||||
npx -y rea-agents@latest doctor
|
||||
npx -y rea-agents@latest analyze /Applications/Notes.app
|
||||
npx skills add morluto/rea --skill reverse-engineer-anything
|
||||
```
|
||||
|
||||
This installs instructions, not MCP registration or analysis engines. Follow the
|
||||
[conditional connection guide](skills/reverse-engineer-anything/SKILL.md#connect-only-when-needed).
|
||||
`npx rea-agents setup` installs a matching skill and registers selected clients
|
||||
only after showing the plan and receiving approval. Restart/reconnect after
|
||||
registration, then verify REA tools in the active session. Repository skills can
|
||||
be ahead of the [released package](docs/installation.md#released-package-and-main).
|
||||
|
||||
For your extracted JavaScript/Electron tree or ASAR, no MCP setup or native
|
||||
engine is required:
|
||||
|
||||
```bash
|
||||
npx -y rea-agents@latest analyze-javascript-application /absolute/path/to/app --json
|
||||
```
|
||||
|
||||
Replace the path with your target; Windows paths such as `"D:/apps/example"`
|
||||
are supported by this static workflow. Native analysis requires its own engine.
|
||||
|
||||
### تثبيت أمر rea
|
||||
|
||||
ثبت واجهة سطر الأوامر:
|
||||
|
|
@ -136,7 +150,7 @@ rea setup
|
|||
|
||||
يستطيع Setup التحقق من التثبيت وحفظ المسارات؛ ولا يثبت أو يحدّث Ghidra أو Java أو Node.js أو npm أو Homebrew.
|
||||
|
||||
تحليل Ghidra على Windows غير متاح. لم تُنفذ بعد ضوابط ملكية العمليات وأذونات المجلدات الخاصة والتحقق الآمن من المسارات. حتى التثبيت الصحيح لـ Ghidra وJava لا يفعّل التحليل. راجع [Windows Ghidra P0](docs/windows-ghidra-p0.md).
|
||||
Repository main includes experimental Windows x64 Ghidra P0 for native, non-managed, non-DLL x86-64 PE applications on fixed local NTFS. The native controls are implemented; npm 4.0.1 does not contain them. See the [release boundary](docs/installation.md#released-package-and-main) and [Windows Ghidra P0](docs/windows-ghidra-p0.md).
|
||||
|
||||
### تشخيص المشكلات
|
||||
|
||||
|
|
@ -152,12 +166,21 @@ rea setup
|
|||
|
||||
## حالة الدعم
|
||||
|
||||
يوفر REA عبر CLI وMCP تحليل الملفات التنفيذية الأصلية وتطبيقات JavaScript وElectron وتجميعات .NET والمواقع. تعتمد العمليات المتاحة على الجهاز والهدف وأداة التحليل المختارة.
|
||||
The current repository capabilities and platform requirements are described in
|
||||
[the English support guide](README.md#current-status). Main can be ahead of the
|
||||
[npm release](docs/installation.md#released-package-and-main).
|
||||
|
||||
- يدعم Hopper التحليل الأصلي والتعليقات؛ ويختلف سلوك واجهته الرسومية حسب المنصة.
|
||||
- يقدم Ghidra على Linux x64 وmacOS x64/arm64 عددًا قدره 22 عملية للقراءة فقط: الجرد والبحث وفك الترجمة والتعليمات والاستدعاءات والمراجع والأنواع. لا يقدم عمليات واجهة رسومية أو تعديل.
|
||||
- لسير عمل المتصفح وElectron وتشغيل العمليات متطلبات مستقلة للإعداد والموافقة وإدارة دورة الحياة. راجع [English README](README.md#current-status) للتفاصيل الكاملة.
|
||||
- تحليل Ghidra على Windows غير مفعّل. تابع التقدم في [#527](https://github.com/morluto/rea/issues/527).
|
||||
- Ghidra provides 25 read-only operations on Linux x64, macOS x64/arm64, and the
|
||||
experimental Windows x64 P0 boundary. Linux/macOS additionally supports atomic
|
||||
session function annotations. Windows P0 is read-only; Ghidra has no GUI controls.
|
||||
- Static Android inspection has separate bring-your-own JADX/Java prerequisites;
|
||||
real-provider verification covers Linux. See [Android analysis](docs/android-analysis.md).
|
||||
- Browser, Electron, and process requests specify their target, actions, and
|
||||
lifecycle directly. They require the host's actual access, without separate
|
||||
REA permission grants. Setup configuration writes and Hopper installation
|
||||
still require approval of their exact plan.
|
||||
- `rea capabilities` describes binary-session operations rather than every
|
||||
application/runtime tool. Consult the full MCP tool list and relevant guide.
|
||||
|
||||
## استقصاء كامل بطلب واحد
|
||||
|
||||
|
|
|
|||
45
README_ja.md
45
README_ja.md
|
|
@ -98,15 +98,29 @@ Setup は最初に連携するエージェントを複数選択できるよう
|
|||
|
||||
Hopper はデモモードで使えます。初回起動の画面ではデモを選択するか、既存のライセンスを入力してください。
|
||||
|
||||
### ターミナルで使う
|
||||
|
||||
設定後に実行します：
|
||||
### Skill instructions and a first CLI result
|
||||
|
||||
```bash
|
||||
npx -y rea-agents@latest doctor
|
||||
npx -y rea-agents@latest analyze /Applications/Notes.app
|
||||
npx skills add morluto/rea --skill reverse-engineer-anything
|
||||
```
|
||||
|
||||
This installs instructions, not MCP registration or analysis engines. Follow the
|
||||
[conditional connection guide](skills/reverse-engineer-anything/SKILL.md#connect-only-when-needed).
|
||||
`npx rea-agents setup` installs a matching skill and registers selected clients
|
||||
only after showing the plan and receiving approval. Restart/reconnect after
|
||||
registration, then verify REA tools in the active session. Repository skills can
|
||||
be ahead of the [released package](docs/installation.md#released-package-and-main).
|
||||
|
||||
For your extracted JavaScript/Electron tree or ASAR, no MCP setup or native
|
||||
engine is required:
|
||||
|
||||
```bash
|
||||
npx -y rea-agents@latest analyze-javascript-application /absolute/path/to/app --json
|
||||
```
|
||||
|
||||
Replace the path with your target; Windows paths such as `"D:/apps/example"`
|
||||
are supported by this static workflow. Native analysis requires its own engine.
|
||||
|
||||
### rea コマンドをインストール
|
||||
|
||||
コマンドラインツールをインストールします：
|
||||
|
|
@ -136,7 +150,7 @@ Ghidra は Linux x64 と macOS x64/arm64 に対応します。Ghidra 12.1.4 と
|
|||
|
||||
Setup はインストールを確認し、パスを保存できます。Ghidra、Java、Node.js、npm、Homebrew のインストールや更新は行いません。
|
||||
|
||||
Windows の Ghidra 解析は利用できません。プロセスの所有権、プライベートディレクトリの権限、安全なパス検証が未実装のため、Ghidra と Java を正しくインストールしても有効になりません。[Windows Ghidra P0](docs/windows-ghidra-p0.md)を参照してください。
|
||||
Repository main includes experimental Windows x64 Ghidra P0 for native, non-managed, non-DLL x86-64 PE applications on fixed local NTFS. The native controls are implemented; npm 4.0.1 does not contain them. See the [release boundary](docs/installation.md#released-package-and-main) and [Windows Ghidra P0](docs/windows-ghidra-p0.md).
|
||||
|
||||
### トラブルシューティング
|
||||
|
||||
|
|
@ -152,12 +166,21 @@ Linux の既定ランチャーは `/opt/hopper/bin/Hopper` です。別の場所
|
|||
|
||||
## 現在の対応状況
|
||||
|
||||
REA は CLI と MCP からネイティブバイナリ、JavaScript/Electron アプリ、.NET アセンブリ、Web サイトを解析できます。使える操作はホスト、対象、選択した解析ツールによって異なります。
|
||||
The current repository capabilities and platform requirements are described in
|
||||
[the English support guide](README.md#current-status). Main can be ahead of the
|
||||
[npm release](docs/installation.md#released-package-and-main).
|
||||
|
||||
- Hopper はネイティブ解析と注釈操作に対応します。GUI の動作はプラットフォームによって異なります。
|
||||
- Ghidra は Linux x64 と macOS x64/arm64 で、一覧、検索、逆コンパイル、アセンブリ、呼び出し、参照、命令、型の検査など 22 の読み取り専用操作を提供します。GUI 操作や変更操作はありません。
|
||||
- ブラウザー、Electron、プロセスの実行時ワークフローには、それぞれ設定、承認、終了処理の要件があります。詳細は [English README](README.md#current-status) を参照してください。
|
||||
- Windows の Ghidra 解析は未対応です。進捗は [#527](https://github.com/morluto/rea/issues/527) で確認できます。
|
||||
- Ghidra provides 25 read-only operations on Linux x64, macOS x64/arm64, and the
|
||||
experimental Windows x64 P0 boundary. Linux/macOS additionally supports atomic
|
||||
session function annotations. Windows P0 is read-only; Ghidra has no GUI controls.
|
||||
- Static Android inspection has separate bring-your-own JADX/Java prerequisites;
|
||||
real-provider verification covers Linux. See [Android analysis](docs/android-analysis.md).
|
||||
- Browser, Electron, and process requests specify their target, actions, and
|
||||
lifecycle directly. They require the host's actual access, without separate
|
||||
REA permission grants. Setup configuration writes and Hopper installation
|
||||
still require approval of their exact plan.
|
||||
- `rea capabilities` describes binary-session operations rather than every
|
||||
application/runtime tool. Consult the full MCP tool list and relevant guide.
|
||||
|
||||
## ひとつのプロンプトで調査を完結
|
||||
|
||||
|
|
|
|||
45
README_ko.md
45
README_ko.md
|
|
@ -99,15 +99,29 @@ Setup은 먼저 연결할 에이전트를 여러 개 선택하도록 안내합
|
|||
|
||||
Hopper는 데모 모드로 사용할 수 있습니다. 첫 실행 안내가 나오면 데모를 선택하거나 기존 라이선스를 입력하세요.
|
||||
|
||||
### 터미널에서 실행하기
|
||||
|
||||
설정 후 실행하세요.
|
||||
### Skill instructions and a first CLI result
|
||||
|
||||
```bash
|
||||
npx -y rea-agents@latest doctor
|
||||
npx -y rea-agents@latest analyze /Applications/Notes.app
|
||||
npx skills add morluto/rea --skill reverse-engineer-anything
|
||||
```
|
||||
|
||||
This installs instructions, not MCP registration or analysis engines. Follow the
|
||||
[conditional connection guide](skills/reverse-engineer-anything/SKILL.md#connect-only-when-needed).
|
||||
`npx rea-agents setup` installs a matching skill and registers selected clients
|
||||
only after showing the plan and receiving approval. Restart/reconnect after
|
||||
registration, then verify REA tools in the active session. Repository skills can
|
||||
be ahead of the [released package](docs/installation.md#released-package-and-main).
|
||||
|
||||
For your extracted JavaScript/Electron tree or ASAR, no MCP setup or native
|
||||
engine is required:
|
||||
|
||||
```bash
|
||||
npx -y rea-agents@latest analyze-javascript-application /absolute/path/to/app --json
|
||||
```
|
||||
|
||||
Replace the path with your target; Windows paths such as `"D:/apps/example"`
|
||||
are supported by this static workflow. Native analysis requires its own engine.
|
||||
|
||||
### rea 명령 설치하기
|
||||
|
||||
명령줄 도구를 설치하세요.
|
||||
|
|
@ -137,7 +151,7 @@ Ghidra는 Linux x64와 macOS x64/arm64를 지원합니다. Ghidra 12.1.4와 완
|
|||
|
||||
Setup은 설치를 확인하고 경로를 저장할 수 있습니다. Ghidra, Java, Node.js, npm, Homebrew를 설치하거나 업데이트하지 않습니다.
|
||||
|
||||
Windows Ghidra 분석은 사용할 수 없습니다. 프로세스 소유권, 비공개 디렉터리 권한, 안전한 경로 검사가 구현되지 않았으므로 Ghidra와 Java를 올바르게 설치해도 분석을 활성화할 수 없습니다. [Windows Ghidra P0](docs/windows-ghidra-p0.md)를 참고하세요.
|
||||
Repository main includes experimental Windows x64 Ghidra P0 for native, non-managed, non-DLL x86-64 PE applications on fixed local NTFS. The native controls are implemented; npm 4.0.1 does not contain them. See the [release boundary](docs/installation.md#released-package-and-main) and [Windows Ghidra P0](docs/windows-ghidra-p0.md).
|
||||
|
||||
### 문제 해결
|
||||
|
||||
|
|
@ -153,12 +167,21 @@ Linux의 기본 Hopper 실행 파일은 `/opt/hopper/bin/Hopper`입니다. 다
|
|||
|
||||
## 현재 지원 범위
|
||||
|
||||
REA는 CLI와 MCP로 네이티브 바이너리, JavaScript/Electron 앱, .NET 어셈블리, 웹사이트를 분석합니다. 사용할 수 있는 작업은 호스트, 대상, 선택한 분석 도구에 따라 다릅니다.
|
||||
The current repository capabilities and platform requirements are described in
|
||||
[the English support guide](README.md#current-status). Main can be ahead of the
|
||||
[npm release](docs/installation.md#released-package-and-main).
|
||||
|
||||
- Hopper는 네이티브 분석과 주석 작업을 지원합니다. GUI 동작은 플랫폼에 따라 다릅니다.
|
||||
- Ghidra는 Linux x64와 macOS x64/arm64에서 목록, 검색, 디컴파일, 어셈블리, 호출, 참조, 명령어, 타입 검사 등 읽기 전용 작업 22개를 제공합니다. GUI나 변경 작업은 제공하지 않습니다.
|
||||
- 브라우저, Electron, 프로세스 런타임 워크플로에는 각각 설정, 승인, 종료 처리 요구 사항이 있습니다. 자세한 내용은 [English README](README.md#current-status)를 참고하세요.
|
||||
- Windows Ghidra 분석은 아직 사용할 수 없습니다. 진행 상황은 [#527](https://github.com/morluto/rea/issues/527)에서 확인하세요.
|
||||
- Ghidra provides 25 read-only operations on Linux x64, macOS x64/arm64, and the
|
||||
experimental Windows x64 P0 boundary. Linux/macOS additionally supports atomic
|
||||
session function annotations. Windows P0 is read-only; Ghidra has no GUI controls.
|
||||
- Static Android inspection has separate bring-your-own JADX/Java prerequisites;
|
||||
real-provider verification covers Linux. See [Android analysis](docs/android-analysis.md).
|
||||
- Browser, Electron, and process requests specify their target, actions, and
|
||||
lifecycle directly. They require the host's actual access, without separate
|
||||
REA permission grants. Setup configuration writes and Hopper installation
|
||||
still require approval of their exact plan.
|
||||
- `rea capabilities` describes binary-session operations rather than every
|
||||
application/runtime tool. Consult the full MCP tool list and relevant guide.
|
||||
|
||||
## 하나의 프롬프트로 전체 조사
|
||||
|
||||
|
|
|
|||
45
README_zh.md
45
README_zh.md
|
|
@ -98,15 +98,29 @@ Setup 会先展示变更并备份已有配置。要求与更多选项见[安装
|
|||
|
||||
Hopper 支持演示模式。如果首次启动时出现提示，选择演示模式或输入已有许可证。
|
||||
|
||||
### 从终端运行
|
||||
|
||||
设置完成后：
|
||||
### Skill instructions and a first CLI result
|
||||
|
||||
```bash
|
||||
npx -y rea-agents@latest doctor
|
||||
npx -y rea-agents@latest analyze /Applications/Notes.app
|
||||
npx skills add morluto/rea --skill reverse-engineer-anything
|
||||
```
|
||||
|
||||
This installs instructions, not MCP registration or analysis engines. Follow the
|
||||
[conditional connection guide](skills/reverse-engineer-anything/SKILL.md#connect-only-when-needed).
|
||||
`npx rea-agents setup` installs a matching skill and registers selected clients
|
||||
only after showing the plan and receiving approval. Restart/reconnect after
|
||||
registration, then verify REA tools in the active session. Repository skills can
|
||||
be ahead of the [released package](docs/installation.md#released-package-and-main).
|
||||
|
||||
For your extracted JavaScript/Electron tree or ASAR, no MCP setup or native
|
||||
engine is required:
|
||||
|
||||
```bash
|
||||
npx -y rea-agents@latest analyze-javascript-application /absolute/path/to/app --json
|
||||
```
|
||||
|
||||
Replace the path with your target; Windows paths such as `"D:/apps/example"`
|
||||
are supported by this static workflow. Native analysis requires its own engine.
|
||||
|
||||
### 安装 rea 命令
|
||||
|
||||
安装命令行工具：
|
||||
|
|
@ -136,7 +150,7 @@ Ghidra 支持 Linux x64 和 macOS x64/arm64。单独安装 Ghidra 12.1.4 和完
|
|||
|
||||
Setup 可以验证安装并保存路径，不会安装或升级 Ghidra、Java、Node.js、npm 或 Homebrew。
|
||||
|
||||
Windows Ghidra 分析目前不可用。进程归属、私有目录权限和安全路径检查尚未实现，正确安装 Ghidra 和 Java 也不能启用分析。详见 [Windows Ghidra P0](docs/windows-ghidra-p0.md)。
|
||||
Repository main includes experimental Windows x64 Ghidra P0 for native, non-managed, non-DLL x86-64 PE applications on fixed local NTFS. The native controls are implemented; npm 4.0.1 does not contain them. See the [release boundary](docs/installation.md#released-package-and-main) and [Windows Ghidra P0](docs/windows-ghidra-p0.md).
|
||||
|
||||
### 故障排查
|
||||
|
||||
|
|
@ -152,12 +166,21 @@ Linux 上的默认 Hopper 启动器为 `/opt/hopper/bin/Hopper`。其他路径
|
|||
|
||||
## 当前状态
|
||||
|
||||
REA 可以通过 CLI 和 MCP 分析原生二进制、JavaScript/Electron 应用、.NET 程序集和网站。具体操作取决于主机、目标和所选分析工具。
|
||||
The current repository capabilities and platform requirements are described in
|
||||
[the English support guide](README.md#current-status). Main can be ahead of the
|
||||
[npm release](docs/installation.md#released-package-and-main).
|
||||
|
||||
- Hopper 支持原生分析和注释操作；GUI 行为取决于平台。
|
||||
- Ghidra 在 Linux x64 和 macOS x64/arm64 上提供 22 项只读操作，包括清单、搜索、反编译、汇编、调用关系、引用、指令与类型检查。它不提供 GUI 或修改操作。
|
||||
- 浏览器、Electron 和进程运行时工作流有独立的配置、批准和生命周期要求。详见 [English README](README.md#current-status) 中的完整状态说明。
|
||||
- Windows Ghidra 分析尚未启用，跟踪进展见 [#527](https://github.com/morluto/rea/issues/527)。
|
||||
- Ghidra provides 25 read-only operations on Linux x64, macOS x64/arm64, and the
|
||||
experimental Windows x64 P0 boundary. Linux/macOS additionally supports atomic
|
||||
session function annotations. Windows P0 is read-only; Ghidra has no GUI controls.
|
||||
- Static Android inspection has separate bring-your-own JADX/Java prerequisites;
|
||||
real-provider verification covers Linux. See [Android analysis](docs/android-analysis.md).
|
||||
- Browser, Electron, and process requests specify their target, actions, and
|
||||
lifecycle directly. They require the host's actual access, without separate
|
||||
REA permission grants. Setup configuration writes and Hopper installation
|
||||
still require approval of their exact plan.
|
||||
- `rea capabilities` describes binary-session operations rather than every
|
||||
application/runtime tool. Consult the full MCP tool list and relevant guide.
|
||||
|
||||
## 一个提示词，完成一次完整调查
|
||||
|
||||
|
|
|
|||
|
|
@ -5,9 +5,12 @@
|
|||
- Implementation status: The provider registry, deterministic selection,
|
||||
target binding, analysis-profile commitment, and snapshot/Evidence migration
|
||||
are implemented. Ghidra discovery, target/profile resolution, doctor checks,
|
||||
the private headless-session foundation, ten read-only inventory capabilities,
|
||||
and twelve function-analysis capabilities are implemented with real
|
||||
cross-format conformance.
|
||||
the private headless-session foundation, thirteen read-only inventory/load-image
|
||||
capabilities, and twelve function-analysis capabilities are implemented with
|
||||
real cross-format conformance. Linux/macOS also supports atomic session
|
||||
function annotations; experimental Windows x64 P0 uses bundled native controls
|
||||
and admits only the 25 read-only operations. See the
|
||||
[release boundary](../installation.md#released-package-and-main).
|
||||
|
||||
## Context
|
||||
|
||||
|
|
@ -25,7 +28,7 @@ engine, engine version, or complete analysis configuration. Two analyses of the
|
|||
same bytes could therefore disagree because of language, compiler, loader,
|
||||
analyzer, or provider-version differences while appearing target-compatible.
|
||||
|
||||
These constraints are embodied in the current
|
||||
The decision addressed the earlier representations of
|
||||
[`CompositeProvider`](../../src/application/CompositeProvider.ts),
|
||||
[runtime composition](../../src/application/runtime.ts),
|
||||
[`BinarySession`](../../src/application/BinarySession.ts),
|
||||
|
|
|
|||
|
|
@ -4,8 +4,8 @@ Accepted decisions describe the architecture that implementation PRs must
|
|||
follow. Acceptance does not by itself mean the behavior is shipped; each record
|
||||
states its implementation status separately.
|
||||
|
||||
| ADR | Status | Implementation |
|
||||
| ------------------------------------------------------------------------------------------------------------------ | -------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
|
||||
| [0001: Provider selection and analysis profiles](0001-provider-selection-and-analysis-profiles.md) | Accepted | Provider selection and 22 Ghidra operations shipped on Linux/macOS; experimental Windows x64 P0 with bundled native controls |
|
||||
| [0002: Controlled JavaScript replay authority and sandbox policy](0002-controlled-replay-authority-and-sandbox.md) | Superseded | Historical design; the controlled JavaScript replay tool was removed |
|
||||
| [0003: Managed-code evidence and provider boundary](0003-managed-code-evidence-and-provider-boundary.md) | Partially superseded | Seven static managed tools remain; runtime planning removed |
|
||||
| ADR | Status | Implementation |
|
||||
| ------------------------------------------------------------------------------------------------------------------ | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| [0001: Provider selection and analysis profiles](0001-provider-selection-and-analysis-profiles.md) | Accepted | Provider selection and 25 read-only Ghidra operations on Linux/macOS and experimental Windows x64 P0; Linux/macOS session annotations |
|
||||
| [0002: Controlled JavaScript replay authority and sandbox policy](0002-controlled-replay-authority-and-sandbox.md) | Superseded | Historical design; the controlled JavaScript replay tool was removed |
|
||||
| [0003: Managed-code evidence and provider boundary](0003-managed-code-evidence-and-provider-boundary.md) | Partially superseded | Seven static managed tools remain; runtime planning removed |
|
||||
|
|
|
|||
|
|
@ -5,6 +5,10 @@ kept as an unmodified, commit-pinned Git submodule; see
|
|||
[upstream provenance](../third_party/README.md). CLI and MCP use the same
|
||||
application workflow and return artifact-bound Evidence inline.
|
||||
|
||||
This family is present on repository main and absent from npm 4.0.1. Check the
|
||||
[released package boundary](installation.md#released-package-and-main) and the
|
||||
connected server's tool list before selecting it.
|
||||
|
||||
## Supply tools
|
||||
|
||||
Use **Java 17 or newer** and **jadx-headless-mcp 0.7.1**. REA does not install Java,
|
||||
|
|
|
|||
|
|
@ -4,7 +4,7 @@ REA can attach to a user-owned Chrome-family browser through the Chrome DevTools
|
|||
|
||||
## Shipped surfaces
|
||||
|
||||
- `list_browser_targets` / `rea list-browser-targets` discovers page targets at the selected target's current origin by default, with an optional exact-origin filter.
|
||||
- `list_browser_targets` / `rea list-browser-targets` discovers all eligible page targets at the endpoint by default, with an optional exact-origin filter.
|
||||
- `inspect_web_page` / `rea inspect-web-page` captures DOM structure, accessibility nodes, scripts, resources, safe response/DOM metadata, attach-window network and console metadata, WebSocket frame sizes, workers, quota, and optionally selected storage key names, redacted storage-content fingerprints, or script sources.
|
||||
- `analyze_web_bundle` / `rea analyze-web-bundle` parses selected script artifacts without execution and derives chunk edges, route and endpoint candidates, vendor fingerprints, static WebMCP declarations, and optionally source-map/original-source evidence.
|
||||
- `observe_web_session` / `rea observe-web-session` arms an observation window of the requested duration for an external user action and records ordered reload, SPA navigation, redirect, failure, lifecycle, and target-termination metadata.
|
||||
|
|
@ -37,9 +37,9 @@ REA does not launch, own, or terminate this browser. Use a dedicated profile and
|
|||
|
||||
## Request boundary
|
||||
|
||||
Each request supplies a literal loopback CDP endpoint and target. Target
|
||||
discovery uses the selected target's current origin by default; an optional
|
||||
exact HTTP(S) origin filter can narrow the result. `localhost`, private-LAN
|
||||
Discovery supplies a literal loopback CDP endpoint and returns all eligible
|
||||
page targets unless an exact HTTP(S) origin filter narrows the result. Follow-up
|
||||
inspection requests select one target; their default scope is its current origin. `localhost`, private-LAN
|
||||
addresses, HTTPS CDP endpoints, credentials, paths, queries, fragments, and
|
||||
implicit ports are not valid CDP endpoints. Origin filters contain only scheme,
|
||||
host, and port; paths, credentials, queries, fragments, and wildcards are not
|
||||
|
|
|
|||
|
|
@ -21,6 +21,34 @@ Duration, action, and navigation
|
|||
timeouts remain fixed provider-owned liveness limits; the request does not
|
||||
accept a caller-controlled `limits` object.
|
||||
|
||||
## Minimal launch example
|
||||
|
||||
Save this as `browser-scenario.json`, replacing the executable path with an
|
||||
already-installed Chrome-family browser and the URL with your running fixture:
|
||||
|
||||
```json
|
||||
{
|
||||
"browser": {
|
||||
"mode": "launch",
|
||||
"executable_path": "/absolute/path/to/chromium"
|
||||
},
|
||||
"start_url": { "url": "http://127.0.0.1:3000" },
|
||||
"actions": [
|
||||
{ "step_id": "settle", "action": "wait_for_timeout", "duration_ms": 100 }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
```bash
|
||||
rea capture-browser-scenario ./browser-scenario.json --json > browser-capture.json
|
||||
```
|
||||
|
||||
The default capture includes the final URL. Select DOM, screenshots, or events
|
||||
only when they help answer the question. REA launches and cleans up the browser
|
||||
profile for this request; it does not start your fixture server or install a
|
||||
browser. A schema-valid scenario does not prove that the executable or target
|
||||
is available on the host.
|
||||
|
||||
The browser boundary is part of the contract. Launch mode requires a
|
||||
caller-selected executable and always uses a provider-owned temporary profile
|
||||
that is closed and deleted during cleanup. Connect mode accepts only an
|
||||
|
|
|
|||
|
|
@ -61,6 +61,56 @@ curl -fsSL https://raw.githubusercontent.com/morluto/rea/main/install.sh |
|
|||
|
||||
Supported options are `--version <semver>`, `--dry-run`, `--no-setup`, `--no-prompt`, and `--verbose`. Neither `--no-prompt` nor a non-interactive shell grants permission to install external dependencies.
|
||||
|
||||
## Released package and main
|
||||
|
||||
Repository main documents its current code and generated catalog. `@latest`
|
||||
selects the npm release, and persistent MCP registrations are pinned to the
|
||||
version that performed setup. Installing newer instructions does not update a
|
||||
running server or its registration.
|
||||
|
||||
The release checked on **2026-10-06** was **4.0.1** (116 MCP tools). That artifact
|
||||
has static JavaScript inspection and full inline Evidence workflows, but does
|
||||
not include main's Windows native control bundle, Android/JADX or firmware
|
||||
tools, Ghidra function annotation workflow, or retained application-Evidence
|
||||
references.
|
||||
Main's catalog describes those additions; a source build or a subsequent
|
||||
release containing them is required. Package startup alone does not verify a
|
||||
provider's real platform workflow.
|
||||
|
||||
To check the published version, run `npm view rea-agents dist-tags.latest`.
|
||||
Use the connected server's actual tool list and advertised input schemas for
|
||||
feature selection. The same package version string in a development checkout
|
||||
does not establish that its bytes match the npm tarball. Update a registration
|
||||
through a reviewed, scoped setup plan, then restart/reconnect the agent.
|
||||
|
||||
## Skill-only installation
|
||||
|
||||
```bash
|
||||
npx skills add morluto/rea --skill reverse-engineer-anything
|
||||
```
|
||||
|
||||
This installs agent instructions and bundled references, not REA MCP
|
||||
registration or analysis engines. Follow the skill's
|
||||
[conditional connection guide](../skills/reverse-engineer-anything/SKILL.md#connect-only-when-needed).
|
||||
Working tools can be used immediately. If tools are missing, inspect the current
|
||||
client's registration with `doctor --client codex --json` (substitute its client
|
||||
ID), then plan repairs with `setup --client codex --dry-run --json`. Show and
|
||||
approve the exact changes before applying that scope. An aligned registration
|
||||
with tools absent from the active session needs a restart/reconnection;
|
||||
`doctor` checks files and prerequisites, not the live agent connection.
|
||||
|
||||
Guided setup installs the package's matching skill by default. The skills.sh
|
||||
route can select newer repository instructions, so follow actual server schemas
|
||||
and the release boundary above. Static JavaScript CLI inspection can proceed
|
||||
while MCP is unavailable:
|
||||
|
||||
```bash
|
||||
npx -y rea-agents@latest analyze-javascript-application /absolute/path/to/app --json
|
||||
```
|
||||
|
||||
It returns the complete Evidence record directly and requires no native engine.
|
||||
Provider failures in doctor do not prevent unrelated target-free tools.
|
||||
|
||||
## Supported agents
|
||||
|
||||
Setup can configure these clients for REA's local MCP server:
|
||||
|
|
@ -319,9 +369,12 @@ host-native Ghidra acceptance lane.
|
|||
On a controlled Windows x64 runner, use
|
||||
`npm run verify:ghidra:windows`. The verifier generates a deterministic native
|
||||
PE fixture from source bytes and requires the Windows native authority before
|
||||
opening the provider. This lane remains blocked until those controls are
|
||||
implemented; its intended checks include operation coverage, digest identity,
|
||||
and complete runtime cleanup.
|
||||
opening the provider. The controls are implemented on main; see the
|
||||
[release boundary](#released-package-and-main). The lane verifies all 25 admitted
|
||||
read-only operations, digest identity, and runtime cleanup. The separate
|
||||
`verify:ghidra:windows:package` lane checks the packed CLI/MCP boundary with an
|
||||
ordinary user. It requires the built Windows native bundle and an existing
|
||||
Ghidra/JDK installation; neither is inferred from startup alone.
|
||||
|
||||
## Diagnose, update, and remove
|
||||
|
||||
|
|
|
|||
|
|
@ -139,9 +139,34 @@ available browser, Electron, or process workflows.
|
|||
|
||||
## CLI and verification
|
||||
|
||||
All five CLI commands accept inline JSON or a path to a JSON file. Put the full
|
||||
Evidence records in the workflow input, as in the corresponding MCP tool; the
|
||||
CLI does not resolve Evidence IDs from a separate bundle.
|
||||
All five CLI commands accept inline JSON or a path to a JSON file. The CLI
|
||||
returns an Evidence record directly. Put the full records in a later CLI input;
|
||||
a separate CLI process has no retained MCP connection state.
|
||||
|
||||
For a literal string trace, analyze your supplied tree once, then build the
|
||||
input from the saved Evidence (replace the target and seed):
|
||||
|
||||
```bash
|
||||
rea analyze-javascript-application /absolute/path/to/app --json > application-evidence.json
|
||||
node --input-type=module -e '
|
||||
import { readFileSync, writeFileSync } from "node:fs";
|
||||
const application = JSON.parse(readFileSync("application-evidence.json", "utf8"));
|
||||
writeFileSync("trace-input.json", JSON.stringify({
|
||||
application, seed: { kind: "string", value: "search-result" }, direction: "both"
|
||||
}));'
|
||||
rea trace-application-feature ./trace-input.json --json
|
||||
```
|
||||
|
||||
MCP analysis returns an envelope containing `result`, `evidence_id`, and full
|
||||
`evidence`. If the connected server advertises retained references, reuse its
|
||||
exact returned ID as `{"kind":"retained-evidence","evidence_id":"RETURNED_ID"}`
|
||||
in `application`, or `left`/`right` for comparisons. `RETURNED_ID` is a template,
|
||||
not a literal valid ID. Native Evidence arrays still use complete records.
|
||||
References are scoped to one connection; `close_binary` clears them. Export a
|
||||
bundle before closing and import it on another connection, or supply the full
|
||||
inline Evidence there. npm 4.0.1 accepts full inline Evidence only; installing
|
||||
newer skill instructions does not change that schema. See
|
||||
[MCP Evidence inputs](mcp-contracts.md#retained-application-evidence-inputs).
|
||||
|
||||
For two operator-provided directories or ASARs, run:
|
||||
|
||||
|
|
|
|||
|
|
@ -18,6 +18,24 @@ rea observe-javascript-runtime http://127.0.0.1:9229 TARGET_ID \
|
|||
--runtime-kind node --json
|
||||
```
|
||||
|
||||
## Start a caller-owned Node target
|
||||
|
||||
Run your selected application with Inspector bound to loopback:
|
||||
|
||||
```bash
|
||||
node --inspect=127.0.0.1:9229 ./app.mjs
|
||||
```
|
||||
|
||||
Keep it running while listing targets and observing the selected ID. Use a free
|
||||
port and the same literal endpoint in both REA calls. Stop the application
|
||||
through its normal lifecycle when finished; REA disconnects but does not own or
|
||||
terminate it. Node.js must already be installed.
|
||||
|
||||
Use `--inspect` for this passive workflow. `--inspect-brk` pauses before the
|
||||
application starts, and REA never resumes it or sends
|
||||
`Runtime.runIfWaitingForDebugger`. Resume a paused target with a separate
|
||||
caller-owned debugger before requesting application runtime observations.
|
||||
|
||||
The caller supplies the literal-loopback HTTP endpoint directly. Selecting an endpoint exposes all targets it serves and their local script locations or renderer origins. A target must match the exact requested target ID and expose a same-port WebSocket reported by that endpoint. Targets already marked attached are rejected rather than displacing another debugger. Local paths are canonicalized after symlink resolution.
|
||||
|
||||
`list_javascript_runtime_targets` returns every available target in one inline
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
# Managed-code analysis plan
|
||||
# Managed-code analysis and planned extensions
|
||||
|
||||
REA inspects .NET PE/CLI artifacts without loading or executing their code.
|
||||
It can identify an assembly, inspect metadata and CIL, compare members across
|
||||
|
|
@ -27,6 +27,20 @@ This guide describes the implementation and verification of
|
|||
[ADR-0003](adr/0003-managed-code-evidence-and-provider-boundary.md). The canonical
|
||||
tool inventory is [`product-catalog.json`](product-catalog.json).
|
||||
|
||||
## Shipped scope
|
||||
|
||||
The canonical parser admits PE/CLI bytes and their metadata/CIL without loading
|
||||
an assembly. It reports observed implementation markers and unavailable facts;
|
||||
it does not unpack .NET single-file hosts, decode IL2CPP metadata, or infer a
|
||||
NativeAOT identity from an ordinary native PE. Inputs without admitted CLI
|
||||
metadata do not become managed assemblies through naming or routing guesses.
|
||||
Inspect separately obtained components explicitly and preserve their identities.
|
||||
|
||||
The broader deployment classification and native-body mapping below are design
|
||||
goals from ADR-0003, not claims that every row has an implemented parser. A
|
||||
valid marker can establish a candidate native boundary, not recovered native
|
||||
semantics or runtime behavior.
|
||||
|
||||
## Analysis objective
|
||||
|
||||
REA's managed-code track is intended to answer five different questions without
|
||||
|
|
@ -43,9 +57,9 @@ collapsing them:
|
|||
The ordinary workflow ends at question four. Static analysis never loads or
|
||||
executes the target.
|
||||
|
||||
## Classification workflow
|
||||
## Planned deployment classification
|
||||
|
||||
Classification proceeds from the outermost authenticated bytes inward:
|
||||
The intended extended classifier proceeds from outermost authenticated bytes inward:
|
||||
|
||||
```text
|
||||
source path
|
||||
|
|
@ -58,7 +72,7 @@ source path
|
|||
-> managed-only, native-only, composed, degraded, or unsupported route
|
||||
```
|
||||
|
||||
The result is a vector rather than one label. For example, a single-file modern
|
||||
The planned result is a vector rather than one label. For example, a single-file modern
|
||||
.NET deployment can contain a native host, ordinary CIL assemblies, and
|
||||
ReadyToRun components. Each component receives its own digest, classification,
|
||||
coverage, and route while retaining the outer bundle commitment.
|
||||
|
|
@ -257,17 +271,20 @@ or server-side behavior.
|
|||
## Tool and packaging boundary
|
||||
|
||||
The production parser is REA-owned TypeScript and ships with the existing Node
|
||||
application. It is verified against the ECMA-335 format and independent pinned
|
||||
oracles but has no runtime dependency on them.
|
||||
application. Deterministic conformance uses source-owned byte-built PE/CLI
|
||||
fixtures and expected semantic facts. An optional real ILSpy lane runs only when
|
||||
its executable is explicitly supplied; the default lane does not establish
|
||||
independent pinned-oracle parity. Production inspection needs none of those tools.
|
||||
|
||||
- `System.Reflection.Metadata` is the primary independent metadata/CIL oracle.
|
||||
- `ICSharpCode.Decompiler` and `ilspycmd` are reconstruction and differential
|
||||
oracles. An admitted BYO reconstruction operation records its exact version
|
||||
- A pinned `System.Reflection.Metadata` differential oracle is planned; it is
|
||||
not part of the current verifier.
|
||||
- `ICSharpCode.Decompiler`/`ilspycmd` can supply reconstruction inference.
|
||||
A BYO reconstruction import records the supplied version
|
||||
and remains non-canonical. When `REA_ILSPY_CMD_PATH` points to an absolute
|
||||
runnable `ilspycmd`, `verify:managed` runs a source-owned real ILSpy oracle
|
||||
and imports its C# output as reconstruction inference against exact static
|
||||
member Evidence.
|
||||
- dnlib and Mono.Cecil may increase differential coverage. Their mutation APIs
|
||||
- dnlib and Mono.Cecil are potential future differential oracles. Their mutation APIs
|
||||
are not exposed or included in the production parsing boundary.
|
||||
- The package contains no .NET runtime, SDK, ILSpy installation, proprietary
|
||||
assembly, or compiled conformance fixture.
|
||||
|
|
@ -288,6 +305,11 @@ by the selected Hopper/Ghidra host and format matrix.
|
|||
|
||||
## Source-built conformance corpus
|
||||
|
||||
The current lane uses source-owned byte-built fixtures and malformed-input
|
||||
regressions, with optional operator-supplied applications and ILSpy verification.
|
||||
The table below describes the desired expanded corpus; it is not a report that
|
||||
all compiler-generated forms have been independently verified.
|
||||
|
||||
Fixture sources are intentionally small and behavior-focused. Build outputs
|
||||
are generated outside tracked fixture directories and must not remain after
|
||||
verification or packaging.
|
||||
|
|
|
|||
|
|
@ -17,9 +17,12 @@ recorded, so its influence may remain unknown.
|
|||
Write a JSON scenario and pass its path to the CLI:
|
||||
|
||||
```sh
|
||||
rea capture-process ./scenario.json > capture.json
|
||||
rea capture-process ./scenario.json --json > capture.json
|
||||
```
|
||||
|
||||
`--json` is required when saving input for JSON consumers; the default terminal
|
||||
format is TOON. The file contains the complete capture Evidence record.
|
||||
|
||||
For example:
|
||||
|
||||
```json
|
||||
|
|
|
|||
|
|
@ -7,7 +7,7 @@
|
|||
"client": "2.3.1",
|
||||
"core": "2.3.1"
|
||||
},
|
||||
"skill_version": "24"
|
||||
"skill_version": "25"
|
||||
},
|
||||
"tools": {
|
||||
"total": 125,
|
||||
|
|
|
|||
|
|
@ -1,5 +1,7 @@
|
|||
# Static-analysis provider evaluation
|
||||
|
||||
This guide describes repository main. Check the [released package boundary](installation.md#released-package-and-main) when using npm.
|
||||
|
||||
Ghidra read-only analysis is available on Linux x64 and macOS x64/arm64.
|
||||
Install Ghidra 12.1.4 and a full 64-bit JDK 21 separately, then configure REA to
|
||||
use them. macOS installations need the matching native decompiler.
|
||||
|
|
@ -55,8 +57,9 @@ follow.
|
|||
optional `JAVA_HOME` must identify a 64-bit full JDK 21, otherwise doctor probes
|
||||
`java`/`javac` or `java.exe`/`javac.exe` from `PATH`. Supported Linux and macOS
|
||||
hosts accept compatible ELF, PE, and Mach-O executable targets. Host admission
|
||||
and target compatibility are separate checks. The intended Windows P0 accepts
|
||||
only native x86-64 PE applications; it remains blocked before launch.
|
||||
and target compatibility are separate checks. Windows x64 P0 admits only native,
|
||||
non-managed, non-DLL x86-64 PE applications on fixed local NTFS, with the packaged
|
||||
native authority available before launch.
|
||||
|
||||
The launcher creates one ephemeral runtime root with project,
|
||||
home/cache/config/data/temp, logs, descriptor, endpoint, target snapshot, and
|
||||
|
|
@ -67,18 +70,21 @@ On Linux, the mode-0600 descriptor carries the random token without
|
|||
exposing it in argv or environment and the Java bridge binds a mode-restricted
|
||||
Unix socket. macOS uses the same local transport. The bridge reports actual
|
||||
Ghidra/language/compiler/analysis/import-digest metadata and accepts only
|
||||
authenticated `ping`, `shutdown`, ten inventory methods, and twelve
|
||||
function-analysis methods. Close, cancellation, timeout, malformed protocol,
|
||||
authenticated `ping`, `shutdown`, thirteen read-only inventory/load-image methods,
|
||||
and twelve function-analysis methods. Linux/macOS also admits atomic function
|
||||
annotation changes in the ephemeral database. Close, cancellation, timeout, malformed protocol,
|
||||
or process exit stops the owned process resources, closes the socket, and
|
||||
removes the runtime root.
|
||||
|
||||
The experimental Windows transport uses authenticated IPv4 loopback with a
|
||||
token-free endpoint record, but cannot start while the native authority is
|
||||
unavailable. Its `taskkill` cleanup code does not establish Job Object ownership,
|
||||
private DACLs, or reparse-safe paths.
|
||||
token-free endpoint record. The bundled native authority establishes Job Object
|
||||
ownership, protected runtime DACLs, and handle-based path admission before
|
||||
launch. If the bundle or an admission constraint is unavailable, the provider
|
||||
remains unavailable; a `taskkill` fallback does not establish that authority.
|
||||
|
||||
The provider catalog lists the 25 Ghidra operations. GUI cursor,
|
||||
navigation, and mutation operations remain absent; the router therefore
|
||||
The provider catalog lists 25 read-only Ghidra operations and the Linux/macOS
|
||||
session annotation operation. GUI cursor/navigation and persistent mutations
|
||||
remain unavailable; Windows P0 admits no database mutation. The router therefore
|
||||
reports them unavailable instead of borrowing Hopper semantics or inferring
|
||||
capability from a successful import.
|
||||
|
||||
|
|
@ -144,8 +150,8 @@ request cancellation and lifecycle-deadline cleanup, bounded stdout and stderr r
|
|||
exact byte counts, process-exit diagnostics, and bounded TERM-to-KILL shutdown.
|
||||
Reusable fixtures exercise exit, timeout, cancellation, graceful termination,
|
||||
forced termination, double-close, spawn failure, and resource release. Windows
|
||||
process-tree termination code exists, but the missing Job Object and private
|
||||
runtime controls prevent it from establishing an available Ghidra session.
|
||||
Ghidra uses its native Job Object, private runtime, and path-admission boundary;
|
||||
generic process-tree termination alone cannot establish provider availability.
|
||||
|
||||
The foundation does not define a bridge schema, socket framing, health payload,
|
||||
analysis model, or shutdown acknowledgement. Hopper keeps its authenticated
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
{
|
||||
"manifest_id": "ecm_18ee96f3c7c08df6a29b2075b8dadf6e7053e88c52a65cecb35aea374112cbc6",
|
||||
"manifest_id": "ecm_167568fa66903a8f654d2673326fe628791d29d08aa1436fa73cc02080357180",
|
||||
"verifier": {
|
||||
"id": "rea-managed-conformance",
|
||||
"version": "1"
|
||||
|
|
@ -13,7 +13,7 @@
|
|||
"skill_digests": [
|
||||
{
|
||||
"skill_id": "reverse-engineer-anything",
|
||||
"sha256": "f72e03be44a47ba176e6aac47c85e930fe1fe5723b650dacbd5873f28a3b3f8f"
|
||||
"sha256": "12f60e9ee66325b3918d093aa8d3e081e44004875d0cce55b5c644d0cb3a06f5"
|
||||
}
|
||||
],
|
||||
"claims": [
|
||||
|
|
|
|||
|
|
@ -1,7 +1,11 @@
|
|||
# Windows Ghidra P0
|
||||
|
||||
Status: experimental Windows x64 support for the read-only P0 boundary. The
|
||||
published package bundles native process, filesystem, and DACL controls. REA
|
||||
This guide describes repository main. npm 4.0.1 does not include the Windows
|
||||
native bundle; check the [release boundary](installation.md#released-package-and-main)
|
||||
before applying these instructions to a published package.
|
||||
|
||||
Status: experimental Windows x64 support for the read-only P0 boundary. Windows
|
||||
package builds bundle native process, filesystem, and DACL controls. REA
|
||||
uses them automatically when the analyst selects a Ghidra operation; no
|
||||
additional permission flag or degraded mode is required.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,5 +1,9 @@
|
|||
import type { ProductCatalog } from "./product-catalog.mjs";
|
||||
|
||||
export function skillReferenceIssues(
|
||||
skillRoot: string,
|
||||
): Promise<readonly string[]>;
|
||||
|
||||
export function documentationFactIssues(
|
||||
root: string,
|
||||
catalog: ProductCatalog,
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
import { readFile } from "node:fs/promises";
|
||||
import { join } from "node:path";
|
||||
import { readFile, readdir, stat } from "node:fs/promises";
|
||||
import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
|
||||
|
||||
const README_PATHS = [
|
||||
"README.md",
|
||||
|
|
@ -28,9 +28,49 @@ const requireText = (issues, path, content, expected) => {
|
|||
if (!content.includes(expected)) issues.push(`${path}: missing ${expected}`);
|
||||
};
|
||||
|
||||
/** Check that local Markdown references travel with an installed skill bundle. */
|
||||
export const skillReferenceIssues = async (skillRoot) => {
|
||||
const issues = [];
|
||||
const paths = (await readdir(skillRoot, { recursive: true }))
|
||||
.filter((path) => path.endsWith(".md"))
|
||||
.sort();
|
||||
for (const path of paths) {
|
||||
const content = await readFile(join(skillRoot, path), "utf8");
|
||||
for (const match of content.matchAll(/\[[^\]\n]*\]\(([^)\s]+)\)/gu)) {
|
||||
const destination = match[1];
|
||||
if (/^(?:https?:\/\/|mailto:|#)/u.test(destination)) continue;
|
||||
const target = resolve(
|
||||
dirname(join(skillRoot, path)),
|
||||
destination.split("#")[0],
|
||||
);
|
||||
const withinBundle = relative(resolve(skillRoot), target);
|
||||
if (
|
||||
withinBundle === ".." ||
|
||||
withinBundle.startsWith(`..${sep}`) ||
|
||||
isAbsolute(withinBundle)
|
||||
) {
|
||||
issues.push(
|
||||
`${path}: reference escapes installed skill bundle: ${destination}`,
|
||||
);
|
||||
continue;
|
||||
}
|
||||
try {
|
||||
if (!(await stat(target)).isFile())
|
||||
issues.push(`${path}: reference is not a file: ${destination}`);
|
||||
} catch (cause) {
|
||||
if (cause?.code !== "ENOENT") throw cause;
|
||||
issues.push(`${path}: missing skill reference: ${destination}`);
|
||||
}
|
||||
}
|
||||
}
|
||||
return issues;
|
||||
};
|
||||
|
||||
/** Return every caller-visible documentation mismatch against canonical facts. */
|
||||
export const documentationFactIssues = async (root, catalog) => {
|
||||
const issues = [];
|
||||
const issues = await skillReferenceIssues(
|
||||
join(root, "skills/reverse-engineer-anything"),
|
||||
);
|
||||
const expectedCounts = catalog.tools.families.map(({ count }) => count);
|
||||
for (const path of README_PATHS) {
|
||||
const content = await readFile(join(root, path), "utf8");
|
||||
|
|
|
|||
|
|
@ -2,11 +2,12 @@ import {
|
|||
lstat,
|
||||
mkdir,
|
||||
readFile,
|
||||
readdir,
|
||||
rm,
|
||||
symlink,
|
||||
writeFile,
|
||||
} from "node:fs/promises";
|
||||
import { join } from "node:path";
|
||||
import { dirname, join } from "node:path";
|
||||
|
||||
import { spawn } from "@lydell/node-pty";
|
||||
|
||||
|
|
@ -19,6 +20,7 @@ import {
|
|||
runWithStatus,
|
||||
} from "./lib/verify-package-core.mjs";
|
||||
import { parse as parseJsonc } from "jsonc-parser";
|
||||
import { skillReferenceIssues } from "./lib/docs-facts.mjs";
|
||||
|
||||
const OPENCODE_ORIGINAL = `{
|
||||
// OpenCode preferences must survive setup.
|
||||
|
|
@ -473,19 +475,23 @@ const assertSkill = async ({ skillPath, siblingSkillPath, root }) => {
|
|||
);
|
||||
if (skill !== canonicalSkill)
|
||||
throw new Error("packaged skill did not match its canonical source");
|
||||
const installedReference = await readFile(
|
||||
join(skillPath, "..", "references/javascript-applications.md"),
|
||||
"utf8",
|
||||
);
|
||||
const canonicalReference = await readFile(
|
||||
join(
|
||||
root,
|
||||
"skills/reverse-engineer-anything/references/javascript-applications.md",
|
||||
),
|
||||
"utf8",
|
||||
);
|
||||
if (installedReference !== canonicalReference)
|
||||
throw new Error("packaged skill references did not match canonical source");
|
||||
const canonicalRoot = join(root, "skills/reverse-engineer-anything");
|
||||
for (const reference of await readdir(join(canonicalRoot, "references"))) {
|
||||
const installed = await readFile(
|
||||
join(dirname(skillPath), "references", reference),
|
||||
"utf8",
|
||||
);
|
||||
const canonical = await readFile(
|
||||
join(canonicalRoot, "references", reference),
|
||||
"utf8",
|
||||
);
|
||||
if (installed !== canonical)
|
||||
throw new Error(
|
||||
`packaged skill reference did not match canonical source: ${reference}`,
|
||||
);
|
||||
}
|
||||
const issues = await skillReferenceIssues(dirname(skillPath));
|
||||
if (issues.length > 0) throw new Error(issues.join("\n"));
|
||||
if ((await readFile(siblingSkillPath, "utf8")) !== "unrelated skill\n")
|
||||
throw new Error("packaged skill installation modified a sibling skill");
|
||||
};
|
||||
|
|
|
|||
|
|
@ -1,8 +1,8 @@
|
|||
---
|
||||
name: reverse-engineer-anything
|
||||
description: Reverse engineer native, managed, Electron/JavaScript, packaged, and browser applications with REA. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.
|
||||
description: Reverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.
|
||||
metadata:
|
||||
version: "24"
|
||||
version: "25"
|
||||
tool_count: 125
|
||||
catalog_digest: "297aced29e7ce5e845c505d5f2e9e2dee42b7ed3e628f088f424fe8088c9e8dc"
|
||||
---
|
||||
|
|
@ -15,17 +15,80 @@ behavior not established by available source. For ordinary analysis of a
|
|||
complete source repository, use normal repository tools and do not run REA
|
||||
readiness or provider commands.
|
||||
|
||||
## Connect only when needed
|
||||
|
||||
Installing this skill supplies instructions; it does not register the REA MCP
|
||||
server, install analysis engines, or add tools to an already-running agent.
|
||||
|
||||
If REA tools are available and their registration is not known to be stale,
|
||||
proceed directly to the target. Do not run diagnostics or setup before every
|
||||
investigation. Use the connected server's actual tool list and input schemas;
|
||||
a skill installed from repository main may describe capabilities absent from
|
||||
an older npm release. Keep complete inline Evidence when that server does not
|
||||
advertise retained references.
|
||||
|
||||
When tools are absent or registration is stale:
|
||||
|
||||
1. Diagnose without changing files. For Codex, run
|
||||
`npx -y rea-agents@latest doctor --client codex --json`. Substitute the current
|
||||
supported client: `claude_code`, `claude_desktop`, `codex`, `cursor`,
|
||||
`gemini_cli`, `windsurf`, `devin`, `opencode`, `antigravity`, `copilot_cli`,
|
||||
`commandcode`, or `vscode`. If the client is unknown, use `doctor --json` and
|
||||
inspect its registration results before choosing a setup scope.
|
||||
2. Distinguish the reason. Missing, malformed, or stale registration needs a
|
||||
scoped configuration repair. An aligned registration with no tools in the
|
||||
active session needs a restart/reconnection; doctor cannot prove that the
|
||||
current agent has connected. A missing provider affects only tasks requiring
|
||||
that provider: static JavaScript inspection needs neither Hopper nor Ghidra,
|
||||
and Android inspection has separate bring-your-own JADX/Java prerequisites.
|
||||
3. For a configuration repair, prepare the read-only plan:
|
||||
`npx -y rea-agents@latest setup --client codex --dry-run --json`.
|
||||
Use the current client's ID, show its exact proposed paths, backups, and
|
||||
changes, and obtain approval before setup writes configuration or installs
|
||||
Hopper. Setup normally installs the matching bundled skill too; include that
|
||||
replacement in the reviewed plan. After approval, apply the same scope with
|
||||
`npx -y rea-agents@latest setup --client codex --yes`. Add `--install-hopper`
|
||||
only if that separate installation was needed and explicitly approved.
|
||||
4. Restart/reconnect the affected agent. Verify that REA tools actually appear
|
||||
in the session, then resume the original investigation. If they remain
|
||||
absent, inspect the client's MCP launch error rather than repeating setup.
|
||||
|
||||
REA setup never installs or upgrades Node.js, npm, Homebrew, Java, Ghidra,
|
||||
JADX, Binwalk, or Unblob. Use existing prerequisites; do not install unrelated
|
||||
software to repair
|
||||
MCP registration. For an unsupported client, use manual stdio registration
|
||||
with a version-pinned `rea-agents` package or continue through the CLI.
|
||||
|
||||
A concrete CLI fallback for an operator-supplied JavaScript tree or ASAR is:
|
||||
|
||||
```bash
|
||||
npx -y rea-agents@latest analyze-javascript-application /absolute/path/to/app --json
|
||||
```
|
||||
|
||||
No MCP registration or native engine is required. Read the returned Evidence,
|
||||
graph, limitations, and unknowns with the same care as an MCP result; the CLI
|
||||
returns the Evidence record directly. This fallback does not establish that
|
||||
MCP is configured. Native CLI tasks still require their selected engine.
|
||||
|
||||
## Route the target first
|
||||
|
||||
Choose the first tool from the target the user supplied. Do not call
|
||||
`open_binary` unless the target is native or an analysis database.
|
||||
Choose the first tool from the target the user supplied. Use `open_binary` for
|
||||
active-target native or archive workflows; target-free tools take their own
|
||||
explicit path or endpoint and do not need it.
|
||||
|
||||
- ASAR or extracted JavaScript/Electron tree:
|
||||
`analyze_javascript_application`.
|
||||
- Archive, application package, ZIP/APK/IPA/MSIX/AppX, or DMG:
|
||||
- Archive/package member inventory (ZIP/APK/IPA/MSIX/AppX or DMG):
|
||||
`open_binary` with the supplied local path; use `inspect_artifact` when its
|
||||
graph and findings help answer the question.
|
||||
- Android APK code, classes, methods, or incoming references:
|
||||
`inspect_android_package`, then focused Android tools when advertised.
|
||||
Archive member inventory still uses the archive route above.
|
||||
- Managed PE/CLI assembly: `inspect_managed_artifact`.
|
||||
- Firmware image: `inspect_firmware_regions` when advertised. Use
|
||||
`extract_firmware` when extraction is requested, with a caller-selected new
|
||||
absolute output directory. These tools use caller-supplied Binwalk/Unblob on
|
||||
Linux; see the [firmware guide](https://github.com/morluto/rea/blob/main/docs/firmware-analysis.md).
|
||||
- User-owned browser page already open: `list_browser_targets`.
|
||||
- User-owned Electron runtime already open: `list_electron_targets`.
|
||||
- Native executable, library, or analysis database: `open_binary`, then
|
||||
|
|
@ -37,10 +100,10 @@ name to one clear installed artifact when possible; ask only when matches are
|
|||
ambiguous. Never choose an example app on the user's behalf.
|
||||
|
||||
In a target-free session, use `open_binary` to bind any archive/package or
|
||||
native target whose analysis tool operates on the active target. Do not call a
|
||||
tool hidden from `tools/list`; inspect `binary_session` with
|
||||
`detail: "capabilities"` for the exact remediation when a desired capability
|
||||
is unavailable.
|
||||
native target whose analysis tool operates on the active target. Do not call an
|
||||
unadvertised tool; inspect `binary_session` with `{}` and its
|
||||
`result.tool_availability` for availability reasons and remediation. The tool
|
||||
list stays complete; availability depends on the operation, target, and host.
|
||||
|
||||
## Work summary-first
|
||||
|
||||
|
|
@ -98,23 +161,13 @@ as complete while required questions remain open.
|
|||
[references/native-and-artifacts.md](references/native-and-artifacts.md)
|
||||
- ASARs, extracted JavaScript, feature tracing, and version comparison:
|
||||
[references/javascript-applications.md](references/javascript-applications.md)
|
||||
- Android APK declarations, classes, methods, and static references:
|
||||
[references/android-applications.md](references/android-applications.md)
|
||||
- Passive browser/Electron observation and static/runtime reconciliation:
|
||||
[references/runtime-observation.md](references/runtime-observation.md)
|
||||
- Evidence paging, comparisons, residual unknowns, and verification:
|
||||
[references/evidence-workflows.md](references/evidence-workflows.md)
|
||||
|
||||
## Readiness and setup
|
||||
|
||||
The readiness rule is conditional: when REA tools are available and their
|
||||
registration is not known to be stale, proceed directly; do not run `doctor`
|
||||
before every task. Run `npx -y rea-agents@latest doctor` when the MCP server or
|
||||
required provider is unavailable, registration is reported stale, or the user
|
||||
asks for an environment diagnosis. Propose
|
||||
`npx -y rea-agents@latest setup` only when doctor identifies an alignment or
|
||||
provider problem. Show the exact plan and obtain approval before setup writes
|
||||
configuration or installs Hopper. Restart the agent after MCP registration
|
||||
changes; direct CLI commands remain available immediately.
|
||||
|
||||
## Finish the task
|
||||
|
||||
Explain findings in plain language and tie them to returned evidence. When the
|
||||
|
|
|
|||
|
|
@ -0,0 +1,31 @@
|
|||
# Android application artifacts
|
||||
|
||||
Use the connected server's advertised Android tools. Repository main includes
|
||||
this family; npm 4.0.1 does not. A skill installation alone cannot add it to an
|
||||
older server.
|
||||
|
||||
Start with `inspect_android_package` on the caller's APK path for package
|
||||
identity, manifest declarations, coverage, and inline Evidence. Use
|
||||
`search_android_classes` to find candidates, `inspect_android_class` for one
|
||||
class's members, `inspect_android_method` for decompilation, and
|
||||
`trace_android_references` for incoming static references. Each call takes its
|
||||
own APK path and explicit selectors; do not open a native session first.
|
||||
Choose an `overload_index` from the class inventory when methods are ambiguous
|
||||
instead of guessing.
|
||||
|
||||
The provider requires a separately supplied headless JADX MCP JAR 0.7.1 and
|
||||
Java 17 or newer. `REA_JADX_MCP_JAR` selects the absolute JAR path; `JAVA_HOME`
|
||||
can select Java. REA setup does not install or configure that JAR, and doctor
|
||||
provider scopes cover Hopper/Ghidra rather than JADX. Use existing tools and
|
||||
report missing prerequisites for the Android task specifically.
|
||||
|
||||
Real verification covers Linux. macOS has the POSIX launch boundary but no
|
||||
claimed real-provider verification; Windows is unsupported. Calls use one
|
||||
worker, a bounded JVM heap, and provider deadlines. The APK is never launched,
|
||||
and no emulator is required.
|
||||
|
||||
Manifest entries and decompiled text are static observations, not execution or
|
||||
policy enforcement. Incoming references are recovered static relationships;
|
||||
reflection, dynamic loading, and unresolved calls remain unknown. Preserve
|
||||
artifact digests, locations, diagnostics, and incomplete coverage. For archive
|
||||
members rather than code analysis, use `open_binary` and `inspect_artifact`.
|
||||
|
|
@ -15,7 +15,9 @@ registration, defaults, or policy enforcement from static analysis.
|
|||
|
||||
Use `trace_application_feature` on existing application Evidence for one
|
||||
literal node ID, route, string, API, IPC channel, module, or native export.
|
||||
Choose a direction and include the complete application Evidence inline. Include
|
||||
Choose a direction and reuse the returned application Evidence ID when the
|
||||
connected server advertises retained references, or supply complete Evidence
|
||||
inline. Include
|
||||
Hopper or Ghidra Evidence only when its artifact digest matches exactly.
|
||||
|
||||
For version comparison, analyze each version once, then call
|
||||
|
|
@ -27,7 +29,8 @@ opposite-side coverage; otherwise report unknown.
|
|||
When the question asks how one exact exported callable's returned object shape
|
||||
changed, analyze each version once and then call
|
||||
`compare_javascript_export_shapes` with explicit module paths and export names.
|
||||
Include the complete Evidence records from both analysis calls. Accept variant
|
||||
Use the returned IDs on the same connection, or complete inline Evidence
|
||||
records, from both analysis calls. Accept variant
|
||||
pairing only through the tool's unique exact literal discriminant. Cite the
|
||||
comparison Evidence and report JSON Pointer changes; dynamic values, ambiguous
|
||||
variants, and incomplete parent-property coverage stay unknown. This is static
|
||||
|
|
@ -37,9 +40,12 @@ through the available browser, Electron, or process workflows.
|
|||
|
||||
## Reusing application Evidence
|
||||
|
||||
Application trace and compare tools accept complete inline Evidence or
|
||||
When advertised by the connected server, application trace and compare tools
|
||||
accept complete inline Evidence or
|
||||
`{"kind":"retained-evidence","evidence_id":"ev_<64 lowercase hex characters>"}`
|
||||
for their application input (`application`, or `left`/`right`). Use the exact ID
|
||||
for their application input (`application`, or `left`/`right`). This notation is
|
||||
a template: replace it with the actual returned ID. npm 4.0.1 accepts only full
|
||||
inline Evidence. Use the exact ID
|
||||
returned by the producer on the same MCP connection. Resolution does not run
|
||||
analysis or select a provider; findings remain inline. Native observation
|
||||
arrays still take full Evidence. `close_binary` clears retained references;
|
||||
|
|
|
|||
|
|
@ -59,7 +59,7 @@ separate filesystem-writing operation.
|
|||
For headerless DOS COM, explicitly open with `format: "dos-com"` (CLI
|
||||
`--target-format dos-com`). Inspect the load image before trusting function
|
||||
analysis: the entry is `0x10100`, file offset zero, with imposed real-mode segment
|
||||
context. PSP/stack/device state remains unmodeled. See [DOS guide](../../../docs/ghidra-dos.md).
|
||||
context. PSP/stack/device state remains unmodeled. See [DOS guide](https://github.com/morluto/rea/blob/main/docs/ghidra-dos.md).
|
||||
|
||||
### Function annotations in Ghidra
|
||||
|
||||
|
|
|
|||
|
|
@ -24,13 +24,13 @@ const runSessionStatus = async (
|
|||
}
|
||||
};
|
||||
|
||||
/** List complete provider identities, capabilities, and availability. */
|
||||
/** List binary-session provider candidates and auxiliary operation availability. */
|
||||
export const runProviderStatus = (
|
||||
logger: Logger = silentLogger,
|
||||
environment: Readonly<Record<string, string | undefined>> = process.env,
|
||||
) => runSessionStatus(logger, environment);
|
||||
|
||||
/** List complete operation descriptors and availability. */
|
||||
/** List binary-session operation descriptors; this is not the full MCP catalog. */
|
||||
export const runCapabilityStatus = (
|
||||
logger: Logger = silentLogger,
|
||||
environment: Readonly<Record<string, string | undefined>> = process.env,
|
||||
|
|
|
|||
|
|
@ -8,6 +8,7 @@ const SKILL_FILES = [
|
|||
"SKILL.md",
|
||||
"references/native-and-artifacts.md",
|
||||
"references/javascript-applications.md",
|
||||
"references/android-applications.md",
|
||||
"references/runtime-observation.md",
|
||||
"references/evidence-workflows.md",
|
||||
] as const;
|
||||
|
|
|
|||
|
|
@ -5,5 +5,5 @@ export const PACKAGE_METADATA = {
|
|||
serverSdkVersion: "2.3.1",
|
||||
clientSdkVersion: "2.3.1",
|
||||
coreSdkVersion: "2.3.1",
|
||||
skillVersion: "24",
|
||||
skillVersion: "25",
|
||||
} as const;
|
||||
|
|
|
|||
|
|
@ -1,5 +1,6 @@
|
|||
import { rm, writeFile } from "node:fs/promises";
|
||||
import { readFile, rm, writeFile } from "node:fs/promises";
|
||||
import { join } from "node:path";
|
||||
import { fileURLToPath } from "node:url";
|
||||
|
||||
import { execFile } from "node:child_process";
|
||||
import { promisify } from "node:util";
|
||||
|
|
@ -32,6 +33,58 @@ const fixture = async (): Promise<string> => {
|
|||
return root;
|
||||
};
|
||||
|
||||
describe("documented process CLI workflow", () => {
|
||||
it(
|
||||
"feeds the documented JSON capture into the comparison CLI",
|
||||
async () => {
|
||||
const root = await fixture();
|
||||
const guide = await readFile(
|
||||
new URL("../../../docs/process-capture.md", import.meta.url),
|
||||
"utf8",
|
||||
);
|
||||
const recipe = /```sh\nrea capture-process ([^\n]+)\n```/u.exec(
|
||||
guide,
|
||||
)?.[1];
|
||||
if (recipe === undefined)
|
||||
throw new Error("Missing process capture recipe");
|
||||
const [argumentsText, output] = recipe.split(" > ");
|
||||
if (argumentsText === undefined || output === undefined)
|
||||
throw new Error("Missing process capture redirection");
|
||||
const args = argumentsText.split(/\s+/u);
|
||||
const input = args[0];
|
||||
if (input === undefined) throw new Error("Missing scenario path");
|
||||
await writeFile(
|
||||
join(root, input),
|
||||
JSON.stringify({
|
||||
executable: process.execPath,
|
||||
arguments: ["-e", "process.stdout.write('documented-capture')"],
|
||||
}),
|
||||
);
|
||||
const cli = fileURLToPath(
|
||||
new URL("../../../scripts/rea.mjs", import.meta.url),
|
||||
);
|
||||
const capture = await execFileAsync(
|
||||
process.execPath,
|
||||
[cli, "capture-process", ...args],
|
||||
{ cwd: root },
|
||||
);
|
||||
expect(JSON.parse(capture.stdout)).toMatchObject({
|
||||
operation: "capture_process_scenario",
|
||||
});
|
||||
await writeFile(join(root, output), capture.stdout);
|
||||
const comparison = await execFileAsync(
|
||||
process.execPath,
|
||||
[cli, "compare-process-captures", output, output, "--json"],
|
||||
{ cwd: root },
|
||||
);
|
||||
expect(JSON.parse(comparison.stdout)).toMatchObject({
|
||||
operation: "compare_process_captures",
|
||||
});
|
||||
},
|
||||
CLI_INTEGRATION_TIMEOUT_MS,
|
||||
);
|
||||
});
|
||||
|
||||
describe("process CLI errors", () => {
|
||||
it(
|
||||
"exits unsuccessfully without writing failure-shaped evidence",
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
import { readFile, rm, writeFile } from "node:fs/promises";
|
||||
import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
|
||||
import { join } from "node:path";
|
||||
import { fileURLToPath } from "node:url";
|
||||
|
||||
|
|
@ -40,6 +40,7 @@ import { NATIVE_MACOS_PROVIDER_IDENTITY } from "../../../src/native/NativeMacOSP
|
|||
import {
|
||||
assertDocumentationFacts,
|
||||
documentationFactIssues,
|
||||
skillReferenceIssues,
|
||||
} from "../../../scripts/lib/docs-facts.mjs";
|
||||
import { ensureGeneratedFile } from "../../../scripts/lib/generated-file.mjs";
|
||||
import {
|
||||
|
|
@ -63,6 +64,24 @@ afterEach(async () => {
|
|||
});
|
||||
|
||||
describe("canonical product catalog", () => {
|
||||
it("admits the documented minimal browser scenario through the named contract", async () => {
|
||||
const guide = await readFile(
|
||||
join(root, "docs/browser-scenario-contract.md"),
|
||||
"utf8",
|
||||
);
|
||||
const example = /```json\n([\s\S]*?)\n```/u.exec(guide)?.[1];
|
||||
if (example === undefined)
|
||||
throw new Error("Missing browser scenario example");
|
||||
const contract = TOOL_CONTRACTS.find(
|
||||
({ name }) => name === "capture_browser_scenario",
|
||||
);
|
||||
if (contract === undefined)
|
||||
throw new Error("Missing browser scenario contract");
|
||||
expect(contract.inputSchema.safeParse(JSON.parse(example)).success).toBe(
|
||||
true,
|
||||
);
|
||||
});
|
||||
|
||||
it("matches every source-derived checked-in product fact", async () => {
|
||||
const catalog = await createProductCatalog(root);
|
||||
expect(catalog.tools.total).toBe(TOOL_CONTRACTS.length);
|
||||
|
|
@ -198,6 +217,27 @@ describe("canonical CLI catalog", () => {
|
|||
});
|
||||
|
||||
describe("canonical product catalog drift", () => {
|
||||
it("rejects missing and repository-only links in an independently installed skill", async () => {
|
||||
const directory = await createTestTempDirectory("rea-skill-references-");
|
||||
const bundle = join(directory, "skill");
|
||||
await mkdir(bundle);
|
||||
await writeFile(join(directory, "repo-only.md"), "Repository-only guide");
|
||||
await writeFile(join(bundle, "local.md"), "Bundled guide");
|
||||
await writeFile(
|
||||
join(bundle, "SKILL.md"),
|
||||
[
|
||||
"[bundled](local.md#guide)",
|
||||
"[missing](missing.md)",
|
||||
"[repository-only](../repo-only.md)",
|
||||
"[public](https://example.test/guide)",
|
||||
].join("\n"),
|
||||
);
|
||||
expect(await skillReferenceIssues(bundle)).toEqual([
|
||||
"SKILL.md: missing skill reference: missing.md",
|
||||
"SKILL.md: reference escapes installed skill bundle: ../repo-only.md",
|
||||
]);
|
||||
});
|
||||
|
||||
it("reports tool-family and setup-client fact drift", async () => {
|
||||
const catalog = await createProductCatalog(root);
|
||||
const firstFamily = catalog.tools.families[0];
|
||||
|
|
|
|||
|
|
@ -9,6 +9,7 @@ import {
|
|||
} from "../../../src/application/SetupSkill.js";
|
||||
import { TOOL_CONTRACTS } from "../../../src/contracts/toolContracts.js";
|
||||
import { PRODUCT_IDENTITY } from "../../../src/identity.js";
|
||||
import { skillReferenceIssues } from "../../../scripts/lib/docs-facts.mjs";
|
||||
|
||||
describe("canonical skill transaction", () => {
|
||||
it("backs up and upgrades a stale managed skill without touching siblings", async () => {
|
||||
|
|
@ -54,6 +55,8 @@ describe("canonical skill transaction", () => {
|
|||
);
|
||||
for (const reference of [
|
||||
"native-and-artifacts.md",
|
||||
"javascript-applications.md",
|
||||
"android-applications.md",
|
||||
"runtime-observation.md",
|
||||
"evidence-workflows.md",
|
||||
]) {
|
||||
|
|
@ -92,5 +95,6 @@ describe("canonical skill transaction", () => {
|
|||
).toContain("analyze_javascript_application");
|
||||
expect(await canonicalSkillNeedsInstall(home)).toBe(false);
|
||||
expect(await installCanonicalSkill(home)).toBe("unchanged");
|
||||
expect(await skillReferenceIssues(dirname(destination))).toEqual([]);
|
||||
});
|
||||
});
|
||||
|
|
|
|||
Loading…
Reference in New Issue