things-api 0.19.3 → 0.20.0

package/dist/cli/commands/writes.js

@@ -10,7 +10,7 @@ import { readFileSync } from "node:fs";
 import { armInterrupt, disarmInterrupt } from "../interrupt.js";
 import { isDevVersion } from "../skill.js";
 import { CLI_VERSION } from "../version.js";
-import { addRepeatCalendarFlags, addRepeatingRuleFieldsFromOpts, addRepeatRuleFlags, repeatRuleFlagsFromOpts, } from "./repeat-flags.js";
+import { addRepeatCalendarFlags, addRepeatingRuleFieldsFromOpts, addRepeatRuleFlags, repeatRuleFlagsFromOpts, rescheduleParamsFromOpts, } from "./repeat-flags.js";
 import { aggregateExitCode, blockedCode, buildUpdatePatch, capabilitiesTable, CLI_UPDATE_LABELS, ClockError, closeCliTrace, describeConfig, errorEnvelope, ExitCode, HELPERS_MODES, installCliTrace, getConfigKey, parseHelpersMode, mutationWireData, NOTES_FORMAT, okEnvelope, openThings, OP_ID_RE, outcomeFailed, ParamSchemaError, ReferenceResolutionError, RESOLUTION_DATE_FORMAT, saveConfigKey, splitWhenSugar, trace, ThingsDbNotFoundError, ThingsDbOpenError, verifyFailedCode, } from "../../index.js";
 import { usageError } from "../read-driver.js";
 import { dim } from "../style.js";
@@ -25,6 +25,14 @@ const PRESERVE_MODIFIED_HELP = "keep this change off the modification-date timel
     "Safe with Things Cloud: the restored date syncs to your other devices and stays put, so " +
     "the item stays off the timeline everywhere — unless another device edits the same item " +
     "at nearly the same time, which re-dates it.";
