things-api 0.5.0

package/dist/write/reorder.js

@@ -0,0 +1,285 @@
+import { localToday, encodePackedDate } from "../model/dates.js";
+import { computeReorderPre, resolveArea, resolveProject } from "./pre-state.js";
+import { sdefDeclaresPrivateReorder } from "./experimental.js";
+import { fingerprintLabel, runMutation, } from "./pipeline.js";
+import { createDbReader, evaluateDelta } from "./verify/delta.js";
+import { pollUntilVerified } from "./verify/poller.js";
+/**
+ * Bounce cost is 2 verified mutations per item; beyond this the today scope
+ * should use the native strategy and the evening scope should be re-thought.
+ */
+export const BOUNCE_MAX_ITEMS = 10;
+export async function runReorder(deps, params, options = {}) {
+    const strategy = resolveStrategy(deps, params);
+    if (strategy.kind === "blocked")
+        return strategy.result;
+    if (strategy.strategy === "native") {
+        return runMutation(deps, "reorder", params, { ...options, vector: "applescript" });
+    }
+    return runBounce(deps, params, options);
+}
+function resolveStrategy(deps, params) {
+    const blocked = (detail, remediation) => ({
+        kind: "blocked",
+        result: {
+            kind: "blocked",
+            op: "reorder",
+            reason: "hazard",
+            hazard: "H-REORDER-SCOPE",
+            detail,
+            remediation,
+        },
+    });
+    const nativeAvailable = deps.config.allowExperimental && (deps.sdefProbe ?? sdefDeclaresPrivateReorder)();
+    if (params.strategy === "native") {
+        if (params.scope === "evening") {
+            return blocked("evening reorder is bounce-only: the native command silently clears startBucket on " +
+                "every listed item (O03)", "omit --strategy (evening defaults to bounce)");
+        }
+        if (params.scope === "projects") {
+            return blocked("top-level sidebar order has NO native surface (every AppleScript spelling errors " +
+                "and the private command no-ops — scf2 P6); only the when= bounce works (P8e)", "omit --strategy (projects defaults to bounce)");
+        }
+        return { kind: "ok", strategy: "native" };
+    }
+    if (params.strategy === "bounce") {
+        if (params.scope === "project" ||
+            params.scope === "area" ||
+            params.scope === "inbox" ||
+            params.scope === "headings" ||
+            params.scope === "someday") {
+            return blocked("bounce can only reorder the Today/Evening sections and top-level projects — its " +
+                "primitive is a when= round-trip, which does not move this scope's order", "use the native strategy (requires `things config set allow-experimental true`)");
+        }
+        return { kind: "ok", strategy: "bounce" };
+    }
+    // Default per scope.
+    switch (params.scope) {
+        case "evening":
+        case "projects":
+            return { kind: "ok", strategy: "bounce" };
+        case "today":
+            return { kind: "ok", strategy: nativeAvailable ? "native" : "bounce" };
+        case "project":
+        case "area":
+        case "inbox":
+        case "headings":
+        case "someday":
+            // Native-only scopes: let the pipeline explain precisely why native is
+            // unavailable (planner: experimental gate; canary: sdef change).
+            return { kind: "ok", strategy: "native" };
+    }
+}
+// ------------------------------------------------------------------- bounce
+async function runBounce(deps, params, options) {
+    const startedAt = deps.now?.() ?? new Date();
+    const now = deps.now ?? (() => new Date());
+    const scope = params.scope;
+    const rankKey = scope === "projects" ? "index" : "todayIndex";
+    const legOp = scope === "projects" ? "project.update" : "todo.update";
+    // Scope/membership guard — same data the native path's guard uses.
+    const pre = computeReorderPre(deps.db, params, resolveContainerUuid(deps, params), now());
+    const problems = [];
+    if (params.container !== undefined)
+        problems.push("container is only valid for project/area/headings scopes");
+    if (params.uuids.length === 0)
+        problems.push("no uuids given");
+    if (pre.duplicates.length > 0)
+        problems.push(`duplicated uuid(s): ${pre.duplicates.join(", ")}`);
+    for (const r of pre.rejected)
+        problems.push(`${r.uuid} ${r.reason}`);
+    if (scope !== "projects") {
+        for (const uuid of pre.projectMembers) {
+            problems.push(`${uuid} is a project — bounce re-schedules via todo.update, which is only validated ` +
+                "for to-dos; use the native strategy for Today lists containing projects");
+        }
+    }
+    if (params.uuids.length > BOUNCE_MAX_ITEMS) {
+        problems.push(`${params.uuids.length} items exceeds the bounce cap of ${BOUNCE_MAX_ITEMS} ` +
+            "(each item costs two verified mutations)");
+    }
+    if (problems.length > 0) {
+        const result = {
+            kind: "blocked",
+            op: "reorder",
+            reason: "hazard",
+            hazard: "H-REORDER-SCOPE",
+            detail: `reorder request rejected: ${problems.join("; ")}`,
+            remediation: "read the scope first (things today) and pass only its eligible members, " +
+                `at most ${BOUNCE_MAX_ITEMS} for the bounce strategy`,
+        };
+        auditSummary(deps, params, startedAt, "blocked:H-REORDER-SCOPE", null);
+        return result;
+    }
+    const away = scope === "today" ? "evening" : scope === "projects" ? "someday" : "today";
+    const back = scope === "projects" ? "anytime" : scope;
+    if (options.dryRun === true) {
+        return {
+            kind: "dry-run",
+            op: "reorder",
+            plan: {
+                op: "reorder",
+                vector: "url-scheme",
+                tier: 0,
+                invocation: `bounce ×${params.uuids.length} (reverse order): ` +
+                    `when=${away} → verified → when=${back} → verified; ` +
+                    "state re-checked between items",
+                expectedDelta: { mode: "ordering", key: rankKey, sequence: params.uuids },
+                hazardsChecked: ["H-REORDER-SCOPE"],
+            },
+        };
+    }
+    // Bounce in REVERSE: each round-trip front-inserts (O07/O08), so placing
+    // the last item first leaves the requested order on top.
+    const placed = [];
+    for (let i = params.uuids.length - 1; i >= 0; i--) {
+        const uuid = params.uuids[i];
+        // Concurrent-edit re-check: the item must still be an eligible member.
+        const memberProblem = checkStillMember(deps, uuid, scope, now());
+        if (memberProblem !== null) {
+            const detail = `aborted before bouncing ${uuid}: ${memberProblem} (Things was likely edited ` +
+                "concurrently); already-placed items keep their new positions";
+            auditSummary(deps, params, startedAt, "verify-failed:mismatch", { placed: [...placed] });
+            return {
+                kind: "bounce-aborted",
+                op: "reorder",
+                detail,
+                placed: [...placed],
+                remaining: params.uuids.slice(0, i + 1),
+                cause: null,
+            };
+        }
+        const leg1 = await runMutation(deps, legOp, { uuid, when: away }, legOptions(options));
+        if (leg1.kind !== "ok") {
+            auditSummary(deps, params, startedAt, "verify-failed:mismatch", { placed: [...placed] });
+            return {
+                kind: "bounce-aborted",
+                op: "reorder",
+                detail: `bounce leg 1 (when=${away}) failed for ${uuid} — the item was NOT moved`,
+                placed: [...placed],
+                remaining: params.uuids.slice(0, i + 1),
+                cause: leg1,
+            };
+        }
+        const leg2 = await runMutation(deps, legOp, { uuid, when: back }, legOptions(options));
+        if (leg2.kind !== "ok") {
+            auditSummary(deps, params, startedAt, "verify-failed:mismatch", { placed: [...placed] });
+            return {
+                kind: "bounce-aborted",
+                op: "reorder",
+                detail: `bounce leg 2 (when=${back}) failed for ${uuid} — THE ITEM IS STRANDED IN ` +
+                    `${away.toUpperCase()}; re-schedule it (when=${back}) or fix in the app`,
+                placed: [...placed],
+                remaining: params.uuids.slice(0, i + 1),
+                cause: leg2,
+            };
+        }
+        placed.unshift(uuid);
+        // Placed-prefix invariant: everything bounced so far must read back in
+        // requested relative order — anything else means a concurrent reshuffle.
+        const prefixCheck = await pollUntilVerified(() => evaluateDelta({ mode: "ordering", key: rankKey, sequence: [...placed] }, createDbReader(deps.db), { modDates: {}, fields: {} }), options.verifyTimeoutMs ?? 4000, deps.poller ?? {});
+        if (prefixCheck.kind !== "ok") {
+            auditSummary(deps, params, startedAt, "verify-failed:mismatch", { placed: [...placed] });
+            return {
+                kind: "bounce-aborted",
+                op: "reorder",
+                detail: `placed items fell out of order after bouncing ${uuid} (concurrent edit?); ` +
+                    "re-run the reorder once Things is idle",
+                placed: [...placed],
+                remaining: params.uuids.slice(0, i),
+                cause: null,
+            };
+        }
+    }
+    const reader = createDbReader(deps.db);
+    const observed = {};
+    for (const uuid of params.uuids)
+        observed[uuid] = reader.rankOf(uuid, rankKey);
+    auditSummary(deps, params, startedAt, "ok", observed);
+    return {
+        kind: "ok",
+        op: "reorder",
+        uuid: null,
+        observed,
+        vector: "url-scheme",
+        tier: 0,
+    };
+}
+function legOptions(options) {
+    const legs = {};
+    if (options.maxDisruption !== undefined)
+        legs.maxDisruption = options.maxDisruption;
+    if (options.verifyTimeoutMs !== undefined)
+        legs.verifyTimeoutMs = options.verifyTimeoutMs;
+    if (options.actor !== undefined)
+        legs.actor = options.actor;
+    return legs;
+}
+function resolveContainerUuid(deps, params) {
+    if (params.scope === "project" || params.scope === "headings") {
+        return resolveProject(deps.db, params.container ?? {}).resolved?.uuid ?? null;
+    }
+    if (params.scope === "area") {
+        return resolveArea(deps.db, params.container ?? {}).resolved?.uuid ?? null;
+    }
+    return null;
+}
+/** null = still eligible; otherwise a human-readable problem. */
+function checkStillMember(deps, uuid, scope, now) {
+    const packedToday = encodePackedDate(localToday(now));
+    const row = deps.db
+        .prepare("SELECT status, trashed, startBucket, startDate, start, type, area FROM TMTask WHERE uuid = ?")
+        .get(uuid);
+    if (row === undefined)
+        return "the item no longer exists";
+    if (row.trashed !== 0)
+        return "the item was trashed";
+    if (row.status !== 0)
+        return "the item is no longer open";
+    if (scope === "projects") {
+        if (row.type !== 1)
+            return "the item is not a project";
+        if (row.area !== null)
+            return "the project moved into an area";
+        if (row.start !== 1 || row.startDate !== null) {
+            return "the project is no longer a plain Anytime project";
+        }
+        return null;
+    }
+    const inToday = row.startDate !== null && row.startDate <= packedToday && (row.start === 1 || row.start === 2);
+    if (!inToday)
+        return "the item left the Today list";
+    if (scope === "today" && row.startBucket !== 0)
+        return "the item moved to This Evening";
+    if (scope === "evening" && (row.startBucket !== 1 || row.startDate !== packedToday)) {
+        return "the item left This Evening";
+    }
+    return null;
+}
+function auditSummary(deps, params, startedAt, result, observed) {
+    const fp = deps.fingerprint();
+    const record = {
+        v: 1,
+        ts: startedAt.toISOString(),
+        actor: deps.config.actor,
+        host: deps.config.host,
+        op: "reorder",
+        uuid: null,
+        vector: "url-scheme",
+        disruption: 0,
+        invocation: `bounce(${params.scope}) ×${params.uuids.length}`,
+        requested: params,
+        pre: null,
+        observed,
+        result,
+        verify: null,
+        durationMs: (deps.now?.() ?? new Date()).getTime() - startedAt.getTime(),
+        env: {
+            pkg: deps.pkgVersion ?? "0.0.1",
+            dbVersion: fp.observation.databaseVersion,
+            fingerprint: fingerprintLabel(fp, deps.config),
+        },
+    };
+    deps.audit.append(record);
+}
+//# sourceMappingURL=reorder.js.map

