things-api 0.8.0 → 0.10.0

package/dist/cli/help.js

@@ -0,0 +1,355 @@
+import { ExitCode, PKG_VERSION } from "../index.js";
+/** The index groups, in display order. Every top-level command lands in one. */
+export const HELP_GROUPS = [
+    {
+        title: "Views — the app's built-in lists",
+        commands: ["inbox", "today", "upcoming", "anytime", "someday", "logbook", "trash"],
+    },
+    {
+        title: "Browse & search",
+        commands: ["show", "open", "search", "projects", "areas", "tags", "changes"],
+    },
+    {
+        title: "Write — create and change items",
+        commands: ["todo", "project", "area", "tag", "heading", "batch", "undo", "reorder"],
+    },
+    {
+        title: "Setup & diagnostics",
+        commands: ["config", "doctor", "capabilities", "setup", "mcp", "snapshot", "legend"],
+    },
+];
+/**
+ * The per-command index copy. Keyed by top-level command name. Kept ≤58 chars
+ * and behavior-only (surface-copy.md); the completeness test asserts this map's
+ * keys are exactly the registered top-level commands (minus `help`).
+ */
+export const INDEX = {
+    // Views
+    inbox: { args: "", desc: "captured, still-unsorted to-dos" },
+    today: { args: "", desc: "what's scheduled for today, plus This Evening" },
+    upcoming: { args: "", desc: "future-scheduled items, in date order" },
+    anytime: { args: "", desc: "all active items, grouped by area and project" },
+    someday: { args: "", desc: "incubating items kept without a date" },
+    logbook: { args: "", desc: "completed and canceled items, newest first" },
+    trash: { args: "", desc: "trashed items (empty it with `trash empty`)" },
+    // Browse & search
+    show: { args: "<ref>", desc: "show a to-do, project, or area by id or name" },
+    open: { args: "<ref>", desc: "reveal an item in the Things app on this Mac" },
+    search: { args: "<query>", desc: "find items by words in their title or notes" },
+    projects: { args: "[ref]", desc: "list projects, or show one" },
+    areas: { args: "[ref]", desc: "list areas, or show one" },
+    tags: { args: "", desc: "list the tag hierarchy" },
+    changes: { args: "", desc: "items created or changed since a moment (--since)" },
+    // Write
+    todo: { args: "<verb>", desc: "add, edit, schedule, complete, move to-dos" },
+    project: { args: "<verb>", desc: "add, edit, complete, move projects" },
+    area: { args: "<verb>", desc: "add, rename, retag, reorder, delete areas" },
+    tag: { args: "<verb>", desc: "add, rename, nest, delete tags" },
+    heading: { args: "<verb>", desc: "add, rename, archive headings in a project" },
+    batch: { args: "[file]", desc: "run many changes from a JSONL script" },
+    undo: { args: "", desc: "reverse recent changes made through this tool" },
+    reorder: { args: "<ids…>", desc: "reorder items within a list or container" },
+    // Setup & diagnostics
+    config: { args: "<verb>", desc: "show or set configuration keys" },
+    doctor: { args: "", desc: "check environment health and pending setup" },
+    capabilities: { args: "", desc: "what each write operation supports" },
+    setup: { args: "<verb>", desc: "one-time setup (install the Shortcuts)" },
+    mcp: { args: "", desc: "serve the Model Context Protocol server on stdio" },
+    snapshot: { args: "", desc: "full normalized dump of every record" },
+    legend: { args: "", desc: "the symbols and colors list output uses" },
+};
+/** Resolve the width to reflow help to: THINGS_WIDTH, else the TTY, else 100. */
+export function helpWidth() {
+    const raw = process.env["THINGS_WIDTH"];
+    if (raw !== undefined) {
+        const n = Number(raw);
+        if (Number.isInteger(n) && n > 0)
+            return n;
+    }
+    const cols = process.stdout.columns;
+    if (typeof cols === "number" && cols > 0)
+        return cols;
+    return 100;
+}
+/** Wrap `text` to `width`, continuation lines indented to `hang`. */
+function wrap(text, width, hang) {
+    const room = Math.max(24, width);
+    const out = [];
+    let cur = "";
+    for (const word of text.split(" ")) {
+        const candidate = cur === "" ? word : `${cur} ${word}`;
+        if (candidate.length <= room || cur === "")
+            cur = candidate;
+        else {
+            out.push(cur);
+            cur = " ".repeat(hang) + word;
+        }
+    }
+    if (cur !== "")
+        out.push(cur);
+    return out;
+}
+/**
+ * Lay out one index row: the (already padded) `head` column followed by the
+ * descriptor, wrapping the DESCRIPTOR only (so the head's alignment padding is
+ * never collapsed) with continuation lines hanging at the head column width.
+ */
+function layoutRow(head, desc, width, col) {
+    const first = head + desc;
+    if (first.length <= Math.max(24, width))
+        return [first];
+    const wrapped = wrap(desc, width - col, 0);
+    return wrapped.map((chunk, i) => (i === 0 ? head + chunk : " ".repeat(col) + chunk));
+}
+/**
+ * Render the top-level signpost index. Pure and width-parameterized so the
+ * contract test can assert its line budget at a fixed width. Returns the body
+ * WITHOUT a trailing newline.
+ */
+export function renderTopLevelHelp(program, width) {
+    void program;
+    const lines = [];
+    lines.push("things — a programmatic interface to Things 3 (Cultured Code).");
+    lines.push("Usage: things <command> [arguments] [options]");
+    lines.push("");
+    // One shared name column across every group, so descriptors align.
+    const headOf = (name) => {
+        const e = INDEX[name];
+        const args = e !== undefined && e.args !== "" ? ` ${e.args}` : "";
+        return `  ${name}${args}`;
+    };
+    let col = 0;
+    for (const g of HELP_GROUPS)
+        for (const name of g.commands) {
+            col = Math.max(col, headOf(name).length);
+        }
+    col += 2;
+    for (const g of HELP_GROUPS) {
+        lines.push(`${g.title}`);
+        for (const name of g.commands) {
+            const e = INDEX[name];
+            if (e === undefined)
+                continue;
+            const head = headOf(name).padEnd(col);
+            lines.push(...layoutRow(head, e.desc, width, col));
+        }
+        lines.push("");
+    }
+    lines.push("Global options (accepted by most commands)");
+    lines.push(`${"  --json".padEnd(col)}emit a versioned JSON envelope on stdout`);
+    lines.push(`${"  --db <path>".padEnd(col)}read from an explicit database path`);
+    lines.push(`${"  -h, --help".padEnd(col)}help for things, or for any <command>`);
+    lines.push(`${"  -V, --version".padEnd(col)}print the version (${PKG_VERSION})`);
+    lines.push("");
+    lines.push("Run `things <command> --help` for the behavior and options of any command.");
+    lines.push("Most commands take a ref (uuid, prefix, share link, or name) — see `things help ids`.");
+    lines.push("Guides: `things help <topic>` — agent, filters, ids, output, writes.");
+    lines.push("New to Things? Start with `things help agent`.");
+    return lines.join("\n");
+}
+// ── Topics ───────────────────────────────────────────────────────────────────
+/**
+ * The AGENT NOTES, verbatim from the former top-level epilog. Authored one
+ * bullet per entry; reflowed to the terminal by {@link renderAgentTopic}.
+ */
+const AGENT_NOTE_BULLETS = [
+    "Every command supports --json: a versioned envelope on stdout, logs on stderr.",
+    "Uuid parameters accept unique PREFIXES (>= 6 chars); list output shows 8+-char prefixes, --json always carries full uuids. Ambiguous prefixes 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 changes exit 4 with machine-readable remediation.",
+];
+function renderAgentTopic(width) {
+    const room = Math.max(40, width);
+    const out = ["AGENT NOTES — orientation for an agent driving this tool", ""];
+    for (const bullet of AGENT_NOTE_BULLETS) {
+        const wrapped = wrap(`- ${bullet}`, room, 2);
+        out.push(...wrapped);
+    }
+    return out.join("\n");
+}
+/**
+ * The static topic bodies. Authored to fit ~90 columns and stay ≤40 lines;
+ * behavior-only (surface-copy.md) — the banned-vocabulary test scans them too.
+ */
+const STATIC_TOPICS = {
+    filters: `FILTERS & BOUNDS — the optional flags a read view accepts
+
+Content scope (which items qualify):
+  --tag <ref>        items with this tag: direct, container-inherited, or on a
+                     descendant tag. Repeatable — several --tag AND together
+  --exact-tag        with --tag: the named tag only, no descendants
+  --untagged         only items with no tag at all (the app's "No Tag" filter)
+  --overdue          only open items past their deadline, due today excluded
+                     (today, inbox, anytime, someday, search; and the
+                     containers projects, project show, area show — by each
+                     entity's OWN deadline, no recursion; not the areas list)
+  --area <ref>       restrict to one area (logbook, search)
+  --project <ref>    restrict to one project (logbook, search)
+  --type <kind>      search only: todo | project
+
+--tag has two axes: CONTAINER inheritance (an item inherits its project/area/
+heading tags) and DESCENDANT expansion (a parent tag matches child-tag items).
+--exact-tag drops expansion. Inheritance is view-dependent: FLAT views (incl. the
+projects LIST) are inheritance-inclusive; project show / area show match a tag
+DIRECTLY on the row (a tag inherited from that one container is vacuous there).
+--untagged mirrors it: whole-relation when flat, direct-only in a container.
+
+Volume caps (how many rows):
+  --limit <n>        maximum rows before truncating (flat views; default 50)
+  --area-limit <n>   per-area-block cap on the grouped views (anytime, someday, areas)
+  --project-limit <n>  per-project-block cap (anytime, area show)
+  --all              lift this view's own caps and bounds — but never pull in a
+                     different class: logged and trashed items stay behind their
+                     own flags (--show-logged, --trashed)
+
+Range bounds (the time window — keyed to each view's own timeline):
+  --since <when>     logbook = logged date · upcoming = scheduled date
+  --until <when>     changes = modified date · inbox = created date
+  Accepts \`2w\`/\`3m\`/\`1y\` back from today, or \`2024\`, \`2024-03\`, \`2024-03-05\`.
+
+Defaults exist only for the bare invocation. Stating any explicit --limit or
+--since/--until drops the remaining defaults of both classes; explicit values
+always compose as an intersection. Content scopes and toggles never lift a
+default. (\`things changes\` requires --since, so that required bound lifts nothing.)`,
+    ids: `REFERENCES & IDS — how to point at an item
+
+A ref is: a things:/// URL, a UUID, a unique UUID prefix, or (areas/projects) a
+case-insensitive name. Anywhere a ref is accepted you may pass any of these:
+  - a full uuid
+  - a unique uuid PREFIX (>= 6 characters)
+  - a things:/// share link (the app's Share > Copy Link) — stripped to its id
+  - a unique NAME, for projects and areas (case-, space-, and dash-insensitive)
+Every item has a uuid; list views print a short prefix, and --json always carries
+the full uuid. Ambiguous prefixes and names fail loudly and list the candidates.
+
+Direct addressing — the word \`show\` may be omitted:
+  things <ref>          show the referenced item (when <ref> is not a command name)
+  things area <ref>     show that area      (the verb is implied inside a type)
+  things project <ref>  show that project
+Command names always win: \`things today\` is the view, never an item called
+"today". Reach a same-named item by its uuid, or by the typed form
+(\`things area show Anytime\`).
+
+A to-do takes a ref by uuid, prefix, or share link — never by title. A bare NAME
+resolves against areas and projects only; on a tie, the area wins. When a name
+does not resolve, the error offers close title matches you can copy.
+
+WRITE targets: project, area, and tag verbs accept a uuid OR a unique name (a
+duplicated project name is refused, listing the candidates to pick from by uuid);
+to-do and heading writes take a uuid or prefix only.`,
+    output: `OUTPUT — human tables vs. --json
+
+Human output (the default): compact aligned tables and detail cards, fit to the
+terminal width on a TTY. On a TTY a list view also prints a title header and, for
+a rewritten shorthand, a dim \`≡ <canonical command>\` echo. Neither the header nor
+the echo rides piped output or --json, so \`things inbox | grep\` stays clean.
+
+  --json    A versioned envelope on stdout: { apiVersion, ok, kind, data, meta }.
+            A failure becomes an error envelope (still exit-coded). Logs, warnings,
+            and errors go to stderr, so stdout stays one clean JSON line. Full uuids
+            always appear here. --json is byte-stable — it is never width-fitted.
+            Optional entity fields are omitted when empty: a to-do with no deadline
+            has no deadline key, one with no tags has no tags key, and so on. Read a
+            missing key as unset/empty/default — absent and empty are the same. The
+            identity keys (uuid, type, and the title) are always present.
+
+Width: human tables fit the terminal on a TTY. Set THINGS_WIDTH=<cols> to force a
+column width, or THINGS_WIDTH=0 to disable fitting. Piped output is never fitted,
+so it stays stable for grep and diffs.
+
+Symbols and colors used in the tables: \`things legend\` (or \`things legend --json\`).`,
+    writes: `WRITES — the gating model, undo, and setup
+
+Every write behaves the same way:
+  - Success means the change happened; if it did not take effect the command exits
+    non-zero with a machine-readable reason.
+  - --dry-run previews the planned change and its expected effect; nothing runs.
+  - No command prompts interactively. A change that cascades, is permanent, or
+    disturbs the app requires an explicit flag, named for its consequence:
+      --acknowledge-*           confirm a cascade or a reset (named per command)
+      --children <policy>       decide what happens to a container's open to-dos
+      --dangerously-permanent   accept a permanent, unrecoverable delete
+      --allow-disruptive        permit a change that briefly steals window focus
+      --allow-very-disruptive   permit a change that visibly drives the Things app
+      --dangerously-drive-gui   for the few operations the app offers nowhere else
+
+Undo — \`things undo\`:
+  Reverse recent changes made through this tool, newest first; each undo applies
+  the inverse change. --dry-run shows the plan. Irreversible changes (permanent
+  deletes, unknown prior state) are reported, never guessed. Changes made directly
+  in the Things app cannot be undone here.
+
+Configuration that affects writes — \`things config set <key> <value>\`:
+  actor               author name recorded on each change
+  maxDisruption       ceiling for how disruptive a change may be
+  ui-enabled          allow the GUI-driven operations
+  allow-experimental  enable experimental strategies (e.g. native reorder)
+
+Writes are NAMESPACED: a bare \`things <verb> …\` (update, add, delete, complete,
+cancel, move, …) is not a command — it points you at the typed form
+(\`things todo|project|area|tag|heading <verb> …\`), never running the change.
+
+Discover every operation and the flags it needs: \`things capabilities\`.
+A few operations need the bundled Shortcuts: \`things setup shortcuts\`.`,
+};
+/** The valid topic names, in the order the "unknown topic" hint lists them. */
+export const TOPIC_NAMES = ["agent", "filters", "ids", "output", "writes"];
+/** Render one topic to `width`, or null when `name` is not a topic. */
+export function renderTopic(name, width) {
+    if (name === "agent")
+        return renderAgentTopic(width);
+    return STATIC_TOPICS[name] ?? null;
+}
+/**
+ * Install the custom top-level help and the `help [topic]` command. Replaces
+ * the root program's `helpInformation` with the signpost index (so both
+ * `things --help` and the help command render it) and disables commander's
+ * built-in help command in favor of one that also serves topics.
+ */
+export function registerHelp(program) {
+    // Root-only override: subcommands keep commander's default per-command help.
+    program.helpInformation = () => `${renderTopLevelHelp(program, helpWidth())}\n`;
+    // Replace commander's built-in `help [command]` with our topic-aware one.
+    program.helpCommand(false);
+    program
+        .command("help [command...]")
+        .description("show this index, a guide (`things help <topic>`), or a command's help")
+        .action((tokens = []) => {
+        const width = helpWidth();
+        if (tokens.length === 0) {
+            program.outputHelp();
+            return;
+        }
+        const first = (tokens[0] ?? "").toLowerCase();
+        // A single topic token renders the guide.
+        if (tokens.length === 1) {
+            const topic = renderTopic(first, width);
+            if (topic !== null) {
+                process.stdout.write(`${topic}\n`);
+                return;
+            }
+        }
+        // Otherwise resolve a command path and defer to its own --help.
+        let cmd = program;
+        for (const token of tokens) {
+            cmd = cmd.commands.find((c) => c.name() === token || c.aliases().includes(token));
+            if (cmd === undefined)
+                break;
+        }
+        if (cmd !== undefined && cmd !== program) {
+            cmd.outputHelp();
+            return;
+        }
+        process.stderr.write(`error: no help topic or command "${tokens.join(" ")}" — ` +
+            `topics: ${TOPIC_NAMES.join(", ")}; ` +
+            "commands: `things --help`\n");
+        process.exitCode = ExitCode.Usage;
+    });
+}
+//# sourceMappingURL=help.js.map

