things-api 0.10.0 → 0.12.0

package/dist/read/scope.js

@@ -0,0 +1,162 @@
+import { EFFECTIVE_AREA, ReferenceResolutionError, resolveAreaUuid, resolveProjectUuid, } from "./queries.js";
+/**
+ * Fail-closed if a requested scope is unresolvable — `things mcp --scope <bogus>`
+ * refuses to start, a CLI invocation errors as usage — so the daemon never runs
+ * unscoped when a scope was asked for. A subclass of {@link ReferenceResolutionError}
+ * so existing usage-class handlers treat it uniformly.
+ */
+export class ScopeResolutionError extends ReferenceResolutionError {
+    constructor(message, ref) {
+        super(message, { code: "not-found", ref });
+        this.name = "ScopeResolutionError";
+    }
+}
+/**
+ * Resolve a scope ref (uuid, uuid-prefix, or unique area/project name) to a
+ * pinned {@link ResolvedScope}. Areas win over same-named projects (mirroring
+ * `classifyShowTarget`). A to-do / heading / tag ref is a usage error — only an
+ * area or a project can be a container. Fail-closed: an unresolvable ref throws
+ * {@link ScopeResolutionError}.
+ */
+export function resolveScope(db, ref, source) {
+    // Area first (an area outranks a same-named project, like the show router).
+    try {
+        const uuid = resolveAreaUuid(db, ref, { prefixTier: false });
+        const row = db.prepare("SELECT title FROM TMArea WHERE uuid = ?").get(uuid);
+        return { kind: "area", uuid, title: row?.title ?? "", source, areaUuid: uuid };
+    }
+    catch (err) {
+        // An ambiguous area name is a real conflict — surface it. A plain not-found
+        // falls through to project resolution.
+        if (err instanceof RangeError && err.message.includes("matches")) {
+            throw new ScopeResolutionError(`scope "${ref}" is ambiguous — ${err.message}`, ref);
+        }
+    }
+    try {
+        const uuid = resolveProjectUuid(db, ref, { prefixTier: false });
+        const row = db.prepare("SELECT title, area FROM TMTask WHERE uuid = ?").get(uuid);
+        return {
+            kind: "project",
+            uuid,
+            title: row?.title ?? "",
+            source,
+            areaUuid: row?.area ?? null,
+        };
+    }
+    catch (err) {
+        if (err instanceof RangeError && err.message.includes("matches")) {
+            throw new ScopeResolutionError(`scope "${ref}" is ambiguous — ${err.message}`, ref);
+        }
+    }
+    throw new ScopeResolutionError(`scope "${ref}" matches no area or project — a scope must name a container (only areas and ` +
+        "projects can be a container; to-dos, headings, and tags cannot)", ref);
+}
+/** The `meta.scope` projection of a resolved scope (drops the internal `areaUuid`). */
+export function scopeMeta(scope) {
+    return { kind: scope.kind, uuid: scope.uuid, title: scope.title, source: scope.source };
+}
+/**
+ * The entity-level membership predicate — the SAME relation as
+ * {@link scopeMembershipSql}, for an already-shaped view row. Area scope: the
+ * row's EFFECTIVE area is the scope (its `area` Ref, which queries.ts already
+ * resolves transitively). Project scope: the row IS the project, is a direct
+ * child, or is nested under one of the project's headings.
+ */
+export function inScopeItem(item, scope) {
+    if (scope.kind === "area") {
+        const area = "area" in item ? item.area : null;
+        return area != null && area.uuid === scope.uuid;
+    }
+    const p = scope.uuid;
+    if (item.uuid === p)
+        return true;
+    const project = "project" in item ? item.project : null;
+    if (project != null && project.uuid === p)
+        return true;
+    const hp = "headingProject" in item ? item.headingProject : undefined;
+    if (hp != null && hp.uuid === p)
+        return true;
+    return false;
+}
+/**
+ * The SQL fragment on alias `t` — the single membership source the leak-critical
+ * query paths AND the write ancestry check share. Area: the effective-area
+ * COALESCE equals the scope. Project: the row is the project, its direct child,
+ * or a heading-nested child.
+ */
+export function scopeMembershipSql(scope) {
+    if (scope.kind === "area") {
+        return { where: `${EFFECTIVE_AREA} = ?`, binds: [scope.uuid] };
+    }
+    return {
+        where: "(t.uuid = ? OR t.project = ? OR t.heading IN " +
+            "(SELECT uuid FROM TMTask WHERE type = 2 AND project = ?))",
+        binds: [scope.uuid, scope.uuid, scope.uuid],
+    };
+}
+/** True when the given uuid is an in-scope TMTask row (single-row leak paths, write parity). */
+export function isUuidInScope(db, uuid, scope) {
+    const mem = scopeMembershipSql(scope);
+    const row = db
+        .prepare(`SELECT 1 AS ok FROM TMTask t WHERE t.uuid = ? AND ${mem.where} LIMIT 1`)
+        .get(uuid, ...mem.binds);
+    return row !== undefined;
+}
+/**
+ * The membership clause for {@link resolveTaskUuidPrefix} (alias `t`): the same
+ * fragment as {@link scopeMembershipSql}, so an out-of-scope uuid resolves to
+ * "not found" through the identical code path a nonexistent one does.
+ */
+export function taskMembershipClause(scope) {
+    return scopeMembershipSql(scope);
+}
+/**
+ * The membership clause for {@link resolveNamedRef} over TMTask projects
+ * (UNqualified columns — that resolver aliases nothing). A project carries its
+ * area directly (no inheritance), so area scope compares `area`; project scope
+ * pins the one project uuid.
+ */
+export function namedProjectClause(scope) {
+    if (scope.kind === "area")
+        return { where: "area = ?", binds: [scope.uuid] };
+    return { where: "uuid = ?", binds: [scope.uuid] };
+}
+/**
+ * The membership clause for {@link resolveNamedRef} over TMArea (UNqualified).
+ * Area scope: the one scope area. Project scope: the project's own area (an
+ * area-less project has none, so nothing resolves — `0`).
+ */
+export function namedAreaClause(scope) {
+    if (scope.kind === "area")
+        return { where: "uuid = ?", binds: [scope.uuid] };
+    return scope.areaUuid === null
+        ? { where: "0", binds: [] }
+        : { where: "uuid = ?", binds: [scope.areaUuid] };
+}
+/** Filter a flat view (upcoming/logbook/trash/search/changes) to in-scope rows. */
+export function filterListByScope(items, scope) {
+    return items.filter((i) => inScopeItem(i, scope));
+}
+/**
+ * Filter the grouped sidebar catalogue (anytime/someday) to in-scope rows: each
+ * section's items are filtered and empty sections drop, so the per-block caps
+ * size the survivors.
+ */
+export function filterSectionsByScope(sections, scope) {
+    return sections
+        .map((s) => ({ area: s.area, items: s.items.filter((i) => inScopeItem(i, scope)) }))
+        .filter((s) => s.items.length > 0);
+}
+/**
+ * Filter the Today split to in-scope rows, RECOMPUTING the badge over the
+ * surviving OPEN members so it never counts a dropped (out-of-scope) row — the
+ * same treatment `filterTodayByArea` gives the area filter.
+ */
+export function filterTodayByScope(view, scope, todayIso) {
+    const today = view.today.filter((i) => inScopeItem(i, scope));
+    const evening = view.evening.filter((i) => inScopeItem(i, scope));
+    const open = [...today, ...evening].filter((i) => i.status === "open");
+    const dueOrOverdue = open.filter((i) => i.deadline !== null && i.deadline <= todayIso).length;
+    return { today, evening, badge: { dueOrOverdue, other: open.length - dueOrOverdue } };
+}
+//# sourceMappingURL=scope.js.map

