appduct 0.9.0

package/dist/cli/open-target.js

@@ -0,0 +1,438 @@
+/**
+ * Emulator/simulator fast path (ARCHITECTURE.md §8 delivery path 1, §10 `link --open`): delivers a
+ * deep link to a booted Android emulator/device or iOS simulator without any human handling a QR
+ * code — this is the CI/agent path. All subprocess execution goes through the injectable
+ * {@link ExecFn} seam so every branch here is testable without `adb`/`xcrun` installed.
+ *
+ * {@link detectBootedTargets} is the same enumeration used *before* a target is chosen, so callers
+ * that were given no explicit target (notably `appduct_connect` over MCP) can deliver to the one
+ * obvious device instead of falling back to a QR code nobody is there to scan.
+ *
+ * A third, experimental target — `ios-device`, a paired physical iPhone/iPad via `xcrun devicectl`
+ * (issue #31) — is explicit opt-in only: it is never auto-detected, it needs the app's bundle id,
+ * and its link must carry the LAN address rather than `127.0.0.1` (see {@link usesLoopbackAddress}).
+ */
+import { execFile } from "node:child_process";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { connectionError, usageError } from "../errors.js";
+export const isOpenTarget = (value) => {
+    return value === "android" || value === "ios-sim" || value === "ios-device";
+};
+/** Human-readable list of every accepted target, for the "must be one of" validation messages the
+ * CLI, the shared `mintLink` core and `appduct_connect` each render in their own wording. */
+export const OPEN_TARGETS = ["android", "ios-sim", "ios-device"];
+/**
+ * Whether a link delivered to this target reaches the daemon over loopback, and so must be minted
+ * with the `127.0.0.1` address override (`link.ts`, `mcp/connect-tool.ts`). True for `android`
+ * (`adb reverse` forwards the port onto the device) and `ios-sim` (the simulator shares the host's
+ * network stack); false for `ios-device` — a physical iPhone reaches the daemon only over the LAN,
+ * so such a link must carry the machine's real advertised address (issue #31).
+ */
+export const usesLoopbackAddress = (target) => {
+    return target === "android" || target === "ios-sim";
+};
+/**
+ * Whether an advertised address is one that only resolves back to the machine that minted the link.
+ * `daemon/address.ts` falls back to `127.0.0.1` when it cannot find a routable interface, and such
+ * a link handed to a physical phone points the phone at *itself*: the app connects to nothing, the
+ * session is never claimed, and `wait_for_session` blocks for its whole timeout with no clue why.
+ * The `ios-device` path checks this after minting and refuses rather than delivering.
+ */
+export const isLoopbackAddress = (address) => {
+    const normalized = address.trim().toLowerCase().replace(/^\[|\]$/gu, "");
+    return (normalized === "localhost" ||
+        normalized === "::1" ||
+        normalized === "0.0.0.0" ||
+        normalized === "::" ||
+        /^127\./u.test(normalized));
+};
+/** The one wording for that refusal, shared by the CLI and MCP paths. */
+export const loopbackAddressMessage = (address) => `The daemon advertised "${address}", which a physical device cannot reach — it would point the ` +
+    "phone at itself and the session would never be claimed. No routable LAN address was detected; " +
+    'set "advertisedIp" in config.json to this machine\'s address on the network the device is on, ' +
+    "and retry.";
+/** Real subprocess execution via `execFile` (no shell involved — argv is passed verbatim). */
+export const defaultExec = (command, args) => {
+    return new Promise((resolve, reject) => {
+        execFile(command, args, { encoding: "utf8" }, (error, stdout, stderr) => {
+            if (error) {
+                reject(Object.assign(error, { stdout, stderr }));
+                return;
+            }
+            resolve({ stdout, stderr });
+        });
+    });
+};
+const TOOL_INSTALL_HINT = {
+    adb: "the Android platform-tools (adb)",
+    xcrun: "the Xcode command line tools (xcrun)",
+};
+const run = async (exec, command, args) => {
+    try {
+        return await exec(command, args);
+    }
+    catch (error) {
+        const err = error;
+        if (err.code === "ENOENT") {
+            throw connectionError(`"${command}" was not found on PATH. Install ${TOOL_INSTALL_HINT[command] ?? command} and retry.`);
+        }
+        const stderr = (err.stderr ?? "").trim();
+        throw connectionError(`"${command} ${args.join(" ")}" failed${stderr ? `: ${stderr}` : `: ${err.message}`}`);
+    }
+};
+const parseBootedSimulators = (stdout) => {
+    let parsed;
+    try {
+        parsed = JSON.parse(stdout);
+    }
+    catch {
+        return [];
+    }
+    return Object.values(parsed.devices ?? {})
+        .flat()
+        .filter((entry) => entry.state === "Booted" && typeof entry.udid === "string" && entry.udid.length > 0)
+        .map((entry) => ({ udid: entry.udid, name: entry.name ?? entry.udid }));
+};
+const listBootedSimulators = async (exec) => {
+    const preflight = await run(exec, "xcrun", ["simctl", "list", "devices", "booted", "--json"]);
+    return parseBootedSimulators(preflight.stdout);
+};
+const describeSimulator = (simulator) => `${simulator.name} (${simulator.udid})`;
+const deliverIosSim = async (exec, deepLink, device) => {
+    // An explicit udid is honored without a preflight, mirroring android's `--device` passthrough:
+    // the caller has already named the device, so re-listing only adds a failure mode.
+    if (device) {
+        await run(exec, "xcrun", ["simctl", "openurl", device, deepLink]);
+        return;
+    }
+    const booted = await listBootedSimulators(exec);
+    if (booted.length === 0) {
+        throw usageError("No booted iOS simulator found. Boot a simulator (e.g. via Xcode) and retry.");
+    }
+    if (booted.length > 1) {
+        // Previously this delivered to simctl's `booted` alias regardless, which silently picks one of
+        // several booted simulators — the link would land on an arbitrary device and the session would
+        // never be claimed, looking exactly like a hung `wait_for_session`. Errors like android does.
+        throw usageError(`Multiple iOS simulators are booted (${booted
+            .map(describeSimulator)
+            .join(", ")}); specify --device <udid>.`);
+    }
+    // Target the resolved udid rather than the `booted` alias: `booted` is only unambiguous while
+    // exactly one simulator is up, and a second one booting between the preflight and this call would
+    // otherwise redirect the link to an arbitrary device.
+    await run(exec, "xcrun", ["simctl", "openurl", booted[0].udid, deepLink]);
+};
+// --- ios-device (experimental, issue #31) ---
+/**
+ * `devicectl` writes its JSON to a *file* (`--json-output <path>`), never to stdout, so this path
+ * cannot reuse the stdout-parsing shape `simctl` uses. The file lives in a private `mkdtemp`
+ * directory removed in a `finally`, so a failing `devicectl` (or a malformed payload) never leaks
+ * a temp file.
+ */
+const runDevicectlJson = async (exec, buildArgs) => {
+    let dir;
+    try {
+        dir = await mkdtemp(path.join(tmpdir(), "appduct-devicectl-"));
+    }
+    catch (error) {
+        // A read-only or missing TMPDIR would otherwise surface as a bare `EACCES`/`ENOENT` against a
+        // path the user never chose, with nothing saying which knob to turn.
+        throw connectionError(`A temporary directory for devicectl's --json-output could not be created in "${tmpdir()}" ` +
+            `(${error.message}). Set TMPDIR to a writable directory and retry.`);
+    }
+    const file = path.join(dir, "devicectl.json");
+    try {
+        await run(exec, "xcrun", buildArgs(file));
+        try {
+            return JSON.parse(await readFile(file, "utf8"));
+        }
+        catch {
+            // `devicectl` exited 0 but wrote nothing readable. Treated as an empty listing (the caller
+            // renders "no device found") rather than surfacing a JSON syntax error, matching how
+            // `parseBootedSimulators` handles unparseable `simctl` output.
+            return undefined;
+        }
+    }
+    finally {
+        // Swallowed deliberately: a failure to clean up a temp directory must not replace the
+        // devicectl error the caller actually needs to read (a `finally` that throws wins).
+        await rm(dir, { force: true, recursive: true }).catch(() => { });
+    }
+};
+/** `hardwareProperties.platform` values `devicectl` reports for things that are not an iPhone or
+ * iPad. A paired Apple Watch or Vision Pro is a real CoreDevice and shows up in the same listing,
+ * but cannot run the app and must never make the device choice look ambiguous. */
+const DELIVERABLE_PLATFORM = "ios";
+/**
+ * The only `tunnelState` that means "not reachable at all". Deliberately *not* including
+ * `disconnected`: a wired, trusted iPhone routinely reports `disconnected` (the tunnel is brought
+ * up on demand), so excluding it would drop exactly the device this target exists to reach. This
+ * matches the vendored Expo CLI's own `devicectl` integration
+ * (`@expo/cli`'s `AppleDevice.js:102`), which keeps `disconnected` and excludes only `unavailable`.
+ */
+const UNREACHABLE_TUNNEL_STATE = "unavailable";
+/** Expo's companion condition: a usable device is affirmatively `paired`. */
+const USABLE_PAIRING_STATE = "paired";
+/**
+ * `devicectl list devices` lists **every CoreDevice the Mac has ever known**, across platforms and
+ * regardless of whether it is plugged in — so the listing has to be filtered, not trusted.
+ *
+ * Filtering happens here rather than through `devicectl --filter` (an NSPredicate over undocumented
+ * keys) so that every rule is exercised by the `ExecFn` tests instead of by a predicate string no
+ * test can evaluate.
+ *
+ * Each rule drops an entry only when the field is **present and disqualifying**; a missing field
+ * keeps the device. The field names are undocumented, so a `devicectl` that stops emitting one must
+ * degrade to "offer the device and let the launch fail loudly", never to "silently find nothing".
+ * That is the one deliberate departure from Expo, which tests `pairingState === "paired"`
+ * positively and so would find nothing at all if the key were ever renamed.
+ */
+const parsePairedIosDevices = (payload) => {
+    const devices = payload?.result?.devices;
+    if (!Array.isArray(devices)) {
+        return [];
+    }
+    return devices
+        .map((entry) => {
+        const platform = entry?.hardwareProperties?.platform;
+        if (typeof platform === "string" && platform.toLowerCase() !== DELIVERABLE_PLATFORM) {
+            return undefined;
+        }
+        const tunnelState = entry?.connectionProperties?.tunnelState;
+        if (typeof tunnelState === "string" && tunnelState.toLowerCase() === UNREACHABLE_TUNNEL_STATE) {
+            return undefined;
+        }
+        const pairingState = entry?.connectionProperties?.pairingState;
+        if (typeof pairingState === "string" && pairingState.toLowerCase() !== USABLE_PAIRING_STATE) {
+            return undefined;
+        }
+        // `hardwareProperties.udid` is what `--device` wants; `identifier` (the CoreDevice UUID) is
+        // also accepted by `devicectl`, so a listing that omits the udid is still usable rather than
+        // silently dropped. Checked for emptiness rather than `??`, which would keep a `""` udid and
+        // never reach the documented fallback.
+        const hardwareUdid = entry?.hardwareProperties?.udid;
+        const udid = typeof hardwareUdid === "string" && hardwareUdid.length > 0
+            ? hardwareUdid
+            : entry?.identifier;
+        return typeof udid === "string" && udid.length > 0
+            ? { udid, name: entry?.deviceProperties?.name ?? udid }
+            : undefined;
+    })
+        .filter((device) => device !== undefined);
+};
+const listPairedIosDevices = async (exec) => {
+    const payload = await runDevicectlJson(exec, (file) => [
+        "devicectl",
+        "list",
+        "devices",
+        "--timeout",
+        "5",
+        "--json-output",
+        file,
+    ]);
+    return parsePairedIosDevices(payload);
+};
+const describeIosDevice = (device) => `${device.name} (${device.udid})`;
+/** The single wording naming both ways to supply a bundle id, so the CLI and MCP paths agree. */
+export const MISSING_BUNDLE_ID_MESSAGE = "Delivering to a physical iPhone needs the app's bundle id: pass \"--bundle-id <id>\" (or " +
+    '"bundleId" over MCP), or set "iosBundleId" in config.json.';
+/**
+ * A bundle id is the **only trailing positional** in the `devicectl device process launch` argv, so
+ * a value beginning with `-` would be read by `devicectl` as an option rather than as the app to
+ * launch — `--console`, say, silently changing what the command does. Apple's own grammar for a
+ * bundle identifier is alphanumerics, `.` and `-`, which never legitimately starts with `-`, so
+ * enforcing exactly that shape closes the hole at every entry point.
+ *
+ * A `--` terminator is deliberately *not* used instead: `devicectl` takes launch arguments after
+ * the bundle id, its handling of `--` is undocumented, and none of it can be verified without
+ * hardware — whereas this check is exact and fully testable.
+ */
+const BUNDLE_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9.-]*$/u;
+export const isValidBundleId = (value) => BUNDLE_ID_PATTERN.test(value);
+export const invalidBundleIdMessage = (value) => `"${value}" is not a valid iOS bundle id (letters, digits, "." and "-", starting with a letter ` +
+    "or digit).";
+/** Same ambiguity rules as `deliverIosSim`: exactly one paired device, or the caller names one. */
+const resolveSingleIosDevice = async (exec) => {
+    const paired = await listPairedIosDevices(exec);
+    if (paired.length === 0) {
+        throw usageError('No connected iOS device was found ("xcrun devicectl list devices" listed none, ignoring ' +
+            "disconnected devices and non-iOS ones such as a paired Watch or Vision Pro). Connect the " +
+            "device, trust this Mac, and enable Developer Mode on it, then retry.");
+    }
+    if (paired.length > 1) {
+        throw usageError(`Multiple connected iOS devices were found (${paired
+            .map(describeIosDevice)
+            .join(", ")}); specify --device <udid>.`);
+    }
+    return paired[0].udid;
+};
+/**
+ * Experimental physical-iPhone delivery (issue #31). `xcrun devicectl device process launch
+ * --device <udid> --payload-url <url> <bundle-id>` is undocumented by Apple but is the mechanism
+ * Xcode 15+ exposes for handing a URL to an installed, dev-signed app on a paired iOS 17+ device.
+ * It may cold-launch (rather than foreground) the app; the app side copes either way, because a
+ * delivered link supersedes a held session and the initial-URL path is handled.
+ *
+ * Unlike `ios-sim`, this is never auto-detected — see {@link detectBootedTargets}.
+ */
+const deliverIosDevice = async (exec, deepLink, device, bundleId, relaunch) => {
+    // Checked before any enumeration: without a bundle id the launch cannot happen at all, so
+    // spending a `devicectl list devices` timeout first would only delay the same error.
+    if (!bundleId) {
+        throw usageError(MISSING_BUNDLE_ID_MESSAGE);
+    }
+    // Last line of defence: every caller validates too, but this is the one place the value reaches
+    // an argv, so it is the one place that must not be bypassable.
+    if (!isValidBundleId(bundleId)) {
+        throw usageError(invalidBundleIdMessage(bundleId));
+    }
+    // An explicit udid is honored without a preflight, mirroring the `ios-sim`/`android` passthrough.
+    const udid = device ?? (await resolveSingleIosDevice(exec));
+    await run(exec, "xcrun", [
+        "devicectl",
+        "device",
+        "process",
+        "launch",
+        "--device",
+        udid,
+        // Opt-in only (`--relaunch` / `relaunch: true`). A plain `process launch` is what the vendored
+        // Expo CLI does, so it is the better-attested default; what it does when the app is *already
+        // running* is the one thing nobody here can verify without hardware. If that turns out to fail
+        // rather than deliver the URL, `--terminate-existing` is the escape hatch — it kills the
+        // running instance first, which Appduct copes with because a delivered link supersedes a
+        // held session.
+        ...(relaunch ? ["--terminate-existing"] : []),
+        "--payload-url",
+        deepLink,
+        bundleId,
+    ]);
+};
+/** Parses `adb devices` output: header line, then `<serial>\t<state>` per attached device. */
+const parseAdbDevices = (stdout) => {
+    return stdout
+        .split("\n")
+        .slice(1)
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0)
+        .map((line) => {
+        const [serial = "", state = ""] = line.split(/\s+/u);
+        return { serial, state };
+    })
+        .filter((entry) => entry.serial.length > 0);
+};
+const listAttachedAndroidDevices = async (exec) => {
+    const listing = await run(exec, "adb", ["devices"]);
+    return parseAdbDevices(listing.stdout)
+        .filter((entry) => entry.state === "device")
+        .map((entry) => entry.serial);
+};
+/**
+ * Resolves the `-s <serial>` argument, if any. `--device` always wins; otherwise, if
+ * `ANDROID_SERIAL` is set, `adb` already honors it with no flag needed from us; otherwise exactly
+ * one attached device is required (zero or several is an error naming what's attached).
+ */
+const resolveAndroidSerial = async (exec, device, env) => {
+    if (device) {
+        return device;
+    }
+    if (env.ANDROID_SERIAL) {
+        return undefined;
+    }
+    const attached = await listAttachedAndroidDevices(exec);
+    if (attached.length === 0) {
+        throw usageError('No Android device or emulator is attached ("adb devices" listed none).');
+    }
+    if (attached.length > 1) {
+        throw usageError(`Multiple Android devices are attached (${attached.join(", ")}); specify --device <serial> or set ANDROID_SERIAL.`);
+    }
+    return undefined;
+};
+const withSerial = (args, serial) => {
+    return serial ? ["-s", serial, ...args] : args;
+};
+const deliverAndroid = async (exec, deepLink, wssPort, device, env) => {
+    const serial = await resolveAndroidSerial(exec, device, env);
+    // `adb reverse` before `am start`: the port forward must exist before the app tries to connect,
+    // which can happen the instant the deep link is handled.
+    await run(exec, "adb", withSerial(["reverse", `tcp:${wssPort}`, `tcp:${wssPort}`], serial));
+    await run(exec, "adb", withSerial([
+        "shell",
+        "am",
+        "start",
+        "-a",
+        "android.intent.action.VIEW",
+        "-d",
+        // `adb shell` reconstructs everything after "shell" into one string and re-parses it on the
+        // device's own shell; single-quoting the URL here (not just for local execFile, which never
+        // re-tokenizes argv) protects against that second, remote parse (ARCHITECTURE.md §8).
+        `'${deepLink}'`,
+    ], serial));
+};
+/** Best-effort enumeration: a missing or failing `xcrun`/`adb` means "no devices of that platform"
+ * rather than an error. Detection runs when the caller named *no* target, so a machine without the
+ * Android tools installed (or without Xcode) must still reach a clean `{ kind: "none" }` and its
+ * QR fallback instead of failing the whole call. */
+const safeList = async (list) => {
+    try {
+        return await list();
+    }
+    catch {
+        return [];
+    }
+};
+/**
+ * Enumerates every booted simulator and attached Android device so a caller with no explicit
+ * target can deliver to the single obvious one. `ANDROID_SERIAL`, when set, narrows the Android
+ * side to that serial — it is exactly the disambiguation the user has already made.
+ *
+ * Physical iPhones (`ios-device`) are deliberately *not* enumerated here (issue #31): a paired
+ * iPhone is often someone's personal phone rather than a test device, delivery to it may
+ * cold-launch the app, and it additionally needs a bundle id the caller has to supply. It is an
+ * explicit, opt-in target only.
+ */
+export const detectBootedTargets = async (options = {}) => {
+    const exec = options.exec ?? defaultExec;
+    const env = options.env ?? process.env;
+    const [simulators, androidSerials] = await Promise.all([
+        safeList(() => listBootedSimulators(exec)),
+        env.ANDROID_SERIAL
+            ? Promise.resolve([env.ANDROID_SERIAL])
+            : safeList(() => listAttachedAndroidDevices(exec)),
+    ]);
+    const candidates = [
+        ...simulators.map((simulator) => ({
+            target: "ios-sim",
+            device: simulator.udid,
+            label: describeSimulator(simulator),
+        })),
+        ...androidSerials.map((serial) => ({
+            target: "android",
+            device: serial,
+            label: serial,
+        })),
+    ];
+    if (candidates.length === 0) {
+        return { kind: "none" };
+    }
+    if (candidates.length === 1) {
+        return { kind: "single", detected: candidates[0] };
+    }
+    return { kind: "ambiguous", candidates };
+};
+/** Delivers `deepLink` to a booted Android device/emulator, an iOS simulator, or (experimentally)
+ * a paired physical iOS device. Throws a clear, actionable error (missing tool, no booted device,
+ * ambiguous device, missing bundle id) rather than a raw one. */
+export const deliverToOpenTarget = async (options) => {
+    const exec = options.exec ?? defaultExec;
+    if (options.target === "ios-sim") {
+        await deliverIosSim(exec, options.deepLink, options.device);
+        return;
+    }
+    if (options.target === "ios-device") {
+        await deliverIosDevice(exec, options.deepLink, options.device, options.bundleId, options.relaunch ?? false);
+        return;
+    }
+    await deliverAndroid(exec, options.deepLink, options.wssPort, options.device, options.env ?? process.env);
+};

