things-api 0.8.0 → 0.9.0

package/dist/cli/glyphs.js

@@ -1,4 +1,4 @@
-import { blue, bold, brightBlue, dim, green, red, yellow } from "./style.js";
+import { blue, bold, brightBlue, dim, green, red, strike, underline, yellow } from "./style.js";
 const MONTHS = [
     "Jan",
     "Feb",
@@ -13,12 +13,23 @@ const MONTHS = [
     "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)}›`);
@@ -84,23 +95,29 @@ function daysBetween(fromIso, toIso) {
     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: `today`, `3 days left`, `253 days ago`. */
-export function relativeDays(iso, todayIso) {
+/**
+ * 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 "today";
+        return "due today";
     return diff > 0
         ? `${diff} day${diff === 1 ? "" : "s"} left`
-        : `${-diff} day${diff === -1 ? "" : "s"} ago`;
+        : `${-diff} day${diff === -1 ? "" : "s"} overdue`;
 }
 /**
- * Detail-card deadline line value (the GUI's "Deadline: Oct 30, 2025 —
- * 253 days ago" row): exact date plus uncapped relative phrasing. Bold red
- * once due; bold dim while upcoming.
+ * 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 text = `⚑ ${shortDate(deadlineIso, todayIso)} (${relativeDays(deadlineIso, todayIso)})`;
-    return daysBetween(todayIso, deadlineIso) <= 0 ? bold(red(text)) : bold(dim(text));
+    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) {
@@ -166,4 +183,100 @@ 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

@@ -1 +1 @@
-{"version":3,"file":"glyphs.js","sourceRoot":"","sources":["../../src/cli/glyphs.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAE7E,MAAM,MAAM,GAAG;IACb,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;CACG,CAAC;AAEX,yEAAyE;AACzE,MAAM,UAAU,SAAS,CAAC,GAAW,EAAE,QAAgB;IACrD,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAC7C,MAAM,KAAK,GAAG,GAAG,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC;IAC7C,OAAO,MAAM,CAAC,CAAC,CAAC,KAAK,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,KAAK,IAAI,CAAC,EAAE,CAAC;AACtE,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,QAAQ,CAAC,GAAW,EAAE,QAAgB;IACpD,OAAO,GAAG,CAAC,IAAI,SAAS,CAAC,GAAG,EAAE,QAAQ,CAAC,GAAG,CAAC,CAAC;AAC9C,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,UAAU,CAAC,OAAa,EAAE,QAAgB;IACxD,MAAM,GAAG,GAAG,GAAG,OAAO,CAAC,WAAW,EAAE,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC;IACxI,OAAO,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC;AAC9C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,OAAO,CAAC,IAAU;IAChC,IAAI,IAAI,CAAC,MAAM,KAAK,WAAW;QAAE,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC;IACpD,IAAI,IAAI,CAAC,MAAM,KAAK,UAAU;QAAE,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC;IACnD,0EAA0E;IAC1E,oEAAoE;IACpE,sEAAsE;IACtE,uEAAuE;IACvE,4EAA4E;IAC5E,IAAI,IAAI,CAAC,SAAS,CAAC,UAAU;QAAE,OAAO,GAAG,CAAC,KAAK,CAAC,CAAC;IACjD,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS,IAAI,IAAI,CAAC,SAAS,KAAK,IAAI;QAAE,OAAO,GAAG,CAAC,KAAK,CAAC,CAAC;IAC3E,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,IAAa;IACzC,IAAI,IAAI,CAAC,MAAM,KAAK,WAAW;QAAE,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC;IACpD,IAAI,IAAI,CAAC,MAAM,KAAK,UAAU;QAAE,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC;IACnD,0EAA0E;IAC1E,IAAI,IAAI,CAAC,SAAS,CAAC,UAAU;QAAE,OAAO,GAAG,CAAC,KAAK,CAAC,CAAC;IACjD,yEAAyE;IACzE,0EAA0E;IAC1E,6BAA6B;IAC7B,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS,IAAI,IAAI,CAAC,SAAS,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC;IAC5E,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC;AACrB,CAAC;AAED,mGAAmG;AACnG,MAAM,UAAU,SAAS,CAAC,IAAa;IACrC,MAAM,KAAK,GAAG,IAAI,CAAC,yBAAyB,CAAC;IAC7C,OAAO,GAAG,CAAC,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,6BAA6B,IAAI,KAAK,GAAG,CAAC,CAAC;AACvF,CAAC;AAED,iFAAiF;AACjF,MAAM,CAAC,MAAM,QAAQ,GAAG,GAAW,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;AAEjD,6EAA6E;AAC7E,SAAS,WAAW,CAAC,OAAe,EAAE,KAAa;IACjD,MAAM,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IACpD,MAAM,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAClD,OAAO,IAAI,CAAC,KAAK,CACf,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC,GAAG,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC,GAAG,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC,CAAC;QACrF,UAAU,CACb,CAAC;AACJ,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,YAAY,CAAC,GAAW,EAAE,QAAgB;IACxD,MAAM,IAAI,GAAG,WAAW,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;IACxC,IAAI,IAAI,KAAK,CAAC;QAAE,OAAO,OAAO,CAAC;IAC/B,OAAO,IAAI,GAAG,CAAC;QACb,CAAC,CAAC,GAAG,IAAI,OAAO,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,OAAO;QAC5C,CAAC,CAAC,GAAG,CAAC,IAAI,OAAO,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC;AAClD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,WAAmB,EAAE,QAAgB;IAClE,MAAM,IAAI,GAAG,KAAK,SAAS,CAAC,WAAW,EAAE,QAAQ,CAAC,KAAK,YAAY,CAAC,WAAW,EAAE,QAAQ,CAAC,GAAG,CAAC;IAC9F,OAAO,WAAW,CAAC,QAAQ,EAAE,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;AACrF,CAAC;AAED,2FAA2F;AAC3F,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,OAAO,GAAG,CAAC,qBAAqB,IAAI,EAAE,CAAC,CAAC;AAC1C,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CACvB,IAA+E,EAC/E,QAAgB;IAEhB,IAAI,KAAK,GAAkB,IAAI,CAAC;IAChC,IAAI,IAAI,CAAC,SAAS,KAAK,IAAI,EAAE,CAAC;QAC5B,KAAK;YACH,IAAI,CAAC,SAAS,IAAI,QAAQ;gBACxB,CAAC,CAAC,IAAI,CAAC,YAAY,KAAK,SAAS;oBAC/B,CAAC,CAAC,GAAG,WAAW,EAAE,eAAe;oBACjC,CAAC,CAAC,GAAG,SAAS,EAAE,QAAQ;gBAC1B,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;IAC5C,CAAC;SAAM,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QACpC,KAAK,GAAG,SAAS,CAAC;IACpB,CAAC;IACD,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAChC,OAAO,IAAI,CAAC,QAAQ,KAAK,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,KAAK,IAAI,GAAG,CAAC,aAAa,CAAC,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;AAC5F,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,WAAmB,EAAE,QAAgB;IACjE,MAAM,IAAI,GAAG,WAAW,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC;IAChD,IAAI,KAAa,CAAC;IAClB,IAAI,IAAI,KAAK,CAAC;QAAE,KAAK,GAAG,OAAO,CAAC;SAC3B,IAAI,IAAI,GAAG,CAAC,IAAI,IAAI,IAAI,EAAE;QAAE,KAAK,GAAG,GAAG,IAAI,OAAO,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC;SAC/E,IAAI,IAAI,GAAG,CAAC,IAAI,IAAI,IAAI,CAAC,EAAE;QAAE,KAAK,GAAG,GAAG,CAAC,IAAI,OAAO,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC;SACjF,CAAC;QACJ,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GAAG,WAAW,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACrD,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QACnC,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC,KAAK,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,IAAI,CAAC,EAAE,CAAC;IACjF,CAAC;IACD,MAAM,IAAI,GAAG,KAAK,KAAK,EAAE,CAAC;IAC1B,OAAO,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;AACvD,CAAC;AAED,4DAA4D;AAC5D,MAAM,CAAC,MAAM,UAAU,GAAG,GAAG,CAAC;AAE9B;;;;GAIG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,GAAG,CAAC;AAEjC,4DAA4D;AAC5D,MAAM,CAAC,MAAM,cAAc,GAAG,GAAG,CAAC;AAElC,uFAAuF;AACvF,MAAM,CAAC,MAAM,SAAS,GAAG,GAAW,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;AACnD,MAAM,CAAC,MAAM,WAAW,GAAG,GAAW,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC"}
+{"version":3,"file":"glyphs.js","sourceRoot":"","sources":["../../src/cli/glyphs.ts"],"names":[],"mappings":"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"}

package/dist/cli/main.js

@@ -17,6 +17,7 @@ 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:
@@ -26,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
@@ -60,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,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC1D,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,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;