things-api 0.19.0 → 0.19.1

package/README.md

@@ -1,8 +1,10 @@
+<img src="assets/things-api-icon-160x160.png" alt="" width="80" height="80">
+
 # things-api
 
 A typed TypeScript library + CLI (`things`) for programmatic interaction with [Things 3](https://culturedcode.com/things/) by Cultured Code.
 
-**Status: read + write + MCP layers live and published to npm (v0.19.0 — see [CHANGELOG.md](CHANGELOG.md)).** Reads go straight to the local SQLite database (UI-exact Today ordering, sidebar-grouped Anytime/Someday with container-status cascade, decoded repeat rules, occurrence projections); writes run a verified pipeline over four write vectors — two lab-validated headless surfaces (the URL scheme + AppleScript) and two opt-in surfaces (Apple Shortcuts and an Accessibility-driven GUI vector) — with hazard guards, disruption-tier policy, a JSONL audit trail, batch mode, audit-replay undo (transactional across compound operations), full project lifecycle (complete/cancel/reopen/restore), heading rename/archive/unarchive with children policies, container detach, granular stateful checklists, tag hierarchy management incl. un-nesting, completion/creation backdating, Logbook imports, tiered fuzzy name resolution (uuid prefixes, `things:///show?id=` share links), and kind-neutral in-place reordering within any container or view (one `things reorder <refs…> [--start|--end|--before|--after] --in <target>` verb — Today/Evening, a project, an area, a heading's children, someday, inbox — plus `project move-heading` for the headings themselves and `area reorder` for the sidebar). The Apple Shortcuts surface is wired for the two headless capabilities nothing else can do: creating a heading in an existing project (`things project add-heading`) and clearing a reminder from a date-scheduled item (`things todo clear-reminder`). Both run through bundled proxy shortcuts (`things setup`) and are gated on their presence. The fourth vector — the Accessibility-driven GUI vector — is off by default and drives the local Things app to reach transforms that exist on no scriptable surface (repeat-rule editing on existing to-dos and projects, convert-to-project, sidebar area reorder); see [Accessibility GUI vector](#accessibility-gui-vector-optional-off-by-default) below. Single-item permanent delete stays interactive-only (its macOS consent has no always-allow) and is out of the headless pipeline. See [docs/design/](docs/design/) for the architecture and VM-lab design, [docs/lab/](docs/lab/harness.md) for the probe harness and campaign results the write layer is grounded in, and [docs/atlas/](docs/atlas/schema-v26.md) for the database↔UI map.
+**Status: read + write + MCP layers live and published to npm (v0.19.1 — see [CHANGELOG.md](CHANGELOG.md)).** Reads go straight to the local SQLite database (UI-exact Today ordering, sidebar-grouped Anytime/Someday with container-status cascade, decoded repeat rules, occurrence projections); writes run a verified pipeline over four write vectors — two lab-validated headless surfaces (the URL scheme + AppleScript) and two opt-in surfaces (Apple Shortcuts and an Accessibility-driven GUI vector) — with hazard guards, disruption-tier policy, a JSONL audit trail, batch mode, audit-replay undo (transactional across compound operations), full project lifecycle (complete/cancel/reopen/restore), heading rename/archive/unarchive with children policies, container detach, granular stateful checklists, tag hierarchy management incl. un-nesting, completion/creation backdating, Logbook imports, tiered fuzzy name resolution (uuid prefixes, `things:///show?id=` share links), and kind-neutral in-place reordering within any container or view (one `things reorder <refs…> [--start|--end|--before|--after] --in <target>` verb — Today/Evening, a project, an area, a heading's children, someday, inbox — plus `project move-heading` for the headings themselves and `area reorder` for the sidebar). The Apple Shortcuts surface is wired for the two headless capabilities nothing else can do: creating a heading in an existing project (`things project add-heading`) and clearing a reminder from a date-scheduled item (`things todo clear-reminder`). Both run through bundled proxy shortcuts (`things setup`) and are gated on their presence. The fourth vector — the Accessibility-driven GUI vector — is off by default and drives the local Things app to reach transforms that exist on no scriptable surface (repeat-rule editing on existing to-dos and projects, convert-to-project, sidebar area reorder); see [Accessibility GUI vector](#accessibility-gui-vector-optional-off-by-default) below. Single-item permanent delete stays interactive-only (its macOS consent has no always-allow) and is out of the headless pipeline. See [docs/design/](docs/design/) for the architecture and VM-lab design, [docs/lab/](docs/lab/harness.md) for the probe harness and campaign results the write layer is grounded in, and [docs/atlas/](docs/atlas/schema-v26.md) for the database↔UI map.
 
 ```sh
 things today --json                # read: your Today list, Evening split, UI order

package/dist/audit/schema.d.ts

@@ -1,4 +1,4 @@
-import type { OccurrenceResolution } from "../write/verify/delta.ts";
+import type { DeltaSpec, OccurrenceResolution } from "../write/verify/delta.ts";
 export interface AuditRecord {
     v: 1;
     ts: string;
@@ -51,6 +51,18 @@ export interface AuditRecord {
      * call returned without re-reading the database.
      */
     occurrence?: OccurrenceResolution;
+    /**
+     * AMBIGUOUS-OUTCOME reconciliation key (ADDITIVE): the expected-state
+     * assertion this attempt was verifying, recorded on `verify-failed:timeout`
+     * records only — the one result class where the change may or may not have
+     * landed. A resubmission carrying the same `opId` re-evaluates THIS assertion
+     * against current state to decide whether the timed-out change is there
+     * (replay it as already-applied) or absent (execute normally), so the presence
+     * test is the attempt's OWN oracle rather than a per-operation guess
+     * (`src/write/opid.ts`). Absent on every other record — and an absent one is a
+     * refusal to guess, never an assumption either way.
+     */
+    expected?: DeltaSpec;
     /** Normalized requested delta (params as given, post-normalization). */
     requested: Record<string, unknown>;
     /** Asserted-field subset of the pre-state (null when target didn't exist). */
@@ -59,7 +71,12 @@ export interface AuditRecord {
     observed: Record<string, unknown> | null;
     result: "intent" | "ok" | "verify-failed:timeout" | "verify-failed:mismatch" | "verify-failed:silent-noop"
     /** A GUI drive stopped because the Things window was unreachable/unresponsive (#512). */
-     | "verify-failed:ui-unreachable" | `blocked:${string}` | "unsupported";
+     | "verify-failed:ui-unreachable"
+    /**
+     * The requested change landed, but a field the caller never named moved with it
+     * and nothing in the operation's vocabulary attributes the movement (CGRD1).
+     */
+     | "verify-failed:collateral" | `blocked:${string}` | "unsupported";
     verify: {
         attempts: number;
         elapsedMs: number;

package/dist/audit/schema.js.map

@@ -1 +1 @@
-{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/audit/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AA8EzC;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,SAAS,CACvB,MAA0E;IAE1E,IAAI,MAAM,CAAC,GAAG,EAAE,IAAI,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;IACzD,yEAAyE;IACzE,wEAAwE;IACxE,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC;QAC9B,MAAM,CAAC,EAAE;QACT,MAAM,CAAC,EAAE;QACT,MAAM,CAAC,KAAK;QACZ,MAAM,CAAC,IAAI;QACX,MAAM,CAAC,IAAI,IAAI,EAAE;KAClB,CAAC,CAAC;IACH,MAAM,MAAM,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAChF,OAAO,KAAK,MAAM,EAAE,CAAC;AACvB,CAAC"}
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/audit/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AA+FzC;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,SAAS,CACvB,MAA0E;IAE1E,IAAI,MAAM,CAAC,GAAG,EAAE,IAAI,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;IACzD,yEAAyE;IACzE,wEAAwE;IACxE,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC;QAC9B,MAAM,CAAC,EAAE;QACT,MAAM,CAAC,EAAE;QACT,MAAM,CAAC,KAAK;QACZ,MAAM,CAAC,IAAI;QACX,MAAM,CAAC,IAAI,IAAI,EAAE;KAClB,CAAC,CAAC;IACH,MAAM,MAAM,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAChF,OAAO,KAAK,MAAM,EAAE,CAAC;AACvB,CAAC"}

package/dist/capability.d.ts

@@ -1,7 +1,8 @@
+import { type TargetWake } from "./deputy/wake.ts";
 import { type HostAccessDeps, type HostApp } from "./host-access.ts";
 export { fdaGranted, type FdaVerdict, type HostApp, hostApp, hostDisplayName, tccDbPath, } from "./host-access.ts";
 /** The Things application's bundle identifier — the Automation grant's target. */
-export declare const THINGS_BUNDLE_ID = "com.culturedcode.ThingsMac";
+export { THINGS_BUNDLE_ID } from "./deputy/wake.ts";
 /** How reads may reach the live library, if at all. */
 export type ReadCapabilityMode = 
 /** A caller-supplied database path — outside the doctrine entirely (Article VI). */
@@ -26,14 +27,37 @@ export type UiCapabilityMode =
  | "config-disabled"
 /** No deputy answers, so there is no identity that could hold the grants. */
  | "helpers-missing"
+/** System Events is down and would not start — a liveness fault, not a grant one. */
+ | "target-unreachable"
 /** The deputy answers but the `--gui` tier is incomplete. */
  | "tier-incomplete";
+/**
+ * Where Things' OWN in-app authorization for the URL scheme stands (URLEN1).
+ *
+ * This is not a macOS consent class at all — `open -g things:///…` is a
+ * LaunchServices dispatch that needs no grant. The gate is the app's: Settings
+ * ▸ General ▸ "Enable Things URLs", recorded as `uriSchemeEnabled` in the
+ * group-container preferences plist. Three states, all measured.
+ */
+export type UrlSchemeCapabilityMode = 
+/** `uriSchemeEnabled = 1` — URL commands execute. */
+"enabled"
+/** `uriSchemeEnabled = 0` — the app drops URL MUTATIONS with no dialog at all. */
+ | "disabled"
+/** No key: nobody has answered the app's first-use dialog on this machine. */
+ | "never-asked"
+/** The plist cannot be reached prompt-free — never resolved by dispatching. */
+ | "unreadable";
 /** How app automation may be delivered, if at all. */
 export type WriteCapabilityMode = 
 /** The deputy is onboarded; Apple Events are sent under the helper identity. */
 "deputy"
+/** Things is not running, so where the deputy's grant stands cannot be read. */
+ | "deputy-target-dormant"
 /** macOS records an Automation grant for the host app against Things. */
  | "direct-granted"
+/** The lab's documented in-guest escape (see {@link WRITE_DIRECT_ESCAPE_ENV}). */
+ | "direct-escape"
 /** macOS records a REFUSAL. It will not re-ask; the human must re-arm it. */
  | "direct-denied"
 /** No record either way, or none readable — never resolved by prompting. */
@@ -53,10 +77,23 @@ export interface Capability<Mode> {
 export type ReadCapability = Capability<ReadCapabilityMode>;
 export type WriteCapability = Capability<WriteCapabilityMode>;
 export type UiCapability = Capability<UiCapabilityMode>;
+export type UrlSchemeCapability = Capability<UrlSchemeCapabilityMode>;
 /** True when this verdict permits opening the live container. */
 export declare function readAllowed(capability: ReadCapability): boolean;
 /** True when this verdict permits driving the Things window. */
 export declare function uiAllowed(capability: UiCapability): boolean;
+/**
+ * True when a URL-scheme MUTATION may be dispatched.
+ *
+ * `unreadable` is permissive, and deliberately so — the asymmetry with the
+ * write gate is the point. There, an unknown standing is refused because
+ * resolving it means sending the Apple Event that IS the dialog. Here,
+ * dispatching costs nothing on a machine whose answer is already "enabled",
+ * which is every settled machine; only the two states we have positively READ
+ * as not-enabled are refused. What catches the unreadable case instead is the
+ * read-after-write verify plus its likely-cause hint (src/write/failure-hints.ts).
+ */
+export declare function urlSchemeAllowed(capability: UrlSchemeCapability): boolean;
 /** True when app automation may be dispatched. */
 export declare function writeAllowed(capability: WriteCapability): boolean;
 /**
@@ -81,6 +118,25 @@ export interface CapabilityDeps extends HostAccessDeps {
         axTrusted: boolean | undefined;
         systemEvents: string | undefined;
     } | null;
+    /**
+     * Start System Events and re-read its Automation standing, for the one state
+     * where the handshake reports liveness instead of authorization
+     * (`not-running`). Prompt-free — see ./deputy/wake.ts for why the launch must
+     * come before the determination.
+     */
+    wakeSystemEvents?: () => TargetWake;
+    /**
+     * Start Things and re-read its Automation standing — the same liveness step
+     * for the AppleScript vector's own target (#617). Consulted ONLY on the
+     * dispatch path: a survey never launches the user's app.
+     */
+    wakeThings?: () => TargetWake;
+    /**
+     * Report a woken target's real standing back to the routing layer, which
+     * defers its `auto` onboarding gate while Things is closed
+     * (./deputy/routing.ts, {@link settleDeputyAutomation}).
+     */
+    settleDeputyAutomation?: (standing: string | undefined) => void;
     /** Is GUI-driving switched on in config (`ui-enabled`)? */
     uiEnabled?: () => boolean;
     /**
@@ -90,6 +146,15 @@ export interface CapabilityDeps extends HostAccessDeps {
     automationAuthValue?: (client: string, target: string) => number | null;
     /** Resolve a running app's display name from its bundle id (LaunchServices). */
     lookupAppName?: (bundleId: string) => string | null;
+    /**
+     * The read standing {@link urlSchemeCapability} consults before it touches
+     * the group container. Defaults to a live {@link readCapability} call.
+     */
+    readStanding?: () => ReadCapability;
+    /** Raw bytes of the Things group-container preferences plist. Throws when unreachable. */
+    readPrefsPlist?: () => Buffer;
+    /** Pull `uriSchemeEnabled` out of those bytes. Throws when the key is absent. */
+    extractUriSchemeEnabled?: (plistBytes: Buffer) => string;
 }
 /**
  * Can this process read the live Things library, and on whose authority?
@@ -107,6 +172,49 @@ export declare class ReadCapabilityError extends Error {
     readonly capability: ReadCapability;
     constructor(capability: ReadCapability);
 }
+/**
+ * The LAB's escape hatch for the AppleScript vector — the write-side twin of
+ * {@link UI_DIRECT_ESCAPE_ENV}, and just as deliberately not consumer surface.
+ *
+ * A guest shell in a golden clone descends from sshd, not from an application
+ * bundle, so `hostApp()` finds no `__CFBundleIdentifier` and macOS has no
+ * identity to have recorded an Automation grant against. The verdict is
+ * therefore `direct-unknown` in every clone, which blocks every AppleScript-
+ * vector verb and every composite carrying an AppleScript leg. What the clone
+ * actually has is an in-guest Automation grant on the runner's own processes
+ * (the same AXVM1 layer the ui escape leans on), so the block is an artefact of
+ * UNKNOWABILITY, not of a missing grant. Setting this to `1` says so.
+ *
+ * Bounded, and the bound is the point: it is consulted ONLY on the
+ * bundle-id-less path. A host that has an identity is answered from its TCC row
+ * as it always was, so the escape can never mask a recorded refusal
+ * (`direct-denied`) or manufacture a grant for a real user's terminal.
+ * Documented in docs/lab/harness.md and exported by the lab's guest
+ * environment; nothing consumer-facing mentions it.
+ */
+export declare const WRITE_DIRECT_ESCAPE_ENV = "THINGS_API_WRITE_DIRECT";
+/**
+ * What a {@link writeCapability} verdict is FOR — the one thing that decides
+ * whether a dormant Things may be started while the verdict is taken (#617).
+ *
+ * The asymmetry with the GUI preflight is deliberate. System Events is a
+ * headless macOS component nobody sees, so {@link uiCapability} wakes it for
+ * every caller. Things is the user's own app: starting it is visible, so only a
+ * caller that is ABOUT TO DRIVE IT may do so.
+ */
+export interface WriteCapabilityOptions {
+    /**
+     * - `survey` (the default) — `doctor`, the MCP startup bake, `--dry-run`.
+     *   Launches nothing and reports a closed Things as the liveness state
+     *   `deputy-target-dormant`.
+     * - `dispatch` — the write gate and the two setup ceremonies, which are about
+     *   to send Things an Apple Event anyway. A dormant target is started in the
+     *   background first and its standing re-read, which is also what keeps the
+     *   operation at tier 0/1: an Apple Event to a CLOSED Things auto-launches it
+     *   WITH focus steal (A40/A41), a background pre-launch does not.
+     */
+    purpose?: "survey" | "dispatch";
+}
 /**
  * May this process drive Things over Apple Events, and on whose authority?
  *
@@ -116,8 +224,21 @@ export declare class ReadCapabilityError extends Error {
  * last state is deliberately NOT resolved here: resolving it means sending a
  * real Apple Event, which is what raises the dialog, and Article I reserves
  * that for `things setup`.
+ *
+ * LIVENESS BEFORE AUTHORIZATION (#617). The deputy's `not-running` is the
+ * ask-false determination having no answer for a CLOSED Things — a fact about
+ * the app's process, not about the grant. Two rules follow, and both matter:
+ *
+ *  - while the deputy is standing, that value NEVER falls through to the direct
+ *    host branch. A silent direct engagement would put consent back on the
+ *    terminal (the routing doctrine's no-fallback rule), and on a machine with
+ *    no host record it would refuse a fully onboarded user with "run
+ *    `things setup`" — the #610 false-onboarding loop, one vector over;
+ *  - a `dispatch` caller resolves it by STARTING Things (a background
+ *    LaunchServices dispatch, never an Apple Event) and re-reading the
+ *    standing. Only what comes back is an authorization fact.
  */
-export declare function writeCapability(deps?: CapabilityDeps): WriteCapability;
+export declare function writeCapability(options?: WriteCapabilityOptions, deps?: CapabilityDeps): WriteCapability;
 /** Thrown when app automation is refused for want of capability (Article II). */
 export declare class WriteCapabilityError extends Error {
     readonly remediation: string[];
@@ -125,7 +246,8 @@ export declare class WriteCapabilityError extends Error {
     constructor(capability: WriteCapability);
 }
 /**
- * The LAB's escape hatch, and deliberately not consumer surface. The VM lab and
+ * The LAB's escape hatch for the ui vector, and deliberately not consumer
+ * surface (its write-side twin is {@link WRITE_DIRECT_ESCAPE_ENV}). The VM lab and
  * the guest e2e bundle drive the UI vector DIRECT — the in-guest Accessibility
  * grant is held by the runner's own processes (the AXVM1 layer), there is no
  * helper bundle in a disposable clone, and there is nobody to answer a dialog
@@ -147,14 +269,54 @@ export declare const UI_DIRECT_ESCAPE_ENV = "THINGS_API_UI_DIRECT";
  *
  * Every answer is prompt-free: the config key is a file read, and the deputy's
  * `hello` carries `AXIsProcessTrusted()` plus its own `AEDeterminePermission`
- * verdict for System Events.
+ * verdict for System Events. The one state that needs more than a read is a
+ * DORMANT System Events, which macOS reaps whenever it has been idle: the
+ * target is started in the background — never by sending it an event — and the
+ * determination re-read, so `not-running` resolves to the truth instead of
+ * masquerading as a missing grant (./deputy/wake.ts).
  */
 export declare function uiCapability(deps?: CapabilityDeps): UiCapability;
+/**
+ * Has Things been authorized to act on `things:///` commands, and how do we know?
+ *
+ * Stateless per invocation, like every other verdict here: the setting is the
+ * user's to flip at any moment, and a cached "yes" would be a stored onboarding
+ * flag by another name. The common case costs one file read plus one `plutil`.
+ *
+ * WHY THIS IS GATED ON THE READ STANDING. The plist lives inside the Things
+ * group container, which is the same `kTCCServiceSystemPolicyAppData` class as
+ * the database — so the open is itself what would raise the app-data modal on a
+ * machine that holds no standing. This function therefore never opens it
+ * speculatively: it asks {@link readCapability} first and reports `unreadable`
+ * unless the container is already reachable (helpers, FDA, or a live session
+ * grant). Where the helpers are serving, the read rides the reader's own
+ * security-scoped bookmark over the container, so the prefs plist is inside the
+ * granted subtree and no host grant is involved at all.
+ *
+ * MEASURED, all three states (URLEN1, golden-v4 / Things 3.23):
+ *
+ *  - `1` — URL mutations execute.
+ *  - `0` — every mutating verb (`add`, token-bearing `update`, the `json`
+ *    batch) is dropped in TOTAL SILENCE: zero row delta, no dialog, no window
+ *    of any kind, and nothing to wait for. Navigation URLs (`things:///show`)
+ *    still work, so this gate covers mutations only.
+ *  - absent — nobody has answered the app's own first-use "Things URL Scheme"
+ *    dialog (Cancel / Enable). The dispatched request PARKS behind that dialog
+ *    rather than being dropped, which is what #611 saw: with nobody at the
+ *    machine, the verify window expired and the write reported a silent no-op.
+ */
+export declare function urlSchemeCapability(deps?: CapabilityDeps): UrlSchemeCapability;
 /** Thrown when GUI-driving is refused for want of capability (Article IV). */
 export declare class UiCapabilityError extends Error {
     readonly remediation: string[];
     readonly capability: UiCapability;
     constructor(capability: UiCapability);
 }
+/** Thrown when a URL-scheme mutation is refused for want of the app's own authorization. */
+export declare class UrlSchemeCapabilityError extends Error {
+    readonly remediation: string[];
+    readonly capability: UrlSchemeCapability;
+    constructor(capability: UrlSchemeCapability);
+}
 /** Test seam: forget the one memo this module keeps (the host's display name). */
 export declare function resetCapabilityForTests(): void;