things-api 0.8.0 → 0.10.0

package/README.md

@@ -2,10 +2,11 @@
 
 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.7.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 two lab-validated write vectors (URL scheme + AppleScript) 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 ordering across eight scopes (incl. a project's headings and the top-level sidebar projects). A third surface — Apple Shortcuts — is now wired for the two headless capabilities nothing else can do: creating a heading in an existing project (`things heading add`) 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. 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.10.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 ordering across eight scopes (incl. a project's headings and the top-level sidebar projects). The Apple Shortcuts surface is wired for the two headless capabilities nothing else can do: creating a heading in an existing project (`things heading add`) 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
+things legend                      # the symbols & colors the list views use
 things upcoming --horizon 5       # date plan incl. projected repeat occurrences
 things todo add "Buy milk" --when today --tags errands --dry-run   # plan without executing
 things undo --dry-run              # inverse plan for the last mutation (audit replay)
@@ -14,7 +15,7 @@ things capabilities --op todo.delete   # what's possible, per vector, with evide
 
 ## Requirements & first-run setup
 
-Things 3 installed and launched once, Node ≥ 24, and a handful of one-time macOS consents / Things settings depending on what you use (file-access consent for reads; "Enable Things URLs" + Automation consents for writes). **See [docs/setup.md](docs/setup.md)** — including the dedicated-automation-Mac checklist. `things doctor` validates your setup and prints remediation for anything missing.
+Things 3 installed and launched once, Node ≥ 24, and a handful of one-time macOS consents / Things settings depending on what you use (file-access consent for reads; "Enable Things URLs" + Automation consents for writes; an Accessibility grant for the optional GUI vector). **See [docs/setup.md](docs/setup.md)** — including the dedicated-automation-Mac checklist. `things doctor` validates your setup and prints remediation for anything missing.
 
 ### Shortcuts setup (optional)
 
