things-api 0.11.0 → 0.13.0

package/dist/client.d.ts

@@ -5,21 +5,25 @@
 import type { AuditWriter } from "./audit/log.ts";
 import { type ThingsApiConfig } from "./config.ts";
 import { type ClockMeta } from "./model/clock.ts";
-import { type GroupedTruncation, type Truncation } from "./contracts.ts";
+import { type Truncation } from "./contracts.ts";
 import { type FingerprintStatus, type SchemaStatus } from "./db/fingerprint.ts";
 import type { AnyTask, Area, Project, Tag } from "./model/entities.ts";
+import type { RefPromoter } from "./read/shape.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 ShowTarget } from "./read/show-target.ts";
 import { type ChangedItem, type InboxFilter, type LiteSearchResult, type ListItem, type LogbookFilter, type SearchOptions, type SearchResultItem, type SidebarSection, type SomedayFilter, type TodayFilter, type TodayView, type UpcomingFilter, type ViewFilter } from "./read/views.ts";
-import type { AreaAddParams, AreaUpdateParams, ContainerRef, ProjectCancelParams, OperationKind, OperationParamsMap, ProjectAddParams, ProjectCompleteParams, ProjectCreateRepeatingParams, ProjectUpdateParams, RepeatRuleParams, ReorderParams, TagAddParams, TagUpdateParams, HeadingArchiveParams, HeadingUnarchiveParams, TodoAddLoggedParams, TodoAddParams, TodoBackdateParams, TodoMoveParams, TodoUpdateParams } from "./write/operations.ts";
+import { type AreaScopedRead, type ViewFilterMeta } from "./read/area-filter.ts";
+import { type ScopeMeta } from "./read/scope.ts";
+import type { AreaAddParams, AreaUpdateParams, ContainerRef, ProjectCancelParams, OperationKind, OperationParamsMap, ProjectAddParams, ProjectCompleteParams, ProjectAddRepeatingParams, ProjectUpdateParams, RepeatRuleParams, ReorderParams, TagAddParams, TagUpdateParams, HeadingArchiveParams, HeadingUnarchiveParams, HeadingPlacement, 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 BatchItemResult, type BatchOp, type BatchOptions, type BatchResult } 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 MoveResult, type ProjectMoveRequest, type ReorderRequest, type TodoMoveRequest } from "./write/move.ts";
 import { type UndoItemResult, type UndoOptions } from "./write/undo.ts";
 import { type ProjectReopenOptions, type ProjectReopenResult } from "./write/reopen.ts";
 import type { WriteVector } from "./write/vectors/types.ts";
