things-api 0.9.0 → 0.10.0

package/dist/cli/commands/reads.js

@@ -7,15 +7,15 @@
  */
 import { Option } from "commander";
 import { execFileSync } from "node:child_process";
-import { localToday } from "../../model/dates.js";
+import { runAreaShow } from "./area.js";
+import { runProjectShow } from "./project.js";
 import { dim } from "../style.js";
 import { areaMark, LEGEND, shortDate } from "../glyphs.js";
-import { formatItem, renderAnytimePreview, renderLegend, renderList, renderLogbook, renderProjectsSidebar, renderSearch, renderSections, renderSomedayPreview, renderToday, renderUpcoming, stripAnsi, uuidCol, uuidDisplayWidth, } from "../render.js";
-import { invocation, parseCap, parseLimit, runRead, shellQuote, withClient, } from "../read-driver.js";
-import { parsePeriodEnd, parsePeriodStart } from "../period.js";
-import { ExitCode, okEnvelope } from "../../contracts.js";
-import { AREA_PREVIEW_LIMIT, PROJECT_PREVIEW_LIMIT, paginateList, paginateToday, partitionSomedaySection, previewSections, previewSomedaySections, } from "../../read/pagination.js";
-import { ALL_DESC, AREA_LIMIT_DESC, GROUPED_ALL_DESC, LIMIT_DESC, PERIOD_SINCE, PERIOD_UNTIL, PROJECT_LIMIT_DESC, } from "../../surface-copy.js";
+import { formatItem, disclosureHint, renderAnytimePreview, renderLegend, renderList, renderLogbook, renderProjectsSidebar, renderSearch, renderSections, renderSomedayPreview, renderToday, renderUpcoming, stripAnsi, uuidCol, uuidDisplayWidth, } from "../render.js";
+import { invocation, parseCap, parseLimit, runRead, shellQuote, truncationHint, usageError, withClient, } from "../read-driver.js";
+import { addTagFilterOptions, collectRef, CONTAINER_TAG_HINT, EXACT_TAG_DESC, hasTagPresence, TAG_DESC, UNTAGGED_DESC, tagFilterFields, tagFlagConflict, tagInvocationParts, } from "../tag-filters.js";
+import { doublePeriod, parsePeriodEnd, parsePeriodStart } from "../period.js";
+import { ALL_DESC, AREA_LIMIT_DESC, AREA_PREVIEW_LIMIT, ExitCode, FILTER_CONTRACT, GROUPED_ALL_DESC, LIMIT_DESC, localToday, okEnvelope, PERIOD_SINCE, PERIOD_UNTIL, PROJECT_LIMIT_DESC, PROJECT_PREVIEW_LIMIT, validateViewArgs, } from "../../index.js";
 /**
  * Foreground the Things app on a resource via its share URI. A GUI action
  * on this Mac — NOT headless; the shared implementation behind every
@@ -26,27 +26,8 @@ export function openInThings(uuid) {
     execFileSync("/usr/bin/open", [uri]);
     return uri;
 }
-function registerListView(program, spec) {
-    program
-        .command(spec.name)
-        .description(spec.description)
-        .option("--tag <ref>", "filter by tag (uuid or unique name): direct, inherited, or descendant-tagged")
-        .option("--exact-tag", "match the named tag only — exclude hierarchy descendants")
-        .option("--limit <n>", LIMIT_DESC)
-        .option("--all", ALL_DESC)
-        .option("--json", "emit versioned JSON envelope on stdout")
-        .option("--db <path>", "explicit database path")
-        .action((opts) => {
-        const lim = parseLimit(opts);
-        if (!lim.ok)
-            return;
-        const base = invocation(spec.name, [
-            opts.tag !== undefined && `--tag ${shellQuote(opts.tag)}`,
-            opts.exactTag === true && "--exact-tag",
-        ]);
-        runRead(opts, spec.name, (c) => spec.paginate(spec.fetch(c, opts.tag, opts.exactTag), lim.limit), spec.render, base, spec.name);
-    });
-}
+/** Help copy for the `--overdue` content scope (open items past their deadline). */
+const OVERDUE_DESC = "only open items past their deadline (due today is not overdue)";
 export function registerReadCommands(program) {
     program
         .command("legend")
@@ -77,51 +58,137 @@ export function registerReadCommands(program) {
     program
         .command("today")
         .description("The Today list, split into Today and This Evening (evening expires daily), with the sidebar badge split (red = deadline due/overdue)")
-        .option("--tag <ref>", "filter by tag (uuid or unique name): direct, inherited, or descendant-tagged")
-        .option("--exact-tag", "match the named tag only — exclude hierarchy descendants")
+        .option("--tag <ref>", TAG_DESC, collectRef, [])
+        .option("--exact-tag", EXACT_TAG_DESC)
+        .option("--untagged", UNTAGGED_DESC)
+        .option("--overdue", OVERDUE_DESC)
+        .option("--evening", "show only the This Evening section")
         .option("--limit <n>", LIMIT_DESC)
         .option("--all", ALL_DESC)
         .option("--json", "emit versioned JSON envelope on stdout")
         .option("--db <path>", "explicit database path")
         .action((opts) => {
+        if (tagFlagConflict(opts))
+            return;
         const lim = parseLimit(opts);
         if (!lim.ok)
             return;
+        const eveningOnly = opts.evening === true;
         const base = invocation("today", [
-            opts.tag !== undefined && `--tag ${shellQuote(opts.tag)}`,
-            opts.exactTag === true && "--exact-tag",
+            ...tagInvocationParts(opts),
+            opts.overdue === true && "--overdue",
+            eveningOnly && "--evening",
         ]);
+        const filter = {
+            ...tagFilterFields(opts),
+            ...(opts.overdue === true && { overdue: true }),
+            ...(eveningOnly && { eveningOnly: true }),
+        };
         runRead(opts, "today", (c) => {
-            const full = c.read.today(opts.tag === undefined
-                ? undefined
-                : { tag: opts.tag, ...(opts.exactTag === true && { exactTag: true }) });
-            const { data, pagination } = paginateToday(full, lim.limit);
-            // The renderer needs the PRE-cap view to keep This Evening honest
-            // under truncation, so the lines are precomputed here; the global
-            // footer (whole-view remainder) is still appended by the driver.
-            return { data, pagination, lines: renderToday(full, data, base) };
+            const { view, truncation } = c.read.today({ ...filter, limit: lim.limit });
+            // The renderer keeps This Evening honest under truncation from the
+            // metadata's per-section counts; the lines are precomputed here and
+            // the global footer (whole-view remainder) is appended by the driver.
+            return {
+                data: view,
+                truncation,
+                lines: renderToday(view, truncation.sections, base, { eveningOnly }),
+            };
         }, 
         // Type-correct fallback for the TodayView payload; never reached
         // because `lines` is always precomputed above.
-        (data) => renderToday(data, data, base), base, "today");
+        (data) => renderToday(data, undefined, base, { eveningOnly }), base, "today");
     });
-    registerListView(program, {
-        name: "inbox",
-        description: "Unprocessed captures (Inbox)",
-        fetch: (c, tag, exactTag) => c.read.inbox(tag === undefined ? undefined : { tag, ...(exactTag === true && { exactTag }) }),
-        render: renderList,
-        paginate: paginateList,
+    program
+        .command("inbox")
+        .description("Unprocessed captures (Inbox). Bound the CREATION date with --since/--until — an " +
+        "item's arrival into Things (a demoted item keeps its original creation date, so " +
+        "this is not strictly when it entered the Inbox).")
+        .option("--tag <ref>", TAG_DESC, collectRef, [])
+        .option("--exact-tag", EXACT_TAG_DESC)
+        .option("--untagged", UNTAGGED_DESC)
+        .option("--overdue", OVERDUE_DESC)
+        .option("--since <when>", `only captures created on/after this bound: ${PERIOD_SINCE}`)
+        .option("--until <when>", `only captures created on/before this bound: ${PERIOD_UNTIL}`)
+        .option("--limit <n>", LIMIT_DESC)
+        .option("--all", ALL_DESC)
+        .option("--json", "emit versioned JSON envelope on stdout")
+        .option("--db <path>", "explicit database path")
+        .action((opts) => {
+        if (tagFlagConflict(opts))
+            return;
+        const lim = parseLimit(opts);
+        if (!lim.ok)
+            return;
+        const since = opts.since !== undefined ? parsePeriodStart(opts.since) : undefined;
+        const until = opts.until !== undefined ? parsePeriodEnd(opts.until) : undefined;
+        for (const [flag, value] of [
+            ["--since", since],
+            ["--until", until],
+        ]) {
+            if (value !== undefined && Number.isNaN(value.getTime())) {
+                usageError(opts, `${flag} is not a parseable date`);
+                return;
+            }
+        }
+        // Bounds-&-defaults lift rule (identical to logbook): an explicit range
+        // bound (--since/--until) drops the default row cap unless --limit is
+        // also stated — the creation window the user named IS the bound, not an
+        // arbitrary 50-row cut.
+        const boundGiven = opts.since !== undefined || opts.until !== undefined;
+        const effectiveLimit = opts.limit === undefined && opts.all !== true && boundGiven ? null : lim.limit;
+        const base = invocation("inbox", [
+            ...tagInvocationParts(opts),
+            opts.overdue === true && "--overdue",
+            opts.since !== undefined && `--since ${shellQuote(opts.since)}`,
+            opts.until !== undefined && `--until ${shellQuote(opts.until)}`,
+        ]);
+        runRead(opts, "inbox", (c) => {
+            const { items: data, truncation } = c.read.inbox({
+                ...tagFilterFields(opts),
+                ...(opts.overdue === true && { overdue: true }),
+                ...(since !== undefined && { since }),
+                ...(until !== undefined && { until }),
+                limit: effectiveLimit,
+            });
+            const lines = renderList(data);
+            // Standard row-truncation hint (bigger --limit / --all), as every
+            // flat view — handled here (not via the driver's hintBase) so the
+            // creation-window note can sit last, mirroring upcoming's window
+            // footer mechanics.
+            const hint = truncationHint(base, truncation);
+            if (hint !== null)
+                lines.push("", hint);
+            // Presentation order is unchanged (manual ORDER BY index); the date
+            // bound is an invisible axis in the rows, so name the effective
+            // window in a dim footer note. Human output only — the precomputed
+            // lines never ride --json.
+            if (boundGiven) {
+                const today = localToday();
+                const sinceLabel = since !== undefined ? shortDate(localToday(since), today) : null;
+                const untilLabel = until !== undefined ? shortDate(localToday(until), today) : null;
+                const note = sinceLabel !== null && untilLabel !== null
+                    ? `(created ${sinceLabel} – ${untilLabel})`
+                    : sinceLabel !== null
+                        ? `(created since ${sinceLabel})`
+                        : `(created through ${untilLabel})`;
+                lines.push("", dim(note));
+            }
+            return { data, truncation, lines };
+        }, renderList, undefined, "inbox");
     });
     program
         .command("anytime")
-        .description("All active items in the UI's sidebar-mirroring order (area-less first, then per " +
+        .description("All active items in canonical order (area-less first, then per " +
         "area: direct to-dos, then each project with its members). Today members are " +
         "starred (★). Children of someday/future-scheduled projects are excluded — the " +
         "project row represents them. Every group and project row is always shown; " +
         "--area-limit caps each area's direct list, --project-limit each project's list, " +
         "--all shows everything")
-        .option("--tag <ref>", "filter by tag (uuid or unique name): direct, inherited, or descendant-tagged")
-        .option("--exact-tag", "match the named tag only — exclude hierarchy descendants")
+        .option("--tag <ref>", TAG_DESC, collectRef, [])
+        .option("--exact-tag", EXACT_TAG_DESC)
+        .option("--untagged", UNTAGGED_DESC)
+        .option("--overdue", OVERDUE_DESC)
         .option("--area-limit <n>", AREA_LIMIT_DESC)
         .option("--project-limit <n>", PROJECT_LIMIT_DESC)
         .option("--all", GROUPED_ALL_DESC)
@@ -129,28 +196,40 @@ export function registerReadCommands(program) {
         .option("--json", "emit versioned JSON envelope on stdout")
         .option("--db <path>", "explicit database path")
         .action((opts) => {
+        if (tagFlagConflict(opts))
+            return;
         if (opts.limit !== undefined) {
-            process.stderr.write("error: --limit is not available on anytime — cap blocks with --area-limit / --project-limit, or pass --all\n");
-            process.exitCode = ExitCode.Usage;
+            usageError(opts, "--limit is not available on anytime — cap blocks with --area-limit / --project-limit, or pass --all");
             return;
         }
-        const area = parseCap("--area-limit", opts.areaLimit, AREA_PREVIEW_LIMIT, opts.all === true);
+        const area = parseCap("--area-limit", opts.areaLimit, AREA_PREVIEW_LIMIT, opts.all === true, opts.json === true);
         if (!area.ok)
             return;
-        const project = parseCap("--project-limit", opts.projectLimit, PROJECT_PREVIEW_LIMIT, opts.all === true);
+        const project = parseCap("--project-limit", opts.projectLimit, PROJECT_PREVIEW_LIMIT, opts.all === true, opts.json === true);
         if (!project.ok)
             return;
         const limits = { area: area.limit, project: project.limit };
         const base = invocation("anytime", [
-            opts.tag !== undefined && `--tag ${shellQuote(opts.tag)}`,
-            opts.exactTag === true && "--exact-tag",
+            ...tagInvocationParts(opts),
+            opts.overdue === true && "--overdue",
         ]);
+        // Content scopes compose (AND): --overdue narrows a tagged/untagged
+        // set, so the filter is built additively rather than one-or-the-other.
+        const filter = {
+            ...tagFilterFields(opts),
+            ...(opts.overdue === true && { overdue: true }),
+        };
         runRead(opts, "anytime", (c) => {
-            const full = c.read.anytime(opts.tag === undefined
-                ? undefined
-                : { tag: opts.tag, ...(opts.exactTag === true && { exactTag: true }) });
-            const { data, grouped } = previewSections(full, limits);
-            return { data, grouped, lines: renderAnytimePreview(full, limits, base) };
+            const { view, grouped } = c.read.anytime({
+                ...filter,
+                areaLimit: area.limit,
+                projectLimit: project.limit,
+            });
+            return {
+                data: view,
+                grouped,
+                lines: renderAnytimePreview(view, grouped, limits, base),
+            };
         }, 
         // Grouped views hand back precomputed `lines`; renderSections is the
         // type-correct fallback for the SidebarSection[] payload but is never
@@ -159,14 +238,16 @@ export function registerReadCommands(program) {
     });
     program
         .command("someday")
-        .description("Someday items (incubated, undated) in sidebar order — inside each group the " +
+        .description("Someday items (incubated, undated) in canonical order — inside each group the " +
         "someday projects list first, then the to-dos; project children are represented " +
         "by their project row. --show-active-project-items [n] appends a trailing section " +
         "of someday to-dos inside active projects, grouped under their project (the UI's " +
         "'Show items from active projects' toggle; n caps each project's list). " +
         "--area-limit caps each group, --all shows everything")
-        .option("--tag <ref>", "filter by tag (uuid or unique name): direct, inherited, or descendant-tagged")
-        .option("--exact-tag", "match the named tag only — exclude hierarchy descendants")
+        .option("--tag <ref>", TAG_DESC, collectRef, [])
+        .option("--exact-tag", EXACT_TAG_DESC)
+        .option("--untagged", UNTAGGED_DESC)
+        .option("--overdue", OVERDUE_DESC)
         .option("--area-limit <n>", AREA_LIMIT_DESC)
         .option("--show-active-project-items [n]", "append someday to-dos inside active projects, grouped under their project; " +
         "n caps each project's list (bare flag: every item)")
@@ -175,6 +256,8 @@ export function registerReadCommands(program) {
         .option("--json", "emit versioned JSON envelope on stdout")
         .option("--db <path>", "explicit database path")
         .action((opts) => {
+        if (tagFlagConflict(opts))
+            return;
         if (opts.limit !== undefined) {
             process.stderr.write("error: --limit is not available on someday — cap groups with --area-limit, or pass --all\n");
             process.exitCode = ExitCode.Usage;
@@ -183,41 +266,45 @@ export function registerReadCommands(program) {
         const showActive = opts.showActiveProjectItems !== undefined;
         let projectCap = null;
         if (typeof opts.showActiveProjectItems === "string") {
-            const capped = parseCap("--show-active-project-items", opts.showActiveProjectItems, 0, opts.all === true);
+            const capped = parseCap("--show-active-project-items", opts.showActiveProjectItems, 0, opts.all === true, opts.json === true);
             if (!capped.ok)
                 return;
             projectCap = capped.limit;
         }
-        const area = parseCap("--area-limit", opts.areaLimit, AREA_PREVIEW_LIMIT, opts.all === true);
+        const area = parseCap("--area-limit", opts.areaLimit, AREA_PREVIEW_LIMIT, opts.all === true, opts.json === true);
         if (!area.ok)
             return;
         const limits = { area: area.limit, project: projectCap };
         const filter = {
-            ...(opts.tag !== undefined && { tag: opts.tag }),
-            ...(opts.exactTag === true && { exactTag: true }),
+            ...tagFilterFields(opts),
+            ...(opts.overdue === true && { overdue: true }),
         };
         const base = invocation("someday", [
-            opts.tag !== undefined && `--tag ${shellQuote(opts.tag)}`,
-            opts.exactTag === true && "--exact-tag",
+            ...tagInvocationParts(opts),
+            opts.overdue === true && "--overdue",
         ]);
         runRead(opts, "someday", (c) => {
-            const full = c.read.someday({
+            const { view, grouped } = c.read.someday({
                 ...filter,
                 ...(showActive && { activeProjectItems: true }),
+                areaLimit: area.limit,
+                projectLimit: projectCap,
             });
             // Hidden-items-never-silent: when the toggle is off, one extra
-            // query counts what it would reveal so the hint can say so.
+            // query counts what it would reveal (someday to-dos inside active
+            // projects) — summing the active-project child blocks' totals from
+            // that query's grouped metadata (projectLimit defaults to every
+            // item there, so each block's total is the full group size).
             const hiddenActiveItems = showActive
                 ? 0
                 : c.read
                     .someday({ ...filter, activeProjectItems: true })
-                    .reduce((n, s) => n +
-                    partitionSomedaySection(s).children.reduce((m, g) => m + g.items.length, 0), 0);
-            const { data, grouped } = previewSomedaySections(full, limits);
+                    .grouped.blocks.reduce((n, b) => n +
+                    (b.children?.reduce((m, child) => m + (child.kind === "project" ? child.total : 0), 0) ?? 0), 0);
             return {
-                data,
+                data: view,
                 grouped,
-                lines: renderSomedayPreview(full, limits, base, showActive, hiddenActiveItems),
+                lines: renderSomedayPreview(view, grouped, limits, base, showActive, hiddenActiveItems),
             };
         }, 
         // Precomputed lines above; renderSections is the type-correct
@@ -237,56 +324,95 @@ export function registerReadCommands(program) {
         .option("--since <period>", `skip items scheduled before this bound: ${PERIOD_SINCE}`)
         .option("--all", "no date bound and no row limit — the app's full Upcoming")
         .option("--limit <n>", LIMIT_DESC)
-        .option("--tag <ref>", "filter by tag (uuid or unique name): direct, inherited, or descendant-tagged")
-        .option("--exact-tag", "match the named tag only — exclude hierarchy descendants")
+        .option("--tag <ref>", TAG_DESC, collectRef, [])
+        .option("--exact-tag", EXACT_TAG_DESC)
+        .option("--untagged", UNTAGGED_DESC)
         .option("--horizon <n>", "occurrences per repeating item (default 1 = UI parity)")
         .option("--json", "emit versioned JSON envelope on stdout")
         .option("--db <path>", "explicit database path")
         .action((opts, command) => {
+        if (tagFlagConflict(opts))
+            return;
         const untilGiven = command.getOptionValueSource("until") !== "default";
         const sinceGiven = opts.since !== undefined;
+        const limitGiven = opts.limit !== undefined;
         if (opts.all === true && (untilGiven || sinceGiven)) {
-            process.stderr.write("error: --all does not combine with --until/--since\n");
-            process.exitCode = ExitCode.Usage;
+            usageError(opts, "--all does not combine with --until/--since");
             return;
         }
         const lim = parseLimit(opts);
         if (!lim.ok)
             return;
-        const untilDate = opts.all === true ? undefined : parsePeriodEnd(opts.until);
+        // Bounds-&-defaults rule: an explicit volume cap (--limit) or range
+        // bound (--until/--since) disables the OTHER class's default. So an
+        // explicit --limit drops the default window (the next N scheduled
+        // items), and an explicit window drops the default row cap — each
+        // stated bound takes over output sizing.
+        const dropWindowDefault = !untilGiven && (limitGiven || sinceGiven);
+        const dropLimitDefault = !limitGiven && opts.all !== true && (untilGiven || sinceGiven);
+        const effectiveLimit = dropLimitDefault ? null : lim.limit;
+        const untilDate = opts.all === true || dropWindowDefault ? undefined : parsePeriodEnd(opts.until);
         if (untilDate !== undefined && Number.isNaN(untilDate.getTime())) {
-            process.stderr.write(`error: --until is not a parseable period: ${opts.until}\n`);
-            process.exitCode = ExitCode.Usage;
+            usageError(opts, `--until is not a parseable period: ${opts.until}`);
             return;
         }
         const sinceDate = sinceGiven ? parsePeriodStart(opts.since) : undefined;
         if (sinceDate !== undefined && Number.isNaN(sinceDate.getTime())) {
-            process.stderr.write(`error: --since is not a parseable period: ${opts.since}\n`);
-            process.exitCode = ExitCode.Usage;
+            usageError(opts, `--since is not a parseable period: ${opts.since}`);
             return;
         }
         const until = untilDate === undefined ? undefined : localToday(untilDate);
         const since = sinceDate === undefined ? undefined : localToday(sinceDate);
+        // The default window is in force only for a bare invocation (no
+        // explicit cap or bound); that is the one case whose footer names the
+        // window itself alongside the levers.
+        const defaultWindowActive = until !== undefined && !untilGiven;
         const base = invocation("upcoming", [
             untilGiven && `--until ${shellQuote(opts.until)}`,
             sinceGiven && `--since ${shellQuote(opts.since)}`,
-            opts.tag !== undefined && `--tag ${shellQuote(opts.tag)}`,
-            opts.exactTag === true && "--exact-tag",
+            ...tagInvocationParts(opts),
             opts.horizon !== undefined && `--horizon ${shellQuote(opts.horizon)}`,
         ]);
-        runRead(opts, "upcoming", (c) => paginateList(c.read.upcoming({
-            ...(until !== undefined && { until }),
-            ...(since !== undefined && { since }),
-            ...(opts.tag !== undefined && { tag: opts.tag }),
-            ...(opts.exactTag === true && { exactTag: true }),
-            ...(opts.horizon !== undefined && { horizon: Number(opts.horizon) }),
-        }), lim.limit), (items) => {
-            const lines = renderUpcoming(items);
-            if (until !== undefined) {
-                lines.push("", dim(`(through ${shortDate(until, localToday())} — --all for the full horizon)`));
+        runRead(opts, "upcoming", (c) => {
+            const { items: data, truncation } = c.read.upcoming({
+                ...(until !== undefined && { until }),
+                ...(since !== undefined && { since }),
+                ...tagFilterFields(opts),
+                ...(opts.horizon !== undefined && { horizon: Number(opts.horizon) }),
+                limit: effectiveLimit,
+            });
+            const lines = renderUpcoming(data);
+            if (defaultWindowActive && until !== undefined) {
+                const windowLabel = shortDate(until, localToday());
+                if (truncation.truncated && truncation.limit !== null) {
+                    // Bare invocation, row cap biting inside the default window: one
+                    // line names BOTH the window and the two levers, so neither the
+                    // limit nor the horizon is a hidden second bound.
+                    const more = truncation.total - truncation.shown;
+                    lines.push("", dim(`── ${more} more item${more === 1 ? "" : "s"} through ${windowLabel} — ` +
+                        `see more: \`${base} --limit ${truncation.limit * 2}\` · ` +
+                        `\`${base} --all\` ──`));
+                }
+                else {
+                    // Default window active, row cap NOT biting: the only useful
+                    // lever is a wider window (or everything).
+                    lines.push("", dim(`(through ${windowLabel} — wider: \`${base} --until ${doublePeriod(opts.until)}\`` +
+                        ` · \`${base} --all\`)`));
+                }
             }
-            return lines;
-        }, base, "upcoming");
+            else if (truncation.truncated && truncation.limit !== null) {
+                // The user stated a bound: no window line, only a row hint, and
+                // only when an explicit --limit truncated. A stated --until/--since
+                // makes --all a usage error (and would discard the very window
+                // they asked for), so a bounded run offers just a bigger cap.
+                const more = truncation.total - truncation.shown;
+                const bounded = untilGiven || sinceGiven;
+                const allLever = bounded ? "" : ` · \`${base} --all\``;
+                lines.push("", dim(`── ${more} more item${more === 1 ? "" : "s"} — ` +
+                    `see more: \`${base} --limit ${truncation.limit * 2}\`${allLever} ──`));
+            }
+            return { data, truncation, lines };
+        }, (items) => renderUpcoming(items), undefined, "upcoming");
     });
     program
         .command("logbook")
@@ -300,11 +426,14 @@ export function registerReadCommands(program) {
         .option("--project <ref>", "restrict to one project's children (uuid or unique name)")
         .option("--since <when>", `only entries logged on/after this bound: ${PERIOD_SINCE}`)
         .option("--until <when>", `only entries logged on/before this bound: ${PERIOD_UNTIL}`)
-        .option("--tag <ref>", "filter by tag (uuid or unique name), direct OR inherited")
-        .option("--exact-tag", "match the named tag only — exclude hierarchy descendants")
+        .option("--tag <ref>", TAG_DESC, collectRef, [])
+        .option("--exact-tag", EXACT_TAG_DESC)
+        .option("--untagged", UNTAGGED_DESC)
         .option("--json", "emit versioned JSON envelope on stdout")
         .option("--db <path>", "explicit database path")
         .action((opts) => {
+        if (tagFlagConflict(opts))
+            return;
         const lim = parseLimit(opts);
         if (!lim.ok)
             return;
@@ -315,28 +444,33 @@ export function registerReadCommands(program) {
             ["--until", until],
         ]) {
             if (value !== undefined && Number.isNaN(value.getTime())) {
-                process.stderr.write(`error: ${flag} is not a parseable date\n`);
-                process.exitCode = ExitCode.Usage;
+                usageError(opts, `${flag} is not a parseable date`);
                 return;
             }
         }
+        // Bounds-&-defaults rule: an explicit range bound (--since/--until)
+        // drops the default row cap unless --limit is also stated — the logged
+        // window the user named is the bound, not an arbitrary 50-row cut.
+        const boundGiven = opts.since !== undefined || opts.until !== undefined;
+        const effectiveLimit = opts.limit === undefined && opts.all !== true && boundGiven ? null : lim.limit;
         const base = invocation("logbook", [
             opts.area !== undefined && `--area ${shellQuote(opts.area)}`,
             opts.project !== undefined && `--project ${shellQuote(opts.project)}`,
             opts.since !== undefined && `--since ${shellQuote(opts.since)}`,
             opts.until !== undefined && `--until ${shellQuote(opts.until)}`,
-            opts.tag !== undefined && `--tag ${shellQuote(opts.tag)}`,
-            opts.exactTag === true && "--exact-tag",
+            ...tagInvocationParts(opts),
         ]);
-        runRead(opts, "logbook", (c) => paginateList(c.read.logbook({
-            limit: null,
-            ...(opts.area !== undefined && { area: opts.area }),
-            ...(opts.project !== undefined && { project: opts.project }),
-            ...(since !== undefined && { since }),
-            ...(until !== undefined && { until }),
-            ...(opts.tag !== undefined && { tag: opts.tag }),
-            ...(opts.exactTag === true && { exactTag: true }),
-        }), lim.limit), (items) => renderLogbook(items), base, "logbook");
+        runRead(opts, "logbook", (c) => {
+            const { items, truncation } = c.read.logbook({
+                ...(opts.area !== undefined && { area: opts.area }),
+                ...(opts.project !== undefined && { project: opts.project }),
+                ...(since !== undefined && { since }),
+                ...(until !== undefined && { until }),
+                ...tagFilterFields(opts),
+                limit: effectiveLimit,
+            });
+            return { data: items, truncation };
+        }, (items) => renderLogbook(items), base, "logbook");
     });
     program
         .command("trash")
@@ -349,36 +483,68 @@ export function registerReadCommands(program) {
         const lim = parseLimit(opts);
         if (!lim.ok)
             return;
-        runRead(opts, "trash", (c) => paginateList(c.read.trash({ limit: null }), lim.limit), renderList, invocation("trash", []), "trash");
+        runRead(opts, "trash", (c) => {
+            const { items, truncation } = c.read.trash({ limit: lim.limit });
+            return { data: items, truncation };
+        }, renderList, invocation("trash", []), "trash");
     });
-    program
-        .command("projects")
-        .description("Active projects in sidebar order: loose projects first, then grouped under " +
-        "their area (optionally scoped to --area <ref>). Someday and future-scheduled " +
-        "projects are hidden — --show-later appends them after each group's active " +
-        "block (state carried by the (~) mark and ‹date› chip)")
+    const projects = program
+        .command("projects [ref]")
+        .description("List active projects in canonical order, or — given a ref — show that one " +
+        "project (exactly like `things project show <ref>`). List: loose projects " +
+        "first, then grouped under their area (optionally scoped to --area <ref>). " +
+        "Someday and future-scheduled projects are hidden — --show-later appends them " +
+        "after each group's active block (state carried by the (~) mark and ‹date› " +
+        "chip). Filter the listed projects by their own tags with --tag / --untagged — " +
+        "inheritance-inclusive (a project inherits its area's tags), the same as the flat " +
+        "views. --show-logged applies only when showing one project.")
         .option("--area <ref>", "filter by area (uuid or unique name)")
         .option("--show-later", "include someday/future-scheduled projects after each active block")
+        .option("--show-logged [n]", "showing one project: include logged items (bare = all)")
+        .option("--overdue", "only projects past their deadline (due today is not overdue)")
         .option("--all", "include someday/future-scheduled projects (same as --show-later)")
         .option("--json", "emit versioned JSON envelope on stdout")
-        .option("--db <path>", "explicit database path")
-        .action((opts) => {
+        .option("--db <path>", "explicit database path");
+    addTagFilterOptions(projects).action((id, opts) => {
+        // Given a ref, this IS `things project show <ref>` — delegate to the same
+        // code path so the output is identical (a true synonym). --overdue rides
+        // along (it filters the shown project's children there).
+        if (id !== undefined) {
+            runProjectShow(id, opts);
+            return;
+        }
+        if (tagFlagConflict(opts))
+            return;
         // --all lifts the sole default restriction here — the hidden later block
         // — so it is exactly --show-later (the charter: --all removes every
         // default restriction on the view's own content).
         const showLater = opts.showLater === true || opts.all === true;
+        // OWN-DEADLINE UNIFORM content scope: keep only projects whose own
+        // deadline is overdue. Composes as AND with --area/--show-later; a
+        // content scope, it never lifts a limit. Threaded into the hidden-later
+        // counting queries too so the counts reflect the same filter.
+        const overdue = opts.overdue === true;
+        // Tag scope (§9a): the projects LIST is a FLAT view — each project ROW is
+        // filtered by its own tags, INHERITANCE-INCLUSIVE (a project inherits its
+        // area's tags), the same as `anytime`. NOT a single-container view.
+        // Threaded into the hidden-later counts too so they reflect the same filter.
+        const tagFilter = tagFilterFields(opts);
         let hints;
         withClient(opts, "projects", (c) => {
             const scope = opts.area !== undefined ? { areaUuid: opts.area } : {};
             const visible = c.read.projects({
                 ...scope,
                 ...(showLater && { later: true }),
+                ...(overdue && { overdue: true }),
+                ...tagFilter,
             });
             if (opts.area === undefined) {
                 // Sidebar scaffold: every VISIBLE area renders (project-less
                 // ones say so), in sidebar order; the loose block leads. One
                 // extra projects query buys the hidden-later counts.
-                const full = showLater ? visible : c.read.projects({ later: true });
+                const full = showLater
+                    ? visible
+                    : c.read.projects({ later: true, ...(overdue && { overdue: true }), ...tagFilter });
                 const shown = new Set(visible.map((i) => i.uuid));
                 const groups = [
                     { area: null, hidden: 0 },
@@ -399,7 +565,12 @@ export function registerReadCommands(program) {
             }
             else if (!showLater) {
                 // --area scoped: only the bottom hint needs a count.
-                const full = c.read.projects({ ...scope, later: true });
+                const full = c.read.projects({
+                    ...scope,
+                    later: true,
+                    ...(overdue && { overdue: true }),
+                    ...tagFilter,
+                });
                 hints = { groups: [{ area: null, hidden: full.length - visible.length }] };
             }
             return visible;
@@ -411,18 +582,60 @@ export function registerReadCommands(program) {
                 return renderProjectsSidebar(items, hints);
             const lines = renderList(items);
             const hidden = hints?.groups.reduce((n, g) => n + g.hidden, 0) ?? 0;
-            if (hidden > 0)
-                lines.push("", dim(`(${hidden} later project${hidden === 1 ? "" : "s"} — visible with \`--show-later\`)`));
+            if (hidden > 0) {
+                // Hidden-section placeholder: the reveal command echoes the user's
+                // own scope (--area) plus the flag that surfaces the later block.
+                const reveal = invocation("projects", [
+                    opts.area !== undefined && `--area ${shellQuote(opts.area)}`,
+                    overdue && "--overdue",
+                    ...tagInvocationParts(opts),
+                    "--show-later",
+                ]);
+                lines.push("", disclosureHint(hidden, "later project", [{ command: reveal }]));
+            }
             return lines;
         });
     });
-    program
-        .command("areas")
-        .description("All areas with their direct tags")
+    const areas = program
+        .command("areas [ref]")
+        .description("List all areas with their direct tags, or — given a ref — show that one area " +
+        "(exactly like `things area show <ref>`: its projects and direct to-dos). " +
+        "--show-later / --show-logged / --area-limit / --project-limit / the tag filters " +
+        "apply only when showing one area.")
         .option("--all", "show every area (no default restriction applies)")
+        .option("--show-later", "showing one area: include its Upcoming and Someday sections")
+        .option("--show-logged [n]", "showing one area: include the n most recent logged items")
+        .option("--project-limit <n>", "showing one area: maximum project rows to show")
+        .option("--area-limit <n>", "showing one area: maximum direct to-dos to show")
+        .option("--overdue", "showing one area: only rows whose own deadline is past (due today is not overdue)")
         .option("--json", "emit versioned JSON envelope on stdout")
-        .option("--db <path>", "explicit database path")
-        .action((opts) => {
+        .option("--db <path>", "explicit database path");
+    addTagFilterOptions(areas).addHelpText("after", CONTAINER_TAG_HINT);
+    areas.action((id, opts) => {
+        // Given a ref, this IS `things area show <ref>` — delegate to the same code
+        // path so the output is identical (a true synonym); --overdue and the tag
+        // filters scope its rows there.
+        if (id !== undefined) {
+            runAreaShow(id, opts);
+            return;
+        }
+        // The areas LIST has no deadline to compare against — an area is not a
+        // dated entity — so --overdue is vacuous here and rejected fail-closed
+        // (the same exclusion style #159 used for upcoming/logbook/trash). The
+        // decision is the contract's (areas: overdue = false).
+        if (!FILTER_CONTRACT.areas.overdue && opts.overdue === true) {
+            usageError(opts, "--overdue does not apply to the areas list — areas have no deadline; use it on `things areas <ref>` (that area's rows) or `things projects --overdue`");
+            return;
+        }
+        // The tag filters scope an area's ROWS, not the area LIST — the bare list
+        // shows every area with its direct tags. Rejected fail-closed here (same
+        // style as --overdue; contract: areas tag = "rejected"). Use
+        // `things areas <ref>` or `things projects --tag`.
+        if (FILTER_CONTRACT.areas.tag === "rejected" &&
+            (hasTagPresence(opts) || opts.untagged === true)) {
+            usageError(opts, "the tag filters (--tag/--untagged) do not apply to the areas list — use them on `things areas <ref>` (that area's rows) or `things projects --tag`");
+            return;
+        }
         withClient(opts, "areas", (c) => c.read.areas(), (data) => {
             const w = uuidDisplayWidth(data);
             return data.map((a) => `${dim(uuidCol(a.uuid, w))}  ${areaMark()} ${a.title}${a.tags.length ? ` ${dim(`#${a.tags.map((t) => t.title).join(" #")}`)}` : ""}`);
@@ -430,12 +643,34 @@ export function registerReadCommands(program) {
     });
     program
         .command("tags")
-        .description("Tag taxonomy (parent → child hierarchy flattened with refs)")
+        .description("Tag taxonomy — the parent → child hierarchy as an indented tree")
         .option("--all", "show every tag (no default restriction applies)")
         .option("--json", "emit versioned JSON envelope on stdout")
         .option("--db <path>", "explicit database path")
         .action((opts) => {
-        withClient(opts, "tags", (c) => c.read.tags(), (data) => data.map((t) => `${t.uuid}  ${t.parent ? `${t.parent.title}/` : ""}${t.title}`));
+        withClient(opts, "tags", (c) => c.read.tags(), 
+        // An INDENTED TREE, leaf names only — nesting is conveyed by indentation
+        // (2 spaces per depth level), mirroring the Things GUI. Tag names are
+        // globally unique (TAGW1-c), so each displayed leaf name is directly
+        // usable as a tag ref — no path prefix or uuid needed. Rows arrive in
+        // canonical DFS order (index, uuid) from tagsView, children following
+        // their parent; the tree IS structure, so leaf names render plainly (not
+        // dim). Depth is the length of the parent-name chain (names are unique).
+        (data) => {
+            const parentOf = new Map(data.map((t) => [t.title, t.parent]));
+            const depthOf = (title) => {
+                let depth = 0;
+                const seen = new Set();
+                let cur = parentOf.get(title) ?? null;
+                while (cur !== null && !seen.has(cur)) {
+                    seen.add(cur);
+                    depth++;
+                    cur = parentOf.get(cur) ?? null;
+                }
+                return depth;
+            };
+            return data.map((t) => `${"  ".repeat(depthOf(t.title))}${t.title}`);
+        });
     });
     program
         .command("changes")
@@ -454,12 +689,14 @@ export function registerReadCommands(program) {
             return;
         const since = parsePeriodStart(opts.since);
         if (Number.isNaN(since.getTime())) {
-            process.stderr.write(`error: --since is not a parseable date: ${opts.since}\n`);
-            process.exitCode = ExitCode.Usage;
+            usageError(opts, `--since is not a parseable date: ${opts.since}`);
             return;
         }
         const base = invocation("changes", [`--since ${shellQuote(opts.since)}`]);
-        runRead(opts, "changes", (c) => paginateList(c.read.changes({ since, limit: null }), lim.limit), (items) => items.length === 0
+        runRead(opts, "changes", (c) => {
+            const { items, truncation } = c.read.changes({ since, limit: lim.limit });
+            return { data: items, truncation };
+        }, (items) => items.length === 0
             ? ["(no changes)"]
             : items.map((i) => `${i.changeKind === "created" ? "+" : "~"} ${formatItem(i)}${i.trashed ? " [trashed]" : ""}`), base);
     });
@@ -470,11 +707,13 @@ export function registerReadCommands(program) {
         "`via heading`); projects rank above to-dos, active above someday, ties broken by " +
         "most-recently-modified. Default scope: OPEN + untrashed items only — widen with " +
         "--logged / --trashed / --all. Scope with --project / --area / --tag (tag matches " +
-        "include hierarchy descendants) / --type.")
+        "include hierarchy descendants) / --type / --overdue (open items past their deadline).")
         .option("--project <ref>", "restrict to one project's children (uuid or unique name)")
         .option("--area <ref>", "restrict to one area's direct members (uuid or unique name)")
-        .option("--tag <ref>", "restrict by tag: direct, inherited, or descendant-tagged")
-        .option("--exact-tag", "match the named tag only — exclude hierarchy descendants")
+        .option("--tag <ref>", TAG_DESC, collectRef, [])
+        .option("--exact-tag", EXACT_TAG_DESC)
+        .option("--untagged", UNTAGGED_DESC)
+        .option("--overdue", OVERDUE_DESC)
         .option("--type <kind>", "todo | project")
         .option("--logged", "include completed/canceled items")
         .option("--trashed", "include trashed items")
@@ -483,40 +722,67 @@ export function registerReadCommands(program) {
         .option("--json", "emit versioned JSON envelope on stdout")
         .option("--db <path>", "explicit database path")
         .action((query, opts) => {
+        const json = opts["json"] === true;
         const type = opts["type"];
         if (type !== undefined && type !== "todo" && type !== "project") {
-            process.stderr.write("error: --type must be todo or project\n");
-            process.exitCode = ExitCode.Usage;
+            usageError({ json }, "--type must be todo or project");
             return;
         }
+        const tagFlags = {
+            ...(Array.isArray(opts["tag"]) && { tag: opts["tag"] }),
+            exactTag: opts["exactTag"] === true,
+            untagged: opts["untagged"] === true,
+        };
+        const overdue = opts["overdue"] === true;
         const all = opts["all"] === true;
+        // Tag-conflict AND the --overdue/status-widening incompatibility both
+        // derive from the shared contract (search: statusWidening = true) —
+        // --overdue lists OPEN, past-deadline items, so combining it with the
+        // completed/canceled/trashed-widening flags is contradictory.
+        const validated = validateViewArgs("search", {
+            ...tagFlags,
+            overdue,
+            logged: opts["logged"] === true,
+            trashed: opts["trashed"] === true,
+            all,
+        }, {
+            untaggedConflict: "--untagged does not combine with --tag/--exact-tag",
+            overdueRejected: "--overdue does not apply to search",
+            overdueStatusWiden: "--overdue does not combine with --logged/--trashed/--all",
+        });
+        if (!validated.ok) {
+            usageError({ json }, validated.message);
+            return;
+        }
         const limitOpt = opts["limit"];
         // --all widens the scope AND lifts the row limit — combining it with an
         // explicit --limit is contradictory (like every other view).
-        const lim = parseLimit({ all, ...(limitOpt !== undefined && { limit: limitOpt }) });
+        const lim = parseLimit({ all, json, ...(limitOpt !== undefined && { limit: limitOpt }) });
         if (!lim.ok)
             return;
         const base = invocation("search", [
             shellQuote(query),
             opts["project"] !== undefined && `--project ${shellQuote(opts["project"])}`,
             opts["area"] !== undefined && `--area ${shellQuote(opts["area"])}`,
-            opts["tag"] !== undefined && `--tag ${shellQuote(opts["tag"])}`,
-            opts["exactTag"] === true && "--exact-tag",
+            ...tagInvocationParts(tagFlags),
+            overdue && "--overdue",
             type !== undefined && `--type ${type}`,
             opts["logged"] === true && "--logged",
             opts["trashed"] === true && "--trashed",
         ]);
-        runRead(opts, "search", (c) => paginateList(c.read.search(query, {
-            limit: null,
-            ...(opts["project"] !== undefined && { project: opts["project"] }),
-            ...(opts["area"] !== undefined && { area: opts["area"] }),
-            ...(opts["tag"] !== undefined && { tag: opts["tag"] }),
-            ...(opts["exactTag"] === true && { exactTag: true }),
-            ...(type !== undefined && { type: type === "todo" ? "to-do" : "project" }),
-            ...(opts["logged"] === true && { logged: true }),
-            ...(opts["trashed"] === true && { trashed: true }),
-            ...(all && { all: true }),
-        }), lim.limit), renderSearch, base);
+        runRead(opts, "search", (c) => {
+            const { items, truncation } = c.read.search(query, {
+                limit: lim.limit,
+                ...(opts["project"] !== undefined && { project: opts["project"] }),
+                ...(opts["area"] !== undefined && { area: opts["area"] }),
+                ...validated.filter,
+                ...(type !== undefined && { type: type === "todo" ? "to-do" : "project" }),
+                ...(opts["logged"] === true && { logged: true }),
+                ...(opts["trashed"] === true && { trashed: true }),
+                ...(all && { all: true }),
+            });
+            return { data: items, truncation };
+        }, renderSearch, base);
     });
     // Every row-rendering view points at `things legend` for its glyph language.
     const GLYPH_VIEWS = new Set([