package/dist/cli/help.js.map

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

package/dist/cli/main.js

@@ -7,6 +7,8 @@
 import { realpathSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { Command } from "commander";
+import { registerHelp } from "./help.js";
+import { installExcessArgsHelp } from "./excess-args.js";
 import { registerDoctor } from "./commands/doctor.js";
 import { registerMcp } from "./commands/mcp.js";
 import { registerAreaCommands } from "./commands/area.js";
@@ -17,32 +19,20 @@ 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 { ExitCode, PKG_VERSION } from "../contracts.js";
-const AGENT_NOTES = `
-AGENT NOTES:
-  - Every command supports --json: versioned envelope on stdout, logs on stderr.
-  - Uuid parameters accept unique PREFIXES (>= 6 chars); list output shows
-    8+-char prefixes, --json always carries full uuids. Ambiguous prefixes
-    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.
-  - 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
-  - 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
-    changes exit 4 with machine-readable remediation.
-`;
+import { resolveInvocation } from "./resolve-invocation.js";
+import { runVerbHint } from "./verb-hint.js";
+import { resolveWidth, setFitWidth } from "./width.js";
+import { ExitCode, PKG_VERSION } from "../index.js";
 export function buildProgram() {
     const program = new Command();
     program
         .name("things")
         .description("Programmatic interface to Things 3 (Cultured Code)")
         .version(PKG_VERSION)
-        .addHelpText("after", AGENT_NOTES);
+        // Unknown-command typos are answered with "did you mean …" (default on;
+        // stated for the record — most top-level typos route through the bare-noun
+        // did-you-mean instead, this covers the subcommand groups).
+        .showSuggestionAfterError(true);
     registerDoctor(program);
     registerReadCommands(program);
     registerShowCommands(program);
@@ -53,14 +43,39 @@ export function buildProgram() {
     registerSetup(program);
     registerSnapshot(program);
     registerMcp(program);
+    // The signpost index + `help [topic]` replace the multi-scroll epilog; the
+    // improved excess-argument message names the command and its usage line.
+    registerHelp(program);
+    installExcessArgsHelp(program);
     return program;
 }
 export function runCli() {
+    // Resolve the width-aware row fit ONCE at startup (docs/design/width-aware-
+    // tty.md): THINGS_WIDTH override, else stdout.columns on a TTY, else null (no
+    // fitting — pipes/grep/--json byte-stable). Threaded to the renderers via the
+    // module-level fit width in ./width.ts, so every human list path inherits it
+    // and MCP/--json never touch it.
+    setFitWidth(resolveWidth({
+        env: process.env,
+        columns: process.stdout.columns,
+        isTTY: process.stdout.isTTY === true,
+    }));
     const program = buildProgram();
     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 resolved = resolveInvocation(program, process.argv.slice(2));
+    // A bare top-level mutation verb (`things update <ref>`) never reaches
+    // commander: it is answered with a namespaced-write suggestion instead of the
+    // show-sugar's confusing usage error (docs/design/cli-grammar.md).
+    if (resolved.form === "verb-hint") {
+        runVerbHint(program, resolved.argv);
+        return;
+    }
+    program.parse(resolved.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,39 @@
+/**
+ * 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 };
+/**
+ * Double a relative period for a "wider window" suggestion: `1m`→`2m`,
+ * `2w`→`4w`, `1y`→`2y`. A non-relative input (an absolute calendar period
+ * like `2026-09`) comes back unchanged — there is nothing sensible to double.
+ * Deliberately dumb: it only scales the count of a `\d+[dwmy]` period.
+ */
+export declare function doublePeriod(period: string): string;
+/**
+ * `--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,141 @@
+/**
+ * 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;
+}
+/**
+ * Double a relative period for a "wider window" suggestion: `1m`→`2m`,
+ * `2w`→`4w`, `1y`→`2y`. A non-relative input (an absolute calendar period
+ * like `2026-09`) comes back unchanged — there is nothing sensible to double.
+ * Deliberately dumb: it only scales the count of a `\d+[dwmy]` period.
+ */
+export function doublePeriod(period) {
+    const m = RELATIVE_PERIOD.exec(period.trim());
+    if (m === null)
+        return period;
+    return `${Number(m[1]) * 2}${(m[2] ?? "").toLowerCase()}`;
+}
+/**
+ * `--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