things-api 0.6.0 → 0.8.0

package/dist/write/checklist.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Checklist edit primitives, shared by the client, the write-layer
+ * orchestrator (`edit-checklist.ts`), and undo (`undo.ts`).
+ *
+ * Things exposes NO item-level checklist write surface: every change is a
+ * wholesale rewrite (`todo.replace-checklist`), and item uuids regenerate on
+ * each rewrite (docs/design/reference-resolution.md). A granular edit is
+ * therefore expressed as ONE action against the CURRENT list, applied here in
+ * memory, and delivered as a full rewrite that preserves every other item's
+ * state. These helpers live in the write layer (not client.ts) so the
+ * orchestrator can reuse them without importing back through the client.
+ */
+import type { ChecklistItemAction, ChecklistItemSpec } from "./operations.ts";
+export type { ChecklistItemAction };
+/**
+ * Target for an existing checklist item: by `item` (title) or `index`
+ * (1-based). Provide exactly one. Title matching is best-effort on duplicates
+ * (docs/design/reference-resolution.md); index is exact.
+ */
+export interface ChecklistTarget {
+    item?: string;
+    /** 1-based position; overrides `item` when both are given. */
+    index?: number;
+}
+export type ChecklistEdit = {
+    action: "add";
+    title: string; /** 1-based insert position (default: append). */
+    at?: number;
+} | ({
+    action: "remove";
+} & ChecklistTarget) | ({
+    action: "check";
+} & ChecklistTarget) | ({
+    action: "uncheck";
+} & ChecklistTarget) | ({
+    action: "rename";
+    title: string;
+} & ChecklistTarget) | ({
+    action: "move"; /** 1-based target position. */
+    to: number;
+} & ChecklistTarget);
+/**
+ * Resolve a checklist target to an array index. `index` (1-based) is exact.
+ * A title resolves best-effort: unique → that item; duplicates → the first on
+ * which the action is meaningful (check → first unchecked, uncheck → first
+ * checked, others → first match). Loud only when nothing matches / index is
+ * out of range.
+ */
+export declare function checklistTarget(items: ChecklistItemSpec[], edit: ChecklistEdit & ChecklistTarget): number;
+export declare function applyChecklistEdit(items: ChecklistItemSpec[], edit: ChecklistEdit): ChecklistItemSpec[];

package/dist/write/checklist.js

@@ -0,0 +1,61 @@
+/**
+ * Resolve a checklist target to an array index. `index` (1-based) is exact.
+ * A title resolves best-effort: unique → that item; duplicates → the first on
+ * which the action is meaningful (check → first unchecked, uncheck → first
+ * checked, others → first match). Loud only when nothing matches / index is
+ * out of range.
+ */
+export function checklistTarget(items, edit) {
+    if (edit.index !== undefined) {
+        const i = edit.index - 1;
+        if (i < 0 || i >= items.length) {
+            throw new RangeError(`checklist index ${edit.index} is out of range (1..${items.length})`);
+        }
+        return i;
+    }
+    const ref = edit.item;
+    if (ref === undefined)
+        throw new RangeError("give a checklist item title or 1-based index");
+    const matches = items.map((c, i) => ({ c, i })).filter(({ c }) => c.title === ref);
+    if (matches.length === 0)
+        throw new RangeError(`no checklist item titled "${ref}"`);
+    if (matches.length === 1)
+        return matches[0].i;
+    const meaningful = edit.action === "check"
+        ? matches.find(({ c }) => !c.completed)
+        : edit.action === "uncheck"
+            ? matches.find(({ c }) => c.completed)
+            : undefined;
+    return (meaningful ?? matches[0] ?? { i: 0 }).i;
+}
+export function applyChecklistEdit(items, edit) {
+    const next = items.map((c) => ({ ...c }));
+    switch (edit.action) {
+        case "add": {
+            const at = edit.at === undefined ? next.length : Math.max(0, Math.min(next.length, edit.at - 1));
+            next.splice(at, 0, { title: edit.title, completed: false });
+            return next;
+        }
+        case "remove":
+            next.splice(checklistTarget(next, edit), 1);
+            return next;
+        case "check":
+        case "uncheck": {
+            const target = next[checklistTarget(next, edit)];
+            target.completed = edit.action === "check";
+            return next;
+        }
+        case "rename": {
+            const target = next[checklistTarget(next, edit)];
+            target.title = edit.title;
+            return next;
+        }
+        case "move": {
+            const from = checklistTarget(next, edit);
+            const [moved] = next.splice(from, 1);
+            next.splice(Math.max(0, Math.min(next.length, edit.to - 1)), 0, moved);
+            return next;
+        }
+    }
+}
+//# sourceMappingURL=checklist.js.map

