things-api 0.7.0 → 0.9.0

package/dist/cli/resolve-invocation.d.ts

@@ -0,0 +1,78 @@
+/**
+ * The single command router (docs/design/cli-grammar.md). Takes raw user argv
+ * (already stripped of the node/script prefix) and applies the precedence
+ * chain — registered command/alias → view keyword → reference — returning a
+ * normalized dispatch that `main.ts` feeds to commander. This replaces the
+ * former `expandShorthand` argv hack, the per-command keyword rewrites, and
+ * the hidden `--via-shorthand` marker.
+ *
+ * The resolver is argv-level and NEVER touches the database: it decides the
+ * command SHAPE. Reference resolution (uuid prefix → share link → tiered name
+ * match) happens later in `classifyShowTarget`, which needs the db. When a
+ * form's canonical command is only knowable after that resolution (bare noun,
+ * uuid/share-link routing), the `show`/`open` action fills `canonical` in via
+ * `setInvocationCanonical`; the view-keyword rewrite knows it immediately.
+ */
+import type { Command } from "commander";
+/**
+ * The type namespaces whose `show` verb takes a reference and may be omitted:
+ * `things area Hobbies` → `things area show Hobbies`. Restricted to the three
+ * TYPE groups — `config show` also exists but takes no reference, so `config`
+ * is deliberately excluded. Registered subcommands (verbs) always win over
+ * this sugar (the reserved-word rule).
+ */
+export declare const IMPLIED_SHOW_NAMESPACES: Set<string>;
+/**
+ * `show`'s keyword vocabulary: EVERY list-view command name. `things show <kw>`
+ * dispatches to the identical `things <kw>` command. Wider than the app's URL
+ * ids because `show` renders our own views — the plurals are real commands too.
+ */
+export declare const SHOW_KEYWORDS: Set<string>;
+/**
+ * `open`'s keyword vocabulary: ONLY the app's verified URL-scheme show ids.
+ * `open`'s vocabulary belongs to the app (it hands the id straight to
+ * `things:///show?id=<kw>`), so the plurals — which have no app list screen —
+ * are deliberately excluded and rejected with a tailored error.
+ */
+export declare const OPEN_KEYWORDS: Set<string>;
+export type InvocationForm = 
+/** A registered command/alias, or a flag-led/empty argv — nothing normalized. */
+"canonical"
+/** `things <subject>` — the verb `show` was omitted. */
+ | "bare-noun"
+/** `things <type> <subject>` — the `show` verb inside a type namespace was omitted. */
+ | "namespace-show"
+/** `things show <ref>` — explicit loose router by reference. */
+ | "loose-show"
+/** `things open <ref>` — explicit loose router by reference. */
+ | "loose-open"
+/** `things show <view-keyword>` — rewritten to the `<view-keyword>` command. */
+ | "show-keyword";
+export interface ResolvedInvocation {
+    form: InvocationForm;
+    /** Normalized argv handed to commander (`from: "user"`). */
+    argv: string[];
+    /**
+     * The canonical runnable command string, once known. Set at resolve time for
+     * `show-keyword`; filled in by the `show` action after reference resolution
+     * for the ref-routing forms; stays null for canonical invocations (and for
+     * loose forms whose result is not a routing sugar worth echoing).
+     */
+    canonical: string | null;
+    /** The subject/reference token (for the action to build the typed canonical). */
+    ref: string | null;
+}
+/** The invocation the current process is running (null before `resolveInvocation`). */
+export declare function getInvocation(): ResolvedInvocation | null;
+/**
+ * Record the canonical command a ref-routing form resolved to, so the renderer
+ * can echo it and stamp `meta.resolvedCommand`. No-op when the form is not a
+ * routing sugar (canonical invocations echo nothing).
+ */
+export declare function setInvocationCanonical(canonical: string): void;
+/**
+ * Classify raw user argv into a normalized dispatch and record it as the
+ * current invocation. Idempotent per process; called once by `runCli` (and by
+ * the in-process test harnesses) before commander parses.
+ */
+export declare function resolveInvocation(program: Command, args: string[]): ResolvedInvocation;

