things-api 0.9.0 → 0.11.0

package/dist/cli/read-driver.d.ts

@@ -1,22 +1,28 @@
-/**
- * The read driver: open the client, stamp the envelope meta, and emit either
- * the `--json` envelope or human lines (with the TTY-only title preamble,
- * normalized-form echo, and truncation hint). Plus the shared `--limit`/`--all`
- * cap parsing and the invocation-echo helpers every read command reuses. No
- * commander dependency — command registration lives in the command modules.
- */
-import { type ThingsClient } from "../client.ts";
-import { type GroupedPagination, type Pagination } from "../contracts.ts";
+import { type GroupedTruncation, type ThingsClient, type Truncation } from "../index.ts";
 export interface GlobalReadOpts {
     json?: boolean;
     db?: string;
 }
+/**
+ * The single usage-error emitter every command surface routes flag/argument
+ * errors through, so `--json` is honored uniformly: under `--json` a
+ * `{ok:false, error:{code:"usage", …}}` envelope goes to STDOUT (machine
+ * consumers read one stream); otherwise the prose `error:` line goes to
+ * STDERR. `details` carries the same machine-readable `candidates`/`suggestions`
+ * shape the resolver errors use. Always sets the Usage exit code.
+ */
+export declare function usageError(opts: {
+    json?: boolean;
+}, message: string, details?: {
+    candidates?: unknown[];
+    suggestions?: string[];
+}): void;
 export interface PagedResult<T> {
     data: T;
     /** Flat-view truncation — carried into meta and the appended hint. */
-    pagination?: Pagination;
+    truncation?: Truncation;
     /** Grouped-view (anytime/someday) per-block truncation — carried into meta. */
-    grouped?: GroupedPagination;
+    grouped?: GroupedTruncation;
     /**
      * Precomputed human lines. Grouped views render inside `fn` (where the full
      * per-block totals live) and hand the finished lines back here; when absent,
@@ -26,7 +32,7 @@ export interface PagedResult<T> {
 }
 /**
  * The shared read driver: open the client, stamp the envelope meta (including
- * fingerprint + optional pagination), and either emit the `--json` envelope or
+ * fingerprint + optional truncation), and either emit the `--json` envelope or
  * render human lines. When `hintBase` is given and the result was truncated,
  * the muted "N more items" hint (reconstructing the user's own invocation) is
  * appended to the human output — never to `--json`. When `header` names a view,
@@ -55,22 +61,23 @@ export type LimitResolution = {
 export declare function parseLimit(opts: {
     limit?: string;
     all?: boolean;
+    json?: boolean;
 }): LimitResolution;
 /**
  * Resolve one cap flag (`--limit`, `--area-limit`, `--project-limit`) against
  * `--all`: positive integer required, `--all` conflicts with an explicit
- * value and otherwise lifts the cap (null). The conflict/default decision is
- * the shared {@link resolveCap}; this surface adds the string→integer
- * validation and the usage-error emission.
+ * value and otherwise lifts the cap (null). This surface owns the string→integer
+ * validation and the usage-error emission; the client re-applies the same
+ * conflict/default semantics on the resolved value it receives.
  */
-export declare function parseCap(flag: string, value: string | undefined, defaultLimit: number, all: boolean): LimitResolution;
+export declare function parseCap(flag: string, value: string | undefined, defaultLimit: number, all: boolean, json?: boolean): LimitResolution;
 export { shellQuote } from "./shell-quote.ts";
 /** Reconstruct `things <name> <flags…>`, dropping falsy/empty parts. */
 export declare function invocation(name: string, parts: Array<string | false | undefined>): string;
 /**
- * The unified truncation hint: a muted `── N more items — see more: … · all:
- * … ──` line whose commands echo the user's actual invocation, so a bigger
+ * The unified truncation hint: a muted `── N more items — see more: … · … ──`
+ * line whose commands echo the user's actual invocation, so a bigger
  * `--limit` or `--all` is one copy-paste away. Returns null when nothing was
  * dropped or the caller already asked for every row.
  */
-export declare function truncationHint(base: string, pagination: Pagination): string | null;
+export declare function truncationHint(base: string, truncation: Truncation): string | null;

package/dist/cli/read-driver.js

@@ -5,19 +5,32 @@
  * cap parsing and the invocation-echo helpers every read command reuses. No
  * commander dependency — command registration lives in the command modules.
  */
-import { openThings } from "../client.js";
-import { ThingsDbNotFoundError } from "../db/locate.js";
-import { ThingsDbOpenError } from "../db/connection.js";
 import { getInvocation } from "./resolve-invocation.js";
 import { dim } from "./style.js";
 import { viewHeaderLines } from "./render.js";
 import { candidatesJson, DidYouMeanError, renderDidYouMean } from "./did-you-mean.js";
-import { errorEnvelope, ExitCode, okEnvelope, } from "../contracts.js";
-import { resolveCap } from "../read/caps.js";
-import { DEFAULT_LIST_LIMIT } from "../read/pagination.js";
+import { ClockError, DEFAULT_LIST_LIMIT, errorEnvelope, ExitCode, okEnvelope, omitEmpty, openThings, ReferenceResolutionError, schemaWarnings, ThingsDbNotFoundError, ThingsDbOpenError, } from "../index.js";
+/**
+ * The single usage-error emitter every command surface routes flag/argument
+ * errors through, so `--json` is honored uniformly: under `--json` a
+ * `{ok:false, error:{code:"usage", …}}` envelope goes to STDOUT (machine
+ * consumers read one stream); otherwise the prose `error:` line goes to
+ * STDERR. `details` carries the same machine-readable `candidates`/`suggestions`
+ * shape the resolver errors use. Always sets the Usage exit code.
+ */
+export function usageError(opts, message, details) {
+    if (opts.json === true) {
+        const meta = { dbVersion: null, fingerprint: "unknown", elapsedMs: 0 };
+        process.stdout.write(`${JSON.stringify(errorEnvelope({ code: "usage", message, ...(details !== undefined && { details }) }, meta))}\n`);
+    }
+    else {
+        process.stderr.write(`error: ${message}\n`);
+    }
+    process.exitCode = ExitCode.Usage;
+}
 /**
  * The shared read driver: open the client, stamp the envelope meta (including
- * fingerprint + optional pagination), and either emit the `--json` envelope or
+ * fingerprint + optional truncation), and either emit the `--json` envelope or
  * render human lines. When `hintBase` is given and the result was truncated,
  * the muted "N more items" hint (reconstructing the user's own invocation) is
  * appended to the human output — never to `--json`. When `header` names a view,
@@ -28,37 +41,50 @@ export function runRead(opts, kind, fn, render, hintBase, header) {
     // An empty --db would silently fall through to the default database path —
     // reject it loudly instead of reading somewhere the caller did not name.
     if (opts.db !== undefined && opts.db.trim() === "") {
-        process.stderr.write("error: --db requires a non-empty path\n");
-        process.exitCode = ExitCode.Usage;
+        usageError(opts, "--db requires a non-empty path");
         return;
     }
     let client = null;
     try {
         client = openThings(opts.db ? { dbPath: opts.db } : {});
         const fp = client.fingerprint();
-        const { data, pagination, grouped, lines: precomputed } = fn(client);
+        // Reads never block on a schema change — they warn (design decision). The
+        // note reuses the same cached fingerprint the write path gates on.
+        const warnings = schemaWarnings(client.schemaStatus());
+        const { data, truncation, grouped, lines: precomputed } = fn(client);
         // The canonical command a sugar invocation normalized to — known now that
         // `fn` has resolved any reference. Present only for the routing sugars
         // (bare noun, keyword-in-show, uuid/share-link routing); null otherwise.
         const resolvedCommand = getInvocation()?.canonical ?? null;
+        // The clock honesty field: present only when a consumer zone / pinned now
+        // is in effect (absent = host clock, so the wire shape is unchanged).
+        const clock = client.clockMeta();
         const meta = {
             dbVersion: fp.observation.databaseVersion,
             fingerprint: fp.kind === "ok" ? "ok" : fp.kind === "drift" ? "drift" : "unknown",
             elapsedMs: Date.now() - started,
-            ...(pagination !== undefined && { pagination }),
+            ...(truncation !== undefined && { truncation }),
             ...(grouped !== undefined && { grouped }),
             ...(resolvedCommand !== null && { resolvedCommand }),
+            ...(warnings.length > 0 && { warnings }),
+            ...(clock !== undefined && { clock }),
         };
-        if (fp.kind !== "ok") {
-            process.stderr.write(`warning: schema fingerprint ${meta.fingerprint} — reads best-effort, writes disabled (run \`things doctor\`)\n`);
+        // Human output gets the note once on STDERR (never mixed into the piped
+        // stdout rows); the --json envelope carries it in meta.warnings instead.
+        if (!opts.json) {
+            for (const warning of warnings)
+                process.stderr.write(`warning: ${warning}\n`);
         }
         if (opts.json) {
-            process.stdout.write(`${JSON.stringify(okEnvelope(kind, data, meta))}\n`);
+            // Omit-empty applies to the entity/data payload only (contracts.md); the
+            // envelope meta/truncation is untouched, and the human render below keeps
+            // the full, unpruned `data`.
+            process.stdout.write(`${JSON.stringify(okEnvelope(kind, omitEmpty(data), meta))}\n`);
         }
         else {
             const lines = precomputed ?? render(data);
-            if (pagination !== undefined && hintBase !== undefined) {
-                const hint = truncationHint(hintBase, pagination);
+            if (truncation !== undefined && hintBase !== undefined) {
+                const hint = truncationHint(hintBase, truncation);
                 if (hint !== null)
                     lines.push("", hint);
             }
@@ -101,6 +127,24 @@ export function runRead(opts, kind, fn, render, hintBase, header) {
             process.exitCode = ExitCode.Usage;
             return;
         }
+        // An unresolved uuid/partial-uuid/name (ambiguous or not-found) is a
+        // usage-class failure carrying machine-readable candidates.
+        if (err instanceof ReferenceResolutionError) {
+            if (opts.json) {
+                process.stdout.write(`${JSON.stringify(errorEnvelope({ code: err.code, message: err.message, details: { candidates: err.candidates } }, meta))}\n`);
+            }
+            else {
+                process.stderr.write(`error: ${err.message}\n`);
+            }
+            process.exitCode = ExitCode.Usage;
+            return;
+        }
+        // A malformed THINGS_TZ / THINGS_NOW (or per-read zone) fails closed as a
+        // usage error naming the expected form — never a silent host fallback.
+        if (err instanceof ClockError) {
+            usageError(opts, err.message);
+            return;
+        }
         const isEnv = err instanceof ThingsDbNotFoundError || err instanceof ThingsDbOpenError;
         const message = err instanceof Error ? err.message : String(err);
         if (opts.json) {
@@ -130,28 +174,28 @@ export function withClient(opts, kind, fn, render) {
  * with `--all`.
  */
 export function parseLimit(opts) {
-    return parseCap("--limit", opts.limit, DEFAULT_LIST_LIMIT, opts.all === true);
+    return parseCap("--limit", opts.limit, DEFAULT_LIST_LIMIT, opts.all === true, opts.json === true);
 }
 /**
  * Resolve one cap flag (`--limit`, `--area-limit`, `--project-limit`) against
  * `--all`: positive integer required, `--all` conflicts with an explicit
- * value and otherwise lifts the cap (null). The conflict/default decision is
- * the shared {@link resolveCap}; this surface adds the string→integer
- * validation and the usage-error emission.
+ * value and otherwise lifts the cap (null). This surface owns the string→integer
+ * validation and the usage-error emission; the client re-applies the same
+ * conflict/default semantics on the resolved value it receives.
  */
-export function parseCap(flag, value, defaultLimit, all) {
+export function parseCap(flag, value, defaultLimit, all, json = false) {
     const n = value === undefined ? undefined : Number(value);
-    const decision = resolveCap(n, all, defaultLimit);
+    // Resolve --all/value into a cap: an explicit value beside --all is a
+    // conflict; --all alone lifts the cap (null); otherwise the value or default.
+    const decision = all && n !== undefined ? "conflict" : all ? null : (n ?? defaultLimit);
     // Conflict takes precedence over value validation (an explicit value beside
     // --all is rejected before we scrutinize the value itself).
     if (decision === "conflict") {
-        process.stderr.write(`error: ${flag} and --all are mutually exclusive\n`);
-        process.exitCode = ExitCode.Usage;
+        usageError({ json }, `${flag} and --all are mutually exclusive`);
         return { ok: false };
     }
     if (n !== undefined && (!Number.isInteger(n) || n < 1)) {
-        process.stderr.write(`error: ${flag} must be a positive integer\n`);
-        process.exitCode = ExitCode.Usage;
+        usageError({ json }, `${flag} must be a positive integer`);
         return { ok: false };
     }
     return { ok: true, limit: decision };
@@ -166,16 +210,16 @@ export function invocation(name, parts) {
     ].join(" ");
 }
 /**
- * The unified truncation hint: a muted `── N more items — see more: … · all:
- * … ──` line whose commands echo the user's actual invocation, so a bigger
+ * The unified truncation hint: a muted `── N more items — see more: … · … ──`
+ * line whose commands echo the user's actual invocation, so a bigger
  * `--limit` or `--all` is one copy-paste away. Returns null when nothing was
  * dropped or the caller already asked for every row.
  */
-export function truncationHint(base, pagination) {
-    if (!pagination.truncated || pagination.limit === null)
+export function truncationHint(base, truncation) {
+    if (!truncation.truncated || truncation.limit === null)
         return null;
-    const more = pagination.total - pagination.shown;
-    const bigger = pagination.limit * 2;
-    return dim(`── ${more} more item${more === 1 ? "" : "s"} — see more: \`${base} --limit ${bigger}\` · all: \`${base} --all\` ──`);
+    const more = truncation.total - truncation.shown;
+    const bigger = truncation.limit * 2;
+    return dim(`── ${more} more item${more === 1 ? "" : "s"} — see more: \`${base} --limit ${bigger}\` · \`${base} --all\` ──`);
 }
 //# sourceMappingURL=read-driver.js.map

package/dist/cli/read-driver.js.map

@@ -1 +1 @@
-{"version":3,"file":"read-driver.js","sourceRoot":"","sources":["../../src/cli/read-driver.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"read-driver.js","sourceRoot":"","sources":["../../src/cli/read-driver.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAAE,GAAG,EAAE,MAAM,YAAY,CAAC;AACjC,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACtF,OAAO,EACL,UAAU,EACV,kBAAkB,EAClB,aAAa,EACb,QAAQ,EACR,UAAU,EACV,SAAS,EACT,UAAU,EACV,wBAAwB,EACxB,cAAc,EACd,qBAAqB,EACrB,iBAAiB,GAKlB,MAAM,aAAa,CAAC;AAOrB;;;;;;;GAOG;AACH,MAAM,UAAU,UAAU,CACxB,IAAwB,EACxB,OAAe,EACf,OAA4D;IAE5D,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;QACvB,MAAM,IAAI,GAAiB,EAAE,SAAS,EAAE,IAAI,EAAE,WAAW,EAAE,SAAS,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC;QACrF,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,GAAG,IAAI,CAAC,SAAS,CACf,aAAa,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,KAAK,SAAS,IAAI,EAAE,OAAO,EAAE,CAAC,EAAE,EAAE,IAAI,CAAC,CAC3F,IAAI,CACN,CAAC;IACJ,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,OAAO,IAAI,CAAC,CAAC;IAC9C,CAAC;IACD,OAAO,CAAC,QAAQ,GAAG,QAAQ,CAAC,KAAK,CAAC;AACpC,CAAC;AAgBD;;;;;;;GAOG;AACH,MAAM,UAAU,OAAO,CACrB,IAAoB,EACpB,IAAY,EACZ,EAA4C,EAC5C,MAA6B,EAC7B,QAAiB,EACjB,MAAe;IAEf,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAC3B,2EAA2E;IAC3E,yEAAyE;IACzE,IAAI,IAAI,CAAC,EAAE,KAAK,SAAS,IAAI,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QACnD,UAAU,CAAC,IAAI,EAAE,gCAAgC,CAAC,CAAC;QACnD,OAAO;IACT,CAAC;IACD,IAAI,MAAM,GAAwB,IAAI,CAAC;IACvC,IAAI,CAAC;QACH,MAAM,GAAG,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACxD,MAAM,EAAE,GAAG,MAAM,CAAC,WAAW,EAAE,CAAC;QAChC,0EAA0E;QAC1E,mEAAmE;QACnE,MAAM,QAAQ,GAAG,cAAc,CAAC,MAAM,CAAC,YAAY,EAAE,CAAC,CAAC;QACvD,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,CAAC;QACrE,0EAA0E;QAC1E,uEAAuE;QACvE,yEAAyE;QACzE,MAAM,eAAe,GAAG,aAAa,EAAE,EAAE,SAAS,IAAI,IAAI,CAAC;QAC3D,0EAA0E;QAC1E,sEAAsE;QACtE,MAAM,KAAK,GAAG,MAAM,CAAC,SAAS,EAAE,CAAC;QACjC,MAAM,IAAI,GAAiB;YACzB,SAAS,EAAE,EAAE,CAAC,WAAW,CAAC,eAAe;YACzC,WAAW,EAAE,EAAE,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS;YAChF,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO;YAC/B,GAAG,CAAC,UAAU,KAAK,SAAS,IAAI,EAAE,UAAU,EAAE,CAAC;YAC/C,GAAG,CAAC,OAAO,KAAK,SAAS,IAAI,EAAE,OAAO,EAAE,CAAC;YACzC,GAAG,CAAC,eAAe,KAAK,IAAI,IAAI,EAAE,eAAe,EAAE,CAAC;YACpD,GAAG,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,QAAQ,EAAE,CAAC;YACxC,GAAG,CAAC,KAAK,KAAK,SAAS,IAAI,EAAE,KAAK,EAAE,CAAC;SACtC,CAAC;QACF,wEAAwE;QACxE,yEAAyE;QACzE,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;YACf,KAAK,MAAM,OAAO,IAAI,QAAQ;gBAAE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,YAAY,OAAO,IAAI,CAAC,CAAC;QAChF,CAAC;QACD,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;YACd,yEAAyE;YACzE,0EAA0E;YAC1E,6BAA6B;YAC7B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,IAAI,EAAE,SAAS,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC;QACvF,CAAC;aAAM,CAAC;YACN,MAAM,KAAK,GAAG,WAAW,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC;YAC1C,IAAI,UAAU,KAAK,SAAS,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;gBACvD,MAAM,IAAI,GAAG,cAAc,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;gBAClD,IAAI,IAAI,KAAK,IAAI;oBAAE,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;YAC1C,CAAC;YACD,0EAA0E;YAC1E,0EAA0E;YAC1E,MAAM,UAAU,GACd,MAAM,KAAK,SAAS,IAAI,OAAO,CAAC,MAAM,CAAC,KAAK,KAAK,IAAI;gBACnD,CAAC,CAAC,CAAC,GAAG,eAAe,CAAC,MAAM,CAAC,EAAE,GAAG,KAAK,CAAC;gBACxC,CAAC,CAAC,KAAK,CAAC;YACZ,wEAAwE;YACxE,0EAA0E;YAC1E,oEAAoE;YACpE,sDAAsD;YACtD,MAAM,GAAG,GACP,eAAe,KAAK,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,KAAK,KAAK,IAAI;gBACvD,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,eAAe,EAAE,CAAC,EAAE,GAAG,UAAU,CAAC;gBAC9C,CAAC,CAAC,UAAU,CAAC;YACjB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC9C,CAAC;QACD,OAAO,CAAC,QAAQ,GAAG,QAAQ,CAAC,EAAE,CAAC;IACjC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,GAAiB;YACzB,SAAS,EAAE,IAAI;YACf,WAAW,EAAE,SAAS;YACtB,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO;SAChC,CAAC;QACF,0EAA0E;QAC1E,0EAA0E;QAC1E,2BAA2B;QAC3B,IAAI,GAAG,YAAY,eAAe,EAAE,CAAC;YACnC,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;gBACd,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,GAAG,IAAI,CAAC,SAAS,CACf,aAAa,CACX;oBACE,IAAI,EAAE,WAAW;oBACjB,OAAO,EAAE,GAAG,CAAC,OAAO;oBACpB,OAAO,EAAE,EAAE,UAAU,EAAE,cAAc,CAAC,GAAG,CAAC,EAAE;iBAC7C,EACD,IAAI,CACL,CACF,IAAI,CACN,CAAC;YACJ,CAAC;iBAAM,CAAC;gBACN,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAChE,CAAC;YACD,OAAO,CAAC,QAAQ,GAAG,QAAQ,CAAC,KAAK,CAAC;YAClC,OAAO;QACT,CAAC;QACD,qEAAqE;QACrE,4DAA4D;QAC5D,IAAI,GAAG,YAAY,wBAAwB,EAAE,CAAC;YAC5C,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;gBACd,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,GAAG,IAAI,CAAC,SAAS,CACf,aAAa,CACX,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,UAAU,EAAE,GAAG,CAAC,UAAU,EAAE,EAAE,EACjF,IAAI,CACL,CACF,IAAI,CACN,CAAC;YACJ,CAAC;iBAAM,CAAC;gBACN,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,GAAG,CAAC,OAAO,IAAI,CAAC,CAAC;YAClD,CAAC;YACD,OAAO,CAAC,QAAQ,GAAG,QAAQ,CAAC,KAAK,CAAC;YAClC,OAAO;QACT,CAAC;QACD,0EAA0E;QAC1E,uEAAuE;QACvE,IAAI,GAAG,YAAY,UAAU,EAAE,CAAC;YAC9B,UAAU,CAAC,IAAI,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC;YAC9B,OAAO;QACT,CAAC;QACD,MAAM,KAAK,GAAG,GAAG,YAAY,qBAAqB,IAAI,GAAG,YAAY,iBAAiB,CAAC;QACvF,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACjE,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;YACd,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,GAAG,IAAI,CAAC,SAAS,CAAC,aAAa,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,YAAY,EAAE,OAAO,EAAE,EAAE,IAAI,CAAC,CAAC,IAAI,CACpG,CAAC;QACJ,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,OAAO,IAAI,CAAC,CAAC;QAC9C,CAAC;QACD,OAAO,CAAC,QAAQ,GAAG,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC,QAAQ,CAAC,UAAU,CAAC;IACxE,CAAC;YAAS,CAAC;QACT,MAAM,EAAE,KAAK,EAAE,CAAC;IAClB,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,UAAU,CACxB,IAAoB,EACpB,IAAY,EACZ,EAA+B,EAC/B,MAA6B;IAE7B,OAAO,CAAI,IAAI,EAAE,IAAI,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC;AACrE,CAAC;AAKD;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CAAC,IAI1B;IACC,OAAO,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC,KAAK,EAAE,kBAAkB,EAAE,IAAI,CAAC,GAAG,KAAK,IAAI,EAAE,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;AACpG,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,QAAQ,CACtB,IAAY,EACZ,KAAyB,EACzB,YAAoB,EACpB,GAAY,EACZ,IAAI,GAAG,KAAK;IAEZ,MAAM,CAAC,GAAG,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC1D,sEAAsE;IACtE,8EAA8E;IAC9E,MAAM,QAAQ,GACZ,GAAG,IAAI,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,YAAY,CAAC,CAAC;IACzE,4EAA4E;IAC5E,4DAA4D;IAC5D,IAAI,QAAQ,KAAK,UAAU,EAAE,CAAC;QAC5B,UAAU,CAAC,EAAE,IAAI,EAAE,EAAE,GAAG,IAAI,mCAAmC,CAAC,CAAC;QACjE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC;IACvB,CAAC;IACD,IAAI,CAAC,KAAK,SAAS,IAAI,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;QACvD,UAAU,CAAC,EAAE,IAAI,EAAE,EAAE,GAAG,IAAI,6BAA6B,CAAC,CAAC;QAC3D,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC;IACvB,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC;AACvC,CAAC;AAED,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C,wEAAwE;AACxE,MAAM,UAAU,UAAU,CAAC,IAAY,EAAE,KAAwC;IAC/E,OAAO;QACL,QAAQ;QACR,IAAI;QACJ,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,EAAE,CAAC;KACvE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACd,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY,EAAE,UAAsB;IACjE,IAAI,CAAC,UAAU,CAAC,SAAS,IAAI,UAAU,CAAC,KAAK,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACpE,MAAM,IAAI,GAAG,UAAU,CAAC,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC;IACjD,MAAM,MAAM,GAAG,UAAU,CAAC,KAAK,GAAG,CAAC,CAAC;IACpC,OAAO,GAAG,CACR,MAAM,IAAI,aAAa,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,kBAAkB,IAAI,YAAY,MAAM,UAAU,IAAI,aAAa,CAChH,CAAC;AACJ,CAAC"}

package/dist/cli/render.d.ts

@@ -7,8 +7,8 @@
  * (agents and humans both need stable references); colors engage on a TTY only
  * (../cli/style.ts).
  */
-import { type ListItem, type SidebarSection, type TodayView } from "../read/views.ts";
-import { type GroupedLimits } from "../read/pagination.ts";
+import { type GroupedLimits, type GroupedTruncation, type ListItem, type SectionCount, type SidebarSection, type TodayView } from "../index.ts";
+import { stripSgr } from "./width.ts";
 /**
  * A view's TTY-only title preamble: bold view name + its dim Things deep link,
  * then a blank line — e.g. `Anytime (things:///show?id=anytime)`. The id is the
@@ -17,7 +17,8 @@ import { type GroupedLimits } from "../read/pagination.ts";
  * of `--json`; the caller gates on both.
  */
 export declare function viewHeaderLines(view: string): string[];
-export declare const stripAnsi: (s: string) => string;
+/** Re-export the canonical ANSI-stripper (impl in ./width.ts) — the legend and `--json` legend path use it. */
+export declare const stripAnsi: typeof stripSgr;
 /**
  * The `things legend` layout: the visual language grouped into sections
  * (`── To-dos ──`, …), each row the glyph as it actually renders (color on a
@@ -27,8 +28,12 @@ export declare const stripAnsi: (s: string) => string;
 export declare function renderLegend(): string[];
 export interface FormatOpts {
     /**
-     * Render a grouped project TITLE row: bold+underlined title (the GUI's
-     * project-header look) — the circle glyph and count chip still apply.
+     * Render this project as a group HEADING: underline the title (its heading
+     * ROLE — the project heads the to-do group beneath it, anytime/someday).
+     * Bold is UNIVERSAL for project titles (projectTitleAccent, the render-
+     * language delta-1 law), so this adds ONLY the underline; the circle glyph
+     * and count chip still apply. A plain project ROW (e.g. area-detail's top
+     * projects, the projects sidebar) omits this — bold without underline.
      */
     projectTitle?: boolean;
     /** Container uuids already implied by surrounding output — their context suffix is dropped. */
@@ -38,20 +43,29 @@ export interface FormatOpts {
     now?: Date;
     /** Pre-styled Today/Evening mark (★/⏾), rendered right after the box — GUI position. */
     mark?: string | null;
-    /** Dim status word after the box (the GUI's waiting/paused/ended chips on repeating templates). */
-    statusWord?: string;
     /** Suppress the ‹date› chip (rows under a day header already carry the date). */
     hideDateChip?: boolean;
+    /**
+     * The container's normal IS the resolved state (the Logbook): completed rows
+     * render plain and canceled rows keep their strikethrough but drop the dim —
+     * a row marks only its DEVIATIONS from the container. Mixed contexts
+     * (project/area show, search --logged/--trashed) omit this, so a resolved row
+     * among open ones stays dim/dim-strike. Never changes the status GLYPHS.
+     */
+    resolvedNormal?: boolean;
 }
 /**
  * One item line:
  * `<uuid-prefix>  <box> [★|⏾] [logged-date] [‹chip›] <title> [‹n›] [⍾] [≡] [≔] (container) #tags [⚑ deadline]`.
  * Repeating templates seat ↻ INSIDE the box (`[↻]`/`(↻)`) rather than as a
- * separate mark; open project rows render their circle and title blue.
- * The box is the glyph-language state carrier (../glyphs.ts): `[ ]`-family
- * for to-dos, `( )`-family for projects — state survives with color
- * stripped. Completed titles dim; canceled titles dim+strike (the `[×]`
- * mark keeps the state when strike/ANSI is unavailable). Human output shows
+ * separate mark; open project circles render blue, and project TITLES render
+ * bold + default-colored in every state (projectTitleAccent — the render-
+ * language law). The box is the glyph-language state carrier (../glyphs.ts):
+ * `[ ]`-family for to-dos, `( )`-family for projects — state survives with
+ * color stripped. Completed titles dim; canceled titles dim+strike (the `[×]`
+ * mark keeps the state when strike/ANSI is unavailable) — except where a view
+ * declares resolved its norm (Logbook, `resolvedNormal`), where completed is
+ * plain and canceled keeps only its strike. Human output shows
  * a SHORTENED uuid prefix (every command accepts unique prefixes >= 6
  * chars); `uuidWidth` is the display length from uuidDisplayWidth — never
  * below 8 so a copied prefix stays unique across the whole database, not
@@ -68,6 +82,12 @@ export declare function formatItem(item: ListItem, uuidWidth?: number, opts?: Fo
  * startDate is exactly today — the UI's daily expiry), null otherwise.
  */
 export declare function todayMark(item: ListItem, now?: Date): string | null;
+/** Minimum displayed-prefix length: shorter prefixes collide across the DB. */
+export declare const UUID_DISPLAY_MIN = 8;
+/** The full-form TTY row floor — worst-case furniture + full deadline. See {@link computeFitFloors}. */
+export declare const FULL_FIT_FLOOR: number;
+/** The compact-form TTY row floor — worst-case furniture + compact deadline. See {@link computeFitFloors}. */
+export declare const COMPACT_FIT_FLOOR: number;
 /**
  * Display width for a list's uuid column: the shortest prefix that is
  * unique WITHIN the list, floored at UUID_DISPLAY_MIN (list-local
@@ -92,15 +112,24 @@ export declare function renderList(items: ListItem[]): string[];
  * the per-row ★/⏾, where the marker still carries information.
  *
  * This Evening mirrors the GUI: it renders ONLY when evening items exist —
- * a truly-empty evening has no header at all. `full` is the pre-cap view and
- * `shown` the rows that survived the global `--limit`; the split lets the
- * section stay honest under truncation. When the cap hid some or all evening
- * rows, an honest muted hint counts the hidden ones and names the `--limit`
- * that reveals them — never the misleading `(empty)` a truncated evening used
- * to show. `base` is the user's own invocation (flags echoed). The global
- * footer (row driver) still reports the whole-view remainder separately.
+ * a truly-empty evening has no header at all. `view` is the rows that survived
+ * the global `--limit`; `sections` is the metadata's pre-cap per-section counts
+ * ({@link SectionCount}) — the Today/This-Evening totals the hint math needs, so
+ * the section stays honest under truncation without a pre-cap copy of the view.
+ * When the cap hid some or all evening rows, an honest muted hint counts the
+ * hidden ones and points at the isolated `--evening` view — never the misleading
+ * `(empty)` a truncated evening used to show. (In `--evening` mode that pointer
+ * is redundant, so the hint keeps the `--limit`/`--all` levers instead.) `base`
+ * is the user's own invocation (flags echoed). The global footer (row driver)
+ * still reports the whole-view remainder separately.
+ *
+ * `options.eveningOnly` (the `--evening` section filter) renders ONLY the This
+ * Evening block — the Today header and its `(empty)` placeholder are suppressed
+ * because that section is deliberately filtered out, not merely empty.
  */
-export declare function renderToday(full: TodayView, shown: TodayView, base: string): string[];
+export declare function renderToday(view: TodayView, sections: SectionCount[] | undefined, base: string, options?: {
+    eveningOnly?: boolean;
+}): string[];
 /**
  * Search rows: a standard list row, plus — for a project surfaced by a HEADING
  * title match — a muted `(via heading "…")` suffix crediting the heading whose
@@ -136,6 +165,12 @@ export declare function renderProjectsSidebar(items: ListItem[], hints?: LaterHi
  * absent), with the trailing Repeating To-Dos section: templates with no
  * set next occurrence, carrying their waiting/paused/ended status word and
  * the bare ⚑ when the rule will assign a deadline per occurrence.
+ *
+ * Deadline-forecast rows (UPC1) keep startDate=null but carry a real future
+ * deadline; they group under their DEADLINE date via COALESCE(startDate,
+ * deadline) — no when-date pill (the header carries the date; formatItem's
+ * chip keys on startDate, so a null-startDate row shows only the ⚑ deadline
+ * flag, mirroring the GUI's bare-flag anatomy).
  */
 export declare function renderUpcoming(items: ListItem[], now?: Date): string[];
 /**
@@ -143,6 +178,9 @@ export declare function renderUpcoming(items: ListItem[], now?: Date): string[];
  * — `── July ──` within the current year, `── March 2025 ──` beyond (finer
  * than the GUI's bare per-year buckets, deliberately). Truncation past the
  * row limit is reported by the shared hint the command appends, not here.
+ * Resolved is the Logbook's NORM, so rows pass `resolvedNormal`: completed
+ * titles render plain and canceled titles keep their strikethrough but drop
+ * the dim (the blue `[✓]`/`[×]` marks and logged date are unchanged).
  */
 export declare function renderLogbook(items: ListItem[], now?: Date): string[];
 /**
@@ -157,16 +195,42 @@ export declare function renderLogbook(items: ListItem[], now?: Date): string[];
  * with the Today-membership mark (★, or ⏾ for This-Evening members).
  */
 export declare function renderSections(sections: SidebarSection[], star?: boolean): string[];
+/** Single-quote a title for a copy-pasteable drill-down command. */
+export declare function quoteTitle(title: string): string;
+/**
+ * The one disclosure-hint grammar (docs/design/render-language.md § Disclosure
+ * hints): a muted `… <count> <noun> — [label:] `command` [· [label:] `command`]`.
+ * Every muted hint that discloses more content routes through here so the
+ * grammar lives in ONE place (the same one-law pattern as projectTitleAccent).
+ *
+ * `count` pluralizes `noun` (pass a `{ one, many }` pair when the plural is not
+ * a trailing `s`); each action is a FULL command echoing the user's own
+ * invocation, and a `label` prefixes an action only where it adds semantics the
+ * command text doesn't carry (e.g. `recent:` before a capped `--show-logged`).
+ * `indent` marks a TRUNCATION FOOTER — two spaces under its partially-shown
+ * section — whereas a HIDDEN-SECTION placeholder stays flush at the position
+ * its unrendered section would occupy.
+ */
+export declare function disclosureHint(count: number, noun: string | {
+    one: string;
+    many: string;
+}, actions: Array<{
+    label?: string;
+    command: string;
+}>, opts?: {
+    indent?: boolean;
+}): string;
 /**
  * The anytime preview: the FULL block skeleton — every area header and every
- * project row — always renders; `limits.area` caps the loose block and each
- * area's direct to-dos, `limits.project` each project's to-dos. A truncated
- * block trails a muted `… N more — \`things (project|area) show '…'\``
- * drill-down (the loose block has no container, so it shows only the count),
- * and the view ends with one line escalating the caps that hit. Today members
- * are starred. Mirrors renderSections' layout exactly.
+ * project row — always renders; the `sections` are the already-bounded view
+ * and `grouped` the per-block metadata that carries each block's pre-cap total,
+ * so a truncated block trails a muted `… N more — \`things (project|area) show
+ * '…'\`` drill-down (the loose block has no container, so it shows only the
+ * count), and the view ends with one line escalating the caps that hit
+ * (`limits` supplies the doubling). Today members are starred. Mirrors
+ * renderSections' layout exactly.
  */
-export declare function renderAnytimePreview(sections: SidebarSection[], limits: GroupedLimits, base: string): string[];
+export declare function renderAnytimePreview(sections: SidebarSection[], grouped: GroupedTruncation, limits: GroupedLimits, base: string): string[];
 /**
  * The someday preview, mirroring the GUI (side-by-side, 2026-07-12): inside
  * each group the project rows render as PLAIN items — `(~)` circle, count
@@ -179,4 +243,4 @@ export declare function renderAnytimePreview(sections: SidebarSection[], limits:
  * When the toggle is off and such items exist, a muted bottom hint counts
  * them and names the flag.
  */
-export declare function renderSomedayPreview(sections: SidebarSection[], limits: GroupedLimits, base: string, showActive: boolean, hiddenActiveItems: number): string[];
+export declare function renderSomedayPreview(sections: SidebarSection[], grouped: GroupedTruncation, limits: GroupedLimits, base: string, showActive: boolean, hiddenActiveItems: number): string[];