package/dist/write/reorder.js.map

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

package/dist/write/undo.d.ts

@@ -0,0 +1,53 @@
+import type { AuditRecord } from "../audit/schema.ts";
+import type { OperationKind } from "./operations.ts";
+import { type MutationResult, type WriteDeps } from "./pipeline.ts";
+import { type ReorderResult } from "./reorder.ts";
+export interface UndoStep {
+    op: OperationKind;
+    params: Record<string, unknown>;
+    /** Acknowledgements the inverse op needs (surfaced in the plan). */
+    options?: {
+        acknowledgeChecklistReset?: boolean;
+        dangerouslyPermanent?: boolean;
+    };
+}
+export interface UndoPlan {
+    /** The audit record being undone. */
+    target: {
+        ts: string;
+        op: string;
+        uuid: string | null;
+        actor: string;
+    };
+    kind: "invertible" | "irreversible";
+    steps: UndoStep[];
+    /** Fidelity caveats — what the inverse cannot restore. */
+    notes: string[];
+    /** Present when kind is "irreversible". */
+    reason?: string;
+}
+export interface UndoItemResult {
+    plan: UndoPlan;
+    /** One result per executed step (empty for dry-run/irreversible). */
+    results: (MutationResult | ReorderResult)[];
+    outcome: "ok" | "partial" | "failed" | "irreversible" | "dry-run";
+}
+export interface UndoOptions {
+    /** How many trailing mutations to undo (default 1). */
+    last?: number;
+    dryRun?: boolean;
+    /** Required for inverses that delete areas/tags permanently. */
+    dangerouslyPermanent?: boolean;
+    verifyTimeoutMs?: number;
+    actor?: string;
+}
+/** Parse every audit record from the monthly JSONL files, oldest first. */
+export declare function readAuditRecords(dir: string): AuditRecord[];
+/**
+ * The last N undoable targets, NEWEST FIRST (undo unwinds a stack). Only
+ * successful mutations qualify; inverse mutations (actor `undo:…`) never do.
+ */
+export declare function selectUndoTargets(records: AuditRecord[], last: number): AuditRecord[];
+/** Build the inverse plan for one audit record. Pure — unit-testable. */
+export declare function planUndo(record: AuditRecord, now: Date): UndoPlan;
+export declare function runUndo(deps: WriteDeps, auditDirPath: string, options?: UndoOptions, onItem?: (item: UndoItemResult) => void): Promise<UndoItemResult[]>;