package/dist/cli/resolve-invocation.js

@@ -0,0 +1,178 @@
+import { shellQuote } from "./shell-quote.js";
+/**
+ * The type namespaces whose `show` verb takes a reference and may be omitted:
+ * `things area Hobbies` → `things area show Hobbies`. Restricted to the three
+ * TYPE groups — `config show` also exists but takes no reference, so `config`
+ * is deliberately excluded. Registered subcommands (verbs) always win over
+ * this sugar (the reserved-word rule).
+ */
+export const IMPLIED_SHOW_NAMESPACES = new Set(["area", "project", "todo"]);
+/**
+ * `show`'s keyword vocabulary: EVERY list-view command name. `things show <kw>`
+ * dispatches to the identical `things <kw>` command. Wider than the app's URL
+ * ids because `show` renders our own views — the plurals are real commands too.
+ */
+export const SHOW_KEYWORDS = new Set([
+    "inbox",
+    "today",
+    "anytime",
+    "upcoming",
+    "someday",
+    "logbook",
+    "trash",
+    "projects",
+    "areas",
+    "tags",
+]);
+/**
+ * `open`'s keyword vocabulary: ONLY the app's verified URL-scheme show ids.
+ * `open`'s vocabulary belongs to the app (it hands the id straight to
+ * `things:///show?id=<kw>`), so the plurals — which have no app list screen —
+ * are deliberately excluded and rejected with a tailored error.
+ */
+export const OPEN_KEYWORDS = new Set([
+    "inbox",
+    "today",
+    "anytime",
+    "upcoming",
+    "someday",
+    "logbook",
+    "trash",
+]);
+let current = null;
+/** The invocation the current process is running (null before `resolveInvocation`). */
+export function getInvocation() {
+    return current;
+}
+/**
+ * Record the canonical command a ref-routing form resolved to, so the renderer
+ * can echo it and stamp `meta.resolvedCommand`. No-op when the form is not a
+ * routing sugar (canonical invocations echo nothing).
+ */
+export function setInvocationCanonical(canonical) {
+    if (current !== null)
+        current.canonical = canonical;
+}
+/**
+ * Classify raw user argv into a normalized dispatch and record it as the
+ * current invocation. Idempotent per process; called once by `runCli` (and by
+ * the in-process test harnesses) before commander parses.
+ */
+export function resolveInvocation(program, args) {
+    current = classify(program, args);
+    return current;
+}
+/**
+ * Skip over LEADING GLOBAL-STYLE FLAGS to find the token being classified, so
+ * `things --json Hobbies` routes exactly like `things Hobbies --json`. Only
+ * the global read options are recognized here — `--json` (boolean) and `--db`
+ * (value-taking: its value is skipped too, never misread as the subject).
+ * Any other leading flag returns null — an unknown flag keeps the plain
+ * fall-through to commander (which reports it), rather than guessing whether
+ * the next token is that flag's value or the subject.
+ */
+function indexPastLeadingFlags(args) {
+    let i = 0;
+    while (i < args.length) {
+        const tok = args[i] ?? "";
+        if (!tok.startsWith("-"))
+            return i;
+        if (tok === "--json") {
+            i += 1;
+        }
+        else if (tok === "--db") {
+            i += 2; // skip the flag AND its value
+        }
+        else if (tok.startsWith("--db=")) {
+            i += 1;
+        }
+        else {
+            return null; // unknown leading flag — commander's to handle
+        }
+    }
+    return i; // flags only, no subject (e.g. bare `things --json`)
+}
+/** The registered subcommand names + aliases of a command group (empty when the group is unknown). */
+function subcommandsOf(program, groupName) {
+    const group = program.commands.find((c) => c.name() === groupName || c.aliases().includes(groupName));
+    const names = new Set();
+    if (group === undefined)
+        return names;
+    for (const sub of group.commands) {
+        names.add(sub.name());
+        for (const alias of sub.aliases())
+            names.add(alias);
+    }
+    return names;
+}
+function classify(program, args) {
+    const at = indexPastLeadingFlags(args);
+    const first = at === null ? undefined : args[at];
+    // An empty, flags-only, or unknown-flag-led argv is commander's to handle
+    // (help, --version, error).
+    if (first === undefined) {
+        return { form: "canonical", argv: args, canonical: null, ref: null };
+    }
+    const known = new Set(["help"]);
+    for (const c of program.commands) {
+        known.add(c.name());
+        for (const alias of c.aliases())
+            known.add(alias);
+    }
+    if (at !== 0) {
+        // A registered command reached THROUGH leading flags stays untouched:
+        // program-level flags before a command were an error before and stay one.
+        if (known.has(first)) {
+            return { form: "canonical", argv: args, canonical: null, ref: null };
+        }
+        // Precedence 3 through leading global flags: a bare-noun subject routes
+        // through `show` with the flags left in place — commander accepts options
+        // before arguments on the subcommand.
+        return { form: "bare-noun", argv: ["show", ...args], canonical: null, ref: first };
+    }
+    // Precedence 1: a registered command/alias always wins (names are reserved).
+    if (known.has(first)) {
+        if (first === "show") {
+            const second = args[1];
+            // Precedence 2 (show): a view keyword routes to that view command.
+            if (second !== undefined && SHOW_KEYWORDS.has(second.toLowerCase())) {
+                const kw = second.toLowerCase();
+                return {
+                    form: "show-keyword",
+                    argv: [kw, ...args.slice(2)],
+                    canonical: `things ${kw}`,
+                    ref: kw,
+                };
+            }
+            return { form: "loose-show", argv: args, canonical: null, ref: second ?? null };
+        }
+        if (first === "open") {
+            // Precedence 2 (open) is handled in the action: keyword launching and the
+            // plural-not-openable error both need the keyword sets, and open renders
+            // no card to anchor an echo to.
+            return { form: "loose-open", argv: args, canonical: null, ref: args[1] ?? null };
+        }
+        // Namespace implied-show: inside a TYPE group with a `show` verb, a first
+        // token that is not one of the group's registered subcommands is a subject
+        // with the verb omitted — `things area Hobbies` → `things area show
+        // Hobbies`. Registered verbs win (reserved-word rule); a flag or an absent
+        // token leaves the bare group command to commander (help / usage error).
+        if (at === 0 && IMPLIED_SHOW_NAMESPACES.has(first)) {
+            const second = args[1];
+            if (second !== undefined &&
+                !second.startsWith("-") &&
+                !subcommandsOf(program, first).has(second)) {
+                return {
+                    form: "namespace-show",
+                    argv: [first, "show", ...args.slice(1)],
+                    canonical: `things ${first} show ${shellQuote(second)}`,
+                    ref: second,
+                };
+            }
+        }
+        return { form: "canonical", argv: args, canonical: null, ref: null };
+    }
+    // Precedence 3: not a command — a bare-noun reference, routed through `show`.
+    return { form: "bare-noun", argv: ["show", ...args], canonical: null, ref: first };
+}
+//# sourceMappingURL=resolve-invocation.js.map