package/dist/write/checklist.js.map

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

package/dist/write/clear-reminder.d.ts

@@ -0,0 +1,3 @@
+import type { UuidParams } from "./operations.ts";
+import { type MutationResult, type WriteDeps, type WriteOptions } from "./pipeline.ts";
+export declare function runClearReminder(deps: WriteDeps, params: UuidParams, options?: WriteOptions): Promise<MutationResult>;

package/dist/write/clear-reminder.js

@@ -0,0 +1,205 @@
+import { resolveTaskUuidPrefix } from "../read/queries.js";
+import { readShortcutProxies } from "./availability.js";
+import { COMMANDS } from "./commands.js";
+import { evaluateGuards } from "./guards.js";
+import { emptyPreState, isRepeatingTemplate, loadTarget } from "./pre-state.js";
+import { fingerprintLabel, runMutation, } from "./pipeline.js";
+const SET_DETAIL_PROXY = "things-proxy-set-detail";
+export async function runClearReminder(deps, params, options = {}) {
+    const uuid = resolveTaskUuidPrefix(deps.db, params.uuid);
+    const forced = options.vector;
+    // Dry-run previews the primary (atomic Shortcuts) plan unless the caller
+    // forces the URL bounce — cheap and host-independent (no proxy probe).
+    if (options.dryRun === true && forced !== "url-scheme") {
+        return runMutation(deps, "todo.clear-dated-reminder", { uuid }, { ...options, vector: "shortcuts" });
+    }
+    // Uniform pre-checks (no reminder to clear / wrong target type) via the op's
+    // own hazard set — identical result whichever path we'd pick.
+    const target = loadTarget(deps.db, uuid);
+    const pre = emptyPreState();
+    pre.target = target;
+    const block = evaluateGuards(COMMANDS["todo.clear-dated-reminder"].hazards, {
+        op: "todo.clear-dated-reminder",
+        params: { uuid },
+        pre,
+        acks: {},
+    });
+    if (block !== null) {
+        appendClearAudit(deps, {
+            uuid,
+            startedAt: deps.now?.() ?? new Date(),
+            result: `blocked:${block.hazard}`,
+        });
+        return {
+            kind: "blocked",
+            op: "todo.clear-dated-reminder",
+            reason: "hazard",
+            hazard: block.hazard,
+            detail: block.detail,
+            remediation: block.remediation,
+        };
+    }
+    const repeating = isRepeatingTemplate(target);
+    if (forced === "url-scheme" && repeating) {
+        appendClearAudit(deps, {
+            uuid,
+            startedAt: deps.now?.() ?? new Date(),
+            result: "blocked:H-REPEAT-SCHEDULE",
+        });
+        return {
+            kind: "blocked",
+            op: "todo.clear-dated-reminder",
+            reason: "hazard",
+            hazard: "H-REPEAT-SCHEDULE",
+            detail: "the URL bounce is unusable on a repeating template — a URL when= re-schedule CRASHES " +
+                "Things (R09); only the atomic Shortcuts clear is safe here",
+            remediation: "install the proxies (`things setup shortcuts`) and omit --vector, or clear it in the app",
+        };
+    }
+    // Repeating items are Shortcuts-only: delegate to the atomic path, which
+    // either clears (proxy present) or blocks with the setup remediation
+    // (proxy absent) — exactly the desired repeating behavior.
+    const useShortcuts = forced === "shortcuts"
+        ? true
+        : forced === "url-scheme"
+            ? false
+            : repeating
+                ? true
+                : proxiesInstalled(deps);
+    if (useShortcuts) {
+        return runMutation(deps, "todo.clear-dated-reminder", { uuid }, { ...options, vector: "shortcuts" });
+    }
+    return runBounce(deps, uuid, target, options);
+}
+function proxiesInstalled(deps) {
+    const state = (deps.shortcutProxies ?? (() => readShortcutProxies()))();
+    return state.present.includes(SET_DETAIL_PROXY);
+}
+// ------------------------------------------------------------------- bounce
+async function runBounce(deps, uuid, target, options) {
+    const startedAt = deps.now?.() ?? new Date();
+    const originalDate = target !== null && target.type === "to-do" ? target.startDate : null;
+    const preReminder = target !== null && target.type === "to-do" ? target.reminder : null;
+    if (originalDate === null || preReminder === null) {
+        // The guard above already ruled these out; defensive only.
+        return {
+            kind: "blocked",
+            op: "todo.clear-dated-reminder",
+            reason: "hazard",
+            hazard: "H-NO-REMINDER",
+            detail: "the item has no dated reminder to clear via the URL bounce",
+            remediation: "target a to-do with a date and a time-of-day reminder",
+        };
+    }
+    if (options.dryRun === true) {
+        return {
+            kind: "dry-run",
+            op: "todo.clear-dated-reminder",
+            plan: {
+                op: "todo.clear-dated-reminder",
+                vector: "url-scheme",
+                tier: 0,
+                invocation: `bounce: update?id=${uuid}&when=today (clears the reminder, R07) → verified → ` +
+                    `update?id=${uuid}&when=${originalDate} (re-dates back, RC02) → verified`,
+                expectedDelta: {
+                    mode: "update",
+                    uuid,
+                    assert: [
+                        { field: "reminder", equals: null },
+                        { field: "startDate", equals: originalDate },
+                    ],
+                },
+                hazardsChecked: ["H-NO-REMINDER"],
+            },
+        };
+    }
+    const txnId = `txn-${startedAt.getTime().toString(36)}-${process.pid.toString(36)}`;
+    const legOptions = { vector: "url-scheme", txn: { id: txnId, role: "leg" } };
+    if (options.maxDisruption !== undefined)
+        legOptions.maxDisruption = options.maxDisruption;
+    if (options.verifyTimeoutMs !== undefined)
+        legOptions.verifyTimeoutMs = options.verifyTimeoutMs;
+    if (options.actor !== undefined)
+        legOptions.actor = options.actor;
+    const leg1 = await runMutation(deps, "todo.update", { uuid, when: "today", reminder: null }, legOptions);
+    if (leg1.kind !== "ok") {
+        appendClearAudit(deps, { uuid, startedAt, result: "verify-failed:mismatch" });
+        return {
+            kind: "verify-failed",
+            op: "todo.clear-dated-reminder",
+            reason: "mismatch",
+            expected: leg1.kind === "verify-failed" ? leg1.expected : { mode: "update", uuid, assert: [] },
+            observed: leg1.kind === "verify-failed" ? leg1.observed : null,
+            detail: "bounce leg 1 (when=today) failed — the item was NOT touched; its dated reminder is " +
+                "unchanged. Retry, or clear it via `things setup shortcuts`",
+        };
+    }
+    const leg2 = await runMutation(deps, "todo.update", { uuid, when: originalDate }, legOptions);
+    if (leg2.kind !== "ok") {
+        // Non-atomic residue: the reminder IS cleared but the item is stranded on
+        // Today. Record it (summary as verify-failed) and surface the exact state.
+        appendClearAudit(deps, {
+            uuid,
+            startedAt,
+            result: "verify-failed:mismatch",
+            observed: { reminder: null, startDate: null },
+        });
+        return {
+            kind: "verify-failed",
+            op: "todo.clear-dated-reminder",
+            reason: "mismatch",
+            expected: { mode: "update", uuid, assert: [{ field: "startDate", equals: originalDate }] },
+            observed: leg2.kind === "verify-failed" ? leg2.observed : null,
+            detail: `bounce leg 2 (when=${originalDate}) failed — the reminder IS cleared but the item is ` +
+                `stranded on TODAY (not its original date ${originalDate}). Re-schedule it ` +
+                `(\`things todo update ${uuid} --when ${originalDate}\`) to finish`,
+        };
+    }
+    // Both legs verified: write the single undoable SUMMARY record.
+    appendClearAudit(deps, {
+        uuid,
+        startedAt,
+        result: "ok",
+        pre: { reminder: preReminder, startDate: originalDate },
+        observed: { reminder: null, startDate: originalDate },
+        txn: { id: txnId, role: "summary" },
+        invocation: `bounce(clear-dated-reminder) id=${uuid}`,
+    });
+    return {
+        kind: "ok",
+        op: "todo.clear-dated-reminder",
+        uuid,
+        observed: { reminder: null, startDate: originalDate },
+        vector: "url-scheme",
+        tier: 0,
+    };
+}
+// --------------------------------------------------------------------- audit
+function appendClearAudit(deps, args) {
+    const fp = deps.fingerprint();
+    const record = {
+        v: 1,
+        ts: args.startedAt.toISOString(),
+        actor: deps.config.actor,
+        host: deps.config.host,
+        op: "todo.clear-dated-reminder",
+        uuid: args.uuid,
+        vector: "url-scheme",
+        disruption: 0,
+        invocation: args.invocation ?? null,
+        requested: { uuid: args.uuid },
+        ...(args.txn !== undefined && { txn: args.txn }),
+        pre: args.pre ?? null,
+        observed: args.observed ?? null,
+        result: args.result,
+        verify: null,
+        durationMs: (deps.now?.() ?? new Date()).getTime() - args.startedAt.getTime(),
+        env: {
+            pkg: deps.pkgVersion ?? "0.0.1",
+            dbVersion: fp.observation.databaseVersion,
+            fingerprint: fingerprintLabel(fp, deps.config),
+        },
+    };
+    deps.audit.append(record);
+}
+//# sourceMappingURL=clear-reminder.js.map

