things-api 0.7.0 → 0.9.0

package/dist/cli/glyphs.js

@@ -0,0 +1,282 @@
+import { blue, bold, brightBlue, dim, green, red, strike, underline, yellow } from "./style.js";
+const MONTHS = [
+    "Jan",
+    "Feb",
+    "Mar",
+    "Apr",
+    "May",
+    "Jun",
+    "Jul",
+    "Aug",
+    "Sep",
+    "Oct",
+    "Nov",
+    "Dec",
+];
+const WEEKDAYS = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
+/** `Jul 31` — the year is appended only when it differs from today's. */
+export function shortDate(iso, todayIso) {
+    const [y, m, d] = iso.split("-").map(Number);
+    const label = `${MONTHS[(m ?? 1) - 1]} ${d}`;
+    return String(y) === todayIso.slice(0, 4) ? label : `${label} ${y}`;
+}
+/**
+ * `Fri, Aug 28` — the GUI's detail-header date form: weekday abbreviation +
+ * month + day, the year appended only when it differs from today's (same
+ * convention as {@link shortDate} / the ‹date› chip).
+ */
+export function weekdayDate(iso, todayIso) {
+    const [y, m, d] = iso.split("-").map(Number);
+    const weekday = WEEKDAYS[new Date(Date.UTC(y ?? 0, (m ?? 1) - 1, d ?? 1)).getUTCDay()];
+    return `${weekday}, ${shortDate(iso, todayIso)}`;
+}
+/** The GUI's grey schedule pill: `‹Jul 31›` on future-scheduled rows. */
+export function dateChip(iso, todayIso) {
+    return dim(`‹${shortDate(iso, todayIso)}›`);
+}
+/** Completion date on logged rows (the GUI's blue date before the title). */
+export function loggedDate(stopped, todayIso) {
+    const iso = `${stopped.getFullYear()}-${String(stopped.getMonth() + 1).padStart(2, "0")}-${String(stopped.getDate()).padStart(2, "0")}`;
+    return bold(blue(shortDate(iso, todayIso)));
+}
+/**
+ * To-do checkbox: `[ ]` open, `[✓]` completed, `[×]` canceled, `[~]`
+ * someday (undated — a dated someday row reads as scheduled and keeps the
+ * plain box; its date chip carries the state).
+ */
+export function todoBox(item) {
+    if (item.status === "completed")
+        return blue("[✓]");
+    if (item.status === "canceled")
+        return blue("[×]");
+    // A repeating TEMPLATE is the rule itself, not a checkable instance — the
+    // GUI shows only the ↻ glyph where a checkbox would be. We keep the
+    // brackets (still a to-do) but seat ↻ INSIDE them so the row reads as
+    // "the recurring one" at a glance, distinct from its spawned instances
+    // (which are ordinary [ ] rows). Never someday, though the DB stores it so.
+    if (item.repeating.isTemplate)
+        return dim("[↻]");
+    if (item.start === "someday" && item.startDate === null)
+        return dim("[~]");
+    return "[ ]";
+}
+/**
+ * Project circle — round where to-dos are square, same marks: `( )` open,
+ * `(✓)` completed, `(×)` canceled, `(~)` someday. (The pie-fill progress
+ * glyphs were tried and dropped — they render inconsistently at cell size;
+ * progress lives in the ratio chip instead.)
+ */
+export function projectCircle(item) {
+    if (item.status === "completed")
+        return blue("(✓)");
+    if (item.status === "canceled")
+        return blue("(×)");
+    // Repeating project template: ↻ inside the circle (the to-do rule above).
+    if (item.repeating.isTemplate)
+        return dim("(↻)");
+    // Open projects render blue — GUI parity (the sidebar/list accent) and a
+    // second, color-independent cue on top of the round bracket that this row
+    // is a project, not a to-do.
+    if (item.start === "someday" && item.startDate === null)
+        return blue("(~)");
+    return blue("( )");
+}
+/** Progress chip on project rows: `‹remaining/total›` (the GUI shows only the remaining count). */
+export function countChip(item) {
+    const total = item.untrashedLeafActionsCount;
+    return dim(total === 0 ? "‹0›" : `‹${item.openUntrashedLeafActionsCount}/${total}›`);
+}
+/** Area marker (the GUI's green cube icon; a hexagon is a cube's silhouette). */
+export const areaMark = () => green("⬡");
+/** Whole-day difference between two ISO dates (positive = `to` is later). */
+function daysBetween(fromIso, toIso) {
+    const [fy, fm, fd] = fromIso.split("-").map(Number);
+    const [ty, tm, td] = toIso.split("-").map(Number);
+    return Math.round((Date.UTC(ty ?? 0, (tm ?? 1) - 1, td ?? 1) - Date.UTC(fy ?? 0, (fm ?? 1) - 1, fd ?? 1)) /
+        86_400_000);
+}
+/**
+ * Uncapped relative phrasing for the detail-card deadline hint, GUI wording:
+ * `due today`, `46 days left`, `3 days overdue`.
+ */
+function deadlineRelative(iso, todayIso) {
+    const diff = daysBetween(todayIso, iso);
+    if (diff === 0)
+        return "due today";
+    return diff > 0
+        ? `${diff} day${diff === 1 ? "" : "s"} left`
+        : `${-diff} day${diff === -1 ? "" : "s"} overdue`;
+}
+/**
+ * Detail-card deadline line value (to-do / project / area cards). GUI parity:
+ * the full `Fri, Aug 28` weekday date (year appended when not the current
+ * year), then a muted relative hint — `(46 days left)` / `(due today)` /
+ * `(3 days overdue)`. The date is bold red once due or overdue, bold otherwise;
+ * the hint is always muted. LIST rows keep the compact {@link deadlineToken}.
+ */
+export function deadlineDetail(deadlineIso, todayIso) {
+    const date = weekdayDate(deadlineIso, todayIso);
+    const styledDate = daysBetween(todayIso, deadlineIso) <= 0 ? bold(red(date)) : bold(date);
+    return `${styledDate} ${dim(`(${deadlineRelative(deadlineIso, todayIso)})`)}`;
+}
+/** The share link the GUI's context menu copies — pasteable back into any ref argument. */
+export function thingsLink(uuid) {
+    return dim(`things:///show?id=${uuid}`);
+}
+/**
+ * The detail card's "when" value, GUI semantics: any past or current
+ * schedule collapses to Today / This Evening (the data model keeps the real
+ * date; the card does not), future dates show the date, undated someday
+ * shows Someday. Appends the reminder time (clock glyph) when set.
+ */
+export function whenValue(item, todayIso) {
+    let label = null;
+    if (item.startDate !== null) {
+        label =
+            item.startDate <= todayIso
+                ? item.todaySection === "evening"
+                    ? `${eveningMoon()} This Evening`
+                    : `${todayStar()} Today`
+                : shortDate(item.startDate, todayIso);
+    }
+    else if (item.start === "someday") {
+        label = "Someday";
+    }
+    if (label === null)
+        return null;
+    return item.reminder === null ? label : `${label} ${dim(REMINDER_MARK)} ${item.reminder}`;
+}
+/**
+ * Deadline token, mirroring the GUI's flag chip: relative phrasing near the
+ * deadline (`⚑ 3 days left` up to 14 days out; `⚑ 4 days ago` up to 59 days
+ * past; `⚑ today` on the day), then the date shorthand — `Sep 16` within
+ * the current year, `Feb 2027` beyond it. Overdue and due-today render
+ * bold red; upcoming renders bold dim (the GUI's gray).
+ */
+export function deadlineToken(deadlineIso, todayIso) {
+    const diff = daysBetween(todayIso, deadlineIso);
+    let label;
+    if (diff === 0)
+        label = "today";
+    else if (diff > 0 && diff <= 14)
+        label = `${diff} day${diff === 1 ? "" : "s"} left`;
+    else if (diff < 0 && diff >= -59)
+        label = `${-diff} day${diff === -1 ? "" : "s"} ago`;
+    else {
+        const [y, m, d] = deadlineIso.split("-").map(Number);
+        const month = MONTHS[(m ?? 1) - 1];
+        label = String(y) === todayIso.slice(0, 4) ? `${month} ${d}` : `${month} ${y}`;
+    }
+    const chip = `⚑ ${label}`;
+    return diff <= 0 ? bold(red(chip)) : bold(dim(chip));
+}
+/** Notes-present marker (the GUI's small document icon). */
+export const NOTES_MARK = "≡";
+/**
+ * Reminder-set marker (the GUI's small bell icon; no Unicode bell renders
+ * well — the clock-face quadrant won Mike's font test, accepted despite its
+ * family resemblance to the project pies).
+ */
+export const REMINDER_MARK = "◷";
+/** Checklist-present marker (the GUI's small list icon). */
+export const CHECKLIST_MARK = "≔";
+/** Today star / This-Evening crescent, rendered after the box in today-aware views. */
+export const todayStar = () => yellow("★");
+export const eveningMoon = () => brightBlue("⏾");
+export const LEGEND_GROUPS = [
+    "To-dos",
+    "Projects",
+    "Markers & chips",
+    "Colors & styles",
+    "Sections & hints",
+];
+/**
+ * The rendered visual language, derived from the glyph helpers above so it
+ * documents what actually renders — never a hand-kept copy that can drift.
+ * Each `glyph` is a real sample built from the same styling the list rows use;
+ * `things legend` groups these for humans and `--json` emits them ANSI-stripped.
+ */
+export const LEGEND = [
+    // To-dos — the [ ]-family box carries state with color stripped.
+    { glyph: "[ ]", meaning: "to-do, open", group: "To-dos" },
+    { glyph: blue("[✓]"), meaning: "to-do, completed", group: "To-dos" },
+    { glyph: blue("[×]"), meaning: "to-do, canceled (title struck through)", group: "To-dos" },
+    { glyph: dim("[~]"), meaning: "to-do, someday (undated)", group: "To-dos" },
+    {
+        glyph: dim("[↻]"),
+        meaning: "repeating to-do — the rule itself (instances are ordinary [ ])",
+        group: "To-dos",
+    },
+    // Projects — round where to-dos are square; open rows render blue.
+    { glyph: blue("( )"), meaning: "project, open", group: "Projects" },
+    { glyph: blue("(✓)"), meaning: "project, completed", group: "Projects" },
+    { glyph: blue("(×)"), meaning: "project, canceled", group: "Projects" },
+    { glyph: blue("(~)"), meaning: "project, someday (undated)", group: "Projects" },
+    {
+        glyph: dim("(↻)"),
+        meaning: "repeating project — the recurring rule itself",
+        group: "Projects",
+    },
+    {
+        glyph: dim("‹2/5›"),
+        meaning: "project progress: remaining/total to-dos (‹0› when it has none)",
+        group: "Projects",
+    },
+    // Markers & chips — trail the title (bell, notes, checklist) or precede it.
+    { glyph: todayStar(), meaning: "Today member", group: "Markers & chips" },
+    { glyph: eveningMoon(), meaning: "This Evening member", group: "Markers & chips" },
+    {
+        glyph: bold(dim("⚑")),
+        meaning: "deadline — bold gray while upcoming, bold red once due or overdue",
+        group: "Markers & chips",
+    },
+    { glyph: dim(NOTES_MARK), meaning: "has notes", group: "Markers & chips" },
+    { glyph: dim(REMINDER_MARK), meaning: "has a reminder time", group: "Markers & chips" },
+    { glyph: dim(CHECKLIST_MARK), meaning: "has a checklist", group: "Markers & chips" },
+    { glyph: areaMark(), meaning: "area", group: "Markers & chips" },
+    {
+        glyph: dim("‹Jul 31›"),
+        meaning: "scheduled date (year appended when not the current year)",
+        group: "Markers & chips",
+    },
+    {
+        glyph: green("#tag"),
+        meaning: "tag — muted on list rows, green on the opened item",
+        group: "Markers & chips",
+    },
+    // Colors & styles — enhancements on top of the shape; never the only cue.
+    {
+        glyph: dim("a1b2c3d4"),
+        meaning: "item id prefix (8+ chars; full id in --json) — pass to any command",
+        group: "Colors & styles",
+    },
+    {
+        glyph: dim("dim text"),
+        meaning: "later, hidden, inactive, or completed row",
+        group: "Colors & styles",
+    },
+    { glyph: strike("struck"), meaning: "canceled item title", group: "Colors & styles" },
+    { glyph: blue("blue"), meaning: "open project (its circle and title)", group: "Colors & styles" },
+    {
+        glyph: bold(underline("bold underline")),
+        meaning: "container header — a project title row, or a section header",
+        group: "Colors & styles",
+    },
+    // Sections & hints — structure and the never-silent truncation notices.
+    {
+        glyph: bold("──"),
+        meaning: "section divider (area, Upcoming date bucket, Logbook month heading)",
+        group: "Sections & hints",
+    },
+    {
+        glyph: dim("… 14 more"),
+        meaning: "a block was truncated; a drill-down command follows",
+        group: "Sections & hints",
+    },
+    {
+        glyph: dim("(23 later — --show-later)"),
+        meaning: "default-hidden rows, and the flag that reveals them",
+        group: "Sections & hints",
+    },
+];
+//# sourceMappingURL=glyphs.js.map

