things-api 0.17.0 → 0.18.0

package/dist/cli/commands/helpers.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `things helpers` — lifecycle for the optional helper pair (one installed
+ * bundle housing both):
+ *
+ *   things-deputy — app automation (mutations), unsandboxed.
+ *   things-reader — database/file reads, sandboxed to a user-granted folder.
+ *
+ * Running them means macOS permission prompts and grants attach to two stable
+ * identities instead of every terminal or agent runtime that invokes
+ * `things`, so grants stop re-prompting when those runtimes update. Routing is
+ * tri-state (`helpers-enabled`: auto | true | false, default auto —
+ * installation is the intent signal), overridable per invocation with
+ * THINGS_API_HELPERS or the global `--helpers`/`--no-helpers` flags; the CLI
+ * always falls back to direct execution when a helper is unavailable.
+ */
+import type { Command } from "commander";
+export declare function registerHelpers(program: Command): void;

package/dist/cli/commands/helpers.js

@@ -0,0 +1,148 @@
+import { helpersStatus, ExitCode, grantReader, installHelpers, loadConfig, okEnvelope, restartHelpers, uninstallHelpers, } from "../../index.js";
+function envelopeMeta(started) {
+    return { dbVersion: null, fingerprint: "unknown", elapsedMs: Date.now() - started };
+}
+/** One line describing what the configured mode means for this machine. */
+function routingLine(status) {
+    switch (status.mode) {
+        case "true":
+            return "enabled — every process routes through the helpers, and reports when it cannot";
+        case "false":
+            return "disabled (things config set helpers-enabled auto)";
+        case "auto":
+            return status.bundleInstalled
+                ? "auto — the installed helpers are used while healthy; a failure is reported, never silent"
+                : "auto — nothing installed, so everything runs direct (things helpers install to change that)";
+    }
+}
+function renderStatus(status) {
+    const deputy = status.deputy;
+    const lines = [`deputy: ${deputy.running ? "running" : "does not appear to be running"}`];
+    // The plain no-socket case needs no elaboration; a socket that exists but
+    // misbehaves (not answering, handshake refused) is worth its own line.
+    if (!deputy.running && !deputy.detail.startsWith("not running")) {
+        lines.push(`  detail: ${deputy.detail}`);
+    }
+    if (deputy.hungSocket) {
+        lines.push("  next: `things helpers restart` — the socket is present but no handshake answers");
+    }
+    lines.push(`  routing: ${routingLine(status)}`, `  launchd: ${deputy.plistInstalled ? (deputy.loaded ? "installed + loaded" : "installed, NOT loaded") : "not installed (things helpers install)"}`, `  bundle: ${status.bundleInstalled
+        ? `installed${status.installedVersion !== null ? ` (v${status.installedVersion})` : ""}`
+        : "not installed"}`, `  socket: ${deputy.socketPath}`);
+    if (deputy.hello !== null) {
+        lines.push(`  version: ${deputy.hello.deputyVersion} (protocol ${deputy.hello.protocol}, pid ${deputy.hello.pid})`);
+    }
+    if (deputy.signing !== null) {
+        lines.push(`  signing: ${deputy.signing.state}${deputy.signing.authority !== null ? ` (${deputy.signing.authority})` : ""}`);
+        if (deputy.signing.state !== "signed") {
+            lines.push("  warning: an unsigned/ad-hoc helper loses its macOS grants on every rebuild — run scripts/deputy-cert-setup.sh once, rebuild, reinstall");
+        }
+    }
+    const reader = status.reader;
+    lines.push(`reader: ${reader.running ? (reader.granted ? "running, granted" : "running, NOT granted") : reader.installed ? reader.detail : "not installed"}`);
+    if (reader.running && !reader.granted) {
+        lines.push("  next: run `things helpers grant` and accept the panel (one time; the grant survives restarts, reboots, and rebuilds)");
+    }
+    if (reader.hungSocket) {
+        lines.push("  next: `things helpers restart` — the socket is present but no handshake answers");
+    }
+    return `${lines.join("\n")}\n`;
+}
+export function registerHelpers(program) {
+    const helpers = program
+        .command("helpers")
+        .description("Manage the optional helper pair that performs database reads and app automation " +
+        "on the CLI's behalf, so macOS permission grants attach to stable helpers instead " +
+        "of every terminal or agent runtime that runs `things`. Subcommands: status, " +
+        "install, grant, restart, uninstall.");
+    helpers
+        .command("status")
+        .description("Report both helpers' state: running or not, launchd installation, installed version, " +
+        "code-signing identity, the reader's grant, and the routing mode on this machine. " +
+        "Read-only.")
+        .option("--json", "emit versioned JSON envelope on stdout")
+        .action((opts) => {
+        const started = Date.now();
+        const status = helpersStatus(loadConfig().helpersMode);
+        if (opts.json === true) {
+            process.stdout.write(`${JSON.stringify(okEnvelope("helpers-status", status, envelopeMeta(started)))}\n`);
+        }
+        else {
+            process.stdout.write(renderStatus(status));
+        }
+        process.exitCode = ExitCode.Ok;
+    });
+    helpers
+        .command("install")
+        .description("Install the helper bundle: copy it to its stable location, register both helpers " +
+        "with launchd (starts now and on every login), and report signing + grant state. " +
+        "Under the default helpers-enabled auto, an installed and healthy helper is used from " +
+        "the next command on. Rerun after every rebuild.")
+        .option("--bundle <path>", "path to a built Things API Helper.app (default: deputy/build/Things API Helper.app in this package)")
+        .action((opts) => {
+        try {
+            const result = installHelpers(opts.bundle !== undefined ? { bundlePath: opts.bundle } : {});
+            process.stdout.write(`installed ${result.bundlePath}\nlaunchd agent: ${result.plistPath}\n`);
+            if (result.readerInstalled) {
+                process.stdout.write(result.readerGranted === true
+                    ? "reader: granted — file reads ride the scoped reader\n"
+                    : result.readerGranted === false
+                        ? "reader: installed — run `things helpers grant` once to give it durable read access\n"
+                        : "reader: installed, not answering yet — check `things helpers status`\n");
+            }
+            for (const warning of result.warnings) {
+                process.stderr.write(`warning: ${warning}\n`);
+            }
+            process.exitCode = ExitCode.Ok;
+        }
+        catch (err) {
+            process.stderr.write(`error: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exitCode = ExitCode.Environment;
+        }
+    });
+    helpers
+        .command("grant")
+        .description("One-time ceremony: opens a folder panel presented by the sandboxed reader helper, " +
+        "already showing the Things data folder. Accepting gives the reader durable read " +
+        "access to exactly that folder — it survives restarts, reboots, and updates, and " +
+        "macOS enforces that the reader can reach nothing else. Interactive: run this at " +
+        "the machine, not from an unattended session.")
+        .action(() => {
+        const result = grantReader();
+        if (result.granted) {
+            process.stdout.write("granted — file reads now ride the scoped reader\n");
+            process.exitCode = ExitCode.Ok;
+        }
+        else {
+            process.stderr.write(`not granted: ${result.detail}\n`);
+            process.exitCode = ExitCode.Environment;
+        }
+    });
+    helpers
+        .command("restart")
+        .description("Restart the launchd-managed helpers (picks up a rebuilt installed bundle).")
+        .action(() => {
+        try {
+            restartHelpers();
+            process.stdout.write("helpers restarted\n");
+            process.exitCode = ExitCode.Ok;
+        }
+        catch (err) {
+            process.stderr.write(`error: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exitCode = ExitCode.Environment;
+        }
+    });
+    helpers
+        .command("uninstall")
+        .description("Stop both helpers and remove their launchd registrations and the installed bundle. " +
+        "Local state (access token, logs, the reader's grant) is kept; routing config is " +
+        "untouched (commands fall back to direct execution).")
+        .action(() => {
+        const result = uninstallHelpers();
+        process.stdout.write(result.removed.length > 0
+            ? `removed:\n${result.removed.map((p) => `  ${p}`).join("\n")}\n`
+            : "nothing installed\n");
+        process.exitCode = ExitCode.Ok;
+    });
+}
+//# sourceMappingURL=helpers.js.map

package/dist/cli/commands/helpers.js.map

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

package/dist/cli/commands/op-result.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `things op-result <op-id>` — a read-only CALLER-RECOVERY lookup over the local
+ * change history (RSPA1 deliverable 3). Thin surface over the library's opResult().
+ *
+ * When your environment kills long commands (a wall-time cap) before a write's
+ * result is printed — a `--dangerously-drive-gui` drive can run its full verify
+ * budget — dispatch the op with `--op-id <key>`, let it die, then run this in a
+ * fresh process to learn what ACTUALLY happened from the record the killed process
+ * already durably wrote. NEVER blind-retry a GUI drive.
+ *
+ * Always exit 0: this is a successful HISTORY READ regardless of the underlying
+ * op's outcome (which lives in `data.status` / `data.result`).
+ */
+import type { Command } from "commander";
+export declare function registerOpResult(program: Command): void;

package/dist/cli/commands/op-result.js

@@ -0,0 +1,39 @@
+import { okEnvelope, opResult } from "../../index.js";
+export function registerOpResult(program) {
+    program
+        .command("op-result")
+        .argument("<op-id>", "the --op-id / op_id the original write carried")
+        .description("Look up what happened to a write you dispatched with --op-id, from the local change " +
+        "history alone (opens no database, drives nothing). Use it to recover the outcome when " +
+        "your environment killed the command before it printed its result: let the command die, " +
+        "then run this. Reports FOUND (the final result + target + observation), INTENT-ONLY (the " +
+        "op started but no outcome was written — still running or the process died mid-flight, " +
+        "outcome UNCERTAIN), or UNKNOWN (no such op-id in history). Always exit 0 (a history read).")
+        .option("--json", "emit versioned JSON envelope on stdout")
+        .action((opId, opts) => {
+        const started = Date.now();
+        const data = opResult(opId);
+        const meta = {
+            dbVersion: null,
+            fingerprint: "unknown",
+            elapsedMs: Date.now() - started,
+        };
+        if (opts.json) {
+            process.stdout.write(`${JSON.stringify(okEnvelope("op-result", data, meta))}\n`);
+        }
+        else {
+            const head = data.status === "found"
+                ? `${data.result} — ${data.op}${data.uuid !== null ? ` (${data.uuid})` : ""}`
+                : data.status === "intent-only"
+                    ? `intent-only — ${data.op} (no final outcome recorded)`
+                    : "unknown op-id";
+            process.stdout.write(`op-result ${opId}: ${head}\n`);
+            process.stdout.write(`  ${data.note}\n`);
+            if (data.status === "found" && data.observed !== null) {
+                process.stdout.write(`  observed: ${JSON.stringify(data.observed)}\n`);
+            }
+        }
+        process.exitCode = 0;
+    });
+}
+//# sourceMappingURL=op-result.js.map

package/dist/cli/commands/op-result.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"op-result.js","sourceRoot":"","sources":["../../../src/cli/commands/op-result.ts"],"names":[],"mappings":"AAeA,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAqB,MAAM,gBAAgB,CAAC;AAEzE,MAAM,UAAU,gBAAgB,CAAC,OAAgB;IAC/C,OAAO;SACJ,OAAO,CAAC,WAAW,CAAC;SACpB,QAAQ,CAAC,SAAS,EAAE,gDAAgD,CAAC;SACrE,WAAW,CACV,sFAAsF;QACpF,wFAAwF;QACxF,yFAAyF;QACzF,2FAA2F;QAC3F,wFAAwF;QACxF,4FAA4F,CAC/F;SACA,MAAM,CAAC,QAAQ,EAAE,wCAAwC,CAAC;SAC1D,MAAM,CAAC,CAAC,IAAY,EAAE,IAAwB,EAAE,EAAE;QACjD,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC3B,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;QAC5B,MAAM,IAAI,GAAiB;YACzB,SAAS,EAAE,IAAI;YACf,WAAW,EAAE,SAAS;YACtB,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO;SAChC,CAAC;QACF,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;YACd,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,WAAW,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC;QACnF,CAAC;aAAM,CAAC;YACN,MAAM,IAAI,GACR,IAAI,CAAC,MAAM,KAAK,OAAO;gBACrB,CAAC,CAAC,GAAG,IAAI,CAAC,MAAM,MAAM,IAAI,CAAC,EAAE,GAAG,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;gBAC7E,CAAC,CAAC,IAAI,CAAC,MAAM,KAAK,aAAa;oBAC7B,CAAC,CAAC,iBAAiB,IAAI,CAAC,EAAE,8BAA8B;oBACxD,CAAC,CAAC,eAAe,CAAC;YACxB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,aAAa,IAAI,KAAK,IAAI,IAAI,CAAC,CAAC;YACrD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC;YACzC,IAAI,IAAI,CAAC,MAAM,KAAK,OAAO,IAAI,IAAI,CAAC,QAAQ,KAAK,IAAI,EAAE,CAAC;gBACtD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,eAAe,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;YACzE,CAAC;QACH,CAAC;QACD,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;IACvB,CAAC,CAAC,CAAC;AACP,CAAC"}