@@ -38,6 +42,16 @@ export interface OpenOptions {
     vectors?: WriteVector[];
     /** Env for config/state-dir resolution (tests). */
     env?: NodeJS.ProcessEnv;
+    /**
+     * Container scope: a ref (uuid / uuid-prefix / unique area or project name)
+     * that jails this client to one container — reads see only in-scope rows,
+     * writes are refused (or redirected) outside it, and out-of-scope refs are
+     * indistinguishable from nonexistent ones. This is the MCP `--scope` flag's
+     * entry point and OUTRANKS `THINGS_API_SCOPE` / the stored `scope` config
+     * (the launcher's boundary must not be agent-overridable). Unresolvable →
+     * fail closed (ScopeResolutionError). See docs/design/container-scope.md.
+     */
+    scope?: string;
     /** Test seams for the mutation pipeline. */
     writeOverrides?: {
         ensureRunning?: (alreadyRunning: boolean) => Promise<boolean>;
@@ -81,33 +95,61 @@ export interface GroupedBound {
 export interface BoundedList<T> {
     items: T[];
     truncation: Truncation;
+    /** The active `area` scope, when one was applied (surfaced as `meta.filter`). */
+    filter?: ViewFilterMeta;
 }
 /**
- * A bounded Today view: `view` is the shown split (capped in render order —
- * Today, then This Evening) and `truncation` the exact counts, including the
- * per-section (`today`/`evening`) breakdown a renderer needs to stay honest.
+ * A bounded today view: `view` is the shown flat `items[]` (capped in comparator
+ * order) plus the whole-view `counts`, and `truncation` the exact counts,
+ * including the per-render-section (`today`/`evening`) breakdown — derived per row
+ * from `when` — a renderer needs to stay honest.
  */
 export interface BoundedTodayView {
     view: TodayView;
     truncation: Truncation;
+    /** The active `area` scope, when one was applied (surfaced as `meta.filter`). */
+    filter?: ViewFilterMeta;
 }
 /**
  * A bounded sidebar catalogue (anytime/someday): `view` is the
- * per-block-capped sections and `grouped` the per-block counts (identity-
- * carrying, project blocks nested under their area/loose block).
+ * per-block-capped sections and `truncation` the unified completeness metadata
+ * whose `blocks` carry the identity-bearing per-block counts (project blocks
+ * nested under their area/loose block).
  */
 export interface BoundedSectionsView {
     view: SidebarSection[];
-    grouped: GroupedTruncation;
+    truncation: Truncation;
+    /** The active `area` scope, when one was applied (surfaced as `meta.filter`). */
+    filter?: ViewFilterMeta;
 }
-/** A bounded composite area card: the per-section-capped view and the per-block counts. */
+/** A bounded composite area card: the per-section-capped view and the per-block truncation. */
 export interface BoundedAreaView {
     view: AreaView;
-    grouped: GroupedTruncation;
+    truncation: Truncation;
+    /**
+     * A resolution disclosure — present ONLY on the `loose` pseudo-area read when
+     * a real area shadows the reserved word (names it, by uuid, for targeting).
+     * Surfaced by the consumers as a `meta.warnings` advisory.
+     */
+    notice?: string;
+    /**
+     * The live count of the area's logged rows (subtree-inclusive, past the
+     * log-move boundary — the population `things logbook --area <ref>` returns).
+     * Present for a real area, absent for the `loose` pseudo-area. A DISPLAY
+     * sibling of `view`: it feeds the TTY card's logbook footer and never enters
+     * the JSON area-view `data`.
+     */
+    loggedCount?: number;
 }
 export interface ThingsClient {
     dbPath: string;
     config: ThingsApiConfig;
+    /**
+     * The active container scope (pinned at open), or undefined when unscoped.
+     * The consumer surfaces surface it as the additive `meta.scope` and the
+     * one-line "scoped to …" banner so the jail is never silently on.
+     */
+    scope?: ScopeMeta;
     fingerprint(): FingerprintStatus;
     /**
      * The read-path schema check: the cached fingerprint comparison reduced to a
@@ -123,30 +165,58 @@ export interface ThingsClient {
      * `tz` argument) so the reported `today` matches what that read computed.
      */
     clockMeta(zoneOverride?: string): ClockMeta | undefined;
+    /**
+     * Reference resolvers the consumer surfaces (CLI/MCP) call to turn a project
+     * ref + heading selector into uuids before invoking a heading verb. Both
+     * throw {@link ReferenceResolutionError} (uuid candidates on ambiguity),
+     * scope-aware when a container scope is active. `heading` shares the one
+     * heading-selector core (title | uuid | empty-string literal; no ordinal).
+     */
+    resolve: {
+        project(ref: string): {
+            uuid: string;
+            title: string;
+        };
+        heading(projectUuid: string, sel: string): {
+            uuid: string;
+            title: string;
+        };
+    };
+    /**
+     * A fresh {@link RefPromoter} (fresh memo) the consumer surfaces hand to
+     * {@link shapeReadPayload} so the flat `area`/`project`/`heading` refs promote
+     * a `*Uuid` sibling exactly when their bare title would not resolve back — the
+     * JSON round-trip law. Build one per response emission (the memo is scoped to
+     * that one shaping pass).
+     */
+    refPromoter(): RefPromoter;
     read: {
         /**
-         * The Today list (Today + This Evening split) with the sidebar badge,
-         * bounded to `limit` rows (default 50) counted in render order — Today
-         * first, then This Evening. `all`/`limit: null` returns every row; the
-         * `truncation` metadata carries the per-section (`today`/`evening`) counts.
+         * The Today list — one flat `items[]` of Today members (Today-proper and
+         * This-Evening interleaved in comparator order, each row's `when` carrying
+         * which) plus the whole-view `counts` aggregate, bounded to `limit` rows
+         * (default 50). `all`/`limit: null` returns every row; the `truncation`
+         * metadata carries the per-render-section (`today`/`evening`) counts.
          */
-        today(options?: TodayFilter & ListBound & ClockScopedRead): BoundedTodayView;
+        today(options?: TodayFilter & ListBound & ClockScopedRead & AreaScopedRead): BoundedTodayView;
         /** Inbox captures, bounded (default 50). */
         inbox(options?: InboxFilter & ListBound & ClockScopedRead): BoundedList<ListItem>;
         /**
          * Anytime catalogue: every area header and project row is always present;
          * `areaLimit` (default 30) caps each area/loose block, `projectLimit`
-         * (default 3) each project block. `all` lifts both.
+         * (default 3) each project block. `all` lifts both. `area` restricts the
+         * catalogue to one area (its rows survive; the rest drop).
          */
-        anytime(options?: ViewFilter & GroupedBound & ClockScopedRead): BoundedSectionsView;
+        anytime(options?: ViewFilter & GroupedBound & ClockScopedRead & AreaScopedRead): BoundedSectionsView;
         /** Future-scheduled items in date order, bounded (default 50). */
-        upcoming(options?: UpcomingFilter & ListBound & ClockScopedRead): BoundedList<ListItem>;
+        upcoming(options?: UpcomingFilter & ListBound & ClockScopedRead & AreaScopedRead): BoundedList<ListItem>;
         /**
          * Someday catalogue: `areaLimit` (default 30) caps each group; with
          * `activeProjectItems`, `projectLimit` (default: every item) caps each
-         * active project's trailing child list. `all` lifts both.
+         * active project's trailing child list. `all` lifts both. `area` restricts
+         * the catalogue to one area.
          */
-        someday(options?: SomedayFilter & GroupedBound & ClockScopedRead): BoundedSectionsView;
+        someday(options?: SomedayFilter & GroupedBound & ClockScopedRead & AreaScopedRead): BoundedSectionsView;
         /** Logbook entries (most recent first), bounded (default 50). */
         logbook(options?: Omit<LogbookFilter, "limit"> & ListBound & ClockScopedRead): BoundedList<ListItem>;
         /** Trashed items (most recently modified first), bounded (default 50). */
@@ -216,6 +286,23 @@ export interface ThingsClient {
         cancelTodo(uuid: string, options?: WriteOptions): Promise<MutationResult>;
         reopenTodo(uuid: string, options?: WriteOptions): Promise<MutationResult>;
         moveTodo(uuid: string, dest: Omit<TodoMoveParams, "uuid">, options?: WriteOptions): Promise<MutationResult>;
+        /**
+         * Move one or more to-dos as an ordered block (spec §4). Give a destination
+         * (--to-project / --to-heading / --to-area / --no-heading / --loose) and an
+         * optional position (first/last/before/after), or a position alone to
+         * reposition items already sharing a container. Membership always succeeds;
+         * placement is guaranteed top-of-bucket only where a reorder protocol exists
+         * (the result states the placement class). Compiles onto the todo.move +
+         * reorder wire primitives — no new op kind.
+         */
+        moveTodos(request: TodoMoveRequest, options?: WriteOptions): Promise<MoveResult>;
+        /**
+         * Reorder to-dos IN PLACE within their shared container+bucket (spec §4).
+         * Bare (no position) assembles the movees as a contiguous block at the
+         * earliest movee's current slot, in argument order. Cross-container operands
+         * fail closed.
+         */
+        reorderTodos(request: ReorderRequest, options?: WriteOptions): Promise<MoveResult>;
         /** Replace the full tag set (an empty list clears all tags). */
         setTags(uuid: string, tags: string[], options?: WriteOptions): Promise<MutationResult>;
         /** Merge: current direct tags + new ones, then replace. */
@@ -248,11 +335,43 @@ export interface ThingsClient {
         /**
          * 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).
+         * `things setup shortcuts` once first). A `placement` positions the new
+         * heading among the project's headings via a native `move-heading` leg
+         * (requires allow-experimental); omitted, it appends. Anchor uuids in the
+         * placement are resolved by the caller.
          */
-        createHeading(project: ContainerRef, title: string, options?: WriteOptions): Promise<MutationResult>;
+        addHeading(project: ContainerRef, title: string, placement?: HeadingPlacement, options?: WriteOptions): Promise<MutationResult>;
         /** Rename a heading in place (works on archived headings too). */
         renameHeading(uuid: string, title: string, options?: WriteOptions): Promise<MutationResult>;
+        /**
+         * Reposition one or more of a project's headings as an ordered block
+         * (selection order = resulting order; children follow). `headings` and the
+         * placement anchors are resolved heading uuids. Native reorder wire
+         * (requires allow-experimental).
+         */
+        moveHeading(project: ContainerRef, headings: string[], placement: HeadingPlacement, options?: WriteOptions): Promise<MutationResult>;
+        /**
+         * Relocate ONE heading (with its children) to a DIFFERENT project — the
+         * cross-project move the within-project `moveHeading` reorder cannot express
+         * (HEADXPROJ). GUI-only: drives the heading row's `…` ellipsis → Move… →
+         * keyboard-driven project picker, so it needs `ui.enabled` + the
+         * `dangerouslyDriveGui` acknowledgement. `heading` is an exact title or uuid
+         * within `project`; both same-titled source headings AND a same-titled
+         * destination project fail closed (the drive addresses by title). No wired
+         * undo — it is app-reversible by moving it back.
+         */
+        moveHeadingToProject(project: ContainerRef, heading: string, toProject: ContainerRef, options?: WriteOptions): Promise<MutationResult>;
+        /**
+         * Dissolve a heading: remove it while its to-dos SURVIVE as direct children
+         * of the project (heading→NULL, keeping their order) — NOT trashed (DISS1).
+         * This is the OPPOSITE of a delete cascade (contrast the Shortcuts heading
+         * delete, P12, which trashes the children). GUI-only (heading row's `…`
+         * ellipsis → Delete), so it needs `ui.enabled` + `dangerouslyDriveGui`. Fails
+         * closed on a title shared by another heading in the project. No wired undo —
+         * the children are kept, so re-create the heading and move them back to
+         * reverse. `uuid` is the heading.
+         */
+        dissolveHeading(uuid: string, options?: WriteOptions): Promise<MutationResult>;
         /**
          * Archive a heading (the UI's Archive — it leaves the active project
          * view, reversibly). With open children the policy is mandatory:
@@ -278,6 +397,14 @@ export interface ThingsClient {
         moveProject(uuid: string, area: ContainerRef, options?: WriteOptions): Promise<MutationResult>;
         /** Detach a project from its current area. */
         detachProject(uuid: string, options?: WriteOptions): Promise<MutationResult>;
+        /**
+         * Move one or more projects as an ordered block (spec §4/§5): --to-area, or
+         * --no-area to leave the area, plus an optional position — or a position
+         * alone to reorder them among their siblings.
+         */
+        moveProjects(request: ProjectMoveRequest, options?: WriteOptions): Promise<MoveResult>;
+        /** Reorder projects IN PLACE among their siblings (spec §4). */
+        reorderProjects(request: ReorderRequest, options?: WriteOptions): Promise<MoveResult>;
         /** Cancel a project — open children are canceled with it, so the children policy is mandatory. */
         cancelProject(uuid: string, policy: Pick<ProjectCancelParams, "children">, options?: WriteOptions): Promise<MutationResult>;
         /**
@@ -307,7 +434,7 @@ export interface ThingsClient {
          * two-key gated, same as makeRepeatingProject). Give an `area` to place it,
          * or omit it to create in Someday. The new template's uuid is on the result.
          */
-        createRepeatingProject(params: ProjectCreateRepeatingParams, options?: WriteOptions): Promise<MutationResult>;
+        addRepeatingProject(params: ProjectAddRepeatingParams, options?: WriteOptions): Promise<MutationResult>;
         /** Replace a project's full tag set (an empty list clears all tags). */
         setProjectTags(uuid: string, tags: string[], options?: WriteOptions): Promise<MutationResult>;
         /** Merge: current project tags + new ones, then replace. */
@@ -326,9 +453,14 @@ export interface ThingsClient {
         reorder(params: ReorderParams, options?: WriteOptions): Promise<ReorderResult>;
         /**
          * Run N ops sequentially and independently — no transactions, a failure
-         * does not roll back earlier ops. Per-op results.
+         * does not roll back earlier ops. Per-op results stream through `onResult`;
+         * the resolved {@link BatchResult} adds the temp-id → uuid mapping and the
+         * batch-level undo token (undo the whole submission as one unit). An op may
+         * carry a `tempId` (a handle bound to its created uuid, referenceable as
+         * `"$name"` by a later op) and/or an `opId` (idempotency id — a resubmitted
+         * op with a matching applied id is skipped, not re-created).
          */
-        batch(ops: BatchOp[], options?: BatchOptions, onResult?: (result: BatchItemResult) => void): Promise<BatchItemResult[]>;
+        batch(ops: BatchOp[], options?: BatchOptions, onResult?: (result: BatchItemResult) => void): Promise<BatchResult>;
         /**
          * Undo changes made through this client, newest first, by applying the
          * inverse change. Selection: `last` trailing changes (default 1), narrowed