appduct 0.9.0

package/dist/client/bootstrap.js

@@ -0,0 +1,108 @@
+/**
+ * `link()`/`waitForSession()` (issue #8): the bootstrap half of the client, so a test's
+ * `globalSetup` can pair a simulator/emulator without shelling out to `appduct link --open`.
+ * `link()` delegates to the same `mintLink` core `commands/link.ts` uses (`../link.js`) so the
+ * deep-link shape can't drift between the CLI and this package; `waitForSession()` mirrors
+ * `mcp/connect-tool.ts`'s `handleWaitForSessionTool`.
+ */
+import { RPC_METHODS } from "@appduct/shared";
+import {} from "../cli/open-target.js";
+import { resolveStateDir } from "../daemon/state-dir.js";
+import { mintLink } from "../link.js";
+import { openDaemonStream, DaemonRpcError } from "../rpc/client.js";
+import { makeAppClient } from "./app-client.js";
+import { AppductError, toAppductError } from "./errors.js";
+const DEFAULT_WAIT_FOR_SESSION_TIMEOUT_MS = 120_000;
+/** Mints a session link via `link.create` and composes the deep link. With `target` set, delivers
+ * it directly to a booted emulator/simulator instead of leaving delivery to the caller. */
+export const link = async (options = {}) => {
+    try {
+        return await mintLink({
+            stateDir: resolveStateDir(options.stateDir),
+            spawn: options.spawn,
+            autoSpawn: options.autoSpawn,
+            ttlSeconds: options.ttlSeconds,
+            target: options.target,
+            device: options.device,
+            bundleId: options.bundleId,
+            relaunch: options.relaunch,
+            scheme: options.scheme,
+            cwd: options.cwd,
+            exec: options.exec,
+            env: options.env,
+            schemeEnv: options.schemeEnv,
+        });
+    }
+    catch (error) {
+        throw toAppductError(error);
+    }
+};
+/** Waits for `sessionId` (from {@link link}) to be claimed by a device, then returns a connected
+ * {@link AppClient} for it — resolves immediately if it's already claimed. */
+export const waitForSession = async (sessionId, options = {}) => {
+    const stateDir = resolveStateDir(options.stateDir);
+    const timeoutMs = options.timeoutMs ?? DEFAULT_WAIT_FOR_SESSION_TIMEOUT_MS;
+    let stream;
+    try {
+        stream = await openDaemonStream({ stateDir, spawn: options.spawn, autoSpawn: options.autoSpawn });
+    }
+    catch (error) {
+        throw toAppductError(error);
+    }
+    try {
+        // The session may already be claimed by the time this runs — resolve immediately rather than
+        // waiting for an event that already happened.
+        try {
+            await stream.call(RPC_METHODS.sessionsDescribe, { selector: sessionId });
+            return makeAppClient(stream, sessionId);
+        }
+        catch (error) {
+            if (!(error instanceof DaemonRpcError) || error.data?.type !== "unknown_session") {
+                throw error;
+            }
+        }
+        await new Promise((resolve, reject) => {
+            let settled = false;
+            const settle = (fn) => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                clearTimeout(timer);
+                unsubscribeNotification();
+                unsubscribeClose();
+                fn();
+            };
+            const timer = setTimeout(() => {
+                settle(() => reject(new AppductError("timeout", `Timed out after ${timeoutMs}ms waiting for session "${sessionId}" to be claimed.`)));
+            }, timeoutMs);
+            const unsubscribeClose = stream.onClose(() => {
+                settle(() => reject(new AppductError("connection_error", `The connection to the Appduct daemon closed while waiting for session "${sessionId}" to be claimed.`)));
+            });
+            // Registered *before* `events.subscribe` is sent (not after awaiting it) — a
+            // `session_claimed` notification that arrives in the same TCP chunk as the subscribe
+            // response is dispatched synchronously within that chunk's processing, before an `await`
+            // continuation below would get a chance to run; registering the listener first means it's
+            // always in place in time to see it.
+            const unsubscribeNotification = stream.onNotification((payload) => {
+                if (settled) {
+                    return;
+                }
+                const event = payload;
+                if (event.kind === "session_claimed" && event.sessionId === sessionId) {
+                    settle(resolve);
+                }
+            });
+            stream
+                .call(RPC_METHODS.eventsSubscribe, { sessionSelector: sessionId, kinds: ["session_claimed"] })
+                .catch((error) => {
+                settle(() => reject(toAppductError(error)));
+            });
+        });
+        return makeAppClient(stream, sessionId);
+    }
+    catch (error) {
+        stream.close();
+        throw toAppductError(error);
+    }
+};

