things-api 0.12.0 → 0.14.0

package/dist/cli/commands/writes.js

@@ -433,9 +433,15 @@ function emitMoveResult(result, opts, meta) {
                 : result.refusal === "unsupported"
                     ? ExitCode.Unsupported
                     : ExitCode.Blocked;
+            // A hoisted placement block names its hazard — surface it with the canonical
+            // `blocked:<hazard>` code + `BLOCKED (<hazard>)` copy, exactly as a direct
+            // `things reorder` hazard block does (emitResult "blocked" case).
+            const jsonCode = result.hazard !== undefined
+                ? blockedCode({ hazard: result.hazard, reason: "hazard" })
+                : result.refusal;
             if (opts.json) {
                 process.stdout.write(`${JSON.stringify(errorEnvelope({
-                    code: result.refusal,
+                    code: jsonCode,
                     message: result.detail,
                     ...(result.remediation !== undefined && { remediation: result.remediation }),
                     ...(result.candidates !== undefined && {
@@ -444,7 +450,12 @@ function emitMoveResult(result, opts, meta) {
                 }, meta))}\n`);
             }
             else {
-                process.stderr.write(`${result.refusal === "usage" ? "error" : result.refusal.toUpperCase()}: ${result.detail}\n` +
+                const prefix = result.refusal === "usage"
+                    ? "error"
+                    : result.hazard !== undefined
+                        ? `BLOCKED (${result.hazard})`
+                        : result.refusal.toUpperCase();
+                process.stderr.write(`${prefix}: ${result.detail}\n` +
                     (result.remediation !== undefined ? `  remediation: ${result.remediation}\n` : ""));
             }
             process.exitCode = code;
@@ -540,6 +551,38 @@ function addPositionFlags(cmd) {
         .option("--before <ref>", "place the block immediately before this item (same bucket)")
         .option("--after <ref>", "place the block immediately after this item (same bucket)");
 }
+/**
+ * The universal-`reorder` anchor grammar (spec §7 ratified vocabulary):
+ * --start / --end / --before / --after. `--start`/`--end` name the block's top/
+ * bottom slot in its scope; --before/--after anchor against a sibling.
+ */
+function addReorderPositionFlags(cmd) {
+    return cmd
+        .option("--start", "place the block at the start of its scope")
+        .option("--end", "place the block at the end of its scope")
+        .option("--before <ref>", "place the block immediately before this item")
+        .option("--after <ref>", "place the block immediately after this item");
+}
+/** Build a MovePosition from the reorder --start/--end/--before/--after flags. */
+function reorderPosition(opts) {
+    const chosen = [
+        opts["start"] === true,
+        opts["end"] === true,
+        opts["before"] !== undefined,
+        opts["after"] !== undefined,
+    ].filter(Boolean).length;
+    if (chosen > 1)
+        return "conflict";
+    if (opts["start"] === true)
+        return { at: "first" };
+    if (opts["end"] === true)
+        return { at: "last" };
+    if (opts["before"] !== undefined)
+        return { before: opts["before"] };
+    if (opts["after"] !== undefined)
+        return { after: opts["after"] };
+    return undefined;
+}
 /** One TTY line for a bulk-add batch item (the human, non-JSON multi rendering). */
 function addResultLine(r) {
     const o = r.outcome;
@@ -658,6 +701,8 @@ export function registerWriteCommands(program) {
         .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("--created-at <iso>", "born with this creation timestamp (ISO date or datetime; a date is noon in the effective zone)")
+        .option("--completed-at <iso>", "born completed (in the Logbook) with this completion timestamp (ISO date or datetime); drop --when/--reminder")
         .option("--acknowledge-project-reopen", "allow adding into a completed/canceled project")
         .option("--stdin", "read newline-delimited titles from stdin (blank lines skipped); exclusive with title arguments")
         .option("--id-only", "print only the new uuid(s), one per line in creation order, and nothing else (exclusive with --json)"))).action(async (titles, opts) => {
@@ -695,6 +740,8 @@ export function registerWriteCommands(program) {
             ...(project !== undefined && { project }),
             ...(area !== undefined && { area }),
             ...(opts["heading"] !== undefined && { heading: opts["heading"] }),
+            ...(opts["createdAt"] !== undefined && { createdAt: opts["createdAt"] }),
+            ...(opts["completedAt"] !== undefined && { completedAt: opts["completedAt"] }),
         });
         const ackReopen = opts["acknowledgeProjectReopen"] !== undefined
             ? { acknowledgeProjectReopen: opts["acknowledgeProjectReopen"] }
@@ -772,7 +819,9 @@ export function registerWriteCommands(program) {
         .option("--reminder <HH:mm>", "set a reminder (24h); requires --when today|evening|date")
         .option("--clear-reminder", "clear the reminder (works while scheduled today|evening)")
         .option("--deadline <date>", "YYYY-MM-DD")
-        .option("--clear-deadline", "remove the deadline")).action(async (uuid, opts) => {
+        .option("--clear-deadline", "remove the deadline")
+        .option("--created-at <iso>", "rewrite the creation timestamp (ISO date or datetime; a date is noon in the effective zone); status-safe")
+        .option("--completed-at <iso>", "rewrite the completion timestamp of an already-resolved to-do (a canceled one stays canceled); open to-dos are refused — use complete/cancel")).action(async (uuid, opts) => {
         const notesModes = ["notes", "appendNotes", "prependNotes"].filter((k) => opts[k] !== undefined);
         if (notesModes.length > 1) {
             usageError(opts, "--notes, --append-notes, --prepend-notes are exclusive");
@@ -796,19 +845,30 @@ export function registerWriteCommands(program) {
             ...(opts["clearReminder"] === true && { reminder: null }),
             ...(opts["deadline"] !== undefined && { deadline: opts["deadline"] }),
             ...(opts["clearDeadline"] === true && { deadline: null }),
+            ...(opts["createdAt"] !== undefined && { createdAt: opts["createdAt"] }),
+            ...(opts["completedAt"] !== undefined && { completedAt: opts["completedAt"] }),
         }, writeOptionsFrom(opts)));
     });
-    for (const [verb, method] of [
-        ["complete", "completeTodo"],
-        ["cancel", "cancelTodo"],
-        ["reopen", "reopenTodo"],
-    ]) {
+    for (const verb of ["complete", "cancel"]) {
+        const method = verb === "complete" ? "completeTodo" : "cancelTodo";
+        const stampNote = verb === "complete"
+            ? "resolving it first if needed, then backdating"
+            : "keeping it canceled via the certified flip legs";
         addWriteFlags(todo
             .command(`${verb} <uuid>`)
-            .description(`${verb[0]?.toUpperCase()}${verb.slice(1)} a to-do. Not available for repeating to-dos.`)).action(async (uuid, opts) => {
-            await runWrite(opts, (c) => c.write[method](uuid, writeOptionsFrom(opts)));
+            .description(`${verb[0]?.toUpperCase()}${verb.slice(1)} a to-do. Not available for repeating to-dos. ` +
+            '--completed-at sets the completion timestamp (also the "Completed on" stamp for a canceled ' +
+            `item), ${stampNote} — a multi-leg sequence, disclosed in the result and --dry-run.`)
+            .option("--completed-at <iso>", "completion timestamp (ISO date or datetime; a date is noon in the effective zone)")).action(async (uuid, opts) => {
+            const resolution = opts["completedAt"] !== undefined ? { completedAt: opts["completedAt"] } : {};
+            await runWrite(opts, (c) => c.write[method](uuid, resolution, writeOptionsFrom(opts)));
         });
     }
+    addWriteFlags(todo
+        .command("reopen <uuid>")
+        .description("Reopen a to-do. Not available for repeating to-dos.")).action(async (uuid, opts) => {
+        await runWrite(opts, (c) => c.write.reopenTodo(uuid, writeOptionsFrom(opts)));
+    });
     addPositionFlags(addWriteFlags(todo
         .command("move <refs...>")
         .description("Move one or more to-dos as an ordered block (the argument order is the order they " +
@@ -975,35 +1035,10 @@ export function registerWriteCommands(program) {
             return;
         await runWrite(opts, (c) => c.write.clearReminder(uuid, writeOptionsFrom(opts)));
     });
-    addWriteFlags(todo
-        .command("backdate <uuid>")
-        .description("Rewrite a to-do's completion and/or creation timestamp to noon (local) on the " +
-        "given date. --completed-on requires the to-do to already be completed or " +
-        "canceled. The Logbook re-sorts to the new date.")
-        .option("--completed-on <date>", "YYYY-MM-DD — new completion date")
-        .option("--created-on <date>", "YYYY-MM-DD — new creation date")).action(async (uuid, opts) => {
-        await runWrite(opts, (c) => c.write.backdateTodo(uuid, {
-            ...(opts["completedOn"] !== undefined && {
-                completionDate: opts["completedOn"],
-            }),
-            ...(opts["createdOn"] !== undefined && { creationDate: opts["createdOn"] }),
-        }, writeOptionsFrom(opts)));
-    });
-    addWriteFlags(todo
-        .command("add-logged <title>")
-        .description("Create a to-do directly in the Logbook: completed, with the given past " +
-        "completion date (and optionally a past creation date). For importing history " +
-        "from another system.")
-        .requiredOption("--completed-on <date>", "YYYY-MM-DD — completion date (required)")
-        .option("--created-on <date>", "YYYY-MM-DD — creation date (must be <= completed-on)")
-        .option("--notes <text>", "notes body")).action(async (title, opts) => {
-        await runWrite(opts, (c) => c.write.addLoggedTodo({
-            title,
-            completionDate: opts["completedOn"],
-            ...(opts["createdOn"] !== undefined && { creationDate: opts["createdOn"] }),
-            ...(opts["notes"] !== undefined && { notes: opts["notes"] }),
-        }, writeOptionsFrom(opts)));
-    });
+    // NB: the bespoke `todo backdate` / `todo add-logged` commands were removed
+    // (plan PR A). Backdated creation and Logbook import are now `todo add
+    // --created-at/--completed-at`; rewriting an existing item's timestamps is
+    // `todo update --created-at/--completed-at` (or complete/cancel --completed-at).
     // --- 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)";
@@ -1288,7 +1323,9 @@ export function registerWriteCommands(program) {
         .option("--area <ref>", "destination area (uuid or unique name)")
         .option("--when <value>", "today | evening | anytime | someday | YYYY-MM-DD")
         .option("--deadline <date>", "YYYY-MM-DD")
-        .option("--todo <title>", "initial child to-do, repeatable (seeds the new project)", collect, [])).action(async (title, opts) => {
+        .option("--todo <title>", "initial child to-do, repeatable (seeds the new project)", collect, [])
+        .option("--created-at <iso>", "born with this creation timestamp (ISO date or datetime; a date is noon in the effective zone)")
+        .option("--completed-at <iso>", "born completed (in the Logbook) with this completion timestamp; cannot seed open child to-dos (§5b)")).action(async (title, opts) => {
         const todos = opts["todo"];
         const area = containerRef(opts["area"]);
         await runWrite(opts, (c) => c.write.addProject({
@@ -1298,6 +1335,8 @@ export function registerWriteCommands(program) {
             ...(opts["when"] !== undefined && { when: opts["when"] }),
             ...(opts["deadline"] !== undefined && { deadline: opts["deadline"] }),
             ...(todos.length > 0 && { todos }),
+            ...(opts["createdAt"] !== undefined && { createdAt: opts["createdAt"] }),
+            ...(opts["completedAt"] !== undefined && { completedAt: opts["completedAt"] }),
         }, writeOptionsFrom(opts)));
     });
     addWriteFlags(project
@@ -1316,6 +1355,8 @@ export function registerWriteCommands(program) {
         .option("--clear-reminder", "clear the reminder (works while scheduled today|evening)")
         .option("--deadline <date>", "YYYY-MM-DD")
         .option("--clear-deadline", "remove the deadline")
+        .option("--created-at <iso>", "rewrite the creation timestamp (ISO date or datetime; a date is noon in the effective zone); status-safe")
+        .option("--completed-at <iso>", "rewrite the completion timestamp of an already-resolved project (a canceled one stays canceled); open projects are refused — use complete/cancel")
         .action(async (uuid, opts) => {
         const notesModes = ["notes", "appendNotes", "prependNotes"].filter((k) => opts[k] !== undefined);
         if (notesModes.length > 1) {
@@ -1342,6 +1383,10 @@ export function registerWriteCommands(program) {
             ...(opts["clearReminder"] === true && { reminder: null }),
             ...(opts["deadline"] !== undefined && { deadline: opts["deadline"] }),
             ...(opts["clearDeadline"] === true && { deadline: null }),
+            ...(opts["createdAt"] !== undefined && { createdAt: opts["createdAt"] }),
+            ...(opts["completedAt"] !== undefined && {
+                completedAt: opts["completedAt"],
+            }),
         }, writeOptionsFrom(opts)));
     });
     addCreateTagsFlag(addWriteFlags(project
@@ -1396,9 +1441,17 @@ export function registerWriteCommands(program) {
         .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)));
+        "are never altered. --completed-at sets the completion timestamp and keeps the project " +
+        "canceled via the certified flip legs (multi-leg, disclosed); it is refused while the " +
+        "project still has open children.")
+        .requiredOption("--children <policy>", "require-resolved (error if open to-dos remain) | auto-cancel (cancel them too)")
+        .option("--completed-at <iso>", "completion timestamp (ISO date or datetime; a date is noon in the effective zone)")).action(async (uuid, opts) => {
+        await runWrite(opts, (c) => c.write.cancelProject(uuid, {
+            children: opts.children,
+            ...(opts["completedAt"] !== undefined && {
+                completedAt: opts["completedAt"],
+            }),
+        }, writeOptionsFrom(opts)));
     });
     addWriteFlags(project
         .command("reopen <ref>")
@@ -1464,9 +1517,16 @@ export function registerWriteCommands(program) {
     addWriteFlags(project
         .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)));
+        "open to-dos, so an explicit --children policy is required. --completed-at sets the " +
+        "completion timestamp and backdates it (multi-leg, disclosed).")
+        .requiredOption("--children <policy>", "require-resolved (error if open to-dos remain) | auto-complete (complete them too)")
+        .option("--completed-at <iso>", "completion timestamp (ISO date or datetime; a date is noon in the effective zone)")).action(async (uuid, opts) => {
+        await runWrite(opts, (c) => c.write.completeProject(uuid, {
+            children: opts.children,
+            ...(opts["completedAt"] !== undefined && {
+                completedAt: opts["completedAt"],
+            }),
+        }, writeOptionsFrom(opts)));
     });
     addWriteFlags(project
         .command("delete <ref>")
@@ -1806,27 +1866,30 @@ export function registerWriteCommands(program) {
             client?.close();
         }
     });
-    addPositionFlags(addWriteFlags(program
+    addReorderPositionFlags(addDriveGuiFlag(addWriteFlags(program
         .command("reorder <refs...>")
-        .description("Rearrange to-dos (and the project rows the Today/Evening/day lists intermix with " +
-        "them) IN PLACE within the container and bucket they already share — REARRANGES, " +
-        "never changes membership (to change what an item belongs to, use `things todo " +
-        "move` / `things project move`). Argument order is the resulting order; unmentioned " +
-        "siblings keep theirs. Bare (no position) assembles the named items as a block at " +
-        "the EARLIEST one's current slot (partial-selection friendly); --first/--last/" +
-        "--before/--after position the block. Operands that span containers or buckets fail " +
-        "closed. A Today/Evening member also has an index slot in its container, so a set " +
-        "sharing BOTH axes is ambiguous — pass --in to say which (the refusal names both " +
-        "spellings). Ordering uses the native re-rank where available (private surface, on " +
-        "by default) and a verified when= bounce otherwise; bounce-max-items caps a bounce, " +
-        "bounce-enabled=false refuses bounce-dependent placements rather than degrading. " +
-        "For a project's HEADINGS use `things project move-heading`; for sidebar AREAS use " +
-        "`things area reorder`.")
-        .option("--in <target>", "disambiguate the axis of a Today/Evening set: today | evening | anytime | someday | " +
-        "inbox, or a project/area/heading ref (uuid or unique title)"))).action(async (refs, opts) => {
-        const position = movePosition(opts);
+        .description("The ONE reorder verb — rearrange to-dos, projects, headings, OR sidebar areas IN " +
+        "PLACE (REARRANGES, never changes membership; to change what an item belongs to use " +
+        "`things todo move` / `things project move`). All operands must be ONE kind (only " +
+        "to-dos and projects intermix, and only on the shared Today/Evening/day axes); a " +
+        "mixed-kind set, a cross-container set, and a non-member anchor each fail closed with " +
+        "one precise message. Argument order is the resulting order; unmentioned siblings " +
+        "keep theirs. Bare (no position) assembles the named items as a block at the " +
+        "EARLIEST one's current slot; --start/--end/--before/--after position the block. A " +
+        "Today/Evening member also has an index slot in its container, so a set sharing BOTH " +
+        "axes is ambiguous — pass --in to say which. HEADINGS: same-project heading " +
+        "re-ranking runs the native heading-block wire; an archived heading is reorderable " +
+        "but repositioning it brings it back to open (disclosed). AREAS: this drives the " +
+        "local Things app (sidebar drag). `things area reorder` and `things project " +
+        "move-heading` remain as kind-specific spellings.")
+        .option("--in <target>", "to-dos/projects only — name the axis to reorder on: today | evening | anytime | " +
+        "someday | inbox, a project/area/heading ref (uuid or unique title), upcoming (the " +
+        "one future day the set shares), or a YYYY-MM-DD day-block. A stage-list or container " +
+        "axis sorts one KIND at a time; only today | evening | upcoming | a day-block " +
+        "intermix both kinds.")))).action(async (refs, opts) => {
+        const position = reorderPosition(opts);
         if (position === "conflict") {
-            usageError(opts, "pass at most one of --first/--last/--before/--after");
+            usageError(opts, "pass at most one of --start / --end / --before / --after");
             return;
         }
         const request = {
@@ -1834,7 +1897,7 @@ export function registerWriteCommands(program) {
             ...(position !== undefined && { position }),
             ...(opts["in"] !== undefined && { in: opts["in"] }),
         };
-        await runMoveCmd(opts, (c) => c.write.reorderTodos(request, writeOptionsFrom(opts)));
+        await runMoveCmd(opts, (c) => c.write.reorderAny(request, writeOptionsFrom(opts)));
     });
     program
         .command("capabilities")
@@ -1903,7 +1966,7 @@ export function registerWriteCommands(program) {
         .description("Persist a config key: profile | maxDisruption | actor | auditEnabled | " +
         "accepted-fingerprint | certified-app-version | allow-experimental | bounce-enabled | " +
         "bounce-max-items | ui-enabled | scope")
-        .action((key, value) => {
+        .action((key, value, opts) => {
         const map = {
             profile: "profile",
             maxDisruption: "maxDisruption",
@@ -1931,6 +1994,14 @@ export function registerWriteCommands(program) {
                 target === "uiEnabled"
                 ? value === "true"
                 : value;
+        // Universal `--dry-run` (../dry-run.ts): `config set` writes local config
+        // state (not the Things DB), so it honors the flag with an honest preview —
+        // the key is still validated above, but nothing is persisted. Exit 0.
+        if (opts.dryRun === true) {
+            process.stdout.write(`DRY RUN would set ${key} = ${String(parsed)} (nothing written)\n`);
+            process.exitCode = ExitCode.Ok;
+            return;
+        }
         saveConfigKey(target, parsed);
         process.stdout.write(`set ${key} = ${String(parsed)}\n`);
         // A stored scope jails EVERY process on this host — including this