things-api 0.13.0 → 0.14.0

package/dist/cli/commands/writes.js

@@ -551,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;
@@ -669,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) => {
@@ -706,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"] }
@@ -783,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");
@@ -807,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 " +
@@ -986,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)";
@@ -1299,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({
@@ -1309,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
@@ -1327,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) {
@@ -1353,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
@@ -1407,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>")
@@ -1475,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>")
@@ -1817,33 +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). A deadline-forecast set sharing one Upcoming day is dual-axis the same " +
-        "way (the day-block vs its container order); --in upcoming or --in <YYYY-MM-DD> names " +
-        "the day-block. 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>", "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 — " +
-        "a mixed to-do+project set is refused (even sharing a container); only today | evening " +
-        "| upcoming | a day-block intermix both kinds. Reorder a project's headings with " +
-        "`things project move-heading`."))).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 = {
@@ -1851,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")