things-api 0.5.0

package/dist/write/pipeline.js

@@ -0,0 +1,375 @@
+/**
+ * The mutation pipeline: fingerprint gate → lock → pre-read → guards →
+ * vector planning → ensure-running → execute → verified read-after-write →
+ * audit. Every mutation attempt is audited, including blocked decisions.
+ */
+import { execFile, execFileSync } from "node:child_process";
+import { localToday } from "../model/dates.js";
+import { COMMANDS } from "./commands.js";
+import { describeEnvironmentChanges, diffEnvironment, } from "./environment.js";
+import { sdefDeclaresPrivateReorder } from "./experimental.js";
+import { classifyTransportFailure, classifyVerifyFailure, } from "./failure-hints.js";
+import { evaluateGuards } from "./guards.js";
+import { acquireMutationLock, MutationLockError } from "./lock.js";
+import { planVector } from "./planner.js";
+import { createDbReader, evaluateDelta, getField, } from "./verify/delta.js";
+import { pollUntilVerified } from "./verify/poller.js";
+export function readAuthToken(db) {
+    try {
+        const row = db.prepare("SELECT uriSchemeAuthenticationToken AS t FROM TMSettings").get();
+        return row?.t ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function defaultIsAppRunning() {
+    try {
+        execFileSync("pgrep", ["-x", "Things3"], { stdio: "ignore" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Background-launch Things and wait for the process (tier 1, by policy). */
+async function defaultEnsureRunning(alreadyRunning) {
+    if (alreadyRunning)
+        return true;
+    await new Promise((resolve) => {
+        execFile("open", ["-g", "-a", "Things3"], () => resolve());
+    });
+    const deadline = Date.now() + 20_000;
+    while (Date.now() < deadline) {
+        if (defaultIsAppRunning()) {
+            await new Promise((r) => setTimeout(r, 2000)); // post-launch settle
+            return true;
+        }
+        await new Promise((r) => setTimeout(r, 250));
+    }
+    return false;
+}
+/** Capture pre-values of asserted fields + movement tripwires for the spec. */
+function capturePre(spec, deps, pre) {
+    const reader = createDbReader(deps.db);
+    const modDates = {};
+    const fields = {};
+    const captureFor = (uuid, assertions) => {
+        modDates[uuid] = reader.modDateOf(uuid);
+        const entity = reader.taskByUuid(uuid);
+        const captured = {};
+        for (const a of assertions) {
+            captured[a.field] = entity === null ? undefined : (getField(entity, a.field) ?? null);
+        }
+        fields[uuid] = captured;
+    };
+    if (spec.mode === "update" || spec.mode === "state") {
+        captureFor(spec.uuid, spec.assert);
+        if (spec.mode === "state" && spec.cascade !== undefined) {
+            for (const c of spec.cascade)
+                captureFor(c.uuid, c.assert);
+        }
+    }
+    if (spec.mode === "ordering") {
+        const preRanks = {};
+        for (const uuid of spec.sequence)
+            preRanks[uuid] = reader.rankOf(uuid, spec.key);
+        fields["__ordering__"] = preRanks;
+    }
+    if (spec.mode === "entity-updated") {
+        const current = reader.entityFields(spec.entity, spec.uuid);
+        const captured = {};
+        for (const a of spec.assert)
+            captured[a.field] = current?.[a.field] ?? null;
+        fields[spec.uuid] = captured;
+    }
+    if (spec.mode === "trash-emptied") {
+        return { modDates, fields, trashedCount: pre.trashedCount };
+    }
+    return { modDates, fields };
+}
+export async function runMutation(deps, op, params, options = {}) {
+    const startedAt = deps.now?.() ?? new Date();
+    const spec = COMMANDS[op];
+    const config = deps.config;
+    const actor = options.actor ?? config.actor;
+    const maxDisruption = options.maxDisruption ?? config.maxDisruption;
+    const audit = (partial) => {
+        const fp = deps.fingerprint();
+        const record = {
+            v: 1,
+            ts: startedAt.toISOString(),
+            actor,
+            host: config.host,
+            op,
+            uuid: null,
+            vector: null,
+            disruption: null,
+            invocation: null,
+            requested: params,
+            pre: null,
+            observed: null,
+            verify: null,
+            durationMs: (deps.now?.() ?? new Date()).getTime() - startedAt.getTime(),
+            env: {
+                pkg: deps.pkgVersion ?? "0.0.1",
+                dbVersion: fp.observation.databaseVersion,
+                fingerprint: fingerprintLabel(fp, config),
+            },
+            ...partial,
+        };
+        deps.audit.append(record);
+    };
+    // 1. Drift gate: writes hard-block on fingerprint mismatch.
+    const fp = deps.fingerprint();
+    const fpLabel = fingerprintLabel(fp, config);
+    if (fpLabel === "drift" || fpLabel === "unknown") {
+        const detail = fp.kind === "unknown-version"
+            ? `unknown database version ${fp.observation.databaseVersion ?? "?"} (newer Things?)`
+            : "schema fingerprint deviates from the shipped baseline";
+        audit({ result: "blocked:drift" });
+        return {
+            kind: "blocked",
+            op,
+            reason: "drift",
+            likelyCause: "schema-drift",
+            detail,
+            remediation: "update things-api to a release with a matching baseline, or (at your own risk) " +
+                "`things config set accepted-fingerprint <observed hash>` after reviewing `things doctor`",
+        };
+    }
+    // 2. Serialize mutations (create-probe verification must never race).
+    let lock;
+    try {
+        lock = await acquireMutationLock(deps.lockPath);
+    }
+    catch (err) {
+        if (err instanceof MutationLockError) {
+            audit({ result: "blocked:lock" });
+            return {
+                kind: "blocked",
+                op,
+                reason: "lock",
+                detail: err.message,
+                remediation: "wait for the concurrent mutation to finish and retry",
+            };
+        }
+        throw err;
+    }
+    try {
+        // 3. Pre-read + guards.
+        const pre = spec.preRead(deps.db, params, deps.now?.() ?? new Date());
+        const acks = {
+            ...(options.acknowledgeChecklistReset !== undefined && {
+                acknowledgeChecklistReset: options.acknowledgeChecklistReset,
+            }),
+            ...(options.acknowledgeProjectReopen !== undefined && {
+                acknowledgeProjectReopen: options.acknowledgeProjectReopen,
+            }),
+            ...(options.dangerouslyPermanent !== undefined && {
+                dangerouslyPermanent: options.dangerouslyPermanent,
+            }),
+            ...(options.acknowledgeTagSubtree !== undefined && {
+                acknowledgeTagSubtree: options.acknowledgeTagSubtree,
+            }),
+        };
+        const block = evaluateGuards(spec.hazards, {
+            op,
+            params: params,
+            pre,
+            acks,
+        });
+        if (block !== null) {
+            audit({ result: `blocked:${block.hazard}` });
+            return {
+                kind: "blocked",
+                op,
+                reason: "hazard",
+                hazard: block.hazard,
+                detail: block.detail,
+                remediation: block.remediation,
+            };
+        }
+        // 4. Vector planning under the disruption policy.
+        const appRunning = (deps.isAppRunning ?? defaultIsAppRunning)();
+        const plan = planVector(op, deps.vectors, {
+            maxDisruption,
+            appRunning,
+            allowExperimental: config.allowExperimental,
+            ...(options.vector !== undefined && { forcedVector: options.vector }),
+        });
+        if (plan.kind === "unsupported") {
+            audit({ result: "unsupported" });
+            return { kind: "unsupported", op, considered: plan.considered };
+        }
+        if (plan.kind === "tier-blocked") {
+            audit({ result: "blocked:disruption-tier" });
+            return {
+                kind: "blocked",
+                op,
+                reason: "disruption-tier",
+                detail: `operation needs disruption tier ${plan.requiredTier} ` +
+                    `(app ${appRunning ? "running" : "closed — launch required"}), ` +
+                    `policy allows ${plan.maxDisruption}`,
+                remediation: "pass --allow-disruptive / raise maxDisruption, or launch Things first",
+            };
+        }
+        const { vector, effectiveTier } = plan.candidate;
+        // 4b. Experimental canary: the private sdef command can vanish in any
+        // Things update — re-check the declaration before every dispatch.
+        if (plan.candidate.support.experimental === true) {
+            const declared = (deps.sdefProbe ?? sdefDeclaresPrivateReorder)();
+            if (!declared) {
+                audit({ result: "blocked:environment" });
+                return {
+                    kind: "blocked",
+                    op,
+                    reason: "environment",
+                    detail: "the installed Things no longer declares the private reorder command in its " +
+                        "sdef — the experimental surface has likely been removed by an app update",
+                    remediation: "check `things doctor`, file/track the change, and fall back to the bounce " +
+                        "strategy where available",
+                };
+            }
+        }
+        // 5. Compile + expected delta.
+        const nowEpoch = Math.floor((deps.now?.() ?? new Date()).getTime() / 1000);
+        const token = readAuthToken(deps.db);
+        const invocation = spec.compile(params, vector.id, pre, { token });
+        const delta = spec.expectedDelta(pre, params, {
+            nowEpoch,
+            todayIso: localToday(deps.now?.() ?? new Date()),
+        });
+        if (options.dryRun === true) {
+            return {
+                kind: "dry-run",
+                op,
+                plan: {
+                    op,
+                    vector: vector.id,
+                    tier: effectiveTier,
+                    invocation: invocation.redactedPayload,
+                    expectedDelta: delta,
+                    hazardsChecked: spec.hazards,
+                },
+            };
+        }
+        // 6. Ensure the app is running in the BACKGROUND before dispatch —
+        // plain opens and AppleEvents to a closed Things steal focus (A40/A41).
+        const running = await (deps.ensureRunning ?? defaultEnsureRunning)(appRunning);
+        if (!running) {
+            audit({ result: "blocked:environment" });
+            return {
+                kind: "blocked",
+                op,
+                reason: "environment",
+                detail: "Things did not become available after a background launch attempt",
+                remediation: "launch Things manually and retry",
+            };
+        }
+        // 7. Execute + verify. The environment tuple diff feeds failure
+        // attribution (a changed tuple is the classic consent re-prompt trigger)
+        // and, on success, a warning + refreshed recording.
+        const envChanges = deps.environment !== undefined
+            ? diffEnvironment(deps.environment.load(), deps.environment.capture())
+            : [];
+        const withHint = (base, hint) => hint === null ? base : { ...base, likelyCause: hint.likelyCause, hint: hint.hint };
+        const preCapture = capturePre(delta, deps, pre);
+        const executeResult = await vector.execute(invocation);
+        if (executeResult.exitCode !== 0 || executeResult.timedOut === true) {
+            audit({
+                result: "verify-failed:silent-noop",
+                vector: vector.id,
+                disruption: effectiveTier,
+                invocation: invocation.redactedPayload,
+                pre: flattenPreFields(preCapture.fields),
+            });
+            return withHint({
+                kind: "verify-failed",
+                op,
+                reason: "silent-noop",
+                expected: delta,
+                observed: null,
+                detail: `transport failed (exit ${executeResult.exitCode ?? "?"}${executeResult.timedOut === true ? ", timed out" : ""}): ${executeResult.stderr.trim()}`,
+            }, classifyTransportFailure({
+                vector: vector.id,
+                stderr: executeResult.stderr,
+                timedOut: executeResult.timedOut === true,
+                environmentChanges: envChanges,
+            }));
+        }
+        const reader = createDbReader(deps.db);
+        const timeoutMs = options.verifyTimeoutMs ?? (appRunning ? 6000 : 10_000);
+        const outcome = await pollUntilVerified(() => evaluateDelta(delta, reader, preCapture), timeoutMs, deps.poller ?? {});
+        const auditCommon = {
+            vector: vector.id,
+            disruption: effectiveTier,
+            invocation: invocation.redactedPayload,
+            pre: flattenPreFields(preCapture.fields),
+            observed: outcome.observed,
+            verify: { attempts: outcome.attempts, elapsedMs: outcome.elapsedMs },
+        };
+        if (outcome.kind === "ok") {
+            const uuid = outcome.discoveredUuid ??
+                (delta.mode === "update" || delta.mode === "state" ? delta.uuid : null);
+            audit({ ...auditCommon, result: "ok", uuid });
+            if (deps.environment !== undefined) {
+                deps.environment.record(deps.environment.capture());
+            }
+            return {
+                kind: "ok",
+                op,
+                uuid,
+                observed: outcome.observed,
+                vector: vector.id,
+                tier: effectiveTier,
+                ...(envChanges.length > 0 && {
+                    warnings: [
+                        `environment changed since the last verified write: ` +
+                            `${describeEnvironmentChanges(envChanges)} — the first use of another ` +
+                            `capability may show a macOS consent prompt`,
+                    ],
+                }),
+            };
+        }
+        audit({ ...auditCommon, result: `verify-failed:${outcome.kind}` });
+        return withHint({
+            kind: "verify-failed",
+            op,
+            reason: outcome.kind,
+            expected: delta,
+            observed: outcome.observed,
+            detail: outcome.kind === "silent-noop"
+                ? "no observable change in the database (the app accepted the command but did nothing)"
+                : outcome.kind === "timeout"
+                    ? "something moved but the expected state never appeared within the timeout"
+                    : "the database reached a state contradicting the expected delta",
+        }, classifyVerifyFailure({
+            reason: outcome.kind,
+            vector: vector.id,
+            authTokenPresent: token !== null,
+            environmentChanges: envChanges,
+        }));
+    }
+    finally {
+        lock.release();
+    }
+}
+export function fingerprintLabel(fp, config) {
+    if (fp.kind === "ok")
+        return "ok";
+    if (fp.kind === "unknown-version")
+        return "unknown";
+    return config.acceptedFingerprint === fp.observation.fingerprint ? "user-accepted" : "drift";
+}
+function flattenPreFields(fields) {
+    const uuids = Object.keys(fields);
+    if (uuids.length === 0)
+        return null;
+    if (uuids.length === 1) {
+        const only = uuids[0];
+        return only === undefined ? null : (fields[only] ?? null);
+    }
+    return fields;
+}
+//# sourceMappingURL=pipeline.js.map

package/dist/write/pipeline.js.map

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

package/dist/write/planner.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Vector selection under the disruption policy. Effective tier accounts for
+ * the ensure-running step: when Things is closed, the pipeline background-
+ * launches it first (tier 1) — required because both a plain `open` and an
+ * AppleEvent to a closed Things steal focus (U01, A40/A41).
+ */
+import type { DisruptionTier } from "../config.ts";
+import type { OperationKind } from "./operations.ts";
+import type { VectorId, VectorSupport, WriteVector } from "./vectors/types.ts";
+export interface PlanCandidate {
+    vector: WriteVector;
+    support: VectorSupport;
+    /** Tier this call will actually incur, given current app state. */
+    effectiveTier: DisruptionTier;
+}
+export type Plan = {
+    kind: "selected";
+    candidate: PlanCandidate;
+} | {
+    kind: "unsupported";
+    considered: {
+        vector: VectorId;
+        why: string;
+    }[];
+} | {
+    kind: "tier-blocked";
+    requiredTier: DisruptionTier;
+    maxDisruption: DisruptionTier;
+    considered: {
+        vector: VectorId;
+        tier: DisruptionTier;
+    }[];
+};
+export declare function planVector(op: OperationKind, vectors: WriteVector[], options: {
+    maxDisruption: DisruptionTier;
+    appRunning: boolean;
+    forcedVector?: VectorId;
+    /** Config gate for `experimental: true` matrix entries (default off). */
+    allowExperimental?: boolean;
+}): Plan;

package/dist/write/planner.js

@@ -0,0 +1,57 @@
+export function planVector(op, vectors, options) {
+    const considered = [];
+    const viable = [];
+    for (const vector of vectors) {
+        if (options.forcedVector !== undefined && vector.id !== options.forcedVector)
+            continue;
+        const support = vector.matrix[op];
+        if (support === undefined) {
+            considered.push({ vector: vector.id, why: "no matrix entry for this operation" });
+            continue;
+        }
+        if (support.support === "no") {
+            considered.push({
+                vector: vector.id,
+                why: support.notes ?? "operation not supported by this vector",
+            });
+            continue;
+        }
+        if (support.validation !== "validated") {
+            considered.push({
+                vector: vector.id,
+                why: `capability is ${support.validation} — not lab-validated`,
+            });
+            continue;
+        }
+        if (support.experimental === true && options.allowExperimental !== true) {
+            considered.push({
+                vector: vector.id,
+                why: "rides an undocumented app surface — enable it with " +
+                    "`things config set allow-experimental true`",
+            });
+            continue;
+        }
+        const launchTier = options.appRunning ? 0 : 1;
+        const effectiveTier = Math.max(support.disruption, launchTier);
+        viable.push({ vector, support, effectiveTier });
+    }
+    if (viable.length === 0)
+        return { kind: "unsupported", considered };
+    const allowed = viable.filter((c) => c.effectiveTier <= options.maxDisruption);
+    if (allowed.length === 0) {
+        const requiredTier = Math.min(...viable.map((c) => c.effectiveTier));
+        return {
+            kind: "tier-blocked",
+            requiredTier,
+            maxDisruption: options.maxDisruption,
+            considered: viable.map((c) => ({ vector: c.vector.id, tier: c.effectiveTier })),
+        };
+    }
+    // Lowest tier wins; registry order breaks ties.
+    allowed.sort((a, b) => a.effectiveTier - b.effectiveTier);
+    const winner = allowed[0];
+    if (winner === undefined)
+        return { kind: "unsupported", considered };
+    return { kind: "selected", candidate: winner };
+}
+//# sourceMappingURL=planner.js.map

package/dist/write/planner.js.map

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

package/dist/write/pre-state.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Pre-read: everything guards and delta-builders need to know about the
+ * world BEFORE a mutation. One read pass, snapshot semantics per statement.
+ */
+import type { DatabaseSync } from "node:sqlite";
+import type { AnyTask, Project, TaskStatus, Todo } from "../model/entities.ts";
+import type { ContainerRef, ReorderParams } from "./operations.ts";
+export interface ResolvedContainer {
+    uuid: string;
+    title: string;
+}
+export interface ContainerResolution {
+    resolved: ResolvedContainer | null;
+    /** 0 = not found, 1 = ok, >1 = ambiguous title. */
+    matches: number;
+}
+export interface ReorderMember {
+    uuid: string;
+    title: string;
+    /** Current rank on the scope's ordering key (todayIndex or "index"). */
+    rank: number;
+    /** Raw startBucket (0 = today, 1 = evening); today/evening scopes only. */
+    startBucket: number | null;
+    /** 0 = to-do, 1 = project. */
+    type: number;
+}
+export interface ReorderPre {
+    /** Ordering key the scope ranks on. */
+    key: "index" | "todayIndex";
+    /** Eligible members in current order (wire-list extension source). */
+    members: ReorderMember[];
+    /** Requested uuids that are not eligible members, with the reason. */
+    rejected: {
+        uuid: string;
+        reason: string;
+    }[];
+    /** Requested uuids appearing more than once. */
+    duplicates: string[];
+    /** Requested project-type members (bounce cannot move projects). */
+    projectMembers: string[];
+    /**
+     * Area scope only: the request mixes to-do and project members. Same-type
+     * area reorders are validated (O05/O10 to-dos, O14 projects); a mixed wire
+     * list is unprobed, so the guard rejects it.
+     */
+    mixedTypes: boolean;
+    /** Full wire list: requested order first, remaining members after. */
+    wireList: string[];
+}
+export interface PreState {
+    /** Primary target for uuid-addressed operations. */
+    target: AnyTask | null;
+    destProject: ContainerResolution | null;
+    /** Status of the resolved destination project (reopen hazard, T19). */
+    destProjectStatus: TaskStatus | null;
+    destArea: ContainerResolution | null;
+    /** Heading resolution inside the destination (or target's) project. */
+    destHeading: ContainerResolution | null;
+    /** Requested tag titles absent from TMTag (case-insensitive). */
+    missingTags: string[];
+    /** tag.add parent resolution. */
+    parentTag: ContainerResolution | null;
+    /** area.delete / tag.delete target resolution (TMArea/TMTag). */
+    entityTarget: ContainerResolution | null;
+    /** tag.delete: descendant tags that a delete would CASCADE onto (P16). */
+    childTags: string[];
+    /** project.complete / project.cancel: children by pre-status. */
+    openChildren: Todo[];
+    canceledChildren: Todo[];
+    completedChildren: Todo[];
+    checklistCount: number;
+    trashedCount: number;
+    /** Pre-existing uuids for entity-created probes. */
+    existingEntityUuids: string[];
+    /** Pre-existing same-title/type rows (todo.add-logged create-probe exclusion). */
+    sameTitleUuids: string[];
+    /** Scope membership + wire list for the reorder operation. */
+    reorder: ReorderPre | null;
+}
+export declare function emptyPreState(): PreState;
+export declare function resolveArea(db: DatabaseSync, ref: ContainerRef): ContainerResolution;
+export declare function resolveProject(db: DatabaseSync, ref: ContainerRef): ContainerResolution;
+export declare function resolveHeading(db: DatabaseSync, projectUuid: string, headingTitle: string): ContainerResolution;
+export declare function projectStatus(db: DatabaseSync, uuid: string): TaskStatus | null;
+export declare function missingTagTitles(db: DatabaseSync, titles: string[]): string[];
+export declare function resolveTag(db: DatabaseSync, ref: string): ContainerResolution;
+export declare function loadTarget(db: DatabaseSync, uuid: string): AnyTask | null;
+export declare function projectChildren(db: DatabaseSync, projectUuid: string): Todo[];
+/**
+ * Titles of every DESCENDANT tag under the given tag (excluding itself).
+ * Deleting the parent CASCADE-DELETES all of these (P16) — the guard lists
+ * them. UNION (not UNION ALL): a parent cycle must terminate, not hang.
+ */
+export declare function childTagTitles(db: DatabaseSync, tagUuid: string): string[];
+export declare function trashedCount(db: DatabaseSync): number;
+export declare function isRepeatingTemplate(task: AnyTask | null): boolean;
+/**
+ * Scope membership + full wire list for `reorder`. Eligibility mirrors the
+ * lab evidence exactly:
+ *  - today:   Today members with raw startBucket=0, to-dos AND projects
+ *             (O01/O03/O12), by todayIndex. Bucket-1 members are listed as
+ *             rejected candidates — including one silently de-evenings it
+ *             (O03), so the guard refuses.
+ *  - evening: raw startBucket=1 AND startDate == today exactly (evening
+ *             membership expires daily), by todayIndex. Bounce-only (O03).
+ *  - project: un-headed open to-do children, by "index" (O04/O09/O11);
+ *             headed children are rejected candidates (O06 rips them out).
+ *  - area:    direct open area to-dos (O05/O10) AND projects (O14), by
+ *             "index" — but only SAME-TYPE requests; mixed wire lists are
+ *             unprobed and the guard rejects them.
+ *  - inbox:   unscheduled to-dos with no container (start=0), by "index"
+ *             (A6/P8a — the command ranks the sent list in order).
+ *  - headings: the HEADING rows (type=2) of a project, by "index" (scf P1 —
+ *             the private command accepts heading uuids; children follow).
+ *  - someday: loose someday to-dos (start=2, no startDate, no container), by
+ *             "index". The Someday list handler is anchor-stacked (P6h/P7e/
+ *             P8b) — the compiler emits the validated two-call protocol.
+ *             Someday PROJECTS moved inconsistently across probes (P7a vs
+ *             P8c) and are rejected candidates until locked.
+ *  - projects: TOP-LEVEL sidebar projects (type=1, no area, start=1,
+ *             undated), by "index". Bounce-only: a when=someday ->
+ *             when=anytime round-trip front-inserts (P8e).
+ */
+export declare function computeReorderPre(db: DatabaseSync, params: ReorderParams, containerUuid: string | null, now: Date): ReorderPre;
+export declare function projectOf(task: AnyTask | null): Project | null;