things-api 0.9.0 → 0.11.0

package/dist/cli/skill.js

@@ -0,0 +1,142 @@
+/**
+ * Shared helpers for the bundled agent skill (`skills/things-cli/`): where the
+ * package copy lives, where an installed copy lands, and how to read the
+ * version stamp both carry. Used by `things install-skill` (distribution) and
+ * the passive CLI drift notice.
+ *
+ * Pure CLI-surface support — node builtins only, no library internals — so it
+ * respects the consumer air gap (AGENTS.md, docs/design/architecture.md).
+ */
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { existsSync, readFileSync } from "node:fs";
+/** The skill's canonical name — its directory basename in every install root. */
+export const SKILL_NAME = "things-cli";
+/**
+ * The bundled skill directory inside THIS package. Resolved from the module's
+ * own location (three levels above src/cli/ AND dist/cli/), so it works under
+ * every package-manager layout — npm, pnpm, bun, npx — with no PATH heuristics.
+ */
+export function bundledSkillDir() {
+    return fileURLToPath(new URL(`../../skills/${SKILL_NAME}`, import.meta.url));
+}
+/** The home directory to resolve `~/.agents` etc. against (env override wins). */
+export function resolveHome(env = process.env) {
+    const h = env["HOME"];
+    return h !== undefined && h !== "" ? h : homedir();
+}
+/**
+ * The well-known install locations we can place and read without the `skills`
+ * CLI's harness detection. The canonical `~/.agents` root comes first — agent
+ * dirs may be symlinks to it, and it is where the drift check looks before the
+ * agent-specific fallbacks.
+ */
+export function skillLocations(home) {
+    return [
+        {
+            label: "canonical (~/.agents)",
+            dir: join(home, ".agents", "skills", SKILL_NAME),
+            canonical: true,
+        },
+        {
+            label: "Claude (~/.claude)",
+            dir: join(home, ".claude", "skills", SKILL_NAME),
+            canonical: false,
+        },
+    ];
+}
+/**
+ * Parse the `version:` stamp from a SKILL.md's YAML frontmatter. Returns the
+ * trimmed value, or null when there is no frontmatter or no version key.
+ * Deliberately tiny (no YAML dependency): the frontmatter is a flat key list.
+ */
+export function parseSkillVersion(md) {
+    if (!md.startsWith("---"))
+        return null;
+    const end = md.indexOf("\n---", 3);
+    if (end === -1)
+        return null;
+    const front = md.slice(0, end);
+    for (const line of front.split("\n")) {
+        const m = /^version:\s*(.+?)\s*$/.exec(line);
+        if (m && m[1] !== undefined)
+            return m[1].replace(/^["']|["']$/g, "");
+    }
+    return null;
+}
+/**
+ * Rewrite the `version:` line in a SKILL.md's frontmatter to `version`. Pure
+ * string transform used by the publish-time stamp (scripts/stamp-skill.mjs).
+ * Throws when there is no frontmatter or no `version:` key — the source file is
+ * expected to carry the `0.0.0-dev` slot.
+ */
+export function stampSkillVersion(md, version) {
+    const end = md.indexOf("\n---", 3);
+    if (!md.startsWith("---") || end === -1)
+        throw new Error("SKILL.md has no frontmatter");
+    const front = md.slice(0, end);
+    const rest = md.slice(end);
+    if (!/^version:\s*.+$/m.test(front))
+        throw new Error("SKILL.md frontmatter has no 'version:' key");
+    return front.replace(/^version:\s*.+$/m, `version: ${version}`) + rest;
+}
+/** Read the version stamp from a SKILL.md file, or null if absent/unreadable. */
+export function readSkillVersion(skillMdPath) {
+    try {
+        return parseSkillVersion(readFileSync(skillMdPath, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+/** The bundled SKILL.md's version stamp (what a fresh install would carry). */
+export function bundledSkillVersion() {
+    return readSkillVersion(join(bundledSkillDir(), "SKILL.md"));
+}
+/** The stamp of the installed skill at `dir`, or null when nothing is there. */
+export function installedSkillVersion(dir) {
+    const md = join(dir, "SKILL.md");
+    if (!existsSync(md))
+        return null;
+    return readSkillVersion(md);
+}
+/** Parse `X.Y.Z` (suffix tolerated), or null when it is not a `X.Y.Z` stamp. */
+export function parseSemver(v) {
+    if (v === null)
+        return null;
+    const m = /^(\d+)\.(\d+)\.(\d+)/.exec(v.trim());
+    if (!m)
+        return null;
+    return { major: Number(m[1]), minor: Number(m[2]), patch: Number(m[3]) };
+}
+/** -1 / 0 / +1 for a<b / a==b / a>b; null when either is not a `X.Y.Z` stamp. */
+export function compareSemver(a, b) {
+    const pa = parseSemver(a);
+    const pb = parseSemver(b);
+    if (pa === null || pb === null)
+        return null;
+    if (pa.major !== pb.major)
+        return pa.major < pb.major ? -1 : 1;
+    if (pa.minor !== pb.minor)
+        return pa.minor < pb.minor ? -1 : 1;
+    if (pa.patch !== pb.patch)
+        return pa.patch < pb.patch ? -1 : 1;
+    return 0;
+}
+/**
+ * True when `installed` is a MINOR version or more behind `bundled` — i.e. their
+ * `(major, minor)` differs and bundled is the newer pair. Patch-only drift is
+ * NOT behind (too small to nudge). False when either is not a `X.Y.Z` stamp, so
+ * a dev build (`0.0.0-dev` → 0.0.0) never flags anything as behind.
+ */
+export function isMinorBehind(installed, bundled) {
+    const pi = parseSemver(installed);
+    const pb = parseSemver(bundled);
+    if (pi === null || pb === null)
+        return false;
+    if (pb.major !== pi.major)
+        return pb.major > pi.major;
+    return pb.minor > pi.minor;
+}
+//# sourceMappingURL=skill.js.map

package/dist/cli/skill.js.map

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

package/dist/cli/tag-filters.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The three universal tag-filter flags (`--tag`, `--exact-tag`, `--untagged`)
+ * shared by every read command that accepts them — the flat list views
+ * (reads.ts) and the container views (project.ts, area.ts, show.ts). One place
+ * owns the help copy, the repeatable-collect, the mutual-exclusivity guard, and
+ * the mapping to a {@link ViewFilter}.
+ *
+ * Two axes live in `--tag`: (A) CONTAINER inheritance (an item inherits its
+ * project/area/heading tags) and (B) TAG-HIERARCHY descendant expansion
+ * (filtering `Parent` matches items tagged with a descendant). `--exact-tag`
+ * drops only (B). Axis (A) is view-dependent: FLAT views keep it (an
+ * inheritance-inclusive `--tag`); CONTAINER views (`project show`, `area show`,
+ * the `projects` list) drop it, since every child inherits the container's tags
+ * — there a `--tag` matches a DIRECT assignment (still descendant-expanded).
+ */
+import type { Command } from "commander";
+import { hasTagPresence as hasTagPresenceShared, type TagPresence, type ViewFilter } from "../index.ts";
+/** Commander repeatable-collect: accumulate each `--tag` value. */
+export declare const collectRef: (value: string, previous: string[]) => string[];
+/**
+ * Help copy for the tag-filter flags (shared verbatim across every view). Kept
+ * to a one-liner: the full inheritance/descendant model — the two axes and how
+ * they differ between flat and container views — lives in `things help filters`.
+ */
+export declare const TAG_DESC: string;
+export declare const EXACT_TAG_DESC = "match the named tag(s) only \u2014 exclude hierarchy descendants";
+export declare const UNTAGGED_DESC = "only items with no tag \u2014 the app's \"No Tag\" filter; see `things help filters`";
+/**
+ * The `--help` footer appended to the container views (`project show`,
+ * `area show`, the `projects` list) explaining their `--tag` semantics: the
+ * filter matches a tag carried directly on the child, ignoring tags inherited
+ * from the container (every child inherits those, so an inheritance-inclusive
+ * match would be vacuous).
+ */
+export declare const CONTAINER_TAG_HINT: string;
+/**
+ * The parsed shape of the three tag-filter flags on any tag-accepting view.
+ * A structural subtype of the shared {@link TagPresence}, so the CLI's parsed
+ * commander options feed the shared predicates without adaptation.
+ */
+export interface TagFlags extends TagPresence {
+    tag?: string[];
+    exactTag?: boolean;
+    untagged?: boolean;
+}
+/** Register the three universal tag-filter flags on a command, in help order. */
+export declare function addTagFilterOptions(cmd: Command): Command;
+/** True when any tag-PRESENCE flag was passed (a positive filter, not a negation). */
+export declare const hasTagPresence: typeof hasTagPresenceShared;
+/**
+ * Shared usage guard for the tag-filter flags. The negation (`--untagged`)
+ * inverts a tag presence, so it does not combine with a tag-presence flag.
+ * Emits the usage error (the view's conflict style) and returns true when it
+ * fires. The predicate is the shared {@link tagFlagConflictShared}; only the
+ * CLI-voiced copy and the `--json`-aware emit stay here.
+ */
+export declare function tagFlagConflict(opts: TagFlags & {
+    json?: boolean;
+}): boolean;
+/** The ViewFilter tag fields built from the parsed flags (empty keys omitted). */
+export declare function tagFilterFields(opts: TagFlags): ViewFilter;
+/** The invocation-echo fragments for the tag flags (one `--tag <ref>` per ref). */
+export declare function tagInvocationParts(opts: TagFlags): Array<string | false>;

package/dist/cli/tag-filters.js

@@ -0,0 +1,59 @@
+import { hasTagPresence as hasTagPresenceShared, tagFilterFields as tagFilterFieldsShared, tagFlagConflict as tagFlagConflictShared, } from "../index.js";
+import { shellQuote, usageError } from "./read-driver.js";
+/** Commander repeatable-collect: accumulate each `--tag` value. */
+export const collectRef = (value, previous) => [...previous, value];
+/**
+ * Help copy for the tag-filter flags (shared verbatim across every view). Kept
+ * to a one-liner: the full inheritance/descendant model — the two axes and how
+ * they differ between flat and container views — lives in `things help filters`.
+ */
+export const TAG_DESC = "filter by tag (uuid or unique name), repeatable — several AND together; " +
+    "see `things help filters`";
+export const EXACT_TAG_DESC = "match the named tag(s) only — exclude hierarchy descendants";
+export const UNTAGGED_DESC = 'only items with no tag — the app\'s "No Tag" filter; see `things help filters`';
+/**
+ * The `--help` footer appended to the container views (`project show`,
+ * `area show`, the `projects` list) explaining their `--tag` semantics: the
+ * filter matches a tag carried directly on the child, ignoring tags inherited
+ * from the container (every child inherits those, so an inheritance-inclusive
+ * match would be vacuous).
+ */
+export const CONTAINER_TAG_HINT = "\n--tag / --untagged match a tag carried directly on the item, ignoring tags\n" +
+    "inherited from this container (every child inherits them). --exact-tag still\n" +
+    "drops hierarchy descendants.";
+/** Register the three universal tag-filter flags on a command, in help order. */
+export function addTagFilterOptions(cmd) {
+    return cmd
+        .option("--tag <ref>", TAG_DESC, collectRef, [])
+        .option("--exact-tag", EXACT_TAG_DESC)
+        .option("--untagged", UNTAGGED_DESC);
+}
+/** True when any tag-PRESENCE flag was passed (a positive filter, not a negation). */
+export const hasTagPresence = hasTagPresenceShared;
+/**
+ * Shared usage guard for the tag-filter flags. The negation (`--untagged`)
+ * inverts a tag presence, so it does not combine with a tag-presence flag.
+ * Emits the usage error (the view's conflict style) and returns true when it
+ * fires. The predicate is the shared {@link tagFlagConflictShared}; only the
+ * CLI-voiced copy and the `--json`-aware emit stay here.
+ */
+export function tagFlagConflict(opts) {
+    if (tagFlagConflictShared(opts)) {
+        usageError(opts, "--untagged does not combine with --tag/--exact-tag");
+        return true;
+    }
+    return false;
+}
+/** The ViewFilter tag fields built from the parsed flags (empty keys omitted). */
+export function tagFilterFields(opts) {
+    return tagFilterFieldsShared(opts);
+}
+/** The invocation-echo fragments for the tag flags (one `--tag <ref>` per ref). */
+export function tagInvocationParts(opts) {
+    return [
+        ...(opts.tag ?? []).map((t) => `--tag ${shellQuote(t)}`),
+        opts.exactTag === true && "--exact-tag",
+        opts.untagged === true && "--untagged",
+    ];
+}
+//# sourceMappingURL=tag-filters.js.map

package/dist/cli/tag-filters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tag-filters.js","sourceRoot":"","sources":["../../src/cli/tag-filters.ts"],"names":[],"mappings":"AAiBA,OAAO,EACL,cAAc,IAAI,oBAAoB,EACtC,eAAe,IAAI,qBAAqB,EACxC,eAAe,IAAI,qBAAqB,GAGzC,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE1D,mEAAmE;AACnE,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,KAAa,EAAE,QAAkB,EAAY,EAAE,CAAC,CAAC,GAAG,QAAQ,EAAE,KAAK,CAAC,CAAC;AAEhG;;;;GAIG;AACH,MAAM,CAAC,MAAM,QAAQ,GACnB,0EAA0E;IAC1E,2BAA2B,CAAC;AAC9B,MAAM,CAAC,MAAM,cAAc,GAAG,6DAA6D,CAAC;AAC5F,MAAM,CAAC,MAAM,aAAa,GACxB,gFAAgF,CAAC;AAEnF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAC7B,gFAAgF;IAChF,gFAAgF;IAChF,8BAA8B,CAAC;AAajC,iFAAiF;AACjF,MAAM,UAAU,mBAAmB,CAAC,GAAY;IAC9C,OAAO,GAAG;SACP,MAAM,CAAC,aAAa,EAAE,QAAQ,EAAE,UAAU,EAAE,EAAE,CAAC;SAC/C,MAAM,CAAC,aAAa,EAAE,cAAc,CAAC;SACrC,MAAM,CAAC,YAAY,EAAE,aAAa,CAAC,CAAC;AACzC,CAAC;AAED,sFAAsF;AACtF,MAAM,CAAC,MAAM,cAAc,GAAG,oBAAoB,CAAC;AAEnD;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,IAAmC;IACjE,IAAI,qBAAqB,CAAC,IAAI,CAAC,EAAE,CAAC;QAChC,UAAU,CAAC,IAAI,EAAE,oDAAoD,CAAC,CAAC;QACvE,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,eAAe,CAAC,IAAc;IAC5C,OAAO,qBAAqB,CAAC,IAAI,CAAC,CAAC;AACrC,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,kBAAkB,CAAC,IAAc;IAC/C,OAAO;QACL,GAAG,CAAC,IAAI,CAAC,GAAG,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,SAAS,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC;QACxD,IAAI,CAAC,QAAQ,KAAK,IAAI,IAAI,aAAa;QACvC,IAAI,CAAC,QAAQ,KAAK,IAAI,IAAI,YAAY;KACvC,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,25 @@
+/**
+ * The bare-mutation-verb handler (docs/design/cli-grammar.md). A top-level
+ * `things <verb> …` whose first token is a write verb (update, add, delete, …)
+ * used to fall into the show-sugar and emit a confusing `things show` usage
+ * error. Instead the resolver flags it `verb-hint` and this handler suggests
+ * the namespaced write command:
+ *
+ *   - a following ref that uniquely resolves as an area/project/to-do → one
+ *     CONCRETE suggestion echoing the remaining args
+ *     (`did you mean: things area update health --tags test`). The mutation is
+ *     NEVER auto-run — the suggestion is the deliberate keystroke.
+ *   - `add`/`create` with a title-like arg → `things todo add "<arg>"` first
+ *     (the common intent), then the other namespaces.
+ *   - no ref, an unresolvable ref, or an ambiguous ref → a hint listing the
+ *     namespaced forms and pointing at `things help writes`.
+ *
+ * Exit class is Usage (exit 2), consistent with the other resolver errors;
+ * under `--json` the suggestions ride `error.details.suggestions`.
+ */
+import type { Command } from "commander";
+/**
+ * Run the bare-verb hint: emit the suggestion(s) and set the Usage exit code.
+ * Never opens the write pipeline — this only reads to classify the ref.
+ */
+export declare function runVerbHint(program: Command, args: string[]): void;

package/dist/cli/verb-hint.js

@@ -0,0 +1,163 @@
+import { errorEnvelope, ExitCode, openThings } from "../index.js";
+import { indexPastLeadingFlags, subcommandsOf, WRITE_GROUP_ORDER } from "./resolve-invocation.js";
+import { shellQuote } from "./shell-quote.js";
+/** The type-group a resolved reference maps to a write namespace by. */
+const KIND_GROUP = { "to-do": "todo", project: "project", area: "area" };
+/** Split the raw argv into verb, ref, echo-tail, and the global read opts. */
+function parse(args) {
+    const at = indexPastLeadingFlags(args) ?? 0;
+    const verb = args[at] ?? "";
+    const after = args.slice(at + 1);
+    let json = false;
+    let db;
+    let ref = null;
+    const tail = [];
+    for (let i = 0; i < after.length; i++) {
+        const tok = after[i] ?? "";
+        if (tok === "--json") {
+            json = true;
+        }
+        else if (tok === "--db") {
+            db = after[++i];
+        }
+        else if (tok.startsWith("--db=")) {
+            db = tok.slice("--db=".length);
+        }
+        else if (!tok.startsWith("-") && ref === null) {
+            ref = tok; // the first positional is the write target
+        }
+        else {
+            tail.push(tok);
+        }
+    }
+    // A leading --json/--db (before the verb) still governs output/target.
+    for (let i = 0; i < at; i++) {
+        const tok = args[i] ?? "";
+        if (tok === "--json")
+            json = true;
+        else if (tok === "--db")
+            db = args[++i];
+        else if (tok.startsWith("--db="))
+            db = tok.slice("--db=".length);
+    }
+    return { verb, ref, tail, json, db };
+}
+/** Build `things <group> <verb> <ref?> <trailing flags…>` for the suggestion echo. */
+function typedForm(group, verb, ref, tail) {
+    const parts = ["things", group, verb, ...(ref !== null ? [shellQuote(ref)] : []), ...tail];
+    return parts.join(" ");
+}
+/** The write groups (in a stable order) whose registered verbs include `verb`. */
+function groupsWithVerb(program, verb) {
+    return WRITE_GROUP_ORDER.filter((g) => subcommandsOf(program, g).has(verb));
+}
+/** Container flags a `move` accepts — its destination is never a positional. */
+const MOVE_CONTAINER_FLAGS = new Set(["--area", "--project", "--heading", "--inbox"]);
+/**
+ * `move` takes its destination as a FLAG (--area/--project/--heading), never as
+ * a second positional. Left alone, the generic echo turns `things move X Home`
+ * into the suggestion `things todo move X Home` — which is itself a usage error.
+ * When the echo tail carries a stray positional destination and no container
+ * flag, rewrite it behind the flag matching the destination's kind (falling back
+ * to --project when it does not resolve) so the suggestion is a command that
+ * actually runs. A tail that already uses a container flag is echoed unchanged.
+ */
+function moveEchoTail(p) {
+    if (p.tail.some((t) => MOVE_CONTAINER_FLAGS.has(t)))
+        return p.tail;
+    const destIdx = p.tail.findIndex((t) => !t.startsWith("-"));
+    if (destIdx < 0)
+        return p.tail;
+    const dest = p.tail[destIdx] ?? "";
+    const rest = p.tail.filter((_, i) => i !== destIdx);
+    const flag = resolvedGroup(p.db, dest) === "area" ? "--area" : "--project";
+    return [flag, shellQuote(dest), ...rest];
+}
+/** Classify the ref's type with the read client; null when it does not uniquely resolve. */
+function resolvedGroup(db, ref) {
+    let client = null;
+    try {
+        client = openThings(db ? { dbPath: db } : {});
+        const target = client.read.showTarget(ref);
+        return KIND_GROUP[target.kind] ?? null;
+    }
+    catch {
+        // Ambiguous, unresolvable, or an unreadable db all fall to the generic hint.
+        return null;
+    }
+    finally {
+        client?.close();
+    }
+}
+/**
+ * Compose the suggestion set for a bare verb. The first line is the best guess;
+ * the rest are the other namespaced forms worth offering.
+ */
+function suggestionsFor(program, p) {
+    const verbLower = p.verb.toLowerCase();
+    // add/create: the target is a NEW title, so a name never "resolves" — offer
+    // to-do first (the common intent), then the container namespaces.
+    if (verbLower === "add" || verbLower === "create") {
+        if (p.ref === null)
+            return [];
+        return [
+            typedForm("todo", "add", p.ref, p.tail),
+            typedForm("project", "add", p.ref, p.tail),
+            typedForm("area", "add", p.ref, p.tail),
+        ];
+    }
+    const applicable = groupsWithVerb(program, verbLower);
+    // `move`'s destination is a flag, not a positional — rewrite a stray
+    // positional destination so every suggestion below is a runnable command.
+    const echoTail = verbLower === "move" ? moveEchoTail(p) : p.tail;
+    // A ref that uniquely resolves to an area/project/to-do gets ONE concrete
+    // suggestion — but only when that type actually offers the verb.
+    if (p.ref !== null) {
+        const group = resolvedGroup(p.db, p.ref);
+        if (group !== null && applicable.includes(group)) {
+            return [typedForm(group, p.verb, p.ref, echoTail)];
+        }
+    }
+    // Generic: every namespace that offers the verb (fall back to all write
+    // groups if the verb is a synonym none register directly).
+    const groups = applicable.length > 0 ? applicable : WRITE_GROUP_ORDER;
+    return groups.map((g) => typedForm(g, p.verb, p.ref, echoTail));
+}
+/** Human render: the error line, the suggestion(s), and the writes signpost. */
+function renderHuman(verb, suggestions) {
+    const lines = [];
+    if (suggestions.length === 0) {
+        lines.push(`error: \`things ${verb}\` is a write verb but names no target — writes are namespaced.`);
+    }
+    else if (suggestions.length === 1) {
+        lines.push(`error: \`things ${verb} …\` is not a command — did you mean:`);
+        lines.push(`  ${suggestions[0]}`);
+    }
+    else {
+        lines.push(`error: \`things ${verb} …\` is not a command — writes are namespaced. Try:`);
+        for (const s of suggestions)
+            lines.push(`  ${s}`);
+    }
+    lines.push("", "See `things help writes` for the full write grammar.");
+    return lines.join("\n");
+}
+/**
+ * Run the bare-verb hint: emit the suggestion(s) and set the Usage exit code.
+ * Never opens the write pipeline — this only reads to classify the ref.
+ */
+export function runVerbHint(program, args) {
+    const p = parse(args);
+    const suggestions = suggestionsFor(program, p);
+    if (p.json) {
+        const meta = { dbVersion: null, fingerprint: "unknown", elapsedMs: 0 };
+        const message = suggestions.length === 1
+            ? `\`things ${p.verb} …\` is not a command — did you mean \`${suggestions[0]}\``
+            : `\`things ${p.verb} …\` is not a command — writes are namespaced (see \`things help writes\`)`;
+        process.stdout.write(`${JSON.stringify(errorEnvelope({ code: "usage", message, details: { suggestions } }, meta))}\n`);
+    }
+    else {
+        process.stderr.write(`${renderHuman(p.verb, suggestions)}\n`);
+    }
+    process.exitCode = ExitCode.Usage;
+}
+//# sourceMappingURL=verb-hint.js.map

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

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

package/dist/cli/version.d.ts

@@ -0,0 +1,4 @@
+/** `${baseVersion}-dev` when running live TS source, else the plain version. */
+export declare function resolveCliVersion(moduleUrl: string, baseVersion: string): string;
+/** The version `things --version` and the `--help` footer report. */
+export declare const CLI_VERSION: string;

package/dist/cli/version.js

@@ -0,0 +1,18 @@
+/**
+ * The CLI version string, marked `-dev` when running from a source checkout.
+ *
+ * `bin/things.js` loads live TS source (`src/cli/main.ts`) in a dev checkout
+ * (npm link / `node bin/things.js` in the repo) and the built `dist/cli/main.js`
+ * in a published install. So inside these modules `import.meta.url` ends in
+ * `.ts` when live source is running and `.js` when the published build is —
+ * which is exactly the signal that tells the two apart. Published installs are
+ * never affected: the suffix appears only when the running module is TS.
+ */
+import { PKG_VERSION } from "../index.js";
+/** `${baseVersion}-dev` when running live TS source, else the plain version. */
+export function resolveCliVersion(moduleUrl, baseVersion) {
+    return moduleUrl.endsWith(".ts") ? `${baseVersion}-dev` : baseVersion;
+}
+/** The version `things --version` and the `--help` footer report. */
+export const CLI_VERSION = resolveCliVersion(import.meta.url, PKG_VERSION);
+//# sourceMappingURL=version.js.map

package/dist/cli/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../../src/cli/version.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,gFAAgF;AAChF,MAAM,UAAU,iBAAiB,CAAC,SAAiB,EAAE,WAAmB;IACtE,OAAO,SAAS,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,WAAW,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC;AACxE,CAAC;AAED,qEAAqE;AACrE,MAAM,CAAC,MAAM,WAAW,GAAG,iBAAiB,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC"}

package/dist/cli/width.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Width-aware TTY row fitting (docs/design/width-aware-tty.md). Terminal list
+ * rows never wrap: like the Things GUI, an over-long row truncates its title
+ * with a trailing `…` and folds its tags, keeping the always-present metadata
+ * (uuid, box, chips, tail markers, the full deadline token) intact. Everything
+ * here is pure and takes the target width explicitly, so it is unit-testable
+ * without a TTY and byte-stable off one: fitting engages ONLY when the driver
+ * resolves a positive width (setFitWidth) — the default is null (no fitting),
+ * so pipes, grep, and `--json` are untouched by construction.
+ *
+ * No runtime dependency (guest e2e bundles ship node + dist + commander only),
+ * so the display-width math is a small vendored wcwidth: SGR escapes strip to
+ * zero, East-Asian-Wide + emoji-presentation codepoints count two cells, the
+ * rest count one. ZWJ-sequence emoji can be off by a cell (accepted — worst
+ * case a row runs a hair short); the glyph vocabulary (★ ⏾ ⚑ ↻ ⍾ ≡ ◷) is all
+ * ambiguous/narrow class and counts one, so the layout math matches the render.
+ */
+/** Drop every SGR (color/dim/bold/…) escape, leaving the visible characters. */
+export declare function stripSgr(s: string): string;
+/** Terminal cells a single codepoint occupies: 0 (combining/zero-width), 2 (wide), else 1. */
+export declare function charWidth(cp: number): number;
+/** Visible terminal width of a string: SGR-stripped, summed per codepoint. */
+export declare function visibleWidth(s: string): number;
+/**
+ * Truncate PLAIN text (no SGR) to at most `cols` terminal cells, never splitting
+ * a wide codepoint across the boundary. Used to clip a raw title before its
+ * styling wrappers are re-applied, so the ellipsis/clip boundary lands OUTSIDE
+ * the SGR runs (the fitter never cuts an escape sequence).
+ */
+export declare function clipPlain(s: string, cols: number): string;
+/**
+ * The title's protected minimum, in columns. NOT a per-row clamp: it is the
+ * input to the derived floors (render.ts FULL_FIT_FLOOR / COMPACT_FIT_FLOOR =
+ * worst-case furniture + TITLE_MIN) and the threshold the sacrifice order
+ * protects the title down to. Because the driver fits every row to at least the
+ * compact floor (max(width, COMPACT_FIT_FLOOR)),
+ * the worst-furniture row's title lands at exactly TITLE_MIN and every lighter
+ * row's title is automatically wider — so this floor is always satisfiable and
+ * there is no sub-floor clip (below the floor the terminal wraps, losing nothing).
+ */
+export declare const TITLE_MIN = 16;
+/**
+ * The named, ordered stages of a row's collapse — the ratified sacrifice order
+ * (docs/design/width-aware-tty.md, GUI-measured oracle + the CLI-only container
+ * rule). Reordering the sacrifice is editing this list plus {@link fitRow}.
+ */
+export type FitStage = "full" | "both-shrink" | "container-drop" | "tags-bare";
+/**
+ * The segments of a row the fitter composes. Fixed parts are pre-styled strings
+ * (measured, never altered); the two collapsible parts arrive as raw material
+ * plus their styling closures so truncation happens on plain text and the SGR
+ * wraps the result:
+ *  - `left`     uuid column + box + meta chips (measured; the space before the
+ *               title is added by the fitter)
+ *  - `rawTitle` + `styleTitle` — the plain title text and its wrapper
+ *  - `tail`     trailing markers (count chip, ◷ ≡ ≔) — pre-styled incl. its
+ *               leading space, or ""
+ *  - `tagNames` raw tag names (no `#`) + `styleTags` wrapping a `#a #b` form
+ *               (incl. the leading space) — the fitter folds the list
+ *  - `context`  the ` (container)` suffix — pre-styled incl. leading space, or ""
+ *  - `deadline` the full ⚑ token — pre-styled incl. leading space, or ""
+ *  - `full`     the fully-composed row (the byte-identical no-fit output)
+ */
+export interface RowSegments {
+    left: string;
+    rawTitle: string;
+    styleTitle: (text: string) => string;
+    tail: string;
+    tagNames: string[];
+    styleTags: (form: string) => string;
+    context: string;
+    deadline: string;
+    full: string;
+}
+/**
+ * Fit one row into `width` terminal cells per the ratified collapse order. The
+ * always-present parts (uuid, box, meta chips, tail markers, full deadline)
+ * never shrink; title and tags divvy up what remains LAZILY — tags fold to the
+ * widest progressive level that fits and the 4:1 ratio arbitrates only when both
+ * genuinely contend (slack an under-share side leaves flows to the other). Then
+ * the CLI-only container is sacrificed WHOLE (before the last tag folds), then
+ * the last tag folds to bare `#…`, and the title bottoms at TITLE_MIN. `width` is
+ * the caller's effective width (already max'd with COMPACT_FIT_FLOOR), so the final
+ * stage always satisfies the floor; a sub-floor width would simply let the
+ * terminal wrap (the title is kept whole rather than clipped). A row that already
+ * fits keeps its full content; the only always-applied transform is the
+ * experimental deadline gutter ({@link alignDeadline}), which right-pins the `⚑`.
+ */
+export declare function fitRow(seg: RowSegments, width: number): string;
+/**
+ * The resolved fit for a view: the effective width every row is fitted to, plus
+ * whether deadline tokens render in the COMPACT form (the Things iOS narrow-
+ * width oracle — `8/12`, `58d ago` — docs/design/width-aware-tty.md § Compact
+ * deadline forms). `compact` is decided ONCE from the effective width against
+ * the two derived floors, never per row, so a view's right-pinned gutter never
+ * mixes `Aug 12` and `8/12`.
+ */
+export interface EffectiveFit {
+    /** Width to fit each row to — the raw fit width clamped up to the compact floor. */
+    width: number;
+    /** True when the effective width sits below the full-form floor. */
+    compact: boolean;
+}
+/**
+ * Resolve the effective fit from the once-resolved fit width and the two
+ * glyph-derived floors (`render.ts`: FULL_FIT_FLOOR / COMPACT_FIT_FLOOR). This
+ * is the SINGLE decision point for the full-vs-compact deadline form:
+ *   - `width ≥ full`        → full forms, fit to width (today's behavior);
+ *   - `compact ≤ width < full` → all deadlines compact, fit to width;
+ *   - `width < compact`     → clamp to the compact floor and wrap (sub-floor
+ *                             rule at the lower floor), still compact.
+ * The floors live in render.ts because their derivation needs the glyph
+ * inventory; the branching lives here so it is pure and unit-testable.
+ */
+export declare function resolveFit(fitWidth: number, fullFloor: number, compactFloor: number): EffectiveFit;
+/**
+ * Set the process-wide fit width (columns), resolved ONCE by the CLI driver at
+ * startup. `null` disables fitting (the default — every non-TTY path stays
+ * byte-stable). Tests set this explicitly and reset it afterward.
+ */
+export declare function setFitWidth(width: number | null): void;
+/** The current fit width, or null when fitting is disabled. */
+export declare function getFitWidth(): number | null;
+/**
+ * Resolve the fit width from the environment and stdout: `THINGS_WIDTH` wins
+ * when set (a positive integer forces that width; `0` disables fitting), else
+ * the terminal's column count when stdout is a TTY, else null (pipes, grep,
+ * captured output — no fitting, byte-stable). A malformed `THINGS_WIDTH` is
+ * ignored (falls through to the TTY/null resolution).
+ */
+export declare function resolveWidth(opts: {
+    env: Record<string, string | undefined>;
+    columns: number | undefined;
+    isTTY: boolean;
+}): number | null;