things-api 0.10.0 → 0.11.0

package/dist/cli/help.js

@@ -1,4 +1,5 @@
-import { ExitCode, PKG_VERSION } from "../index.js";
+import { CLI_VERSION } from "./version.js";
+import { ExitCode } from "../index.js";
 /** The index groups, in display order. Every top-level command lands in one. */
 export const HELP_GROUPS = [
     {
@@ -15,7 +16,16 @@ export const HELP_GROUPS = [
     },
     {
         title: "Setup & diagnostics",
-        commands: ["config", "doctor", "capabilities", "setup", "mcp", "snapshot", "legend"],
+        commands: [
+            "config",
+            "doctor",
+            "capabilities",
+            "setup",
+            "install-skill",
+            "mcp",
+            "snapshot",
+            "legend",
+        ],
     },
 ];
 /**
@@ -54,6 +64,7 @@ export const INDEX = {
     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)" },
+    "install-skill": { args: "", desc: "install the agent skill for coding agents" },
     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" },
@@ -136,15 +147,16 @@ export function renderTopLevelHelp(program, width) {
         lines.push("");
     }
     lines.push("Global options (accepted by most commands)");
-    lines.push(`${"  --json".padEnd(col)}emit a versioned JSON envelope on stdout`);
+    lines.push(`${"  --json".padEnd(col)}emit {apiVersion, ok, kind, data, meta}; payload=.data; entity id=.uuid (not .id)`);
     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(`${"  -V, --version".padEnd(col)}print the version (${CLI_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("Guides: `things help <topic>` — agent, filters, ids, output, repeating, writes.");
     lines.push("New to Things? Start with `things help agent`.");
+    lines.push("Agent skill available: run `things install-skill`.");
     return lines.join("\n");
 }
 // ── Topics ───────────────────────────────────────────────────────────────────
@@ -163,6 +175,7 @@ const AGENT_NOTE_BULLETS = [
     "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.",
+    "An agent skill is available: `things install-skill`. On human output the tool reads your installed skill under ~/.agents and ~/.claude and notes (once, on stderr) when it is well behind this binary; silence it with THINGS_API_NO_SKILL_CHECK=1.",
 ];
 function renderAgentTopic(width) {
     const room = Math.max(40, width);
@@ -297,9 +310,46 @@ cancel, move, …) is not a command — it points you at the typed form
 
 Discover every operation and the flags it needs: \`things capabilities\`.
 A few operations need the bundled Shortcuts: \`things setup shortcuts\`.`,
+    repeating: `REPEATING — rules for recurring to-dos and projects
+
+Verbs: \`things todo|project make-repeating <ref>\` (turn an existing item into a
+repeater), \`things project create-repeating "<title>"\`, \`… reschedule-repeat <ref>\`
+(change a rule in place). Every rule takes \`--frequency <daily|weekly|monthly|yearly>\`
+and a required \`--interval <n>\` (\`--interval 1\` = every unit). Repeating operations
+require \`--allow-disruptive\`, including \`--dry-run\` previews.
+
+Two modes:
+  fixed (default)      occurrences land on calendar dates. NOTE: this REPLACES the
+                       item — the response returns the new uuids (see below).
+  --after-completion   next occurrence lands N units after you complete the current
+                       one. The item keeps its uuid.
+
+Shaping the rule (compose with the frequency):
+  --weekdays mon,thu,fri      weekly: MULTIPLE days in ONE rule — never make two
+                              repeaters for "every Thursday and Friday"
+  --on-day <1-31|last>        monthly/yearly: a date anchor
+  --on-weekday <day> --on-ordinal <1-5|last>   nth-weekday anchor; yearly adds
+  --yearly-month <1-12>       e.g. last Sunday of December, every year:
+                              --frequency yearly --yearly-month 12
+                              --on-weekday sunday --on-ordinal last
+  --ends-after <n> | --ends-on YYYY-MM-DD      stop bounds
+  --reminder HH:mm · --deadline · --start-days-earlier <n>
+
+make-repeating returns a \`repeating\` block: \`instanceUuid\` is the visible current
+occurrence (use it to reach the item), \`templateUuid\` the recurring rule (use it as
+the <ref> for \`reschedule-repeat\`), and \`replacedUuid\` the original when it was
+replaced. Typical chain: \`things todo add "<title>" --json\`, then
+\`things todo make-repeating <returned-uuid> --frequency … --allow-disruptive\`.`,
 };
 /** The valid topic names, in the order the "unknown topic" hint lists them. */
-export const TOPIC_NAMES = ["agent", "filters", "ids", "output", "writes"];
+export const TOPIC_NAMES = [
+    "agent",
+    "filters",
+    "ids",
+    "output",
+    "repeating",
+    "writes",
+];
 /** Render one topic to `width`, or null when `name` is not a topic. */
 export function renderTopic(name, width) {
     if (name === "agent")

package/dist/cli/help.js.map

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

package/dist/cli/main.js

@@ -15,20 +15,25 @@ 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 { registerInstallSkill } from "./commands/install-skill.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 { runVerbHint } from "./verb-hint.js";
+import { detectMoveHint, runMoveHint } from "./move-hint.js";
+import { setRenderClock } from "./clock.js";
+import { maybeEmitSkillDriftNote } from "./skill-check.js";
 import { resolveWidth, setFitWidth } from "./width.js";
-import { ExitCode, PKG_VERSION } from "../index.js";
+import { CLI_VERSION } from "./version.js";
+import { ExitCode, resolveClock } from "../index.js";
 export function buildProgram() {
     const program = new Command();
     program
         .name("things")
         .description("Programmatic interface to Things 3 (Cultured Code)")
-        .version(PKG_VERSION)
+        .version(CLI_VERSION)
         // 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).
@@ -41,6 +46,7 @@ export function buildProgram() {
     registerTodoCommands(program);
     registerWriteCommands(program);
     registerSetup(program);
+    registerInstallSkill(program);
     registerSnapshot(program);
     registerMcp(program);
     // The signpost index + `help [topic]` replace the multi-scroll epilog; the
@@ -60,6 +66,22 @@ export function runCli() {
         columns: process.stdout.columns,
         isTTY: process.stdout.isTTY === true,
     }));
+    // Resolve the consumer clock ONCE (THINGS_TZ / THINGS_NOW) so the human
+    // renderers and period parsers evaluate dates in the same zone the library
+    // does. A malformed value is NOT fatal here: the command's own client-open
+    // re-resolves it and surfaces the usage error with --json awareness — so
+    // leave the render clock on the host default if resolution throws.
+    try {
+        const clock = resolveClock({ env: process.env });
+        setRenderClock({ now: clock.now, zone: clock.zone });
+    }
+    catch {
+        // handled by the command path (openThings → runRead/runWrite usage error)
+    }
+    // Passive skill-drift notice: one stderr line when the installed agent skill
+    // is well behind this binary's bundled copy (human paths only, never --json /
+    // mcp; kill switch THINGS_API_NO_SKILL_CHECK=1). Silent on any error/absence.
+    maybeEmitSkillDriftNote({ argv: process.argv.slice(2), env: process.env });
     const program = buildProgram();
     program.exitOverride((err) => {
         process.exit(err.exitCode === 0 ? ExitCode.Ok : ExitCode.Usage);
@@ -75,6 +97,15 @@ export function runCli() {
         runVerbHint(program, resolved.argv);
         return;
     }
+    // A namespaced `move` carrying scheduling intent (`todo move X --when today`,
+    // `todo move X someday`) is answered with the command that actually schedules
+    // an item, instead of a bare unknown-option / excess-argument usage error
+    // (docs/design/cli-grammar.md). Never fires on a valid container move.
+    const moveHint = detectMoveHint(program, resolved.argv);
+    if (moveHint !== null) {
+        runMoveHint(moveHint);
+        return;
+    }
     program.parse(resolved.argv, { from: "user" });
 }
 // Direct-run detection must survive the npm .bin symlink (argv[1] ends with

package/dist/cli/main.js.map

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

package/dist/cli/move-hint.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The scheduling-intent hint for a namespaced `move` (docs/design/cli-grammar.md).
+ * `things todo move <ref>` and `things project move <ref>` take CONTAINER
+ * destinations only (--area/--project/--heading; todo also --inbox/--detach).
+ * An agent carrying scheduling intent ("move X to Someday") reaches for
+ * spellings `move` does not accept — `--to someday`, `--when today`,
+ * `--someday`, or a bare `someday` positional — and would otherwise land on a
+ * bare unknown-option / excess-argument usage error that never names the
+ * command which actually schedules an item.
+ *
+ * This runs BEFORE commander parses (like the bare-verb hint) and, when it
+ * recognizes scheduling vocabulary on a `move` invocation, answers with the
+ * concrete command that works:
+ *
+ *   - a scheduling term (`someday`/`today`/`evening`/`anytime`/a date), as a
+ *     flag value or a stray positional → `things <group> update <ref> --when <value>`.
+ *   - a bare `inbox` positional on `todo move` → `things todo move <ref> --inbox`
+ *     (the real Inbox-return; `--when inbox` is not a thing).
+ *
+ * It NEVER fires on a valid move: every trapped spelling is already a usage
+ * error, so the accepted grammar is unchanged. Exit class stays Usage (2);
+ * under `--json` the suggestion rides `error.details.suggestions`.
+ */
+import type { Command } from "commander";
+/** The corrected command this hint points at. */
+export interface MoveHint {
+    group: "todo" | "project";
+    /** Whether the caller asked for a --json envelope. */
+    json: boolean;
+    /** Inbox return vs. a schedule change — selects the wording. */
+    intent: "schedule" | "inbox";
+    /** The full, runnable suggestion (already shell-quoted). */
+    suggestion: string;
+}
+/**
+ * Classify a `<group> move` invocation for scheduling intent. Returns the
+ * corrected-command hint when a trapped spelling is present, else null (the
+ * invocation falls through to commander unchanged).
+ */
+export declare function detectMoveHint(program: Command, argv: string[]): MoveHint | null;
+/**
+ * Emit the scheduling-intent hint and set the Usage exit code. Never opens the
+ * write pipeline — it only rewrites the failing invocation into a working one.
+ */
+export declare function runMoveHint(hint: MoveHint): void;

package/dist/cli/move-hint.js

@@ -0,0 +1,196 @@
+import { errorEnvelope, ExitCode } from "../index.js";
+import { indexPastLeadingFlags } from "./resolve-invocation.js";
+import { shellQuote } from "./shell-quote.js";
+/** The write groups whose `move` subcommand this hint guards. */
+const MOVE_GROUPS = new Set(["todo", "project"]);
+/**
+ * Flag spellings that signal scheduling intent on a `move` — none is a real
+ * `move` option, so their presence is always a usage error we can improve.
+ * `--inbox` is deliberately absent: it is a genuine `todo move` destination.
+ */
+const SCHEDULING_FLAGS = new Set([
+    "--to",
+    "--when",
+    "--someday",
+    "--today",
+    "--evening",
+    "--anytime",
+    "--date",
+    "--schedule",
+]);
+/** Scheduling flags that carry their term as the NEXT token (or `--flag=term`). */
+const VALUE_SCHEDULING_FLAGS = new Set(["--to", "--when", "--date", "--schedule"]);
+/** Boolean-style scheduling flags whose name IS the `--when` term. */
+const FLAG_TERM = {
+    "--someday": "someday",
+    "--today": "today",
+    "--evening": "evening",
+    "--anytime": "anytime",
+};
+/** Recognized `--when` terms (a date is matched separately). */
+const WHEN_TERMS = new Set(["today", "evening", "anytime", "someday"]);
+/** Positional destinations that read as scheduling intent, not a container. */
+const SCHEDULING_POSITIONALS = new Set(["someday", "today", "evening", "anytime", "inbox"]);
+/** A bare `YYYY-MM-DD` — a valid `--when` value, never a container name. */
+function isDate(token) {
+    return /^\d{4}-\d{2}-\d{2}$/.test(token);
+}
+/** Long/short flag names of `<group> move` that consume the following token. */
+function valueFlagsFor(program, group) {
+    const names = new Set();
+    const groupCmd = program.commands.find((c) => c.name() === group);
+    const moveCmd = groupCmd?.commands.find((c) => c.name() === "move");
+    if (moveCmd === undefined)
+        return names;
+    for (const opt of moveCmd.options) {
+        // Commander marks value-taking options `<x>` (required) or `[x]` (optional).
+        if (opt.required === true || opt.optional === true) {
+            if (opt.long !== undefined)
+                names.add(opt.long);
+            if (opt.short !== undefined)
+                names.add(opt.short);
+        }
+    }
+    return names;
+}
+/** Map a raw scheduling term to a valid `--when` value (park by default). */
+function whenValue(term) {
+    if (term !== null && (WHEN_TERMS.has(term.toLowerCase()) || isDate(term))) {
+        return term.toLowerCase() === term ? term : term.toLowerCase();
+    }
+    return "someday";
+}
+/**
+ * Walk the tokens after `<group> move`, skipping global/known value flags so
+ * their values are never misread as a positional destination (`--heading
+ * someday` moves under a heading literally named "someday" — not a trap).
+ */
+function scan(tokens, valueFlags) {
+    const positionals = [];
+    let flagTerm = null;
+    let flagIntent = false;
+    for (let i = 0; i < tokens.length; i++) {
+        const tok = tokens[i] ?? "";
+        if (tok.startsWith("-")) {
+            const eq = tok.indexOf("=");
+            const name = eq >= 0 ? tok.slice(0, eq) : tok;
+            const inline = eq >= 0 ? tok.slice(eq + 1) : undefined;
+            if (SCHEDULING_FLAGS.has(name)) {
+                if (!flagIntent) {
+                    if (VALUE_SCHEDULING_FLAGS.has(name)) {
+                        flagTerm = inline ?? tokens[i + 1] ?? null;
+                    }
+                    else {
+                        flagTerm = FLAG_TERM[name] ?? null;
+                    }
+                    flagIntent = true;
+                }
+                if (VALUE_SCHEDULING_FLAGS.has(name) && inline === undefined)
+                    i++; // consume its term
+            }
+            else if (valueFlags.has(name) && inline === undefined) {
+                i++; // a known value flag — skip its value, it is not a positional
+            }
+            // boolean / unknown flags carry no positional to protect
+        }
+        else {
+            positionals.push(tok);
+        }
+    }
+    return {
+        ref: positionals[0] ?? null,
+        dest: positionals[1] ?? null,
+        flagTerm,
+        flagIntent,
+    };
+}
+/**
+ * Classify a `<group> move` invocation for scheduling intent. Returns the
+ * corrected-command hint when a trapped spelling is present, else null (the
+ * invocation falls through to commander unchanged).
+ */
+export function detectMoveHint(program, argv) {
+    const at = indexPastLeadingFlags(argv);
+    if (at === null)
+        return null;
+    const group = argv[at];
+    if (group === undefined || !MOVE_GROUPS.has(group))
+        return null;
+    if (argv[at + 1] !== "move")
+        return null;
+    const g = group;
+    const s = scan(argv.slice(at + 2), valueFlagsFor(program, group));
+    const json = argv.includes("--json");
+    const refEcho = s.ref !== null ? shellQuote(s.ref) : "<ref>";
+    // Precedence: an explicit scheduling FLAG wins over a positional read.
+    if (s.flagIntent) {
+        return {
+            group: g,
+            json,
+            intent: "schedule",
+            suggestion: `things ${g} update ${refEcho} --when ${whenValue(s.flagTerm)}`,
+        };
+    }
+    // A stray positional destination that reads as scheduling vocabulary.
+    const dest = s.dest;
+    if (dest === null)
+        return null;
+    const lower = dest.toLowerCase();
+    if (lower === "inbox") {
+        // Only to-dos have an Inbox, and its return is a flag (`--when inbox` is not
+        // a thing). A project has no Inbox — leave that to commander.
+        if (g !== "todo")
+            return null;
+        return {
+            group: g,
+            json,
+            intent: "inbox",
+            suggestion: `things todo move ${refEcho} --inbox`,
+        };
+    }
+    if (SCHEDULING_POSITIONALS.has(lower) || isDate(dest)) {
+        return {
+            group: g,
+            json,
+            intent: "schedule",
+            suggestion: `things ${g} update ${refEcho} --when ${whenValue(dest)}`,
+        };
+    }
+    return null;
+}
+/** The lead line naming what `move` does — scheduling vs. Inbox framing. */
+function leadLine(hint) {
+    return hint.intent === "inbox"
+        ? `error: \`things ${hint.group} move\` takes a container flag, not a positional destination.`
+        : `error: \`things ${hint.group} move\` changes an item's container, not its schedule.`;
+}
+/** The action line inviting the corrected command. */
+function actionLine(hint) {
+    return hint.intent === "inbox"
+        ? `to send an item back to the Inbox use: ${hint.suggestion}`
+        : `to schedule or park an item use: ${hint.suggestion}`;
+}
+/** Human render: the framing line, the corrected command, the container reminder. */
+function renderHuman(hint) {
+    return [
+        leadLine(hint),
+        actionLine(hint),
+        `move changes containers (--area/--project/--heading).`,
+    ].join("\n");
+}
+/**
+ * Emit the scheduling-intent hint and set the Usage exit code. Never opens the
+ * write pipeline — it only rewrites the failing invocation into a working one.
+ */
+export function runMoveHint(hint) {
+    if (hint.json) {
+        const meta = { dbVersion: null, fingerprint: "unknown", elapsedMs: 0 };
+        const message = `${leadLine(hint).replace(/^error: /, "")} ${actionLine(hint)}`;
+        process.stdout.write(`${JSON.stringify(errorEnvelope({ code: "usage", message, details: { suggestions: [hint.suggestion] } }, meta))}\n`);
+    }
+    else {
+        process.stderr.write(`${renderHuman(hint)}\n`);
+    }
+    process.exitCode = ExitCode.Usage;
+}
+//# sourceMappingURL=move-hint.js.map

package/dist/cli/move-hint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"move-hint.js","sourceRoot":"","sources":["../../src/cli/move-hint.ts"],"names":[],"mappings":"AAyBA,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAqB,MAAM,aAAa,CAAC;AACzE,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C,iEAAiE;AACjE,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC;AAEjD;;;;GAIG;AACH,MAAM,gBAAgB,GAAG,IAAI,GAAG,CAAC;IAC/B,MAAM;IACN,QAAQ;IACR,WAAW;IACX,SAAS;IACT,WAAW;IACX,WAAW;IACX,QAAQ;IACR,YAAY;CACb,CAAC,CAAC;AAEH,mFAAmF;AACnF,MAAM,sBAAsB,GAAG,IAAI,GAAG,CAAC,CAAC,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,YAAY,CAAC,CAAC,CAAC;AAEnF,sEAAsE;AACtE,MAAM,SAAS,GAA2B;IACxC,WAAW,EAAE,SAAS;IACtB,SAAS,EAAE,OAAO;IAClB,WAAW,EAAE,SAAS;IACtB,WAAW,EAAE,SAAS;CACvB,CAAC;AAEF,gEAAgE;AAChE,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,CAAC,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC;AAEvE,+EAA+E;AAC/E,MAAM,sBAAsB,GAAG,IAAI,GAAG,CAAC,CAAC,SAAS,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC;AAE5F,4EAA4E;AAC5E,SAAS,MAAM,CAAC,KAAa;IAC3B,OAAO,qBAAqB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAC3C,CAAC;AAaD,gFAAgF;AAChF,SAAS,aAAa,CAAC,OAAgB,EAAE,KAAa;IACpD,MAAM,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;IAChC,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,KAAK,KAAK,CAAC,CAAC;IAClE,MAAM,OAAO,GAAG,QAAQ,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,KAAK,MAAM,CAAC,CAAC;IACpE,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IACxC,KAAK,MAAM,GAAG,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;QAClC,6EAA6E;QAC7E,IAAI,GAAG,CAAC,QAAQ,KAAK,IAAI,IAAI,GAAG,CAAC,QAAQ,KAAK,IAAI,EAAE,CAAC;YACnD,IAAI,GAAG,CAAC,IAAI,KAAK,SAAS;gBAAE,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YAChD,IAAI,GAAG,CAAC,KAAK,KAAK,SAAS;gBAAE,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACpD,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,6EAA6E;AAC7E,SAAS,SAAS,CAAC,IAAmB;IACpC,IAAI,IAAI,KAAK,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;QAC1E,OAAO,IAAI,CAAC,WAAW,EAAE,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;IACjE,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAYD;;;;GAIG;AACH,SAAS,IAAI,CAAC,MAAgB,EAAE,UAAuB;IACrD,MAAM,WAAW,GAAa,EAAE,CAAC;IACjC,IAAI,QAAQ,GAAkB,IAAI,CAAC;IACnC,IAAI,UAAU,GAAG,KAAK,CAAC;IACvB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACvC,MAAM,GAAG,GAAG,MAAM,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QAC5B,IAAI,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YACxB,MAAM,EAAE,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;YAC5B,MAAM,IAAI,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;YAC9C,MAAM,MAAM,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;YACvD,IAAI,gBAAgB,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC/B,IAAI,CAAC,UAAU,EAAE,CAAC;oBAChB,IAAI,sBAAsB,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;wBACrC,QAAQ,GAAG,MAAM,IAAI,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,IAAI,CAAC;oBAC7C,CAAC;yBAAM,CAAC;wBACN,QAAQ,GAAG,SAAS,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC;oBACrC,CAAC;oBACD,UAAU,GAAG,IAAI,CAAC;gBACpB,CAAC;gBACD,IAAI,sBAAsB,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,MAAM,KAAK,SAAS;oBAAE,CAAC,EAAE,CAAC,CAAC,mBAAmB;YACxF,CAAC;iBAAM,IAAI,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;gBACxD,CAAC,EAAE,CAAC,CAAC,8DAA8D;YACrE,CAAC;YACD,yDAAyD;QAC3D,CAAC;aAAM,CAAC;YACN,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACxB,CAAC;IACH,CAAC;IACD,OAAO;QACL,GAAG,EAAE,WAAW,CAAC,CAAC,CAAC,IAAI,IAAI;QAC3B,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,IAAI,IAAI;QAC5B,QAAQ;QACR,UAAU;KACX,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,OAAgB,EAAE,IAAc;IAC7D,MAAM,EAAE,GAAG,qBAAqB,CAAC,IAAI,CAAC,CAAC;IACvC,IAAI,EAAE,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC7B,MAAM,KAAK,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC;IACvB,IAAI,KAAK,KAAK,SAAS,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAChE,IAAI,IAAI,CAAC,EAAE,GAAG,CAAC,CAAC,KAAK,MAAM;QAAE,OAAO,IAAI,CAAC;IACzC,MAAM,CAAC,GAAG,KAA2B,CAAC;IAEtC,MAAM,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,aAAa,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC;IAClE,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IACrC,MAAM,OAAO,GAAG,CAAC,CAAC,GAAG,KAAK,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;IAE7D,uEAAuE;IACvE,IAAI,CAAC,CAAC,UAAU,EAAE,CAAC;QACjB,OAAO;YACL,KAAK,EAAE,CAAC;YACR,IAAI;YACJ,MAAM,EAAE,UAAU;YAClB,UAAU,EAAE,UAAU,CAAC,WAAW,OAAO,WAAW,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE;SAC5E,CAAC;IACJ,CAAC;IAED,sEAAsE;IACtE,MAAM,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC;IACpB,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC/B,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;IACjC,IAAI,KAAK,KAAK,OAAO,EAAE,CAAC;QACtB,6EAA6E;QAC7E,8DAA8D;QAC9D,IAAI,CAAC,KAAK,MAAM;YAAE,OAAO,IAAI,CAAC;QAC9B,OAAO;YACL,KAAK,EAAE,CAAC;YACR,IAAI;YACJ,MAAM,EAAE,OAAO;YACf,UAAU,EAAE,oBAAoB,OAAO,UAAU;SAClD,CAAC;IACJ,CAAC;IACD,IAAI,sBAAsB,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;QACtD,OAAO;YACL,KAAK,EAAE,CAAC;YACR,IAAI;YACJ,MAAM,EAAE,UAAU;YAClB,UAAU,EAAE,UAAU,CAAC,WAAW,OAAO,WAAW,SAAS,CAAC,IAAI,CAAC,EAAE;SACtE,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,4EAA4E;AAC5E,SAAS,QAAQ,CAAC,IAAc;IAC9B,OAAO,IAAI,CAAC,MAAM,KAAK,OAAO;QAC5B,CAAC,CAAC,mBAAmB,IAAI,CAAC,KAAK,+DAA+D;QAC9F,CAAC,CAAC,mBAAmB,IAAI,CAAC,KAAK,wDAAwD,CAAC;AAC5F,CAAC;AAED,sDAAsD;AACtD,SAAS,UAAU,CAAC,IAAc;IAChC,OAAO,IAAI,CAAC,MAAM,KAAK,OAAO;QAC5B,CAAC,CAAC,0CAA0C,IAAI,CAAC,UAAU,EAAE;QAC7D,CAAC,CAAC,oCAAoC,IAAI,CAAC,UAAU,EAAE,CAAC;AAC5D,CAAC;AAED,qFAAqF;AACrF,SAAS,WAAW,CAAC,IAAc;IACjC,OAAO;QACL,QAAQ,CAAC,IAAI,CAAC;QACd,UAAU,CAAC,IAAI,CAAC;QAChB,uDAAuD;KACxD,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,IAAc;IACxC,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;QACd,MAAM,IAAI,GAAiB,EAAE,SAAS,EAAE,IAAI,EAAE,WAAW,EAAE,SAAS,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC;QACrF,MAAM,OAAO,GAAG,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,IAAI,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QAChF,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,GAAG,IAAI,CAAC,SAAS,CACf,aAAa,CACX,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,EAAE,WAAW,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,EAAE,EACvE,IAAI,CACL,CACF,IAAI,CACN,CAAC;IACJ,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACjD,CAAC;IACD,OAAO,CAAC,QAAQ,GAAG,QAAQ,CAAC,KAAK,CAAC;AACpC,CAAC"}

package/dist/cli/period.d.ts

@@ -1,9 +1,3 @@
-/**
- * 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 };
 /**
@@ -19,14 +13,14 @@ export declare function doublePeriod(period: string): string;
  * 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;
+export declare function parsePeriodEnd(s: string, now?: Date, zone?: string): 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;
+export declare function parsePeriodStart(s: string, now?: Date, zone?: string): 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

package/dist/cli/period.js

@@ -1,9 +1,12 @@
 /**
  * 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.
+ * the Upcoming date-bucket labeller. The only library dependency is the pair of
+ * zone-aware date helpers (through the single entry point) so a `--since 2w` is
+ * counted in the CONSUMER'S calendar, not the host's — byte-identical to the
+ * host math when no zone is in effect.
  */
+import { dayBoundInstant, localToday } from "../index.js";
 const FULL_MONTHS = [
     "January",
     "February",
@@ -40,19 +43,45 @@ export { FULL_MONTHS };
  * bound (each command's natural direction; the flag name carries it).
  */
 const RELATIVE_PERIOD = /^(\d+)([dwmy])$/i;
-function relativePeriodDate(m, now, sign) {
+/** Format a UTC-anchored Date's date fields as `YYYY-MM-DD`. */
+function isoFromUtc(dt) {
+    return `${String(dt.getUTCFullYear()).padStart(4, "0")}-${String(dt.getUTCMonth() + 1).padStart(2, "0")}-${String(dt.getUTCDate()).padStart(2, "0")}`;
+}
+/**
+ * The target CALENDAR date for a relative period, counted from a base ISO date
+ * (the consumer's today) — days/weeks add days, months/years use the JS Date
+ * overflow the host arithmetic always used (Jan 31 + 1m → Mar 3). Pure calendar
+ * math on the date fields (UTC-anchored so the host zone never intrudes), so it
+ * is zone-agnostic once the base date is chosen.
+ */
+function relativeTargetIso(m, baseIso, sign) {
+    const [y, mo, d] = baseIso.split("-").map(Number);
+    const dt = new Date(Date.UTC(y ?? 1970, (mo ?? 1) - 1, d ?? 1));
     const n = sign * Number(m[1]);
     const unit = (m[2] ?? "").toLowerCase();
-    const d = new Date(now);
     if (unit === "d")
-        d.setDate(d.getDate() + n);
+        dt.setUTCDate(dt.getUTCDate() + n);
     else if (unit === "w")
-        d.setDate(d.getDate() + 7 * n);
+        dt.setUTCDate(dt.getUTCDate() + 7 * n);
     else if (unit === "m")
-        d.setMonth(d.getMonth() + n);
+        dt.setUTCMonth(dt.getUTCMonth() + n);
     else
-        d.setFullYear(d.getFullYear() + n);
-    return d;
+        dt.setUTCFullYear(dt.getUTCFullYear() + n);
+    return isoFromUtc(dt);
+}
+/** The ISO date at a whole absolute period's START or END edge (`2024` → Jan 1 / Dec 31, etc.). */
+function absolutePeriodIso(m, edge) {
+    const year = Number(m[1]);
+    if (m[2] === undefined)
+        return edge === "start" ? `${m[1]}-01-01` : `${m[1]}-12-31`;
+    const month = Number(m[2]) - 1;
+    if (m[3] === undefined) {
+        if (edge === "start")
+            return `${m[1]}-${m[2]}-01`;
+        const lastDay = new Date(Date.UTC(year, month + 1, 0)).getUTCDate();
+        return `${m[1]}-${m[2]}-${String(lastDay).padStart(2, "0")}`;
+    }
+    return `${m[1]}-${m[2]}-${m[3]}`;
 }
 /**
  * Double a relative period for a "wider window" suggestion: `1m`→`2m`,
@@ -72,23 +101,15 @@ export function doublePeriod(period) {
  * 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()) {
+export function parsePeriodEnd(s, now = new Date(), zone) {
     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);
+        return dayBoundInstant(relativeTargetIso(rel, localToday(now, zone), 1), "end", zone);
     }
     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);
+    return dayBoundInstant(absolutePeriodIso(m, "end"), "end", zone);
 }
 /**
  * `--since` accepting the same vocabulary at the period's START: `2024` =
@@ -96,22 +117,15 @@ export function parsePeriodEnd(s, now = new Date()) {
  * 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()) {
+export function parsePeriodStart(s, now = new Date(), zone) {
     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());
+        return dayBoundInstant(relativeTargetIso(rel, localToday(now, zone), -1), "start", zone);
     }
     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]));
+    return dayBoundInstant(absolutePeriodIso(m, "start"), "start", zone);
 }
 /**
  * GUI-style Upcoming bucket for a date, granularity decaying with distance: