things-api 0.5.0

package/dist/write/guards.js

@@ -0,0 +1,312 @@
+import { isRepeatingTemplate } from "./pre-state.js";
+export const HAZARD_IDS = [
+    "H-REPEAT-SCHEDULE",
+    "H-PROJECT-COMPLETE-CHILDREN",
+    "H-CHECKLIST-REPLACE",
+    "H-REOPEN-RESOLVED-PROJECT",
+    "H-UNKNOWN-TAG",
+    "H-UNKNOWN-DESTINATION",
+    "H-AMBIGUOUS-HEADING",
+    "H-PERMANENT-DELETE",
+    "H-REORDER-SCOPE",
+    "H-REMINDER-SCOPE",
+    "H-TAG-SUBTREE-DELETE",
+    "H-BACKDATE-OPEN",
+];
+/** Ops where a schedule/status-class write on a repeating template is destructive. */
+const REPEAT_SENSITIVE = [
+    "todo.complete",
+    "todo.cancel",
+    "todo.reopen",
+    "todo.move",
+    "todo.delete",
+    "todo.duplicate", // unvalidated on templates (E07 probed a plain to-do)
+    "todo.restore", // unvalidated on templates (E15 probed a plain to-do)
+    "project.move", // unvalidated on repeating projects (E14 probed a plain project)
+    "project.duplicate", // unvalidated on repeating projects (E17 probed a plain project)
+    "project.cancel", // unvalidated on repeating projects (P01 probed a plain project)
+    "project.reopen", // unvalidated on repeating projects (P02/P05 probed plain projects)
+    "project.restore", // unvalidated on repeating projects (P06 probed a plain project)
+];
+const GUARDS = {
+    "H-REPEAT-SCHEDULE": ({ op, params, pre }) => {
+        if (!isRepeatingTemplate(pre.target))
+            return null;
+        const touchesSchedule = op === "todo.update" && (params["when"] !== undefined || params["deadline"] !== undefined);
+        if (!touchesSchedule && !REPEAT_SENSITIVE.includes(op))
+            return null;
+        return {
+            hazard: "H-REPEAT-SCHEDULE",
+            detail: "target is a repeating template: URL scheduling writes crash Things (T12/U12); " +
+                "status/move/delete on templates are unvalidated",
+            remediation: "edit the repeat rule in the Things app; title/notes updates and checklist " +
+                "replacement remain allowed on templates",
+        };
+    },
+    "H-PROJECT-COMPLETE-CHILDREN": ({ op, params, pre }) => {
+        if (op !== "project.complete" && op !== "project.cancel")
+            return null;
+        if (pre.openChildren.length === 0)
+            return null;
+        const auto = op === "project.complete" ? "auto-complete" : "auto-cancel";
+        if (params["children"] === auto)
+            return null;
+        return {
+            hazard: "H-PROJECT-COMPLETE-CHILDREN",
+            detail: `project has ${pre.openChildren.length} open child to-do(s); the URL write would ` +
+                `silently ${op === "project.complete" ? "auto-complete" : "auto-cancel"} them ` +
+                "(no prompt, unlike the UI — T08/U08, P01)",
+            remediation: `resolve the children first, or pass children='${auto}' (--children ${auto})`,
+        };
+    },
+    "H-CHECKLIST-REPLACE": ({ op, pre, acks }) => {
+        if (op !== "todo.replace-checklist")
+            return null;
+        if (pre.checklistCount === 0 || acks.acknowledgeChecklistReset === true)
+            return null;
+        return {
+            hazard: "H-CHECKLIST-REPLACE",
+            detail: `target has ${pre.checklistCount} existing checklist item(s); replacement is wholesale ` +
+                "and destroys per-item completion state (T07/U07)",
+            remediation: "pass acknowledgeChecklistReset (--acknowledge-checklist-reset)",
+        };
+    },
+    "H-REOPEN-RESOLVED-PROJECT": ({ op, pre, acks }) => {
+        if (op !== "todo.add" && op !== "todo.move")
+            return null;
+        const dest = pre.destProject?.resolved;
+        if (dest === undefined || dest === null)
+            return null;
+        const status = pre.destProjectStatus;
+        if (status === null || status === "open")
+            return null;
+        if (acks.acknowledgeProjectReopen === true)
+            return null;
+        return {
+            hazard: "H-REOPEN-RESOLVED-PROJECT",
+            detail: `destination project "${dest.title}" is ${status}; adding an open child reopens it (T19/U19)`,
+            remediation: "pass acknowledgeProjectReopen (--acknowledge-project-reopen)",
+        };
+    },
+    "H-UNKNOWN-TAG": ({ pre }) => {
+        if (pre.missingTags.length === 0)
+            return null;
+        return {
+            hazard: "H-UNKNOWN-TAG",
+            detail: `tag(s) not found: ${pre.missingTags.join(", ")} — the app silently ignores unknown ` +
+                "tags (T03/U03), so this would be a partial write",
+            remediation: "create the tag first (things tag add) or fix the spelling",
+        };
+    },
+    "H-UNKNOWN-DESTINATION": ({ op, params, pre }) => {
+        const problems = [];
+        if (pre.destProject !== null && pre.destProject.resolved === null) {
+            problems.push(pre.destProject.matches > 1 ? "project reference is ambiguous" : "project not found");
+        }
+        if (pre.destArea !== null && pre.destArea.resolved === null) {
+            problems.push(pre.destArea.matches > 1 ? "area reference is ambiguous" : "area not found");
+        }
+        if (pre.entityTarget !== null && pre.entityTarget.resolved === null) {
+            problems.push(pre.entityTarget.matches > 1 ? "target reference is ambiguous" : "target not found");
+        }
+        const needsTarget = typeof params["uuid"] === "string" &&
+            op !== "todo.add" &&
+            op !== "project.add" &&
+            pre.target === null;
+        if (needsTarget)
+            problems.push(`no record with uuid ${String(params["uuid"])}`);
+        if (pre.target !== null) {
+            // Type/state preconditions for the Tier-2 ops: the probed commands
+            // address `project id` / trashed `to do id` specifically (E14/E15/E17).
+            if ((op === "project.move" || op === "project.duplicate") && pre.target.type !== "project") {
+                problems.push(`target ${String(params["uuid"])} is a ${pre.target.type}, not a project`);
+            }
+            if ((op === "project.cancel" || op === "project.reopen" || op === "project.restore") &&
+                pre.target.type !== "project") {
+                problems.push(`target ${String(params["uuid"])} is a ${pre.target.type}, not a project`);
+            }
+            else if (op === "project.cancel" && pre.target.type === "project") {
+                // Only open->canceled is probed (P01); re-canceling resolved
+                // projects is unvalidated.
+                if (pre.target.status !== "open") {
+                    problems.push(`target project is already ${pre.target.status} — cancel needs an open project`);
+                }
+            }
+            else if (op === "project.reopen" && pre.target.type === "project") {
+                if (pre.target.status === "open") {
+                    problems.push("target project is already open — nothing to reopen");
+                }
+                if (pre.target.trashed) {
+                    problems.push("target project is in the Trash — restore it first (things project restore)");
+                }
+            }
+            else if (op === "project.restore" && pre.target.type === "project" && !pre.target.trashed) {
+                problems.push(`target ${String(params["uuid"])} is not in the Trash — restore only applies to ` +
+                    "trashed projects");
+            }
+            if (op === "todo.restore") {
+                if (pre.target.type !== "to-do") {
+                    problems.push(`target ${String(params["uuid"])} is a ${pre.target.type} — restore is only ` +
+                        "validated for to-dos (E15); restore a trashed project via the app");
+                }
+                else if (!pre.target.trashed) {
+                    problems.push(`target ${String(params["uuid"])} is not in the Trash — restore only applies to ` +
+                        "trashed to-dos (a live item would just be de-scheduled into the Inbox)");
+                }
+            }
+        }
+        if (problems.length === 0)
+            return null;
+        return {
+            hazard: "H-UNKNOWN-DESTINATION",
+            detail: `${problems.join("; ")} — unknown destinations are silent no-ops in the app (T06/U06)`,
+            remediation: "verify the uuid/name with `things search` or `things areas`/`things projects`",
+        };
+    },
+    "H-AMBIGUOUS-HEADING": ({ pre }) => {
+        if (pre.destHeading === null)
+            return null;
+        if (pre.destHeading.resolved !== null)
+            return null;
+        return {
+            hazard: "H-AMBIGUOUS-HEADING",
+            detail: pre.destHeading.matches > 1
+                ? "multiple headings with that name exist in the destination project"
+                : "heading not found in the destination project (the heading param never creates one — T09/U09)",
+            remediation: "rename the duplicate headings, or omit --heading",
+        };
+    },
+    "H-REMINDER-SCOPE": ({ op, params }) => {
+        if (op !== "todo.add" && op !== "todo.update" && op !== "project.update")
+            return null;
+        if (!("reminder" in params) || params["reminder"] === undefined)
+            return null;
+        const when = params["when"];
+        const isDate = typeof when === "string" && /^\d{4}-\d{2}-\d{2}$/.test(when);
+        if (params["reminder"] === null) {
+            // The clear IS a bare when= write — but only today/evening honor it;
+            // dated reminders are STICKY (persist through same-date AND re-dated
+            // bare when=, R20/R21). No URL clear path exists for them.
+            if (when === "today" || when === "evening")
+                return null;
+            return {
+                hazard: "H-REMINDER-SCOPE",
+                detail: isDate
+                    ? "dated reminders cannot be cleared via the URL scheme — they persist through " +
+                        "bare when= re-schedules (R20/R21)"
+                    : "clearing a reminder IS a bare when= write (R07) — when: today|evening must be " +
+                        "re-stated in the same call",
+                remediation: isDate
+                    ? "re-schedule with `--when today --clear-reminder` first (then re-date), or clear " +
+                        "it in the app"
+                    : "pass when today|evening together with --clear-reminder",
+            };
+        }
+        if (when === "today" || when === "evening" || isDate)
+            return null;
+        return {
+            hazard: "H-REMINDER-SCOPE",
+            detail: "reminders require a scheduled when: today|evening|YYYY-MM-DD (R-suite; " +
+                "anytime/someday carry no date for the reminder to attach to)",
+            remediation: "pass when today|evening|YYYY-MM-DD together with the reminder",
+        };
+    },
+    "H-BACKDATE-OPEN": ({ op, params, pre }) => {
+        if (op !== "todo.backdate" || params["completionDate"] === undefined)
+            return null;
+        const status = pre.target?.type === "to-do" ? pre.target.status : null;
+        if (status === "completed" || status === "canceled")
+            return null;
+        return {
+            hazard: "H-BACKDATE-OPEN",
+            detail: "completionDate can only be rewritten on a completed or canceled to-do — this one " +
+                `is ${status ?? "not a to-do / not found"}`,
+            remediation: "complete it first (todo.complete), then backdate",
+        };
+    },
+    "H-REORDER-SCOPE": ({ op, params, pre }) => {
+        if (op !== "reorder" || pre.reorder === null)
+            return null;
+        const problems = [];
+        // The `reorder` operation IS the native private command. Evening must
+        // never reach it: a native reorder normalizes startBucket to the Today
+        // list, silently de-evening-ing members (O03). The evening scope is
+        // served by the bounce orchestrator in reorder.ts instead.
+        if (params["scope"] === "evening") {
+            return {
+                hazard: "H-REORDER-SCOPE",
+                detail: "evening reorder is bounce-only: the native command would silently clear " +
+                    "startBucket on every listed item (O03)",
+                remediation: "use write.reorder / `things reorder --scope evening` (bounce strategy)",
+            };
+        }
+        if ((params["scope"] === "today" ||
+            params["scope"] === "evening" ||
+            params["scope"] === "inbox" ||
+            params["scope"] === "someday" ||
+            params["scope"] === "projects") &&
+            params["container"] !== undefined) {
+            problems.push("container is only valid for project/area/headings scopes");
+        }
+        const uuids = params["uuids"];
+        if (!Array.isArray(uuids) || uuids.length === 0) {
+            problems.push("no uuids given");
+        }
+        if (pre.reorder.duplicates.length > 0) {
+            problems.push(`duplicated uuid(s): ${pre.reorder.duplicates.join(", ")}`);
+        }
+        if (pre.reorder.mixedTypes) {
+            problems.push("mixes to-dos and projects in one area reorder — only same-type area reorders are " +
+                "validated (O05/O10 to-dos, O14 projects); issue two requests instead");
+        }
+        for (const r of pre.reorder.rejected) {
+            problems.push(`${r.uuid} ${r.reason}`);
+        }
+        if (problems.length === 0)
+            return null;
+        return {
+            hazard: "H-REORDER-SCOPE",
+            detail: `reorder request rejected — every uuid must be an eligible member of the scope, ` +
+                `exactly once: ${problems.join("; ")}`,
+            remediation: "read the scope first (things today / things project-view / things area) and pass " +
+                "only its eligible members in the desired order",
+        };
+    },
+    "H-TAG-SUBTREE-DELETE": ({ op, pre, acks }) => {
+        if (op !== "tag.delete")
+            return null;
+        if (pre.childTags.length === 0 || acks.acknowledgeTagSubtree === true)
+            return null;
+        return {
+            hazard: "H-TAG-SUBTREE-DELETE",
+            detail: `deleting this tag CASCADE-DELETES its ${pre.childTags.length} descendant tag(s) ` +
+                `permanently (P16): ${pre.childTags.join(", ")}`,
+            remediation: "re-parent the children first (things tag update <child> --parent <new>), or pass " +
+                "acknowledgeTagSubtree (--acknowledge-subtree) to delete the whole subtree",
+        };
+    },
+    "H-PERMANENT-DELETE": ({ op, acks }) => {
+        if (op !== "area.delete" && op !== "tag.delete" && op !== "trash.empty")
+            return null;
+        if (acks.dangerouslyPermanent === true)
+            return null;
+        const what = op === "trash.empty"
+            ? "empty-trash hard-deletes every trashed row"
+            : `${op === "area.delete" ? "areas" : "tags"} are deleted PERMANENTLY (no Trash, A25/A26)`;
+        return {
+            hazard: "H-PERMANENT-DELETE",
+            detail: `${what}; no tombstones are written while sync is off`,
+            remediation: "pass dangerouslyPermanent (--dangerously-permanent) to proceed",
+        };
+    },
+};
+export function evaluateGuards(hazards, input) {
+    for (const id of hazards) {
+        const guard = GUARDS[id];
+        const block = guard(input);
+        if (block !== null)
+            return block;
+    }
+    return null;
+}
+//# sourceMappingURL=guards.js.map