@@ -28,6 +29,14 @@ On each shortcut's first run macOS asks for permission — choose **Always Allow
 
 Once installed, these Shortcuts-only operations become available as ordinary commands: `things heading add <project> <title>` (create a heading in an existing project) and `things todo clear-reminder <uuid>` (clear a date-scheduled to-do's reminder while keeping its date). Both are also exposed over MCP (`create_heading`, `clear_reminder`). If a required shortcut is missing, the command is blocked up front with a pointer back to `things setup shortcuts` — nothing is dispatched.
 
+### Accessibility GUI vector (optional, off by default)
+
+A handful of transforms exist on **no scriptable surface at all** — the URL scheme, AppleScript, and Shortcuts cannot express them. The fourth write vector (the "ui" vector) reaches them by driving the local Things app's real interface through macOS Accessibility. It unlocks: making an existing to-do or project repeat and rescheduling/pausing/resuming its rule; converting a to-do into a project; and moving an area to a new position in the global area order (the sidebar). See [docs/design/ui-vector.md](docs/design/ui-vector.md) for the full model.
+
+Because it drives the live GUI it is **fail-closed and two-key gated**: enable it once with `things config set ui-enabled true`, then acknowledge each individual call with `--dangerously-drive-gui` (`dangerously_drive_gui` over MCP). It carries the `H-UI-DRIVE` hazard, sits at the top disruption tier (3), and is intended for a dedicated, always-on Mac pinned to the English app language (a non-English UI fails the vector closed). Its recipes are **fragile** — an app-layout change can break them — so each op carries a per-op certification status (`uncertified` → `lab-certified` → on-device `certified`) recorded in the manifest at [src/write/vectors/ui-certification.ts](src/write/vectors/ui-certification.ts) and surfaced by `things capabilities` and the `things doctor` ui-vector section; a successful drive of a not-yet-`certified` op returns a note saying so.
+
+Setup — granting Accessibility to the driving process and verifying it with `things doctor --probe-accessibility` — is in [docs/setup.md](docs/setup.md).
+
 ### Development install
 
 To get a global `things` command that runs the live TypeScript source (no build step — Node ≥ 24 strips types natively):
@@ -41,23 +50,23 @@ Edits under `src/` take effect immediately. The bin launcher ([bin/things.js](bi
 
 ## Core principles
 
-- **Reads** go directly to Things' local SQLite database (read-only, WAL-aware). **Writes** go exclusively through official app surfaces — URL scheme, AppleScript, Shortcuts — never direct DB writes (sync corruption).
+- **Reads** go directly to Things' local SQLite database (read-only, WAL-aware). **Writes** go exclusively through official app surfaces — URL scheme, AppleScript, Shortcuts, and (opt-in) the Accessibility-driven GUI — never direct DB writes (sync corruption).
 - **Every mutation is verified**: pre-read → hazard guards → execute → poll re-read until the expected delta appears. Silent no-ops are failures.
 - **Every mutation is audited**: JSONL trail (`~/.local/state/things-api/audit/`) with requested vs. observed deltas; auth tokens structurally redacted.
-- **Schema drift is detected**: table/column fingerprints keyed by Things' database version; writes hard-block on mismatch ([drift runbook](docs/lab/drift-runbook.md)).
-- **Disruption is explicit**: every operation×vector combination carries a disruption tier (0 = invisible → 3 = navigates UI/modals); disruptive operations require explicit opt-in flags.
+- **Schema drift is detected**: table/column fingerprints keyed by Things' database version; writes hard-block on mismatch, and reads surface a non-blocking `meta.warnings` note rather than failing ([drift runbook](docs/lab/drift-runbook.md)).
+- **Disruption is explicit**: every operation×vector combination carries a disruption tier (0 = invisible → 3 = drives the live UI); disruptive operations require explicit opt-in flags.
 - **Nothing is developed against production data**: probing and integration tests run in disposable Tart macOS VMs.
 
 ## For agents
 
 The CLI is designed to be driven by coding agents with no out-of-band knowledge. The contract:
 
-1. **Discovery**: `things --help` (ends with AGENT NOTES), per-command `--help` (states each write's vector, disruption tier, hazards, and exact acknowledgement flag names — regression-tested as API), and `things capabilities [--op <op>] --json` (the lab-validated operation × vector support matrix, with probe-evidence ids).
-2. **Structured output**: every command takes `--json` → versioned envelope `{ apiVersion, ok, kind, data|error, meta }` on stdout; human chatter goes to stderr only.
-3. **Stable exit codes**: `0` ok · `2` usage · `3` verify-failed (mutation executed, expected delta never appeared) · `4` blocked (hazard guard or disruption policy; error carries `remediation`) · `5` drift-blocked · `6` unsupported · `7` environment.
+1. **Discovery**: `things --help` (a grouped one-line-per-command index; orientation detail lives behind `things help <topic>` — `agent`, `filters`, `ids`, `output`, `writes`), per-command `things <command> --help` (behavior, side effects, and the exact acknowledgement flag names a write needs — regression-tested as API; by design it does **not** carry vector/tier/hazard vocabulary, which is banned from help text by [docs/design/surface-copy.md](docs/design/surface-copy.md) — that classification lives in `capabilities`), and `things capabilities [--op <op>] --json` (the lab-validated operation × vector support matrix with disruption tiers, hazards, per-op certification status, and probe-evidence ids). Command invocation follows one grammar (`things <view>` · `things <type> <verb> <subject>` · loose `things <verb> <subject>` · bare `things <subject>`) with a single precedence chain — registered command/alias → view keyword → reference resolution — specified in [docs/design/cli-grammar.md](docs/design/cli-grammar.md).
+2. **Structured output**: every command takes `--json` → versioned envelope `{ apiVersion, ok, kind, data|error, meta }` on stdout; human chatter goes to stderr only. List views are **bounded by default**: the flat/chronological views (`inbox`, `today`, `upcoming`, `logbook`, `trash`, `search`, `changes`) return at most 50 items — raise with `--limit <n>` or lift with `--all` — and carry exact truncation counts in `meta.truncation { shown, total, limit, truncated }` (the split `today` view also breaks the counts down per render section under `sections`). The grouped catalogues (`anytime`, `someday`) always show every area and project row and cap per block instead (no `--limit`): `--area-limit <n>` (default 30) per area block on both, `--project-limit <n>` (default 3) per project block on anytime, `--show-active-project-items [n]` for someday's trailing active-projects section — reporting `meta.grouped { truncated, blocks[] }`, where each block is identity-carrying (`kind`, `ref`, `title`, `shown`, `total`) and project blocks nest inside their area block under `children`. A read whose database schema no longer matches this build's validated fingerprint carries a non-blocking `meta.warnings` note (the read still returns best-effort; the same drift hard-blocks writes). Same defaults and metadata apply over MCP.
+3. **Stable exit codes**: `0` ok · `2` usage · `3` verify-failed (mutation executed, expected delta never appeared) · `4` blocked (hazard guard or disruption policy; error carries `remediation`) · `5` drift-blocked · `6` unsupported (op has no supported vector — `things batch` also aggregates to 6 when its only failures are unsupported ops) · `7` environment.
 4. **Plan before executing**: every write supports `--dry-run` — compiled invocation (token-redacted), chosen vector, tier, hazards checked, expected delta. Nothing runs, nothing is audited.
-5. **No prompts, ever**: risky semantics are explicit flags — `--children require-resolved|auto-complete` (project completion cascades), `--acknowledge-checklist-reset` (checklist replacement destroys per-item state), `--acknowledge-project-reopen` (open child reopens a resolved project), `--dangerously-permanent` (area/tag delete and empty-trash skip the Trash).
-6. **Experimental surfaces are opt-in**: `things reorder` (ordering within Today, the Inbox, Someday, a project's to-dos, a project's headings, or an area) rides an undocumented AppleScript command that any Things update may remove. It requires `things config set allow-experimental true` and re-checks the app's sdef declaration before every dispatch; `things doctor` reports both gates. Two scopes never touch it: This Evening and the top-level sidebar projects use verified `when=` round-trips (the "bounce", ≤10 items) instead.
+5. **No prompts, ever**: risky semantics are explicit flags — `--children require-resolved|auto-complete` (project completion cascades), `--acknowledge-checklist-reset` (checklist replacement destroys per-item state), `--acknowledge-project-reopen` (open child reopens a resolved project), `--dangerously-permanent` (area/tag delete and empty-trash skip the Trash), `--dangerously-drive-gui` (each Accessibility GUI-vector call).
+6. **Experimental surfaces are opt-in**: `things reorder` (ordering within Today, the Inbox, Someday, a project's to-dos, a project's headings, or an area) rides an undocumented AppleScript command that any Things update may remove. It requires `things config set allow-experimental true` and re-checks the app's sdef declaration before every dispatch; `things doctor` reports both gates. Two scopes never touch it: This Evening and the top-level sidebar projects use verified `when=` round-trips (the "bounce", ≤10 items) instead. Reordering the areas themselves (the sidebar order) is a separate operation on the Accessibility GUI vector (`things area reorder`, MCP `reorder_area`).
 
 A typical mutation flow:
 
@@ -86,4 +95,15 @@ The TypeScript library (`import { openThings } from "things-api"`) is the produc
 { "mcpServers": { "things": { "command": "things", "args": ["mcp"] } } }
 ```
 
-The server instructions carry the user's live inventory (areas, tag hierarchy, open projects — read at server start) plus the reference/scheduling vocabulary, so models can name real destinations without a discovery round-trip. Tools mirror the client surface: reads (`read_view` — today/inbox/anytime/upcoming with occurrence horizon/someday/logbook/trash — `search`, `changes_since`, `get_item`, `get_project`, `list_collections`) and grouped semantic mutations (`add_todo`, `update_todo`, `set_todo_status`, `move_todo`, `set_tags`, `edit_checklist`; `delete_item`/`restore_item`/`duplicate_item` for to-dos and projects alike; `add_project`, `update_project`, `set_project_status`, `move_project`; area and tag CRUD incl. tag un-nesting and guarded subtree deletion; plus generic `run_operation` for the full 28-op catalog, `batch`, `reorder`, `undo`, `capabilities`, `doctor`). Every write tool takes `dry_run`; tools carry read-only/destructive annotations; hazard blocks come back as structured tool errors carrying the same remediation text the CLI prints. Tool descriptions follow the consumer-voice contract in [docs/design/surface-copy.md](docs/design/surface-copy.md).
+The server instructions carry the user's live inventory (areas, tag hierarchy, open projects — read at server start) plus the reference/scheduling vocabulary, so models can name real destinations without a discovery round-trip. Tools mirror the client surface, grouped by area:
+
+- **Reads**: `read_view` (today / inbox / anytime / upcoming with occurrence horizon / someday / logbook / trash), `search`, `changes_since`, `get_item`, `get_project`, `get_area`, `list_collections`.
+- **To-do writes**: `add_todo`, `update_todo`, `set_todo_status`, `move_todo`, `set_tags`, `edit_checklist`, plus completion/creation backdating (`backdate_todo`) and Logbook import (`add_logged_todo`).
+- **Project writes**: `add_project`, `update_project`, `set_project_status`, `move_project`.
+- **To-dos and projects alike**: `delete_item`, `restore_item`, `duplicate_item`.
+- **Areas & tags**: `add_area`, `update_area`, `delete_area`, `add_tag`, `update_tag`, `delete_tag` (tag CRUD incl. un-nesting and guarded subtree deletion).
+- **Headings & reminders** (Shortcuts-backed where headless-impossible): `create_heading`, `rename_heading`, `archive_heading`, `unarchive_heading`, `clear_reminder`.
+- **Accessibility GUI ("ui") vector** (two-key gated — `ui-enabled` config + `dangerously_drive_gui` per call): `make_repeating`, `reschedule_repeat`, `set_repeat_state`, `convert_to_project`, `make_project_repeating`, `create_repeating_project`, `reschedule_project_repeat`, `set_project_repeat_state`, `reorder_area`.
+- **Generic & discovery**: `run_operation` (the full 49-op catalog), `batch`, `reorder`, `undo`, `capabilities`, `doctor`.
+
+Every write tool takes `dry_run`; the ui-vector tools additionally require `dangerously_drive_gui`; tools carry read-only/destructive annotations; hazard blocks come back as structured tool errors carrying the same remediation text the CLI prints. Tool descriptions follow the consumer-voice contract in [docs/design/surface-copy.md](docs/design/surface-copy.md).

package/dist/audit/log.js

@@ -2,9 +2,63 @@
  * JSONL audit writer: monthly files, never auto-deleted, structural token
  * redaction — the serializer refuses to emit any string containing the
  * loaded auth token.
+ *
+ * DURABILITY + TEAR-RESISTANCE (M5). Audit appends happen from processes that
+ * do NOT hold the mutation lock (e.g. a drift-gate or lock-contention block is
+ * recorded before/without ever acquiring it), so two things-api invocations can
+ * append to the same monthly file concurrently. The append path is therefore:
+ *
+ *   open(path, O_APPEND) → ONE writeSync(fd, completeLineBuffer) → fsyncSync → close
+ *
+ * Two properties make this safe for our use in practice, on regular files:
+ *  - ATOMIC APPEND. With O_APPEND the kernel positions the write at end-of-file
+ *    and performs the append under the inode lock, so a SINGLE write() call
+ *    cannot interleave with a concurrent write() from another fd — no torn or
+ *    spliced line. We hand writeSync the COMPLETE `${line}\n` buffer so exactly
+ *    one write() syscall carries the whole record. (The old appendFileSync path
+ *    gave neither a single-write guarantee nor a flush.)
+ *  - DURABILITY. fsyncSync flushes the record to disk before we return, so a
+ *    crash immediately after the append cannot lose an already-acknowledged
+ *    record — the pairing invariant the M3 intent record relies on holds.
+ *
+ * No lockfile is used, deliberately: for regular local files a single
+ * O_APPEND write() is already interleave-safe, our records are small and writes
+ * infrequent, and a lockfile would add a failure mode (stale locks, contention)
+ * into a path that must NEVER throw into the mutation result. A short write from
+ * write() only occurs on signals/full disks/pipes — not local regular-file
+ * appends of records this size — so the "one writeSync = one record" assumption
+ * holds; the >1MB round-trip test exercises the large-buffer case.
+ *
+ * NEVER THROWS INTO THE MUTATION PATH. If the durable path fails for any reason
+ * (fsync unsupported on an exotic FS, transient open error, …) we fall back to a
+ * best-effort plain append, and if THAT throws we swallow it: a mutation's
+ * result must never break because auditing hit an I/O error.
  */
-import { appendFileSync, mkdirSync } from "node:fs";
+import { appendFileSync, closeSync, fsyncSync, mkdirSync, openSync, writeSync } from "node:fs";
 import { join } from "node:path";
+/** Durable single-write append (O_APPEND + fsync), best-effort fallback on failure. */
+function durableAppend(path, buf) {
+    try {
+        const fd = openSync(path, "a"); // "a" → O_APPEND
+        try {
+            writeSync(fd, buf); // one write() with the complete line — atomic append
+            fsyncSync(fd); // flush to disk before returning
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    catch {
+        // Best-effort fallback: try a plain append, then give up silently. An audit
+        // write must never throw into the mutation path that called it.
+        try {
+            appendFileSync(path, buf);
+        }
+        catch {
+            /* swallow — a mutation result must never break because auditing failed */
+        }
+    }
+}
 export function createAuditWriter(options) {
     const secrets = options.secrets.filter((s) => s.length > 0);
     return {
@@ -24,7 +78,7 @@ export function createAuditWriter(options) {
                 }
                 return value;
             });
-            appendFileSync(join(options.dir, `${month}.jsonl`), `${line}\n`);
+            durableAppend(join(options.dir, `${month}.jsonl`), Buffer.from(`${line}\n`, "utf8"));
         },
     };
 }

package/dist/audit/log.js.map

@@ -1 +1 @@
-{"version":3,"file":"log.js","sourceRoot":"","sources":["../../src/audit/log.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACpD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAQjC,MAAM,UAAU,iBAAiB,CAAC,OAKjC;IACC,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC5D,OAAO;QACL,MAAM,CAAC,MAAmB;YACxB,IAAI,CAAC,OAAO,CAAC,OAAO;gBAAE,OAAO;YAC7B,SAAS,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YAC5C,MAAM,KAAK,GAAG,MAAM,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,UAAU;YAC/C,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE;gBAClD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;oBAC9B,IAAI,GAAG,GAAG,KAAK,CAAC;oBAChB,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;wBAC7B,OAAO,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC;4BAAE,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;oBACrE,CAAC;oBACD,OAAO,GAAG,CAAC;gBACb,CAAC;gBACD,OAAO,KAAK,CAAC;YACf,CAAC,CAAC,CAAC;YACH,cAAc,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,KAAK,QAAQ,CAAC,EAAE,GAAG,IAAI,IAAI,CAAC,CAAC;QACnE,CAAC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"log.js","sourceRoot":"","sources":["../../src/audit/log.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAC/F,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAQjC,uFAAuF;AACvF,SAAS,aAAa,CAAC,IAAY,EAAE,GAAW;IAC9C,IAAI,CAAC;QACH,MAAM,EAAE,GAAG,QAAQ,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC,iBAAiB;QACjD,IAAI,CAAC;YACH,SAAS,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC,qDAAqD;YACzE,SAAS,CAAC,EAAE,CAAC,CAAC,CAAC,iCAAiC;QAClD,CAAC;gBAAS,CAAC;YACT,SAAS,CAAC,EAAE,CAAC,CAAC;QAChB,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,4EAA4E;QAC5E,gEAAgE;QAChE,IAAI,CAAC;YACH,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QAC5B,CAAC;QAAC,MAAM,CAAC;YACP,0EAA0E;QAC5E,CAAC;IACH,CAAC;AACH,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,OAKjC;IACC,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC5D,OAAO;QACL,MAAM,CAAC,MAAmB;YACxB,IAAI,CAAC,OAAO,CAAC,OAAO;gBAAE,OAAO;YAC7B,SAAS,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YAC5C,MAAM,KAAK,GAAG,MAAM,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,UAAU;YAC/C,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE;gBAClD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;oBAC9B,IAAI,GAAG,GAAG,KAAK,CAAC;oBAChB,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;wBAC7B,OAAO,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC;4BAAE,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;oBACrE,CAAC;oBACD,OAAO,GAAG,CAAC;gBACb,CAAC;gBACD,OAAO,KAAK,CAAC;YACf,CAAC,CAAC,CAAC;YACH,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,KAAK,QAAQ,CAAC,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,IAAI,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;QACvF,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/audit/schema.d.ts

@@ -1,10 +1,3 @@
-/**
- * Audit record v1 — one JSON object per line in
- * ~/.local/state/things-api/audit/YYYY-MM.jsonl (see design §5).
- *
- * Every mutation ATTEMPT is recorded: successes, verification failures, and
- * blocked decisions (with invocation null — the app was never touched).
- */
 export interface AuditRecord {
     v: 1;
     ts: string;
@@ -26,13 +19,20 @@ export interface AuditRecord {
         id: string;
         role: "leg" | "summary";
     };
+    /**
+     * Undo back-reference (ADDITIVE): the undo token of the ORIGINAL mutation
+     * this record inverts. Set only on inverse mutations (`undo:<actor>` records)
+     * so a later `things undo --txn <token>` can tell an already-undone mutation
+     * apart from a nonexistent one. Absent on ordinary (non-undo) mutations.
+     */
+    undoOf?: string;
     /** Normalized requested delta (params as given, post-normalization). */
     requested: Record<string, unknown>;
     /** Asserted-field subset of the pre-state (null when target didn't exist). */
     pre: Record<string, unknown> | null;
     /** Post-verify observation (best-effort on failure). */
     observed: Record<string, unknown> | null;
-    result: "ok" | "verify-failed:timeout" | "verify-failed:mismatch" | "verify-failed:silent-noop" | `blocked:${string}` | "unsupported";
+    result: "intent" | "ok" | "verify-failed:timeout" | "verify-failed:mismatch" | "verify-failed:silent-noop" | `blocked:${string}` | "unsupported";
     verify: {
         attempts: number;
         elapsedMs: number;
@@ -44,3 +44,21 @@ export interface AuditRecord {
         fingerprint: "ok" | "drift" | "user-accepted" | "unknown";
     };
 }
+/**
+ * The stable UNDO TOKEN for a mutation — the value a caller passes to
+ * `things undo --txn <token>` (MCP `txn`) to invert exactly THIS record,
+ * immune to interleaving. Two cases:
+ *
+ *  - A compound operation's SUMMARY record already carries a real transaction
+ *    id shared by its legs — that id IS the token (undoing it replays the
+ *    whole sequence as one unit).
+ *  - A single-op record has no such id, so we derive a content-addressed one
+ *    from the fields that identify the record on disk (start timestamp + op +
+ *    actor + host + target uuid). The mutation lock serializes writes, so those
+ *    fields are unique per record in practice; the token is deterministic, so
+ *    the write path (which returns it in the result) and the undo path (which
+ *    recomputes it while scanning the trail) always agree.
+ *
+ * Purely additive: it is DERIVED from persisted fields, never stored.
+ */
+export declare function undoToken(record: Pick<AuditRecord, "ts" | "op" | "actor" | "host" | "uuid" | "txn">): string;

package/dist/audit/schema.js

@@ -4,6 +4,47 @@
  *
  * Every mutation ATTEMPT is recorded: successes, verification failures, and
  * blocked decisions (with invocation null — the app was never touched).
+ *
+ * A successful mutation writes TWO records: an `intent` marker immediately
+ * before the app is touched (M3 durability — so a crash between the app-side
+ * mutation and the final record leaves evidence the change may have landed),
+ * then the final `ok`/`verify-failed:*` record after read-after-write. The two
+ * share ts+op+actor+host (both derive from the same startedAt); an intent with
+ * no later final sibling is the signature of a crashed write. Intent records
+ * are NEVER undo targets — every undo reader filters `result === "ok"`, which
+ * an intent (result `"intent"`) is not, so it is excluded uniformly.
+ */
+import { createHash } from "node:crypto";
+/**
+ * The stable UNDO TOKEN for a mutation — the value a caller passes to
+ * `things undo --txn <token>` (MCP `txn`) to invert exactly THIS record,
+ * immune to interleaving. Two cases:
+ *
+ *  - A compound operation's SUMMARY record already carries a real transaction
+ *    id shared by its legs — that id IS the token (undoing it replays the
+ *    whole sequence as one unit).
+ *  - A single-op record has no such id, so we derive a content-addressed one
+ *    from the fields that identify the record on disk (start timestamp + op +
+ *    actor + host + target uuid). The mutation lock serializes writes, so those
+ *    fields are unique per record in practice; the token is deterministic, so
+ *    the write path (which returns it in the result) and the undo path (which
+ *    recomputes it while scanning the trail) always agree.
+ *
+ * Purely additive: it is DERIVED from persisted fields, never stored.
  */
-export {};
+export function undoToken(record) {
+    if (record.txn?.role === "summary")
+        return record.txn.id;
+    // JSON-encode the identity tuple so field boundaries are unambiguous (no
+    // separator an actor/host string could forge) while staying plain text.
+    const identity = JSON.stringify([
+        record.ts,
+        record.op,
+        record.actor,
+        record.host,
+        record.uuid ?? "",
+    ]);
+    const digest = createHash("sha256").update(identity).digest("hex").slice(0, 12);
+    return `m-${digest}`;
+}
 //# sourceMappingURL=schema.js.map

package/dist/audit/schema.js.map

@@ -1 +1 @@
-{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/audit/schema.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/audit/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAkDzC;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,SAAS,CACvB,MAA0E;IAE1E,IAAI,MAAM,CAAC,GAAG,EAAE,IAAI,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;IACzD,yEAAyE;IACzE,wEAAwE;IACxE,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC;QAC9B,MAAM,CAAC,EAAE;QACT,MAAM,CAAC,EAAE;QACT,MAAM,CAAC,KAAK;QACZ,MAAM,CAAC,IAAI;QACX,MAAM,CAAC,IAAI,IAAI,EAAE;KAClB,CAAC,CAAC;IACH,MAAM,MAAM,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAChF,OAAO,KAAK,MAAM,EAAE,CAAC;AACvB,CAAC"}

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

@@ -3,11 +3,20 @@
  * under `things area` are registered by writes.ts on the same group).
  */
 import type { Command } from "commander";
-import type { AreaView } from "../../read/area-view.ts";
+import { type AreaView, type GroupedLimits, type GroupedTruncation } from "../../index.ts";
+import { type TagFlags } from "../tag-filters.ts";
 export interface AreaShowOpts {
     showLater?: boolean;
     /** Commander optional-value flag: true when bare, the raw string when given a count. */
     showLogged?: boolean | string;
+    /**
+     * Per-section caps: `project` bounds the project-ROWS section, `area` the
+     * direct-to-dos section (null = uncapped). The toggled later/logged
+     * sections keep their own existing bounds.
+     */
+    limits?: GroupedLimits;
+    /** The user's invocation, echoed by the per-section truncation footers. */
+    hintBase?: string;
 }
 /**
  * GUI layout: active projects first (sidebar order), then the area's direct
@@ -15,6 +24,29 @@ export interface AreaShowOpts {
  * (future-scheduled projects, to-dos, and repeating templates intermixed in
  * date order) and Someday (someday projects as a leading block, then
  * someday to-dos). `--show-logged` reveals the full logbook.
+ *
+ * `view` is the already-bounded card (its ACTIVE project rows and direct to-dos
+ * capped; scheduled/someday project rows and the later/logged/trashed sections
+ * intact) and `grouped` the per-block metadata carrying each capped section's
+ * pre-cap total — so the "… N more" footers derive from metadata, never a
+ * pre-cap copy of the view.
  */
-export declare function renderAreaView(view: AreaView, opts: AreaShowOpts): string[];
+export declare function renderAreaView(view: AreaView, grouped: GroupedTruncation, opts: AreaShowOpts): string[];
+/** Options accepted by the area-show code path (shared by `area show` and `areas <ref>`). */
+export type AreaShowActionOpts = AreaShowOpts & TagFlags & {
+    json?: boolean;
+    db?: string;
+    limit?: string;
+    areaLimit?: string;
+    projectLimit?: string;
+    all?: boolean;
+    /** Content scope: keep only rows (loose to-dos + child projects) with an overdue own deadline. */
+    overdue?: boolean;
+};
+/**
+ * The `area show <ref>` action body, factored out so the pluralized
+ * `things areas <ref>` can delegate to the identical code path (a true synonym,
+ * not a reimplementation). Both echo the canonical `things area show …` hint.
+ */
+export declare function runAreaShow(ref: string, opts: AreaShowActionOpts): void;
 export declare function registerAreaCommands(program: Command): void;

package/dist/cli/commands/area.js

@@ -1,7 +1,13 @@
-import { localToday } from "../../model/dates.js";
 import { bold, dim, green } from "../style.js";
 import { areaMark, thingsLink } from "../glyphs.js";
-import { formatItem, openInThings, uuidDisplayWidth, withClient } from "./reads.js";
+import { Option } from "commander";
+import { openInThings } from "./reads.js";
+import { invocation, parseCap, runRead, shellQuote, usageError, withClient, } from "../read-driver.js";
+import { disclosureHint, formatItem, quoteTitle, uuidDisplayWidth } from "../render.js";
+import { DidYouMeanError } from "../did-you-mean.js";
+import { showToggleFlags } from "./project.js";
+import { AREA_PREVIEW_LIMIT, GROUPED_ALL_DESC, isActiveProjectRow, isScheduledProjectRow, isSomedayProjectRow, localToday, } from "../../index.js";
+import { addTagFilterOptions, CONTAINER_TAG_HINT, tagFilterFields, tagFlagConflict, tagInvocationParts, } from "../tag-filters.js";
 /** Bare `--show-logged` shows this many recent entries (areas accumulate thousands). */
 const RECENT_LOGGED_DEFAULT = 15;
 function loggedCount(showLogged) {
@@ -18,22 +24,28 @@ function loggedCount(showLogged) {
  * (future-scheduled projects, to-dos, and repeating templates intermixed in
  * date order) and Someday (someday projects as a leading block, then
  * someday to-dos). `--show-logged` reveals the full logbook.
+ *
+ * `view` is the already-bounded card (its ACTIVE project rows and direct to-dos
+ * capped; scheduled/someday project rows and the later/logged/trashed sections
+ * intact) and `grouped` the per-block metadata carrying each capped section's
+ * pre-cap total — so the "… N more" footers derive from metadata, never a
+ * pre-cap copy of the view.
  */
-export function renderAreaView(view, opts) {
+export function renderAreaView(view, grouped, opts) {
     const todayIso = localToday();
-    // Closed-but-unswept projects always sit in the active block (checked),
-    // never in Upcoming/Someday — start/startDate only classify OPEN rows.
-    const isSomedayProject = (p) => p.status === "open" && p.start === "someday" && p.startDate === null;
-    const isScheduledProject = (p) => p.status === "open" && p.startDate !== null && p.startDate > todayIso;
-    const activeProjects = view.projects.filter((p) => !isSomedayProject(p) && !isScheduledProject(p));
-    const somedayProjects = view.projects.filter(isSomedayProject);
+    // The card's ACTIVE project rows are already capped in `view`; scheduled and
+    // someday rows always survive and route to the Upcoming/Someday sections.
+    const activeProjects = view.projects.filter((p) => isActiveProjectRow(p, todayIso));
+    const somedayProjects = view.projects.filter(isSomedayProjectRow);
     // Upcoming intermixes scheduled projects, scheduled to-dos, and repeating
     // templates in date order (templates sort by their next occurrence).
     const upcoming = [
-        ...view.projects.filter(isScheduledProject).map((p) => ({ date: p.startDate ?? "", item: p })),
+        ...view.projects
+            .filter((p) => isScheduledProjectRow(p, todayIso))
+            .map((p) => ({ date: p.startDate ?? "", item: p })),
         ...view.later.scheduled.flatMap((d) => d.items.map((t) => ({ date: d.date, item: t }))),
         ...view.later.repeating.map((t) => ({ date: t.repeating.nextOccurrence ?? "9999", item: t })),
-    ].sort((a, b) => a.date.localeCompare(b.date));
+    ].toSorted((a, b) => a.date.localeCompare(b.date));
     const logged = view.logged.slice(0, loggedCount(opts.showLogged));
     const shown = [
         ...activeProjects,
@@ -44,9 +56,35 @@ export function renderAreaView(view, opts) {
         ...logged,
     ];
     const w = uuidDisplayWidth(shown);
-    // Rows inside this view never repeat the area's own name.
+    // Per-section caps (this view's sections are containers, so there is no
+    // strict total limit): the project-ROWS block and the direct-to-dos block
+    // truncate independently, each with its own exact-count footer. The card
+    // preamble and the toggled later/logged sections are never capped. The pre-cap
+    // totals come from the metadata; `limits` supplies the footer's doubling.
+    const limits = opts.limits ?? { area: null, project: null };
+    const projectsBlock = grouped.blocks.find((b) => b.kind === "projects");
+    const activeBlock = grouped.blocks.find((b) => b.kind === "area");
+    const hiddenProjects = projectsBlock ? projectsBlock.total - projectsBlock.shown : 0;
+    const hiddenActive = activeBlock ? activeBlock.total - activeBlock.shown : 0;
+    // The user's invocation, echoed by every disclosure hint (falls back to a
+    // canonical typed command when a caller omits it, e.g. a direct unit test).
+    const base = opts.hintBase ?? `things area show ${quoteTitle(view.area.title)}`;
+    // A per-block TRUNCATION FOOTER (indented two spaces under its partially-
+    // shown block): `  … N more <noun>s — `<base> <flag> <bigger>``.
+    const sectionMore = (hidden, noun, flag, cap) => {
+        if (hidden <= 0 || opts.hintBase === undefined || cap === null)
+            return;
+        lines.push(disclosureHint(hidden, `more ${noun}`, [{ command: `${opts.hintBase} ${flag} ${cap * 2}` }], {
+            indent: true,
+        }));
+    };
+    // Rows inside this view never repeat the area's own name. The area's top
+    // projects are plain ROWS here (not group headings — they don't head a to-do
+    // group in this view), so they get the bold project title from delta 1 but NO
+    // underline; only ANYTIME treats projects as headings. So a project renders
+    // exactly like any other row here — no projectTitle opt.
     const fmt = (i) => formatItem(i, w, { suppressArea: view.area.uuid });
-    const fmtProject = (i) => formatItem(i, w, { projectTitle: true, suppressArea: view.area.uuid });
+    const fmtProject = fmt;
     // Card header: glyph + name, the GUI's share link (carries the uuid — it
     // pastes back into any ref argument), then labeled meta lines. The opened
     // resource shows its tags green (GUI: list pills are gray).
@@ -61,7 +99,9 @@ export function renderAreaView(view, opts) {
             lines.push("", ...rows);
     };
     block(activeProjects.map(fmtProject));
+    sectionMore(hiddenProjects, "project", "--project-limit", limits.project);
     block(view.active.map(fmt));
+    sectionMore(hiddenActive, "to-do", "--area-limit", limits.area);
     if (activeProjects.length === 0 && view.active.length === 0)
         lines.push("", "(no active items)");
     if (opts.showLater === true) {
@@ -77,42 +117,114 @@ export function renderAreaView(view, opts) {
             }
         }
     }
-    // Default-hidden rows are never silent — a muted count names the toggle.
+    // Default-hidden rows are never silent — a HIDDEN-SECTION placeholder (flush,
+    // full command) stands where the Upcoming/Someday sections would render.
     if (opts.showLater !== true) {
         const hiddenLater = upcoming.length + somedayProjects.length + view.later.someday.length;
         if (hiddenLater > 0)
-            lines.push("", dim(`…${hiddenLater} later item${hiddenLater === 1 ? "" : "s"} (--show-later)`));
+            lines.push("", disclosureHint(hiddenLater, "later item", [{ command: `${base} --show-later` }]));
     }
+    // The full archive belongs to `things logbook --area <ref>` — echoed
+    // ready-to-paste with the real area name, like every other drill hint.
+    const logbookCmd = `things logbook --area ${quoteTitle(view.area.title)}`;
     if (logged.length > 0) {
-        // Truncation is loud: areas accumulate years of history — the full
-        // archive belongs to `things logbook --area`.
-        const header = logged.length < view.logged.length
-            ? `── Logged (${logged.length} of ${view.logged.length} — see things logbook --area) ──`
+        // Truncation is loud: areas accumulate years of history. The header keeps
+        // the shown-of-total count for orientation; the actionable drill rides a
+        // section footer (matching the other truncated sections), never the header.
+        const more = view.logged.length - logged.length;
+        const header = more > 0
+            ? `── Logged (${logged.length} of ${view.logged.length}) ──`
             : `── Logged (${view.logged.length}) ──`;
         lines.push("", bold(header), ...logged.map(fmt));
+        if (more > 0)
+            lines.push(dim(`… ${more} more — \`${logbookCmd}\``));
     }
     else if (view.logged.length > 0) {
-        lines.push("", dim(`…${view.logged.length} logged (--show-logged; full history: things logbook --area)`));
+        // Hidden-section placeholder: `--show-logged` reveals only the RECENT 15
+        // (areas accumulate years), so it is labeled; the logbook drill reads its
+        // own effect and needs none.
+        lines.push("", disclosureHint(view.logged.length, "logged item", [
+            { label: "recent", command: `${base} --show-logged` },
+            { command: logbookCmd },
+        ]));
     }
     if (view.trashed.length)
         lines.push("", bold(`── Trashed (${view.trashed.length}) ──`));
     return lines;
 }