package/dist/client/connect.d.ts

@@ -0,0 +1,17 @@
+import { type SpawnFn } from "../rpc/client.js";
+import { type AppClient, type ToolMap } from "./app-client.js";
+export type ConnectOptions = {
+    /** Session id or alias; omitted selects the sole active/suspended session (rejects with
+     * `"no_session"`/`"ambiguous_session"` otherwise — the same rule the CLI/MCP surfaces use). */
+    selector?: string;
+    /** Defaults to `APPDUCT_STATE_DIR`, else `~/.appduct` — the same resolution the CLI uses. */
+    stateDir?: string;
+    /** Injectable daemon-spawn seam (tests only); real callers never need this. */
+    spawn?: SpawnFn;
+    /** Auto-spawn a daemon on a missing connection. Defaults to `true`. */
+    autoSpawn?: boolean;
+    requestTimeoutMs?: number;
+};
+/** Opens a persistent connection to the daemon and resolves `options.selector` to one session. */
+export declare const connect: <TTools = ToolMap>(options?: ConnectOptions) => Promise<AppClient<TTools>>;
+//# sourceMappingURL=connect.d.ts.map

package/dist/client/connect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connect.d.ts","sourceRoot":"","sources":["../../src/client/connect.ts"],"names":[],"mappings":"AAUA,OAAO,EAAuC,KAAK,OAAO,EAAE,MAAM,kBAAkB,CAAC;AACrF,OAAO,EAAiB,KAAK,SAAS,EAAE,KAAK,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAG9E,MAAM,MAAM,cAAc,GAAG;IAC3B;mGAC+F;IAC/F,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6FAA6F;IAC7F,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+EAA+E;IAC/E,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,uEAAuE;IACvE,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC;AAEF,kGAAkG;AAClG,eAAO,MAAM,OAAO,GAAU,MAAM,GAAG,OAAO,EAC5C,UAAS,cAAmB,KAC3B,OAAO,CAAC,SAAS,CAAC,MAAM,CAAC,CA0B3B,CAAC"}

package/dist/client/connect.js

@@ -0,0 +1,38 @@
+/**
+ * `connect()` (issue #8): the entry point for a test runner that wants to drive an already-claimed
+ * session without shelling out to the CLI. Auto-spawns the daemon (same seam `rpc/client.ts` gives
+ * the CLI/MCP server) and resolves `selector` up front via `sessions.describe` so a bad/ambiguous
+ * selector fails fast with a typed {@link AppductError} rather than surfacing on the first
+ * `call()`.
+ */
+import { RPC_METHODS } from "@appduct/shared";
+import { resolveStateDir } from "../daemon/state-dir.js";
+import { openDaemonStream } from "../rpc/client.js";
+import { makeAppClient } from "./app-client.js";
+import { toAppductError } from "./errors.js";
+/** Opens a persistent connection to the daemon and resolves `options.selector` to one session. */
+export const connect = async (options = {}) => {
+    const stateDir = resolveStateDir(options.stateDir);
+    let stream;
+    try {
+        stream = await openDaemonStream({
+            stateDir,
+            spawn: options.spawn,
+            autoSpawn: options.autoSpawn,
+            requestTimeoutMs: options.requestTimeoutMs,
+        });
+    }
+    catch (error) {
+        throw toAppductError(error);
+    }
+    try {
+        const detail = await stream.call(RPC_METHODS.sessionsDescribe, {
+            selector: options.selector,
+        });
+        return makeAppClient(stream, detail.sessionId);
+    }
+    catch (error) {
+        stream.close();
+        throw toAppductError(error);
+    }
+};