package/dist/write/guards.js.map

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

package/dist/write/lock.d.ts

@@ -0,0 +1,10 @@
+export declare class MutationLockError extends Error {
+    constructor(message: string);
+}
+export interface MutationLock {
+    release(): void;
+}
+export declare function acquireMutationLock(path: string, options?: {
+    waitMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+}): Promise<MutationLock>;

package/dist/write/lock.js

@@ -0,0 +1,70 @@
+/**
+ * Advisory mutation lockfile: serializes mutations across concurrent CLI
+ * invocations so create-probe verification is never ambiguous (design §4).
+ * Stale locks (dead pid) are stolen; live locks are awaited with backoff.
+ */
+import { mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+export class MutationLockError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "MutationLockError";
+    }
+}
+function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function acquireMutationLock(path, options = {}) {
+    const waitMs = options.waitMs ?? 30_000;
+    const sleep = options.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const deadline = Date.now() + waitMs;
+    mkdirSync(dirname(path), { recursive: true });
+    for (;;) {
+        try {
+            const payload = { pid: process.pid, ts: new Date().toISOString() };
+            writeFileSync(path, JSON.stringify(payload), { flag: "wx" });
+            return {
+                release() {
+                    try {
+                        unlinkSync(path);
+                    }
+                    catch {
+                        // already gone — fine
+                    }
+                },
+            };
+        }
+        catch (err) {
+            if (err.code !== "EEXIST")
+                throw err;
+            let holder = null;
+            try {
+                holder = JSON.parse(readFileSync(path, "utf8"));
+            }
+            catch {
+                holder = null; // torn write — treat as stale
+            }
+            if (holder === null || !pidAlive(holder.pid)) {
+                try {
+                    unlinkSync(path); // stale: holder is dead
+                }
+                catch {
+                    // raced another steal — loop and retry
+                }
+                continue;
+            }
+            if (Date.now() >= deadline) {
+                throw new MutationLockError(`another mutation is in progress (pid ${holder.pid} since ${holder.ts}); ` +
+                    `waited ${waitMs}ms for ${path}`);
+            }
+            await sleep(150);
+        }
+    }
+}
+//# sourceMappingURL=lock.js.map

