@ramarivera/chofi 0.1.0

package/dist/cli.js

@@ -0,0 +1,1326 @@
+#!/usr/bin/env node
+import { Command, Option } from "commander";
+import { createChofiEvent, NdjsonEventWriter } from "./events.js";
+import { discoverMobileProjectContext } from "./discovery.js";
+import { createCommandRunner, summarizeOutput } from "./executor.js";
+import { createIosRunPlan, createMaestroPlan, doctorChecks } from "./planning.js";
+import { RuntimeController } from "./runtime.js";
+import { isConfirmed, requireConfirmation } from "./safety.js";
+import { readConfig, writeConfig } from "./config.js";
+import { ChofiError, classifyError, ToolOutputError } from "./errors.js";
+class CliError extends Error {
+    exitCode;
+    phase;
+    constructor(message, exitCode, phase) {
+        super(message);
+        this.exitCode = exitCode;
+        this.phase = phase;
+    }
+}
+function createProgram(ctx, deps) {
+    const program = new Command("chofi")
+        .description("Sophia's mobile control surface")
+        .configureOutput({ writeOut: () => { }, writeErr: () => { } })
+        .exitOverride();
+    const globalJson = new Option("--json", "Emit NDJSON events (required for all commands)")
+        .makeOptionMandatory(true);
+    program.addOption(globalJson);
+    // === context ===
+    program
+        .command("context")
+        .description("Show project metadata and tool availability")
+        .action(async () => {
+        const discovered = ctx.context();
+        ctx.writer.write(createChofiEvent({
+            clock: ctx.clock,
+            event: "summary",
+            phase: "context",
+            status: "passed",
+            data: discovered
+        }));
+    });
+    // === doctor ===
+    program
+        .command("doctor")
+        .description("Run safe health checks")
+        .action(async () => {
+        const code = await runDoctorCommand({
+            clock: ctx.clock,
+            context: ctx.context(),
+            runner: ctx.runner,
+            writer: ctx.writer
+        });
+        if (code !== 0)
+            throw new CliError("", code);
+    });
+    // === plan ===
+    const planCmd = program.command("plan").description("Non-executing command plans");
+    planCmd
+        .command("run ios")
+        .description("Show what an iOS run would do")
+        .action(async () => {
+        const plan = createIosRunPlan(ctx.context());
+        emitPlan(ctx, plan);
+    });
+    planCmd
+        .command("maestro")
+        .description("Show what Maestro flows would run")
+        .action(async () => {
+        const plan = createMaestroPlan(ctx.context());
+        emitPlan(ctx, plan);
+    });
+    // === build / test / clean ===
+    const buildOpts = [
+        new Option("--scheme <scheme>", "Xcode scheme name").default(process.env.CHOFI_SCHEME, "from CHOFI_SCHEME env var"),
+        new Option("--workspace <path>", "Xcode workspace path").default(process.env.CHOFI_WORKSPACE, "from CHOFI_WORKSPACE env var"),
+        new Option("--project <path>", "Xcode project path").default(process.env.CHOFI_PROJECT, "from CHOFI_PROJECT env var"),
+        new Option("--destination <dest>", "xcodebuild destination").default(process.env.CHOFI_DESTINATION, "from CHOFI_DESTINATION env var")
+    ];
+    program
+        .command("build")
+        .description("Build the project via xcodebuild")
+        .addOption(buildOpts[0])
+        .addOption(buildOpts[1])
+        .addOption(buildOpts[2])
+        .addOption(buildOpts[3])
+        .option("--progress", "Stream build phases as they happen")
+        .action(async (options) => {
+        const scheme = options.scheme;
+        if (!scheme) {
+            ctx.writer.write(createChofiEvent({ clock: ctx.clock, event: "summary", phase: "build", status: "failed", data: { message: "--scheme is required (or set CHOFI_SCHEME)" } }));
+            throw new CliError("", 2);
+        }
+        if (options.progress) {
+            ctx.writer.write(createChofiEvent({ clock: ctx.clock, event: "command_started", phase: "build", data: { cwd: ctx.context().mobilePath, scheme } }));
+            try {
+                const c = ctx.context();
+                await ctx.runtime.buildWithProgress(c.mobilePath, scheme, (phase) => {
+                    ctx.writer.write(createChofiEvent({ clock: ctx.clock, event: "command_completed", phase: "build.progress", status: "passed", data: phase }));
+                }, { destination: options.destination, workspace: options.workspace, project: options.project });
+                ctx.writer.write(createChofiEvent({ clock: ctx.clock, event: "command_completed", phase: "build", status: "passed", data: {} }));
+            }
+            catch (error) {
+                const chofiError = error instanceof ChofiError ? error : new ChofiError(error instanceof Error ? error.message : String(error), "UNKNOWN_ERROR");
+                ctx.writer.write(createChofiEvent({ clock: ctx.clock, event: "command_failed", phase: "build", status: "failed", errorType: classifyError(chofiError).code, data: { message: chofiError.message, recoverySuggestion: classifyError(chofiError).recoverySuggestion } }));
+                throw new CliError("", 1);
+            }
+        }
+        else {
+            await runExecution({
+                clock: ctx.clock,
+                writer: ctx.writer,
+                phase: "build",
+                action: async () => {
+                    const c = ctx.context();
+                    await ctx.runtime.build(c.mobilePath, scheme, { destination: options.destination, workspace: options.workspace, project: options.project });
+                }
+            });
+        }
+    });
+    const testCmd = program
+        .command("test")
+        .description("Run tests via xcodebuild")
+        .addOption(buildOpts[0])
+        .addOption(buildOpts[1])
+        .addOption(buildOpts[2])
+        .addOption(buildOpts[3])
+        .option("--with-results", "Return structured test results via xcresulttool")
+        .option("--only <tests...>", "Run only specific tests (e.g., MyTests/LoginTests)")
+        .option("--skip <tests...>", "Skip specific tests")
+        .option("--retry", "Retry failed tests once")
+        .option("--progress", "Stream test progress in real-time")
+        .action(async (options) => {
+        const scheme = options.scheme;
+        if (!scheme) {
+            ctx.writer.write(createChofiEvent({ clock: ctx.clock, event: "summary", phase: "test", status: "failed", data: { message: "--scheme is required (or set CHOFI_SCHEME)" } }));
+            throw new CliError("", 2);
+        }
+        const testOpts = {
+            destination: options.destination,
+            workspace: options.workspace,
+            project: options.project,
+            only: options.only,
+            skip: options.skip,
+            retry: options.retry
+        };
+        if (options.progress) {
+            ctx.writer.write(createChofiEvent({ clock: ctx.clock, event: "command_started", phase: "test", data: { cwd: ctx.context().mobilePath, scheme } }));
+            try {
+                const c = ctx.context();
+                await ctx.runtime.testWithProgress(c.mobilePath, scheme, (progress) => {
+                    ctx.writer.write(createChofiEvent({ clock: ctx.clock, event: "command_completed", phase: "test.progress", status: "passed", data: progress }));
+                }, testOpts);
+                ctx.writer.write(createChofiEvent({ clock: ctx.clock, event: "command_completed", phase: "test", status: "passed", data: {} }));
+            }
+            catch (error) {
+                const chofiError = error instanceof ChofiError ? error : new ChofiError(error instanceof Error ? error.message : String(error), "UNKNOWN_ERROR");
+                ctx.writer.write(createChofiEvent({ clock: ctx.clock, event: "command_failed", phase: "test", status: "failed", errorType: classifyError(chofiError).code, data: { message: chofiError.message, recoverySuggestion: classifyError(chofiError).recoverySuggestion } }));
+                throw new CliError("", 1);
+            }
+        }
+        else if (options.withResults) {
+            ctx.writer.write(createChofiEvent({ clock: ctx.clock, event: "command_started", phase: "test", data: { cwd: ctx.context().mobilePath, scheme } }));
+            try {
+                const c = ctx.context();
+                const results = await ctx.runtime.testWithResults(c.mobilePath, scheme, testOpts);
+                ctx.writer.write(createChofiEvent({ clock: ctx.clock, event: "command_completed", phase: "test", status: "passed", data: { results } }));
+            }
+            catch (error) {
+                const chofiError = error instanceof ChofiError ? error : new ChofiError(error instanceof Error ? error.message : String(error), "UNKNOWN_ERROR");
+                ctx.writer.write(createChofiEvent({ clock: ctx.clock, event: "command_failed", phase: "test", status: "failed", errorType: classifyError(chofiError).code, data: { message: chofiError.message, recoverySuggestion: classifyError(chofiError).recoverySuggestion } }));
+                throw new CliError("", 1);
+            }
+        }
+        else {
+            await runExecution({
+                clock: ctx.clock,
+                writer: ctx.writer,
+                phase: "test",
+                action: async () => {
+                    const c = ctx.context();
+                    await ctx.runtime.test(c.mobilePath, scheme, testOpts);
+                }
+            });
+        }
+    });
+    testCmd
+        .command("discover")
+        .description("Discover test cases without running them")
+        .addOption(buildOpts[0])
+        .addOption(buildOpts[1])
+        .addOption(buildOpts[2])
+        .addOption(buildOpts[3])
+        .action(async (options) => {
+        const scheme = options.scheme;
+        if (!scheme) {
+            ctx.writer.write(createChofiEvent({ clock: ctx.clock, event: "summary", phase: "test.discover", status: "failed", data: { message: "--scheme is required (or set CHOFI_SCHEME)" } }));
+            throw new CliError("", 2);
+        }
+        await runExecution({
+            clock: ctx.clock,
+            writer: ctx.writer,
+            phase: "test.discover",
+            action: async () => {
+                const c = ctx.context();
+                const tests = await ctx.runtime.discoverTests(c.mobilePath, scheme, { destination: options.destination, workspace: options.workspace, project: options.project });
+                return { tests };
+            },
+            mapResult: (result) => ({ tests: result.tests })
+        });
+    });
+    testCmd
+        .command("results <path>")
+        .description("Parse test results from an .xcresult bundle")
+        .action(async (path) => {
+        await runExecution({
+            clock: ctx.clock,
+            writer: ctx.writer,
+            phase: "test.results",
+            action: async () => {
+                const results = await ctx.runtime.getTestResults(path);
+                return { results };
+            },
+            mapResult: (result) => ({ results: result.results })
+        });
+    });
+    program
+        .command("clean")
+        .description("Clean build artifacts via xcodebuild")
+        .addOption(buildOpts[0])
+        .addOption(buildOpts[1])
+        .addOption(buildOpts[2])
+        .option("--derived-data", "Delete DerivedData directory")
+        .option("--xcode-derived-data", "Delete Xcode DerivedData")
+        .option("--xcode-cache", "Delete Xcode cache")
+        .action(async (options) => {
+        const scheme = options.scheme;
+        if (!scheme && !options.derivedData && !options.xcodeDerivedData && !options.xcodeCache) {
+            ctx.writer.write(createChofiEvent({ clock: ctx.clock, event: "summary", phase: "clean", status: "failed", data: { message: "--scheme is required (or set CHOFI_SCHEME), or use --derived-data/--xcode-cache" } }));
+            throw new CliError("", 2);
+        }
+        await runExecution({
+            clock: ctx.clock,
+            writer: ctx.writer,
+            phase: "clean",
+            action: async () => {
+                const c = ctx.context();
+                await ctx.runtime.clean(c.mobilePath, scheme ?? "", { workspace: options.workspace, project: options.project, derivedData: options.derivedData, xcodeDerivedData: options.xcodeDerivedData, xcodeCache: options.xcodeCache });
+            }
+        });
+    });
+    // === logs ===
+    program
+        .command("logs <udid>")
+        .description("Stream logs from a device or simulator")
+        .option("--timeout <ms>", "Timeout in milliseconds", "30000")
+        .action(async (udid, options) => {
+        const timeoutMs = Number.parseInt(options.timeout, 10);
+        await runExecution({
+            clock: ctx.clock,
+            writer: ctx.writer,
+            phase: "logs.stream",
+            action: async () => {
+                const output = await ctx.runtime.streamLogs(udid, timeoutMs);
+                return { output };
+            },
+            mapResult: (result) => ({ logs: result.output })
+        });
+    });
+    // === stop ===
+    program
+        .command("stop <udid> [bundleId]")
+        .description("Terminate a running app (omit bundleId with --all to stop all)")
+        .option("--all", "Stop all running apps")
+        .option("--force", "Force kill (SIGKILL) instead of graceful termination")
+        .action(async (udid, bundleId, options) => {
+        if (options.all) {
+            await runExecution({
+                clock: ctx.clock,
+                writer: ctx.writer,
+                phase: "app.terminate-all",
+                action: async () => {
+                    await ctx.runtime.appTerminateAll(udid, options.force ?? false);
+                }
+            });
+            return;
+        }
+        if (!bundleId) {
+            ctx.writer.write(createChofiEvent({ clock: ctx.clock, event: "summary", phase: "app.terminate", status: "failed", data: { message: "bundleId is required (or use --all)" } }));
+            throw new CliError("", 2);
+        }
+        await runSimAction({
+            clock: ctx.clock,
+            runtime: ctx.runtime,
+            writer: ctx.writer,
+            phase: "app.terminate",
+            action: () => ctx.runtime.appTerminate(udid, bundleId, options.force ?? false),
+            target: udid
+        });
+    });
+    // === sim ===
+    const simCmd = program.command("sim").description("Simulator management");
+    simCmd
+        .command("list")
+        .description("List available simulators")
+        .action(async () => {
+        await runSimList({ clock: ctx.clock, runtime: ctx.runtime, writer: ctx.writer });
+    });
+    simCmd
+        .command("boot <target>")
+        .description("Boot a simulator by name or UDID")
+        .action(async (target) => {
+        await runSimAction({
+            clock: ctx.clock,
+            runtime: ctx.runtime,
+            writer: ctx.writer,
+            phase: "sim.boot",
+            action: () => ctx.runtime.simBoot(target),
+            target
+        });
+    });
+    simCmd
+        .command("shutdown <target>")
+        .description("Shutdown a simulator")
+        .action(async (target) => {
+        await runSimAction({
+            clock: ctx.clock,
+            runtime: ctx.runtime,
+            writer: ctx.writer,
+            phase: "sim.shutdown",
+            action: () => ctx.runtime.simShutdown(target),
+            target
+        });
+    });
+    simCmd
+        .command("open <target>")
+        .description("Open Simulator app for a device")
+        .action(async (target) => {
+        await runSimAction({
+            clock: ctx.clock,
+            runtime: ctx.runtime,
+            writer: ctx.writer,
+            phase: "sim.open",
+            action: () => ctx.runtime.simOpen(target),
+            target
+        });
+    });
+    simCmd
+        .command("erase <target>")
+        .description("Erase simulator contents and settings")
+        .option("--confirm", "Explicitly confirm destructive operation")
+        .option("--yes", "Alias for --confirm")
+        .action(async (target, options) => {
+        if (!options.confirm && !options.yes) {
+            ctx.writer.write(createChofiEvent({
+                clock: ctx.clock,
+                event: "summary",
+                phase: "sim.erase",
+                status: "failed",
+                data: { message: requireConfirmation("sim.erase") }
+            }));
+            throw new CliError("", 1);
+        }
+        await runSimAction({
+            clock: ctx.clock,
+            runtime: ctx.runtime,
+            writer: ctx.writer,
+            phase: "sim.erase",
+            action: () => ctx.runtime.simErase(target),
+            target
+        });
+    });
+    simCmd
+        .command("screenshot <target>")
+        .description("Take a screenshot of a simulator")
+        .option("--output <path>", "Output file path", "./screenshot.png")
+        .option("--format <format>", "Screenshot format (png/jpeg)", "png")
+        .action(async (target, options) => {
+        await runExecution({
+            clock: ctx.clock,
+            writer: ctx.writer,
+            phase: "sim.screenshot",
+            action: async () => {
+                if (options.format === "jpeg" || options.format === "jpg") {
+                    const result = await ctx.runtime.apple.screenshotToBuffer(target, "jpeg");
+                    if (result.exitCode !== 0) {
+                        throw new ToolOutputError("simctl", result.stderr || "Screenshot failed");
+                    }
+                    return { outputPath: options.output, data: result.stdout };
+                }
+                await ctx.runtime.simScreenshot(target, options.output);
+                return { outputPath: options.output };
+            },
+            mapResult: (result) => ({ outputPath: result.outputPath })
+        });
+    });
+    simCmd
+        .command("create <name> <deviceType> <runtime>")
+        .description("Create a new simulator")
+        .action(async (name, deviceType, runtime) => {
+        await runExecution({
+            clock: ctx.clock,
+            writer: ctx.writer,
+            phase: "sim.create",
+            action: async () => {
+                const udid = await ctx.runtime.simCreate(name, deviceType, runtime);
+                return { udid };
+            },
+            mapResult: (result) => ({ udid: result.udid })
+        });
+    });
+    simCmd
+        .command("delete <target>")
+        .description("Delete a simulator")
+        .option("--confirm", "Explicitly confirm destructive operation")
+        .option("--yes", "Alias for --confirm")
+        .action(async (target, options) => {
+        if (!options.confirm && !options.yes) {
+            ctx.writer.write(createChofiEvent({
+                clock: ctx.clock,
+                event: "summary",
+                phase: "sim.delete",
+                status: "failed",
+                data: { message: requireConfirmation("sim.delete") }
+            }));
+            throw new CliError("", 1);
+        }
+        await runSimAction({
+            clock: ctx.clock,
+            runtime: ctx.runtime,
+            writer: ctx.writer,
+            phase: "sim.delete",
+            action: () => ctx.runtime.simDelete(target),
+            target
+        });
+    });
+    simCmd
+        .command("prune")
+        .description("Delete unavailable simulators")
+        .option("--confirm", "Explicitly confirm destructive operation")
+        .option("--yes", "Alias for --confirm")
+        .action(async (options) => {
+        if (!options.confirm && !options.yes) {
+            ctx.writer.write(createChofiEvent({
+                clock: ctx.clock,
+                event: "summary",
+                phase: "sim.prune",
+                status: "failed",
+                data: { message: requireConfirmation("sim.prune") }
+            }));
+            throw new CliError("", 1);
+        }
+        await runSimAction({
+            clock: ctx.clock,
+            runtime: ctx.runtime,
+            writer: ctx.writer,
+            phase: "sim.prune",
+            action: () => ctx.runtime.simPrune(),
+            target: "unavailable"
+        });
+    });
+    simCmd
+        .command("runtime")
+        .description("List available simulator runtimes")
+        .action(async () => {
+        await runExecution({
+            clock: ctx.clock,
+            writer: ctx.writer,
+            phase: "sim.runtime",
+            action: async () => {
+                const runtimes = await ctx.runtime.simRuntimeList();
+                return { runtimes };
+            },
+            mapResult: (result) => ({ runtimes: result.runtimes })
+        });
+    });
+    simCmd
+        .command("device-types")
+        .description("List available simulator device types")
+        .action(async () => {
+        await runExecution({
+            clock: ctx.clock,
+            writer: ctx.writer,
+            phase: "sim.device-types",
+            action: async () => {
+                const types = await ctx.runtime.simDeviceTypeList();
+                return { types };
+            },
+            mapResult: (result) => ({ types: result.types })
+        });
+    });
+    simCmd
+        .command("clone <source> <name>")
+        .description("Clone a simulator")
+        .action(async (source, name) => {
+        await runExecution({
+            clock: ctx.clock,
+            writer: ctx.writer,
+            phase: "sim.clone",
+            action: async () => {
+                const udid = await ctx.runtime.simClone(source, name);
+                return { udid };
+            },
+            mapResult: (result) => ({ udid: result.udid })
+        });
+    });
+    simCmd
+        .command("clear-cache <target>")
+        .description("Clear simulator caches")
+        .action(async (target) => {
+        await runSimAction({
+            clock: ctx.clock,
+            runtime: ctx.runtime,
+            writer: ctx.writer,
+            phase: "sim.clear-cache",
+            action: () => ctx.runtime.simClearCache(target),
+            target
+        });
+    });
+    simCmd
+        .command("set-appearance <target> <appearance>")
+        .description("Set simulator appearance (dark/light)")
+        .action(async (target, appearance) => {
+        if (appearance !== "dark" && appearance !== "light") {
+            ctx.writer.write(createChofiEvent({ clock: ctx.clock, event: "summary", phase: "sim.set-appearance", status: "failed", data: { message: "appearance must be 'dark' or 'light'" } }));
+            throw new CliError("", 2);
+        }
+        await runSimAction({
+            clock: ctx.clock,
+            runtime: ctx.runtime,
+            writer: ctx.writer,
+            phase: "sim.set-appearance",
+            action: () => ctx.runtime.simSetAppearance(target, appearance),
+            target
+        });
+    });
+    simCmd
+        .command("record <udid>")
+        .description("Record simulator video")
+        .option("--output <path>", "Output file path", "./recording.mp4")
+        .option("--duration <seconds>", "Recording duration in seconds", "10")
+        .action(async (udid, options) => {
+        await runExecution({
+            clock: ctx.clock,
+            writer: ctx.writer,
+            phase: "sim.record",
+            action: async () => {
+                await ctx.runtime.simStartRecording(udid, options.output);
+                const durationMs = Number.parseInt(options.duration, 10) * 1000;
+                await new Promise((resolve) => setTimeout(resolve, durationMs));
+                await ctx.runtime.simStopRecording(udid);
+                return { outputPath: options.output };
+            },
+            mapResult: (result) => ({ outputPath: result.outputPath })
+        });
+    });
+    simCmd
+        .command("add-media <udid> <paths...>")
+        .description("Add photos/videos to simulator Photos app")
+        .action(async (udid, paths) => {
+        await runSimAction({
+            clock: ctx.clock,
+            runtime: ctx.runtime,
+            writer: ctx.writer,
+            phase: "sim.add-media",
+            action: () => ctx.runtime.simAddMedia(udid, paths),
+            target: udid
+        });
+    });
+    // === device ===
+    const deviceCmd = program.command("device").description("Physical device management");
+    deviceCmd
+        .command("list")
+        .description("List physical devices")
+        .option("--platform <platform>", "Filter by platform (iOS, watchOS)")
+        .action(async (options) => {
+        await runExecution({
+            clock: ctx.clock,
+            writer: ctx.writer,
+            phase: "device.list",
+            action: async () => {
+                const devices = await ctx.runtime.deviceList(options.platform);
+                return { devices };
+            },
+            mapResult: (result) => ({ devices: result.devices })
+        });
+    });
+    // === apps ===
+    const appsCmd = program.command("apps").description("App management");
+    appsCmd
+        .command("list <udid>")
+        .description("List running apps on a simulator/device")
+        .action(async (udid) => {
+        await runExecution({
+            clock: ctx.clock,
+            writer: ctx.writer,
+            phase: "apps.list",
+            action: async () => {
+                const apps = await ctx.runtime.appListRunning(udid);
+                return { apps };
+            },
+            mapResult: (result) => ({ apps: result.apps })
+        });
+    });
+    appsCmd
+        .command("prune <udid>")
+        .description("Remove stale/uninstalled app entries from registry")
+        .action(async (udid) => {
+        await runExecution({
+            clock: ctx.clock,
+            writer: ctx.writer,
+            phase: "apps.prune",
+            action: async () => {
+                const apps = await ctx.runtime.appListRunning(udid);
+                const pruned = apps.filter((a) => a.pid > 0);
+                return { pruned: pruned.length };
+            },
+            mapResult: (result) => ({ pruned: result.pruned })
+        });
+    });
+    // === app ===
+    const appCmd = program.command("app").description("App lifecycle on simulator/device");
+    appCmd
+        .command("install <udid> <appPath>")
+        .description("Install app on simulator/device")
+        .action(async (udid, appPath) => {
+        await runSimAction({
+            clock: ctx.clock,
+            runtime: ctx.runtime,
+            writer: ctx.writer,
+            phase: "app.install",
+            action: () => ctx.runtime.appInstall(udid, appPath),
+            target: udid
+        });
+    });
+    appCmd
+        .command("launch <udid> <bundleId>")
+        .description("Launch app on simulator/device")
+        .action(async (udid, bundleId) => {
+        await runSimAction({
+            clock: ctx.clock,
+            runtime: ctx.runtime,
+            writer: ctx.writer,
+            phase: "app.launch",
+            action: () => ctx.runtime.appLaunch(udid, bundleId),
+            target: udid
+        });
+    });
+    appCmd
+        .command("terminate <udid> <bundleId>")
+        .description("Terminate app on simulator/device")
+        .option("--force", "Force kill (SIGKILL)")
+        .action(async (udid, bundleId, options) => {
+        await runSimAction({
+            clock: ctx.clock,
+            runtime: ctx.runtime,
+            writer: ctx.writer,
+            phase: "app.terminate",
+            action: () => ctx.runtime.appTerminate(udid, bundleId, options.force ?? false),
+            target: udid
+        });
+    });
+    appCmd
+        .command("uninstall <udid> <bundleId>")
+        .description("Uninstall app from simulator/device")
+        .action(async (udid, bundleId) => {
+        await runSimAction({
+            clock: ctx.clock,
+            runtime: ctx.runtime,
+            writer: ctx.writer,
+            phase: "app.uninstall",
+            action: () => ctx.runtime.appUninstall(udid, bundleId),
+            target: udid
+        });
+    });
+    // === project ===
+    const projectCmd = program.command("project").description("Project introspection");
+    projectCmd
+        .command("build-config")
+        .description("List available build configurations")
+        .addOption(buildOpts[1])
+        .addOption(buildOpts[2])
+        .action(async (options) => {
+        await runExecution({
+            clock: ctx.clock,
+            writer: ctx.writer,
+            phase: "project.build-config",
+            action: async () => {
+                const c = ctx.context();
+                const configs = await ctx.runtime.projectBuildConfigs(c.mobilePath, { workspace: options.workspace, project: options.project });
+                return { configs };
+            },
+            mapResult: (result) => ({ configs: result.configs })
+        });
+    });
+    projectCmd
+        .command("schemes")
+        .description("Auto-detect available schemes")
+        .addOption(buildOpts[1])
+        .addOption(buildOpts[2])
+        .action(async (options) => {
+        await runExecution({
+            clock: ctx.clock,
+            writer: ctx.writer,
+            phase: "project.schemes",
+            action: async () => {
+                const c = ctx.context();
+                const schemes = await ctx.runtime.detectSchemes(c.mobilePath, { workspace: options.workspace, project: options.project });
+                return { schemes };
+            },
+            mapResult: (result) => ({ schemes: result.schemes })
+        });
+    });
+    // === run ===
+    const runCmd = program.command("run").description("Run the app on a platform");
+    runCmd
+        .command("ios")
+        .description("Run iOS app (requires --confirm)")
+        .option("--confirm", "Explicitly confirm")
+        .option("--yes", "Alias for --confirm")
+        .option("--no-build", "Skip build, launch existing app")
+        .option("--launch-env <env...>", "Environment variables for launch (KEY=VALUE)")
+        .action(async (options) => {
+        if (!options.confirm && !options.yes) {
+            ctx.writer.write(createChofiEvent({
+                clock: ctx.clock,
+                event: "summary",
+                phase: "run.ios",
+                status: "failed",
+                data: { message: requireConfirmation("run.ios") }
+            }));
+            throw new CliError("", 1);
+        }
+        await runExecution({
+            clock: ctx.clock,
+            writer: ctx.writer,
+            phase: "run.ios",
+            action: async () => {
+                const c = ctx.context();
+                if (!options.noBuild) {
+                    await ctx.runtime.prebuild(c.repoRoot, "ios");
+                }
+                await ctx.runtime.runExpoIos(c.mobilePath);
+            }
+        });
+    });
+    runCmd
+        .command("android")
+        .description("Run Android app (requires --confirm)")
+        .option("--confirm", "Explicitly confirm")
+        .option("--yes", "Alias for --confirm")
+        .action(async (options) => {
+        if (!options.confirm && !options.yes) {
+            ctx.writer.write(createChofiEvent({
+                clock: ctx.clock,
+                event: "summary",
+                phase: "run.android",
+                status: "failed",
+                data: { message: requireConfirmation("run.android") }
+            }));
+            throw new CliError("", 1);
+        }
+        await runExecution({
+            clock: ctx.clock,
+            writer: ctx.writer,
+            phase: "run.android",
+            action: async () => {
+                const c = ctx.context();
+                await ctx.runtime.prebuild(c.repoRoot, "android");
+                await ctx.runtime.runExpoAndroid(c.mobilePath);
+            }
+        });
+    });
+    // === maestro ===
+    const maestroCmd = program.command("maestro").description("Maestro UI automation");
+    maestroCmd
+        .command("check")
+        .description("Check Maestro installation")
+        .action(async () => {
+        const availability = ctx.context().maestro;
+        writeToolCheck(ctx.writer, ctx.clock, availability);
+        if (availability.status !== "available") {
+            throw new CliError("", 1);
+        }
+    });
+    maestroCmd
+        .command("run <flow>")
+        .description("Run a Maestro flow")
+        .action(async (flow) => {
+        await runExecution({
+            clock: ctx.clock,
+            writer: ctx.writer,
+            phase: "maestro.run",
+            action: async () => {
+                const c = ctx.context();
+                await ctx.runtime.runMaestroTest(flow, { cwd: c.repoRoot });
+            }
+        });
+    });
+    maestroCmd
+        .command("continuous <flow>")
+        .description("Run a Maestro flow in continuous mode")
+        .action(async (flow) => {
+        await runExecution({
+            clock: ctx.clock,
+            writer: ctx.writer,
+            phase: "maestro.continuous",
+            action: async () => {
+                const c = ctx.context();
+                await ctx.runtime.runMaestroContinuous(flow, { cwd: c.repoRoot });
+            }
+        });
+    });
+    maestroCmd
+        .command("hierarchy")
+        .description("Get UI hierarchy")
+        .action(async () => {
+        await runExecution({
+            clock: ctx.clock,
+            writer: ctx.writer,
+            phase: "maestro.hierarchy",
+            action: async () => {
+                const c = ctx.context();
+                const output = await ctx.runtime.runMaestroHierarchy({ cwd: c.repoRoot });
+                return { output };
+            },
+            mapResult: (result) => ({ hierarchy: result.output })
+        });
+    });
+    maestroCmd
+        .command("record <flow>")
+        .description("Record a Maestro flow")
+        .action(async (flow) => {
+        await runExecution({
+            clock: ctx.clock,
+            writer: ctx.writer,
+            phase: "maestro.record",
+            action: async () => {
+                const c = ctx.context();
+                await ctx.runtime.runMaestroRecord(flow, { cwd: c.repoRoot });
+            }
+        });
+    });
+    maestroCmd
+        .command("driver-setup")
+        .description("Setup Maestro driver")
+        .action(async () => {
+        await runExecution({
+            clock: ctx.clock,
+            writer: ctx.writer,
+            phase: "maestro.driver-setup",
+            action: async () => {
+                const c = ctx.context();
+                await ctx.runtime.maestroDriverSetup(c.repoRoot);
+            }
+        });
+    });
+    maestroCmd
+        .command("start-device")
+        .description("Start a simulator or emulator for Maestro")
+        .option("--platform <platform>", "Platform: ios or android")
+        .option("--device <device>", "Device identifier")
+        .action(async (options) => {
+        await runExecution({
+            clock: ctx.clock,
+            writer: ctx.writer,
+            phase: "maestro.start-device",
+            action: async () => {
+                const c = ctx.context();
+                await ctx.runtime.maestroStartDevice({
+                    cwd: c.repoRoot,
+                    platform: options.platform,
+                    device: options.device
+                });
+            }
+        });
+    });
+    // === idb ===
+    const idbCmd = program.command("idb").description("idb integration — accessibility, UI, crashes, permissions, location");
+    idbCmd
+        .command("accessibility <udid>")
+        .description("Dump accessibility tree via idb")
+        .option("--point <x,y>", "Describe element at point (format: x,y)")
+        .action(async (udid, options) => {
+        await runExecution({
+            clock: ctx.clock,
+            writer: ctx.writer,
+            phase: "idb.accessibility",
+            action: async () => {
+                if (options.point) {
+                    const [x, y] = options.point.split(",").map(Number);
+                    const element = await ctx.runtime.idbDescribePoint(udid, x, y);
+                    return { element };
+                }
+                const tree = await ctx.runtime.idbDescribeAll(udid);
+                return { tree };
+            },
+            mapResult: (result) => (options.point ? result.element : result.tree)
+        });
+    });
+    idbCmd
+        .command("tap <udid> <x> <y>")
+        .description("Tap at screen coordinates via idb")
+        .action(async (udid, x, y) => {
+        await runExecution({
+            clock: ctx.clock,
+            writer: ctx.writer,
+            phase: "idb.tap",
+            action: async () => {
+                await ctx.runtime.idbTap(udid, Number(x), Number(y));
+            }
+        });
+    });
+    idbCmd
+        .command("swipe <udid> <x1> <y1> <x2> <y2>")
+        .description("Swipe from point to point via idb")
+        .action(async (udid, x1, y1, x2, y2) => {
+        await runExecution({
+            clock: ctx.clock,
+            writer: ctx.writer,
+            phase: "idb.swipe",
+            action: async () => {
+                await ctx.runtime.idbSwipe(udid, Number(x1), Number(y1), Number(x2), Number(y2));
+            }
+        });
+    });
+    idbCmd
+        .command("button <udid> <button>")
+        .description("Press a hardware button via idb (home, volume_up, volume_down, lock)")
+        .action(async (udid, button) => {
+        await runExecution({
+            clock: ctx.clock,
+            writer: ctx.writer,
+            phase: "idb.button",
+            action: async () => {
+                await ctx.runtime.idbPressButton(udid, button);
+            }
+        });
+    });
+    idbCmd
+        .command("text <udid> <text>")
+        .description("Input text via idb")
+        .action(async (udid, text) => {
+        await runExecution({
+            clock: ctx.clock,
+            writer: ctx.writer,
+            phase: "idb.text",
+            action: async () => {
+                await ctx.runtime.idbInputText(udid, text);
+            }
+        });
+    });
+    idbCmd
+        .command("crash-list <udid>")
+        .description("List crash logs via idb")
+        .action(async (udid) => {
+        await runExecution({
+            clock: ctx.clock,
+            writer: ctx.writer,
+            phase: "idb.crash-list",
+            action: async () => {
+                const crashes = await ctx.runtime.idbListCrashes(udid);
+                return { crashes };
+            },
+            mapResult: (result) => ({ crashes: result.crashes })
+        });
+    });
+    idbCmd
+        .command("crash-show <udid> <name>")
+        .description("Show crash log contents via idb")
+        .action(async (udid, name) => {
+        await runExecution({
+            clock: ctx.clock,
+            writer: ctx.writer,
+            phase: "idb.crash-show",
+            action: async () => {
+                const content = await ctx.runtime.idbShowCrash(udid, name);
+                return { content };
+            },
+            mapResult: (result) => ({ content: result.content })
+        });
+    });
+    idbCmd
+        .command("approve <udid> <bundleId> <permissions...>")
+        .description("Approve permissions via idb (photos, camera, contacts, url, location, notification)")
+        .action(async (udid, bundleId, permissions) => {
+        await runExecution({
+            clock: ctx.clock,
+            writer: ctx.writer,
+            phase: "idb.approve",
+            action: async () => {
+                await ctx.runtime.idbApprove(udid, bundleId, permissions);
+            }
+        });
+    });
+    idbCmd
+        .command("location <udid> <latitude> <longitude>")
+        .description("Set simulator location via idb")
+        .action(async (udid, latitude, longitude) => {
+        await runExecution({
+            clock: ctx.clock,
+            writer: ctx.writer,
+            phase: "idb.location",
+            action: async () => {
+                await ctx.runtime.idbSetLocation(udid, Number(latitude), Number(longitude));
+            }
+        });
+    });
+    idbCmd
+        .command("focus <udid>")
+        .description("Bring simulator window to front via idb")
+        .action(async (udid) => {
+        await runExecution({
+            clock: ctx.clock,
+            writer: ctx.writer,
+            phase: "idb.focus",
+            action: async () => {
+                await ctx.runtime.idbFocus(udid);
+            }
+        });
+    });
+    // === config ===
+    const configCmd = program.command("config").description("Configuration management");
+    configCmd
+        .command("get <key>")
+        .description("Get a config value")
+        .action(async (key) => {
+        const c = ctx.context();
+        const config = readConfig(c.repoRoot);
+        const value = config[key];
+        ctx.writer.write(createChofiEvent({
+            clock: ctx.clock,
+            event: "summary",
+            phase: "config.get",
+            status: "passed",
+            data: { key, value }
+        }));
+    });
+    configCmd
+        .command("set <key> <value>")
+        .description("Set a config value")
+        .action(async (key, value) => {
+        const c = ctx.context();
+        const config = readConfig(c.repoRoot);
+        const updated = { ...config, [key]: value };
+        writeConfig(c.repoRoot, updated);
+        ctx.writer.write(createChofiEvent({
+            clock: ctx.clock,
+            event: "summary",
+            phase: "config.set",
+            status: "passed",
+            data: { key, value }
+        }));
+    });
+    configCmd
+        .command("reset")
+        .description("Reset config to defaults")
+        .option("--confirm", "Explicitly confirm destructive operation")
+        .option("--yes", "Alias for --confirm")
+        .action(async (options) => {
+        if (!options.confirm && !options.yes) {
+            ctx.writer.write(createChofiEvent({
+                clock: ctx.clock,
+                event: "summary",
+                phase: "config.reset",
+                status: "failed",
+                data: { message: requireConfirmation("config.reset") }
+            }));
+            throw new CliError("", 1);
+        }
+        const c = ctx.context();
+        writeConfig(c.repoRoot, {});
+        ctx.writer.write(createChofiEvent({
+            clock: ctx.clock,
+            event: "summary",
+            phase: "config.reset",
+            status: "passed",
+            data: {}
+        }));
+    });
+    return program;
+}
+export async function runChofiCli(argv, dependencies = {}) {
+    const writer = dependencies.writer ?? new NdjsonEventWriter();
+    const clock = dependencies.clock;
+    const runtime = dependencies.runtime ??
+        new RuntimeController({ spawner: dependencies.spawner });
+    const context = () => discoverMobileProjectContext({
+        cwd: dependencies.cwd,
+        pathEnv: dependencies.pathEnv,
+        toolChecker: dependencies.toolChecker
+    });
+    const ctx = {
+        clock,
+        runtime,
+        writer,
+        context,
+        runner: dependencies.runner ?? createCommandRunner(dependencies.spawner)
+    };
+    const program = createProgram(ctx, dependencies);
+    try {
+        await program.parseAsync(argv, { from: "user" });
+        return 0;
+    }
+    catch (error) {
+        if (error instanceof CliError) {
+            return error.exitCode;
+        }
+        if (error instanceof Error && "exitCode" in error && typeof error.exitCode === "number") {
+            const isMissingJson = error.message.includes("required option '--json'");
+            const code = isMissingJson ? 2 : error.exitCode === 1 && error.message.includes("unknown command") ? 2 : error.exitCode;
+            writer.write(createChofiEvent({
+                clock,
+                event: "summary",
+                phase: "usage",
+                status: "failed",
+                data: {
+                    message: isMissingJson
+                        ? "chofi requires --json for every command. Example: chofi context --json"
+                        : error.message
+                }
+            }));
+            return code;
+        }
+        writer.write(createChofiEvent({
+            clock,
+            event: "summary",
+            phase: "usage",
+            status: "failed",
+            data: { message: String(error) }
+        }));
+        return 2;
+    }
+}
+function emitPlan(ctx, plan) {
+    ctx.writer.write(createChofiEvent({
+        clock: ctx.clock,
+        event: "plan",
+        phase: plan.phase,
+        status: "planned",
+        data: plan
+    }));
+    ctx.writer.write(createChofiEvent({
+        clock: ctx.clock,
+        event: "summary",
+        phase: plan.phase,
+        status: "planned",
+        data: {
+            commandCount: plan.commands.length,
+            notes: plan.notes
+        }
+    }));
+}
+async function runDoctorCommand(input) {
+    const checks = [];
+    for (const command of doctorChecks(input.context)) {
+        input.writer.write(createChofiEvent({
+            clock: input.clock,
+            event: "command_started",
+            phase: "doctor",
+            data: commandStartedData(command)
+        }));
+        const result = await input.runner(command);
+        const status = result.exitCode === 0 ? "passed" : "failed";
+        checks.push({
+            name: command.name,
+            status,
+            exitCode: result.exitCode,
+            durationMs: result.durationMs
+        });
+        input.writer.write(createChofiEvent({
+            clock: input.clock,
+            event: result.exitCode === 0 ? "command_completed" : "command_failed",
+            phase: "doctor",
+            status,
+            data: {
+                ...commandStartedData(command),
+                durationMs: result.durationMs,
+                exitCode: result.exitCode,
+                stderr: summarizeOutput(result.stderr),
+                stdout: summarizeOutput(result.stdout)
+            }
+        }));
+    }
+    const status = checks.every((check) => check.exitCode === 0)
+        ? "passed"
+        : "failed";
+    input.writer.write(createChofiEvent({
+        clock: input.clock,
+        event: "summary",
+        phase: "doctor",
+        status,
+        data: { checks }
+    }));
+    return status === "passed" ? 0 : 1;
+}
+async function runSimList(input) {
+    try {
+        const devices = await input.runtime.simList();
+        input.writer.write(createChofiEvent({
+            clock: input.clock,
+            event: "summary",
+            phase: "sim.list",
+            status: "passed",
+            data: { devices }
+        }));
+        return 0;
+    }
+    catch (error) {
+        input.writer.write(createChofiEvent({
+            clock: input.clock,
+            event: "summary",
+            phase: "sim.list",
+            status: "failed",
+            data: { message: String(error) }
+        }));
+        return 1;
+    }
+}
+async function runSimAction(input) {
+    input.writer.write(createChofiEvent({
+        clock: input.clock,
+        event: "command_started",
+        phase: input.phase,
+        data: { target: input.target }
+    }));
+    try {
+        await input.action();
+        input.writer.write(createChofiEvent({
+            clock: input.clock,
+            event: "command_completed",
+            phase: input.phase,
+            status: "passed",
+            data: { target: input.target }
+        }));
+        return 0;
+    }
+    catch (error) {
+        input.writer.write(createChofiEvent({
+            clock: input.clock,
+            event: "command_failed",
+            phase: input.phase,
+            status: "failed",
+            data: { target: input.target, message: String(error) }
+        }));
+        return 1;
+    }
+}
+async function runExecution(input) {
+    input.writer.write(createChofiEvent({
+        clock: input.clock,
+        event: "command_started",
+        phase: input.phase,
+        data: {}
+    }));
+    try {
+        const result = await input.action();
+        const data = input.mapResult ? input.mapResult(result) : {};
+        input.writer.write(createChofiEvent({
+            clock: input.clock,
+            event: "command_completed",
+            phase: input.phase,
+            status: "passed",
+            data
+        }));
+        input.writer.write(createChofiEvent({
+            clock: input.clock,
+            event: "summary",
+            phase: input.phase,
+            status: "passed",
+            data
+        }));
+        return 0;
+    }
+    catch (error) {
+        const chofiError = classifyError(error);
+        const errorData = {
+            message: chofiError.message,
+            recoverySuggestion: chofiError.recoverySuggestion
+        };
+        input.writer.write(createChofiEvent({
+            clock: input.clock,
+            event: "command_failed",
+            phase: input.phase,
+            status: "failed",
+            errorType: chofiError.code,
+            data: errorData
+        }));
+        input.writer.write(createChofiEvent({
+            clock: input.clock,
+            event: "summary",
+            phase: input.phase,
+            status: "failed",
+            errorType: chofiError.code,
+            data: errorData
+        }));
+        throw new CliError(chofiError.message, 1);
+    }
+}
+function commandStartedData(command) {
+    return {
+        name: command.name,
+        command: command.command,
+        args: command.args,
+        cwd: command.cwd
+    };
+}
+function writeToolCheck(writer, clock, availability) {
+    const status = availability.status === "available" ? "available" : "missing";
+    writer.write(createChofiEvent({
+        clock,
+        event: "tool_checked",
+        phase: "maestro.check",
+        status,
+        data: availability
+    }));
+    writer.write(createChofiEvent({
+        clock,
+        event: "summary",
+        phase: "maestro.check",
+        status,
+        data: { maestro: availability }
+    }));
+}
+if (import.meta.url === `file://${process.argv[1]}`) {
+    process.exitCode = await runChofiCli(process.argv.slice(2));
+}