things-api 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mike Greiling
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,77 @@
+# things-api
+
+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 (v0.3.0 — see [CHANGELOG.md](CHANGELOG.md)).** Reads go straight to the local SQLite database (UI-exact Today ordering, decoded repeat rules, occurrence projections); writes run a verified pipeline over two lab-validated vectors (URL scheme + AppleScript) with hazard guards, disruption-tier policy, a JSONL audit trail, batch mode, audit-replay undo, full project lifecycle (complete/cancel/reopen/restore), container detach, granular stateful checklists, and tag hierarchy management incl. un-nesting. 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 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)
+things capabilities --op todo.delete   # what's possible, per vector, with evidence
+```
+
+## 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.
+
+### Development install
+
+To get a global `things` command that runs the live TypeScript source (no build step — Node ≥ 24 strips types natively):
+
+```sh
+npm link            # symlink this checkout as the global things-api package
+asdf reshim nodejs  # once, if you use asdf: expose the new `things` shim
+```
+
+Edits under `src/` take effect immediately. The bin launcher ([bin/things.js](bin/things.js)) prefers `src/` when present and falls back to `dist/`, so published installs (`npm i -g things-api`, `npx things-api`) run the compiled output with identical behavior.
+
+## 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).
+- **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.
+- **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.
+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/a project/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. Evening reorders never touch it — they use verified `when=` round-trips (the "bounce", ≤10 items) instead.
+
+A typical mutation flow:
+
+```sh
+things capabilities --op todo.move --json      # is it possible, which vector, what tier?
+things search "Buy milk" --json                # resolve the uuid (open items; scope with --project/--area/--tag, widen with --logged/--trashed/--all)
+things todo move <uuid> --project "Errands" --dry-run --json   # inspect the plan
+things todo move <uuid> --project "Errands" --json             # execute, verified
+things changes --since 2026-07-05T08:00 --json # what changed since the agent last looked
+things batch inbox-triage.jsonl                # N ops, each guarded+verified, JSONL results
+things undo --dry-run                          # inverse plan for the last mutation (audit replay)
+things undo                                    # execute it — verified like any mutation
+```
+
+Failure modes are first-class: a `verify-failed:silent-noop` means the app accepted the command and did nothing (a real Things behavior the guards mostly prevent — see [docs/things-app-oddities.md](docs/things-app-oddities.md)); `blocked:*` responses include machine-readable remediation.
+
+## Architecture: one library, thin surfaces
+
+The TypeScript library (`import { openThings } from "things-api"`) is the product; the CLI and the MCP server are thin presentation layers over the same `ThingsClient` — every read view and every verified mutation is a client method first. Shared machine contracts (JSON envelope, exit codes) live in the core (`contracts.ts`), and `diagnose()` / `capabilitiesTable()` are library functions the surfaces merely render.
+
+### MCP server
+
+`things mcp` serves the Model Context Protocol over stdio. Configure it in any MCP client:
+
+```json
+{ "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).

package/bin/things.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env -S node --disable-warning=ExperimentalWarning
+// Dev checkouts (npm link) run live TS source via Node's type stripping;
+// published tarballs ship only dist + bin, so src is absent and dist is used.
+import { existsSync } from "node:fs";
+
+const src = new URL("../src/cli/main.ts", import.meta.url);
+const entry = existsSync(src) ? src : new URL("../dist/cli/main.js", import.meta.url);
+const { runCli } = await import(entry.href);
+runCli();

package/dist/audit/log.d.ts

@@ -0,0 +1,10 @@
+import type { AuditRecord } from "./schema.ts";
+export interface AuditWriter {
+    append(record: AuditRecord): void;
+}
+export declare function createAuditWriter(options: {
+    dir: string;
+    /** Secrets to structurally redact from every string field. */
+    secrets: string[];
+    enabled: boolean;
+}): AuditWriter;

package/dist/audit/log.js

@@ -0,0 +1,31 @@
+/**
+ * JSONL audit writer: monthly files, never auto-deleted, structural token
+ * redaction — the serializer refuses to emit any string containing the
+ * loaded auth token.
+ */
+import { appendFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+export function createAuditWriter(options) {
+    const secrets = options.secrets.filter((s) => s.length > 0);
+    return {
+        append(record) {
+            if (!options.enabled)
+                return;
+            mkdirSync(options.dir, { recursive: true });
+            const month = record.ts.slice(0, 7); // YYYY-MM
+            const line = JSON.stringify(record, (_key, value) => {
+                if (typeof value === "string") {
+                    let out = value;
+                    for (const secret of secrets) {
+                        while (out.includes(secret))
+                            out = out.replace(secret, "REDACTED");
+                    }
+                    return out;
+                }
+                return value;
+            });
+            appendFileSync(join(options.dir, `${month}.jsonl`), `${line}\n`);
+        },
+    };
+}
+//# sourceMappingURL=log.js.map

package/dist/audit/log.js.map

@@ -0,0 +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"}

package/dist/audit/schema.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 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;
+    actor: string;
+    host: string;
+    op: string;
+    /** Target uuid; null until discovered for creates that verify by probe. */
+    uuid: string | null;
+    vector: string | null;
+    disruption: number | null;
+    /** Compiled invocation with the auth token structurally redacted. */
+    invocation: string | null;
+    /** 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";
+    verify: {
+        attempts: number;
+        elapsedMs: number;
+    } | null;
+    durationMs: number;
+    env: {
+        pkg: string;
+        dbVersion: number | null;
+        fingerprint: "ok" | "drift" | "user-accepted" | "unknown";
+    };
+}

package/dist/audit/schema.js

@@ -0,0 +1,9 @@
+/**
+ * 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 {};
+//# sourceMappingURL=schema.js.map

package/dist/audit/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/audit/schema.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

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

@@ -0,0 +1,9 @@
+/**
+ * `things doctor` — thin CLI surface over the library's diagnose().
+ * Exit codes: 0 healthy; 5 drift/unknown-version; 7 environment problems.
+ */
+import type { Command } from "commander";
+import { type DiagnoseReport, type DiagnoseResult } from "../../diagnose.ts";
+export type DoctorReport = DiagnoseReport;
+export declare const runDoctor: (dbPath?: string) => DiagnoseResult;
+export declare function registerDoctor(program: Command): void;

package/dist/cli/commands/doctor.js

@@ -0,0 +1,60 @@
+import { diagnose } from "../../diagnose.js";
+import { describeEnvironmentChanges } from "../../write/environment.js";
+import { errorEnvelope, okEnvelope } from "../../contracts.js";
+export const runDoctor = diagnose;
+function environmentLine(env) {
+    if (env.lastVerifiedWrite === null) {
+        return "no verified write recorded yet (the tuple is recorded on the first successful write)";
+    }
+    if (env.changes.length === 0)
+        return "unchanged since the last verified write";
+    return (`CHANGED since the last verified write — ${describeEnvironmentChanges(env.changes)} ` +
+        "(a macOS consent prompt may reappear on the next automation call)");
+}
+export function registerDoctor(program) {
+    program
+        .command("doctor")
+        .description("Check environment health: database location, database schema compatibility, app " +
+        "presence, any one-time setup still needed (macOS permissions, the app's " +
+        "'Enable Things URLs' setting), and whether the environment changed since the last " +
+        "successful write — with steps to fix. " +
+        "Exit 0 healthy; 5 schema drift (writes disabled); 7 environment problem.")
+        .option("--json", "emit versioned JSON envelope on stdout")
+        .option("--db <path>", "explicit database path (overrides THINGS_DB and discovery)")
+        .option("--probe-automation", "actively test whether automation of Things is authorized (may show a one-time macOS " +
+        "consent prompt; skipped when Things is not running)")
+        .action((opts) => {
+        const started = Date.now();
+        const { report, error, exitCode, meta } = diagnose(opts.db, {
+            ...(opts.probeAutomation === true && { probeAutomation: true }),
+        });
+        const fullMeta = { ...meta, elapsedMs: Date.now() - started };
+        if (opts.json) {
+            const envelope = report
+                ? okEnvelope("doctor", report, fullMeta)
+                : errorEnvelope(error ?? { code: "unexpected", message: "no report" }, fullMeta);
+            process.stdout.write(`${JSON.stringify(envelope)}\n`);
+        }
+        else if (report) {
+            const lines = [
+                `db:          ${report.db.path} (${report.db.source})`,
+                `db version:  ${report.db.databaseVersion ?? "unknown"}`,
+                `fingerprint: ${report.fingerprint.status} (${report.fingerprint.value.slice(0, 23)}…)`,
+                ...report.fingerprint.detail.map((d) => `  drift: ${d}`),
+                `app:         ${report.app.installed ? "installed" : "NOT INSTALLED"}`,
+                `writes:      ${report.writes.enabled ? "enabled" : "DISABLED"} — ${report.writes.reason}`,
+                `experimental: ${report.experimental.reason}`,
+                `environment: ${environmentLine(report.environment)}`,
+                `automation:  ${report.automation.status}${report.automation.status === "granted" ? "" : ` — ${report.automation.detail}`}`,
+            ];
+            process.stdout.write(`${lines.join("\n")}\n`);
+        }
+        else if (error) {
+            process.stderr.write(`doctor: ${error.message}\n`);
+            if (error.remediation)
+                process.stderr.write(`  remediation: ${error.remediation}\n`);
+        }
+        process.exitCode = exitCode;
+    });
+}
+//# sourceMappingURL=doctor.js.map

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

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

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

@@ -0,0 +1,7 @@
+/**
+ * `things mcp` — serve the MCP surface over stdio. Agents configure this as
+ * their MCP server command: { "command": "things", "args": ["mcp"] }.
+ * MCP protocol traffic owns stdout; all logging goes to stderr.
+ */
+import type { Command } from "commander";
+export declare function registerMcp(program: Command): void;

package/dist/cli/commands/mcp.js

@@ -0,0 +1,26 @@
+export function registerMcp(program) {
+    program
+        .command("mcp")
+        .description("Serve the Things MCP server on stdio (Model Context Protocol). Tools cover the full " +
+        "surface: read views, search, changes, item detail, to-do/project/area/tag " +
+        "mutations, batch, reorder, undo, capabilities, doctor; the server instructions " +
+        "carry the user's live area/tag/project inventory. Configure in an MCP client as " +
+        'command `things` with args ["mcp"].')
+        .option("--db <path>", "explicit database path")
+        .action(async (opts) => {
+        // LAZY imports: the MCP SDK + zod load only when `things mcp` actually
+        // runs. Every other CLI command must work in environments that ship a
+        // minimal dependency set (the guest e2e bundle carries only commander).
+        const [{ createThingsMcpServer }, { StdioServerTransport }] = await Promise.all([
+            import("../../mcp/server.js"),
+            import("@modelcontextprotocol/sdk/server/stdio.js"),
+        ]);
+        const server = createThingsMcpServer(opts.db !== undefined ? { dbPath: opts.db } : {});
+        const transport = new StdioServerTransport();
+        await server.connect(transport);
+        process.stderr.write("things-api MCP server listening on stdio\n");
+        // The transport keeps the process alive; exit cleanly when it closes.
+        transport.onclose = () => process.exit(0);
+    });
+}
+//# sourceMappingURL=mcp.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.js","sourceRoot":"","sources":["../../../src/cli/commands/mcp.ts"],"names":[],"mappings":"AAOA,MAAM,UAAU,WAAW,CAAC,OAAgB;IAC1C,OAAO;SACJ,OAAO,CAAC,KAAK,CAAC;SACd,WAAW,CACV,sFAAsF;QACpF,4EAA4E;QAC5E,iFAAiF;QACjF,kFAAkF;QAClF,qCAAqC,CACxC;SACA,MAAM,CAAC,aAAa,EAAE,wBAAwB,CAAC;SAC/C,MAAM,CAAC,KAAK,EAAE,IAAqB,EAAE,EAAE;QACtC,uEAAuE;QACvE,sEAAsE;QACtE,wEAAwE;QACxE,MAAM,CAAC,EAAE,qBAAqB,EAAE,EAAE,EAAE,oBAAoB,EAAE,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;YAC9E,MAAM,CAAC,qBAAqB,CAAC;YAC7B,MAAM,CAAC,2CAA2C,CAAC;SACpD,CAAC,CAAC;QACH,MAAM,MAAM,GAAG,qBAAqB,CAAC,IAAI,CAAC,EAAE,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACvF,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;QAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QAChC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,4CAA4C,CAAC,CAAC;QACnE,sEAAsE;QACtE,SAAS,CAAC,OAAO,GAAG,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC5C,CAAC,CAAC,CAAC;AACP,CAAC"}

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

@@ -0,0 +1,5 @@
+/**
+ * `things project show <uuid>` — the composite project view.
+ */
+import type { Command } from "commander";
+export declare function registerProjectCommands(program: Command): void;

package/dist/cli/commands/project.js

@@ -0,0 +1,50 @@
+import { formatItem, withClient } from "./reads.js";
+function renderProjectView(view) {
+    const everyItem = [
+        ...view.active,
+        ...view.headings.flatMap((g) => g.items),
+        ...view.later.scheduled.flatMap((d) => d.items),
+        ...view.later.repeating,
+        ...view.later.someday,
+        ...view.logged.slice(0, 10),
+    ];
+    const w = everyItem.reduce((max, i) => Math.max(max, i.uuid.length), 0);
+    const fmt = (i) => formatItem(i, w);
+    const lines = [
+        `${view.project.uuid}  ${view.project.title}`,
+        `  area: ${view.project.area?.title ?? "—"}  open: ${view.project.openUntrashedLeafActionsCount}/${view.project.untrashedLeafActionsCount}`,
+    ];
+    lines.push("── Active ──", ...(view.active.length ? view.active.map(fmt) : ["(none)"]));
+    for (const group of view.headings) {
+        lines.push(`── ${group.heading.title} ──`, ...(group.items.length ? group.items.map(fmt) : ["(none)"]));
+    }
+    if (view.later.scheduled.length || view.later.repeating.length || view.later.someday.length) {
+        lines.push("── Later ──");
+        for (const day of view.later.scheduled) {
+            lines.push(`  ${day.date}:`, ...day.items.map(fmt));
+        }
+        if (view.later.repeating.length) {
+            lines.push("  repeating templates:", ...view.later.repeating.map(fmt));
+        }
+        if (view.later.someday.length) {
+            lines.push("  someday:", ...view.later.someday.map(fmt));
+        }
+    }
+    if (view.logged.length)
+        lines.push(`── Logged (${view.logged.length}) ──`, ...view.logged.slice(0, 10).map(fmt));
+    if (view.trashed.length)
+        lines.push(`── Trashed (${view.trashed.length}) ──`);
+    return lines;
+}
+export function registerProjectCommands(program) {
+    const project = program.command("project").description("Project-scoped operations");
+    project
+        .command("show <uuid>")
+        .description("Composite project view mirroring the native UI: active items, headings, later (scheduled/repeating/someday), logged, trashed")
+        .option("--json", "emit versioned JSON envelope on stdout")
+        .option("--db <path>", "explicit database path")
+        .action((uuid, opts) => {
+        withClient(opts, "project-view", (c) => c.read.projectView(uuid), renderProjectView);
+    });
+}
+//# sourceMappingURL=project.js.map

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

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

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

@@ -0,0 +1,21 @@
+/**
+ * Read-only list commands. Each renders a compact human table (UUIDs always
+ * shown — agents and humans both need stable references) or a --json envelope.
+ */
+import type { Command } from "commander";
+import { type ThingsClient } from "../../client.ts";
+import { type ListItem } from "../../read/views.ts";
+interface GlobalReadOpts {
+    json?: boolean;
+    db?: string;
+}
+export declare function withClient(opts: GlobalReadOpts, kind: string, fn: (client: ThingsClient) => unknown, render: (data: never) => string[]): void;
+/**
+ * One item line: `<uuid>  <marker> [meta …] <title> (container)`. The uuid
+ * column pads to `uuidWidth` (uuids vary 21–22 chars) so the marker column
+ * aligns; exactly one space separates every following token. Meta tokens are
+ * colorized on a TTY only (see ../style.ts) — piped output stays plain.
+ */
+export declare function formatItem(item: ListItem, uuidWidth?: number): string;
+export declare function registerReadCommands(program: Command): void;
+export {};