+/**
+ * The `area show <ref>` action body, factored out so the pluralized
+ * `things areas <ref>` can delegate to the identical code path (a true synonym,
+ * not a reimplementation). Both echo the canonical `things area show …` hint.
+ */
+export function runAreaShow(ref, opts) {
+    if (tagFlagConflict(opts))
+        return;
+    if (opts.limit !== undefined) {
+        usageError(opts, "--limit is not available on area show — cap sections with --area-limit / --project-limit, or pass --all");
+        return;
+    }
+    const areaCap = parseCap("--area-limit", opts.areaLimit, AREA_PREVIEW_LIMIT, opts.all === true, opts.json === true);
+    if (!areaCap.ok)
+        return;
+    const projectCap = parseCap("--project-limit", opts.projectLimit, AREA_PREVIEW_LIMIT, opts.all === true, opts.json === true);
+    if (!projectCap.ok)
+        return;
+    const overdue = opts.overdue === true;
+    const tagFilter = tagFilterFields(opts);
+    const limits = { area: areaCap.limit, project: projectCap.limit };
+    const hintBase = invocation("area show", [
+        shellQuote(ref),
+        ...showToggleFlags(opts),
+        overdue && "--overdue",
+        ...tagInvocationParts(opts),
+    ]);
+    runRead(opts, "area-view", (c) => {
+        let bounded;
+        try {
+            bounded = c.read.areaView(ref, {
+                overdue,
+                ...tagFilter,
+                areaLimit: areaCap.limit,
+                projectLimit: projectCap.limit,
+            });
+        }
+        catch (err) {
+            // Not-found gets a type-scoped did-you-mean; ambiguity is verbatim.
+            if (err instanceof RangeError && !err.message.includes("ambiguous")) {
+                throw new DidYouMeanError(err.message, ref, c.read.liteTitleSearch(ref, { type: "area" }));
+            }
+            throw err;
+        }
+        return {
+            data: bounded.view,
+            grouped: bounded.grouped,
+            lines: renderAreaView(bounded.view, bounded.grouped, { ...opts, limits, hintBase }),
+        };
+    }, () => []);
+}
 export function registerAreaCommands(program) {
     const area = program.command("area").description("Area-scoped operations");
-    area
+    const areaShow = area
         .command("show <ref>")
         .description("Composite area view mirroring the native UI: active projects first, then the " +
         "area's direct to-dos. --show-later adds the Upcoming (date-ordered) and " +
-        "Someday sections; --show-logged adds the full logbook. Target by uuid or " +
-        "unique name.")
+        "Someday sections; --show-logged adds the full logbook. --tag / --untagged filter " +
+        "the rows by a tag carried directly on the row — tags inherited from this area are " +
+        "ignored (every row inherits them); no descent into project contents. Target by " +
+        "uuid or unique name.")
         .option("--show-later", "include Upcoming and Someday sections")
         .option("--show-logged [n]", "include the n most recently logged items (bare flag = 15; full history via `things logbook --area`)")