package/dist/cli/glyphs.js.map

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

package/dist/cli/main.js

@@ -13,9 +13,11 @@ import { registerAreaCommands } from "./commands/area.js";
 import { registerProjectCommands } from "./commands/project.js";
 import { registerReadCommands } from "./commands/reads.js";
 import { registerSetup } from "./commands/setup.js";
+import { registerShowCommands } from "./commands/show.js";
 import { registerSnapshot } from "./commands/snapshot.js";
 import { registerTodoCommands } from "./commands/todo.js";
 import { registerWriteCommands } from "./commands/writes.js";
+import { resolveInvocation } from "./resolve-invocation.js";
 import { ExitCode, PKG_VERSION } from "../contracts.js";
 const AGENT_NOTES = `
 AGENT NOTES:
@@ -25,11 +27,14 @@ AGENT NOTES:
     fail with the candidates listed.
   - A Things share link (Share > Copy Link, "things:///show?id=<uuid>") is
     accepted anywhere a uuid or name is expected — it is stripped to the id.
+  - The word \`show\` may be omitted: \`things <ref>\` shows the referenced
+    item whenever <ref> is not a command name (command names always win).
   - Exit codes are stable: 0 ok, 2 usage, 3 verify-failed, 4 blocked,
     5 drift-blocked, 6 unsupported, 7 environment.
   - No command ever prompts interactively; operations with cascading or
     permanent effects require explicit flags documented in their --help.
   - Discover the full operation catalog with: things capabilities --json
+  - Symbols & colors in list output: run \`things legend\` (add --json for the table).
   - Every write supports --dry-run: preview the planned change and its
     expected effect without executing anything.
   - Failures are loud: a change that does not take effect exits 3; refused
@@ -44,6 +49,7 @@ export function buildProgram() {
         .addHelpText("after", AGENT_NOTES);
     registerDoctor(program);
     registerReadCommands(program);
+    registerShowCommands(program);
     registerProjectCommands(program);
     registerAreaCommands(program);
     registerTodoCommands(program);
@@ -58,7 +64,11 @@ export function runCli() {
     program.exitOverride((err) => {
         process.exit(err.exitCode === 0 ? ExitCode.Ok : ExitCode.Usage);
     });
-    program.parse();
+    // The single router (docs/design/cli-grammar.md): classify the invocation,
+    // then dispatch its normalized argv. Sugar forms (bare noun, keyword-in-show)
+    // normalize into the canonical grammar here.
+    const { argv } = resolveInvocation(program, process.argv.slice(2));
+    program.parse(argv, { from: "user" });
 }
 // Direct-run detection must survive the npm .bin symlink (argv[1] ends with
 // "things", not "main.js") — resolve through realpath and compare to this

package/dist/cli/main.js.map

@@ -1 +1 @@
-{"version":3,"file":"main.js","sourceRoot":"","sources":["../../src/cli/main.ts"],"names":[],"mappings":";AACA;;;;GAIG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAExD,MAAM,WAAW,GAAG;;;;;;;;;;;;;;;;;CAiBnB,CAAC;AAEF,MAAM,UAAU,YAAY;IAC1B,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;IAC9B,OAAO;SACJ,IAAI,CAAC,QAAQ,CAAC;SACd,WAAW,CAAC,oDAAoD,CAAC;SACjE,OAAO,CAAC,WAAW,CAAC;SACpB,WAAW,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;IACrC,cAAc,CAAC,OAAO,CAAC,CAAC;IACxB,oBAAoB,CAAC,OAAO,CAAC,CAAC;IAC9B,uBAAuB,CAAC,OAAO,CAAC,CAAC;IACjC,oBAAoB,CAAC,OAAO,CAAC,CAAC;IAC9B,oBAAoB,CAAC,OAAO,CAAC,CAAC;IAC9B,qBAAqB,CAAC,OAAO,CAAC,CAAC;IAC/B,aAAa,CAAC,OAAO,CAAC,CAAC;IACvB,gBAAgB,CAAC,OAAO,CAAC,CAAC;IAC1B,WAAW,CAAC,OAAO,CAAC,CAAC;IACrB,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,UAAU,MAAM;IACpB,MAAM,OAAO,GAAG,YAAY,EAAE,CAAC;IAC/B,OAAO,CAAC,YAAY,CAAC,CAAC,GAAG,EAAE,EAAE;QAC3B,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IAClE,CAAC,CAAC,CAAC;IACH,OAAO,CAAC,KAAK,EAAE,CAAC;AAClB,CAAC;AAED,4EAA4E;AAC5E,0EAA0E;AAC1E,wEAAwE;AACxE,4EAA4E;AAC5E,+BAA+B;AAC/B,MAAM,WAAW,GAAG,CAAC,GAAY,EAAE;IACjC,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAChC,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IACxC,IAAI,CAAC;QACH,OAAO,YAAY,CAAC,OAAO,CAAC,KAAK,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAClE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC,CAAC,EAAE,CAAC;AACL,IAAI,WAAW,EAAE,CAAC;IAChB,MAAM,EAAE,CAAC;AACX,CAAC"}
+{"version":3,"file":"main.js","sourceRoot":"","sources":["../../src/cli/main.ts"],"names":[],"mappings":"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"}

package/dist/cli/period.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Period-and-calendar grammar shared by the read views: the `--since`/`--until`
+ * whole-period parsers, the relative-period (`3d`/`2w`/`1m`/`1y`) grammar, and
+ * the Upcoming date-bucket labeller. Fully pure — no CLI or app imports — so
+ * the renderers and command registrations can both draw on it.
+ */
+declare const FULL_MONTHS: readonly ["January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"];
+export { FULL_MONTHS };
+/**
+ * `--until` accepting whole periods: `2024` means through Dec 31 2024,
+ * `2024-03` through Mar 31, `2024-03-05` through end of that day; relative
+ * periods (`2w`, `1m`, `1y`) count FORWARD from now through the end of the
+ * landing day; anything else parses as an instant.
+ */
+export declare function parsePeriodEnd(s: string, now?: Date): Date;
+/**
+ * `--since` accepting the same vocabulary at the period's START: `2024` =
+ * Jan 1 2024 00:00, `2024-03` = Mar 1, `2024-03-05` = that midnight;
+ * relative periods (`2w`, `1m`) count BACKWARD from now to the landing
+ * day's midnight; anything else parses as an instant.
+ */
+export declare function parsePeriodStart(s: string, now?: Date): Date;
+/**
+ * GUI-style Upcoming bucket for a date, granularity decaying with distance:
+ * individual days for the next week ("Wed Jul 15"), the remainder of the
+ * current month ("Jul 19–31"), months through the end of NEXT year
+ * ("August", "January 2027"), then bare years ("2028").
+ */
+export declare function upcomingBucket(iso: string, todayIso: string): {
+    label: string;
+    isDay: boolean;
+};

package/dist/cli/period.js

@@ -0,0 +1,129 @@
+/**
+ * Period-and-calendar grammar shared by the read views: the `--since`/`--until`
+ * whole-period parsers, the relative-period (`3d`/`2w`/`1m`/`1y`) grammar, and
+ * the Upcoming date-bucket labeller. Fully pure — no CLI or app imports — so
+ * the renderers and command registrations can both draw on it.
+ */
+const FULL_MONTHS = [
+    "January",
+    "February",
+    "March",
+    "April",
+    "May",
+    "June",
+    "July",
+    "August",
+    "September",
+    "October",
+    "November",
+    "December",
+];
+const WEEKDAYS = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
+const SHORT_MONTHS = [
+    "Jan",
+    "Feb",
+    "Mar",
+    "Apr",
+    "May",
+    "Jun",
+    "Jul",
+    "Aug",
+    "Sep",
+    "Oct",
+    "Nov",
+    "Dec",
+];
+export { FULL_MONTHS };
+/**
+ * Relative period: `3d`/`2w`/`1m`/`1y` (days/weeks/calendar months/years),
+ * counted from `now` — FORWARD for an until-bound, BACKWARD for a since-
+ * bound (each command's natural direction; the flag name carries it).
+ */
+const RELATIVE_PERIOD = /^(\d+)([dwmy])$/i;
+function relativePeriodDate(m, now, sign) {
+    const n = sign * Number(m[1]);
+    const unit = (m[2] ?? "").toLowerCase();
+    const d = new Date(now);
+    if (unit === "d")
+        d.setDate(d.getDate() + n);
+    else if (unit === "w")
+        d.setDate(d.getDate() + 7 * n);
+    else if (unit === "m")
+        d.setMonth(d.getMonth() + n);
+    else
+        d.setFullYear(d.getFullYear() + n);
+    return d;
+}
+/**
+ * `--until` accepting whole periods: `2024` means through Dec 31 2024,
+ * `2024-03` through Mar 31, `2024-03-05` through end of that day; relative
+ * periods (`2w`, `1m`, `1y`) count FORWARD from now through the end of the
+ * landing day; anything else parses as an instant.
+ */
+export function parsePeriodEnd(s, now = new Date()) {
+    const rel = RELATIVE_PERIOD.exec(s.trim());
+    if (rel !== null) {
+        const d = relativePeriodDate(rel, now, 1);
+        return new Date(d.getFullYear(), d.getMonth(), d.getDate(), 23, 59, 59, 999);
+    }
+    const m = /^(\d{4})(?:-(\d{2})(?:-(\d{2}))?)?$/.exec(s.trim());
+    if (m === null)
+        return new Date(s);
+    const year = Number(m[1]);
+    // Day 0 of month n+1 = the last day of month n.
+    if (m[2] === undefined)
+        return new Date(year, 11, 31, 23, 59, 59, 999);
+    const month = Number(m[2]) - 1;
+    if (m[3] === undefined)
+        return new Date(year, month + 1, 0, 23, 59, 59, 999);
+    return new Date(year, month, Number(m[3]), 23, 59, 59, 999);
+}
+/**
+ * `--since` accepting the same vocabulary at the period's START: `2024` =
+ * Jan 1 2024 00:00, `2024-03` = Mar 1, `2024-03-05` = that midnight;
+ * relative periods (`2w`, `1m`) count BACKWARD from now to the landing
+ * day's midnight; anything else parses as an instant.
+ */
+export function parsePeriodStart(s, now = new Date()) {
+    const rel = RELATIVE_PERIOD.exec(s.trim());
+    if (rel !== null) {
+        const d = relativePeriodDate(rel, now, -1);
+        return new Date(d.getFullYear(), d.getMonth(), d.getDate());
+    }
+    const m = /^(\d{4})(?:-(\d{2})(?:-(\d{2}))?)?$/.exec(s.trim());
+    if (m === null)
+        return new Date(s);
+    const year = Number(m[1]);
+    if (m[2] === undefined)
+        return new Date(year, 0, 1);
+    const month = Number(m[2]) - 1;
+    if (m[3] === undefined)
+        return new Date(year, month, 1);
+    return new Date(year, month, Number(m[3]));
+}
+/**
+ * GUI-style Upcoming bucket for a date, granularity decaying with distance:
+ * individual days for the next week ("Wed Jul 15"), the remainder of the
+ * current month ("Jul 19–31"), months through the end of NEXT year
+ * ("August", "January 2027"), then bare years ("2028").
+ */
+export function upcomingBucket(iso, todayIso) {
+    const [y, m, d] = iso.split("-").map(Number);
+    const [y0, m0, d0] = todayIso.split("-").map(Number);
+    const diff = Math.round((Date.UTC(y ?? 0, (m ?? 1) - 1, d ?? 1) - Date.UTC(y0 ?? 0, (m0 ?? 1) - 1, d0 ?? 1)) /
+        86_400_000);
+    if (diff <= 7) {
+        const weekday = WEEKDAYS[new Date(Date.UTC(y ?? 0, (m ?? 1) - 1, d ?? 1)).getUTCDay()];
+        return { label: `${weekday} ${SHORT_MONTHS[(m ?? 1) - 1]} ${d}`, isDay: true };
+    }
+    if (y === y0 && m === m0) {
+        const lastDay = new Date(y ?? 0, m ?? 1, 0).getDate();
+        return { label: `${SHORT_MONTHS[(m ?? 1) - 1]} ${(d0 ?? 1) + 8}–${lastDay}`, isDay: false };
+    }
+    if ((y ?? 0) <= (y0 ?? 0) + 1) {
+        const month = FULL_MONTHS[(m ?? 1) - 1];
+        return { label: y === y0 ? `${month}` : `${month} ${y}`, isDay: false };
+    }
+    return { label: `${y}`, isDay: false };
+}
+//# sourceMappingURL=period.js.map

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,76 @@
+/**
+ * The read driver: open the client, stamp the envelope meta, and emit either
+ * the `--json` envelope or human lines (with the TTY-only title preamble,
+ * normalized-form echo, and truncation hint). Plus the shared `--limit`/`--all`
+ * cap parsing and the invocation-echo helpers every read command reuses. No
+ * commander dependency — command registration lives in the command modules.
+ */
+import { type ThingsClient } from "../client.ts";
+import { type GroupedPagination, type Pagination } from "../contracts.ts";
+export interface GlobalReadOpts {
+    json?: boolean;
+    db?: string;
+}
+export interface PagedResult<T> {
+    data: T;
+    /** Flat-view truncation — carried into meta and the appended hint. */
+    pagination?: Pagination;
+    /** Grouped-view (anytime/someday) per-block truncation — carried into meta. */
+    grouped?: GroupedPagination;
+    /**
+     * 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 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 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;
+}): LimitResolution;
+/**
+ * Resolve one cap flag (`--limit`, `--area-limit`, `--project-limit`) against
+ * `--all`: positive integer required, `--all` conflicts with an explicit
+ * value and otherwise lifts the cap (null). The conflict/default decision is
+ * the shared {@link resolveCap}; this surface adds the string→integer
+ * validation and the usage-error emission.
+ */
+export declare function parseCap(flag: string, value: string | undefined, defaultLimit: number, all: boolean): LimitResolution;
+export { shellQuote } from "./shell-quote.ts";
+/** Reconstruct `things <name> <flags…>`, dropping falsy/empty parts. */
+export declare function invocation(name: string, parts: Array<string | false | undefined>): string;
+/**
+ * The unified truncation hint: a muted `── N more items — see more: … · all:
+ * … ──` line whose commands echo the user's actual invocation, so a bigger
+ * `--limit` or `--all` is one copy-paste away. Returns null when nothing was
+ * dropped or the caller already asked for every row.
+ */
+export declare function truncationHint(base: string, pagination: Pagination): string | null;