things-api 0.9.0 → 0.10.0

package/dist/cli/commands/writes.js

@@ -1,23 +1,24 @@
 import { readFileSync } from "node:fs";
-import { openThings } from "../../client.js";
-import { saveConfigKey } from "../../config.js";
-import { ThingsDbNotFoundError } from "../../db/locate.js";
-import { ThingsDbOpenError } from "../../db/connection.js";
-import { capabilitiesTable } from "../../write/capabilities.js";
-import { outcomeFailed } from "../../write/batch.js";
-import { BOUNCE_MAX_ITEMS } from "../../write/reorder.js";
-import { errorEnvelope, ExitCode, okEnvelope } from "../../contracts.js";
+import { addRepeatRuleFlags, repeatRuleFlagsFromOpts } from "./repeat-flags.js";
+import { aggregateExitCode, blockedCode, BOUNCE_MAX_ITEMS, capabilitiesTable, errorEnvelope, ExitCode, okEnvelope, openThings, outcomeFailed, ReferenceResolutionError, saveConfigKey, splitWhenSugar, ThingsDbNotFoundError, ThingsDbOpenError, verifyFailedCode, } from "../../index.js";
+import { usageError } from "../read-driver.js";
 function addWriteFlags(cmd) {
     return cmd
         .option("--json", "emit versioned JSON envelope on stdout")
         .option("--db <path>", "explicit database path")
         .option("--dry-run", "preview the planned change and its expected effect; nothing executes")
-        .option("--vector <id>", "force how the change is delivered: url-scheme | applescript | shortcuts")
+        .option("--vector <id>", "force how the change is delivered: url-scheme | applescript | shortcuts | ui")
         .option("--allow-disruptive", "permit changes that briefly steal window focus")
         .option("--allow-very-disruptive", "permit changes that visibly drive the Things UI")
         .option("--verify-timeout <ms>", "how long to wait for the change to take effect")
         .option("--actor <name>", "author name recorded for this change (default: from config)");
 }
+/** A commander flag value when present-with-value (bare presence yields `true`). */
+const flagVal = (v) => (typeof v === "string" ? v : undefined);
+/** Writes one batch result as an NDJSON line to stdout. */
+const emit = (r) => {
+    process.stdout.write(`${JSON.stringify(r)}\n`);
+};
 function writeOptionsFrom(opts, extra = {}) {
     const maxDisruption = opts.allowVeryDisruptive
         ? 3
@@ -30,31 +31,46 @@ function writeOptionsFrom(opts, extra = {}) {
         ...(maxDisruption !== undefined && { maxDisruption }),
         ...(opts.verifyTimeout !== undefined && { verifyTimeoutMs: Number(opts.verifyTimeout) }),
         ...(opts.actor !== undefined && { actor: opts.actor }),
+        ...(opts.dangerouslyDriveGui === true && { dangerouslyDriveGui: true }),
         ...extra,
     };
 }
