things-api 0.9.0 → 0.11.0

package/dist/write/tag-refs.js

@@ -0,0 +1,126 @@
+import { normalizeNameKey, stripThingsUri } from "../read/queries.js";
+function allTags(db) {
+    return db.prepare("SELECT uuid, title, parent FROM TMTag").all();
+}
+/** Dedup key for a per-parent planned title (parent title + title). */
+function planKey(parentTitle, title) {
+    return `${parentTitle ?? ""}${title}`;
+}
+/**
+ * Title-match tiers within a candidate row set: exact -> case-insensitive ->
+ * normalized (dash/space-forgiving). Returns the rows of the FIRST tier that
+ * matches at all.
+ */
+function titleMatches(rows, title) {
+    const exact = rows.filter((r) => r.title === title);
+    if (exact.length > 0)
+        return exact;
+    const lower = title.toLowerCase();
+    const ci = rows.filter((r) => r.title.toLowerCase() === lower);
+    if (ci.length > 0)
+        return ci;
+    const key = normalizeNameKey(title);
+    if (key === "")
+        return [];
+    return rows.filter((r) => normalizeNameKey(r.title) === key);
+}
+function resolveOne(rows, refRaw) {
+    const ref = stripThingsUri(refRaw);
+    // Literal title (literal-over-path: this matches `sl/ash` as a whole). A name
+    // matching ≥1 tag is "known" — pass the NAME through; the app resolves it.
+    const literal = titleMatches(rows, ref);
+    if (literal.length >= 1)
+        return { kind: "title", title: literal[0].title };
+    // Path-qualified `parent/child` — resolve the chain from the root. Duplicate
+    // names never refuse: descend into the first match at each level.
+    if (ref.includes("/")) {
+        const segs = ref.split("/").map((s) => s.trim());
+        if (segs.some((s) => s === ""))
+            return { kind: "missing" };
+        let scope = rows.filter((r) => r.parent === null);
+        let leaf = null;
+        for (const seg of segs) {
+            const hits = titleMatches(scope, seg);
+            if (hits.length === 0)
+                return { kind: "missing" };
+            leaf = hits[0];
+            scope = rows.filter((r) => r.parent === leaf.uuid);
+        }
+        if (leaf !== null)
+            return { kind: "title", title: leaf.title };
+    }
+    return { kind: "missing" };
+}
+export function resolveTagRefs(db, refs) {
+    const rows = allTags(db);
+    const titles = [];
+    const seen = new Set();
+    const missing = [];
+    for (const ref of refs) {
+        const r = resolveOne(rows, ref);
+        if (r.kind === "title") {
+            if (!seen.has(r.title)) {
+                seen.add(r.title);
+                titles.push(r.title);
+            }
+        }
+        else {
+            missing.push(ref);
+        }
+    }
+    return { titles, missing };
+}
+/**
+ * Ordered `make new tag` steps to satisfy `--create-tags`: only the tags that
+ * are genuinely MISSING, with mkdir-p intermediates for a `parent/child` path
+ * (parents first so each child's parent resolves). A ref that already resolves
+ * yields no step (idempotent — the TAGW1-c coalesce also makes re-creation a
+ * no-op).
+ */
+export function planTagCreation(db, refs) {
+    const rows = allTags(db);
+    const steps = [];
+    // Titles known to exist OR already planned this call, per hierarchy level,
+    // so a repeated segment across refs is planned once.
+    const planned = new Set();
+    for (const refRaw of refs) {
+        const ref = stripThingsUri(refRaw);
+        if (resolveOne(rows, ref).kind === "title")
+            continue;
+        if (ref.includes("/")) {
+            const segs = ref.split("/").map((s) => s.trim());
+            if (segs.some((s) => s === ""))
+                continue;
+            let scope = rows.filter((r) => r.parent === null);
+            let parentTitle;
+            for (const seg of segs) {
+                const hits = titleMatches(scope, seg);
+                if (hits.length >= 1) {
+                    const hit = hits[0];
+                    parentTitle = hit.title;
+                    scope = rows.filter((r) => r.parent === hit.uuid);
+                }
+                else {
+                    // Missing -> plan it and descend into a now-empty scope so the
+                    // remaining segments are all created too.
+                    const k = planKey(parentTitle, seg);
+                    if (!planned.has(k)) {
+                        planned.add(k);
+                        steps.push(parentTitle === undefined ? { title: seg } : { title: seg, parent: parentTitle });
+                    }
+                    parentTitle = seg;
+                    scope = [];
+                }
+            }
+        }
+        else {
+            const k = planKey(undefined, ref);
+            if (!planned.has(k)) {
+                planned.add(k);
+                steps.push({ title: ref });
+            }
+        }
+    }
+    return steps;
+}
+//# sourceMappingURL=tag-refs.js.map

package/dist/write/tag-refs.js.map

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

package/dist/write/undo.d.ts

@@ -1,6 +1,6 @@
-import type { AuditRecord } from "../audit/schema.ts";
+import { type AuditRecord } from "../audit/schema.ts";
 import type { AnyTask } from "../model/entities.ts";
