things-api 0.18.0 → 0.19.1

package/dist/audit/schema.d.ts

@@ -1,3 +1,4 @@
+import type { DeltaSpec, OccurrenceResolution } from "../write/verify/delta.ts";
 export interface AuditRecord {
     v: 1;
     ts: string;
@@ -41,13 +42,41 @@ export interface AuditRecord {
      * bumped) without a separate read. Absent on writes made without the flag.
      */
     preModDates?: Record<string, number | null>;
+    /**
+     * Template-target composite disclosure (ADDITIVE): which occurrence a
+     * `complete`/`cancel`/`update --exception` aimed at a repeating series
+     * actually wrote, and whether the composite minted it. Recorded on the
+     * composite's SUMMARY record only — the one record its `opId` keys — so an
+     * idempotency replay can hand the caller the same two uuids the original
+     * 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). */
     pre: Record<string, unknown> | null;
     /** Post-verify observation (best-effort on failure). */
     observed: Record<string, unknown> | null;
-    result: "intent" | "ok" | "verify-failed:timeout" | "verify-failed:mismatch" | "verify-failed:silent-noop" | `blocked:${string}` | "unsupported";
+    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"
+    /**
+     * 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;AAiEzC;;;;;;;;;;;;;;;;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

@@ -0,0 +1,322 @@
+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 { 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). */
+"explicit-db"
+/** Reads ride the sandboxed reader; the read itself is the capability check. */
+ | "helpers"
+/** The helpers are expected here but cannot serve — refuse, never fall back. */
+ | "helpers-unavailable"
+/** No helpers, but the host app holds Full Disk Access. */
+ | "direct-fda"
+/** A ceremony witnessed an app-data grant that is still live for this app instance. */
+ | "session-grant"
+/** Nothing can open the container — the caller must run a setup ceremony. */
+ | "none";
+/** How GUI-driving may be delivered, if at all (Article IV). */
+export type UiCapabilityMode = 
+/** The helper pair holds Accessibility + Automation→System Events. */
+"helpers"
+/** The lab's documented in-guest escape (see {@link UI_DIRECT_ESCAPE_ENV}). */
+ | "direct-escape"
+/** GUI-driving is switched off in config — nothing has been asked for yet. */
+ | "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. */
+ | "direct-unknown";
+export interface Capability<Mode> {
+    mode: Mode;
+    /** One sentence of provenance, for `doctor` and for refusal copy. */
+    detail: string;
+    /**
+     * The remediation lines a refusal prints, in the order they should be
+     * offered. Empty when the capability is present.
+     */
+    remediation: string[];
+    /** The identity a direct-mode grant would attach to. */
+    host: HostApp;
+}
+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;
+/**
+ * Injection seams. Every one of these defaults to a real, prompt-free probe;
+ * tests replace them so no test ever touches the host's TCC state.
+ */
+export interface CapabilityDeps extends HostAccessDeps {
+    /** Are this process's database reads actually being served by the reader? */
+    helpersServing?: () => boolean;
+    /** Are the helpers expected on this machine (enabled, and installed under auto)? */
+    helpersExpected?: () => boolean;
+    /** Why the helpers are not serving, for the loud refusal. */
+    helpersReason?: () => string | null;
+    /** The deputy's `automation.things` standing, from its handshake. */
+    deputyAutomation?: () => string | undefined;
+    /**
+     * The deputy's GUI-driving standing, from the same handshake: whether it is
+     * Accessibility-trusted and where its Automation→System Events grant stands.
+     * `null` means no deputy answered at all.
+     */
+    deputyGuiStanding?: () => {
+        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;
+    /**
+     * Read one Automation row out of TCC.db. Returns the raw `auth_value`, or
+     * null when there is no row / the file cannot be read.
+     */
+    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?
+ *
+ * Stateless: every call re-derives the verdict, because a grant can appear or
+ * vanish between one invocation and the next and a cached "yes" would be a
+ * stored onboarding flag by another name. The common case costs one `open(2)`.
+ */
+export declare function readCapability(options?: {
+    dbPath?: string;
+}, deps?: CapabilityDeps): ReadCapability;
+/** Thrown when a read is refused for want of capability (Article II). */
+export declare class ReadCapabilityError extends Error {
+    readonly remediation: string[];
+    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?
+ *
+ * The deputy wins when it is onboarded (its own handshake reports the grant it
+ * holds). Otherwise the host app's own Automation record is read out of TCC —
+ * granted, denied, or, when there is no record at all, `direct-unknown`. That
+ * 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(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[];
+    readonly capability: WriteCapability;
+    constructor(capability: WriteCapability);
+}
+/**
+ * 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
+ * either. Setting this to `1` restores direct UI-vector availability for that
+ * one situation. It is documented in docs/lab/harness.md and exported by the
+ * lab's guest environment; nothing consumer-facing mentions it, and it does not
+ * bypass `ui.enabled` — a lab clone still sets that key explicitly.
+ */
+export declare const UI_DIRECT_ESCAPE_ENV = "THINGS_API_UI_DIRECT";
+/**
+ * May this process drive the Things WINDOW, and on whose authority?
+ *
+ * Article IV admits exactly one provenance: the helper pair. Accessibility on a
+ * general-purpose host app (a terminal, an agent harness, an MCP host) has a
+ * blast radius far beyond Things, churns with every host update, and has no
+ * sane story at all over ssh — so direct AX is unsupported, and a refusal here
+ * names the config knob and `things helpers setup --gui` rather than raising an
+ * Accessibility prompt against whatever happens to be running us.
+ *
+ * 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. 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;