package/dist/write/lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock.js","sourceRoot":"","sources":["../../src/write/lock.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC7E,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IAC1C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IAClC,CAAC;CACF;AAOD,SAAS,QAAQ,CAAC,GAAW;IAC3B,IAAI,CAAC;QACH,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QACrB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAMD,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,IAAY,EACZ,UAAsE,EAAE;IAExE,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,MAAM,CAAC;IACxC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;IAC/E,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,MAAM,CAAC;IACrC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAE9C,SAAS,CAAC;QACR,IAAI,CAAC;YACH,MAAM,OAAO,GAAgB,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,EAAE,CAAC;YAChF,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;YAC7D,OAAO;gBACL,OAAO;oBACL,IAAI,CAAC;wBACH,UAAU,CAAC,IAAI,CAAC,CAAC;oBACnB,CAAC;oBAAC,MAAM,CAAC;wBACP,sBAAsB;oBACxB,CAAC;gBACH,CAAC;aACF,CAAC;QACJ,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAK,GAA6B,CAAC,IAAI,KAAK,QAAQ;gBAAE,MAAM,GAAG,CAAC;YAChE,IAAI,MAAM,GAAuB,IAAI,CAAC;YACtC,IAAI,CAAC;gBACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAgB,CAAC;YACjE,CAAC;YAAC,MAAM,CAAC;gBACP,MAAM,GAAG,IAAI,CAAC,CAAC,8BAA8B;YAC/C,CAAC;YACD,IAAI,MAAM,KAAK,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC7C,IAAI,CAAC;oBACH,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,wBAAwB;gBAC5C,CAAC;gBAAC,MAAM,CAAC;oBACP,uCAAuC;gBACzC,CAAC;gBACD,SAAS;YACX,CAAC;YACD,IAAI,IAAI,CAAC,GAAG,EAAE,IAAI,QAAQ,EAAE,CAAC;gBAC3B,MAAM,IAAI,iBAAiB,CACzB,wCAAwC,MAAM,CAAC,GAAG,UAAU,MAAM,CAAC,EAAE,KAAK;oBACxE,UAAU,MAAM,UAAU,IAAI,EAAE,CACnC,CAAC;YACJ,CAAC;YACD,MAAM,KAAK,CAAC,GAAG,CAAC,CAAC;QACnB,CAAC;IACH,CAAC;AACH,CAAC"}