+/**
+ * `--create-tags` on a tag-accepting command: create any named tag that does
+ * not exist yet (mkdir-p for `parent/child`) before applying, instead of
+ * refusing. Nesting is via the clean `make new tag` path.
+ */
+function addCreateTagsFlag(cmd) {
+    return cmd.option("--create-tags", "create any named tag that does not exist yet (nesting parent/child) before applying, " +
+        "instead of stopping on an unknown tag");
+}
+/** WriteOptions extra carrying createTags when the flag is set. */
+function createTagsExtra(opts) {
+    return opts["createTags"] === true ? { createTags: true } : {};
+}
+/** Add the mandatory GUI-drive acknowledgement to a ui-vector command. */
+function addDriveGuiFlag(cmd) {
+    return cmd.option("--dangerously-drive-gui", "required: this drives the local Things app through its accessibility interface to make a " +
+        "change the app offers nowhere else; also needs `things config set ui-enabled true`. " +
+        "Intended for a dedicated always-on Mac.");
+}
 function collect(value, previous) {
     return [...previous, value];
 }
 /**
  * URL-style `--when DATE@TIME` sugar: splits into when + reminder for the
- * ops that take both (an explicit --reminder alongside the suffix errors).
+ * ops that take both (an explicit --reminder alongside the suffix errors). The
+ * `@` split and its usage copy are the shared {@link splitWhenSugar} core; this
+ * only mutates the parsed opts on a successful split.
  */
 function applyWhenSugar(opts) {
-    const when = opts["when"];
-    if (typeof when !== "string" || !when.includes("@"))
-        return null;
-    const at = when.indexOf("@");
-    const date = when.slice(0, at);
-    const time = when.slice(at + 1);
-    if (date === "" || time === "" || time.includes("@")) {
-        return `invalid --when "${when}" — expected today | evening | anytime | someday | YYYY-MM-DD (set a reminder with --reminder HH:mm)`;
+    const r = splitWhenSugar(opts["when"], opts["reminder"] !== undefined);
+    if (r.kind === "error")
+        return r.message;
+    if (r.kind === "split") {
+        opts["when"] = r.when;
+        opts["reminder"] = r.reminder;
     }
-    if (opts["reminder"] !== undefined) {
-        return `--when "${when}" carries an @time suffix and --reminder was also given — use one`;
-    }
-    opts["when"] = date;
-    opts["reminder"] = time;
     return null;
 }
 /** Apply the sugar or print the usage error; false = caller returns. */
@@ -62,8 +78,7 @@ function whenSugarOk(opts) {
     const err = applyWhenSugar(opts);
     if (err === null)
         return true;
-    process.stderr.write(`error: ${err}\n`);
-    process.exitCode = ExitCode.Usage;
+    usageError(opts, err);
     return false;
 }
 function splitCsv(value) {
@@ -93,6 +108,23 @@ async function runWrite(opts, fn) {
         emitResult(result, opts, meta(client));
     }
     catch (err) {
+        // An unresolved write target (uuid/partial-uuid/name that is ambiguous or
+        // not-found) is a usage-class failure carrying machine-readable candidates
+        // — never the generic `unexpected`.
+        if (err instanceof ReferenceResolutionError) {
+            if (opts.json) {
+                process.stdout.write(`${JSON.stringify(errorEnvelope({
+                    code: err.code,
+                    message: err.message,
+                    details: { candidates: err.candidates },
+                }, meta(client)))}\n`);
+            }
+            else {
+                process.stderr.write(`error: ${err.message}\n`);
+            }
+            process.exitCode = ExitCode.Usage;
+            return;
+        }
         const isEnv = err instanceof ThingsDbNotFoundError || err instanceof ThingsDbOpenError;
         const message = err instanceof Error ? err.message : String(err);
         if (opts.json) {
@@ -159,7 +191,7 @@ function emitResult(result, opts, meta) {
         case "verify-failed": {
             if (opts.json) {
                 process.stdout.write(`${JSON.stringify(errorEnvelope({
-                    code: `verify-failed:${result.reason}`,
+                    code: verifyFailedCode(result),
                     message: result.detail,
                     ...(result.likelyCause !== undefined && { likelyCause: result.likelyCause }),
                     ...(result.hint !== undefined && { remediation: result.hint }),
@@ -179,7 +211,7 @@ function emitResult(result, opts, meta) {
             const code = result.reason === "drift" ? ExitCode.DriftBlocked : ExitCode.Blocked;
             if (opts.json) {
                 process.stdout.write(`${JSON.stringify(errorEnvelope({
-                    code: `blocked:${result.hazard ?? result.reason}`,
+                    code: blockedCode(result),
                     message: result.detail,
                     ...(result.likelyCause !== undefined && { likelyCause: result.likelyCause }),
                     remediation: result.remediation,
@@ -223,22 +255,23 @@ function group(program, name, description) {
 const containerRef = (value) => value === undefined ? undefined : { uuid: value, title: value };
 export function registerWriteCommands(program) {
     const todo = group(program, "todo", "To-do–scoped operations");
-    addWriteFlags(todo
+    addCreateTagsFlag(addWriteFlags(todo
         .command("add <title>")
-        .description("Create a to-do; its uuid is printed on success. Tags, projects, areas, and " +
-        "headings must name existing items — unknown or ambiguous references are " +
-        "rejected. Adding into a completed/canceled project reopens that project — " +
+        .description("Create a to-do; its uuid is printed on success. Projects, areas, and headings " +
+        "must name existing items — unknown or ambiguous references are rejected. A tag " +
+        "may be a name or a parent/child path, and must exist unless " +
+        "--create-tags. Adding into a completed/canceled project reopens that project — " +
         "requires --acknowledge-project-reopen.")
         .option("--notes <text>", "notes body")
         .option("--when <value>", "today | evening | anytime | someday | YYYY-MM-DD")
         .option("--reminder <HH:mm>", "time-of-day reminder (24h); requires --when today|evening|YYYY-MM-DD")
         .option("--deadline <date>", "YYYY-MM-DD")
-        .option("--tags <list>", "comma-separated EXISTING tag names")
+        .option("--tags <list>", "comma-separated tags; each a name or a parent/child path (must exist unless --create-tags)")
         .option("--checklist-item <text>", "checklist item (repeatable)", collect, [])
         .option("--project <ref>", "destination project (uuid or unique name)")
         .option("--area <ref>", "destination area (uuid or unique name)")
         .option("--heading <name>", "existing heading in the destination project")
-        .option("--acknowledge-project-reopen", "allow adding into a completed/canceled project")).action(async (title, opts) => {
+        .option("--acknowledge-project-reopen", "allow adding into a completed/canceled project"))).action(async (title, opts) => {
         const checklist = opts["checklistItem"];
         const tags = splitCsv(opts["tags"]);
         const project = containerRef(opts["project"]);
@@ -260,6 +293,7 @@ export function registerWriteCommands(program) {
             ...(opts["acknowledgeProjectReopen"] !== undefined && {
                 acknowledgeProjectReopen: opts["acknowledgeProjectReopen"],
             }),
+            ...createTagsExtra(opts),
         })));
     });
     addWriteFlags(todo
@@ -282,13 +316,11 @@ export function registerWriteCommands(program) {
         .option("--clear-deadline", "remove the deadline")).action(async (uuid, opts) => {
         const notesModes = ["notes", "appendNotes", "prependNotes"].filter((k) => opts[k] !== undefined);
         if (notesModes.length > 1) {
-            process.stderr.write("error: --notes, --append-notes, --prepend-notes are exclusive\n");
-            process.exitCode = ExitCode.Usage;
+            usageError(opts, "--notes, --append-notes, --prepend-notes are exclusive");
             return;
         }
         if (opts["reminder"] !== undefined && opts["clearReminder"] === true) {
-            process.stderr.write("error: pass at most one of --reminder / --clear-reminder\n");
-            process.exitCode = ExitCode.Usage;
+            usageError(opts, "pass at most one of --reminder / --clear-reminder");
             return;
         }
         if (!whenSugarOk(opts))
@@ -336,8 +368,7 @@ export function registerWriteCommands(program) {
         const detach = opts["detach"] === true;
         const dest = project !== undefined || area !== undefined || opts["heading"] !== undefined;
         if ((inbox && (dest || detach)) || (detach && dest)) {
-            process.stderr.write("error: --inbox/--detach are exclusive with each other and with --project/--area/--heading\n");
-            process.exitCode = ExitCode.Usage;
+            usageError(opts, "--inbox/--detach are exclusive with each other and with --project/--area/--heading");
             return;
         }
         await runWrite(opts, (c) => c.write.moveTodo(uuid, {
@@ -359,23 +390,22 @@ export function registerWriteCommands(program) {
         "available for repeating to-dos.")).action(async (uuid, opts) => {
         await runWrite(opts, (c) => c.write.duplicateTodo(uuid, writeOptionsFrom(opts)));
     });
-    addWriteFlags(todo
+    addCreateTagsFlag(addWriteFlags(todo
         .command("tags <uuid>")
         .description("Set or extend a to-do's tags. --set REPLACES the full tag set (an empty value " +
-        "clears all tags); --add merges with the current tags. Tags must name existing " +
-        "tags — unknown tags are rejected.")
-        .option("--set <list>", "comma-separated tag names: full replacement")
-        .option("--add <list>", "comma-separated tag names: merge with existing")).action(async (uuid, opts) => {
+        "clears all tags); --add merges with the current tags. Each tag may be a name " +
+        "or a parent/child path, and must exist unless --create-tags.")
+        .option("--set <list>", "comma-separated tags: full replacement")
+        .option("--add <list>", "comma-separated tags: merge with existing"))).action(async (uuid, opts) => {
         const set = splitCsv(opts["set"]);
         const add = splitCsv(opts["add"]);
         if ((set === undefined) === (add === undefined)) {
-            process.stderr.write("error: pass exactly one of --set or --add\n");
-            process.exitCode = ExitCode.Usage;
+            usageError(opts, "pass exactly one of --set or --add");
             return;
         }
         await runWrite(opts, (c) => set !== undefined
-            ? c.write.setTags(uuid, set, writeOptionsFrom(opts))
-            : c.write.addTags(uuid, add ?? [], writeOptionsFrom(opts)));
+            ? c.write.setTags(uuid, set, writeOptionsFrom(opts, createTagsExtra(opts)))
+            : c.write.addTags(uuid, add ?? [], writeOptionsFrom(opts, createTagsExtra(opts))));
     });
     addWriteFlags(todo
         .command("checklist <uuid>")
@@ -401,36 +431,30 @@ export function registerWriteCommands(program) {
         .option("--to-position <n>", "1-based position for --move-item")).action(async (uuid, opts) => {
         const granular = ["add", "remove", "check", "uncheck", "rename", "moveItem"].filter((k) => opts[k] !== undefined);
         if (granular.length > 1) {
-            process.stderr.write("error: pass at most ONE granular checklist action per call\n");
-            process.exitCode = ExitCode.Usage;
+            usageError(opts, "pass at most ONE granular checklist action per call");
             return;
         }
         const action = granular[0];
         if (action !== undefined) {
             if (opts["item"].length > 0) {
-                process.stderr.write("error: --item (wholesale) is exclusive with granular actions\n");
-                process.exitCode = ExitCode.Usage;
+                usageError(opts, "--item (wholesale) is exclusive with granular actions");
                 return;
             }
             if (action === "rename" && opts["to"] === undefined) {
-                process.stderr.write("error: --rename requires --to <title>\n");
-                process.exitCode = ExitCode.Usage;
+                usageError(opts, "--rename requires --to <title>");
                 return;
             }
             if (action === "moveItem" && opts["toPosition"] === undefined) {
-                process.stderr.write("error: --move-item requires --to-position <n>\n");
-                process.exitCode = ExitCode.Usage;
+                usageError(opts, "--move-item requires --to-position <n>");
                 return;
             }
             // Target: --index (1-based) OR the action flag's title value. When a
             // targeting flag is present without a value commander yields `true`.
-            const flagVal = (v) => (typeof v === "string" ? v : undefined);
             const target = opts["index"] !== undefined
                 ? { index: Number(opts["index"]) }
                 : { item: flagVal(opts[action]) ?? "" };
             if (action !== "add" && opts["index"] === undefined && target.item === "") {
-                process.stderr.write(`error: --${action} needs a title, or use --index <n>\n`);
-                process.exitCode = ExitCode.Usage;
+                usageError(opts, `--${action} needs a title, or use --index <n>`);
                 return;
             }
             const edit = action === "add"
@@ -509,6 +533,64 @@ export function registerWriteCommands(program) {
             ...(opts["notes"] !== undefined && { notes: opts["notes"] }),
         }, writeOptionsFrom(opts)));
     });
+    // --- ui vector: GUI-driven transforms (two-key gated) --------------------
+    const REPEAT_FREQ_HELP = "daily | weekly | monthly | yearly";
+    const REPEAT_INTERVAL_HELP = "every N units (1–99)";
+    for (const [verb, op, desc] of [
+        [
+            "make-repeating",
+            "todo.make-repeating",
+            "Turn a plain to-do into a repeating one. This REPLACES the to-do with a new repeating " +
+                "series — the original disappears and a fresh recurring item takes its place " +
+                "(cannot be undone). Set the frequency and interval, and optionally the weekday set, " +
+                "monthly/yearly day, end bound, reminders, or deadline.",
+        ],
+        [
+            "reschedule-repeat",
+            "todo.reschedule-repeat",
+            "Change an existing repeating to-do's rule in place (the item keeps its identity). Set the " +
+                "frequency and interval, and optionally the weekday set, monthly/yearly day, end bound, " +
+                "reminders, or deadline. `things undo` restores the previous rule.",
+        ],
+    ]) {
+        addDriveGuiFlag(addRepeatRuleFlags(addWriteFlags(todo
+            .command(`${verb} <uuid>`)
+            .description(desc)
+            .requiredOption("--frequency <freq>", REPEAT_FREQ_HELP)
+            .requiredOption("--interval <n>", REPEAT_INTERVAL_HELP)))).action(async (uuid, opts) => {
+            const frequency = opts["frequency"];
+            await runWrite(opts, (c) => c.write.run(op, {
+                uuid,
+                frequency,
+                interval: Number(opts["interval"]),
+                ...repeatRuleFlagsFromOpts(opts, frequency),
+            }, writeOptionsFrom(opts)));
+        });
+    }
+    for (const [verb, op, desc] of [
+        [
+            "pause-repeat",
+            "todo.pause-repeat",
+            "Pause a repeating to-do: it stops spawning new occurrences but keeps its rule. Reversible " +
+                "with `things todo resume-repeat`.",
+        ],
+        [
+            "resume-repeat",
+            "todo.resume-repeat",
+            "Resume a paused repeating to-do: it starts spawning occurrences again.",
+        ],
+        [
+            "convert-to-project",
+            "todo.convert-to-project",
+            "Convert a to-do into a project. This REPLACES the to-do with a new project (its notes are " +
+                "kept); the to-do's identity is gone and it cannot be undone. The new project's uuid is " +
+                "printed on success.",
+        ],
+    ]) {
+        addDriveGuiFlag(addWriteFlags(todo.command(`${verb} <uuid>`).description(desc))).action(async (uuid, opts) => {
+            await runWrite(opts, (c) => c.write.run(op, { uuid }, writeOptionsFrom(opts)));
+        });
+    }
     const heading = group(program, "heading", "Heading-scoped operations");
     addWriteFlags(heading
         .command("add <project> <title>")
@@ -556,7 +638,90 @@ export function registerWriteCommands(program) {
             return outcome.heading;
         });
     });
+    addDriveGuiFlag(addWriteFlags(heading
+        .command("convert-to-project <uuid>")
+        .description("Convert a heading into a project. This REPLACES the heading with a new project — it " +
+        "is promoted alongside its parent project (into the same area) and the heading's " +
+        "to-dos move under the new project. The heading's identity is gone and it cannot be " +
+        "undone. The new project's uuid is printed on success."))).action(async (uuid, opts) => {
+        await runWrite(opts, (c) => c.write.run("heading.convert-to-project", { uuid }, writeOptionsFrom(opts)));
+    });
     const project = group(program, "project", "Project-scoped operations");
+    // --- ui vector: repeating-project transforms (two-key gated) -------------
+    addDriveGuiFlag(addRepeatRuleFlags(addWriteFlags(project
+        .command("reschedule-repeat <ref>")
+        .description("Change an existing repeating project's rule in place (target by uuid or unique name; " +
+        "the project keeps its identity). " +
+        "Set the frequency and interval, and optionally the weekday set, monthly/yearly day, " +
+        "end bound, reminders, or deadline. `things undo` restores the previous rule.")
+        .requiredOption("--frequency <freq>", REPEAT_FREQ_HELP)
+        .requiredOption("--interval <n>", REPEAT_INTERVAL_HELP)))).action(async (uuid, opts) => {
+        const frequency = opts["frequency"];
+        await runWrite(opts, (c) => c.write.run("project.reschedule-repeat", {
+            uuid,
+            frequency,
+            interval: Number(opts["interval"]),
+            ...repeatRuleFlagsFromOpts(opts, frequency),
+        }, writeOptionsFrom(opts)));
+    });
+    for (const [verb, op, desc] of [
+        [
+            "pause-repeat",
+            "project.pause-repeat",
+            "Pause a repeating project: it stops spawning new occurrences but keeps its rule. Reversible " +
+                "with `things project resume-repeat`.",
+        ],
+        [
+            "resume-repeat",
+            "project.resume-repeat",
+            "Resume a paused repeating project: it starts spawning occurrences again.",
+        ],
+    ]) {
+        addDriveGuiFlag(addWriteFlags(project.command(`${verb} <ref>`).description(desc))).action(async (uuid, opts) => {
+            await runWrite(opts, (c) => c.write.run(op, { uuid }, writeOptionsFrom(opts)));
+        });
+    }
+    addDriveGuiFlag(addRepeatRuleFlags(addWriteFlags(project
+        .command("make-repeating <ref>")
+        .description("Turn a project into a repeating one. This REPLACES the project with a new repeating " +
+        "series — the original disappears and a fresh recurring project takes its place (its " +
+        "area is kept; cannot be undone). An Anytime project with no area is moved to Someday " +
+        "first (a cleanup-free intermediate step, shown in --dry-run). Set the frequency and " +
+        "interval, and optionally the weekday set, monthly/yearly day, end bound, reminders, " +
+        "or deadline.")
+        .requiredOption("--frequency <freq>", REPEAT_FREQ_HELP)
+        .requiredOption("--interval <n>", REPEAT_INTERVAL_HELP)))).action(async (uuid, opts) => {
+        const frequency = opts["frequency"];
+        await runWrite(opts, (c) => c.write.makeRepeatingProject(uuid, {
+            frequency,
+            interval: Number(opts["interval"]),
+            ...repeatRuleFlagsFromOpts(opts, frequency),
+        }, writeOptionsFrom(opts)));
+    });
+    addDriveGuiFlag(addWriteFlags(project
+        .command("create-repeating <title>")
+        .description("Create a project and turn it into a repeating series in ONE call. Two operations: the " +
+        "project is created first and PERSISTS even if the make-repeating step refuses; then it " +
+        "is promoted (which drives the GUI). Give --area to place it, or omit it to create in " +
+        "Someday. The new repeating project's uuid is printed on success.")
+        .option("--notes <text>", "notes body")
+        .option("--area <ref>", "destination area (uuid or unique name)")
+        .option("--deadline <date>", "YYYY-MM-DD")
+        .option("--todo <title>", "initial child to-do (repeatable)", collect, [])
+        .requiredOption("--frequency <freq>", REPEAT_FREQ_HELP)
+        .requiredOption("--interval <n>", REPEAT_INTERVAL_HELP))).action(async (title, opts) => {
+        const todos = opts["todo"];
+        const area = containerRef(opts["area"]);
+        await runWrite(opts, (c) => c.write.createRepeatingProject({
+            title,
+            ...(opts["notes"] !== undefined && { notes: opts["notes"] }),
+            ...(area !== undefined && { area }),
+            ...(opts["deadline"] !== undefined && { deadline: opts["deadline"] }),
+            ...(todos.length > 0 && { todos }),
+            frequency: opts["frequency"],
+            interval: Number(opts["interval"]),
+        }, writeOptionsFrom(opts)));
+    });
     addWriteFlags(project
         .command("add <title>")
         .description("Create a project; its uuid is printed on success.")
@@ -577,11 +742,12 @@ export function registerWriteCommands(program) {
         }, writeOptionsFrom(opts)));
     });
     addWriteFlags(project
-        .command("update <uuid>")
-        .description("Update a project's title/notes/when/deadline/reminder. --append-notes/" +
-        "--prepend-notes join with a newline (exclusive with --notes). --reminder needs " +
-        "--when today|evening|YYYY-MM-DD; when re-scheduling WITHOUT --reminder an existing " +
-        "reminder is auto-preserved."))
+        .command("update <ref>")
+        .description("Update a project's title/notes/when/deadline/reminder. Target by uuid or unique " +
+        "name — a duplicated project name is refused, listing the candidates to pick from " +
+        "by uuid. --append-notes/--prepend-notes join with a newline (exclusive with " +
+        "--notes). --reminder needs --when today|evening|YYYY-MM-DD; when re-scheduling " +
+        "WITHOUT --reminder an existing reminder is auto-preserved."))
         .option("--title <text>", "new title")
         .option("--notes <text>", "replace notes")
         .option("--append-notes <text>", "append to existing notes (newline-joined)")
@@ -594,13 +760,11 @@ export function registerWriteCommands(program) {
         .action(async (uuid, opts) => {
         const notesModes = ["notes", "appendNotes", "prependNotes"].filter((k) => opts[k] !== undefined);
         if (notesModes.length > 1) {
-            process.stderr.write("error: --notes, --append-notes, --prepend-notes are exclusive\n");
-            process.exitCode = ExitCode.Usage;
+            usageError(opts, "--notes, --append-notes, --prepend-notes are exclusive");
             return;
         }
         if (opts["reminder"] !== undefined && opts["clearReminder"] === true) {
-            process.stderr.write("error: pass at most one of --reminder / --clear-reminder\n");
-            process.exitCode = ExitCode.Usage;
+            usageError(opts, "pass at most one of --reminder / --clear-reminder");
             return;
         }
         if (!whenSugarOk(opts))
@@ -621,33 +785,33 @@ export function registerWriteCommands(program) {
             ...(opts["clearDeadline"] === true && { deadline: null }),
         }, writeOptionsFrom(opts)));
     });
-    addWriteFlags(project
-        .command("tags <uuid>")
-        .description("Set or extend a project's tags. --set REPLACES the full tag set (an empty value " +
-        "clears all tags); --add merges with the current tags. Tags must name existing " +
-        "tags — unknown tags are rejected.")
-        .option("--set <list>", "comma-separated tag names: full replacement")
-        .option("--add <list>", "comma-separated tag names: merge with existing")).action(async (uuid, opts) => {
+    addCreateTagsFlag(addWriteFlags(project
+        .command("tags <ref>")
+        .description("Set or extend a project's tags (target by uuid or unique name). --set REPLACES the " +
+        "full tag set (an empty value clears all tags); --add merges with the current tags. " +
+        "Each tag may be a name or a parent/child path, and must exist unless " +
+        "--create-tags.")
+        .option("--set <list>", "comma-separated tags: full replacement")
+        .option("--add <list>", "comma-separated tags: merge with existing"))).action(async (uuid, opts) => {
         const set = splitCsv(opts["set"]);
         const add = splitCsv(opts["add"]);
         if ((set === undefined) === (add === undefined)) {
-            process.stderr.write("error: pass exactly one of --set or --add\n");
-            process.exitCode = ExitCode.Usage;
+            usageError(opts, "pass exactly one of --set or --add");
             return;
         }
         await runWrite(opts, (c) => set !== undefined
-            ? c.write.setProjectTags(uuid, set, writeOptionsFrom(opts))
-            : c.write.addProjectTags(uuid, add ?? [], writeOptionsFrom(opts)));
+            ? c.write.setProjectTags(uuid, set, writeOptionsFrom(opts, createTagsExtra(opts)))
+            : c.write.addProjectTags(uuid, add ?? [], writeOptionsFrom(opts, createTagsExtra(opts))));
     });
     addWriteFlags(project
-        .command("move <uuid>")
-        .description("Move a project to another area, or DETACH it from its current area (--detach). " +
-        "Status and schedule are untouched. Unknown areas are rejected.")
+        .command("move <ref>")
+        .description("Move a project (target by uuid or unique name) to another area, or DETACH it from " +
+        "its current area (--detach). Status and schedule are untouched. Unknown areas are " +
+        "rejected.")
         .option("--area <ref>", "destination area (uuid or unique name)")
         .option("--detach", "remove the current area assignment (exclusive with --area)")).action(async (uuid, opts) => {
         if ((opts.detach === true) === (opts.area !== undefined)) {
-            process.stderr.write("error: pass exactly one of --area / --detach\n");
-            process.exitCode = ExitCode.Usage;
+            usageError(opts, "pass exactly one of --area / --detach");
             return;
         }
         await runWrite(opts, (c) => opts.detach === true
@@ -655,15 +819,17 @@ export function registerWriteCommands(program) {
             : c.write.moveProject(uuid, { uuid: opts.area, title: opts.area }, writeOptionsFrom(opts)));
     });
     addWriteFlags(project
-        .command("cancel <uuid>")
-        .description("Cancel a project. Canceling also cancels its open to-dos, so an explicit " +
-        "--children policy is required; already-completed children are never altered.")
+        .command("cancel <ref>")
+        .description("Cancel a project (target by uuid or unique name). Canceling also cancels its open " +
+        "to-dos, so an explicit --children policy is required; already-completed children " +
+        "are never altered.")
         .requiredOption("--children <policy>", "require-resolved (error if open to-dos remain) | auto-cancel (cancel them too)")).action(async (uuid, opts) => {
         await runWrite(opts, (c) => c.write.cancelProject(uuid, { children: opts.children }, writeOptionsFrom(opts)));
     });
     addWriteFlags(project
-        .command("reopen <uuid>")
-        .description("Reopen a completed/canceled project. Its children stay completed/canceled unless " +
+        .command("reopen <ref>")
+        .description("Reopen a completed/canceled project (target by uuid or unique name). Its children " +
+        "stay completed/canceled unless " +
         "--restore-children also reopens the ones that were resolved together with the " +
         "project — children resolved earlier are never touched. Exit 3 if any child " +
         "restore fails.")
@@ -708,57 +874,87 @@ export function registerWriteCommands(program) {
         }
     });
     addWriteFlags(project
-        .command("restore <uuid>")
-        .description("Restore a TRASHED project IN PLACE: schedule, area, and children all keep their " +
-        "state. Only trashed projects qualify.")).action(async (uuid, opts) => {
+        .command("restore <ref>")
+        .description("Restore a TRASHED project IN PLACE (target by uuid or unique name): schedule, area, " +
+        "and children all keep their state. Only trashed projects qualify.")).action(async (uuid, opts) => {
         await runWrite(opts, (c) => c.write.restoreProject(uuid, writeOptionsFrom(opts)));
     });
     addWriteFlags(project
-        .command("duplicate <uuid>")
-        .description("Duplicate a project INCLUDING its children; the copy's uuid is printed on " +
-        "success. Not available for repeating projects.")).action(async (uuid, opts) => {
+        .command("duplicate <ref>")
+        .description("Duplicate a project (target by uuid or unique name) INCLUDING its children; the " +
+        "copy's uuid is printed on success. Not available for repeating projects.")).action(async (uuid, opts) => {
         await runWrite(opts, (c) => c.write.duplicateProject(uuid, writeOptionsFrom(opts)));
     });
     addWriteFlags(project
-        .command("complete <uuid>")
-        .description("Complete a project. Completing also completes its open to-dos, so an explicit " +
-        "--children policy is required.")
+        .command("complete <ref>")
+        .description("Complete a project (target by uuid or unique name). Completing also completes its " +
+        "open to-dos, so an explicit --children policy is required.")
         .requiredOption("--children <policy>", "require-resolved (error if open to-dos remain) | auto-complete (complete them too)")).action(async (uuid, opts) => {
         await runWrite(opts, (c) => c.write.completeProject(uuid, { children: opts.children }, writeOptionsFrom(opts)));
     });
     addWriteFlags(project
-        .command("delete <uuid>")
-        .description("Move a project to the Trash; its children go with it (recover with `things " +
-        "project restore`).")).action(async (uuid, opts) => {
+        .command("delete <ref>")
+        .description("Move a project (target by uuid or unique name) to the Trash; its children go with " +
+        "it (recover with `things project restore`).")).action(async (uuid, opts) => {
         await runWrite(opts, (c) => c.write.deleteProject(uuid, writeOptionsFrom(opts)));
     });
     const area = group(program, "area", "Area-scoped operations");
-    addWriteFlags(area
+    addCreateTagsFlag(addWriteFlags(area
         .command("add <title>")
-        .description("Create an area, optionally tagged with EXISTING tags.")
-        .option("--tags <list>", "comma-separated existing tag names")).action(async (title, opts) => {
+        .description("Create an area, optionally tagged. Each tag may be a name or a " +
+        "parent/child path, and must exist unless --create-tags.")
+        .option("--tags <list>", "comma-separated tags; each a name or a parent/child path (must exist unless --create-tags)"))).action(async (title, opts) => {
         const tags = splitCsv(opts["tags"]);
-        await runWrite(opts, (c) => c.write.addArea({ title, ...(tags !== undefined && { tags }) }, writeOptionsFrom(opts)));
+        await runWrite(opts, (c) => c.write.addArea({ title, ...(tags !== undefined && { tags }) }, writeOptionsFrom(opts, createTagsExtra(opts))));
     });
-    addWriteFlags(area
-        .command("update <target>")
-        .description("Rename an area and/or replace its tags (the full set; tags must name existing " +
-        "tags). Target by uuid or unique name.")
+    addCreateTagsFlag(addWriteFlags(area
+        .command("update <ref>")
+        .description("Rename an area and/or replace its tags (the full set). Each tag may be a name " +
+        "or a parent/child path, and must exist unless --create-tags. Target by " +
+        "uuid or unique name.")
         .option("--title <text>", "new name")
-        .option("--tags <list>", 'comma-separated EXISTING tag names (full replacement; "" clears all)')).action(async (target, opts) => {
+        .option("--tags <list>", 'comma-separated tags (full replacement; "" clears all); each a name or a parent/child path'))).action(async (target, opts) => {
         const tags = splitCsv(opts["tags"]);
         if (opts["title"] === undefined && tags === undefined) {
-            process.stderr.write("error: pass --title and/or --tags\n");
-            process.exitCode = ExitCode.Usage;
+            usageError(opts, "pass --title and/or --tags");
             return;
         }
         await runWrite(opts, (c) => c.write.updateArea(target, {
             ...(opts["title"] !== undefined && { title: opts["title"] }),
             ...(tags !== undefined && { tags }),
+        }, writeOptionsFrom(opts, createTagsExtra(opts))));
+    });
+    addDriveGuiFlag(addWriteFlags(area
+        .command("reorder <ref>")
+        .description("Move an area to a new position in the area order (target by uuid or unique name). " +
+        "Pass exactly one destination: --before/--after another area, or --first/--last. " +
+        "This drives the Things window with the pointer — the app comes to the front and " +
+        "the sidebar may scroll while the area is moved; the area's projects and to-dos " +
+        "are untouched.")
+        .option("--before <area>", "place it immediately above this area (uuid or unique name)")
+        .option("--after <area>", "place it immediately below this area (uuid or unique name)")
+        .option("--first", "move it to the top of the area list")
+        .option("--last", "move it to the bottom of the area list"))).action(async (target, opts) => {
+        const chosen = [
+            opts["before"] !== undefined,
+            opts["after"] !== undefined,
+            opts["first"] === true,
+            opts["last"] === true,
+        ].filter(Boolean).length;
+        if (chosen !== 1) {
+            usageError(opts, "pass exactly one of --before / --after / --first / --last");
+            return;
+        }
+        await runWrite(opts, (c) => c.write.run("area.reorder", {
+            target,
+            ...(opts["before"] !== undefined && { before: opts["before"] }),
+            ...(opts["after"] !== undefined && { after: opts["after"] }),
+            ...(opts["first"] === true && { position: "first" }),
+            ...(opts["last"] === true && { position: "last" }),
         }, writeOptionsFrom(opts)));
     });
     addWriteFlags(area
-        .command("delete <target>")
+        .command("delete <ref>")
         .description("Delete an area PERMANENTLY — areas do not go to the Trash, so this cannot be " +
         "undone; requires --dangerously-permanent. The area's to-dos move to the Trash; " +
         "its projects remain, no longer assigned to any area.")
@@ -777,7 +973,7 @@ export function registerWriteCommands(program) {
         await runWrite(opts, (c) => c.write.addTag({ title: name, ...(opts["parent"] !== undefined && { parent: opts["parent"] }) }, writeOptionsFrom(opts)));
     });
     addWriteFlags(tag
-        .command("update <target>")
+        .command("update <ref>")
         .description("Rename a tag (existing assignments follow the rename), nest it under an existing " +
         "tag, UN-NEST it to the root (--unnest; exclusive with --parent), and set or clear " +
         "its keyboard shortcut (--shortcut / --clear-shortcut, exclusive).")
@@ -791,18 +987,15 @@ export function registerWriteCommands(program) {
             opts["unnest"] === undefined &&
             opts["shortcut"] === undefined &&
             opts["clearShortcut"] === undefined) {
-            process.stderr.write("error: pass --title, --parent, --unnest, --shortcut, and/or --clear-shortcut\n");
-            process.exitCode = ExitCode.Usage;
+            usageError(opts, "pass --title, --parent, --unnest, --shortcut, and/or --clear-shortcut");
             return;
         }
         if (opts["parent"] !== undefined && opts["unnest"] === true) {
-            process.stderr.write("error: --parent and --unnest are exclusive\n");
-            process.exitCode = ExitCode.Usage;
+            usageError(opts, "--parent and --unnest are exclusive");
             return;
         }
         if (opts["shortcut"] !== undefined && opts["clearShortcut"] === true) {
-            process.stderr.write("error: --shortcut and --clear-shortcut are exclusive\n");
-            process.exitCode = ExitCode.Usage;
+            usageError(opts, "--shortcut and --clear-shortcut are exclusive");
             return;
         }
         await runWrite(opts, (c) => c.write.updateTag(target, {
@@ -814,7 +1007,7 @@ export function registerWriteCommands(program) {
         }, writeOptionsFrom(opts)));
     });
     addWriteFlags(tag
-        .command("delete <target>")
+        .command("delete <ref>")
         .description("Delete a tag PERMANENTLY — tags do not go to the Trash, so this cannot be " +
         "undone; requires --dangerously-permanent. The tag is removed from every item, " +
         "and ALL of its nested child tags are deleted with it — requires " +
@@ -852,8 +1045,8 @@ export function registerWriteCommands(program) {
         "options carry the confirmation flags (acknowledgeChecklistReset, " +
         "acknowledgeProjectReopen, dangerouslyPermanent, acknowledgeTagSubtree). " +
         "--dry-run plans everything without executing; --fail-fast skips the rest after " +
-        "the first failure. Exit: 0 all ok · 3 any verify-failed/invalid · 4 any blocked " +
-        "· 5 any drift-blocked.")
+        "the first failure. Exit (worst failure wins): 0 all ok · 3 any verify-failed/invalid " +
+        "· 4 any blocked · 5 any drift-blocked · 6 any unsupported.")
         .option("--dry-run", "plan every op; execute nothing")
         .option("--fail-fast", "skip remaining ops after the first failure")
         .option("--json", "JSONL results + summary on stdout (also the default)")
@@ -894,9 +1087,6 @@ export function registerWriteCommands(program) {
         let client = null;
         try {
             client = openThings(opts.db ? { dbPath: opts.db } : {});
-            const emit = (r) => {
-                process.stdout.write(`${JSON.stringify(r)}\n`);
-            };
             const results = await client.write.batch(ops, {
                 ...(opts.dryRun !== undefined && { dryRun: opts.dryRun }),
                 ...(opts["failFast"] === true && { failFast: true }),
@@ -916,15 +1106,9 @@ export function registerWriteCommands(program) {
                 },
             };
             process.stdout.write(`${JSON.stringify(summary)}\n`);
-            const kinds = new Set(failed.map((r) => r.outcome.kind));
-            const reasons = new Set(failed.map((r) => (r.outcome.kind === "blocked" ? r.outcome.reason : "")));
-            process.exitCode = reasons.has("drift")
-                ? ExitCode.DriftBlocked
-                : kinds.has("blocked")
-                    ? ExitCode.Blocked
-                    : failed.length > 0
-                        ? ExitCode.VerifyFailed
-                        : ExitCode.Ok;
+            // Worst failure decides the exit code, by the stable precedence
+            // drift > blocked > unsupported > verify-failed (see aggregateExitCode).
+            process.exitCode = aggregateExitCode(failed.map((r) => r.outcome));
         }
         finally {
             client?.close();
@@ -934,28 +1118,54 @@ export function registerWriteCommands(program) {
         .command("undo")
         .description("Undo the last N changes made through things-api, newest first — each undo applies " +
         "the INVERSE change (recorded as actor `undo:<actor>`, never itself an undo " +
-        "target). Changes made directly in the Things app cannot be undone here. " +
-        "IRREVERSIBLE changes are reported, not guessed: permanent deletes and changes " +
-        "whose prior state is unknown. Partial restores carry notes (e.g. a delete-undo " +
-        "lands in the Inbox de-scheduled). --dry-run shows every inverse plan without " +
-        "executing. Undoing a CREATED area/tag deletes it permanently — requires " +
-        "--dangerously-permanent. Unwinding stops at the first failed inverse. " +
-        "Exit: 0 all ok · 3 any failed/partial · 0 with per-item detail otherwise.")
-        .option("--last <n>", "how many trailing mutations to undo", "1")
+        "target). By default undo is GLOBAL — the owner's Cmd+Z — reversing the latest " +
+        "changes whoever made them; narrow it with --by <actor> to undo only a given " +
+        "author's changes (e.g. `--by mcp` to clean up after an agent), or --txn <token> " +
+        "to undo one exact change by the `undoToken` its result returned (immune to any " +
+        "changes made in between). Changes made directly in the Things app cannot be " +
+        "undone here. IRREVERSIBLE changes are reported, not guessed: permanent deletes " +
+        "and changes whose prior state is unknown. Partial restores carry notes (e.g. a " +
+        "delete-undo lands in the Inbox de-scheduled). --dry-run shows every inverse plan " +
+        "without executing. Undoing a CREATED area/tag deletes it permanently — requires " +
+        "--dangerously-permanent. An undo is refused when the item changed outside things-api " +
+        "since (its list/project, status, schedule, trashed state, or a field like the title " +
+        "moved) — pass --acknowledge-out-of-band-changes to overwrite it anyway. Unwinding " +
+        "stops at the first failed inverse. " +
+        "Exit: 0 all ok · 3 any failed/partial · 2 nothing matched or bad flags.")
+        .option("--last <n>", "how many trailing mutations to undo (default 1)")
+        .option("--by <actor>", "undo only changes recorded under this author — an exact actor name (`mike`, `mcp`) " +
+        "or `*` for all; matches exactly, so `--by mcp` never touches an `undo:mcp` " +
+        "record. This SELECTS which changes to undo; --actor names who the undo is " +
+        "recorded as. Not combinable with --txn.")
+        .option("--txn <token>", "undo exactly the one change with this undo token (the `undoToken` field from its " +
+        "result); immune to interleaving. Not combinable with --last/--by.")
         .option("--dry-run", "show the inverse plans; execute nothing")
         .option("--dangerously-permanent", "allow inverses that delete areas/tags permanently")
+        .option("--acknowledge-out-of-band-changes", "proceed even when the item changed outside things-api since (in the Things app or by " +
+        "another tool) — overwrites whatever the out-of-band change left")
         .option("--json", "JSONL per-item results + summary on stdout (also the default)")
         .option("--db <path>", "explicit database path")
         .option("--verify-timeout <ms>", "how long to wait for each inverse change to take effect")
-        .option("--actor <name>", "author name recorded for the undo (as undo:<name>)")
+        .option("--actor <name>", "author name RECORDED for the undo (as undo:<name>); see --by")
         .action(async (opts) => {
+        // --txn selects one exact record; --last/--by select a set. Mixing them
+        // is a usage error (house style).
+        if (opts["txn"] !== undefined && (opts["last"] !== undefined || opts["by"] !== undefined)) {
+            usageError(opts, "--txn cannot be combined with --last or --by");
+            return;
+        }
         let client = null;
         try {
             client = openThings(opts.db ? { dbPath: opts.db } : {});
             const items = await client.write.undo({
-                last: Number(opts["last"] ?? 1),
+                ...(opts["last"] !== undefined && { last: Number(opts["last"]) }),
+                ...(opts["by"] !== undefined && { by: String(opts["by"]) }),
+                ...(opts["txn"] !== undefined && { txn: String(opts["txn"]) }),
                 ...(opts.dryRun !== undefined && { dryRun: opts.dryRun }),
                 ...(opts["dangerouslyPermanent"] === true && { dangerouslyPermanent: true }),
+                ...(opts["acknowledgeOutOfBandChanges"] === true && {
+                    acknowledgeOutOfBandChanges: true,
+                }),
                 ...(opts.verifyTimeout !== undefined && {
                     verifyTimeoutMs: Number(opts.verifyTimeout),
                 }),
@@ -980,7 +1190,22 @@ export function registerWriteCommands(program) {
                         ? ExitCode.Usage
                         : ExitCode.Ok;
             if (items.length === 0) {
-                process.stderr.write("error: no undoable mutations found in the audit trail\n");
+                // The JSONL summary line (targets: 0) already conveys this as data on
+                // stdout; the prose note is a human-only affordance on stderr.
+                if (opts.json !== true) {
+                    const scope = opts["by"] !== undefined ? ` for actor ${String(opts["by"])}` : "";
+                    process.stderr.write(`error: no undoable mutations found in the audit trail${scope}\n`);
+                }
+            }
+        }
+        catch (err) {
+            // runUndo throws RangeError for a --txn token that names no undoable
+            // mutation or one already undone — a usage error (exit 2).
+            if (err instanceof RangeError) {
+                usageError(opts, err.message);
+            }
+            else {
+                throw err;
             }
         }
         finally {
@@ -1034,6 +1259,10 @@ export function registerWriteCommands(program) {
         for (const entry of data) {
             process.stdout.write(`${entry.op}\n`);
             process.stdout.write(`  undo: ${entry.undo.class}${entry.undo.ack !== undefined ? ` (ack: ${entry.undo.ack})` : ""} — ${entry.undo.note}\n`);
+            if (entry.certification !== undefined) {
+                process.stdout.write(`  certification: ${entry.certification.status}` +
+                    `${entry.certification.evidence.length > 0 ? ` (${entry.certification.evidence.join(", ")})` : ""}\n`);
+            }
             for (const v of entry.vectors) {
                 const s = v;
                 process.stdout.write(`  ${v.vector}: ${s.support}${s.disruption !== undefined ? ` (tier ${s.disruption}, ${s.validation})` : ""}${s.notes !== undefined ? ` — ${s.notes}` : ""}\n`);
@@ -1066,7 +1295,7 @@ export function registerWriteCommands(program) {
     config
         .command("set <key> <value>")
         .description("Persist a config key: profile | maxDisruption | actor | auditEnabled | " +
-        "accepted-fingerprint | allow-experimental")
+        "accepted-fingerprint | allow-experimental | ui-enabled")
         .action((key, value) => {
         const map = {
             profile: "profile",
@@ -1075,6 +1304,7 @@ export function registerWriteCommands(program) {
             auditEnabled: "auditEnabled",
             "accepted-fingerprint": "acceptedFingerprint",
             "allow-experimental": "allowExperimental",
+            "ui-enabled": "uiEnabled",
         };
         const target = map[key];
         if (target === undefined) {
@@ -1084,7 +1314,7 @@ export function registerWriteCommands(program) {
         }
         const parsed = target === "maxDisruption"
             ? Number(value)
-            : target === "auditEnabled" || target === "allowExperimental"
+            : target === "auditEnabled" || target === "allowExperimental" || target === "uiEnabled"
                 ? value === "true"
                 : value;
         saveConfigKey(target, parsed);