package/dist/cli/commands/writes.js

@@ -3,7 +3,7 @@ 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, closeCliTrace, describeConfig, errorEnvelope, ExitCode, installCliTrace, getConfigKey, mutationWireData, okEnvelope, openThings, OP_ID_RE, outcomeFailed, ReferenceResolutionError, saveConfigKey, splitWhenSugar, trace, ThingsDbNotFoundError, ThingsDbOpenError, verifyFailedCode, } from "../../index.js";
+import { aggregateExitCode, blockedCode, capabilitiesTable, ClockError, closeCliTrace, describeConfig, errorEnvelope, ExitCode, HELPERS_MODES, installCliTrace, getConfigKey, parseHelpersMode, 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) {
@@ -354,6 +354,7 @@ function emitResult(result, opts, meta) {
                     `  invocation: ${result.plan.invocation}`,
                     `  hazards checked: ${result.plan.hazardsChecked.join(", ") || "none"}`,
                     `  expected delta: ${JSON.stringify(result.plan.expectedDelta)}`,
+                    ...(result.plan.notes ?? []).map((n) => `  note: ${n}`),
                     "",
                 ].join("\n"));
             }
@@ -1423,7 +1424,12 @@ export function registerWriteCommands(program) {
         .option("--notes <text>", "notes body")
         .option("--when <value>", "today | evening | anytime | someday | YYYY-MM-DD")
         .option("--reminder <time>", "HH:mm reminder (needs a schedulable --when)")
-        .option("--deadline <date>", "YYYY-MM-DD")
+        .option("--deadline <date>", "YYYY-MM-DD — deadlines EVERY occurrence: each starts (deadline − --when) days " +
+        "before its own deadline (needs a concrete --when, on or before the deadline; " +
+        "alternative spelling of --start-days-earlier — give one or the other, both must agree)")
+        .option("--start-days-earlier <n>", "deadlines EVERY occurrence, naming the lead directly: each starts N days before " +
+        "its own deadline (needs a concrete --when; alternative spelling of --deadline <date> — " +
+        "give one or the other, both must agree)")
         .option("--tag <name>", "tag to attach (repeatable)", collect, [])
         .option("--checklist-item <title>", "checklist item (repeatable)", collect, [])
         .option("--project <ref>", "destination project (uuid or unique name)")
@@ -1445,6 +1451,9 @@ export function registerWriteCommands(program) {
             ...(opts["when"] !== undefined && { when: opts["when"] }),
             ...(opts["reminder"] !== undefined && { reminder: opts["reminder"] }),
             ...(opts["deadline"] !== undefined && { deadline: opts["deadline"] }),
+            ...(opts["startDaysEarlier"] !== undefined && {
+                startDaysEarlier: Number(opts["startDaysEarlier"]),
+            }),
             ...(tags.length > 0 && { tags }),
             ...(checklistItems.length > 0 && { checklistItems }),
             ...(projectRef !== undefined && { project: projectRef }),
@@ -2155,7 +2164,8 @@ 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 | auto-launch | ui-enabled | ui-drive-budget-ms | trace | scope")
+        "bounce-max-items | auto-launch | helpers-enabled (auto | true | false) | ui-enabled | " +
+        "ui-drive-budget-ms | trace | scope")
         .action((key, value, opts) => {
         const map = {
             profile: "profile",
@@ -2168,6 +2178,7 @@ export function registerWriteCommands(program) {
             "bounce-enabled": "bounceEnabled",
             "bounce-max-items": "bounceMaxItems",
             "auto-launch": "autoLaunch",
+            "helpers-enabled": "helpersMode",
             "ui-enabled": "uiEnabled",
             "ui-drive-budget-ms": "uiDriveBudgetMs",
             trace: "traceEnabled",
@@ -2179,6 +2190,14 @@ export function registerWriteCommands(program) {
             process.exitCode = ExitCode.Usage;
             return;
         }
+        // `helpers-enabled` is TRI-state (auto | true | false): anything else is
+        // refused rather than silently coerced to a boolean, so a typo can never
+        // read as "off" on a machine that meant "auto".
+        if (target === "helpersMode" && parseHelpersMode(value) === undefined) {
+            process.stderr.write(`error: helpers-enabled accepts ${HELPERS_MODES.join(" | ")} (got "${value}")\n`);
+            process.exitCode = ExitCode.Usage;
+            return;
+        }
         const parsed = target === "maxDisruption" || target === "bounceMaxItems" || target === "uiDriveBudgetMs"
             ? Number(value)
             : target === "auditEnabled" ||