+        .option("--project-limit <n>", `maximum project rows to show (default ${AREA_PREVIEW_LIMIT})`)
+        .option("--area-limit <n>", `maximum direct to-dos to show (default ${AREA_PREVIEW_LIMIT})`)
+        .option("--overdue", "only rows whose own deadline is past (due today is not overdue)")
+        .option("--all", GROUPED_ALL_DESC)
+        .addOption(new Option("--limit <n>").hideHelp())
         .option("--json", "emit versioned JSON envelope on stdout")
-        .option("--db <path>", "explicit database path")
-        .action((ref, opts) => {
-        withClient(opts, "area-view", (c) => c.read.areaView(ref), ((d) => renderAreaView(d, opts)));
-    });
+        .option("--db <path>", "explicit database path");
+    addTagFilterOptions(areaShow)
+        .addHelpText("after", CONTAINER_TAG_HINT)
+        .action((ref, opts) => runAreaShow(ref, opts));
     area
         .command("open <ref>")
         .description("Open the area in the Things app — foregrounds the GUI on this Mac (NOT headless). Errors when the reference is not an area.")
@@ -124,7 +236,7 @@ export function registerAreaCommands(program) {
             if (t.kind !== "area")
                 throw new RangeError(`"${ref}" is a ${t.viaHeading === true ? "heading" : t.kind}, not an area (try \`things open\`)`);
             return { uri: openInThings(t.uuid) };
-        }, ((d) => [`opened ${d.uri}`]));
+        }, (d) => [`opened ${d.uri}`]);
     });
 }
 //# sourceMappingURL=area.js.map