package/dist/cli/resolve-invocation.js.map

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

package/dist/cli/shell-quote.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Shell-safe rendering of a single argument for a reconstructed `things …`
+ * command string (truncation footers, the normalized-form echo, the
+ * did-you-mean suggestion). A plain word is left bare; anything with spaces or
+ * shell metacharacters is double-quoted with the hazardous characters escaped.
+ * Lives in its own leaf module so both the read driver and the argv resolver
+ * can share ONE quoting rule (they must agree — the echo is contract-tested).
+ */
+export declare function shellQuote(v: string): string;

package/dist/cli/shell-quote.js

@@ -0,0 +1,12 @@
+/**
+ * Shell-safe rendering of a single argument for a reconstructed `things …`
+ * command string (truncation footers, the normalized-form echo, the
+ * did-you-mean suggestion). A plain word is left bare; anything with spaces or
+ * shell metacharacters is double-quoted with the hazardous characters escaped.
+ * Lives in its own leaf module so both the read driver and the argv resolver
+ * can share ONE quoting rule (they must agree — the echo is contract-tested).
+ */
+export function shellQuote(v) {
+    return /^[\w./@:+-]+$/.test(v) ? v : `"${v.replace(/(["\\$`])/g, "\\$1")}"`;
+}
+//# sourceMappingURL=shell-quote.js.map

