things-api 0.18.0 → 0.19.1

package/dist/session-grant.js

@@ -0,0 +1,185 @@
+/**
+ * The instance-scoped app-data grant marker (docs/design/permissions-doctrine.md,
+ * Article III).
+ *
+ * macOS has a consent class beneath Full Disk Access — "would like to access
+ * data from other apps" (`kTCCServiceSystemPolicyAppData`) — that covers the
+ * Things group container. It is MEASURED allow-once-per-responsible-process-
+ * instance: the grant is pinned to the running host app, and it dies when that
+ * app quits. APDP1 (docs/lab/apdp1-grant-pinning.md) settled the axis this
+ * marker rests on — TCC writes the row against the RESPONSIBLE APP (its bundle
+ * id, pinned to that instance's pid + pid_version), never against the pid that
+ * opened the file, so every process under one host-app instance shares a single
+ * grant and a relaunch of the host app re-arms the prompt. It is also, by
+ * TCC's ask-on-access design, undetectable without
+ * FDA: the only way to learn whether you hold it is to open the file, and the
+ * open is what raises the modal. That is precisely what Article I forbids
+ * outside a ceremony.
+ *
+ * So the grant is not detected — it is WITNESSED. `things setup` deliberately
+ * provokes the modal, and if the container open then succeeds it writes this
+ * marker recording WHICH host-app instance the grant was minted for. A later
+ * invocation reads the marker and re-derives that instance's identity; if it
+ * still matches, the grant is necessarily still live and the container may be
+ * opened without risk of a dialog.
+ *
+ * The marker is NOT an "onboarded" flag and cannot become one: it records a
+ * live-instance fact (pid + that pid's start time), so it self-invalidates the
+ * moment the host app quits — because the grant it describes dies at the same
+ * instant. Nothing here can outlive what it describes.
+ *
+ * The one honest hole: a `tccutil reset` performed by the user mid-session
+ * revokes the grant while the app instance keeps running, so the marker stays
+ * valid and the next container open re-prompts. That is user-caused, visible,
+ * and recorded in the doctrine's enforcement inventory rather than papered over.
+ */
+import { execFileSync } from "node:child_process";
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { stateDir } from "./paths.js";
+/**
+ * How far apart two `kern.boottime` readings may sit and still describe the
+ * same boot. MEASURED 2026-08-24: macOS re-derives boot time from the current
+ * clock after sleep/wake, so the value drifts by minutes on a laptop that
+ * suspends — an exact match would invalidate the marker on every lid close.
+ * The pid + start-time pair is what actually carries the guarantee; boot time
+ * is only a coarse guard against pid reuse across a restart, and a restart
+ * moves it by far more than this.
+ */
+const BOOT_TIME_TOLERANCE_SEC = 3600;
+export function sessionGrantPath(env = process.env) {
+    return join(stateDir(env), "session-grant.json");
+}
+function hostPidDefault(bundleId) {
+    try {
+        // LaunchServices answers for RUNNING apps only, which is exactly the
+        // question: a bundle id with no pid means that instance is gone.
+        //
+        // This asks about the RESPONSIBLE APP (the bundle id this process inherited
+        // from it), never about this process — the CLI's own pid is irrelevant to
+        // the grant and would expire the marker on every command. It is also not a
+        // process-tree walk, so it stays correct inside tmux, where the responsible
+        // app is the one that started the tmux server and the ppid chain leads only
+        // to launchd. Where the bundle id names an app that quit and relaunched,
+        // this returns the NEW instance's pid, which fails the marker's pid +
+        // start-time comparison — the marker expires, which is the conservative
+        // answer and the true one: the grant died with the old instance.
+        const out = execFileSync("lsappinfo", ["info", "-only", "pid", bundleId], {
+            encoding: "utf8",
+            timeout: 3000,
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+        const match = /"pid"\s*=\s*(\d+)/.exec(out);
+        const pid = match?.[1] !== undefined ? Number(match[1]) : Number.NaN;
+        return Number.isInteger(pid) && pid > 0 ? pid : null;
+    }
+    catch {
+        return null;
+    }
+}
+function processStartDefault(pid) {
+    try {
+        const out = execFileSync("ps", ["-p", String(pid), "-o", "lstart="], {
+            encoding: "utf8",
+            timeout: 3000,
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+        const trimmed = out.trim();
+        return trimmed === "" ? null : trimmed;
+    }
+    catch {
+        // A dead pid exits nonzero — the instance is gone, which is an answer.
+        return null;
+    }
+}
+function bootTimeDefault() {
+    try {
+        const out = execFileSync("sysctl", ["-n", "kern.boottime"], {
+            encoding: "utf8",
+            timeout: 3000,
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+        const match = /sec\s*=\s*(\d+)/.exec(out);
+        return match?.[1] !== undefined ? Number(match[1]) : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The live identity of the host app instance, or null when it is not running. */
+function currentInstance(bundleId, deps) {
+    const pid = (deps.hostPid ?? hostPidDefault)(bundleId);
+    if (pid === null)
+        return null;
+    const start = (deps.processStart ?? processStartDefault)(pid);
+    return start === null ? null : { pid, start };
+}
+/**
+ * Record that a container open succeeded for the CURRENT host-app instance.
+ * Called by `things setup` only, and only after the open actually worked —
+ * writing this on any other occasion would turn a live-instance fact into the
+ * stored "onboarded" flag the doctrine forbids.
+ */
+export function witnessSessionGrant(bundleId, deps = {}) {
+    const env = deps.env ?? process.env;
+    const instance = currentInstance(bundleId, deps);
+    if (instance === null)
+        return null;
+    const marker = {
+        hostBundleId: bundleId,
+        hostPid: instance.pid,
+        hostStart: instance.start,
+        bootTime: (deps.bootTime ?? bootTimeDefault)() ?? 0,
+        witnessedAt: (deps.now ?? (() => new Date()))().toISOString(),
+    };
+    const path = sessionGrantPath(env);
+    mkdirSync(join(path, ".."), { recursive: true });
+    writeFileSync(path, `${JSON.stringify(marker, null, 2)}\n`, "utf8");
+    return marker;
+}
+/** Forget the marker (a ceremony that finds the grant gone clears the stale claim). */
+export function clearSessionGrant(env = process.env) {
+    rmSync(sessionGrantPath(env), { force: true });
+}
+/**
+ * Is a witnessed app-data grant still live for THIS host-app instance?
+ *
+ * Costs a marker read plus, only when a marker exists, two small process
+ * queries. Never runs at all when Full Disk Access already answers the
+ * question, which is the common direct-mode case.
+ */
+export function sessionGrantValid(bundleId, deps = {}) {
+    const env = deps.env ?? process.env;
+    if (bundleId === null) {
+        return { valid: false, reason: "this process has no host application identity" };
+    }
+    let marker;
+    try {
+        marker = JSON.parse(readFileSync(sessionGrantPath(env), "utf8"));
+    }
+    catch {
+        return { valid: false, reason: "no app-data grant has been witnessed on this machine" };
+    }
+    if (marker.hostBundleId !== bundleId) {
+        return {
+            valid: false,
+            reason: `the witnessed grant belongs to ${marker.hostBundleId}, not ${bundleId}`,
+        };
+    }
+    const instance = currentInstance(bundleId, deps);
+    if (instance === null) {
+        return { valid: false, reason: "the application that held the grant is no longer running" };
+    }
+    if (instance.pid !== marker.hostPid || instance.start !== marker.hostStart) {
+        return {
+            valid: false,
+            reason: "the application that held the grant has been restarted since",
+        };
+    }
+    const boot = (deps.bootTime ?? bootTimeDefault)();
+    if (boot !== null && Math.abs(boot - marker.bootTime) > BOOT_TIME_TOLERANCE_SEC) {
+        return { valid: false, reason: "the machine has restarted since the grant was witnessed" };
+    }
+    return { valid: true, marker };
+}
+//# sourceMappingURL=session-grant.js.map

package/dist/session-grant.js.map

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

package/dist/surface-copy.d.ts

@@ -13,12 +13,28 @@ export declare const DATE_FORMAT = "YYYY-MM-DD";
 export declare const REMINDER_FORMAT = "HH:mm (24-hour)";
 /**
  * Resolution-timestamp value format (`--created-at`/`--completed-at`,
- * `created_at`/`completed_at`): an ISO date or datetime; a bare date normalizes
- * to noon in the effective zone (resolution-timestamp plan §5).
+ * `created_at`/`completed_at`): a date or a datetime whose date and time are
+ * joined by `T` or by a space — both spellings resolve to the same instant. A
+ * bare date normalizes to noon in the effective zone (resolution-timestamp
+ * plan §5).
  */
-export declare const RESOLUTION_DATE_FORMAT = "ISO date or datetime; a date is noon in the effective zone";
+export declare const RESOLUTION_DATE_FORMAT = "YYYY-MM-DD, or YYYY-MM-DD HH:mm with T or a space between date and time; a date is noon in the effective zone";
+/**
+ * The same grammar as {@link RESOLUTION_DATE_FORMAT}, phrased as the "expected"
+ * half of a refusal ("expected … — received …"). Every layer that parses a
+ * resolution timestamp names the accepted spellings with this one string.
+ */
+export declare const RESOLUTION_TIMESTAMP_EXPECTED = "a date (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:mm or YYYY-MM-DD HH:mm)";
 /** How projects, areas, and tags may be referenced. */
 export declare const REF_FORMAT = "uuid or unique name";
+/**
+ * The notes-field format, shared by every `--notes`/`notes` surface: notes is a
+ * markdown field with multi-line support, not a plain text blob. Things renders
+ * the common markdown constructs while leaving the syntax characters in place,
+ * and links a bare URL on its own — so `[label](url)` stays literal text.
+ * Evidence: docs/lab/notesmd-results.md.
+ */
+export declare const NOTES_FORMAT = "markdown, multi-line; a bare URL becomes a link, [label](url) stays literal";
 /**
  * Time-window bound grammar shared by `--since`/`--until` flags: relative
  * periods counted from today (`2w`/`3m`/`1y`) or whole calendar periods

package/dist/surface-copy.js

@@ -13,12 +13,28 @@ export const DATE_FORMAT = "YYYY-MM-DD";
 export const REMINDER_FORMAT = "HH:mm (24-hour)";
 /**
  * Resolution-timestamp value format (`--created-at`/`--completed-at`,
- * `created_at`/`completed_at`): an ISO date or datetime; a bare date normalizes
- * to noon in the effective zone (resolution-timestamp plan §5).
+ * `created_at`/`completed_at`): a date or a datetime whose date and time are
+ * joined by `T` or by a space — both spellings resolve to the same instant. A
+ * bare date normalizes to noon in the effective zone (resolution-timestamp
+ * plan §5).
  */
-export const RESOLUTION_DATE_FORMAT = "ISO date or datetime; a date is noon in the effective zone";
+export const RESOLUTION_DATE_FORMAT = "YYYY-MM-DD, or YYYY-MM-DD HH:mm with T or a space between date and time; a date is noon in the effective zone";
+/**
+ * The same grammar as {@link RESOLUTION_DATE_FORMAT}, phrased as the "expected"
+ * half of a refusal ("expected … — received …"). Every layer that parses a
+ * resolution timestamp names the accepted spellings with this one string.
+ */
+export const RESOLUTION_TIMESTAMP_EXPECTED = "a date (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:mm or YYYY-MM-DD HH:mm)";
 /** How projects, areas, and tags may be referenced. */
 export const REF_FORMAT = "uuid or unique name";
+/**
+ * The notes-field format, shared by every `--notes`/`notes` surface: notes is a
+ * markdown field with multi-line support, not a plain text blob. Things renders
+ * the common markdown constructs while leaving the syntax characters in place,
+ * and links a bare URL on its own — so `[label](url)` stays literal text.
+ * Evidence: docs/lab/notesmd-results.md.
+ */
+export const NOTES_FORMAT = "markdown, multi-line; a bare URL becomes a link, [label](url) stays literal";
 /**
  * Time-window bound grammar shared by `--since`/`--until` flags: relative
  * periods counted from today (`2w`/`3m`/`1y`) or whole calendar periods

package/dist/surface-copy.js.map

@@ -1 +1 @@
-{"version":3,"file":"surface-copy.js","sourceRoot":"","sources":["../src/surface-copy.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,yCAAyC;AACzC,MAAM,CAAC,MAAM,WAAW,GAAG,kDAAkD,CAAC;AAE9E,gEAAgE;AAChE,MAAM,CAAC,MAAM,WAAW,GAAG,YAAY,CAAC;AAExC,6CAA6C;AAC7C,MAAM,CAAC,MAAM,eAAe,GAAG,iBAAiB,CAAC;AAEjD;;;;GAIG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,4DAA4D,CAAC;AAEnG,uDAAuD;AACvD,MAAM,CAAC,MAAM,UAAU,GAAG,qBAAqB,CAAC;AAEhD;;;;GAIG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,oEAAoE,CAAC;AACjG,MAAM,CAAC,MAAM,YAAY,GAAG,+DAA+D,CAAC;AAE5F,sEAAsE;AACtE,MAAM,CAAC,MAAM,kBAAkB,GAAG,EAAE,CAAC;AAErC,2EAA2E;AAC3E,MAAM,CAAC,MAAM,UAAU,GAAG,kCAAkC,kBAAkB,GAAG,CAAC;AAElF,6DAA6D;AAC7D,MAAM,CAAC,MAAM,QAAQ,GAAG,oCAAoC,CAAC;AAE7D;;;;;GAKG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,sDAAsD,CAAC;AAEhF,2EAA2E;AAC3E,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC;AAEvC,8EAA8E;AAC9E,MAAM,CAAC,MAAM,kBAAkB,GAAG,EAAE,CAAC;AAErC,+DAA+D;AAC/D,MAAM,CAAC,MAAM,eAAe,GAAG,mGAAmG,kBAAkB,gCAAgC,CAAC;AAErL,+DAA+D;AAC/D,MAAM,CAAC,MAAM,kBAAkB,GAAG,4DAA4D,qBAAqB,sCAAsC,CAAC;AAE1J,kFAAkF;AAClF,MAAM,CAAC,MAAM,gBAAgB,GAAG,oDAAoD,CAAC;AAErF,oFAAoF;AACpF,MAAM,CAAC,MAAM,gBAAgB,GAAG,sEAAsE,UAAU,yCAAyC,CAAC;AAE1J;;;;;GAKG;AACH,MAAM,CAAC,MAAM,eAAe,GAC1B,qJAAqJ,CAAC;AAExJ;;;;;GAKG;AACH,MAAM,CAAC,MAAM,aAAa,GACxB,obAAob,CAAC;AAEvb;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAAC,MAAsD;IACnF,QAAQ,MAAM,CAAC,MAAM,EAAE,CAAC;QACtB,KAAK,IAAI;YACP,OAAO,EAAE,CAAC;QACZ,KAAK,OAAO;YACV,OAAO;gBACL,wEAAwE;oBACtE,8CAA8C;aACjD,CAAC;QACJ,KAAK,iBAAiB;YACpB,OAAO;gBACL,6EAA6E;oBAC3E,8CAA8C;aACjD,CAAC;IACN,CAAC;AACH,CAAC"}
+{"version":3,"file":"surface-copy.js","sourceRoot":"","sources":["../src/surface-copy.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,yCAAyC;AACzC,MAAM,CAAC,MAAM,WAAW,GAAG,kDAAkD,CAAC;AAE9E,gEAAgE;AAChE,MAAM,CAAC,MAAM,WAAW,GAAG,YAAY,CAAC;AAExC,6CAA6C;AAC7C,MAAM,CAAC,MAAM,eAAe,GAAG,iBAAiB,CAAC;AAEjD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,sBAAsB,GACjC,+GAA+G,CAAC;AAElH;;;;GAIG;AACH,MAAM,CAAC,MAAM,6BAA6B,GACxC,wEAAwE,CAAC;AAE3E,uDAAuD;AACvD,MAAM,CAAC,MAAM,UAAU,GAAG,qBAAqB,CAAC;AAEhD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,YAAY,GACvB,6EAA6E,CAAC;AAEhF;;;;GAIG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,oEAAoE,CAAC;AACjG,MAAM,CAAC,MAAM,YAAY,GAAG,+DAA+D,CAAC;AAE5F,sEAAsE;AACtE,MAAM,CAAC,MAAM,kBAAkB,GAAG,EAAE,CAAC;AAErC,2EAA2E;AAC3E,MAAM,CAAC,MAAM,UAAU,GAAG,kCAAkC,kBAAkB,GAAG,CAAC;AAElF,6DAA6D;AAC7D,MAAM,CAAC,MAAM,QAAQ,GAAG,oCAAoC,CAAC;AAE7D;;;;;GAKG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,sDAAsD,CAAC;AAEhF,2EAA2E;AAC3E,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC;AAEvC,8EAA8E;AAC9E,MAAM,CAAC,MAAM,kBAAkB,GAAG,EAAE,CAAC;AAErC,+DAA+D;AAC/D,MAAM,CAAC,MAAM,eAAe,GAAG,mGAAmG,kBAAkB,gCAAgC,CAAC;AAErL,+DAA+D;AAC/D,MAAM,CAAC,MAAM,kBAAkB,GAAG,4DAA4D,qBAAqB,sCAAsC,CAAC;AAE1J,kFAAkF;AAClF,MAAM,CAAC,MAAM,gBAAgB,GAAG,oDAAoD,CAAC;AAErF,oFAAoF;AACpF,MAAM,CAAC,MAAM,gBAAgB,GAAG,sEAAsE,UAAU,yCAAyC,CAAC;AAE1J;;;;;GAKG;AACH,MAAM,CAAC,MAAM,eAAe,GAC1B,qJAAqJ,CAAC;AAExJ;;;;;GAKG;AACH,MAAM,CAAC,MAAM,aAAa,GACxB,obAAob,CAAC;AAEvb;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAAC,MAAsD;IACnF,QAAQ,MAAM,CAAC,MAAM,EAAE,CAAC;QACtB,KAAK,IAAI;YACP,OAAO,EAAE,CAAC;QACZ,KAAK,OAAO;YACV,OAAO;gBACL,wEAAwE;oBACtE,8CAA8C;aACjD,CAAC;QACJ,KAAK,iBAAiB;YACpB,OAAO;gBACL,6EAA6E;oBAC3E,8CAA8C;aACjD,CAAC;IACN,CAAC;AACH,CAAC"}

package/dist/wizard.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The human stopped the ceremony — Ctrl-D at a gate, a `\x03`/`\x04` arriving
+ * as data, or a closed terminal. Every leg is resumable, so this is a clean
+ * stop and not a failure: the CLI prints the stopped line and exits nonzero.
+ */
+export declare class CeremonyStopped extends Error {
+    constructor(why?: string);
+}
+/**
+ * Run a ceremony's synchronous span with the process's DEFAULT SIGINT/SIGTERM
+ * disposition, so Ctrl-C really does stop it (see the module note above).
+ *
+ * The lifted listeners are restored on the way out. A `once` listener comes
+ * back as a plain one — the CLI's handler exits the process, so it cannot fire
+ * twice, and a ceremony that returns normally never reaches it at all.
+ */
+export declare function withDefaultInterrupts<T>(run: () => T): T;
+export interface WizardDeps {
+    /**
+     * Is a human sitting here? Default: stdin AND stderr are both terminals —
+     * stdin because the gate has to be answerable, stderr because the explainers
+     * have to be visible even when stdout is a pipe carrying `--json`.
+     */
+    interactive?: boolean;
+    /** Where explainers and questions are printed. Default: stderr. */
+    say?: (line: string) => void;
+    /**
+     * Read one line from the human. Default: one line off /dev/tty. `null` means
+     * end of input — Ctrl-D, or a terminal that went away — and stops the
+     * ceremony rather than reading as a bare Enter.
+     */
+    readLine?: () => string | null;
+}
+export interface Wizard {
+    /** True when this run is a guided sitting rather than strict mode. */
+    readonly interactive: boolean;
+    /**
+     * Explain a dialog that is about to be raised, then wait for the human to say
+     * they are ready. A no-op in strict mode — there the upfront banner has
+     * already counted the dialogs and nobody is here to pace them.
+     */
+    explain(lines: string[]): void;
+    /**
+     * Ask a yes/no question. `fallback` is the answer in strict mode (and the
+     * answer a bare Enter gives), so a non-interactive run is never blocked on
+     * one; the flag that decides it non-interactively is the caller's business.
+     */
+    ask(question: string, fallback: boolean): boolean;
+    /**
+     * Offer a leg's alternatives: `lines` describes them, Enter takes the first
+     * one, and typing any of `keys` takes that one. Returns the chosen key, or
+     * `""` for Enter — which is also strict mode's silent answer, so the default
+     * has to be the choice an absent human would want.
+     */
+    choose(lines: string[], keys: string[]): string;
+}
+/** Build the wizard for one ceremony run. Fully injectable for tests. */
+export declare function createWizard(deps?: WizardDeps): Wizard;

package/dist/wizard.js

@@ -0,0 +1,174 @@
+/**
+ * The ceremony wizard — Article V's mode-aware half
+ * (docs/design/permissions-doctrine.md).
+ *
+ * Both setup ceremonies (`things setup` and `things helpers setup`) share this
+ * machinery, because a human sitting at either one needs the same two things:
+ * to be told what is about to appear on screen BEFORE it appears, and to be
+ * allowed to get there at their own pace.
+ *
+ * At a TTY the ceremony is a WIZARD: each prompt-raising leg is preceded by one
+ * plain-language explainer naming the dialog by its actual words and the button
+ * to click, and then the ceremony waits for Enter. Off a TTY it is STRICT mode,
+ * exactly as before: the upfront banner counts the dialogs, waits are bounded,
+ * and an unanswered leg fails the run. The tier question is asked interactively
+ * when nothing else decided it, and answered by the flag when it did.
+ *
+ * TTY-ness is the ONLY signal used, and it selects wizard-vs-strict *inside* a
+ * ceremony only — never behavior anywhere else. There is deliberately no
+ * env-based agent sniffing anywhere in the package (Article V): Article I makes
+ * it unnecessary, because no ordinary command can raise a dialog for an agent
+ * to hang on in the first place.
+ *
+ * ## Why a ceremony runs with the DEFAULT signal disposition
+ *
+ * MEASURED 2026-08-24 (macOS 24.6, node under a pty): a ceremony's gates and
+ * bounded waits are SYNCHRONOUS — a blocking `read(2)` on /dev/tty, or
+ * `Atomics.wait` between polls — so they hold the event loop for their whole
+ * duration. The CLI used to install `process.once("SIGINT", …)` at startup
+ * (../cli/interrupt.ts), and a registered JS listener replaces the kernel's
+ * default disposition with a libuv watcher that can only run a handler ON the
+ * event loop. With the loop held, the signal is queued and never dispatched,
+ * libuv restarts the EINTR'd read, and — because the line discipline keeps
+ * ISIG on, so ^C is consumed as a signal and never arrives as a byte — Ctrl-C
+ * is swallowed COMPLETELY: no handler, no exit, no input. Reproduced both at a
+ * gate and inside a poll; without the listener the same ^C kills node at once.
+ *
+ * The startup install is GONE (the same starvation hit ordinary commands, which
+ * now keep the kernel's disposition and are armed only for the span of a write),
+ * so a ceremony reached from a bare CLI invocation already has nothing to lift.
+ * {@link withDefaultInterrupts} stays as the ceremony's own guarantee: it holds
+ * whatever the process arrives with, and is what makes the promise independent
+ * of who called it.
+ *
+ * The fix is {@link withDefaultInterrupts}: for the span of the ceremony the JS
+ * listeners are lifted, so the kernel terminates the process on ^C exactly as
+ * the copy promises, at the conventional 130. Deliberately NOT fixed by putting
+ * the terminal in raw mode to read ^C as `\x03`: raw mode is what would disable
+ * ISIG and *cause* this class of bug, and it leaves a terminal to restore on
+ * every exit path — including the ones a signal never lets us reach. The gate
+ * stays in canonical mode, so there is no terminal state to restore, and a
+ * `\x03`/`\x04` that does arrive as data (a harness feeding the gate, or
+ * Ctrl-D) is treated as a stop.
+ */
+import { closeSync, openSync, readSync } from "node:fs";
+/** The controlling terminal, so a piped stdout/stdin cannot swallow the gate. */
+const TTY_DEVICE = "/dev/tty";
+/** Signals whose default disposition a ceremony restores while it blocks. */
+const CEREMONY_SIGNALS = ["SIGINT", "SIGTERM"];
+/**
+ * The human stopped the ceremony — Ctrl-D at a gate, a `\x03`/`\x04` arriving
+ * as data, or a closed terminal. Every leg is resumable, so this is a clean
+ * stop and not a failure: the CLI prints the stopped line and exits nonzero.
+ */
+export class CeremonyStopped extends Error {
+    constructor(why = "stopped at the keyboard") {
+        super(`the setup ceremony was ${why}`);
+        this.name = "CeremonyStopped";
+    }
+}
+/**
+ * Run a ceremony's synchronous span with the process's DEFAULT SIGINT/SIGTERM
+ * disposition, so Ctrl-C really does stop it (see the module note above).
+ *
+ * The lifted listeners are restored on the way out. A `once` listener comes
+ * back as a plain one — the CLI's handler exits the process, so it cannot fire
+ * twice, and a ceremony that returns normally never reaches it at all.
+ */
+export function withDefaultInterrupts(run) {
+    const lifted = CEREMONY_SIGNALS.map((signal) => {
+        const listeners = process.listeners(signal);
+        for (const listener of listeners)
+            process.removeListener(signal, listener);
+        return { signal, listeners };
+    });
+    try {
+        return run();
+    }
+    finally {
+        for (const { signal, listeners } of lifted) {
+            for (const listener of listeners)
+                process.on(signal, listener);
+        }
+    }
+}
+function readLineDefault() {
+    let fd;
+    try {
+        fd = openSync(TTY_DEVICE, "r");
+        const buffer = Buffer.alloc(256);
+        const read = readSync(fd, buffer, 0, buffer.length, null);
+        // A zero-byte read is EOF, not an empty answer.
+        return read === 0 ? null : buffer.toString("utf8", 0, read).trim();
+    }
+    catch {
+        // No controlling terminal after all (a ceremony started under a harness
+        // that reported isTTY and then detached). Nobody can answer, so stop.
+        return null;
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                closeSync(fd);
+            }
+            catch {
+                // Nothing here can change the answer we already have.
+            }
+        }
+    }
+}
+function interactiveDefault() {
+    return process.stdin.isTTY === true && process.stderr.isTTY === true;
+}
+/** Build the wizard for one ceremony run. Fully injectable for tests. */
+export function createWizard(deps = {}) {
+    const interactive = deps.interactive ?? interactiveDefault();
+    const say = deps.say ?? ((line) => process.stderr.write(`${line}\n`));
+    const readLine = deps.readLine ?? readLineDefault;
+    /**
+     * One gate: block for the human, with the default signal disposition in
+     * force so Ctrl-C stops the ceremony. Throws {@link CeremonyStopped} on end
+     * of input, or on a `\x03`/`\x04` that reached us as data.
+     */
+    const gate = () => {
+        const answer = withDefaultInterrupts(readLine);
+        if (answer === null)
+            throw new CeremonyStopped("stopped — no more input");
+        if (answer.includes("\u0003") || answer.includes("\u0004"))
+            throw new CeremonyStopped();
+        return answer.trim();
+    };
+    return {
+        interactive,
+        explain(lines) {
+            if (!interactive)
+                return;
+            say("");
+            for (const line of lines)
+                say(line);
+            say("  press Enter when you are ready — Ctrl-C stops here, and rerunning resumes here");
+            gate();
+        },
+        ask(question, fallback) {
+            if (!interactive)
+                return fallback;
+            say("");
+            say(`${question} [${fallback ? "Y/n" : "y/N"}]`);
+            const answer = gate().toLowerCase();
+            if (answer === "")
+                return fallback;
+            return answer.startsWith("y");
+        },
+        choose(lines, keys) {
+            if (!interactive)
+                return "";
+            say("");
+            for (const line of lines)
+                say(line);
+            say(`  press Enter, or type ${keys.join(" / ")} then Enter — Ctrl-C stops here, and rerunning resumes here`);
+            const answer = gate().toLowerCase();
+            return keys.find((key) => answer.startsWith(key)) ?? "";
+        },
+    };
+}
+//# sourceMappingURL=wizard.js.map

package/dist/wizard.js.map

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

package/dist/write/availability.d.ts

@@ -1,28 +1,13 @@
 /** The proxy shortcuts the Shortcuts surface is driven through (lab/shortcuts/). */
 export declare const EXPECTED_PROXIES: readonly ["things-proxy-find-items", "things-proxy-create-heading", "things-proxy-edit-title", "things-proxy-set-detail", "things-proxy-delete-items", "things-proxy-delete-items-permanently"];
-export interface UrlSchemeState {
-    /** true = on, false = off, null = not determinable from disk. */
-    enabled: boolean | null;
-    detail: string;
-}
 export interface ShortcutsState {
     present: string[];
     missing: string[];
     detail: string;
 }
 export interface AvailabilityDeps {
-    /** Test seam: plist path override. */
-    plistPath?: string;
-    /** Test seam: raw `plutil -extract` runner; return the raw value or throw. */
-    extract?: (plistBytes: Buffer) => string;
     /** Test seam: `shortcuts list` runner; return stdout or throw. */
     listShortcuts?: () => string;
 }
-/**
- * Read the "Enable Things URLs" state from disk. `1`/`0` when the toggle has
- * ever been set; the key is absent on an untouched install (the app then
- * holds the first URL write behind an enable dialog).
- */
-export declare function readUrlSchemeEnabled(deps?: AvailabilityDeps): UrlSchemeState;
-/** Which proxy shortcuts are installed (drives the Shortcuts surface + `setup shortcuts`). */
+/** Which proxy shortcuts are installed (drives the Shortcuts surface + `setup`). */
 export declare function readShortcutProxies(deps?: AvailabilityDeps): ShortcutsState;

package/dist/write/availability.js

@@ -1,18 +1,13 @@
 /**
- * Static (no-consent-prompt) availability signals per write surface. The URL
- * scheme's on/off switch lives as `uriSchemeEnabled` in the group-container
- * preferences plist — NOT in TMSettings, and NOT implied by the auth token
- * (the token persists while the feature is off; Phase 21b). The plist bytes
- * are read by this process (the same binary macOS already authorized for the
- * database read) and parsed via `plutil` on stdin, so no new file-access
- * shape is introduced.
+ * Static (no-consent-prompt) availability signals per write surface.
+ *
+ * The URL scheme's own switch used to live here too. It now lives with the
+ * other prompt-free verdicts, as `urlSchemeCapability()` in ../capability.ts:
+ * it gates a dispatch exactly the way the app-control and GUI-driving standings
+ * do, and reading it has a consent story of its own (the plist is inside the
+ * Things group container) that belongs next to the rest of the doctrine.
  */
-import { execFileSync } from "node:child_process";
-import { homedir } from "node:os";
-import { join } from "node:path";
-import { readContainerFileSync } from "../deputy/files.js";
 import { shortcutsListSync } from "../deputy/shortcuts-exec.js";
-const PREFS_PLIST = join("Library/Group Containers/JLMPQHK86H.com.culturedcode.ThingsMac", "Library/Preferences/JLMPQHK86H.com.culturedcode.ThingsMac.plist");
 /** The proxy shortcuts the Shortcuts surface is driven through (lab/shortcuts/). */
 export const EXPECTED_PROXIES = [
     "things-proxy-find-items",
@@ -22,61 +17,11 @@ export const EXPECTED_PROXIES = [
     "things-proxy-delete-items",
     "things-proxy-delete-items-permanently",
 ];
-function defaultExtract(plistBytes) {
-    return execFileSync("plutil", ["-extract", "uriSchemeEnabled", "raw", "-o", "-", "--", "-"], {
-        input: plistBytes,
-        encoding: "utf8",
-        timeout: 5000,
-    });
-}
 function defaultListShortcuts() {
     // Deputy-routed when active (src/deputy/shortcuts-exec.ts); direct otherwise.
     return shortcutsListSync(10000);
 }
-/**
- * Read the "Enable Things URLs" state from disk. `1`/`0` when the toggle has
- * ever been set; the key is absent on an untouched install (the app then
- * holds the first URL write behind an enable dialog).
- */
-export function readUrlSchemeEnabled(deps = {}) {
-    const path = deps.plistPath ?? join(homedir(), PREFS_PLIST);
-    let bytes;
-    try {
-        // Deputy-routed when active (the prefs plist lives in the TCC-protected
-        // group container); plutil below parses the bytes locally, consent-free.
-        bytes = readContainerFileSync(path);
-    }
-    catch {
-        return {
-            enabled: null,
-            detail: "the app's preferences plist is not readable on this machine — the 'Enable Things " +
-                "URLs' state is unknown (check Things > Settings > General)",
-        };
-    }
-    let raw;
-    try {
-        raw = (deps.extract ?? defaultExtract)(bytes).trim();
-    }
-    catch {
-        return {
-            enabled: null,
-            detail: "'Enable Things URLs' has never been toggled on this machine — the app holds the " +
-                "first URL command behind an enable dialog (Things > Settings > General)",
-        };
-    }
-    if (raw === "1" || raw === "true") {
-        return { enabled: true, detail: "'Enable Things URLs' is on" };
-    }
-    if (raw === "0" || raw === "false") {
-        return {
-            enabled: false,
-            detail: "'Enable Things URLs' is OFF (Things > Settings > General) — the app holds URL " +
-                "commands behind an enable dialog instead of executing them",
-        };
-    }
-    return { enabled: null, detail: `unexpected uriSchemeEnabled value: ${raw}` };
-}
-/** Which proxy shortcuts are installed (drives the Shortcuts surface + `setup shortcuts`). */
+/** Which proxy shortcuts are installed (drives the Shortcuts surface + `setup`). */
 export function readShortcutProxies(deps = {}) {
     let listing;
     try {
@@ -102,8 +47,8 @@ export function readShortcutProxies(deps = {}) {
             ? "all proxy shortcuts are installed"
             : present.length === 0
                 ? "no proxy shortcuts are installed — heading creation and dated-reminder clearing " +
-                    "need them (run `things setup shortcuts`)"
-                : `missing: ${missing.join(", ")} (run \`things setup shortcuts\`)`,
+                    "need them (run `things setup`)"
+                : `missing: ${missing.join(", ")} (run \`things setup\`)`,
     };
 }
 //# sourceMappingURL=availability.js.map