things-api 0.8.0 → 0.9.0

package/dist/cli/read-driver.js

@@ -0,0 +1,181 @@
+/**
+ * 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 { 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";
+/**
+ * The shared read driver: open the client, stamp the envelope meta (including
+ * fingerprint + optional pagination), 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,
+ * its title preamble leads the human output on a TTY only (viewHeaderLines).
+ */
+export function runRead(opts, kind, fn, render, hintBase, header) {
+    const started = Date.now();
+    // 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;
+        return;
+    }
+    let client = null;
+    try {
+        client = openThings(opts.db ? { dbPath: opts.db } : {});
+        const fp = client.fingerprint();
+        const { data, pagination, 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;
+        const meta = {
+            dbVersion: fp.observation.databaseVersion,
+            fingerprint: fp.kind === "ok" ? "ok" : fp.kind === "drift" ? "drift" : "unknown",
+            elapsedMs: Date.now() - started,
+            ...(pagination !== undefined && { pagination }),
+            ...(grouped !== undefined && { grouped }),
+            ...(resolvedCommand !== null && { resolvedCommand }),
+        };
+        if (fp.kind !== "ok") {
+            process.stderr.write(`warning: schema fingerprint ${meta.fingerprint} — reads best-effort, writes disabled (run \`things doctor\`)\n`);
+        }
+        if (opts.json) {
+            process.stdout.write(`${JSON.stringify(okEnvelope(kind, data, meta))}\n`);
+        }
+        else {
+            const lines = precomputed ?? render(data);
+            if (pagination !== undefined && hintBase !== undefined) {
+                const hint = truncationHint(hintBase, pagination);
+                if (hint !== null)
+                    lines.push("", hint);
+            }
+            // The view title preamble is a TTY-only affordance (`things inbox | grep`
+            // must stay clean) and never rides --json — both gates already hold here.
+            const withHeader = header !== undefined && process.stdout.isTTY === true
+                ? [...viewHeaderLines(header), ...lines]
+                : lines;
+            // The normalized-form echo: one dim line naming the canonical command a
+            // sugar invocation resolved to, adjacent to the header. Same gates as the
+            // preamble (TTY-only, never in --json) — canonical invocations echo
+            // nothing because `resolvedCommand` is null for them.
+            const out = resolvedCommand !== null && process.stdout.isTTY === true
+                ? [dim(`≡ ${resolvedCommand}`), ...withHeader]
+                : withHeader;
+            process.stdout.write(`${out.join("\n")}\n`);
+        }
+        process.exitCode = ExitCode.Ok;
+    }
+    catch (err) {
+        const meta = {
+            dbVersion: null,
+            fingerprint: "unknown",
+            elapsedMs: Date.now() - started,
+        };
+        // An unresolved show/bare-noun subject carries did-you-mean candidates: a
+        // usage-level failure (exit 2) with a lite title-search fallback, not the
+        // generic unexpected path.
+        if (err instanceof DidYouMeanError) {
+            if (opts.json) {
+                process.stdout.write(`${JSON.stringify(errorEnvelope({
+                    code: "not-found",
+                    message: err.message,
+                    details: { candidates: candidatesJson(err) },
+                }, meta))}\n`);
+            }
+            else {
+                process.stderr.write(`${renderDidYouMean(err).join("\n")}\n`);
+            }
+            process.exitCode = ExitCode.Usage;
+            return;
+        }
+        const isEnv = err instanceof ThingsDbNotFoundError || err instanceof ThingsDbOpenError;
+        const message = err instanceof Error ? err.message : String(err);
+        if (opts.json) {
+            process.stdout.write(`${JSON.stringify(errorEnvelope({ code: isEnv ? "environment" : "unexpected", message }, meta))}\n`);
+        }
+        else {
+            process.stderr.write(`error: ${message}\n`);
+        }
+        process.exitCode = isEnv ? ExitCode.Environment : ExitCode.Unexpected;
+    }
+    finally {
+        client?.close();
+    }
+}
+/**
+ * Structured single-payload read: `fn` produces the whole payload, `render`
+ * turns it into human lines. Generic so `fn`'s return type flows into
+ * `render`'s parameter — the compiler verifies the renderer matches the data.
+ */
+export function withClient(opts, kind, fn, render) {
+    runRead(opts, kind, (client) => ({ data: fn(client) }), render);
+}
+/**
+ * Resolve the shared `--limit`/`--all` pair (flat views) into a row cap
+ * (null = no cap), writing a loud usage error and setting the exit code on
+ * bad input: `--limit` must be a positive integer, and it may not combine
+ * with `--all`.
+ */
+export function parseLimit(opts) {
+    return parseCap("--limit", opts.limit, DEFAULT_LIST_LIMIT, opts.all === 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.
+ */
+export function parseCap(flag, value, defaultLimit, all) {
+    const n = value === undefined ? undefined : Number(value);
+    const decision = resolveCap(n, all, 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;
+        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;
+        return { ok: false };
+    }
+    return { ok: true, limit: decision };
+}
+export { shellQuote } from "./shell-quote.js";
+/** Reconstruct `things <name> <flags…>`, dropping falsy/empty parts. */
+export function invocation(name, parts) {
+    return [
+        "things",
+        name,
+        ...parts.filter((p) => typeof p === "string" && p !== ""),
+    ].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
+ * `--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)
+        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\` ──`);
+}
+//# sourceMappingURL=read-driver.js.map

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

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

package/dist/cli/render.d.ts

@@ -0,0 +1,182 @@
+/**
+ * The pure human-rendering family for the read views: the glyph-language item
+ * formatter, the flat and grouped list renderers, the sidebar/upcoming/logbook
+ * layouts, the anytime/someday previews, and the legend. No commander and no
+ * database access — every function maps already-fetched data to output lines,
+ * so the whole module is unit-testable in isolation. UUIDs are always shown
+ * (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";
+/**
+ * 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
+ * app's documented show id (identical to the command name for these views).
+ * Suppressed off a TTY so `things inbox | grep …` stays clean, and never part
+ * of `--json`; the caller gates on both.
+ */
+export declare function viewHeaderLines(view: string): string[];
+export declare const stripAnsi: (s: string) => string;
+/**
+ * The `things legend` layout: the visual language grouped into sections
+ * (`── To-dos ──`, …), each row the glyph as it actually renders (color on a
+ * TTY) followed by its meaning. Content comes straight from glyphs.ts's LEGEND
+ * table, so it can never drift from what the list renderers emit.
+ */
+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.
+     */
+    projectTitle?: boolean;
+    /** Container uuids already implied by surrounding output — their context suffix is dropped. */
+    suppressProject?: string | null;
+    suppressArea?: string | null;
+    /** Reference instant for date-relative tokens (tests pin this; defaults to now). */
+    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;
+}
+/**
+ * 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
+ * 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
+ * just the rendered list. Tags follow the title (`#`-prefixed, green — GUI
+ * color), after the count chip (projects), notes marker, and container.
+ * Heading-nested to-dos label their parent PROJECT (via headingProject),
+ * never the heading — GUI behavior. Colors engage on a TTY only
+ * (../style.ts); `--json` always carries full uuids.
+ */
+export declare function formatItem(item: ListItem, uuidWidth?: number, opts?: FormatOpts): string;
+/**
+ * Row prefix in today-aware views: yellow ★ for Today members, cyan ⏾ for
+ * effective This-Evening members (raw evening assignment counts only while
+ * startDate is exactly today — the UI's daily expiry), null otherwise.
+ */
+export declare function todayMark(item: ListItem, now?: Date): string | null;
+/**
+ * Display width for a list's uuid column: the shortest prefix that is
+ * unique WITHIN the list, floored at UUID_DISPLAY_MIN (list-local
+ * uniqueness at 2–3 chars would still collide database-wide).
+ */
+export declare function uuidDisplayWidth(items: Array<{
+    uuid: string;
+}>): number;
+/**
+ * Fit a uuid into the shared id column: truncate to `width` when longer, pad
+ * to it when shorter, so ids line up under one another regardless of prefix
+ * length. `width` is the value from uuidDisplayWidth.
+ */
+export declare function uuidCol(uuid: string, width: number): string;
+export declare function renderList(items: ListItem[]): string[];
+/**
+ * The `things today` split. The membership glyph lives in the SECTION HEADER,
+ * not on every row — a yellow ★ in the Today header (which also carries the
+ * sidebar badge split) and a blue ⏾ in the This Evening header — so the rows
+ * drop the redundant per-item marker (the same convention that suppresses a
+ * `(project)` context inside that project's own view). Every OTHER view keeps
+ * 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.
+ */
+export declare function renderToday(full: TodayView, shown: TodayView, base: string): 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
+ * text matched (the parent project row stands in for the heading; the GUI has
+ * no bare heading row). Ordinary title/notes matches render as plain rows.
+ */
+export declare function renderSearch(items: ListItem[]): string[];
+/** Hidden-later counts per sidebar group (null area = the loose block). */
+export interface LaterHints {
+    /** Sidebar-ordered, INCLUDING groups whose every project is later. */
+    groups: Array<{
+        area: {
+            uuid: string;
+            title: string;
+        } | null;
+        hidden: number;
+    }>;
+}
+/**
+ * The sidebar mirror for `things projects`: loose projects first (the GUI
+ * lists them above the areas), then a `── ⬡ Area ──` header per area with
+ * its projects beneath (the redundant `(Area)` suffix suppressed). Items
+ * arrive from projectsView already in sidebar order — this only inserts the
+ * headers. Denser than renderSections on purpose: no title styling and no
+ * blank line per project (every row here IS a project). With `hints`,
+ * default-hidden later projects are never silent: each group trails a muted
+ * `…n later projects` count (a later-only area still gets its header), and
+ * the output ends with the flag that reveals them.
+ */
+export declare function renderProjectsSidebar(items: ListItem[], hints?: LaterHints): string[];
+/**
+ * Upcoming rows under GUI-style date headers (empty periods are simply
+ * 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.
+ */
+export declare function renderUpcoming(items: ListItem[], now?: Date): string[];
+/**
+ * Logbook rows under GUI-style date headings, month granularity throughout
+ * — `── 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.
+ */
+export declare function renderLogbook(items: ListItem[], now?: Date): string[];
+/**
+ * Sidebar-grouped views (anytime/someday), rendered the way the GUI reads:
+ * the area-less block headerless first, then one `── <area> ──` header per
+ * area; inside a section, loose to-dos first, then each project GROUP — a
+ * blank line, the project's bold+underlined title row, then its members.
+ * Container names implied by the grouping are not repeated on member rows
+ * (an area header covers its rows; a project title row covers the to-dos
+ * beneath it — a clustered child whose project row is absent, e.g. under a
+ * tag filter, keeps its `(project)` suffix). `star` prefixes each item line
+ * with the Today-membership mark (★, or ⏾ for This-Evening members).
+ */
+export declare function renderSections(sections: SidebarSection[], star?: 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.
+ */
+export declare function renderAnytimePreview(sections: SidebarSection[], 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
+ * chip, no header styling, no surrounding blank lines — listed before the
+ * direct to-dos; `limits.area` caps each group's combined list. With
+ * `showActive` (the --show-active-project-items toggle) the someday to-dos
+ * living inside active projects append as a separate trailing
+ * `── From active projects ──` section — a flat run of project-header blocks
+ * (no area grouping), each capped at `limits.project` (null = every item).
+ * 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[];