rea-agents 0.2.1

package/dist/application/Setup.js

@@ -0,0 +1,240 @@
+import { access, copyFile, mkdir, readFile, rename, rm, writeFile, } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { z } from "zod";
+import { PRODUCT_IDENTITY } from "../identity.js";
+import { runDoctor, systemDoctorHost } from "./Doctor.js";
+import { probeHomebrew } from "./homebrew.js";
+const execFileAsync = promisify(execFile);
+/**
+ * Install prerequisites and configure detected clients idempotently.
+ * With `yes` false, mutations requiring consent are reported as `needs_human`;
+ * with `yes` true, external installers still fail closed if they require UI.
+ */
+export const runSetup = async (yes, host = systemSetupHost()) => {
+    const actions = [];
+    const clients = {};
+    const fail = async (remediation) => ({
+        status: "needs_human",
+        actions,
+        clients,
+        doctor: await host.doctor(),
+        remediation,
+    });
+    if (host.platform !== "darwin")
+        return fail("Hopper requires macOS 12 or newer.");
+    const macosVersion = await host.macosVersion();
+    if (macosVersion === undefined || major(macosVersion) < 12)
+        return fail("Upgrade to macOS 12 or newer.");
+    if (major(host.nodeVersion) < 22)
+        return fail("Install Node.js 22 or newer.");
+    if (!(await host.hasHomebrew())) {
+        if (!yes)
+            return fail("Re-run with --yes to install Homebrew.");
+        if (!(await host.installHomebrew()))
+            return fail("Homebrew installation was interrupted; resolve the installer prompt and re-run setup.");
+        actions.push("installed_homebrew");
+    }
+    let hopperPath = await host.hopperPath();
+    if (hopperPath === undefined) {
+        if (!yes)
+            return fail("Re-run with --yes to install Hopper.");
+        if (!(await host.installHopper()))
+            return fail("Hopper installation was interrupted; resolve the system prompt and re-run setup.");
+        actions.push("installed_hopper");
+        hopperPath = await host.hopperPath();
+        if (hopperPath === undefined)
+            return fail("Hopper installation completed but its launcher was not found.");
+    }
+    for (const client of await host.detectedClients()) {
+        const result = await host.configureClient(client, hopperPath);
+        clients[client.name] = result;
+        if (result.status === "failed")
+            return fail(`${client.name} configuration ${result.reason} verification failed; no successful configuration was reported.`);
+        if (result.status === "configured")
+            actions.push(`configured_${client.name}`);
+    }
+    const skill = await host.installSkill();
+    if (skill === "failed")
+        return fail("Agent skill installation or readback failed.");
+    if (skill === "installed")
+        actions.push("installed_skill");
+    const doctor = await host.doctor();
+    return {
+        status: doctor.healthy ? "ready" : "needs_human",
+        actions,
+        clients,
+        doctor,
+        ...(doctor.healthy
+            ? {}
+            : {
+                remediation: "Run rea doctor and apply each reported remediation.",
+            }),
+    };
+};
+/** Production setup effects for macOS, Homebrew, JSON MCP clients, and the canonical skill directory. */
+const systemSetupHost = () => {
+    const doctorHost = systemDoctorHost();
+    return {
+        platform: process.platform,
+        nodeVersion: process.versions.node,
+        macosVersion: () => doctorHost.macosVersion(),
+        hasHomebrew: () => brewSucceeds(["--version"]),
+        installHomebrew: () => commandSucceeds("/bin/bash", [
+            "-c",
+            "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)",
+        ], { ...process.env, NONINTERACTIVE: "1" }),
+        hopperPath: async () => (await runDoctor(undefined, doctorHost)).hopperPath,
+        installHopper: () => brewSucceeds(["install", "--cask", "hopper-disassembler"]),
+        detectedClients: () => detectJsonClients(homedir()),
+        configureClient: configureJsonClient,
+        installSkill: () => installCanonicalSkill(homedir()),
+        doctor: () => runDoctor(undefined, doctorHost),
+    };
+};
+const detectJsonClients = async (home) => {
+    const candidates = [
+        {
+            name: "claude_desktop",
+            configPath: join(home, "Library/Application Support/Claude/claude_desktop_config.json"),
+            marker: join(home, "Library/Application Support/Claude"),
+        },
+        {
+            name: "cursor",
+            configPath: join(home, ".cursor/mcp.json"),
+            marker: join(home, ".cursor"),
+        },
+    ];
+    const detected = [];
+    for (const candidate of candidates)
+        if (await exists(candidate.marker))
+            detected.push({ name: candidate.name, configPath: candidate.configPath });
+    return detected;
+};
+/** Back up, atomically update, and semantically read back one JSON MCP configuration. */
+export const configureJsonClient = async (client, hopperPath) => {
+    let document = {};
+    let original;
+    try {
+        original = await readFile(client.configPath, "utf8");
+        document = parseObject(original);
+    }
+    catch (cause) {
+        if (!isMissing(cause))
+            return { status: "failed", reason: "readback" };
+    }
+    let servers;
+    try {
+        servers = parseOptionalObject(document.mcpServers);
+    }
+    catch {
+        return { status: "failed", reason: "readback" };
+    }
+    const desired = {
+        command: "npx",
+        args: ["-y", PRODUCT_IDENTITY.packageName, "mcp"],
+        ...(hopperPath === undefined
+            ? {}
+            : { env: { HOPPER_LAUNCHER_PATH: hopperPath } }),
+    };
+    if (JSON.stringify(servers[PRODUCT_IDENTITY.mcpServerKey]) ===
+        JSON.stringify(desired))
+        return { status: "unchanged" };
+    let backupPath;
+    if (original !== undefined) {
+        backupPath = `${client.configPath}.rea.backup`;
+        try {
+            await copyFile(client.configPath, backupPath);
+        }
+        catch {
+            return { status: "failed", reason: "backup" };
+        }
+    }
+    document.mcpServers = {
+        ...servers,
+        [PRODUCT_IDENTITY.mcpServerKey]: desired,
+    };
+    const encoded = `${JSON.stringify(document, null, 2)}\n`;
+    const temporary = `${client.configPath}.rea.tmp`;
+    try {
+        await mkdir(dirname(client.configPath), { recursive: true });
+        await writeFile(temporary, encoded, { encoding: "utf8", mode: 0o600 });
+        await rename(temporary, client.configPath);
+    }
+    catch {
+        await rm(temporary, { force: true }).catch(() => undefined);
+        return { status: "failed", reason: "write" };
+    }
+    try {
+        const readback = parseObject(await readFile(client.configPath, "utf8"));
+        const value = parseOptionalObject(readback.mcpServers)[PRODUCT_IDENTITY.mcpServerKey];
+        if (JSON.stringify(value) !== JSON.stringify(desired)) {
+            await restoreConfig(client.configPath, original);
+            return { status: "failed", reason: "readback" };
+        }
+    }
+    catch {
+        await restoreConfig(client.configPath, original);
+        return { status: "failed", reason: "readback" };
+    }
+    return {
+        status: "configured",
+        ...(backupPath === undefined ? {} : { backupPath }),
+    };
+};
+const installCanonicalSkill = async (home) => {
+    const destination = join(home, ".agents/skills", PRODUCT_IDENTITY.skillName, "SKILL.md");
+    try {
+        const content = await readFile(new URL(`../../skills/${PRODUCT_IDENTITY.skillName}/SKILL.md`, import.meta.url), "utf8");
+        if ((await readFile(destination, "utf8").catch(() => undefined)) === content)
+            return "unchanged";
+        await mkdir(dirname(destination), { recursive: true });
+        await writeFile(destination, content, { encoding: "utf8", mode: 0o600 });
+        return (await readFile(destination, "utf8")) === content
+            ? "installed"
+            : "failed";
+    }
+    catch {
+        return "failed";
+    }
+};
+const commandSucceeds = async (command, args, env) => {
+    try {
+        await execFileAsync(command, args, env === undefined ? {} : { env });
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+const brewSucceeds = async (args) => {
+    const result = await probeHomebrew(async (command) => (await commandSucceeds(command, args)) ? true : undefined);
+    return result === true;
+};
+const major = (version) => Number.parseInt(version.split(".")[0] ?? "0", 10);
+const exists = async (path) => {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+const objectSchema = z.record(z.string(), z.unknown());
+const parseOptionalObject = (value) => value === undefined ? {} : objectSchema.parse(value);
+const parseObject = (text) => objectSchema.parse(JSON.parse(text));
+const isMissing = (cause) => cause instanceof Error && "code" in cause && cause.code === "ENOENT";
+const restoreConfig = async (path, original) => {
+    try {
+        if (original === undefined)
+            await rm(path, { force: true });
+        else
+            await writeFile(path, original, { encoding: "utf8", mode: 0o600 });
+    }
+    catch {
+        // The backup remains available for the remediation reported by setup.
+    }
+};

package/dist/application/homebrew.js

@@ -0,0 +1,19 @@
+/** Standard executable names and locations used to discover Homebrew. */
+const HOMEBREW_COMMANDS = [
+    "brew",
+    "/opt/homebrew/bin/brew",
+    "/usr/local/bin/brew",
+];
+/**
+ * Return the first defined result from standard Homebrew executables.
+ * A probe returning `undefined` means that location was unavailable or failed;
+ * other falsy values are successful results and stop discovery.
+ */
+export const probeHomebrew = async (probe) => {
+    for (const command of HOMEBREW_COMMANDS) {
+        const result = await probe(command);
+        if (result !== undefined)
+            return result;
+    }
+    return undefined;
+};

package/dist/application/runtime.js

@@ -0,0 +1,11 @@
+import { BinarySession } from "./BinarySession.js";
+import { HopperProvider } from "../hopper/HopperProvider.js";
+import { silentLogger } from "../logger.js";
+/**
+ * Compose the target-switching runtime shared directly by CLI and MCP adapters.
+ * This is the sole production wiring point for Hopper so neither adapter shells
+ * out to the other and both retain identical loader and bridge semantics.
+ */
+export const createBinarySession = (config, logger = silentLogger) => {
+    return new BinarySession(new HopperProvider(config, logger));
+};

package/dist/cli.js

@@ -0,0 +1,88 @@
+import { Cli, z } from "incur";
+import { fileURLToPath } from "node:url";
+import { runDoctor } from "./application/Doctor.js";
+import { runDirectAnalysis } from "./application/DirectAnalysis.js";
+import { runSetup } from "./application/Setup.js";
+import { PRODUCT_IDENTITY } from "./identity.js";
+import { createLogger, parseLogLevel } from "./logger.js";
+/**
+ * Build the one-shot Incur CLI without starting Hopper at import time.
+ * Analysis commands acquire and close their own sessions; bare `mcp` and
+ * `--mcp` are intercepted by the executable dispatcher before this module loads.
+ */
+export const createCli = () => {
+    const logger = createLogger("cli", process.env.REA_LOG_LEVEL === undefined
+        ? "silent"
+        : parseLogLevel(process.env.REA_LOG_LEVEL));
+    const cli = Cli.create(PRODUCT_IDENTITY.cliBinary, {
+        version: "0.1.0",
+        description: "Reverse engineer apps from your terminal or coding agent.",
+        mcp: {
+            command: PRODUCT_IDENTITY.mcpCommand,
+            instructions: "Ask which app and feature the user wants to understand, then open the app and investigate it.",
+        },
+        sync: {
+            cwd: fileURLToPath(new URL("..", import.meta.url)),
+            include: ["skills/*"],
+            suggestions: [
+                "understand how an app feature works",
+                "decompile part of an app",
+                "check my REA setup",
+            ],
+        },
+    });
+    cli.command("setup", {
+        description: "Install requirements and configure coding agents",
+        options: z.object({
+            yes: z
+                .boolean()
+                .default(false)
+                .describe("Approve prerequisite installation"),
+        }),
+        alias: { yes: "y" },
+        run: ({ options }) => logCliCommand(logger, "setup", () => runSetup(options.yes)),
+    });
+    cli.command("doctor", {
+        description: "Check whether REA is ready",
+        options: z.object({
+            target: z.string().optional().describe("Optional app path to check"),
+        }),
+        run: ({ options }) => logCliCommand(logger, "doctor", () => runDoctor(options.target)),
+    });
+    cli.command("analyze", {
+        description: "Get an overview of an app",
+        args: z.object({
+            path: z.string().describe("App, program, or Hopper database path"),
+        }),
+        run: ({ args }) => logCliCommand(logger, "analyze", () => runDirectAnalysis(args.path, "binary_overview", {}, logger)),
+    });
+    cli.command("decompile", {
+        description: "Read one part of an app as code",
+        args: z.object({
+            path: z.string().describe("App or program path"),
+            address: z.string().describe("Procedure address"),
+        }),
+        run: ({ args }) => logCliCommand(logger, "decompile", () => runDirectAnalysis(args.path, "procedure_pseudo_code", { procedure: args.address }, logger)),
+    });
+    return cli;
+};
+const logCliCommand = async (logger, command, execute) => {
+    const startedAt = performance.now();
+    try {
+        const value = await execute();
+        logger.info({
+            command,
+            durationMs: Math.round((performance.now() - startedAt) * 100) / 100,
+            status: "ok",
+        }, "CLI command completed");
+        return value;
+    }
+    catch (cause) {
+        logger.error({
+            command,
+            durationMs: Math.round((performance.now() - startedAt) * 100) / 100,
+            status: "error",
+        }, "CLI command failed");
+        throw cause;
+    }
+};

package/dist/config.js

@@ -0,0 +1,86 @@
+import { z } from "zod";
+import { ConfigurationError } from "./domain/errors.js";
+import { err, ok } from "./domain/result.js";
+const DEFAULT_HOPPER_LAUNCHER_PATH = "/Applications/Hopper Disassembler.app/Contents/MacOS/hopper";
+const environmentSchema = z.object({
+    HOPPER_LAUNCHER_PATH: z.string().min(1).optional(),
+    HOPPER_TARGET_PATH: z.string().min(1).optional(),
+    HOPPER_TARGET_KIND: z.enum(["executable", "database"]).default("executable"),
+    HOPPER_LOADER_ARGS_JSON: z.string().optional(),
+    REA_LOG_LEVEL: z
+        .enum(["trace", "debug", "info", "warn", "error", "fatal", "silent"])
+        .default("info"),
+    REA_PROCESS_CAPTURE_ENABLED: z.enum(["true", "false"]).default("false"),
+    REA_PROCESS_EXECUTABLE_ROOTS_JSON: z.string().default("[]"),
+    REA_PROCESS_WORKING_ROOTS_JSON: z.string().default("[]"),
+    REA_PROCESS_ALLOWED_ENV_JSON: z.string().default("[]"),
+});
+const parseStringArray = (encoded, name) => {
+    try {
+        const parsed = z
+            .array(z.string().min(1))
+            .max(128)
+            .safeParse(JSON.parse(encoded));
+        return parsed.success
+            ? ok(parsed.data)
+            : err(new ConfigurationError(`${name} must encode an array of strings`, {
+                cause: parsed.error,
+            }));
+    }
+    catch (cause) {
+        return err(new ConfigurationError(`${name} must be valid JSON`, { cause }));
+    }
+};
+/**
+ * Parse Hopper launcher configuration once at the composition root.
+ * Explicit loader arguments override REA's header-derived defaults for a
+ * supported target, allowing callers to refine Hopper's loader behavior without
+ * bypassing REA's path and executable-header checks.
+ */
+export const parseConfig = (environment) => {
+    const parsedEnvironment = environmentSchema.safeParse(environment);
+    if (!parsedEnvironment.success) {
+        return err(new ConfigurationError("Invalid Hopper environment configuration", {
+            cause: parsedEnvironment.error,
+        }));
+    }
+    let loaderArgs = [];
+    const encoded = parsedEnvironment.data.HOPPER_LOADER_ARGS_JSON;
+    if (encoded !== undefined) {
+        try {
+            loaderArgs = JSON.parse(encoded);
+        }
+        catch (cause) {
+            return err(new ConfigurationError("HOPPER_LOADER_ARGS_JSON must be valid JSON", {
+                cause,
+            }));
+        }
+    }
+    const parsedArgs = z.array(z.string()).safeParse(loaderArgs);
+    if (!parsedArgs.success) {
+        return err(new ConfigurationError("HOPPER_LOADER_ARGS_JSON must encode an array of strings", { cause: parsedArgs.error }));
+    }
+    const executableRoots = parseStringArray(parsedEnvironment.data.REA_PROCESS_EXECUTABLE_ROOTS_JSON, "REA_PROCESS_EXECUTABLE_ROOTS_JSON");
+    if (!executableRoots.ok)
+        return executableRoots;
+    const workingRoots = parseStringArray(parsedEnvironment.data.REA_PROCESS_WORKING_ROOTS_JSON, "REA_PROCESS_WORKING_ROOTS_JSON");
+    if (!workingRoots.ok)
+        return workingRoots;
+    const allowedEnvironment = parseStringArray(parsedEnvironment.data.REA_PROCESS_ALLOWED_ENV_JSON, "REA_PROCESS_ALLOWED_ENV_JSON");
+    if (!allowedEnvironment.ok)
+        return allowedEnvironment;
+    return ok({
+        hopperLauncherPath: parsedEnvironment.data.HOPPER_LAUNCHER_PATH ??
+            DEFAULT_HOPPER_LAUNCHER_PATH,
+        hopperTargetPath: parsedEnvironment.data.HOPPER_TARGET_PATH,
+        hopperTargetKind: parsedEnvironment.data.HOPPER_TARGET_KIND,
+        hopperLoaderArgs: parsedArgs.data,
+        logLevel: parsedEnvironment.data.REA_LOG_LEVEL,
+        processExecutionPolicy: {
+            enabled: parsedEnvironment.data.REA_PROCESS_CAPTURE_ENABLED === "true",
+            executableRoots: executableRoots.value,
+            workingRoots: workingRoots.value,
+            allowedEnvironment: allowedEnvironment.value,
+        },
+    });
+};

package/dist/contracts/enhancedInputs.js

@@ -0,0 +1,73 @@
+import { z } from "zod";
+/** Input schemas shared by MCP registration and enhanced application dispatch. */
+export const enhancedInputSchemas = {
+    swift_classes: z.object({ pattern: z.string().default("") }),
+    get_objc_classes: z.object({ pattern: z.string().default("") }),
+    get_objc_protocols: z.object({}),
+    batch_decompile: z.object({
+        addresses: z
+            .array(z.string().describe("A Hopper address"))
+            .max(20)
+            .default([]),
+    }),
+    get_call_graph: z.object({
+        address: z.string().describe("A Hopper address"),
+        direction: z.enum(["forward", "backward"]).default("forward"),
+        depth: z.number().int().min(1).max(5).default(2),
+    }),
+    analyze_swift_types: z.object({}),
+    find_xrefs_to_name: z.object({ name: z.string() }),
+    binary_overview: z.object({
+        detail: z.enum(["concise", "detailed"]).default("concise"),
+        limit: z.number().int().min(1).max(50).default(10),
+    }),
+    analyze_function: z.object({
+        procedure: z.string().describe("A procedure name or address"),
+        include_assembly: z.boolean().default(false),
+        limit: z.number().int().min(1).max(500).default(100),
+        max_pseudocode_chars: z.number().int().min(1).max(100_000).default(20_000),
+        max_instructions: z.number().int().min(1).max(5_000).default(500),
+        pseudocode_offset: z.number().int().min(0).default(0),
+        assembly_offset: z.number().int().min(0).default(0),
+        collection_offset: z
+            .object({
+            comments: z.number().int().min(0).default(0),
+            callers: z.number().int().min(0).default(0),
+            callees: z.number().int().min(0).default(0),
+            incoming_references: z.number().int().min(0).default(0),
+            outgoing_references: z.number().int().min(0).default(0),
+            referenced_strings: z.number().int().min(0).default(0),
+            referenced_names: z.number().int().min(0).default(0),
+            basic_blocks: z.number().int().min(0).default(0),
+        })
+            .default({
+            comments: 0,
+            callers: 0,
+            callees: 0,
+            incoming_references: 0,
+            outgoing_references: 0,
+            referenced_strings: 0,
+            referenced_names: 0,
+            basic_blocks: 0,
+        }),
+    }),
+    trace_feature: z.object({
+        query: z.string().min(1),
+        case_sensitive: z.boolean().default(false),
+        limit: z.number().int().min(1).max(100).default(20),
+        max_operations: z.number().int().min(1).max(100).default(20),
+    }),
+};
+/** Runtime parser for dispatching only the eight closed enhanced names. */
+export const enhancedToolNameSchema = z.enum([
+    "swift_classes",
+    "get_objc_classes",
+    "get_objc_protocols",
+    "batch_decompile",
+    "get_call_graph",
+    "analyze_swift_types",
+    "find_xrefs_to_name",
+    "binary_overview",
+    "analyze_function",
+    "trace_feature",
+]);