Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
feat(cli): add guided local onboarding
morluto8ca3db829f90
diff --git a/package-lock.json b/package-lock.jsonindex 71647255b..d9f718a1b 100644--- a/package-lock.json+++ b/package-lock.json@@ -9,6 +9,7 @@"version": "0.1.0","dependencies": {"@modelcontextprotocol/server": "2.0.0-beta.3",+ "incur": "0.4.13","zod": "4.4.3"},"bin": {@@ -28,6 +29,12 @@"node": ">=20"}},+ "node_modules/@cfworker/json-schema": {+ "version": "4.1.1",+ "resolved": "https://registry.npmjs.org/@cfworker/json-schema/-/json-schema-4.1.1.tgz",+ "integrity": "sha512-gAmrUZSGtKc3AiBL71iNWxDsyUC5uMaKKGdvzYsBoTW/xi42JQHl7eKV2OYzCUqvc+D2RCcf7EXY2iCyFIk6og==",+ "license": "MIT"+ },"node_modules/@emnapi/core": {"version": "1.11.1","resolved": "https://registry.npmjs.org/@emnapi/core/-/core-1.11.1.tgz",@@ -602,6 +609,15 @@"dev": true,"license": "MIT"},+ "node_modules/@scalar/openapi-types": {+ "version": "0.8.0",+ "resolved": "https://registry.npmjs.org/@scalar/openapi-types/-/openapi-types-0.8.0.tgz",+ "integrity": "sha512-WmaxVSfvY5K/TwcG2B2TU1WOe1As1uc2s7myswtP6dBlcjU3hM08SApxv/jmyGaCE8t4gO5BBhmHY4pDUfmr2g==",+ "license": "MIT",+ "engines": {+ "node": ">=22"+ }+ },"node_modules/@standard-schema/spec": {"version": "1.1.0","resolved": "https://registry.npmjs.org/@standard-schema/spec/-/spec-1.1.0.tgz",@@ -609,6 +625,12 @@"dev": true,"license": "MIT"},+ "node_modules/@toon-format/toon": {+ "version": "2.3.0",+ "resolved": "https://registry.npmjs.org/@toon-format/toon/-/toon-2.3.0.tgz",+ "integrity": "sha512-/Ew9etdRQKVMnm9fDaCG0JjyAOK/O7T0M97oum1aW4W+UR8ZhVVPBanIV7oWgHBiGlnVxV9M55PWQCHofDV07w==",+ "license": "MIT"+ },"node_modules/@tybys/wasm-util": {"version": "0.10.3","resolved": "https://registry.npmjs.org/@tybys/wasm-util/-/wasm-util-0.10.3.tgz",@@ -1646,6 +1668,28 @@"node": ">=0.8.19"}},+ "node_modules/incur": {+ "version": "0.4.13",+ "resolved": "https://registry.npmjs.org/incur/-/incur-0.4.13.tgz",+ "integrity": "sha512-BeKlYFLIsRCgC8IxsUd3S2/4kPeZaNf1Rbz+Kz41jQII4jOgr7j5w4KYe00aAEQa3V0Ur57BVxE5JDTx8L2s5Q==",+ "license": "MIT",+ "dependencies": {+ "@cfworker/json-schema": "^4.1.1",+ "@modelcontextprotocol/server": "^2.0.0-alpha.2",+ "@scalar/openapi-types": "^0.8.0",+ "@toon-format/toon": "^2.1.0",+ "tokenx": "^1.3.0",+ "yaml": "^2.8.2",+ "zod": "^4.3.6"+ },+ "bin": {+ "incur": "dist/bin.js",+ "incur.src": "src/bin.ts"+ },+ "engines": {+ "node": ">=22"+ }+ },"node_modules/is-extglob": {"version": "2.1.1","resolved": "https://registry.npmjs.org/is-extglob/-/is-extglob-2.1.1.tgz",@@ -2474,6 +2518,12 @@"node": ">=14.0.0"}},+ "node_modules/tokenx": {+ "version": "1.3.0",+ "resolved": "https://registry.npmjs.org/tokenx/-/tokenx-1.3.0.tgz",+ "integrity": "sha512-NLdXTEZkKiO0gZuLtMoZKjCXTREXeZZt8nnnNeyoXtNZAfG/GKGSbQtLU5STspc0rMSwcA+UJfWZkbNU01iKmQ==",+ "license": "MIT"+ },"node_modules/ts-api-utils": {"version": "2.5.0","resolved": "https://registry.npmjs.org/ts-api-utils/-/ts-api-utils-2.5.0.tgz",@@ -2774,6 +2824,21 @@"node": ">=0.10.0"}},+ "node_modules/yaml": {+ "version": "2.9.0",+ "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.9.0.tgz",+ "integrity": "sha512-2AvhNX3mb8zd6Zy7INTtSpl1F15HW6Wnqj0srWlkKLcpYl/gMIMJiyuGq2KeI2YFxUPjdlB+3Lc10seMLtL4cA==",+ "license": "ISC",+ "bin": {+ "yaml": "bin.mjs"+ },+ "engines": {+ "node": ">= 14.6"+ },+ "funding": {+ "url": "https://github.com/sponsors/eemeli"+ }+ },"node_modules/yocto-queue": {"version": "0.1.0","resolved": "https://registry.npmjs.org/yocto-queue/-/yocto-queue-0.1.0.tgz",diff --git a/package.json b/package.jsonindex 0ca1203fa..b6accb4ac 100644--- a/package.json+++ b/package.json@@ -4,11 +4,20 @@"private": true,"type": "module","bin": {+ "better-binary": "./scripts/better-binary.mjs","better-binary-mcp": "./dist/main.js"},"engines": {- "node": ">=20"+ "node": ">=22"},+ "files": [+ "dist",+ "bridge",+ "scripts/better-binary.mjs",+ "skills",+ "README.md",+ "LICENSE"+ ],"scripts": {"build": "tsc -p tsconfig.build.json","check": "npm run typecheck && npm run lint && npm run format:check && npm test",@@ -21,10 +30,12 @@"test:watch": "vitest","typecheck": "tsc --noEmit","verify:hopper": "npm run build && node scripts/verify-real-hopper.mjs",+ "verify:package": "npm run build && node scripts/verify-package.mjs","config:print": "node scripts/print-mcp-config.mjs"},"dependencies": {"@modelcontextprotocol/server": "2.0.0-beta.3",+ "incur": "0.4.13","zod": "4.4.3"},"devDependencies": {diff --git a/scripts/better-binary.mjs b/scripts/better-binary.mjsnew file mode 100644index 000000000..f621b18c6--- /dev/null+++ b/scripts/better-binary.mjs@@ -0,0 +1,64 @@+#!/usr/bin/env node++import { Cli, z } from "incur";+import { runDoctor } from "../dist/application/Doctor.js";+import { runDirectAnalysis } from "../dist/application/DirectAnalysis.js";+import { runSetup } from "../dist/application/Setup.js";+import { PRODUCT_IDENTITY } from "../dist/identity.js";++const cli = Cli.create(PRODUCT_IDENTITY.cliBinary, {+ version: "0.1.0",+ description: "Install, diagnose, and automate Hopper binary analysis.",+ mcp: {+ command: PRODUCT_IDENTITY.mcpBinary,+ instructions:+ "Open a local target with open_binary, analyze it, and close the session when finished.",+ },+ sync: {+ cwd: import.meta.dirname,+ include: ["../skills/*"],+ suggestions: [+ "open a binary and summarize it",+ "decompile a procedure",+ "diagnose my Hopper setup",+ ],+ },+});++cli.command("setup", {+ description: "Install prerequisites and configure binary analysis",+ options: z.object({+ yes: z+ .boolean()+ .default(false)+ .describe("Approve prerequisite installation"),+ }),+ alias: { yes: "y" },+ run: ({ options }) => runSetup(options.yes),+});+cli.command("doctor", {+ description: "Diagnose the local Hopper integration",+ options: z.object({+ target: z.string().optional().describe("Optional binary path to check"),+ }),+ run: ({ options }) => runDoctor(options.target),+});+cli.command("analyze", {+ description: "Analyze a binary through the beta.3 MCP server",+ args: z.object({+ path: z.string().describe("Binary or Hopper database path"),+ }),+ run: ({ args }) => runDirectAnalysis(args.path, "binary_overview", {}),+});+cli.command("decompile", {+ description: "Decompile an address through the beta.3 MCP server",+ args: z.object({+ path: z.string().describe("Binary path"),+ address: z.string().describe("Procedure address"),+ }),+ run: ({ args }) =>+ runDirectAnalysis(args.path, "procedure_pseudo_code", {+ procedure: args.address,+ }),+});+cli.serve();diff --git a/scripts/verify-package.mjs b/scripts/verify-package.mjsnew file mode 100644index 000000000..c410ec009--- /dev/null+++ b/scripts/verify-package.mjs@@ -0,0 +1,178 @@+import { execFile } from "node:child_process";+import {+ chmod,+ mkdtemp,+ mkdir,+ readFile,+ rm,+ writeFile,+} from "node:fs/promises";+import { tmpdir } from "node:os";+import { join } from "node:path";+import { promisify } from "node:util";++import { Client } from "@modelcontextprotocol/client";+import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";++const exec = promisify(execFile);+const root = process.cwd();+const workspace = await mkdtemp(join(tmpdir(), "better-binary-package-"));+let tarball;++try {+ tarball = (+ await exec("npm", ["pack", "--silent"], { cwd: root })+ ).stdout.trim();+ const prefix = join(workspace, "prefix");+ const home = join(workspace, "home");+ const fakeBin = join(workspace, "bin");+ await mkdir(fakeBin, { recursive: true });+ const brew = join(fakeBin, "brew");+ const swVers = join(fakeBin, "sw_vers");+ const npx = join(fakeBin, "npx");+ const npxLog = join(workspace, "npx.log");+ const hopper = join(workspace, "hopper");+ await writeFile(+ brew,+ '#!/bin/sh\nif [ "$1" = "--prefix" ]; then echo /fake/cask; fi\nexit 0\n',+ );+ await writeFile(swVers, "#!/bin/sh\necho 14.5\n");+ await writeFile(+ npx,+ '#!/bin/sh\nprintf "%s\\n" "$*" > "$BETTER_BINARY_NPX_LOG"\necho "│ ✓ Cursor: isolated │"\n',+ );+ await writeFile(hopper, "#!/bin/sh\nexit 0\n");+ await Promise.all([+ chmod(brew, 0o755),+ chmod(swVers, 0o755),+ chmod(hopper, 0o755),+ chmod(npx, 0o755),+ ]);+ const claudeDir = join(home, "Library/Application Support/Claude");+ const cursorDir = join(home, ".cursor");+ await Promise.all([+ mkdir(claudeDir, { recursive: true }),+ mkdir(cursorDir, { recursive: true }),+ ]);+ const claudeConfig = join(claudeDir, "claude_desktop_config.json");+ const cursorConfig = join(cursorDir, "mcp.json");+ await writeFile(claudeConfig, '{"existing":true}\n');+ await writeFile(cursorConfig, '{"existing":true}\n');+ const environment = {+ ...process.env,+ HOME: home,+ XDG_CONFIG_HOME: join(home, ".config"),+ PATH: `${fakeBin}:${process.env.PATH ?? ""}`,+ HOPPER_LAUNCHER_PATH: hopper,+ BETTER_BINARY_NPX_LOG: npxLog,+ };+ await exec(+ "npm",+ ["install", "--global", "--prefix", prefix, join(root, tarball)],+ { env: environment },+ );+ const cli = join(prefix, "bin", "better-binary");+ const mcp = join(prefix, "bin", "better-binary-mcp");+ const help = await run(cli, ["--help"], environment);+ const llms = await run(cli, ["--llms"], environment);+ const doctor = json(await run(cli, ["doctor", "--json"], environment));+ if (+ !help.includes("setup") ||+ !llms.includes("decompile") ||+ doctor.healthy !== true+ )+ throw new Error("packaged CLI discovery or doctor failed");+ await run(cli, ["mcp", "add"], environment);+ const mcpRegistration = await readFile(npxLog, "utf8");+ if (+ !mcpRegistration.includes("add-mcp better-binary-mcp --name better-binary")+ )+ throw new Error("Incur mcp add did not register the beta.3 executable");+ const first = json(await run(cli, ["setup", "--yes", "--json"], environment));+ const second = json(+ await run(cli, ["setup", "--yes", "--json"], environment),+ );+ if (+ first.status !== "ready" ||+ second.status !== "ready" ||+ second.actions.length !== 0+ )+ throw new Error("packaged setup was not ready and idempotent");+ for (const configPath of [claudeConfig, cursorConfig]) {+ const config = json(await readFile(configPath, "utf8"));+ if (+ config.existing !== true ||+ config.mcpServers?.["better-binary"]?.command !== "better-binary-mcp"+ )+ throw new Error("packaged client readback failed");+ if (+ !(await readFile(`${configPath}.better-binary.backup`, "utf8")).includes(+ "existing",+ )+ )+ throw new Error("packaged client backup failed");+ }+ const skill = await readFile(+ join(home, ".agents/skills/better-binary-analysis/SKILL.md"),+ "utf8",+ );+ if (!skill.includes("open_binary"))+ throw new Error("packaged skill readback failed");++ await writeFile(cursorConfig, "malformed");+ const failed = json(+ await run(cli, ["setup", "--yes", "--json"], environment),+ );+ if (+ failed.status !== "needs_human" ||+ (await readFile(cursorConfig, "utf8")) !== "malformed"+ )+ throw new Error("packaged setup failure recovery did not preserve input");+ await writeFile(cursorConfig, "{}\n");+ const recovered = json(+ await run(cli, ["setup", "--yes", "--json"], environment),+ );+ if (recovered.status !== "ready")+ throw new Error("packaged setup did not recover");++ const transport = new StdioClientTransport({+ command: mcp,+ env: environment,+ stderr: "pipe",+ });+ let mcpStderr = "";+ transport.stderr?.on("data", (chunk) => {+ mcpStderr += chunk.toString();+ });+ const client = new Client({ name: "package-smoke", version: "1.0.0" });+ try {+ await client.connect(transport);+ if ((await client.listTools()).tools.length !== 42)+ throw new Error("packaged MCP did not expose 42 tools");+ const result = await client.callTool({+ name: "current_document",+ arguments: {},+ });+ if (result.isError !== true)+ throw new Error("packaged target-free MCP omitted no-target error");+ } catch (cause) {+ throw new Error(`packaged MCP smoke failed: ${mcpStderr}`, { cause });+ } finally {+ await client.close();+ await transport.close();+ }++ process.stdout.write(+ `${JSON.stringify({ cli: true, incurMcpCommand: "better-binary-mcp", doctor: true, setup: "idempotent", clients: 2, backupReadback: true, failureRecovery: true, skill: true, mcpTools: 42, targetFree: true })}\n`,+ );+} finally {+ if (tarball) await rm(join(root, tarball), { force: true });+ await rm(workspace, { recursive: true, force: true });+}++async function run(command, args, env) {+ return (await exec(command, args, { env })).stdout;+}+function json(text) {+ return JSON.parse(text);+}diff --git a/skills/better-binary-analysis/SKILL.md b/skills/better-binary-analysis/SKILL.mdnew file mode 100644index 000000000..fa6c675ec--- /dev/null+++ b/skills/better-binary-analysis/SKILL.md@@ -0,0 +1,8 @@+---+name: better-binary-analysis+description: Analyze local binaries with Better Binary and Hopper through its MCP session workflow.+---++# Better Binary Analysis++Call `open_binary` with a readable local path before analysis. Begin with `binary_overview`, use strings and symbol searches to identify relevant procedures, then use `procedure_pseudo_code`, callers, callees, and xrefs to build evidence. Call `open_binary` again to switch targets and `close_binary` when finished. Never claim real-Hopper behavior from mock-only evidence.diff --git a/src/application/DirectAnalysis.ts b/src/application/DirectAnalysis.tsnew file mode 100644index 000000000..c8d23c00e--- /dev/null+++ b/src/application/DirectAnalysis.ts@@ -0,0 +1,47 @@+import { fileURLToPath } from "node:url";++import { parseConfig } from "../config.js";+import { HopperApplicationLauncher } from "../hopper/BridgeLauncher.js";+import { HopperClient } from "../hopper/HopperClient.js";+import type { JsonValue } from "../hopper/protocol.js";+import { BinarySession } from "./BinarySession.js";++/** Open one binary, execute one tool, and always release the target session. */+export const runDirectAnalysis = async (+ path: string,+ tool: "binary_overview" | "procedure_pseudo_code",+ arguments_: Readonly<Record<string, JsonValue>>,+): Promise<JsonValue> => {+ const config = parseConfig(process.env);+ if (!config.ok)+ return { error: config.error._tag, message: config.error.message };+ const bridgeScriptPath = fileURLToPath(+ new URL("../../bridge/hopper_bridge.py", import.meta.url),+ );+ const session = new BinarySession(+ (target) =>+ new HopperClient({+ launcher: new HopperApplicationLauncher({+ launcherPath: config.value.hopperLauncherPath,+ targetPath: target.path,+ targetKind: target.kind,+ loaderArgs:+ config.value.hopperLoaderArgs.length > 0+ ? config.value.hopperLoaderArgs+ : target.loaderArgs,+ bridgeScriptPath,+ }),+ }),+ );+ try {+ const opened = await session.open(path);+ if (!opened.ok)+ return { error: opened.error._tag, message: opened.error.message };+ const result = await session.callTool(tool, arguments_);+ return result.ok+ ? result.value+ : { error: result.error._tag, message: result.error.message };+ } finally {+ await session.close();+ }+};diff --git a/src/application/Doctor.ts b/src/application/Doctor.tsnew file mode 100644index 000000000..d83411553--- /dev/null+++ b/src/application/Doctor.ts@@ -0,0 +1,171 @@+import { constants } from "node:fs";+import { access } from "node:fs/promises";+import { readdir } from "node:fs/promises";+import { homedir } from "node:os";+import { join } from "node:path";+import { execFile } from "node:child_process";+import { promisify } from "node:util";++const execFileAsync = promisify(execFile);+const DEFAULT_HOPPER =+ "/Applications/Hopper Disassembler.app/Contents/MacOS/hopper";++/** One actionable environment diagnostic. */+export interface DoctorCheck {+ readonly name: string;+ readonly ok: boolean;+ readonly detail?: string;+ readonly remediation?: string;+}+/** Host facts and effects required by diagnostics. */+export interface DoctorHost {+ readonly platform: NodeJS.Platform;+ readonly nodeVersion: string;+ readonly configuredHopperPath?: string;+ macosVersion(): Promise<string | undefined>;+ readable(path: string): Promise<boolean>;+ brewHopperPath(): Promise<string | undefined>;+ manualHopperPaths(): Promise<readonly string[]>;+}++/** Check requirements and an optional target without mutating the host. */+export const runDoctor = async (+ target?: string,+ host: DoctorHost = systemDoctorHost(),+): Promise<{+ readonly healthy: boolean;+ readonly hopperPath?: string;+ readonly checks: readonly DoctorCheck[];+}> => {+ const checks: DoctorCheck[] = [];+ const nodeMajor = parseMajor(host.nodeVersion);+ checks.push(+ check(+ "node",+ nodeMajor >= 22,+ host.nodeVersion,+ "Install Node.js 22 or newer.",+ ),+ );+ const macosVersion =+ host.platform === "darwin" ? await host.macosVersion() : undefined;+ const macosMajor = macosVersion === undefined ? 0 : parseMajor(macosVersion);+ checks.push(+ check(+ "macos",+ host.platform === "darwin" && macosMajor >= 12,+ macosVersion ?? host.platform,+ "Hopper requires macOS 12 or newer.",+ ),+ );+ const candidates = [+ host.configuredHopperPath,+ DEFAULT_HOPPER,+ ...(await host.manualHopperPaths()),+ await host.brewHopperPath(),+ ].filter((value): value is string => value !== undefined);+ let hopperPath: string | undefined;+ for (const candidate of new Set(candidates))+ if (await host.readable(candidate)) {+ hopperPath = candidate;+ break;+ }+ checks.push(+ check(+ "hopper",+ hopperPath !== undefined,+ hopperPath,+ "Install Hopper with: brew install --cask hopper-disassembler, or set HOPPER_LAUNCHER_PATH.",+ ),+ );+ if (target !== undefined)+ checks.push(+ check(+ "target",+ await host.readable(target),+ target,+ "Supply a readable local binary path.",+ ),+ );+ return {+ healthy: checks.every(({ ok }) => ok),+ ...(hopperPath === undefined ? {} : { hopperPath }),+ checks,+ };+};++/** Create diagnostics backed by the current process and host commands. */+export const systemDoctorHost = (): DoctorHost => ({+ platform: process.platform,+ nodeVersion: process.versions.node,+ ...(process.env.HOPPER_LAUNCHER_PATH === undefined+ ? {}+ : { configuredHopperPath: process.env.HOPPER_LAUNCHER_PATH }),+ async macosVersion() {+ try {+ return (+ await execFileAsync("sw_vers", ["-productVersion"])+ ).stdout.trim();+ } catch {+ return undefined;+ }+ },+ async readable(path) {+ try {+ await access(path, constants.R_OK);+ return true;+ } catch {+ return false;+ }+ },+ async brewHopperPath() {+ for (const command of [+ "brew",+ "/opt/homebrew/bin/brew",+ "/usr/local/bin/brew",+ ]) {+ try {+ const prefix = (+ await execFileAsync(command, [+ "--prefix",+ "--cask",+ "hopper-disassembler",+ ])+ ).stdout.trim();+ return `${prefix}/Hopper Disassembler.app/Contents/MacOS/hopper`;+ } catch {+ // Try the next standard Homebrew executable location.+ }+ }+ return undefined;+ },+ async manualHopperPaths() {+ const roots = ["/Applications", join(homedir(), "Applications")];+ const paths: string[] = [];+ for (const root of roots) {+ try {+ for (const entry of await readdir(root, { withFileTypes: true })) {+ if (entry.isDirectory() && /^Hopper.*\.app$/i.test(entry.name))+ paths.push(join(root, entry.name, "Contents/MacOS/hopper"));+ }+ } catch {+ // A missing or unreadable optional application directory is not fatal.+ }+ }+ return paths;+ },+});++const parseMajor = (version: string): number =>+ Number.parseInt(version.split(".")[0] ?? "0", 10);+const check = (+ name: string,+ ok: boolean,+ detail: string | undefined,+ remediation: string,+): DoctorCheck => ({+ name,+ ok,+ ...(detail === undefined ? {} : { detail }),+ ...(ok ? {} : { remediation }),+});diff --git a/src/application/Setup.ts b/src/application/Setup.tsnew file mode 100644index 000000000..282b25adc--- /dev/null+++ b/src/application/Setup.ts@@ -0,0 +1,311 @@+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";++const execFileAsync = promisify(execFile);++/** A detected agent configuration owned by setup. */+export interface SetupClient {+ readonly name: string;+ readonly configPath: string;+}+/** Result of one backup/write/readback transaction. */+export type ClientConfigurationResult =+ | {+ readonly status: "unchanged" | "configured";+ readonly backupPath?: string;+ }+ | {+ readonly status: "failed";+ readonly reason: "backup" | "write" | "readback";+ };+/** Effects required by the idempotent setup workflow. */+export interface SetupHost {+ readonly platform: NodeJS.Platform;+ readonly nodeVersion: string;+ macosVersion(): Promise<string | undefined>;+ hasHomebrew(): Promise<boolean>;+ installHomebrew(): Promise<boolean>;+ hopperPath(): Promise<string | undefined>;+ installHopper(): Promise<boolean>;+ detectedClients(): Promise<readonly SetupClient[]>;+ configureClient(client: SetupClient): Promise<ClientConfigurationResult>;+ installSkill(): Promise<"installed" | "unchanged" | "failed">;+ doctor(): Promise<Awaited<ReturnType<typeof runDoctor>>>;+}+/** Structured setup outcome with actionable partial progress. */+export interface SetupResult {+ readonly status: "ready" | "needs_human";+ readonly actions: readonly string[];+ readonly clients: Readonly<Record<string, ClientConfigurationResult>>;+ readonly doctor: Awaited<ReturnType<typeof runDoctor>>;+ readonly remediation?: string;+}++/** Install prerequisites and configure every detected supported client idempotently. */+export const runSetup = async (+ yes: boolean,+ host: SetupHost = systemSetupHost(),+): Promise<SetupResult> => {+ const actions: string[] = [];+ const clients: Record<string, ClientConfigurationResult> = {};+ const fail = async (remediation: string): Promise<SetupResult> => ({+ 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");+ }+ if ((await host.hopperPath()) === undefined) {+ if (!(await host.installHopper()))+ return fail(+ "Hopper installation was interrupted; resolve the system prompt and re-run setup.",+ );+ actions.push("installed_hopper");+ }+ for (const client of await host.detectedClients()) {+ const result = await host.configureClient(client);+ 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 better-binary doctor and apply each reported remediation.",+ }),+ };+};++/** Production setup effects for macOS, Homebrew, JSON MCP clients, and the canonical skill directory. */+export const systemSetupHost = (): SetupHost => {+ 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: string,+): Promise<readonly SetupClient[]> => {+ 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: SetupClient[] = [];+ 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: SetupClient,+): Promise<ClientConfigurationResult> => {+ let document: Record<string, unknown> = {};+ let original: string | undefined;+ try {+ original = await readFile(client.configPath, "utf8");+ document = parseObject(original);+ } catch (cause: unknown) {+ if (!isMissing(cause)) return { status: "failed", reason: "readback" };+ }+ const servers = objectValue(document.mcpServers);+ const desired = { command: PRODUCT_IDENTITY.mcpBinary };+ if (+ JSON.stringify(servers[PRODUCT_IDENTITY.mcpServerKey]) ===+ JSON.stringify(desired)+ )+ return { status: "unchanged" };+ let backupPath: string | undefined;+ if (original !== undefined) {+ backupPath = `${client.configPath}.better-binary.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}.better-binary.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 = objectValue(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: string,+): Promise<"installed" | "unchanged" | "failed"> => {+ const destination = join(+ home,+ ".agents/skills",+ PRODUCT_IDENTITY.skillName,+ "SKILL.md",+ );+ const content = `---\nname: ${PRODUCT_IDENTITY.skillName}\ndescription: Analyze binaries with Better Binary and Hopper.\n---\n\nOpen a target with open_binary, begin with binary_overview, and close it when finished.\n`;+ try {+ 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: string,+ args: readonly string[],+ env?: NodeJS.ProcessEnv,+): Promise<boolean> => {+ try {+ await execFileAsync(command, args, env === undefined ? {} : { env });+ return true;+ } catch {+ return false;+ }+};+const brewSucceeds = async (args: readonly string[]): Promise<boolean> => {+ for (const command of [+ "brew",+ "/opt/homebrew/bin/brew",+ "/usr/local/bin/brew",+ ])+ if (await commandSucceeds(command, args)) return true;+ return false;+};+const major = (version: string): number =>+ Number.parseInt(version.split(".")[0] ?? "0", 10);+const exists = async (path: string): Promise<boolean> => {+ try {+ await access(path);+ return true;+ } catch {+ return false;+ }+};+const objectSchema = z.record(z.string(), z.unknown());+const objectValue = (value: unknown): Record<string, unknown> => {+ const parsed = objectSchema.safeParse(value);+ return parsed.success ? parsed.data : {};+};+const parseObject = (text: string): Record<string, unknown> =>+ objectValue(JSON.parse(text));+const isMissing = (cause: unknown): boolean =>+ cause instanceof Error && "code" in cause && cause.code === "ENOENT";+const restoreConfig = async (+ path: string,+ original: string | undefined,+): Promise<void> => {+ 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.+ }+};diff --git a/tests/doctor.test.ts b/tests/doctor.test.tsnew file mode 100644index 000000000..bda405f74--- /dev/null+++ b/tests/doctor.test.ts@@ -0,0 +1,62 @@+import { describe, expect, it } from "vitest";+import { runDoctor, type DoctorHost } from "../src/application/Doctor.js";++const host = (overrides: Partial<DoctorHost> = {}): DoctorHost => ({+ platform: "darwin",+ nodeVersion: "22.1.0",+ macosVersion: () => Promise.resolve("12.0"),+ readable: (path) => Promise.resolve(path.includes("Hopper")),+ brewHopperPath: () => Promise.resolve(undefined),+ manualHopperPaths: () => Promise.resolve([]),+ ...overrides,+});++describe("doctor", () => {+ it.each(["11.7", undefined])(+ "rejects unsupported macOS version %s",+ async (version) => {+ const result = await runDoctor(+ undefined,+ host({ macosVersion: () => Promise.resolve(version) }),+ );+ expect(result.checks.find(({ name }) => name === "macos")?.ok).toBe(+ false,+ );+ },+ );+ it("detects a manual configured Hopper before Homebrew", async () => {+ const result = await runDoctor(+ undefined,+ host({+ configuredHopperPath: "/manual/Hopper",+ readable: (path) => Promise.resolve(path === "/manual/Hopper"),+ }),+ );+ expect(result.hopperPath).toBe("/manual/Hopper");+ expect(result.healthy).toBe(true);+ });+ it("detects a Homebrew cask installed outside /Applications", async () => {+ const path =+ "/opt/homebrew/Caskroom/hopper/Hopper Disassembler.app/Contents/MacOS/hopper";+ const result = await runDoctor(+ undefined,+ host({+ readable: (candidate) => Promise.resolve(candidate === path),+ brewHopperPath: () => Promise.resolve(path),+ }),+ );+ expect(result.hopperPath).toBe(path);+ });++ it("detects a manually installed Hopper application", async () => {+ const path = "/Applications/Hopper v6.app/Contents/MacOS/hopper";+ const result = await runDoctor(+ undefined,+ host({+ readable: (candidate) => Promise.resolve(candidate === path),+ manualHopperPaths: () => Promise.resolve([path]),+ }),+ );+ expect(result.hopperPath).toBe(path);+ });+});diff --git a/tests/setup.test.ts b/tests/setup.test.tsnew file mode 100644index 000000000..e1df79cc5--- /dev/null+++ b/tests/setup.test.ts@@ -0,0 +1,161 @@+import { describe, expect, it } from "vitest";++import {+ runSetup,+ type ClientConfigurationResult,+ type SetupClient,+ type SetupHost,+} from "../src/application/Setup.js";+import type { DoctorCheck } from "../src/application/Doctor.js";++class FakeSetupHost implements SetupHost {+ readonly platform = "darwin" as const;+ readonly nodeVersion = "22.4.0";+ version: string | undefined = "14.5";+ brew = false;+ hopper: string | undefined;+ homebrewInstallSucceeds = true;+ hopperInstallSucceeds = true;+ skill: "installed" | "unchanged" | "failed" = "installed";+ clients: readonly SetupClient[] = [];+ clientResults = new Map<string, ClientConfigurationResult>();+ homebrewInstalls = 0;+ hopperInstalls = 0;+ configurations = 0;++ macosVersion = (): Promise<string | undefined> =>+ Promise.resolve(this.version);+ hasHomebrew = (): Promise<boolean> => Promise.resolve(this.brew);+ installHomebrew = (): Promise<boolean> => {+ this.homebrewInstalls += 1;+ if (this.homebrewInstallSucceeds) this.brew = true;+ return Promise.resolve(this.homebrewInstallSucceeds);+ };+ hopperPath = (): Promise<string | undefined> => Promise.resolve(this.hopper);+ installHopper = (): Promise<boolean> => {+ this.hopperInstalls += 1;+ if (this.hopperInstallSucceeds) this.hopper = "/manual/Hopper";+ return Promise.resolve(this.hopperInstallSucceeds);+ };+ detectedClients = (): Promise<readonly SetupClient[]> =>+ Promise.resolve(this.clients);+ configureClient = (+ client: SetupClient,+ ): Promise<ClientConfigurationResult> => {+ this.configurations += 1;+ return Promise.resolve(+ this.clientResults.get(client.name) ?? {+ status: "configured",+ backupPath: `${client.configPath}.backup`,+ },+ );+ };+ installSkill = (): Promise<"installed" | "unchanged" | "failed"> =>+ Promise.resolve(this.skill);+ doctor = (): Promise<{+ healthy: boolean;+ hopperPath?: string;+ checks: readonly DoctorCheck[];+ }> =>+ Promise.resolve({+ healthy: this.brew && this.hopper !== undefined,+ ...(this.hopper === undefined ? {} : { hopperPath: this.hopper }),+ checks: [],+ });+}++describe("setup workflow", () => {+ it("installs Homebrew and Hopper on a clean approved machine", async () => {+ const host = new FakeSetupHost();+ const result = await runSetup(true, host);+ expect(result.status).toBe("ready");+ expect(result.actions).toEqual([+ "installed_homebrew",+ "installed_hopper",+ "installed_skill",+ ]);+ });++ it("requires --yes before installing Homebrew", async () => {+ const host = new FakeSetupHost();+ const result = await runSetup(false, host);+ expect(result.status).toBe("needs_human");+ expect(host.homebrewInstalls).toBe(0);+ expect(result.remediation).toContain("--yes");+ });++ it("accepts existing Homebrew and manually installed Hopper", async () => {+ const host = new FakeSetupHost();+ host.brew = true;+ host.hopper = "/Applications/Manual Hopper";+ expect((await runSetup(true, host)).actions).toEqual(["installed_skill"]);+ expect(host.hopperInstalls).toBe(0);+ });++ it.each(["homebrew", "hopper"] as const)(+ "returns needs_human when %s installation is interrupted",+ async (stage) => {+ const host = new FakeSetupHost();+ if (stage === "homebrew") host.homebrewInstallSucceeds = false;+ else {+ host.brew = true;+ host.hopperInstallSucceeds = false;+ }+ const result = await runSetup(true, host);+ expect(result.status).toBe("needs_human");+ expect(result.remediation).toContain("interrupted");+ },+ );++ it("configures every detected client and reports backup paths", async () => {+ const host = new FakeSetupHost();+ host.brew = true;+ host.hopper = "/Hopper";+ host.clients = [+ { name: "claude", configPath: "/claude.json" },+ { name: "cursor", configPath: "/cursor.json" },+ ];+ const result = await runSetup(true, host);+ expect(Object.keys(result.clients)).toEqual(["claude", "cursor"]);+ expect(host.configurations).toBe(2);+ });++ it.each(["backup", "write", "readback"] as const)(+ "stops with precise remediation after a %s failure",+ async (reason) => {+ const host = new FakeSetupHost();+ host.brew = true;+ host.hopper = "/Hopper";+ host.clients = [{ name: "cursor", configPath: "/cursor.json" }];+ host.clientResults.set("cursor", { status: "failed", reason });+ const result = await runSetup(true, host);+ expect(result.status).toBe("needs_human");+ expect(result.remediation).toContain(reason);+ },+ );++ it("is idempotent on repeated setup", async () => {+ const host = new FakeSetupHost();+ host.brew = true;+ host.hopper = "/Hopper";+ host.skill = "unchanged";+ host.clients = [{ name: "cursor", configPath: "/cursor.json" }];+ host.clientResults.set("cursor", { status: "unchanged" });+ const first = await runSetup(true, host);+ const second = await runSetup(true, host);+ expect(first.actions).toEqual([]);+ expect(second.actions).toEqual([]);+ expect(host.homebrewInstalls).toBe(0);+ expect(host.hopperInstalls).toBe(0);+ });++ it.each(["11.7", undefined])(+ "rejects unsupported macOS %s before mutation",+ async (version) => {+ const host = new FakeSetupHost();+ host.version = version;+ expect((await runSetup(true, host)).status).toBe("needs_human");+ expect(host.homebrewInstalls).toBe(0);+ },+ );+});diff --git a/tests/setupConfig.test.ts b/tests/setupConfig.test.tsnew file mode 100644index 000000000..1154f74cd--- /dev/null+++ b/tests/setupConfig.test.ts@@ -0,0 +1,61 @@+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";+import { tmpdir } from "node:os";+import { join } from "node:path";+import { afterEach, describe, expect, it } from "vitest";++import { configureJsonClient } from "../src/application/Setup.js";++let directory: string | undefined;+afterEach(async () => {+ if (directory !== undefined)+ await rm(directory, { recursive: true, force: true });+ directory = undefined;+});++describe("JSON client configuration transaction", () => {+ it("preserves existing keys, creates a backup, and reads back the MCP entry", async () => {+ directory = await mkdtemp(join(tmpdir(), "bb-setup-"));+ const configPath = join(directory, "mcp.json");+ const original =+ '{"theme":"dark","mcpServers":{"other":{"command":"other"}}}\n';+ await writeFile(configPath, original);+ const result = await configureJsonClient({ name: "cursor", configPath });+ expect(result.status).toBe("configured");+ expect(await readFile(`${configPath}.better-binary.backup`, "utf8")).toBe(+ original,+ );+ expect(JSON.parse(await readFile(configPath, "utf8"))).toMatchObject({+ theme: "dark",+ mcpServers: {+ other: { command: "other" },+ "better-binary": { command: "better-binary-mcp" },+ },+ });+ });++ it("performs no write or second backup when configuration already matches", async () => {+ directory = await mkdtemp(join(tmpdir(), "bb-setup-"));+ const configPath = join(directory, "mcp.json");+ await writeFile(+ configPath,+ '{"mcpServers":{"better-binary":{"command":"better-binary-mcp"}}}\n',+ );+ expect(await configureJsonClient({ name: "cursor", configPath })).toEqual({+ status: "unchanged",+ });+ await expect(+ readFile(`${configPath}.better-binary.backup`, "utf8"),+ ).rejects.toThrow();+ });++ it("refuses malformed existing JSON without overwriting it", async () => {+ directory = await mkdtemp(join(tmpdir(), "bb-setup-"));+ const configPath = join(directory, "mcp.json");+ await writeFile(configPath, "not-json");+ expect(await configureJsonClient({ name: "cursor", configPath })).toEqual({+ status: "failed",+ reason: "readback",+ });+ expect(await readFile(configPath, "utf8")).toBe("not-json");+ });+});