-import type { OperationKind } from "./operations.ts";
+import { type OperationKind } from "./operations.ts";
 import { type MutationResult, type WriteDeps } from "./pipeline.ts";
 import { type ReorderResult } from "./reorder.ts";
 export interface UndoStep {
@@ -21,6 +21,18 @@ export interface UndoStep {
             detail: string;
             remediation: string;
         };
+        /**
+         * STRUCTURAL axes this step overwrites (getField paths into the decoded
+         * target: `status`, `trashed`, `project`/`project.uuid`, `area`/`area.uuid`,
+         * `heading.uuid`, `start`/`startDate`/`todaySection`). Before executing,
+         * `checkStepPrecondition` verifies the target's CURRENT value on each still
+         * equals the recorded `observed` after-value — an out-of-band move/status/
+         * schedule change already there blocks rather than being clobbered. Set only
+         * for the PRIMARY-target step and only for axes whose after-state `observed`
+         * captured (fields absent from `observed` are skipped). Content fields stay
+         * on the separate CLOBBER_FIELDS path; the two are checked together.
+         */
+        guardFields?: string[];
     };
 }
 export interface UndoPlan {
@@ -30,6 +42,7 @@ export interface UndoPlan {
         op: string;
         uuid: string | null;
         actor: string;
+        token: string;
     };
     kind: "invertible" | "irreversible";
     steps: UndoStep[];
@@ -47,19 +60,75 @@ export interface UndoItemResult {
 export interface UndoOptions {
     /** How many trailing mutations to undo (default 1). */
     last?: number;
+    /**
+     * SELECTION filter — undo only mutations recorded under this actor. An exact
+     * actor string (e.g. "mcp:claude-code", "mike") or "*" for all actors.
+     * Undefined means all (the CLI's global default); the MCP surface defaults it
+     * to the connecting client's own derived actor (`mcp:<client>`).
+     *
+     * Matching is EXACT: `by: "mike"` selects records whose actor is exactly
+     * "mike" and never an undo record (`undo:mike`) — inverse mutations are their
+     * own actor and are never themselves undo targets. NOT the same as `actor`
+     * below, which names who the NEW inverse mutation is attributed to.
+     */
+    by?: string;
+    /**
+     * EXACT selection by undo token (from a mutation result's `undoToken`).
+     * Undoes precisely that one record, immune to interleaving. Mutually
+     * exclusive with `last`/`by` (enforced at the call surfaces).
+     */
+    txn?: string;
     dryRun?: boolean;
     /** Required for inverses that delete areas/tags permanently. */
     dangerouslyPermanent?: boolean;
+    /**
+     * Proceed even when the target changed OUTSIDE things-api since the recorded
+     * change — bypasses the precondition guard uniformly (both the content-field
+     * and the structural axis checks), overwriting whatever an out-of-band edit
+     * left. Does NOT bypass the checklist item-level refusal (a separate plan-time
+     * mechanism with no faithful forced inverse). "The world moved, overwrite
+     * anyway."
+     */
+    acknowledgeOutOfBandChanges?: boolean;
     verifyTimeoutMs?: number;
+    /** Author RECORDED for the inverse mutation (as `undo:<actor>`); see `by`. */
     actor?: string;
 }
 /** Parse every audit record from the monthly JSONL files, oldest first. */
 export declare function readAuditRecords(dir: string): AuditRecord[];
+export interface UndoSelector {
+    /** How many trailing targets to take (default 1); ignored when `txn` is set. */
+    last?: number;
+    /** Actor filter: exact actor string, or "*"/undefined for all. */
+    by?: string;
+    /** Exact undo-token selection: returns the single matching target (or none). */
+    txn?: string;
+}
+export interface AuditIntegrity {
+    /** Intent records with no later matching final record — a write MAY have landed unrecorded. */
+    orphanedIntents: number;
+    /** Newest orphaned intent's timestamp (ISO), or null when there are none. */
+    newestOrphanIntent: string | null;
+}
+/**
+ * Detect crashed writes: INTENT records left without a matching final record.
+ * A mutation writes an intent immediately before touching the app and a final
+ * record after read-after-write; the two share ts+op+actor+host. An intent
+ * with no non-intent sibling on that key means the process died mid-write — the
+ * app may have applied the change, but no result was recorded, so the change is
+ * invisible to undo. Surfaced by `things doctor` so the user can reconcile.
+ */
+export declare function scanAuditIntegrity(records: AuditRecord[]): AuditIntegrity;
 /**
- * The last N undoable targets, NEWEST FIRST (undo unwinds a stack). Only
- * successful mutations qualify; inverse mutations (actor `undo:…`) never do.
+ * The undoable targets to unwind, NEWEST FIRST (undo unwinds a stack).
+ *
+ *  - `txn` wins when present: the ONE record whose undo token matches (or an
+ *    empty array — the caller distinguishes not-found from already-undone).
+ *  - otherwise the last `last` records, optionally narrowed to actor `by`
+ *    (exact match; "*"/undefined = every actor). `by` NEVER matches an
+ *    `undo:<actor>` record — those are excluded from undoability entirely.
  */
-export declare function selectUndoTargets(records: AuditRecord[], last: number): AuditRecord[];
+export declare function selectUndoTargets(records: AuditRecord[], selector?: UndoSelector): AuditRecord[];
 /**
  * Operations with NO validated inverse surface — reported irreversible on
  * sight, before any per-record analysis. The reversibility matrix cross-checks