package/dist/read/scope.js.map

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

package/dist/read/search-rank.d.ts

@@ -18,12 +18,9 @@ import type { ListItem } from "./views.ts";
 export type MatchField = "title" | "notes" | "heading" | "checklist";
 export interface SearchMatch {
     item: ListItem;
+    /** The RANK field (strongest match by rank order); the displayed provenance
+     * annotation rides the item as `match` and follows its own precedence. */
     field: MatchField;
-    /** Present when `field === "heading"`: the heading whose title matched. */
-    matchedVia?: {
-        kind: "heading";
-        title: string;
-    };
 }
 export declare function fieldRank(field: MatchField): number;
 /** Containers (projects, areas) sort above to-dos. */

package/dist/read/shape.d.ts

@@ -0,0 +1,162 @@
+/**
+ * The read-payload SHAPING transform: the token-economy rules R6 and R7, the
+ * universal item-DTO reshapes (R9), and the R10 lifecycle taxonomy — applied at
+ * the JSON emit boundary of the read surfaces (the CLI `--json` read envelope,
+ * src/cli/read-driver.ts, and the MCP read tool results, src/mcp/server.ts), the
+ * same boundaries omit-empty runs at. Shaping runs BEFORE omit-empty. The
+ * human-render path keeps the full, unshaped entities, so this is JSON-only.
+ *
+ * Both R6/R7 are deterministic BY VIEW KIND / SECTION — the emitter knows whether
+ * it is inside a single-container view, a lifecycle bucket, or a mixed list —
+ * never a per-item heuristic.
+ *
+ * ## R10 — the `stage` lifecycle taxonomy (every tier, every kind incl. detail)
+ * The three former wire fields `start` / `logged` / `trashed` are DELETED from
+ * every item and replaced by ONE derived `stage` ∈ `inbox | upcoming | anytime |
+ * someday | logbook | trash` (src/read/stage.ts `deriveStage`, the single pure
+ * derivation reused by the card bucketing so `stage` can never disagree with the
+ * bucket a view puts an item in). Today/evening membership is a SEPARATE
+ * presence-keyed axis — `today: true` / `evening: true` (evening implies today) —
+ * derived in the mapper with the Today view's own two-arm predicate.
+ * - `stage` is DROPPED only where the enclosing node PROVABLY states it — the R6
+ *   rule (drop only what the node provably says). That is the stage-PURE flat
+ *   views (inbox, `anytime`, someday, logbook, trash) and the stage-named card
+ *   sub-buckets (anytime/upcoming/someday/logbook/trash, which the bucketer splits
+ *   BY stage). The `anytime` catalogue is stage-PURE (R10.2): every member is an
+ *   Anytime-view row (ANYTIME_SELF) — undated-active, arrived-active, or arrived
+ *   someday-scheduled — and an ARRIVED dated row derives `anytime` (Upcoming is
+ *   STRICTLY FUTURE, UPC1), so the field is redundant there.
+ *   `stage` is KEPT on the stage-MIXED or derived surfaces: the `upcoming` view
+ *   carries deadline-forecast stage-`anytime`/`someday` rows alongside its
+ *   future-dated stage-`upcoming` ones — dropping `stage` there would delete
+ *   non-redundant information — plus `today` (mixes upcoming + anytime-deadline
+ *   rows), search, changes, the projects/areas listings, the card NODE, and
+ *   detail.
+ * - the former `todaySection` field is RETIRED from the wire entirely (R10.1):
+ *   `todaySection: "evening"` merely duplicated the `evening: true` marker. It
+ *   remains an internal entity field (the human render and the write-verify delta
+ *   still read it); shaping deletes it from the JSON copy.
+ *
+ * ## R12 — `when`, the derived TIME-AXIS position (replaces startDate + markers)
+ * Today/evening membership and the scheduled/projected date collapse onto ONE
+ * derived, presence-keyed field `when` (src/read/stage.ts `deriveWhen`): `"today"`
+ * / `"evening"` (Today-view membership, from the SAME `today`/`evening` markers the
+ * mapper stamps — never re-derived, so `when` can never disagree with the star), a
+ * FUTURE ISO date (a strictly-future scheduled row, or a template's projected next
+ * occurrence), or absent (unscheduled + not in Today; also an unprojected template
+ * and every logged/trashed row). The doctrine line: **`stage` enumerates the
+ * sidebar BUCKETS an item lives in; `when` enumerates its TIME POSITIONS (today |
+ * evening | a future date).** Someday is deliberately NOT a `when` value (it is a
+ * bucket → stage). Tier/drop rules:
+ * - the former `today`/`evening` marker KEYS are DELETED from the wire on EVERY
+ *   tier — `when` carries the fact; the markers stay internal (they feed `when`).
+ * - the raw `startDate` is DELETED in COMPACT (a list needs the position, not the
+ *   substrate) and KEPT in FULL/DETAIL beside `when` — different facts: `startDate`
+ *   = what is stored, `when` = where it sits.
+ * - a template's `repeating.nextOccurrence` is GONE from the wire — `when` replaces
+ *   it (same fact, one word); the resting-templates `{date: null}` group is
+ *   unchanged (an unprojected template has no `when`).
+ * - `when` is DROPPED inside the `today` view's own sections (the section key states
+ *   today/evening) and inside any card/heading `upcoming` DATE-GROUP for a member
+ *   whose `when` equals the group's date (the group states it). KEPT everywhere
+ *   else it is present — including the flat `upcoming`/`anytime`/`inbox`/`someday`
+ *   catalogues, search, changes (a deadline-pulled row reads `when: "today"` in the
+ *   mixed search/changes surfaces, informatively; note R13 re-files it to stage
+ *   `anytime` and the flat inbox/someday views now EXCLUDE it — it appears in the
+ *   `anytime` catalogue instead, `when: "today"` kept, stage dropped as pure).
+ *
+ * ## R13 — provisional Today members + GUI-faithful pulled-row membership
+ * BANNER1 / BANNER1b (docs/lab/banner1-research.md). Two coupled facts:
+ * - **`provisional: true`** — a presence-keyed marker on every Today member the GUI
+ *   pips / counts in the "You have N new to-dos" banner: a Today member NOT yet
+ *   materialized (`start != active OR startDate IS NULL`, BANNER1 L1). Derived from
+ *   the SAME today/evening markers + fields the stage/`when` axes use (never
+ *   re-derived). Emitted on EVERY tier, NEVER dropped (the banner is not a section,
+ *   so no node implies it). Absent on non-Today rows and on materialized ones.
+ *   Read-only: the app clears it by materializing the row on banner-OK, a GUI-only
+ *   side effect our read cannot perform (watchers beware).
+ * - **stage `anytime` for a deadline pull** — a due-deadline pull re-files an undated
+ *   Inbox/Someday row into Anytime (deriveStage step 2½, L-A). So EVERY Today member
+ *   derives stage `anytime`, and the `today` view's own sections become stage-PURE →
+ *   `stage` is DROPPED there (TODAY_SECTION_DROP), alongside the section-implied
+ *   `when`. The flat someday/inbox views EXCLUDE pulled rows and the anytime view
+ *   INCLUDES them (src/read/views.ts + predicates.ts DEADLINE_PULLED) — GUI fidelity.
+ *
+ * ## Universal item-DTO reshapes (R9 — EVERY tier, EVERY read kind incl. detail)
+ * - **checklist nesting** — flat counts → presence-keyed `checklist: {open,total}`.
+ * - **todos counts** — a project's flat leaf-action counts → presence-keyed
+ *   `todos: {open, total}` (omit when total 0).
+ * - **repeating template/instance split (R11)** — the wire drops the
+ *   `isTemplate`/`isInstance` discriminators; key presence carries the fact. A
+ *   TEMPLATE keeps a nested `repeating: {paused?, deadlined?, rule?,
+ *   latestInstance?}` — the series object (rule config + backward pointer +
+ *   state flags); presence MEANS template. The forward pointer `nextOccurrence`
+ *   moved to the top-level `when` (R12 — a template's projected date IS its time
+ *   position); `latestInstance` is detail-only (SL1). An INSTANCE keeps a flat
+ *   `instanceOf: <templateUuid>` and no `repeating`. A plain row keeps neither.
+ *   See {@link reshapeRepeatingWire}.
+ * - **string tags** — `tags`/`inheritedTags` become plain arrays of names.
+ * - **one project key** — a headed item's owning project (formerly
+ *   `headingProject`) is merged into `project`; `headingProject` never appears.
+ *
+ * ## R6 — no-redundant-ancestry (both tiers)
+ * project-view children drop `project`+`area` (heading-group members also drop
+ * `heading`); area-view children/project-cards drop `area`; anytime/someday
+ * section items drop `area`. Mixed lists keep every ref. (In the COMPACT tier the
+ * `heading` ref is additionally dropped everywhere — R7.)
+ *
+ * ## R7 — named detail tiers (compact | full)
+ * List contexts default to COMPACT; `detail`/`show` and `--full` / `full:true`
+ * use FULL. Compact drops `created`/`modified`, the full `notes` string (a
+ * presence-keyed `hasNotes: true` marks a row with notes), and the `heading` ref;
+ * `status` is omitted when `open`. FULL keeps them but still applies R6, the
+ * universal reshapes, and R10.
+ */
+import { type Stage, type When } from "./stage.ts";
+/**
+ * Apply the universal reshapes + R6 + R7 + R10 to a read payload for one view
+ * `kind`. `full` forces the FULL tier (R7 default-pruning off, everything else
+ * applied); an unrecognized kind passes through unchanged. The input is never
+ * mutated (shallow copies throughout), so the human-render path keeps the full
+ * entities.
+ */
+export declare function shapeReadPayload(kind: string, data: unknown, full: boolean): unknown;
+/** The disambiguation-candidate kinds an error may list (a subset of the entity kinds). */
+export type CandidateType = "to-do" | "project" | "heading" | "area" | "tag";
+/**
+ * The ONE fixed error-candidate shape — the presence-keyed disambiguation DTO a
+ * not-found / ambiguous resolution lists under `error.detail.candidates` (and the
+ * did-you-mean fallback under the same key). Deliberately minimal and INVARIANT
+ * across request flags: `--full` / `--all` / etc. NEVER widen it, because an
+ * error payload is the most determinism-critical surface. A candidate carries
+ * ONLY material that helps a caller pick the right entity, drawn from the SAME
+ * single-source derivations the read wire uses — never the raw internal entity
+ * (no counts, no notes, no dates, no null-stuffed keys):
+ * - `uuid` / `title` / `type` — always present (`type` names the kind).
+ * - `area` / `project` — container hint as a TITLE string, present only when set.
+ * - `stage` / `when` — the R10/R12 lifecycle words, present only for a to-do /
+ *   project candidate whose source row carries the materialized lifecycle fields
+ *   (a thin uuid+title resolver row carries neither — presence-keyed, so absent).
+ * A trashed / logged candidate needs no boolean: `stage` already reads `"trash"`
+ * / `"logbook"` for it — the same vocabulary the wire uses.
+ */
+export interface CandidateRef {
+    uuid: string;
+    title: string;
+    type: CandidateType;
+    area?: string;
+    project?: string;
+    stage?: Stage;
+    when?: When;
+}
+/** The fixed cap on a listed candidate array; the error `message` states the total when it overflows. */
+export declare const CANDIDATE_CAP = 8;
+/**
+ * Project ONE entity — a materialized to-do/project/area/heading, or a thin
+ * `{uuid, title}` resolver row — to the fixed {@link CandidateRef}. The SINGLE
+ * source every error-candidate emit flows through (the did-you-mean fallback and
+ * every not-found/ambiguous resolver), so the candidate shape can never vary by
+ * site. Reuses the wire's own {@link stageOf}/{@link whenOf} derivations — the
+ * lifecycle words are never re-derived here.
+ */
+export declare function candidateRef(type: CandidateType, src: unknown): CandidateRef;