things-api 0.17.0 → 0.19.0

package/dist/deputy/protocol.js.map

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

package/dist/deputy/routing.d.ts

@@ -0,0 +1,84 @@
+import { type HelpersMode } from "../config.ts";
+import { type DeputyHello, type ReaderHello } from "./protocol.ts";
+export interface DeputyRouting {
+    /** True when requests are actually flowing to the deputy. */
+    readonly active: boolean;
+    /** Why routing is inactive ("disabled", or the activation failure). */
+    readonly reason: string | null;
+    /** Handshake result when active. */
+    readonly hello: DeputyHello | null;
+}
+/** Test seam: forget the per-process activation memo (and close transports). */
+export declare function resetDeputyRoutingForTests(): void;
+/** The per-process routing decision (activated lazily on first ask). */
+export declare function deputyRouting(env?: NodeJS.ProcessEnv): DeputyRouting;
+/** The reader transport's state (activated lazily; test seam via reset). */
+export declare function readerRouting(env?: NodeJS.ProcessEnv): {
+    active: boolean;
+    granted: boolean;
+    hello: ReaderHello | null;
+    reason: string | null;
+};
+/**
+ * What routing actually RESOLVED to in this process: the configured mode plus
+ * whether each half is carrying traffic. Activates both halves (memoized), so
+ * it reports the same decision every other call in this process sees — doctor's
+ * helpers section reads it rather than re-deriving one.
+ */
+export interface HelpersRouting {
+    mode: HelpersMode;
+    /** Automation verbs (osascript/shortcuts) ride the deputy. */
+    automation: boolean;
+    /** File verbs (sql/read-file/locate) ride the granted reader. */
+    files: boolean;
+    /** Why automation is not routed (null when it is). */
+    deputyReason: string | null;
+    /** Why file verbs are not routed (null when they are). */
+    readerReason: string | null;
+}
+export declare function helpersRouting(env?: NodeJS.ProcessEnv): HelpersRouting;
+/** True when file verbs ride the reader (present, protocol-matched, granted). */
+export declare function deputyFilesActive(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Does this machine EXPECT the helpers to carry its reads?
+ *
+ * `true` is an explicit instruction, and under `auto` an installed bundle is
+ * the intent signal (src/deputy/agent-daemon.md §3c). The permissions doctrine
+ * hangs its no-fallback rule on this: when the helpers are expected but cannot
+ * serve, a read refuses loudly instead of quietly re-attaching consent to the
+ * terminal — the exact churn the helpers exist to end. A machine with nothing
+ * installed under `auto` is an ordinary direct machine and is NOT expecting
+ * them, so it falls through to the direct grants as it always has.
+ */
+export declare function helpersExpected(env?: NodeJS.ProcessEnv): boolean;
+/** Why the reader is not carrying reads (null when it is). */
+export declare function readerUnavailableReason(env?: NodeJS.ProcessEnv): string | null;
+/** Blocking FILE-verb round-trip via the granted reader. */
+export declare function fileSyncRequest(fields: Record<string, unknown>, timeoutMs: number, env?: NodeJS.ProcessEnv): Record<string, unknown>;
+/** Blocking round-trip via the bridge (facade + sync probes only). */
+export declare function deputySyncRequest(fields: Record<string, unknown>, timeoutMs: number, env?: NodeJS.ProcessEnv): Record<string, unknown>;
+/** Event-loop-friendly round-trip (vector dispatch). */
+export declare function deputyAsyncRequest(fields: Record<string, unknown>, timeoutMs: number, env?: NodeJS.ProcessEnv): Promise<Record<string, unknown>>;
+/**
+ * The reader-resolved container database path, or null when no granted reader
+ * is active (the caller then locates locally, exactly as before the helpers
+ * existed). The reader's scope is grant-checked, never prompted — a locate
+ * through it can refuse but can never stall on a consent dialog.
+ *
+ * A reader that IS serving and then fails to locate THROWS rather than
+ * returning null. Falling back to a direct locate there would silently move
+ * the read — and its consent — back onto the host app, which the permissions
+ * doctrine forbids (Article I; no-fallback rule). The reader's typed
+ * `not-granted` / `not-found` codes travel out on the error so the CLI can
+ * name the remedy.
+ */
+export declare function deputyDbPath(env?: NodeJS.ProcessEnv): string | null;
+/**
+ * Should DATABASE access route through the deputy? Only for the default
+ * container database: an explicit dbPath option or THINGS_DB env names a
+ * caller-chosen file (lab clones, fixtures) the deputy knows nothing about —
+ * those always open locally, deputy or no deputy.
+ */
+export declare function deputyRoutesDb(options: {
+    dbPath?: string;
+} | undefined, env?: NodeJS.ProcessEnv): boolean;

package/dist/deputy/routing.js

@@ -0,0 +1,422 @@
+/**
+ * Deputy routing: decides ONCE per process whether privileged primitives (SQL
+ * reads, osascript, container file reads) go through the things-deputy broker
+ * or run direct exactly as they always have.
+ *
+ * Mode resolution (highest wins): the CLI `--helpers/--no-helpers` flag (which
+ * writes THINGS_API_HELPERS before any load) → THINGS_API_HELPERS env → stored
+ * `helpers-enabled` config → default `auto`. Direct execution is the contract's
+ * ground truth; the helpers are an alternative transport for the same
+ * primitives.
+ *
+ * The tri-state (docs/design/agent-daemon.md §3c):
+ *
+ * | mode    | helper absent  | installed, unhealthy | healthy, NOT onboarded | healthy + onboarded |
+ * |---------|----------------|----------------------|------------------------|---------------------|
+ * | `auto`  | direct, SILENT | direct, LOUD         | direct, LOUD           | routed              |
+ * | `true`  | direct, LOUD   | direct, LOUD         | routed                 | routed              |
+ * | `false` | direct, silent | direct, silent       | direct, silent         | direct, silent      |
+ *
+ * Under `auto` installation IS the intent signal, so absence is not a
+ * degradation to report (a fresh machine must not nag) while an installed
+ * helper that cannot serve is — silence there would hide the very consent churn
+ * the helpers exist to end.
+ *
+ * There is no "installed but unpermissioned" routing state under `auto`: a
+ * deputy without an app-control grant for Things would move the consent dialog
+ * onto the helper, where nobody is watching for it, so it stays DORMANT until
+ * `things helpers setup` proves the grant. Each half is gated on its OWN
+ * requisite — writes on the deputy's `automation.things`, reads on the
+ * reader's bookmark grant — so a machine that finished half the ceremony gets
+ * the half it earned. Accessibility and System Events are NOT requisite: the
+ * UI vector is separately double-gated and refuses on its own.
+ *
+ * Fallback is decided at ACTIVATION, never mid-operation: if a helper is
+ * expected but unreachable (or speaks a different protocol), the whole process
+ * runs direct with one stderr notice — a half-routed operation is worse than
+ * an honestly direct one. A helper that dies mid-request surfaces as that
+ * request's error; it is never silently retried on the other path.
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { loadConfig } from "../config.js";
+import { readRendezvousToken, rendezvousExists } from "../host-access.js";
+import { DeputySyncBridge } from "./bridge.js";
+import { DeputyAsyncClient } from "./client.js";
+import { emitHelpersNotice, resetHelpersNoticeForTests } from "./notice.js";
+import { DEPUTY_LAUNCHD_LABEL, DEPUTY_PROTOCOL_VERSION, DeputyRequestError, deputyInstalledBinaryPath, deputySocketPath, deputyTokenPath, EXPECTED_HELPERS_VERSION, readerInstalledAppPath, readerSocketPath, readerTokenPath, } from "./protocol.js";
+let state = null;
+let readerState = null;
+/** Test seam: forget the per-process activation memo (and close transports). */
+export function resetDeputyRoutingForTests() {
+    if (state?.active === true) {
+        state.bridge.close();
+        state.client.close();
+    }
+    readerState?.bridge?.close();
+    state = null;
+    readerState = null;
+    resetHelpersNoticeForTests();
+}
+/**
+ * Report a degradation — but only when the mode asks to hear about it. Under
+ * `auto` an ABSENT helper is an ordinary machine, not a fault: `loud` is false
+ * there and the process just runs direct.
+ */
+function notice(loud, message) {
+    if (loud)
+        emitHelpersNotice(message);
+}
+function syncSleep(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+function hello(bridge, token) {
+    const res = bridge.request({ v: DEPUTY_PROTOCOL_VERSION, token, verb: "hello" }, 2000);
+    if (res["ok"] !== true) {
+        const err = res["error"];
+        throw new DeputyRequestError(err?.code ?? "internal", err?.message ?? "handshake refused");
+    }
+    return res;
+}
+/**
+ * Version-skew policy: a PROTOCOL mismatch always deactivates (the shapes on
+ * the wire cannot be trusted). The helpers are versioned on their own line
+ * (EXPECTED_HELPERS_VERSION, decoupled from the package version so unchanged
+ * helpers never nag across package releases); a helpers-version mismatch on
+ * matching protocol gets one automatic `launchctl kickstart` (the installed
+ * bundle may already be newer on disk — the daily npm-link reality), then
+ * proceeds with a notice: the helpers' verbs are dumb primitives, so
+ * cross-version execution is safe by construction as long as the protocol
+ * matches.
+ */
+function reconcileVersions(bridge, token, first) {
+    if (first.deputyVersion === EXPECTED_HELPERS_VERSION)
+        return first;
+    try {
+        execFileSync("launchctl", ["kickstart", "-k", `gui/${process.getuid?.() ?? 501}/${DEPUTY_LAUNCHD_LABEL}`], 
+        // Clears the helpers' drain bound: kickstart -k waits for the old
+        // process, which finishes an in-flight request before exiting.
+        { stdio: "ignore", timeout: 30_000 });
+    }
+    catch {
+        // Not installed under launchd (foreground/test deputy) — nothing to restart.
+        notice(true, `installed helpers are v${first.deputyVersion}, this package expects v${EXPECTED_HELPERS_VERSION} (same protocol) — proceeding; rebuild with \`bash scripts/build-helpers.sh\` + \`things helpers setup\` to align`);
+        return first;
+    }
+    for (let attempt = 0; attempt < 8; attempt++) {
+        syncSleep(250);
+        try {
+            const fresh = hello(bridge, token);
+            if (fresh.deputyVersion === EXPECTED_HELPERS_VERSION)
+                return fresh;
+        }
+        catch {
+            // Restart still in flight — keep waiting out the bounded window.
+        }
+    }
+    const current = hello(bridge, token);
+    notice(true, `installed helpers are v${current.deputyVersion}, this package expects v${EXPECTED_HELPERS_VERSION} (same protocol) — proceeding; rebuild with \`bash scripts/build-helpers.sh\` + \`things helpers setup\` to align`);
+    return current;
+}
+/**
+ * Is a helper half INSTALLED on this machine? Installation is what separates
+ * "this host does not use the helpers" (silent under `auto`) from "the helper
+ * this host installed cannot serve" (always loud). The installed bundle on disk
+ * is the durable signal — a stopped launchd job leaves no socket but the bundle
+ * stays put.
+ */
+function halfInstalled(path, socketPath, tokenPath) {
+    return existsSync(path) || (existsSync(socketPath) && existsSync(tokenPath));
+}
+function activate(env) {
+    const mode = loadConfig(env).helpersMode;
+    if (mode === "false")
+        return { active: false, reason: "disabled", hello: null };
+    const socketPath = deputySocketPath(env);
+    const tokenPath = deputyTokenPath(env);
+    const installed = halfInstalled(deputyInstalledBinaryPath(env), socketPath, tokenPath);
+    // `auto` + nothing installed = an ordinary un-onboarded machine, not a fault.
+    const loud = mode === "true" || installed;
+    if (!existsSync(socketPath) || !existsSync(tokenPath)) {
+        notice(loud, `${installed
+            ? `installed but not running (no socket at ${socketPath})`
+            : "not installed on this machine"} — running DIRECT, so TCC prompts attach to this process. \`things helpers ${installed ? "status` to inspect" : "setup` to change that"}.`);
+        return {
+            active: false,
+            reason: installed
+                ? `deputy not running (no socket at ${socketPath})`
+                : "deputy not installed",
+            hello: null,
+        };
+    }
+    const token = readFileSync(tokenPath, "utf8").trim();
+    const bridge = new DeputySyncBridge(socketPath);
+    let helloResult;
+    try {
+        helloResult = reconcileVersions(bridge, token, hello(bridge, token));
+    }
+    catch (err) {
+        bridge.close();
+        const why = err instanceof Error ? err.message : String(err);
+        // A socket that will not handshake is a broken helper under EVERY non-off
+        // mode — never silent, whatever the mode says about absence.
+        notice(true, `the handshake failed (${why}) — running DIRECT. \`things helpers restart\`, then \`things helpers status\` to inspect.`);
+        return { active: false, reason: `handshake failed: ${why}`, hello: null };
+    }
+    if (helloResult.protocol !== DEPUTY_PROTOCOL_VERSION) {
+        bridge.close();
+        notice(true, `the deputy speaks protocol ${helloResult.protocol}, this package speaks ${DEPUTY_PROTOCOL_VERSION} — running DIRECT. Rebuild with \`bash scripts/build-helpers.sh\` + \`things helpers setup\`.`);
+        return {
+            active: false,
+            reason: `protocol skew (deputy ${helloResult.protocol}, library ${DEPUTY_PROTOCOL_VERSION})`,
+            hello: null,
+        };
+    }
+    // The onboarding gate. Routing writes through a deputy that has no
+    // app-control grant for Things does not move the consent surface anywhere —
+    // it just relocates the dialog to the helper, where nobody is looking. Under
+    // `auto` (installation is the intent signal, not a promise) the deputy must
+    // PROVE the grant before it carries traffic; `true` is an explicit
+    // instruction to route regardless and stays loud on failure.
+    const automationThings = helloResult.automation?.things;
+    if (mode === "auto" && automationThings !== "granted") {
+        bridge.close();
+        // Absent fields = helpers predating the TCC handshake. Not provably
+        // onboarded is not onboarded: fail closed rather than guess.
+        const reason = automationThings === undefined
+            ? `onboarding not provable (helpers v${helloResult.deputyVersion} predate the permission handshake)`
+            : `onboarding incomplete (automation → Things: ${automationThings})`;
+        notice(true, automationThings === undefined
+            ? `the installed helpers (v${helloResult.deputyVersion}) cannot report their macOS permission standing, so app automation runs DIRECT — rebuild with \`bash scripts/build-helpers.sh\`, then \`things helpers setup\`.`
+            : `the helpers have no app-control permission for Things (${automationThings}), so app automation runs DIRECT — \`things helpers setup\` settles it in one sitting.`);
+        return { active: false, reason, hello: null };
+    }
+    return {
+        active: true,
+        reason: null,
+        hello: helloResult,
+        token,
+        bridge,
+        client: new DeputyAsyncClient(socketPath),
+    };
+}
+/** The per-process routing decision (activated lazily on first ask). */
+export function deputyRouting(env = process.env) {
+    state ??= activate(env);
+    return state;
+}
+function activeState(env) {
+    const routing = deputyRouting(env);
+    return routing.active ? state : null;
+}
+function readerInactive(reason) {
+    return {
+        active: false,
+        granted: false,
+        hello: null,
+        token: "",
+        bridge: null,
+        reason,
+    };
+}
+function activateReader(env) {
+    const mode = loadConfig(env).helpersMode;
+    if (mode === "false")
+        return readerInactive("disabled");
+    // The rendezvous is `<state>/reader` — our own directory, outside every App
+    // Sandbox container — so these are ordinary file touches from any host app.
+    // No guard, no consent class, nothing to prove before looking.
+    const socketPath = readerSocketPath(env);
+    const tokenPath = readerTokenPath(env);
+    const installed = halfInstalled(readerInstalledAppPath(env), socketPath, tokenPath);
+    if (!rendezvousExists(socketPath) || !rendezvousExists(tokenPath)) {
+        // launchd creates the socket when the reader's LaunchAgent is loaded, and
+        // install mints the token beside it — so an absent rendezvous means the
+        // pair was never installed here, or its LaunchAgent is not loaded.
+        // Absence is silent under `auto`; under `true` the caller asserted routing.
+        // An UNGRANTED reader is deliberately NOT noticed here — that is the
+        // ceremony's own state, reported by `things helpers status` and doctor.
+        notice(mode === "true" || installed, installed
+            ? `the reader is installed but not registered with launchd (no rendezvous at ${socketPath}) — database reads run DIRECT. \`things helpers setup\` to re-register it.`
+            : "the reader is not installed on this machine — database reads run DIRECT. `things helpers setup` to change that.");
+        return readerInactive(installed ? `reader not registered with launchd (no ${socketPath})` : "reader not installed");
+    }
+    const token = readRendezvousToken(tokenPath);
+    if (token === null) {
+        notice(true, `the reader's access token could not be read (${tokenPath}) — database reads run DIRECT. \`things helpers setup\` to mint a fresh one.`);
+        return readerInactive(`the reader's access token could not be read (${tokenPath})`);
+    }
+    const bridge = new DeputySyncBridge(socketPath);
+    try {
+        const res = bridge.request({ v: DEPUTY_PROTOCOL_VERSION, token, verb: "hello" }, 2000);
+        if (res["ok"] !== true)
+            throw new DeputyRequestError("handshake", JSON.stringify(res["error"]));
+        const readerHello = res;
+        if (readerHello.protocol !== DEPUTY_PROTOCOL_VERSION) {
+            bridge.close();
+            notice(true, `the reader speaks protocol ${readerHello.protocol}, this package speaks ${DEPUTY_PROTOCOL_VERSION} — database reads run DIRECT. Rebuild with \`bash scripts/build-helpers.sh\` + \`things helpers setup\`.`);
+            return readerInactive(`protocol skew (reader ${readerHello.protocol})`);
+        }
+        return {
+            active: true,
+            granted: readerHello.granted === true,
+            hello: readerHello,
+            token,
+            bridge,
+            reason: null,
+        };
+    }
+    catch (err) {
+        bridge.close();
+        const why = err instanceof Error ? err.message : String(err);
+        notice(true, `the reader handshake failed (${why}) — database reads run DIRECT. \`things helpers restart\`, then \`things helpers status\` to inspect.`);
+        return readerInactive(`reader handshake failed: ${why}`);
+    }
+}
+/** The reader transport's state (activated lazily; test seam via reset). */
+export function readerRouting(env = process.env) {
+    readerState ??= activateReader(env);
+    return readerState;
+}
+/**
+ * The transport serving FILE verbs (sql / read-file / locate): the sandboxed
+ * reader when present AND granted, else null (direct local access). ONLY the
+ * reader — the deputy is mutations-only by design (the maintainer's ruling
+ * 2026-08-21: no multi-step fallback chains; its container access would ride
+ * the per-process consent class this pair exists to end). A reader that dies
+ * mid-request errors that request honestly, never a silent transport switch.
+ */
+function fileTransport(env) {
+    const reader = readerRouting(env);
+    if (reader.active && reader.granted) {
+        const rs = readerState;
+        return { bridge: rs.bridge, token: rs.token };
+    }
+    return null;
+}
+export function helpersRouting(env = process.env) {
+    const mode = loadConfig(env).helpersMode;
+    const deputy = deputyRouting(env);
+    const reader = readerRouting(env);
+    const files = deputyFilesActive(env);
+    return {
+        mode,
+        automation: deputy.active,
+        files,
+        deputyReason: deputy.reason,
+        readerReason: files
+            ? null
+            : reader.active && !reader.granted
+                ? "reader running but NOT granted (things helpers setup)"
+                : reader.reason,
+    };
+}
+/** True when file verbs ride the reader (present, protocol-matched, granted). */
+export function deputyFilesActive(env = process.env) {
+    return fileTransport(env) !== null;
+}
+/**
+ * Does this machine EXPECT the helpers to carry its reads?
+ *
+ * `true` is an explicit instruction, and under `auto` an installed bundle is
+ * the intent signal (src/deputy/agent-daemon.md §3c). The permissions doctrine
+ * hangs its no-fallback rule on this: when the helpers are expected but cannot
+ * serve, a read refuses loudly instead of quietly re-attaching consent to the
+ * terminal — the exact churn the helpers exist to end. A machine with nothing
+ * installed under `auto` is an ordinary direct machine and is NOT expecting
+ * them, so it falls through to the direct grants as it always has.
+ */
+export function helpersExpected(env = process.env) {
+    const mode = loadConfig(env).helpersMode;
+    if (mode === "false")
+        return false;
+    if (mode === "true")
+        return true;
+    // Both halves of the question live in our own state directory now — the
+    // installed bundle and the rendezvous alike — so this is always answerable
+    // from any host, with no probe that could prompt.
+    if (existsSync(readerInstalledAppPath(env)))
+        return true;
+    return rendezvousExists(readerSocketPath(env)) && rendezvousExists(readerTokenPath(env));
+}
+/** Why the reader is not carrying reads (null when it is). */
+export function readerUnavailableReason(env = process.env) {
+    if (deputyFilesActive(env))
+        return null;
+    const reader = readerRouting(env);
+    if (reader.active && !reader.granted) {
+        return "the reader is running but holds no read grant for the Things data folder";
+    }
+    return reader.reason;
+}
+/** Blocking FILE-verb round-trip via the granted reader. */
+export function fileSyncRequest(fields, timeoutMs, env = process.env) {
+    const transport = fileTransport(env);
+    if (transport === null) {
+        throw new DeputyRequestError("inactive", "the reader is not active");
+    }
+    return unwrap(transport.bridge.request({ v: DEPUTY_PROTOCOL_VERSION, token: transport.token, ...fields }, timeoutMs));
+}
+/** Unwrap a protocol response: return it on ok, throw DeputyRequestError otherwise. */
+function unwrap(res) {
+    if (res["ok"] === true)
+        return res;
+    const err = res["error"];
+    throw new DeputyRequestError(err?.code ?? "internal", err?.message ?? "deputy refused the request");
+}
+/** Blocking round-trip via the bridge (facade + sync probes only). */
+export function deputySyncRequest(fields, timeoutMs, env = process.env) {
+    const active = activeState(env);
+    if (active === null)
+        throw new DeputyRequestError("inactive", "deputy routing is not active");
+    return unwrap(active.bridge.request({ v: DEPUTY_PROTOCOL_VERSION, token: active.token, ...fields }, timeoutMs));
+}
+/** Event-loop-friendly round-trip (vector dispatch). */
+export async function deputyAsyncRequest(fields, timeoutMs, env = process.env) {
+    const active = activeState(env);
+    if (active === null)
+        throw new DeputyRequestError("inactive", "deputy routing is not active");
+    return unwrap(await active.client.request({ v: DEPUTY_PROTOCOL_VERSION, token: active.token, ...fields }, timeoutMs));
+}
+/**
+ * The reader-resolved container database path, or null when no granted reader
+ * is active (the caller then locates locally, exactly as before the helpers
+ * existed). The reader's scope is grant-checked, never prompted — a locate
+ * through it can refuse but can never stall on a consent dialog.
+ *
+ * A reader that IS serving and then fails to locate THROWS rather than
+ * returning null. Falling back to a direct locate there would silently move
+ * the read — and its consent — back onto the host app, which the permissions
+ * doctrine forbids (Article I; no-fallback rule). The reader's typed
+ * `not-granted` / `not-found` codes travel out on the error so the CLI can
+ * name the remedy.
+ */
+export function deputyDbPath(env = process.env) {
+    const reader = readerRouting(env);
+    if (!reader.active || !reader.granted)
+        return null;
+    if (reader.hello?.dbPath != null)
+        return reader.hello.dbPath;
+    const rs = readerState;
+    if (rs.dbPathMemo !== undefined && rs.dbPathMemo !== null)
+        return rs.dbPathMemo;
+    const res = fileSyncRequest({ verb: "locate" }, 10_000, env);
+    const path = typeof res["path"] === "string" ? res["path"] : null;
+    if (path === null) {
+        throw new DeputyRequestError("not-found", "the reader answered the locate but named no database");
+    }
+    rs.dbPathMemo = path;
+    return path;
+}
+/**
+ * Should DATABASE access route through the deputy? Only for the default
+ * container database: an explicit dbPath option or THINGS_DB env names a
+ * caller-chosen file (lab clones, fixtures) the deputy knows nothing about —
+ * those always open locally, deputy or no deputy.
+ */
+export function deputyRoutesDb(options, env = process.env) {
+    if (options?.dbPath !== undefined || (env["THINGS_DB"] ?? "") !== "")
+        return false;
+    return deputyFilesActive(env);
+}
+//# sourceMappingURL=routing.js.map

package/dist/deputy/routing.js.map

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

package/dist/deputy/shortcuts-exec.d.ts

@@ -0,0 +1,10 @@
+export interface ShortcutsRunResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    timedOut?: boolean;
+}
+/** `shortcuts run <name> --input-path … --output-path …` (the write vector's shape). */
+export declare function shortcutsRunExec(name: string, inputPath: string, outputPath: string, timeoutMs: number): Promise<ShortcutsRunResult>;
+/** `shortcuts list` (availability's proxy census). Returns stdout; throws on failure. */
+export declare function shortcutsListSync(timeoutMs?: number): string;

package/dist/deputy/shortcuts-exec.js

@@ -0,0 +1,50 @@
+/**
+ * The Apple Shortcuts execution seam — the `shortcuts` CLI twin of osa.ts.
+ * Both call sites (the shortcuts write vector's `run`, availability's `list`)
+ * route through the deputy when it is active, so every app-automation surface
+ * shares the deputy's one stable identity; direct mode is byte-identical to
+ * the pre-deputy behavior. The deputy only accepts this library's bundled
+ * `things-proxy-*` shortcut names — it is a paired tool, not a general
+ * shortcut runner.
+ */
+import { execFile, execFileSync } from "node:child_process";
+import {} from "./protocol.js";
+import { deputyAsyncRequest, deputyRouting, deputySyncRequest } from "./routing.js";
+/** Deputy-side kill fires at timeoutMs; the client deadline adds grace so the deputy's honest answer wins. */
+const CLIENT_GRACE_MS = 5000;
+/** `shortcuts run <name> --input-path … --output-path …` (the write vector's shape). */
+export async function shortcutsRunExec(name, inputPath, outputPath, timeoutMs) {
+    if (deputyRouting().active) {
+        const res = (await deputyAsyncRequest({ verb: "shortcuts", op: "run", name, inputPath, outputPath, timeoutMs }, timeoutMs + CLIENT_GRACE_MS));
+        return {
+            exitCode: res.timedOut === true && res.exitCode === 0 ? 1 : res.exitCode,
+            stdout: res.stdout,
+            stderr: res.stderr,
+            ...(res.timedOut === true && { timedOut: true }),
+        };
+    }
+    return new Promise((resolve) => {
+        execFile("shortcuts", ["run", name, "--input-path", inputPath, "--output-path", outputPath], { timeout: timeoutMs }, (err, stdout, stderr) => {
+            // A deadline kill (err.killed) is the signature of an unanswered
+            // first-run consent dialog — surfaced distinctly for attribution.
+            const timedOut = err !== null && err.killed === true;
+            resolve({
+                exitCode: err === null ? 0 : (err.code ?? 1),
+                stdout: String(stdout),
+                stderr: String(stderr),
+                ...(timedOut && { timedOut: true }),
+            });
+        });
+    });
+}
+/** `shortcuts list` (availability's proxy census). Returns stdout; throws on failure. */
+export function shortcutsListSync(timeoutMs = 10_000) {
+    if (!deputyRouting().active) {
+        return execFileSync("shortcuts", ["list"], { encoding: "utf8", timeout: timeoutMs });
+    }
+    const res = deputySyncRequest({ verb: "shortcuts", op: "list", timeoutMs }, timeoutMs + CLIENT_GRACE_MS);
+    if (res.exitCode === 0 && res.timedOut !== true)
+        return res.stdout;
+    throw new Error(`Command failed: shortcuts list\n${res.stderr}`);
+}
+//# sourceMappingURL=shortcuts-exec.js.map

package/dist/deputy/shortcuts-exec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shortcuts-exec.js","sourceRoot":"","sources":["../../src/deputy/shortcuts-exec.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAE5D,OAAO,EAAwB,MAAM,eAAe,CAAC;AACrD,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEpF,8GAA8G;AAC9G,MAAM,eAAe,GAAG,IAAI,CAAC;AAS7B,wFAAwF;AACxF,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,IAAY,EACZ,SAAiB,EACjB,UAAkB,EAClB,SAAiB;IAEjB,IAAI,aAAa,EAAE,CAAC,MAAM,EAAE,CAAC;QAC3B,MAAM,GAAG,GAAG,CAAC,MAAM,kBAAkB,CACnC,EAAE,IAAI,EAAE,WAAW,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,UAAU,EAAE,SAAS,EAAE,EACxE,SAAS,GAAG,eAAe,CAC5B,CAA+B,CAAC;QACjC,OAAO;YACL,QAAQ,EAAE,GAAG,CAAC,QAAQ,KAAK,IAAI,IAAI,GAAG,CAAC,QAAQ,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ;YACxE,MAAM,EAAE,GAAG,CAAC,MAAM;YAClB,MAAM,EAAE,GAAG,CAAC,MAAM;YAClB,GAAG,CAAC,GAAG,CAAC,QAAQ,KAAK,IAAI,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;SACjD,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,QAAQ,CACN,WAAW,EACX,CAAC,KAAK,EAAE,IAAI,EAAE,cAAc,EAAE,SAAS,EAAE,eAAe,EAAE,UAAU,CAAC,EACrE,EAAE,OAAO,EAAE,SAAS,EAAE,EACtB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE;YACtB,iEAAiE;YACjE,kEAAkE;YAClE,MAAM,QAAQ,GAAG,GAAG,KAAK,IAAI,IAAK,GAA4B,CAAC,MAAM,KAAK,IAAI,CAAC;YAC/E,OAAO,CAAC;gBACN,QAAQ,EAAE,GAAG,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAE,GAAyB,CAAC,IAAI,IAAI,CAAC,CAAC;gBACnE,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC;gBACtB,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC;gBACtB,GAAG,CAAC,QAAQ,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;aACpC,CAAC,CAAC;QACL,CAAC,CACF,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC;AAED,yFAAyF;AACzF,MAAM,UAAU,iBAAiB,CAAC,SAAS,GAAG,MAAM;IAClD,IAAI,CAAC,aAAa,EAAE,CAAC,MAAM,EAAE,CAAC;QAC5B,OAAO,YAAY,CAAC,WAAW,EAAE,CAAC,MAAM,CAAC,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC,CAAC;IACvF,CAAC;IACD,MAAM,GAAG,GAAG,iBAAiB,CAC3B,EAAE,IAAI,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,EAC5C,SAAS,GAAG,eAAe,CACE,CAAC;IAChC,IAAI,GAAG,CAAC,QAAQ,KAAK,CAAC,IAAI,GAAG,CAAC,QAAQ,KAAK,IAAI;QAAE,OAAO,GAAG,CAAC,MAAM,CAAC;IACnE,MAAM,IAAI,KAAK,CAAC,mCAAmC,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;AACnE,CAAC"}