package/dist/cli/result-types.d.ts

@@ -0,0 +1,194 @@
+/**
+ * CLI command-result types (ARCHITECTURE.md §10). The v2 command table replaces the v1 shapes that
+ * used to live here (`host`/`connect`/`session` — all removed from the v2 command surface) with
+ * the thin-client shapes for the v2 command table.
+ */
+import type { OpenTarget } from "./open-target.js";
+import type { AgentEndpoint, EffectivePolicyDecision, EventNotification, SessionSummary, ToolDescriptor } from "@appduct/shared";
+/**
+ * CLI-domain error classes, used only to pick a sysexits-style exit code (see `errors.ts`).
+ * `CliError.type` itself is *not* restricted to this union: RPC/app-originated failures preserve
+ * the daemon's wire `ErrorType` verbatim in `type` (ARCHITECTURE.md §5 — "never re-wrapped"), while
+ * CLI-originated failures (bad flags, JSON parse errors, ...) use one of these names directly.
+ */
+export type CliErrorType = "usage_error" | "validation_error" | "connection_error" | "session_error" | "tool_error" | "permission_error" | "internal_error" | "inspection_error" | "assertion_error";
+export type CliError = {
+    /** A `CliErrorType` for CLI-originated failures, or the verbatim daemon/app `ErrorType` for
+     * RPC-originated ones (e.g. `tool_execution_error`) — never re-wrapped under a generic type. */
+    type: string;
+    message: string;
+    details?: unknown;
+};
+export type CommandMeta = {
+    command: string;
+    timestamp: string;
+    duration_ms?: number;
+};
+export type CliSuccessResult<TData> = {
+    ok: true;
+    data: TData;
+    meta?: CommandMeta;
+};
+export type CliFailureResult = {
+    ok: false;
+    error: CliError;
+    meta?: CommandMeta;
+};
+export type CliResult<TData> = CliSuccessResult<TData> | CliFailureResult;
+export type KeygenCommandData = {
+    path: string;
+    pin: string;
+};
+/**
+ * `appduct init` (issue #29). `created`/`changed` are what make the command's idempotency
+ * observable to a script: a re-run with the same scheme returns `ok: true` with both `false`, so a
+ * caller can tell "nothing to do" from "I just wrote this" without diffing the file itself.
+ */
+export type InitCommandData = {
+    /** Absolute path of the project config that was written (or already correct). */
+    path: string;
+    scheme: string;
+    /**
+     * Where `scheme` came from. These are `init`'s *own* inputs, deliberately named so they cannot
+     * be read as `scheme.ts`'s resolution tiers: `init` never consults `APPDUCT_SCHEME` and
+     * never walks up to a parent project config (see `commands/init.ts`).
+     *
+     * - `"--scheme"` — the flag.
+     * - `"app.json"` — `<cwd>/app.json`'s `expo.scheme`.
+     * - `"android-gradle"` / `"android-manifest"` / `"ios-info-plist"` / `"ios-project-yml"` — one of
+     *   the static-file native-project probes added for issue #48 (`native-scheme.ts`), tried in
+     *   that order whenever `app.json` declares nothing. `origin` names the exact file/key.
+     * - `"already-recorded"` — the value this file already held, which a plain re-run keeps so it
+     *   stays idempotent even after the discovered value changes.
+     */
+    source: "--scheme" | "app.json" | "android-gradle" | "android-manifest" | "ios-info-plist" | "ios-project-yml" | "already-recorded";
+    /** The exact file (and key/placeholder) `scheme` was read from, when `source` is a discovery
+     * tier rather than `"--scheme"`/`"already-recorded"` — `init`'s human-readable hint surfaces
+     * this so a native-probe result says which file to go edit, not just which platform. */
+    origin?: string;
+    /** The project config did not exist before this run. */
+    created: boolean;
+    /** This run wrote to the file. `false` on an idempotent re-run. */
+    changed: boolean;
+    /** Present when the recorded scheme and the value discovery would currently find (`app.json` or
+     * a native probe) disagree. The recorded one still wins (a re-run must not start failing because
+     * the underlying project file was edited); this says so and names the `--force` invocation that
+     * would adopt the other. */
+    note?: string;
+    /** The MCP server entry to paste into an agent's config — self-contained (it carries `--scheme`)
+     * so one machine can serve several apps without editing a global file. */
+    mcpServerEntry: {
+        command: string;
+        args: string[];
+    };
+    /** Human-facing follow-ups that cannot be inferred from the filesystem (the `auto` import, the
+     * MCP paste, how to pair a device). Also carried in `--json` so an agent can relay them. */
+    nextSteps: string[];
+};
+export type LinkCommandData = {
+    sessionId: string;
+    /** Already includes the `pin` query param (see `pin` below) alongside `appduct`. */
+    deepLink: string;
+    endpoint: AgentEndpoint;
+    /** Unix seconds. */
+    expiresAt: number;
+    /** The daemon's SPKI pin, same value as embedded in `deepLink`'s `pin` query param — surfaced
+     * as its own field for `--json` consumers that don't want to re-parse the URL (opt-in
+     * hardening dev-mode: native clients trust this only in debug builds with no `cliPins`). */
+    pin: string;
+    /** Present (and `true`) only once `--open <target>` has successfully delivered the link
+     * (ARCHITECTURE.md §10). */
+    delivered?: true;
+    /** The `--open` target the link was delivered to, alongside `delivered`. */
+    target?: OpenTarget;
+};
+/** `appduct ls`: `sessions.list` passthrough, verbatim (ARCHITECTURE.md §10: "--json passthrough"). */
+export type LsCommandData = SessionSummary[];
+/** `appduct tools`: the full list, or a single descriptor when a tool name resolved to a detail lookup. */
+export type ToolsCommandData = ToolDescriptor[] | ToolDescriptor;
+/** `appduct invoke`: the tool's raw result payload, printed as-is. */
+export type InvokeCommandData = unknown;
+export type RevokeCommandData = {
+    ok: true;
+};
+/** A single `appduct events` line, in both human and NDJSON (`--json`) rendering. */
+export type EventsCommandLine = EventNotification;
+export type DaemonRunCommandData = {
+    daemon: {
+        pid: number;
+        state_dir: string;
+        socket_path: string;
+    };
+};
+export type DaemonStartCommandData = {
+    daemon: {
+        pid: number;
+        wss_port: number;
+        started_at: string;
+    };
+};
+export type DaemonStopCommandData = {
+    daemon: {
+        ok: true;
+        /** How the daemon was told to stop: a clean RPC round-trip, or a SIGTERM fallback. */
+        method: "rpc" | "sigterm";
+    };
+};
+/** `appduct doctor <artifact>`: artifact-level Appduct inclusion report (docs/tasks/08). */
+export type DoctorCommandData = {
+    artifact: string;
+    platform: "ios" | "android";
+    format: "app" | "ipa" | "apk" | "aab";
+    present: boolean;
+    /** Which specific markers matched; empty when `present` is `false`. */
+    signals: string[];
+    /** Present only when `--assert-present`/`--assert-absent` was given. `holds` is always `true` on
+     * a successful result — a failed assertion throws instead (see `assertion_error`), so a caller
+     * reading only `ok: true` results never needs to re-check this field to know whether the gate
+     * passed. */
+    assertion?: {
+        expected: "present" | "absent";
+        holds: true;
+    };
+};
+export type DaemonStatusCommandData = {
+    daemon: {
+        version: string;
+        pid: number;
+        started_at: string;
+        wss_port: number;
+        pinned_keys: string[];
+        session_count: number;
+    };
+    /**
+     * Present only when the running daemon's version differs from this CLI's (issue #30). `daemon
+     * status` deliberately reports drift instead of acting on it — it is the command an operator
+     * reaches for to *diagnose* a daemon, so it must never restart the one they are inspecting.
+     */
+    warning?: string;
+    /** Effective policy + audit surfacing (ARCHITECTURE.md §12). */
+    policy: {
+        default: EffectivePolicyDecision;
+        destructive: EffectivePolicyDecision;
+        tools?: Record<string, EffectivePolicyDecision>;
+    };
+    /**
+     * `path`/`failed_writes` come from every daemon version. The retention fields are optional
+     * because a daemon started before retention existed answers `daemon.status` without them, and a
+     * newer CLI can be pointed at exactly that daemon. Absent is reported as absent — omitted from
+     * `--json` and skipped in the human rendering — rather than defaulted to `0`, which would state
+     * "this daemon retains nothing and has zero day files" when the truth is that it was never
+     * asked. `daemon.version` is the field that explains why they are missing.
+     */
+    audit: {
+        path: string;
+        failed_writes: number;
+        failed_prunes?: number;
+        retention_days?: number;
+        /** Retained `audit/<YYYY-MM-DD>.jsonl` day files. */
+        files?: number;
+        /** Total bytes across those files. */
+        bytes?: number;
+    };
+};
+//# sourceMappingURL=result-types.d.ts.map

package/dist/cli/result-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"result-types.d.ts","sourceRoot":"","sources":["../../src/cli/result-types.ts"],"names":[],"mappings":"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"}

package/dist/cli/result-types.js

@@ -0,0 +1,6 @@
+/**
+ * CLI command-result types (ARCHITECTURE.md §10). The v2 command table replaces the v1 shapes that
+ * used to live here (`host`/`connect`/`session` — all removed from the v2 command surface) with
+ * the thin-client shapes for the v2 command table.
+ */
+export {};