package/dist/cli/shell-quote.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell-quote.js","sourceRoot":"","sources":["../../src/cli/shell-quote.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,UAAU,UAAU,CAAC,CAAS;IAClC,OAAO,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,YAAY,EAAE,MAAM,CAAC,GAAG,CAAC;AAC9E,CAAC"}

package/dist/cli/style.d.ts

@@ -1,8 +1,13 @@
 export declare const bold: (s: string) => string;
 export declare const dim: (s: string) => string;
 export declare const underline: (s: string) => string;
+/** Strikethrough (SGR 9) — enhancement only; state must also live in a glyph. */
+export declare const strike: (s: string) => string;
 export declare const red: (s: string) => string;
+export declare const green: (s: string) => string;
 export declare const blue: (s: string) => string;
+/** Bright-blue (SGR 94) — the palette's "light blue"; still theme-remapped. */
+export declare const brightBlue: (s: string) => string;
 export declare const yellow: (s: string) => string;
 export declare const magenta: (s: string) => string;
 export declare const cyan: (s: string) => string;

package/dist/cli/style.js

@@ -19,8 +19,13 @@ const wrap = (open, close) => (s) => ENABLED ? `\u001b[${open}m${s}\u001b[${clos
 export const bold = wrap(1, 22);
 export const dim = wrap(2, 22);
 export const underline = wrap(4, 24);
+/** Strikethrough (SGR 9) — enhancement only; state must also live in a glyph. */
+export const strike = wrap(9, 29);
 export const red = wrap(31, 39);
+export const green = wrap(32, 39);
 export const blue = wrap(34, 39);
+/** Bright-blue (SGR 94) — the palette's "light blue"; still theme-remapped. */
+export const brightBlue = wrap(94, 39);
 export const yellow = wrap(33, 39);
 export const magenta = wrap(35, 39);
 export const cyan = wrap(36, 39);

package/dist/cli/style.js.map

@@ -1 +1 @@
-{"version":3,"file":"style.js","sourceRoot":"","sources":["../../src/cli/style.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,SAAS,YAAY;IACnB,IAAI,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IACxD,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;IACzC,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,KAAK,KAAK,GAAG,CAAC;IAC9C,OAAO,OAAO,CAAC,MAAM,CAAC,KAAK,KAAK,IAAI,CAAC;AACvC,CAAC;AAED,MAAM,OAAO,GAAG,YAAY,EAAE,CAAC;AAE/B,MAAM,IAAI,GAAG,CAAC,IAAY,EAAE,KAAa,EAAE,EAAE,CAAC,CAAC,CAAS,EAAE,EAAE,CAC1D,OAAO,CAAC,CAAC,CAAC,UAAU,IAAI,IAAI,CAAC,UAAU,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;AAEtD,MAAM,CAAC,MAAM,IAAI,GAAG,IAAI,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAChC,MAAM,CAAC,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAC/B,MAAM,CAAC,MAAM,SAAS,GAAG,IAAI,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AACrC,MAAM,CAAC,MAAM,GAAG,GAAG,IAAI,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;AAChC,MAAM,CAAC,MAAM,IAAI,GAAG,IAAI,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;AACjC,MAAM,CAAC,MAAM,MAAM,GAAG,IAAI,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;AACnC,MAAM,CAAC,MAAM,OAAO,GAAG,IAAI,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;AACpC,MAAM,CAAC,MAAM,IAAI,GAAG,IAAI,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC"}
+{"version":3,"file":"style.js","sourceRoot":"","sources":["../../src/cli/style.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,SAAS,YAAY;IACnB,IAAI,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IACxD,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;IACzC,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,KAAK,KAAK,GAAG,CAAC;IAC9C,OAAO,OAAO,CAAC,MAAM,CAAC,KAAK,KAAK,IAAI,CAAC;AACvC,CAAC;AAED,MAAM,OAAO,GAAG,YAAY,EAAE,CAAC;AAE/B,MAAM,IAAI,GAAG,CAAC,IAAY,EAAE,KAAa,EAAE,EAAE,CAAC,CAAC,CAAS,EAAE,EAAE,CAC1D,OAAO,CAAC,CAAC,CAAC,UAAU,IAAI,IAAI,CAAC,UAAU,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;AAEtD,MAAM,CAAC,MAAM,IAAI,GAAG,IAAI,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAChC,MAAM,CAAC,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAC/B,MAAM,CAAC,MAAM,SAAS,GAAG,IAAI,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AACrC,iFAAiF;AACjF,MAAM,CAAC,MAAM,MAAM,GAAG,IAAI,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAClC,MAAM,CAAC,MAAM,GAAG,GAAG,IAAI,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;AAChC,MAAM,CAAC,MAAM,KAAK,GAAG,IAAI,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;AAClC,MAAM,CAAC,MAAM,IAAI,GAAG,IAAI,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;AACjC,+EAA+E;AAC/E,MAAM,CAAC,MAAM,UAAU,GAAG,IAAI,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;AACvC,MAAM,CAAC,MAAM,MAAM,GAAG,IAAI,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;AACnC,MAAM,CAAC,MAAM,OAAO,GAAG,IAAI,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;AACpC,MAAM,CAAC,MAAM,IAAI,GAAG,IAAI,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC"}

package/dist/client.d.ts

@@ -9,12 +9,14 @@ import type { AnyTask, Area, Project, Tag } from "./model/entities.ts";
 import { type AreaView } from "./read/area-view.ts";
 import { type ProjectView } from "./read/project-view.ts";
 import { type Snapshot } from "./read/snapshot.ts";
-import { type ChangedItem, type ListItem, type SearchOptions, type SidebarSection, type SomedayFilter, type TodayView, type UpcomingFilter, type ViewFilter } from "./read/views.ts";
-import type { AreaAddParams, AreaUpdateParams, ChecklistItemSpec, ContainerRef, ProjectCancelParams, OperationKind, OperationParamsMap, ProjectAddParams, ProjectCompleteParams, ProjectUpdateParams, ReorderParams, TagAddParams, TagUpdateParams, HeadingArchiveParams, HeadingUnarchiveParams, TodoAddLoggedParams, TodoAddParams, TodoBackdateParams, TodoMoveParams, TodoUpdateParams } from "./write/operations.ts";
+import { type ShowTarget } from "./read/show-target.ts";
+import { type ChangedItem, type LiteSearchResult, type ListItem, type LogbookFilter, type SearchOptions, type SearchResultItem, type SidebarSection, type SomedayFilter, type TodayView, type UpcomingFilter, type ViewFilter } from "./read/views.ts";
+import type { AreaAddParams, AreaUpdateParams, ContainerRef, ProjectCancelParams, OperationKind, OperationParamsMap, ProjectAddParams, ProjectCompleteParams, ProjectUpdateParams, ReorderParams, TagAddParams, TagUpdateParams, HeadingArchiveParams, HeadingUnarchiveParams, TodoAddLoggedParams, TodoAddParams, TodoBackdateParams, TodoMoveParams, TodoUpdateParams } from "./write/operations.ts";
 import { type MutationResult, type WriteOptions } from "./write/pipeline.ts";
 import { type BatchItemResult, type BatchOp, type BatchOptions } from "./write/batch.ts";
 import { type EnvironmentTracker } from "./write/environment.ts";
 import { type HeadingArchiveResult, type HeadingUnarchiveResult } from "./write/heading.ts";
+import type { ChecklistEdit } from "./write/checklist.ts";
 import { type ReorderResult } from "./write/reorder.ts";
 import { type UndoItemResult, type UndoOptions } from "./write/undo.ts";
 import { type ProjectReopenOptions, type ProjectReopenResult } from "./write/reopen.ts";
@@ -48,16 +50,18 @@ export interface ThingsClient {
         anytime(filter?: ViewFilter): SidebarSection[];
         upcoming(filter?: UpcomingFilter): ListItem[];
         someday(filter?: SomedayFilter): SidebarSection[];
-        logbook(options?: {
-            limit?: number;
-            tag?: string;
-            exactTag?: boolean;
-        }): ListItem[];
+        logbook(options?: LogbookFilter): ListItem[];
         trash(options?: {
-            limit?: number;
+            limit?: number | null;
         }): ListItem[];
+        /**
+         * Projects in sidebar order. LATER (someday + future-scheduled) projects
+         * are excluded by default — `later: true` appends them after the active
+         * block of their group (loose block / area), never intermingled.
+         */
         projects(options?: {
             areaUuid?: string;
+            later?: boolean;
         }): Project[];
         /** Composite project view. Targets by uuid, unique name, or uuid prefix. */
         projectView(ref: string): ProjectView;
@@ -65,13 +69,28 @@ export interface ThingsClient {
         areaView(ref: string): AreaView;
         areas(): Area[];
         tags(): Tag[];
-        search(query: string, options?: SearchOptions): ListItem[];
+        search(query: string, options?: SearchOptions): SearchResultItem[];
+        /**
+         * Did-you-mean fallback: case-insensitive title-only substring match over
+         * areas/projects/to-dos (open + untrashed), ordered and capped. `type`
+         * scopes to one class.
+         */
+        liteTitleSearch(query: string, options?: {
+            type?: "to-do" | "project" | "area";
+            limit?: number;
+        }): LiteSearchResult;
         /** Rows created/modified since a moment — incl. trashed/logged/templates. */
         changes(options: {
             since: Date;
-            limit?: number;
+            limit?: number | null;
         }): ChangedItem[];
         byUuid(uuid: string): AnyTask | null;
+        /**
+         * Classify a loose reference (uuid, >=6-char prefix, share link, or
+         * area name) into the resource class that has a show view. Headings
+         * resolve to their containing project (viaHeading: true).
+         */
+        showTarget(ref: string): ShowTarget;
         snapshot(): Snapshot;
     };
     write: {
@@ -93,6 +112,14 @@ export interface ThingsClient {
         duplicateTodo(uuid: string, options?: WriteOptions): Promise<MutationResult>;
         /** Restore a TRASHED to-do: it returns to the Inbox, de-scheduled. */
         restoreTodo(uuid: string, options?: WriteOptions): Promise<MutationResult>;
+        /**
+         * Clear a to-do's time-of-day reminder while keeping its scheduled date.
+         * Uses the Things proxy shortcuts when installed (in place, and the only
+         * path for repeating to-dos); without them, a non-repeating dated to-do
+         * falls back to a URL re-schedule that briefly moves it to Today and back.
+         * Reversible with `undo`. Force a path with `vector: "shortcuts" | "url-scheme"`.
+         */
+        clearReminder(uuid: string, options?: WriteOptions): Promise<MutationResult>;
         /**
          * Rewrite a to-do's completion and/or creation timestamp to noon (local)
          * on the given date. Completion requires the to-do to be completed or
@@ -104,6 +131,12 @@ export interface ThingsClient {
          * completion (and optionally creation) timestamps.
          */
         addLoggedTodo(params: TodoAddLoggedParams, options?: WriteOptions): Promise<MutationResult>;
+        /**
+         * Create a heading inside an EXISTING project; the new heading's uuid is
+         * on the result. Delivered through the Things proxy shortcuts (run
+         * `things setup shortcuts` once first).
+         */
+        createHeading(project: ContainerRef, title: string, options?: WriteOptions): Promise<MutationResult>;
         /** Rename a heading in place (works on archived headings too). */
         renameHeading(uuid: string, title: string, options?: WriteOptions): Promise<MutationResult>;
         /**
@@ -173,33 +206,6 @@ export interface ThingsClient {
     };
     close(): void;
 }
-/** One granular checklist edit; every other item's checked state is preserved. */
-/**
- * Target for an existing checklist item: by `item` (title) or `index`
- * (1-based). Provide exactly one. Title matching is best-effort on duplicates
- * (docs/design/reference-resolution.md); index is exact.
- */
-export interface ChecklistTarget {
-    item?: string;
-    /** 1-based position; overrides `item` when both are given. */
-    index?: number;
-}
-export type ChecklistEdit = {
-    action: "add";
-    title: string; /** 1-based insert position (default: append). */
-    at?: number;
-} | ({
-    action: "remove";
-} & ChecklistTarget) | ({
-    action: "check";
-} & ChecklistTarget) | ({
-    action: "uncheck";
-} & ChecklistTarget) | ({
-    action: "rename";
-    title: string;
-} & ChecklistTarget) | ({
-    action: "move"; /** 1-based target position. */
-    to: number;
-} & ChecklistTarget);
-export declare function applyChecklistEdit(items: ChecklistItemSpec[], edit: ChecklistEdit): ChecklistItemSpec[];
+export type { ChecklistEdit, ChecklistTarget, ChecklistItemAction } from "./write/checklist.ts";
+export { applyChecklistEdit } from "./write/checklist.ts";
 export declare function openThings(options?: OpenOptions): ThingsClient;

package/dist/client.js

@@ -11,76 +11,20 @@ import { resolveProjectUuid, resolveTaskUuidPrefix } from "./read/queries.js";
 import { areaView } from "./read/area-view.js";
 import { projectView } from "./read/project-view.js";
 import { snapshotView } from "./read/snapshot.js";
+import { classifyShowTarget } from "./read/show-target.js";
 import { areasView, tagsView } from "./read/tags.js";
-import { anytimeView, changesView, inboxView, logbookView, projectsView, searchView, somedayView, todayView, trashView, upcomingView, } from "./read/views.js";
+import { anytimeView, changesView, inboxView, liteTitleSearch, logbookView, projectsView, searchView, somedayView, todayView, trashView, upcomingView, } from "./read/views.js";
 import { readAuthToken, runMutation, } from "./write/pipeline.js";
 import { runBatch } from "./write/batch.js";
 import { createEnvironmentTracker } from "./write/environment.js";
 import { runHeadingArchive, runHeadingUnarchive, } from "./write/heading.js";
+import { runClearReminder } from "./write/clear-reminder.js";
+import { runEditChecklist } from "./write/edit-checklist.js";
 import { runReorder } from "./write/reorder.js";
 import { runUndo } from "./write/undo.js";
 import { runProjectReopen, } from "./write/reopen.js";
 import { defaultVectors } from "./write/vectors/registry.js";
-/**
- * Resolve a checklist target to an array index. `index` (1-based) is exact.
- * A title resolves best-effort: unique → that item; duplicates → the first on
- * which the action is meaningful (check → first unchecked, uncheck → first
- * checked, others → first match). Loud only when nothing matches / index is
- * out of range.
- */
-function checklistTarget(items, edit) {
-    if (edit.index !== undefined) {
-        const i = edit.index - 1;
-        if (i < 0 || i >= items.length) {
-            throw new RangeError(`checklist index ${edit.index} is out of range (1..${items.length})`);
-        }
-        return i;
-    }
-    const ref = edit.item;
-    if (ref === undefined)
-        throw new RangeError("give a checklist item title or 1-based index");
-    const matches = items.map((c, i) => ({ c, i })).filter(({ c }) => c.title === ref);
-    if (matches.length === 0)
-        throw new RangeError(`no checklist item titled "${ref}"`);
-    if (matches.length === 1)
-        return matches[0].i;
-    const meaningful = edit.action === "check"
-        ? matches.find(({ c }) => !c.completed)
-        : edit.action === "uncheck"
-            ? matches.find(({ c }) => c.completed)
-            : undefined;
-    return (meaningful ?? matches[0] ?? { i: 0 }).i;
-}
-export function applyChecklistEdit(items, edit) {
-    const next = items.map((c) => ({ ...c }));
-    switch (edit.action) {
-        case "add": {
-            const at = edit.at === undefined ? next.length : Math.max(0, Math.min(next.length, edit.at - 1));
-            next.splice(at, 0, { title: edit.title, completed: false });
-            return next;
-        }
-        case "remove":
-            next.splice(checklistTarget(next, edit), 1);
-            return next;
-        case "check":
-        case "uncheck": {
-            const target = next[checklistTarget(next, edit)];
-            target.completed = edit.action === "check";
-            return next;
-        }
-        case "rename": {
-            const target = next[checklistTarget(next, edit)];
-            target.title = edit.title;
-            return next;
-        }
-        case "move": {
-            const from = checklistTarget(next, edit);
-            const [moved] = next.splice(from, 1);
-            next.splice(Math.max(0, Math.min(next.length, edit.to - 1)), 0, moved);
-            return next;
-        }
-    }
-}
+export { applyChecklistEdit } from "./write/checklist.js";
 export function openThings(options = {}) {
     const located = locateThingsDb(options.dbPath ? { dbPath: options.dbPath } : undefined);
     const conn = openConnection(located.path);
@@ -135,12 +79,14 @@ export function openThings(options = {}) {
             logbook: (o) => logbookView(conn.db, o),
             trash: (o) => trashView(conn.db, o),
             projects: (o) => projectsView(conn.db, o),
-            projectView: (ref) => projectView(conn.db, resolveProjectUuid(conn.db, ref), now()),
+            projectView: (ref) => projectView(conn.db, resolveProjectUuid(conn.db, ref, { trashed: true }), now()),
             areaView: (ref) => areaView(conn.db, ref, now()),
             areas: () => areasView(conn.db),
             tags: () => tagsView(conn.db),
             search: (query, o) => searchView(conn.db, query, o),
+            liteTitleSearch: (query, o) => liteTitleSearch(conn.db, query, o),
             changes: (o) => changesView(conn.db, o),
+            showTarget: (ref) => classifyShowTarget(conn.db, ref),
             byUuid: (uuid) => {
                 // Prefix-friendly: unknown refs keep the null contract; ambiguity throws.
                 try {
@@ -175,22 +121,13 @@ export function openThings(options = {}) {
             restoreTodo: (uuid, o) => run("todo.restore", { uuid }, o),
             backdateTodo: (uuid, dates, o) => run("todo.backdate", { uuid, ...dates }, o),
             addLoggedTodo: (params, o) => run("todo.add-logged", params, o),
+            createHeading: (project, title, o) => run("heading.create", { project, title }, o),
             renameHeading: (uuid, title, o) => run("heading.rename", { uuid, title }, o),
+            clearReminder: (uuid, o) => runClearReminder(writeDeps, { uuid }, o ?? {}),
             archiveHeading: (uuid, policy, o) => runHeadingArchive(writeDeps, { uuid, ...policy }, o ?? {}),
             unarchiveHeading: (uuid, policy, o) => runHeadingUnarchive(writeDeps, { uuid, ...policy }, o ?? {}),
             detachTodo: (uuid, o) => run("todo.move", { uuid, detach: true }, o),
-            editChecklist(uuid, edit, o) {
-                const current = byUuid(conn.db, uuid);
-                if (current === null || current.type !== "to-do") {
-                    throw new RangeError(`no to-do with uuid ${uuid}`);
-                }
-                const items = (current.checklist ?? []).map((c) => ({
-                    title: c.title,
-                    completed: c.status === "completed",
-                }));
-                const next = applyChecklistEdit(items, edit);
-                return run("todo.replace-checklist", { uuid, items: next }, { ...o, acknowledgeChecklistReset: true });
-            },
+            editChecklist: (uuid, edit, o) => runEditChecklist(writeDeps, uuid, edit, o ?? {}),
             addProject: (params, o) => run("project.add", params, o),
             updateProject: (uuid, patch, o) => run("project.update", { uuid, ...patch }, o),
             completeProject: (uuid, policy, o) => run("project.complete", { uuid, children: policy.children }, o),