+/**
+ * `--verbose` help. The flag is the middle rung of the diagnostic ladder: a
+ * successful change reports what it did and what to consider doing next, and
+ * only says HOW it drove the app when asked. A failure prints the steps without
+ * the flag, and `things op-result <key>` prints them after the fact either way.
+ */
+const VERBOSE_HELP = "add the step-by-step account of how the change was driven through the app; a failed change " +
+    "reports it anyway, and `things op-result` reports it for any change already made";
 function addWriteFlags(cmd, capability = {}) {
     const opId = new Option("--op-id <key>", "idempotency key: a resubmission with the same key is recognized as already applied " +
         "and not re-run (matches [A-Za-z0-9_-], 1-64 chars)");
@@ -40,6 +48,7 @@ function addWriteFlags(cmd, capability = {}) {
         .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)")
+        .option("--verbose", VERBOSE_HELP)
         .addOption(opId);
 }
 /**
@@ -126,6 +135,7 @@ function writeOptionsFrom(opts, extra = {}) {
         ...(maxDisruption !== undefined && { maxDisruption }),
         ...(opts.verifyTimeout !== undefined && { verifyTimeoutMs: Number(opts.verifyTimeout) }),
         ...(opts.actor !== undefined && { actor: opts.actor }),
+        ...(opts.verbose === true && { verbose: true }),
         ...(opts.dangerouslyDriveGui === true && { dangerouslyDriveGui: true }),
         ...(opts.opId !== undefined && { opId: opts.opId }),
         ...(opts.preserveModified === true && { preserveModified: true }),
@@ -396,6 +406,30 @@ function emitContextNote(result) {
     if (parts.length > 0)
         process.stdout.write(dim(`  ${parts.join("; ")}\n`));
 }
+/**
+ * The TWO TIERS on the human path (#632), plus the step account when it was
+ * asked for. Warnings are the actionable half and keep the `warning:` prefix on
+ * stderr, where an operator's eye already goes; notes are matter-of-fact and
+ * render DIM and unprefixed on stdout alongside the other disclosure lines, so
+ * "here is what happened" never wears the costume of "you should do something".
+ *
+ * The step account is dimmer still and indented under its own heading — present
+ * only when `--verbose` put `steps` on the result.
+ */
+function emitDisclosures(result) {
+    for (const note of result.notes ?? [])
+        process.stdout.write(dim(`  ${note}\n`));
+    for (const warning of result.warnings ?? []) {
+        process.stderr.write(`warning: ${warning}\n`);
+    }
+    const steps = result.steps ?? [];
+    if (steps.length === 0)
+        return;
+    process.stdout.write(dim(`  drove ${steps.length} step(s):\n`));
+    for (const [i, step] of steps.entries()) {
+        process.stdout.write(dim(`    ${i + 1}. ${step}\n`));
+    }
+}
 function emitResult(result, opts, meta) {
     switch (result.kind) {
         case "bounce-aborted": {
@@ -415,10 +449,11 @@ function emitResult(result, opts, meta) {
             return;
         }
         case "ok": {
-            for (const warning of result.warnings ?? []) {
-                process.stderr.write(`warning: ${warning}\n`);
-            }
             if (opts.json) {
+                // ONE CHANNEL (#632). Under --json the envelope is the WHOLE output:
+                // `warnings` and `notes` are already in it, so echoing them to stderr
+                // made every consumer pay for the same prose twice — once parsed, once
+                // as noise in its log. The human path below keeps the prose.
                 process.stdout.write(`${JSON.stringify(okEnvelope("mutation-result", mutationWireData(result), meta))}\n`);
             }
             else {
@@ -430,6 +465,7 @@ function emitResult(result, opts, meta) {
                 emitOccurrenceNote(result);
                 emitPreserveNote(result);
                 emitContextNote(result);
+                emitDisclosures(result);
             }
             process.exitCode = ExitCode.Ok;
             return;
@@ -459,7 +495,14 @@ function emitResult(result, opts, meta) {
                     message: result.detail,
                     ...(result.likelyCause !== undefined && { likelyCause: result.likelyCause }),
                     ...(result.hint !== undefined && { remediation: result.hint }),
-                    detail: { expected: result.expected, observed: result.observed },
+                    detail: {
+                        expected: result.expected,
+                        observed: result.observed,
+                        // A FAILURE always carries the drive's play-by-play (#632) —
+                        // no flag, no second command. It is what made the field bug
+                        // reports actionable.
+                        ...(result.steps !== undefined && { steps: result.steps }),
+                    },
                 }, meta))}\n`);
             }
             else {
@@ -467,6 +510,9 @@ function emitResult(result, opts, meta) {
                 if (result.likelyCause !== undefined) {
                     process.stderr.write(`  likely cause: ${result.likelyCause}${result.hint !== undefined ? ` — ${result.hint}` : ""}\n`);
                 }
+                for (const [i, step] of (result.steps ?? []).entries()) {
+                    process.stderr.write(`  step ${i + 1}: ${step}\n`);
+                }
             }
             process.exitCode = ExitCode.VerifyFailed;
             return;
@@ -1309,18 +1355,23 @@ export function registerWriteCommands(program) {
     });
     addDriveGuiFlag(addRepeatRuleFlags(addWriteFlags(todo
         .command("reschedule-repeat <uuid>")
-        .description("Change an existing repeating to-do's rule in place (the item keeps its identity). Set " +
-        "the new rule with the flags below; see `things help repeating`. `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("todo.reschedule-repeat", {
-            uuid,
-            frequency,
-            interval: Number(opts["interval"]),
-            ...repeatRuleFlagsFromOpts(opts, frequency),
-        }, writeOptionsFrom(opts)));
+        .description("Change an existing repeating to-do in place (the item keeps its identity). Two " +
+        "spellings: with --frequency and --interval it sets a new rule (see `things help " +
+        "repeating`), driving the app's interface, and `things undo` restores the previous " +
+        "rule. With --when <date> ALONE it MOVES the series to that date instead, keeping " +
+        "the rule and needing no --dangerously-drive-gui — the whole series moves (a weekly " +
+        "item moved to a Thursday repeats on Thursdays), occurrences due before that date " +
+        "never appear, and it cannot be undone here. Moving needs a date after today, a " +
+        "series that is not paused, does not repeat after completion, and does not repeat " +
+        "on several weekdays; Things 3.23 or later.")
+        .option("--frequency <freq>", REPEAT_FREQ_HELP)
+        .option("--interval <n>", REPEAT_INTERVAL_HELP)))).action(async (uuid, opts) => {
+        const built = rescheduleParamsFromOpts(uuid, opts);
+        if (built.kind === "error") {
+            usageError(opts, built.message);
+            return;
+        }
+        await runWrite(opts, (c) => c.write.run("todo.reschedule-repeat", built.params, writeOptionsFrom(opts)));
     });
     for (const [verb, op, desc] of [
         [
@@ -1495,18 +1546,23 @@ export function registerWriteCommands(program) {
     // --- 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 new rule with the flags below; see " +
-        "`things help repeating`. `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)));
+        .description("Change an existing repeating project in place (target by uuid or unique name; the " +
+        "project keeps its identity). With --frequency and --interval it sets a new rule " +
+        "(see `things help repeating`), driving the app's interface, and `things undo` " +
+        "restores the previous rule. With --when <date> ALONE it MOVES the series to that " +
+        "date instead, keeping the rule and needing no --dangerously-drive-gui — the whole " +
+        "series moves, occurrences due before that date never appear, and it cannot be " +
+        "undone here. Same conditions as the to-do verb: a date after today, a series that " +
+        "is not paused, does not repeat after completion, and does not repeat on several " +
+        "weekdays; Things 3.23 or later.")
+        .option("--frequency <freq>", REPEAT_FREQ_HELP)
+        .option("--interval <n>", REPEAT_INTERVAL_HELP)))).action(async (uuid, opts) => {
+        const built = rescheduleParamsFromOpts(uuid, opts);
+        if (built.kind === "error") {
+            usageError(opts, built.message);
+            return;
+        }
+        await runWrite(opts, (c) => c.write.run("project.reschedule-repeat", built.params, writeOptionsFrom(opts)));
     });
     for (const [verb, op, desc] of [
         [
@@ -1999,12 +2055,10 @@ export function registerWriteCommands(program) {
             // Human path discloses the count inline; --json carries it on
             // `observed.logged`. Everything else defers to the shared emitter.
             if (result.kind === "ok" && o.json !== true) {
-                for (const warning of result.warnings ?? []) {
-                    process.stderr.write(`warning: ${warning}\n`);
-                }
                 const logged = result.observed?.logged ?? 0;
                 process.stdout.write(`ok log-now (logged ${logged} item${logged === 1 ? "" : "s"}, ` +
                     `vector=${result.vector}, tier=${result.tier}, verified)\n`);
+                emitDisclosures(result);
                 process.exitCode = ExitCode.Ok;
                 return;
             }