things-api 0.16.0 → 0.17.0

package/README.md

@@ -2,7 +2,7 @@
 
 A typed TypeScript library + CLI (`things`) for programmatic interaction with [Things 3](https://culturedcode.com/things/) by Cultured Code.
 
-**Status: read + write + MCP layers live and published to npm (v0.16.0 — see [CHANGELOG.md](CHANGELOG.md)).** Reads go straight to the local SQLite database (UI-exact Today ordering, sidebar-grouped Anytime/Someday with container-status cascade, decoded repeat rules, occurrence projections); writes run a verified pipeline over four write vectors — two lab-validated headless surfaces (the URL scheme + AppleScript) and two opt-in surfaces (Apple Shortcuts and an Accessibility-driven GUI vector) — with hazard guards, disruption-tier policy, a JSONL audit trail, batch mode, audit-replay undo (transactional across compound operations), full project lifecycle (complete/cancel/reopen/restore), heading rename/archive/unarchive with children policies, container detach, granular stateful checklists, tag hierarchy management incl. un-nesting, completion/creation backdating, Logbook imports, tiered fuzzy name resolution (uuid prefixes, `things:///show?id=` share links), and kind-neutral in-place reordering within any container or view (one `things reorder <refs…> [--start|--end|--before|--after] --in <target>` verb — Today/Evening, a project, an area, a heading's children, someday, inbox — plus `project move-heading` for the headings themselves and `area reorder` for the sidebar). The Apple Shortcuts surface is wired for the two headless capabilities nothing else can do: creating a heading in an existing project (`things project add-heading`) and clearing a reminder from a date-scheduled item (`things todo clear-reminder`). Both run through bundled proxy shortcuts (`things setup shortcuts`) and are gated on their presence. The fourth vector — the Accessibility-driven GUI vector — is off by default and drives the local Things app to reach transforms that exist on no scriptable surface (repeat-rule editing on existing to-dos and projects, convert-to-project, sidebar area reorder); see [Accessibility GUI vector](#accessibility-gui-vector-optional-off-by-default) below. Single-item permanent delete stays interactive-only (its macOS consent has no always-allow) and is out of the headless pipeline. See [docs/design/](docs/design/) for the architecture and VM-lab design, [docs/lab/](docs/lab/harness.md) for the probe harness and campaign results the write layer is grounded in, and [docs/atlas/](docs/atlas/schema-v26.md) for the database↔UI map.
+**Status: read + write + MCP layers live and published to npm (v0.17.0 — see [CHANGELOG.md](CHANGELOG.md)).** Reads go straight to the local SQLite database (UI-exact Today ordering, sidebar-grouped Anytime/Someday with container-status cascade, decoded repeat rules, occurrence projections); writes run a verified pipeline over four write vectors — two lab-validated headless surfaces (the URL scheme + AppleScript) and two opt-in surfaces (Apple Shortcuts and an Accessibility-driven GUI vector) — with hazard guards, disruption-tier policy, a JSONL audit trail, batch mode, audit-replay undo (transactional across compound operations), full project lifecycle (complete/cancel/reopen/restore), heading rename/archive/unarchive with children policies, container detach, granular stateful checklists, tag hierarchy management incl. un-nesting, completion/creation backdating, Logbook imports, tiered fuzzy name resolution (uuid prefixes, `things:///show?id=` share links), and kind-neutral in-place reordering within any container or view (one `things reorder <refs…> [--start|--end|--before|--after] --in <target>` verb — Today/Evening, a project, an area, a heading's children, someday, inbox — plus `project move-heading` for the headings themselves and `area reorder` for the sidebar). The Apple Shortcuts surface is wired for the two headless capabilities nothing else can do: creating a heading in an existing project (`things project add-heading`) and clearing a reminder from a date-scheduled item (`things todo clear-reminder`). Both run through bundled proxy shortcuts (`things setup shortcuts`) and are gated on their presence. The fourth vector — the Accessibility-driven GUI vector — is off by default and drives the local Things app to reach transforms that exist on no scriptable surface (repeat-rule editing on existing to-dos and projects, convert-to-project, sidebar area reorder); see [Accessibility GUI vector](#accessibility-gui-vector-optional-off-by-default) below. Single-item permanent delete stays interactive-only (its macOS consent has no always-allow) and is out of the headless pipeline. See [docs/design/](docs/design/) for the architecture and VM-lab design, [docs/lab/](docs/lab/harness.md) for the probe harness and campaign results the write layer is grounded in, and [docs/atlas/](docs/atlas/schema-v26.md) for the database↔UI map.
 
 ```sh
 things today --json                # read: your Today list, Evening split, UI order

package/dist/cli/commands/repeat-flags.d.ts

@@ -23,8 +23,8 @@ export declare function addRepeatCalendarFlags(cmd: Command): Command;
 export declare function addRepeatingRuleFieldsFromOpts(opts: Record<string, unknown>, frequency: RepeatFrequency, interval: number): AddRepeatingRuleFields;
 /**
  * Build the extended rule fields from CLI options (present keys only —
- * exactOptionalPropertyTypes). Combination validity is enforced downstream
- * (the same refusals the library raises), so a wrong-frequency flag surfaces a
- * clear error rather than being silently applied.
+ * exactOptionalPropertyTypes). A wrong-frequency anchor flag is REFUSED here
+ * (UIC6-l), never silently dropped; other combination validity (e.g. weekdays on
+ * a non-weekly rule) is enforced downstream by assertRepeatRule.
  */
 export declare function repeatRuleFlagsFromOpts(opts: Record<string, unknown>, frequency: RepeatFrequency): RepeatRuleFlagFields;

package/dist/cli/commands/repeat-flags.js

@@ -9,6 +9,8 @@ export function addRepeatRuleFlags(cmd) {
         .option("--yearly-month <n>", "yearly only: the month (1–12)")
         .option("--ends-after <n>", "stop after N occurrences (1–999)")
         .option("--ends-on <date>", "YYYY-MM-DD — stop after this date")
+        .option("--when <date>", "YYYY-MM-DD — the first occurrence (drives the Repeat dialog's Next field); " +
+        "make-repeating defaults to the item's scheduled date")
         .option("--reminder <time>", "HH:mm — a reminder time on each occurrence")
         .option("--deadline", "give each occurrence a deadline")
         .option("--start-days-earlier <n>", "with --deadline: start each occurrence N days before its deadline");
@@ -55,45 +57,100 @@ function dayAnchor(opts) {
     return undefined;
 }
 /**
- * Build the extended rule fields from CLI options (present keys only —
- * exactOptionalPropertyTypes). Combination validity is enforced downstream
- * (the same refusals the library raises), so a wrong-frequency flag surfaces a
- * clear error rather than being silently applied.
+ * The CALENDAR-ANCHOR flags that apply only to a SUBSET of frequencies, and the
+ * frequencies that consume each. A present anchor flag on any other frequency is
+ * a hard error — never a silent drop (UIC6-l). Exhaustive over the anchor flag
+ * set; a new anchor flag must earn a row here (and the mapper below consumes it).
+ * `weekdays` is intentionally ABSENT: it is mapped unconditionally and refused
+ * downstream by assertRepeatRule ("weekdays apply only to a weekly rule"), the
+ * mapped-contradiction path — this table is only for the SILENTLY-dropped anchors.
  */
-export function repeatRuleFlagsFromOpts(opts, frequency) {
-    const fields = {};
-    if (opts["afterCompletion"] === true)
-        fields.afterCompletion = true;
-    if (typeof opts["weekdays"] === "string") {
-        fields.weekdays = opts["weekdays"]
+const ANCHOR_FLAG_FREQUENCIES = {
+    onDay: ["monthly", "yearly"],
+    onWeekday: ["monthly", "yearly"],
+    onOrdinal: ["monthly", "yearly"],
+    yearlyMonth: ["yearly"],
+};
+/** The user-facing flag spelling for a camelCase option key (error messages). */
+const ANCHOR_FLAG_SPELLING = {
+    onDay: "--on-day",
+    onWeekday: "--on-weekday",
+    onOrdinal: "--on-ordinal",
+    yearlyMonth: "--yearly-month",
+};
+/**
+ * Refuse a calendar-anchor flag supplied on a frequency that does not consume it
+ * (UIC6-l): `--frequency weekly --on-day 15` errors instead of silently running a
+ * plain weekly rule. Behavioral message — names the flag + the frequency it
+ * belongs to, never a mechanism.
+ */
+function assertAnchorFlagsMatchFrequency(opts, frequency) {
+    for (const [key, allowed] of Object.entries(ANCHOR_FLAG_FREQUENCIES)) {
+        if (opts[key] === undefined)
+            continue;
+        if (!allowed.includes(frequency)) {
+            const flag = ANCHOR_FLAG_SPELLING[key] ?? key;
+            throw new RangeError(`${flag} applies only to a ${allowed.join(" or ")} rule — this rule is ${frequency}`);
+        }
+    }
+}
+/**
+ * EXHAUSTIVE over every field of {@link RepeatRuleFlagFields}: each rule param is
+ * derived from the CLI options by exactly one entry, so a new param added to
+ * RepeatRuleParams breaks compilation here until it earns a flag mapping. This is
+ * what makes an accepted-but-dropped flag impossible for this vocabulary (the
+ * UIC6-l class) — the wrong-frequency guard above catches the inverse (a flag
+ * with no consuming frequency). Each entry returns the mapped value or
+ * `undefined` (absent — exactOptionalPropertyTypes).
+ */
+const FLAG_MAP = {
+    afterCompletion: (opts) => (opts["afterCompletion"] === true ? true : undefined),
+    weekdays: (opts) => typeof opts["weekdays"] === "string"
+        ? opts["weekdays"]
             .split(",")
             .map((d) => d.trim().toLowerCase())
-            .filter((d) => d.length > 0);
-    }
-    const anchor = dayAnchor(opts);
-    if (frequency === "monthly" && anchor !== undefined) {
-        fields.monthly = anchor;
-    }
-    if (frequency === "yearly") {
+            .filter((d) => d.length > 0)
+        : undefined,
+    monthly: (_opts, frequency, anchor) => frequency === "monthly" && anchor !== undefined ? anchor : undefined,
+    yearly: (opts, frequency, anchor) => {
+        if (frequency !== "yearly")
+            return undefined;
         const month = opts["yearlyMonth"];
-        if (month !== undefined || anchor !== undefined) {
-            const base = { month: Number(month) };
-            fields.yearly = (anchor === undefined ? base : { ...base, ...anchor });
+        if (month === undefined && anchor === undefined)
+            return undefined;
+        const base = { month: Number(month) };
+        return (anchor === undefined ? base : { ...base, ...anchor });
+    },
+    ends: (opts) => {
+        if (opts["endsAfter"] !== undefined)
+            return { kind: "after", count: Number(opts["endsAfter"]) };
+        if (typeof opts["endsOn"] === "string")
+            return { kind: "on-date", date: opts["endsOn"] };
+        return undefined;
+    },
+    reminder: (opts) => (typeof opts["reminder"] === "string" ? opts["reminder"] : undefined),
+    next: (opts) => (typeof opts["when"] === "string" ? opts["when"] : undefined),
+    deadline: (opts) => (opts["deadline"] === true ? true : undefined),
+    startDaysEarlier: (opts) => opts["startDaysEarlier"] !== undefined ? Number(opts["startDaysEarlier"]) : undefined,
+};
+/**
+ * Build the extended rule fields from CLI options (present keys only —
+ * exactOptionalPropertyTypes). A wrong-frequency anchor flag is REFUSED here
+ * (UIC6-l), never silently dropped; other combination validity (e.g. weekdays on
+ * a non-weekly rule) is enforced downstream by assertRepeatRule.
+ */
+export function repeatRuleFlagsFromOpts(opts, frequency) {
+    assertAnchorFlagsMatchFrequency(opts, frequency);
+    const anchor = dayAnchor(opts);
+    const fields = {};
+    for (const key of Object.keys(FLAG_MAP)) {
+        const value = FLAG_MAP[key](opts, frequency, anchor);
+        if (value !== undefined) {
+            // The map's per-key return type is exactly RepeatRuleFlagFields[K]; the
+            // index write is safe but TS cannot narrow K across the loop.
+            fields[key] = value;
         }
     }
-    if (opts["endsAfter"] !== undefined) {
-        fields.ends = { kind: "after", count: Number(opts["endsAfter"]) };
-    }
-    else if (typeof opts["endsOn"] === "string") {
-        fields.ends = { kind: "on-date", date: opts["endsOn"] };
-    }
-    if (typeof opts["reminder"] === "string")
-        fields.reminder = opts["reminder"];
-    if (opts["deadline"] === true)
-        fields.deadline = true;
-    if (opts["startDaysEarlier"] !== undefined) {
-        fields.startDaysEarlier = Number(opts["startDaysEarlier"]);
-    }
     return fields;
 }
 //# sourceMappingURL=repeat-flags.js.map

package/dist/cli/commands/repeat-flags.js.map

@@ -1 +1 @@
-{"version":3,"file":"repeat-flags.js","sourceRoot":"","sources":["../../../src/cli/commands/repeat-flags.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"repeat-flags.js","sourceRoot":"","sources":["../../../src/cli/commands/repeat-flags.ts"],"names":[],"mappings":"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"}

package/dist/cli/commands/writes.js

@@ -1,6 +1,9 @@
 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 { aggregateExitCode, blockedCode, capabilitiesTable, ClockError, describeConfig, errorEnvelope, ExitCode, getConfigKey, mutationWireData, okEnvelope, openThings, OP_ID_RE, outcomeFailed, ReferenceResolutionError, saveConfigKey, splitWhenSugar, ThingsDbNotFoundError, ThingsDbOpenError, verifyFailedCode, } from "../../index.js";
+import { aggregateExitCode, blockedCode, capabilitiesTable, ClockError, closeCliTrace, describeConfig, errorEnvelope, ExitCode, installCliTrace, getConfigKey, mutationWireData, okEnvelope, openThings, OP_ID_RE, outcomeFailed, ReferenceResolutionError, saveConfigKey, splitWhenSugar, trace, ThingsDbNotFoundError, ThingsDbOpenError, verifyFailedCode, } from "../../index.js";
 import { usageError } from "../read-driver.js";
 import { dim } from "../style.js";
 function addWriteFlags(cmd) {
@@ -145,7 +148,12 @@ function headingPlacement(c, projectUuid, opts) {
 /** Add the mandatory GUI-drive acknowledgement to a ui-vector command. */
 function addDriveGuiFlag(cmd) {
     return cmd.option("--dangerously-drive-gui", "required: visibly drives the Things app to make a change it offers nowhere else; " +
-        "also needs `things config set ui-enabled true`");
+        "also needs `things config set ui-enabled true`. Driving the app can take over a " +
+        "minute on a large database, so allow a generous timeout (180s or more) — if your own " +
+        "timeout stops the command first you get empty output, not a result. A timeout or empty " +
+        "output is not a success: the change may still have landed, so re-check with " +
+        "`things show <ref>` before retrying, and never fire an identical retry (it can duplicate " +
+        "the change) — stop and report if the state is wrong or unclear");
 }
 function collect(value, previous) {
     return [...previous, value];
@@ -186,6 +194,16 @@ async function runWrite(opts, fn, emitFn = emitResult) {
     if (!opIdOk(opts))
         return;
     const started = Date.now();
+    // Dev-mode step-timeline trace + signal-safe interrupt guard (TRACE1, #487).
+    // Scoped to the write driver — the invocations where a per-step timeline earns
+    // its keep, and where a mid-drive kill would otherwise leave empty stdout. The
+    // sink is a no-op unless tracing is on (a `-dev` build, or config/env forced).
+    installCliTrace({
+        argv: process.argv.slice(1),
+        version: CLI_VERSION,
+        isDev: isDevVersion(CLI_VERSION),
+    });
+    armInterrupt(opts.json === true);
     let client = null;
     const meta = (client_) => {
         let dbVersion = null;
@@ -239,6 +257,16 @@ async function runWrite(opts, fn, emitFn = emitResult) {
     }
     finally {
         client?.close();
+        // Close the trace with a final result line (the exit code the caller sees),
+        // then disarm the interrupt guard so a later signal during teardown/reads
+        // emits nothing.
+        trace(() => ({
+            phase: "invocation-end",
+            exitCode: process.exitCode ?? 0,
+            elapsedMs: Date.now() - started,
+        }));
+        disarmInterrupt();
+        closeCliTrace();
     }
 }
 /**
@@ -258,6 +286,26 @@ function emitPreserveNote(result) {
         process.stderr.write(`warning: preserve-modified: ${f.uuid}: ${f.detail}\n`);
     }
 }
+/**
+ * TTY disclosure for the HINTS1 completion-context on a verified complete/cancel:
+ * a dim line naming the OPEN work remaining in the to-do's project and/or Today,
+ * so an operator (or an agent reading the human render) sees an emptied container
+ * at a glance. Silent when neither arm applies (the field is absent).
+ */
+function emitContextNote(result) {
+    const context = result.context;
+    if (context === undefined)
+        return;
+    const parts = [];
+    if (context.project !== undefined) {
+        parts.push(`project "${context.project.title}": ${context.project.remainingOpen} open remaining`);
+    }
+    if (context.today !== undefined) {
+        parts.push(`today: ${context.today.remainingOpen} open remaining`);
+    }
+    if (parts.length > 0)
+        process.stdout.write(dim(`  ${parts.join("; ")}\n`));
+}
 function emitResult(result, opts, meta) {
     switch (result.kind) {
         case "bounce-aborted": {
@@ -290,6 +338,7 @@ function emitResult(result, opts, meta) {
                     : `vector=${result.vector}, tier=${result.tier}, verified`;
                 process.stdout.write(`ok ${result.op}${uuid} (${status})\n`);
                 emitPreserveNote(result);
+                emitContextNote(result);
             }
             process.exitCode = ExitCode.Ok;
             return;
@@ -2106,7 +2155,7 @@ export function registerWriteCommands(program) {
         .command("set <key> <value>")
         .description("Persist a config key: profile | maxDisruption | actor | auditEnabled | " +
         "accepted-fingerprint | certified-app-version | allow-experimental | bounce-enabled | " +
-        "bounce-max-items | ui-enabled | scope")
+        "bounce-max-items | auto-launch | ui-enabled | ui-drive-budget-ms | trace | scope")
         .action((key, value, opts) => {
         const map = {
             profile: "profile",
@@ -2118,7 +2167,10 @@ export function registerWriteCommands(program) {
             "allow-experimental": "allowExperimental",
             "bounce-enabled": "bounceEnabled",
             "bounce-max-items": "bounceMaxItems",
+            "auto-launch": "autoLaunch",
             "ui-enabled": "uiEnabled",
+            "ui-drive-budget-ms": "uiDriveBudgetMs",
+            trace: "traceEnabled",
             scope: "scope",
         };
         const target = map[key];
@@ -2127,12 +2179,14 @@ export function registerWriteCommands(program) {
             process.exitCode = ExitCode.Usage;
             return;
         }
-        const parsed = target === "maxDisruption" || target === "bounceMaxItems"
+        const parsed = target === "maxDisruption" || target === "bounceMaxItems" || target === "uiDriveBudgetMs"
             ? Number(value)
             : target === "auditEnabled" ||
                 target === "allowExperimental" ||
                 target === "bounceEnabled" ||
-                target === "uiEnabled"
+                target === "autoLaunch" ||
+                target === "uiEnabled" ||
+                target === "traceEnabled"
                 ? value === "true"
                 : value;
         // Universal `--dry-run` (../dry-run.ts): `config set` writes local config