things-api 0.8.0 → 0.10.0

package/dist/cli/period.js.map

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

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

@@ -0,0 +1,83 @@
+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. */
+    truncation?: Truncation;
+    /** Grouped-view (anytime/someday) per-block truncation — carried into meta. */
+    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,
+     * `render(data)` produces them.
+     */
+    lines?: string[];
+}
+/**
+ * The shared read driver: open the client, stamp the envelope meta (including
+ * 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,
+ * its title preamble leads the human output on a TTY only (viewHeaderLines).
+ */
+export declare function runRead<T>(opts: GlobalReadOpts, kind: string, fn: (client: ThingsClient) => PagedResult<T>, render: (data: T) => string[], hintBase?: string, header?: string): void;
+/**
+ * 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 declare function withClient<T>(opts: GlobalReadOpts, kind: string, fn: (client: ThingsClient) => T, render: (data: T) => string[]): void;
+/** Result of resolving `--limit`/`--all`; `limit: null` means every row. */
+export type LimitResolution = {
+    ok: true;
+    limit: number | null;
+} | {
+    ok: false;
+};
+/**
+ * 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 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). 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, 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: … · … ──`
+ * 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, truncation: Truncation): string | null;

package/dist/cli/read-driver.js

@@ -0,0 +1,215 @@
+/**
+ * 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 { 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 { 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 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,
+ * 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() === "") {
+        usageError(opts, "--db requires a non-empty path");
+        return;
+    }
+    let client = null;
+    try {
+        client = openThings(opts.db ? { dbPath: opts.db } : {});
+        const fp = client.fingerprint();
+        // 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;
+        const meta = {
+            dbVersion: fp.observation.databaseVersion,
+            fingerprint: fp.kind === "ok" ? "ok" : fp.kind === "drift" ? "drift" : "unknown",
+            elapsedMs: Date.now() - started,
+            ...(truncation !== undefined && { truncation }),
+            ...(grouped !== undefined && { grouped }),
+            ...(resolvedCommand !== null && { resolvedCommand }),
+            ...(warnings.length > 0 && { warnings }),
+        };
+        // 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) {
+            // 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 (truncation !== undefined && hintBase !== undefined) {
+                const hint = truncationHint(hintBase, truncation);
+                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;
+        }
+        // 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;
+        }
+        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, 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). 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, json = false) {
+    const n = value === undefined ? undefined : Number(value);
+    // 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") {
+        usageError({ json }, `${flag} and --all are mutually exclusive`);
+        return { ok: false };
+    }
+    if (n !== undefined && (!Number.isInteger(n) || n < 1)) {
+        usageError({ json }, `${flag} must be a positive integer`);
+        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: … · … ──`
+ * 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, truncation) {
+    if (!truncation.truncated || truncation.limit === null)
+        return null;
+    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

@@ -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,246 @@
+/**
+ * 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 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
+ * 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[];
+/** 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
+ * 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 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. */
+    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;
+    /** 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 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
+ * 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;
+/** 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
+ * 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. `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(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
+ * 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.
+ *
+ * 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[];
+/**
+ * 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.
+ * 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[];
+/**
+ * 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[];
+/** 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; 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[], 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
+ * 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[], grouped: GroupedTruncation, limits: GroupedLimits, base: string, showActive: boolean, hiddenActiveItems: number): string[];