package/dist/client/errors.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Client-facing error type (issue #8): the wire `error.data.type` (ARCHITECTURE.md §5) surfaced as
+ * a typed exception instead of a `DaemonRpcError`/stderr string a test would have to pattern-match.
+ * `type` preserves the wire value verbatim — the same non-rewrapping rule `errors.ts`'s
+ * `toCliError` already enforces for the CLI — so `expect(...).rejects.toMatchObject({ type:
+ * "policy_denied" })` works without this package's internal error classes leaking into test code.
+ */
+import type { ErrorType } from "@appduct/shared";
+/** The wire `ErrorType` union, plus three client-only buckets for conditions the daemon never
+ * produced: `"connection_error"` (daemon unreachable/unspawnable, or the connection dropped mid-
+ * wait), `"timeout"` (a client-side wait — `waitForEvent`, `waitForSession` — gave up; distinct
+ * from the wire `"tool_timeout"` so a test can tell "the app's tool timed out" apart from "my wait
+ * gave up"), and `"client_error"` (anything else, e.g. a failed emulator/simulator delivery from
+ * {@link link}, or a malformed JSON-RPC error with no `data.type`). */
+export type AppductErrorType = ErrorType | "connection_error" | "timeout" | "client_error";
+export declare class AppductError extends Error {
+    readonly type: AppductErrorType;
+    readonly details?: unknown;
+    /** The JSON-RPC error code, when this wraps a `DaemonRpcError`. */
+    readonly code?: number;
+    constructor(type: AppductErrorType, message: string, details?: unknown, code?: number);
+}
+/** Converts any error thrown by the RPC layer into a {@link AppductError}, preserving the wire
+ * `data.type` verbatim when present. Idempotent on an already-converted error. */
+export declare const toAppductError: (error: unknown) => AppductError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/client/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/client/errors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAKjD;;;;;uEAKuE;AACvE,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,kBAAkB,GAAG,SAAS,GAAG,cAAc,CAAC;AAE3F,qBAAa,YAAa,SAAQ,KAAK;IACrC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,mEAAmE;IACnE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;gBAEX,IAAI,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,MAAM;CAOtF;AAED;kFACkF;AAClF,eAAO,MAAM,cAAc,GAAI,OAAO,OAAO,KAAG,YAiC/C,CAAC"}

package/dist/client/errors.js

@@ -0,0 +1,40 @@
+import { isAppductCliError } from "../errors.js";
+import { DaemonRpcError, isDaemonUnreachableError } from "../rpc/client.js";
+export class AppductError extends Error {
+    type;
+    details;
+    /** The JSON-RPC error code, when this wraps a `DaemonRpcError`. */
+    code;
+    constructor(type, message, details, code) {
+        super(message);
+        this.name = "AppductError";
+        this.type = type;
+        this.details = details;
+        this.code = code;
+    }
+}
+/** Converts any error thrown by the RPC layer into a {@link AppductError}, preserving the wire
+ * `data.type` verbatim when present. Idempotent on an already-converted error. */
+export const toAppductError = (error) => {
+    if (error instanceof AppductError) {
+        return error;
+    }
+    const withCause = (result) => {
+        result.cause = error;
+        return result;
+    };
+    if (error instanceof DaemonRpcError) {
+        const type = error.data?.type ?? "client_error";
+        return withCause(new AppductError(type, error.message, error.data?.details, error.code));
+    }
+    if (isDaemonUnreachableError(error)) {
+        return withCause(new AppductError("connection_error", error instanceof Error ? error.message : "The Appduct daemon is unreachable."));
+    }
+    if (isAppductCliError(error)) {
+        return withCause(new AppductError("client_error", error.message, error.details));
+    }
+    if (error instanceof Error) {
+        return withCause(new AppductError("client_error", error.message));
+    }
+    return new AppductError("client_error", "An unexpected error occurred.", error);
+};

package/dist/client/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `appduct/client` (issue #8): a first-class programmatic client for test runners — a thin typed
+ * wrapper over the same daemon RPC the CLI and MCP server use, so a Jest/Vitest/Detox spec can
+ * `connect()`/`call()` instead of spawning `appduct invoke ... --json` and parsing stdout.
+ *
+ * ```ts
+ * import { connect } from "appduct/client";
+ *
+ * const app = await connect();
+ * const { total } = await app.call("sum", { a: 2, b: 3 });
+ * await app.close();
+ * ```
+ */
+export { connect, type ConnectOptions } from "./connect.js";
+export { link, waitForSession, type LinkOptions, type LinkResult, type WaitForSessionOptions } from "./bootstrap.js";
+export { AppductError, type AppductErrorType } from "./errors.js";
+export type { AppClient, AppEvent, CallOptions, EventsOptions, EventsResult, ToolMap, WaitForEventOptions, } from "./app-client.js";
+export type { AgentEndpoint, ErrorType, ToolDescriptor } from "@appduct/shared";
+//# sourceMappingURL=index.d.ts.map

package/dist/client/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AAC5D,OAAO,EAAE,IAAI,EAAE,cAAc,EAAE,KAAK,WAAW,EAAE,KAAK,UAAU,EAAE,KAAK,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AACrH,OAAO,EAAE,YAAY,EAAE,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAClE,YAAY,EACV,SAAS,EACT,QAAQ,EACR,WAAW,EACX,aAAa,EACb,YAAY,EACZ,OAAO,EACP,mBAAmB,GACpB,MAAM,iBAAiB,CAAC;AACzB,YAAY,EAAE,aAAa,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/client/index.js

@@ -0,0 +1,16 @@
+/**
+ * `appduct/client` (issue #8): a first-class programmatic client for test runners — a thin typed
+ * wrapper over the same daemon RPC the CLI and MCP server use, so a Jest/Vitest/Detox spec can
+ * `connect()`/`call()` instead of spawning `appduct invoke ... --json` and parsing stdout.
+ *
+ * ```ts
+ * import { connect } from "appduct/client";
+ *
+ * const app = await connect();
+ * const { total } = await app.call("sum", { a: 2, b: 3 });
+ * await app.close();
+ * ```
+ */
+export { connect } from "./connect.js";
+export { link, waitForSession } from "./bootstrap.js";
+export { AppductError } from "./errors.js";

package/dist/commands/daemon.d.ts

@@ -0,0 +1,22 @@
+import type { CliResult, DaemonRunCommandData, DaemonStartCommandData, DaemonStatusCommandData, DaemonStopCommandData } from "../cli/result-types.js";
+import type { Clock } from "../cli/types.js";
+import { type SpawnFn } from "../rpc/client.js";
+export type DaemonCommandContext = {
+    stateDir: string;
+    clock?: Clock;
+    spawn?: SpawnFn;
+    warn?: (message: string) => void;
+    /** Test seam: the version `daemon status` compares the daemon against; defaults to this
+     * package's own version. */
+    clientVersion?: string;
+};
+export type DaemonRunHostedResult = {
+    result: CliResult<DaemonRunCommandData>;
+    completion: Promise<void>;
+    stop: () => void;
+};
+export declare const handleDaemonRunCommand: (context: DaemonCommandContext) => Promise<DaemonRunHostedResult>;
+export declare const handleDaemonStartCommand: (context: DaemonCommandContext) => Promise<CliResult<DaemonStartCommandData>>;
+export declare const handleDaemonStopCommand: (context: DaemonCommandContext) => Promise<CliResult<DaemonStopCommandData>>;
+export declare const handleDaemonStatusCommand: (context: DaemonCommandContext) => Promise<CliResult<DaemonStatusCommandData>>;
+//# sourceMappingURL=daemon.d.ts.map

package/dist/commands/daemon.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"daemon.d.ts","sourceRoot":"","sources":["../../src/commands/daemon.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,SAAS,EACT,oBAAoB,EACpB,sBAAsB,EACtB,uBAAuB,EACvB,qBAAqB,EACtB,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AAM7C,OAAO,EAAuD,KAAK,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAErG,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACjC;gCAC4B;IAC5B,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,MAAM,EAAE,SAAS,CAAC,oBAAoB,CAAC,CAAC;IACxC,UAAU,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,IAAI,EAAE,MAAM,IAAI,CAAC;CAClB,CAAC;AAEF,eAAO,MAAM,sBAAsB,GACjC,SAAS,oBAAoB,KAC5B,OAAO,CAAC,qBAAqB,CAiC/B,CAAC;AAEF,eAAO,MAAM,wBAAwB,GACnC,SAAS,oBAAoB,KAC5B,OAAO,CAAC,SAAS,CAAC,sBAAsB,CAAC,CAiB3C,CAAC;AAEF,eAAO,MAAM,uBAAuB,GAClC,SAAS,oBAAoB,KAC5B,OAAO,CAAC,SAAS,CAAC,qBAAqB,CAAC,CAyB1C,CAAC;AAQF,eAAO,MAAM,yBAAyB,GACpC,SAAS,oBAAoB,KAC5B,OAAO,CAAC,SAAS,CAAC,uBAAuB,CAAC,CA2D5C,CAAC"}

package/dist/commands/daemon.js

@@ -0,0 +1,128 @@
+import { RPC_METHODS } from "@appduct/shared";
+import { startDaemon } from "../daemon/daemon.js";
+import { DaemonAlreadyRunningError, readPidFromFile } from "../daemon/pidfile.js";
+import { getStateDirPaths } from "../daemon/state-dir.js";
+import { connectionError } from "../errors.js";
+import { getPackageVersion } from "../package-version.js";
+import { callDaemon, isDaemonUnreachableError, isSameVersion } from "../rpc/client.js";
+export const handleDaemonRunCommand = async (context) => {
+    let daemon;
+    try {
+        daemon = await startDaemon({
+            stateDir: context.stateDir,
+            clock: context.clock,
+            warn: context.warn,
+        });
+    }
+    catch (error) {
+        if (error instanceof DaemonAlreadyRunningError) {
+            throw connectionError(error.message, { pid: error.pid });
+        }
+        throw error;
+    }
+    return {
+        result: {
+            ok: true,
+            data: {
+                daemon: {
+                    pid: process.pid,
+                    state_dir: daemon.paths.root,
+                    socket_path: daemon.paths.socketPath,
+                },
+            },
+        },
+        completion: daemon.exited,
+        stop: () => {
+            void daemon.shutdown();
+        },
+    };
+};
+export const handleDaemonStartCommand = async (context) => {
+    const status = await callDaemon(RPC_METHODS.daemonStatus, {}, { stateDir: context.stateDir, autoSpawn: true, spawn: context.spawn });
+    return {
+        ok: true,
+        data: {
+            daemon: {
+                pid: status.pid,
+                wss_port: status.wssPort,
+                started_at: status.startedAt,
+            },
+        },
+    };
+};
+export const handleDaemonStopCommand = async (context) => {
+    try {
+        await callDaemon(RPC_METHODS.daemonShutdown, {}, { stateDir: context.stateDir, autoSpawn: false });
+        return { ok: true, data: { daemon: { ok: true, method: "rpc" } } };
+    }
+    catch (error) {
+        if (!isDaemonUnreachableError(error)) {
+            throw error;
+        }
+        const paths = getStateDirPaths(context.stateDir);
+        const pid = await readPidFromFile(paths.pidFilePath);
+        if (pid === undefined) {
+            throw connectionError("No Appduct daemon is running.");
+        }
+        process.kill(pid, "SIGTERM");
+        return { ok: true, data: { daemon: { ok: true, method: "sigterm" } } };
+    }
+};
+/** Drops the entries whose value is `undefined`, so spreading the result adds only keys that
+ * carry an actual answer. */
+const definedOnly = (fields) => {
+    return Object.fromEntries(Object.entries(fields).filter(([, value]) => value !== undefined));
+};
+export const handleDaemonStatusCommand = async (context) => {
+    const status = await callDaemon(RPC_METHODS.daemonStatus, {}, { stateDir: context.stateDir, autoSpawn: true, spawn: context.spawn });
+    // The wire type declares the retention fields required, as it must for any daemon built from
+    // this tree — but the daemon on the other end of the socket may predate them, and a running
+    // daemon outlives the CLI upgrade that would replace it. Reading them through a partial view
+    // keeps that possibility in the types instead of in a comment, and leaves each one `undefined`
+    // rather than `0` when it was never reported.
+    const retention = status.audit;
+    const clientVersion = context.clientVersion ?? getPackageVersion();
+    // Guarded the same way the version check guards it (`rpc/client.ts`): a `daemon.status` without
+    // `sessions` would otherwise throw from the middle of the command that exists to diagnose a
+    // daemon — the one command that must keep working against a daemon it does not fully understand.
+    const sessionCount = Array.isArray(status.sessions) ? status.sessions.length : 0;
+    const pendingLinkCount = typeof status.pendingLinks === "number" ? status.pendingLinks : 0;
+    // Names the same cost the restart path names (`rpc/client.ts`), so the diagnosis an operator
+    // reads here and the error they hit on the next command tell one consistent story: an unclaimed
+    // link is destroyed by a restart just as surely as a session is.
+    const atStake = `${sessionCount} session(s) and ${pendingLinkCount} unclaimed link(s)`;
+    const warning = isSameVersion(status.version, clientVersion)
+        ? undefined
+        : `Version drift: this daemon is ${status.version} but the CLI is ${clientVersion}. ` +
+            `Newer RPC methods will fail against it — run "appduct daemon stop" (this drops ${atStake}) ` +
+            `and the next command will start a matching daemon, or pass "--daemon-restart" to any command to replace it in place.`;
+    return {
+        ok: true,
+        data: {
+            warning,
+            daemon: {
+                version: status.version,
+                pid: status.pid,
+                started_at: status.startedAt,
+                wss_port: status.wssPort,
+                pinned_keys: status.pinnedKeys,
+                session_count: sessionCount,
+            },
+            policy: status.policy,
+            audit: {
+                path: status.audit.path,
+                failed_writes: status.audit.failedWrites,
+                // Spread so an unreported field is a *missing key*, not a key holding `undefined`. The two
+                // serialize identically, but only the first is honestly shaped: a caller can ask whether
+                // the daemon answered, and `--json` consumers see the same absence in-process as on the
+                // wire.
+                ...definedOnly({
+                    failed_prunes: retention.failedPrunes,
+                    retention_days: retention.retentionDays,
+                    files: retention.files,
+                    bytes: retention.bytes,
+                }),
+            },
+        },
+    };
+};

package/dist/commands/doctor.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `appduct doctor <artifact>` (docs/tasks/08-appduct-doctor.md): the release-gate replacement
+ * for the runtime `debuggable` check removed elsewhere in opt-in hardening — see
+ * `artifact-inspect.ts`'s doc comment for the detection strategy and why it never collapses a
+ * missing-tool or unreadable-artifact case into "absent".
+ *
+ * This handler owns only the CLI-facing concerns: option validation (mutually exclusive
+ * `--assert-present`/`--assert-absent`) and turning a failed assertion into a distinct
+ * {@link assertionError} exit, separate from `inspectionError`'s "couldn't tell" exit. All artifact
+ * inspection itself lives in `artifact-inspect.ts`, unit-testable without going through the CLI.
+ */
+import type { CliResult, DoctorCommandData } from "../cli/result-types.js";
+import { type ExecBufferFn } from "../artifact-inspect.js";
+export type DoctorCommandOptions = {
+    artifactPath?: string;
+    assertPresent?: boolean;
+    assertAbsent?: boolean;
+};
+export type DoctorCommandContext = {
+    exec?: ExecBufferFn;
+};
+export declare const handleDoctorCommand: (options: DoctorCommandOptions, context?: DoctorCommandContext) => Promise<CliResult<DoctorCommandData>>;
+//# sourceMappingURL=doctor.d.ts.map

package/dist/commands/doctor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAE3E,OAAO,EAAmB,KAAK,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAG5E,MAAM,MAAM,oBAAoB,GAAG;IACjC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,CAAC,EAAE,YAAY,CAAC;CACrB,CAAC;AAEF,eAAO,MAAM,mBAAmB,GAC9B,SAAS,oBAAoB,EAC7B,UAAS,oBAAyB,KACjC,OAAO,CAAC,SAAS,CAAC,iBAAiB,CAAC,CAyCtC,CAAC"}

package/dist/commands/doctor.js

@@ -0,0 +1,42 @@
+/**
+ * `appduct doctor <artifact>` (docs/tasks/08-appduct-doctor.md): the release-gate replacement
+ * for the runtime `debuggable` check removed elsewhere in opt-in hardening — see
+ * `artifact-inspect.ts`'s doc comment for the detection strategy and why it never collapses a
+ * missing-tool or unreadable-artifact case into "absent".
+ *
+ * This handler owns only the CLI-facing concerns: option validation (mutually exclusive
+ * `--assert-present`/`--assert-absent`) and turning a failed assertion into a distinct
+ * {@link assertionError} exit, separate from `inspectionError`'s "couldn't tell" exit. All artifact
+ * inspection itself lives in `artifact-inspect.ts`, unit-testable without going through the CLI.
+ */
+import { inspectArtifact } from "../artifact-inspect.js";
+import { assertionError, usageError } from "../errors.js";
+export const handleDoctorCommand = async (options, context = {}) => {
+    if (!options.artifactPath) {
+        throw usageError("Usage: appduct doctor <path-to-artifact> [--assert-present | --assert-absent]");
+    }
+    if (options.assertPresent && options.assertAbsent) {
+        throw usageError("--assert-present and --assert-absent are mutually exclusive.");
+    }
+    const inspection = await inspectArtifact(options.artifactPath, { exec: context.exec });
+    const data = {
+        artifact: options.artifactPath,
+        platform: inspection.platform,
+        format: inspection.format,
+        present: inspection.present,
+        signals: inspection.signals,
+    };
+    if (options.assertPresent && !inspection.present) {
+        throw assertionError(`Expected Appduct to be present in "${options.artifactPath}", but no inclusion signal was found.`, data);
+    }
+    if (options.assertAbsent && inspection.present) {
+        throw assertionError(`Expected Appduct to be absent from "${options.artifactPath}", but found: ${inspection.signals.join(", ")}.`, data);
+    }
+    if (options.assertPresent || options.assertAbsent) {
+        data.assertion = {
+            expected: options.assertPresent ? "present" : "absent",
+            holds: true,
+        };
+    }
+    return { ok: true, data };
+};

package/dist/commands/events.d.ts

@@ -0,0 +1,37 @@
+/**
+ * `appduct events` (ARCHITECTURE.md §10): subscribes to `events.subscribe` over a persistent
+ * connection and streams notifications until interrupted (Ctrl-C) or the connection drops. This is
+ * the one command whose output isn't a single rendered `CliResult` — each event is written as it
+ * arrives (NDJSON under `--json`, a human line otherwise) — so it plugs into `executeHostedCommand`
+ * with a live reporter that suppresses the default one-shot bootstrap render (`cli/runner.ts`).
+ *
+ * `--since <cursor>` (issue #6) switches to a one-shot mode: a single `events.since` pull instead
+ * of a live subscription. It falls out of the same `EventsHostedResult` shape (each retained event
+ * is written through `onEvent` exactly like a live one) so the CLI plumbing needs no forking — the
+ * "hosted command" here just completes immediately instead of running until interrupted.
+ */
+import { type EventNotification } from "@appduct/shared";
+import type { CliResult } from "../cli/result-types.js";
+import { type SpawnFn } from "../rpc/client.js";
+export type EventsCommandOptions = {
+    selector?: string;
+    /** Exclusive lower bound on `EventNotification.seq`; switches this command to a one-shot
+     * `events.since` pull instead of a live `events.subscribe` stream. */
+    since?: number;
+};
+export type EventsCommandContext = {
+    stateDir: string;
+    spawn?: SpawnFn;
+    onEvent: (event: EventNotification) => void;
+    /** `--since` mode only: called once with the pull's resulting cursor, so a scripted caller
+     * doesn't have to reconstruct it by maxing `seq` over the printed lines (impossible when the
+     * response is empty — the whole point of a cursor is knowing where to resume from either way). */
+    onCursor?: (cursor: number) => void;
+};
+export type EventsHostedResult = {
+    result: CliResult<never>;
+    completion: Promise<void>;
+    stop: () => void;
+};
+export declare const handleEventsCommand: (options: EventsCommandOptions, context: EventsCommandContext) => Promise<EventsHostedResult>;
+//# sourceMappingURL=events.d.ts.map

package/dist/commands/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/commands/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAe,KAAK,iBAAiB,EAAsD,MAAM,iBAAiB,CAAC;AAE1H,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAoB,KAAK,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAElE,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;0EACsE;IACtE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAC;IAC5C;;sGAEkG;IAClG,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;CACrC,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,MAAM,EAAE,SAAS,CAAC,KAAK,CAAC,CAAC;IACzB,UAAU,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,IAAI,EAAE,MAAM,IAAI,CAAC;CAClB,CAAC;AA4BF,eAAO,MAAM,mBAAmB,GAC9B,SAAS,oBAAoB,EAC7B,SAAS,oBAAoB,KAC5B,OAAO,CAAC,kBAAkB,CAkD5B,CAAC"}

package/dist/commands/events.js

@@ -0,0 +1,76 @@
+/**
+ * `appduct events` (ARCHITECTURE.md §10): subscribes to `events.subscribe` over a persistent
+ * connection and streams notifications until interrupted (Ctrl-C) or the connection drops. This is
+ * the one command whose output isn't a single rendered `CliResult` — each event is written as it
+ * arrives (NDJSON under `--json`, a human line otherwise) — so it plugs into `executeHostedCommand`
+ * with a live reporter that suppresses the default one-shot bootstrap render (`cli/runner.ts`).
+ *
+ * `--since <cursor>` (issue #6) switches to a one-shot mode: a single `events.since` pull instead
+ * of a live subscription. It falls out of the same `EventsHostedResult` shape (each retained event
+ * is written through `onEvent` exactly like a live one) so the CLI plumbing needs no forking — the
+ * "hosted command" here just completes immediately instead of running until interrupted.
+ */
+import { RPC_METHODS } from "@appduct/shared";
+import { openDaemonStream } from "../rpc/client.js";
+const NEVER_RESULT = { ok: true, data: undefined };
+const handleEventsSinceCommand = async (options, context) => {
+    const stream = await openDaemonStream({ stateDir: context.stateDir, spawn: context.spawn });
+    try {
+        const since = await stream.call(RPC_METHODS.eventsSince, {
+            selector: options.selector,
+            since: options.since,
+        });
+        for (const event of since.events) {
+            context.onEvent(event);
+        }
+        context.onCursor?.(since.cursor);
+    }
+    finally {
+        stream.close();
+    }
+    return { result: NEVER_RESULT, completion: Promise.resolve(), stop: () => { } };
+};
+export const handleEventsCommand = async (options, context) => {
+    if (options.since !== undefined) {
+        return handleEventsSinceCommand(options, context);
+    }
+    const stream = await openDaemonStream({ stateDir: context.stateDir, spawn: context.spawn });
+    try {
+        await stream.call(RPC_METHODS.eventsSubscribe, {
+            sessionSelector: options.selector,
+        });
+    }
+    catch (error) {
+        stream.close();
+        throw error;
+    }
+    let resolveCompletion;
+    const completion = new Promise((resolve) => {
+        resolveCompletion = resolve;
+    });
+    const unsubscribeNotifications = stream.onNotification((payload) => {
+        context.onEvent(payload);
+    });
+    let unsubscribeClose = () => { };
+    let stopped = false;
+    const stop = () => {
+        if (stopped) {
+            return;
+        }
+        stopped = true;
+        unsubscribeNotifications();
+        unsubscribeClose();
+        stream.close();
+        resolveCompletion();
+    };
+    // The daemon going away mid-stream (shutdown, crash) must end the command gracefully rather than
+    // hang forever waiting for a Ctrl-C that will never resolve anything.
+    unsubscribeClose = stream.onClose(stop);
+    return {
+        // Never rendered: the reporter passed to `executeHostedCommand` suppresses the bootstrap
+        // render for this command (see the doc comment above).
+        result: NEVER_RESULT,
+        completion,
+        stop,
+    };
+};