package/dist/write/clear-reminder.js.map

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

package/dist/write/commands.js

@@ -28,6 +28,23 @@ function osa(script) {
     const payload = `tell application "Things3" to ${script}`;
     return { vector: "applescript", kind: "osascript", payload, redactedPayload: payload };
 }
+/**
+ * A `shortcuts run <name>` invocation. The input dict is piped to the proxy
+ * as JSON (no secrets — the auth token is never sent to a shortcut), so the
+ * redacted rendering equals the payload. Key names come verbatim from the
+ * proxy input contracts in docs/lab/s-campaign-results.md.
+ */
+function shortcutsRun(shortcut, input) {
+    const rendered = `shortcuts run ${shortcut} <- ${JSON.stringify(input)}`;
+    return {
+        vector: "shortcuts",
+        kind: "shortcuts-run",
+        payload: rendered,
+        redactedPayload: rendered,
+        shortcut,
+        input,
+    };
+}
 /** Multi-statement `tell` block (one osascript invocation, several events). */
 function osaBlock(statements) {
     const payload = `tell application "Things3"\n  ${statements.join("\n  ")}\nend tell`;
@@ -40,6 +57,19 @@ function unsupportedVector(op, vector) {
     throw new Error(`${op} cannot be compiled for vector ${vector} (planner bug)`);
 }
 function whenAssertions(when, todayIso) {
+    // Strict shape check: an unvalidated string used to flow straight into the
+    // URL (e.g. "2026-07-20@09:30", the raw URL grammar) — the app would SET
+    // date+reminder while verification asserted the literal string as the date,
+    // reporting a false mismatch on a write that succeeded.
+    if (when !== "today" &&
+        when !== "evening" &&
+        when !== "anytime" &&
+        when !== "someday" &&
+        !/^\d{4}-\d{2}-\d{2}$/.test(when)) {
+        throw new RangeError(when.includes("@")
+            ? `invalid when "${when}" — a reminder time is a separate parameter (reminder: "HH:mm"; CLI --reminder), not an @ suffix`
+            : `invalid when "${when}" — expected today | evening | anytime | someday | YYYY-MM-DD`);
+    }
     switch (when) {
         case "today":
             return [
@@ -407,17 +437,16 @@ const todoReplaceChecklist = {
         return pre;
     },
     expectedDelta(_pre, params) {
-        const { specs, needsJson } = checklistSpecs(params.items);
+        const { specs } = checklistSpecs(params.items);
+        // Always assert titles AND states: the non-json form recreates every item
+        // OPEN (T07) and the json form honors per-item `completed` (P18), so the
+        // resulting states are known either way. Asserting them (a) strengthens
+        // verification and (b) records the ordered states into `pre`/`observed`,
+        // which the wholesale undo needs to restore states and to precondition on.
         const assert = [
             { field: "checklistTitles", equals: specs.map((s) => s.title) },
+            { field: "checklistStates", equals: specs.map((s) => (s.completed ? "completed" : "open")) },
         ];
-        if (needsJson) {
-            // P18: the json form applies per-item completed states — verify them.
-            assert.push({
-                field: "checklistStates",
-                equals: specs.map((s) => (s.completed ? "completed" : "open")),
-            });
-        }
         return { mode: "update", uuid: params.uuid, assert };
     },
     compile(params, vector, _pre, ctx) {
@@ -445,6 +474,24 @@ const todoReplaceChecklist = {
         return thingsUrl("json", { data: payload }, ctx.token);
     },
 };
+const ORCHESTRATED_ONLY = "todo.edit-checklist-item is delivered by the runEditChecklist orchestrator (a targeted " +
+    "todo.replace-checklist rewrite that preserves every other item's state); it has no atomic " +
+    "surface and is never dispatched directly through the pipeline";
+const todoEditChecklistItem = {
+    op: "todo.edit-checklist-item",
+    hazards: [],
+    preRead(db, params) {
+        const pre = emptyPreState();
+        pre.target = loadTarget(db, params.uuid);
+        return pre;
+    },
+    expectedDelta() {
+        throw new Error(ORCHESTRATED_ONLY);
+    },
+    compile() {
+        throw new Error(ORCHESTRATED_ONLY);
+    },
+};
 const todoDelete = {
     op: "todo.delete",
     hazards: ["H-UNKNOWN-DESTINATION", "H-REPEAT-SCHEDULE"],
@@ -1205,9 +1252,15 @@ const todoAddLogged = {
             unsupportedVector(this.op, vector);
         // Local noon -> UTC instant, so the stored timestamp decodes back to the
         // requested local DATE in every timezone (P4d: json attrs honored exactly).
+        // WITHOUT milliseconds: the app's json date parser rejects fractional
+        // seconds — a `.000Z` timestamp fails the whole command (error modal, no
+        // write; caught live by the e2e 2026-07-09 — P4d's validated shape was
+        // second-precision).
         const utcNoon = (iso) => {
             const [y, m, d] = iso.split("-").map(Number);
-            return new Date(y ?? 0, (m ?? 1) - 1, d ?? 1, 12, 0, 0).toISOString();
+            return new Date(y ?? 0, (m ?? 1) - 1, d ?? 1, 12, 0, 0)
+                .toISOString()
+                .replace(/\.\d{3}Z$/, "Z");
         };
         const payload = JSON.stringify([
             {
@@ -1336,6 +1389,70 @@ const headingUnarchive = {
         return osa(`set status of to do id ${q(params.uuid)} to open`);
     },
 };
+const headingCreate = {
+    op: "heading.create",
+    hazards: ["H-UNKNOWN-DESTINATION"],
+    preRead(db, params) {
+        const pre = emptyPreState();
+        pre.destProject = resolveProject(db, params.project);
+        return pre;
+    },
+    expectedDelta(pre, params, ctx) {
+        const project = pre.destProject?.resolved;
+        // A new type=2 row with this title under the project; disambiguate
+        // duplicate titles by newest creationDate (findCreated orders DESC).
+        return {
+            mode: "create",
+            probe: { title: params.title, type: "heading", sinceEpoch: ctx.nowEpoch - 2 },
+            assert: project !== undefined && project !== null
+                ? [{ field: "project.uuid", equals: project.uuid }]
+                : [],
+        };
+    },
+    compile(params, vector, pre) {
+        if (vector !== "shortcuts")
+            unsupportedVector(this.op, vector);
+        // `things-proxy-create-heading` input: {"title": <str>, "project": <uuid>}.
+        return shortcutsRun("things-proxy-create-heading", {
+            title: params.title,
+            project: pre.destProject?.resolved?.uuid ?? "",
+        });
+    },
+};
+const todoClearDatedReminder = {
+    op: "todo.clear-dated-reminder",
+    hazards: ["H-UNKNOWN-DESTINATION", "H-NO-REMINDER"],
+    preRead(db, params) {
+        const pre = emptyPreState();
+        pre.target = loadTarget(db, params.uuid);
+        return pre;
+    },
+    expectedDelta(pre, params) {
+        // The reminder clears; the scheduled date is left untouched (P3b).
+        const target = pre.target;
+        const startDate = target !== null && target.type === "to-do" ? (target.startDate ?? null) : null;
+        return {
+            mode: "update",
+            uuid: params.uuid,
+            assert: [
+                { field: "reminder", equals: null },
+                { field: "startDate", equals: startDate },
+            ],
+        };
+    },
+    compile(params, vector) {
+        if (vector !== "shortcuts")
+            unsupportedVector(this.op, vector);
+        // `things-proxy-set-detail` input: {"id": <uuid>, "detail": <Detail>, "value": <str>}.
+        // Reminder Time = "" is the clear path (scf P3b); the Detail selector name
+        // comes from the app's Edit Items action list.
+        return shortcutsRun("things-proxy-set-detail", {
+            id: params.uuid,
+            detail: "Reminder Time",
+            value: "",
+        });
+    },
+};
 const trashEmpty = {
     op: "trash.empty",
     hazards: ["H-PERMANENT-DELETE"],
@@ -1362,6 +1479,7 @@ export const COMMANDS = {
     "todo.move": todoMove,
     "todo.set-tags": todoSetTags,
     "todo.replace-checklist": todoReplaceChecklist,
+    "todo.edit-checklist-item": todoEditChecklistItem,
     "todo.delete": todoDelete,
     "project.add": projectAdd,
     "project.update": projectUpdate,
@@ -1388,5 +1506,7 @@ export const COMMANDS = {
     "heading.rename": headingRename,
     "heading.archive": headingArchive,
     "heading.unarchive": headingUnarchive,
+    "heading.create": headingCreate,
+    "todo.clear-dated-reminder": todoClearDatedReminder,
 };
 //# sourceMappingURL=commands.js.map