things-api 0.5.0

package/dist/model/occurrences.js

@@ -0,0 +1,164 @@
+/** Hard cap on calendar cells examined — a runaway-rule backstop. */
+const MAX_ITERATIONS = 1000;
+// ------------------------------------------------------------ date helpers
+// UTC-midnight arithmetic: IsoDate ↔ epoch days, no timezone hazards.
+function toUtc(iso) {
+    return new Date(`${iso}T00:00:00Z`);
+}
+function toIso(d) {
+    return d.toISOString().slice(0, 10);
+}
+function addDays(iso, days) {
+    const d = toUtc(iso);
+    d.setUTCDate(d.getUTCDate() + days);
+    return toIso(d);
+}
+function weekdayOf(iso) {
+    return toUtc(iso).getUTCDay(); // 0 = Sunday, matching the rule encoding
+}
+function lastDayOfMonth(year, month1) {
+    return new Date(Date.UTC(year, month1, 0)).getUTCDate();
+}
+function isoFor(year, month1, day) {
+    return `${String(year).padStart(4, "0")}-${String(month1).padStart(2, "0")}-${String(day).padStart(2, "0")}`;
+}
+/** Resolve a monthly/yearly day offset within a month; null = no such date. */
+function dayInMonth(year, month1, offset) {
+    const last = lastDayOfMonth(year, month1);
+    if (offset.weekday !== undefined) {
+        // nth weekday (weekdayOrdinal 1..5, -1 = last)
+        const ordinal = offset.weekdayOrdinal ?? 1;
+        if (ordinal === -1) {
+            for (let day = last; day >= last - 6; day--) {
+                const iso = isoFor(year, month1, day);
+                if (weekdayOf(iso) === offset.weekday)
+                    return iso;
+            }
+            return null;
+        }
+        const firstWeekday = weekdayOf(isoFor(year, month1, 1));
+        const day = 1 + ((offset.weekday - firstWeekday + 7) % 7) + (ordinal - 1) * 7;
+        return day <= last ? isoFor(year, month1, day) : null; // missing 5th → skip
+    }
+    const day = offset.day ?? 1;
+    if (day === -1)
+        return isoFor(year, month1, last);
+    return isoFor(year, month1, Math.min(day, last)); // clamp (see header)
+}
+// ------------------------------------------------------------- generation
+/**
+ * Event dates of a FIXED rule from `anchor` (an app-materialized event date,
+ * INCLUDED as the first result), honoring the rule's endDate/remainingCount
+ * bounds and the window's count/until. Throws on after-completion rules.
+ */
+export function generateEventDates(rule, anchor, window) {
+    if (rule.type !== "fixed") {
+        throw new RangeError("after-completion rules cannot be projected — the next date depends on when the " +
+            "prior instance resolves");
+    }
+    // remainingCount counts occurrences the rule will still produce; the
+    // anchor is the first of them.
+    const cap = Math.min(Math.max(1, window.count), rule.remainingCount === null ? Number.POSITIVE_INFINITY : rule.remainingCount);
+    const inBounds = (iso) => (window.until === undefined || iso <= window.until) &&
+        (rule.endDate === null || iso <= rule.endDate);
+    // Every unit generates in ascending date order, so the first out-of-bounds
+    // date terminates the walk. Returns "keep generating".
+    const out = [];
+    const push = (iso) => {
+        if (iso < anchor)
+            return true; // pre-anchor cell (same week/month) — skip
+        if (!inBounds(iso))
+            return false; // past until/endDate — done
+        if (out.at(-1) !== iso)
+            out.push(iso);
+        return out.length < cap;
+    };
+    switch (rule.unit) {
+        case "daily": {
+            let date = anchor;
+            for (let i = 0; i < MAX_ITERATIONS; i++) {
+                if (!push(date))
+                    break;
+                date = addDays(date, rule.interval);
+            }
+            break;
+        }
+        case "weekly": {
+            const weekdays = [
+                ...new Set(rule.offsets
+                    .map((o) => o.weekday)
+                    .filter((w) => w !== undefined)
+                    .toSorted((a, b) => a - b)),
+            ];
+            const days = weekdays.length > 0 ? weekdays : [weekdayOf(anchor)];
+            const cohortStart = addDays(anchor, -weekdayOf(anchor)); // Sunday of the anchor's week
+            outer: for (let week = 0; week < MAX_ITERATIONS; week++) {
+                const weekStart = addDays(cohortStart, week * rule.interval * 7);
+                for (const wd of days) {
+                    if (!push(addDays(weekStart, wd)))
+                        break outer;
+                }
+            }
+            break;
+        }
+        case "monthly": {
+            const offsets = rule.offsets.length > 0
+                ? rule.offsets
+                : [{ day: Number(anchor.slice(8, 10)) }];
+            const anchorYear = Number(anchor.slice(0, 4));
+            const anchorMonth = Number(anchor.slice(5, 7));
+            outer: for (let step = 0; step < MAX_ITERATIONS; step++) {
+                const monthIndex = anchorMonth - 1 + step * rule.interval;
+                const year = anchorYear + Math.floor(monthIndex / 12);
+                const month1 = (monthIndex % 12) + 1;
+                const dates = offsets
+                    .map((o) => dayInMonth(year, month1, o))
+                    .filter((d) => d !== null)
+                    .toSorted();
+                for (const date of dates) {
+                    if (!push(date))
+                        break outer;
+                }
+            }
+            break;
+        }
+        case "yearly": {
+            const offsets = rule.offsets.length > 0
+                ? rule.offsets
+                : [
+                    {
+                        month: Number(anchor.slice(5, 7)),
+                        day: Number(anchor.slice(8, 10)),
+                    },
+                ];
+            const anchorYear = Number(anchor.slice(0, 4));
+            outer: for (let step = 0; step < MAX_ITERATIONS; step++) {
+                const year = anchorYear + step * rule.interval;
+                const dates = offsets
+                    .map((o) => dayInMonth(year, o.month ?? Number(anchor.slice(5, 7)), o))
+                    .filter((d) => d !== null)
+                    .toSorted();
+                for (const date of dates) {
+                    if (!push(date))
+                        break outer;
+                }
+            }
+            break;
+        }
+    }
+    return out;
+}
+/**
+ * Project a template's next occurrences in INSTANCE terms. The anchor is the
+ * app-materialized next instance START date (rt1_nextInstanceStartDate);
+ * the rule's ts offset splits each event into startDate/deadline exactly as
+ * the app does when spawning (deadline = start − ts, validated live).
+ */
+export function projectOccurrences(rule, nextInstanceStartDate, window) {
+    const anchorEvent = addDays(nextInstanceStartDate, -rule.startOffsetDays);
+    return generateEventDates(rule, anchorEvent, window).map((event) => ({
+        startDate: addDays(event, rule.startOffsetDays),
+        deadline: rule.startOffsetDays < 0 ? event : null,
+    }));
+}
+//# sourceMappingURL=occurrences.js.map

package/dist/model/occurrences.js.map

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

package/dist/model/recurrence.d.ts

@@ -0,0 +1,52 @@
+/**
+ * READ-ONLY decoder for TMTask.rt1_recurrenceRule — an XML plist Things
+ * writes for repeating templates. NEVER serialized or written back (repeat
+ * rules are UI-only; see docs/gaps.md). Semantics reverse-engineered from a
+ * 91-rule live corpus and cross-validated against the app's own spawned
+ * instances (deadline = startDate − ts held on every sample, 2026-07-04):
+ *
+ *   tp  0 fixed schedule · 1 after-completion
+ *   fu  16 daily · 256 weekly · 8 monthly · 4 yearly
+ *   fa  interval multiplier ("every fa units")
+ *   ts  start offset in days relative to the event date (≤0 = start early;
+ *       the event date becomes the spawned instance's DEADLINE when ts<0)
+ *   of  occurrence offsets: dy (0-based day; -1 = last day of month),
+ *       mo (0-based month), wd (weekday, 0=Sunday), wdo (nth weekday, -1=last)
+ *   ed  end date (unix seconds; distant-future sentinel = no end)
+ *   rc  remaining repeat count (0 = unlimited)
+ *   rrv rule schema version (4 observed)
+ *   sr/ia anchor timestamps (not needed for reads)
+ */
+import type { IsoDate } from "./dates.ts";
+export interface RepeatOffset {
+    /** 1-based day of month; -1 = last day. */
+    day?: number;
+    /** 1-based month. */
+    month?: number;
+    /** Weekday, 0 = Sunday … 6 = Saturday. */
+    weekday?: number;
+    /** Nth weekday within the month (1..5), -1 = last. */
+    weekdayOrdinal?: number;
+}
+export interface RepeatRule {
+    type: "fixed" | "after-completion";
+    unit: "daily" | "weekly" | "monthly" | "yearly";
+    interval: number;
+    /** Days the instance's start precedes its event date (≤ 0). */
+    startOffsetDays: number;
+    offsets: RepeatOffset[];
+    endDate: IsoDate | null;
+    remainingCount: number | null;
+    version: number;
+}
+export declare function decodeRecurrenceRule(blob: unknown): RepeatRule;
+type PlistValue = number | string | boolean | PlistValue[] | {
+    [key: string]: PlistValue;
+};
+/**
+ * Parses the machine-generated plist subset Things emits (dict/array/
+ * integer/real/string/true/false). Deliberately tiny — not a general XML
+ * parser; unknown node kinds fail loudly.
+ */
+export declare function parsePlist(xml: string): PlistValue;
+export {};

package/dist/model/recurrence.js

@@ -0,0 +1,164 @@
+const UNITS = {
+    16: "daily",
+    256: "weekly",
+    8: "monthly",
+    4: "yearly",
+};
+/** Unix seconds this far out (year ≥ 3000) mean "repeats forever". */
+const DISTANT_FUTURE_EPOCH = 32503680000;
+export function decodeRecurrenceRule(blob) {
+    const xml = typeof blob === "string"
+        ? blob
+        : blob instanceof Uint8Array
+            ? new TextDecoder().decode(blob)
+            : null;
+    if (xml === null)
+        throw new RangeError("recurrence rule is not an XML blob");
+    const root = parsePlist(xml);
+    if (typeof root !== "object" || root === null || Array.isArray(root)) {
+        throw new RangeError("recurrence rule plist is not a dict");
+    }
+    const dict = root;
+    const tp = num(dict, "tp");
+    const fu = num(dict, "fu");
+    const unit = UNITS[fu];
+    if (unit === undefined)
+        throw new RangeError(`unknown recurrence unit fu=${fu}`);
+    if (tp !== 0 && tp !== 1)
+        throw new RangeError(`unknown recurrence type tp=${tp}`);
+    const offsets = [];
+    const of = dict["of"];
+    if (Array.isArray(of)) {
+        for (const entry of of) {
+            if (typeof entry !== "object" || entry === null || Array.isArray(entry))
+                continue;
+            const e = entry;
+            const offset = {};
+            if (typeof e["dy"] === "number")
+                offset.day = e["dy"] === -1 ? -1 : e["dy"] + 1;
+            if (typeof e["mo"] === "number")
+                offset.month = e["mo"] + 1;
+            if (typeof e["wd"] === "number")
+                offset.weekday = e["wd"];
+            if (typeof e["wdo"] === "number")
+                offset.weekdayOrdinal = e["wdo"];
+            offsets.push(offset);
+        }
+    }
+    const ed = typeof dict["ed"] === "number" ? dict["ed"] : null;
+    const rc = typeof dict["rc"] === "number" ? dict["rc"] : 0;
+    return {
+        type: tp === 0 ? "fixed" : "after-completion",
+        unit,
+        interval: num(dict, "fa"),
+        startOffsetDays: typeof dict["ts"] === "number" ? dict["ts"] : 0,
+        offsets,
+        endDate: ed === null || ed >= DISTANT_FUTURE_EPOCH ? null : epochToIso(ed),
+        remainingCount: rc === 0 ? null : rc,
+        version: typeof dict["rrv"] === "number" ? dict["rrv"] : 0,
+    };
+}
+function num(dict, key) {
+    const v = dict[key];
+    if (typeof v !== "number")
+        throw new RangeError(`recurrence rule missing numeric ${key}`);
+    return v;
+}
+function epochToIso(seconds) {
+    const d = new Date(seconds * 1000);
+    return `${String(d.getUTCFullYear()).padStart(4, "0")}-${String(d.getUTCMonth() + 1).padStart(2, "0")}-${String(d.getUTCDate()).padStart(2, "0")}`;
+}
+/**
+ * Parses the machine-generated plist subset Things emits (dict/array/
+ * integer/real/string/true/false). Deliberately tiny — not a general XML
+ * parser; unknown node kinds fail loudly.
+ */
+export function parsePlist(xml) {
+    const body = /<plist[^>]*>([\s\S]*)<\/plist>/.exec(xml)?.[1];
+    if (body === undefined)
+        throw new RangeError("not a plist document");
+    const parser = new Parser(body);
+    const value = parser.parseValue();
+    parser.skipWs();
+    return value;
+}
+class Parser {
+    pos = 0;
+    s;
+    constructor(s) {
+        this.s = s;
+    }
+    skipWs() {
+        while (this.pos < this.s.length && /\s/.test(this.s[this.pos]))
+            this.pos++;
+    }
+    openTag() {
+        this.skipWs();
+        const m = /^<([a-z]+)\s*(\/)?>/.exec(this.s.slice(this.pos));
+        if (!m)
+            throw new RangeError(`plist parse error at ${this.pos}`);
+        this.pos += m[0].length;
+        return m[2] === "/" ? `${m[1]}/` : m[1];
+    }
+    closeTag(name) {
+        this.skipWs();
+        const expect = `</${name}>`;
+        if (!this.s.startsWith(expect, this.pos)) {
+            throw new RangeError(`plist parse error: expected ${expect} at ${this.pos}`);
+        }
+        this.pos += expect.length;
+    }
+    text(until) {
+        const idx = this.s.indexOf(`</${until}>`, this.pos);
+        if (idx === -1)
+            throw new RangeError(`plist parse error: unterminated <${until}>`);
+        const raw = this.s.slice(this.pos, idx);
+        this.pos = idx + until.length + 3;
+        return raw
+            .replaceAll("&lt;", "<")
+            .replaceAll("&gt;", ">")
+            .replaceAll("&quot;", '"')
+            .replaceAll("&apos;", "'")
+            .replaceAll("&amp;", "&");
+    }
+    peekClose(name) {
+        this.skipWs();
+        return this.s.startsWith(`</${name}>`, this.pos);
+    }
+    parseValue() {
+        const tag = this.openTag();
+        switch (tag) {
+            case "integer":
+            case "real":
+                return Number(this.text(tag));
+            case "string":
+                return this.text(tag);
+            case "true/":
+                return true;
+            case "false/":
+                return false;
+            case "dict": {
+                const dict = {};
+                while (!this.peekClose("dict")) {
+                    const keyTag = this.openTag();
+                    if (keyTag !== "key")
+                        throw new RangeError(`plist parse error: expected <key>`);
+                    const key = this.text("key");
+                    dict[key] = this.parseValue();
+                }
+                this.closeTag("dict");
+                return dict;
+            }
+            case "array": {
+                const arr = [];
+                while (!this.peekClose("array"))
+                    arr.push(this.parseValue());
+                this.closeTag("array");
+                return arr;
+            }
+            default:
+                throw new RangeError(`plist parse error: unsupported node <${tag}>`);
+        }
+    }
+}
+//# sourceMappingURL=recurrence.js.map

package/dist/model/recurrence.js.map

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

package/dist/paths.d.ts

@@ -0,0 +1,6 @@
+export declare function stateDir(env?: NodeJS.ProcessEnv): string;
+export declare function configDir(env?: NodeJS.ProcessEnv): string;
+export declare function auditDir(env?: NodeJS.ProcessEnv): string;
+export declare function mutationLockPath(env?: NodeJS.ProcessEnv): string;
+/** Environment tuple recorded at the last verified mutation (consent-churn tripwire). */
+export declare function environmentStatePath(env?: NodeJS.ProcessEnv): string;

package/dist/paths.js

@@ -0,0 +1,30 @@
+/**
+ * XDG-style directory resolution for state (audit log, lockfile, local
+ * acceptances) and config. Overridable via THINGS_API_* env for tests and
+ * non-standard setups.
+ */
+import { homedir } from "node:os";
+import { join } from "node:path";
+export function stateDir(env = process.env) {
+    if (env["THINGS_API_STATE_DIR"])
+        return env["THINGS_API_STATE_DIR"];
+    const xdg = env["XDG_STATE_HOME"];
+    return join(xdg && xdg !== "" ? xdg : join(homedir(), ".local", "state"), "things-api");
+}
+export function configDir(env = process.env) {
+    if (env["THINGS_API_CONFIG_DIR"])
+        return env["THINGS_API_CONFIG_DIR"];
+    const xdg = env["XDG_CONFIG_HOME"];
+    return join(xdg && xdg !== "" ? xdg : join(homedir(), ".config"), "things-api");
+}
+export function auditDir(env = process.env) {
+    return join(stateDir(env), "audit");
+}
+export function mutationLockPath(env = process.env) {
+    return join(stateDir(env), "mutation.lock");
+}
+/** Environment tuple recorded at the last verified mutation (consent-churn tripwire). */
+export function environmentStatePath(env = process.env) {
+    return join(stateDir(env), "environment.json");
+}
+//# sourceMappingURL=paths.js.map

package/dist/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,MAAM,UAAU,QAAQ,CAAC,MAAyB,OAAO,CAAC,GAAG;IAC3D,IAAI,GAAG,CAAC,sBAAsB,CAAC;QAAE,OAAO,GAAG,CAAC,sBAAsB,CAAC,CAAC;IACpE,MAAM,GAAG,GAAG,GAAG,CAAC,gBAAgB,CAAC,CAAC;IAClC,OAAO,IAAI,CAAC,GAAG,IAAI,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE,YAAY,CAAC,CAAC;AAC1F,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,MAAyB,OAAO,CAAC,GAAG;IAC5D,IAAI,GAAG,CAAC,uBAAuB,CAAC;QAAE,OAAO,GAAG,CAAC,uBAAuB,CAAC,CAAC;IACtE,MAAM,GAAG,GAAG,GAAG,CAAC,iBAAiB,CAAC,CAAC;IACnC,OAAO,IAAI,CAAC,GAAG,IAAI,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,SAAS,CAAC,EAAE,YAAY,CAAC,CAAC;AAClF,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,MAAyB,OAAO,CAAC,GAAG;IAC3D,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC,CAAC;AACtC,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,MAAyB,OAAO,CAAC,GAAG;IACnE,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,eAAe,CAAC,CAAC;AAC9C,CAAC;AAED,yFAAyF;AACzF,MAAM,UAAU,oBAAoB,CAAC,MAAyB,OAAO,CAAC,GAAG;IACvE,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,kBAAkB,CAAC,CAAC;AACjD,CAAC"}

package/dist/read/detail.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Single-record reads by UUID — includes repeating templates (which list
+ * views hide), checklist items, and inherited tags.
+ */
+import type { DatabaseSync } from "node:sqlite";
+import type { AnyTask, ChecklistItem } from "../model/entities.ts";
+export declare function byUuid(db: DatabaseSync, uuid: string): AnyTask | null;
+export declare function checklistFor(db: DatabaseSync, taskUuid: string): ChecklistItem[];

package/dist/read/detail.js

@@ -0,0 +1,34 @@
+import { mapChecklistItem, mapHeading, mapProject, mapTodo, } from "../model/mappers.js";
+import { decodeRecurrenceRule } from "../model/recurrence.js";
+import { fetchChecklistRows, fetchTagsForTasks, fetchTaskByUuid, makeRefResolver, } from "./queries.js";
+import { inheritedTagsFor } from "./tags.js";
+export function byUuid(db, uuid) {
+    const row = fetchTaskByUuid(db, uuid);
+    if (!row)
+        return null;
+    return materializeOne(db, row);
+}
+function materializeOne(db, row) {
+    const refs = makeRefResolver(db);
+    if (row.type === 2)
+        return mapHeading(row, refs);
+    const tags = fetchTagsForTasks(db, [row.uuid]).get(row.uuid) ?? [];
+    const entity = row.type === 1 ? mapProject(row, refs, tags) : mapTodo(row, refs, tags);
+    entity.inheritedTags = inheritedTagsFor(db, row);
+    if (entity.type === "to-do")
+        entity.checklist = checklistFor(db, row.uuid);
+    if (entity.repeating.isTemplate && row.rt1_recurrenceRule !== null) {
+        try {
+            entity.repeating.rule = decodeRecurrenceRule(row.rt1_recurrenceRule);
+        }
+        catch {
+            // Unknown rule schema (future Things build) — surface the template
+            // without a decoded rule rather than failing the whole read.
+        }
+    }
+    return entity;
+}
+export function checklistFor(db, taskUuid) {
+    return fetchChecklistRows(db, taskUuid).map(mapChecklistItem);
+}
+//# sourceMappingURL=detail.js.map

package/dist/read/detail.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"detail.js","sourceRoot":"","sources":["../../src/read/detail.ts"],"names":[],"mappings":"AAOA,OAAO,EACL,gBAAgB,EAChB,UAAU,EACV,UAAU,EACV,OAAO,GAER,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,eAAe,EACf,eAAe,GAChB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAE7C,MAAM,UAAU,MAAM,CAAC,EAAgB,EAAE,IAAY;IACnD,MAAM,GAAG,GAAG,eAAe,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;IACtC,IAAI,CAAC,GAAG;QAAE,OAAO,IAAI,CAAC;IACtB,OAAO,cAAc,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;AACjC,CAAC;AAED,SAAS,cAAc,CAAC,EAAgB,EAAE,GAAY;IACpD,MAAM,IAAI,GAAG,eAAe,CAAC,EAAE,CAAC,CAAC;IACjC,IAAI,GAAG,CAAC,IAAI,KAAK,CAAC;QAAE,OAAO,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IACjD,MAAM,IAAI,GAAG,iBAAiB,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;IACnE,MAAM,MAAM,GAAG,GAAG,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;IACvF,MAAM,CAAC,aAAa,GAAG,gBAAgB,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;IACjD,IAAI,MAAM,CAAC,IAAI,KAAK,OAAO;QAAE,MAAM,CAAC,SAAS,GAAG,YAAY,CAAC,EAAE,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC;IAC3E,IAAI,MAAM,CAAC,SAAS,CAAC,UAAU,IAAI,GAAG,CAAC,kBAAkB,KAAK,IAAI,EAAE,CAAC;QACnE,IAAI,CAAC;YACH,MAAM,CAAC,SAAS,CAAC,IAAI,GAAG,oBAAoB,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;QACvE,CAAC;QAAC,MAAM,CAAC;YACP,mEAAmE;YACnE,6DAA6D;QAC/D,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,EAAgB,EAAE,QAAgB;IAC7D,OAAO,kBAAkB,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;AAChE,CAAC"}

package/dist/read/project-view.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Composite project view mirroring the native UI (validated T17 + "later
+ * items" findings): active items, headings with their children, later
+ * (scheduled by date / repeating templates / someday), logged, trashed.
+ *
+ * Child membership: `project = ? OR heading IN (project's headings)` — the
+ * DB invariant is that headed to-dos have project = NULL (atlas §TMTask).
+ * This is the dedup-safe alternative to things.py's include_items.
+ */
+import type { DatabaseSync } from "node:sqlite";
+import type { Heading, IsoDateGroup, Project, Todo } from "../model/entities.ts";
+export interface ProjectView {
+    project: Project;
+    /** Open, unscheduled/current children not under a heading, by index. */
+    active: Todo[];
+    /** Headings in project order, each with its open children. */
+    headings: Array<{
+        heading: Heading;
+        items: Todo[];
+    }>;
+    later: {
+        /** Future-dated children grouped by date ascending. */
+        scheduled: IsoDateGroup<Todo>[];
+        /** Repeating template rows owned by this project (invisible in list views). */
+        repeating: Todo[];
+        someday: Todo[];
+    };
+    logged: Todo[];
+    trashed: Todo[];
+}
+export declare class ProjectNotFoundError extends Error {
+    constructor(uuid: string);
+}
+export declare function projectView(db: DatabaseSync, uuid: string, now?: Date): ProjectView;

package/dist/read/project-view.js

@@ -0,0 +1,87 @@
+import { encodePackedDate, localToday, decodePackedDate } from "../model/dates.js";
+import { mapHeading, mapProject, mapTodo } from "../model/mappers.js";
+import { fetchTagsForTasks, fetchTaskByUuid, fetchTaskRows, makeRefResolver } from "./queries.js";
+export class ProjectNotFoundError extends Error {
+    constructor(uuid) {
+        super(`no project with uuid ${uuid}`);
+        this.name = "ProjectNotFoundError";
+    }
+}
+export function projectView(db, uuid, now) {
+    const projectRow = fetchTaskByUuid(db, uuid);
+    if (!projectRow || projectRow.type !== 1)
+        throw new ProjectNotFoundError(uuid);
+    const refs = makeRefResolver(db);
+    const tagsOf = (rows) => fetchTagsForTasks(db, rows.map((r) => r.uuid));
+    const projectTags = tagsOf([projectRow]);
+    const project = mapProject(projectRow, refs, projectTags.get(projectRow.uuid) ?? []);
+    const headingRows = fetchTaskRows(db, `t.type = 2 AND t.project = ? AND t.trashed = 0 ORDER BY t."index" ASC`, [uuid]);
+    const headings = headingRows.map((h) => mapHeading(h, refs));
+    const childRows = fetchTaskRows(db, `t.type = 0 AND (t.project = ? OR t.heading IN (
+       SELECT uuid FROM TMTask WHERE type = 2 AND project = ?
+     ))
+     ORDER BY t."index" ASC`, [uuid, uuid]);
+    const childTags = tagsOf(childRows);
+    const todos = childRows.map((r) => ({
+        row: r,
+        todo: mapTodo(r, refs, childTags.get(r.uuid) ?? []),
+    }));
+    const packedToday = encodePackedDate(localToday(now));
+    const active = [];
+    const byHeading = new Map();
+    const scheduledRows = [];
+    const repeating = [];
+    const someday = [];
+    const logged = [];
+    const trashed = [];
+    for (const { row, todo } of todos) {
+        if (row.trashed === 1) {
+            trashed.push(todo);
+            continue;
+        }
+        if (todo.repeating.isTemplate) {
+            repeating.push(todo);
+            continue;
+        }
+        if (row.status !== 0) {
+            logged.push(todo);
+            continue;
+        }
+        if (row.start === 2 && row.startDate === null) {
+            someday.push(todo);
+            continue;
+        }
+        if (row.startDate !== null && row.startDate > packedToday) {
+            scheduledRows.push({ date: decodePackedDate(row.startDate) ?? "", todo });
+            continue;
+        }
+        if (row.heading) {
+            const list = byHeading.get(row.heading) ?? [];
+            list.push(todo);
+            byHeading.set(row.heading, list);
+            continue;
+        }
+        active.push(todo);
+    }
+    logged.sort((a, b) => (b.stopped?.getTime() ?? 0) - (a.stopped?.getTime() ?? 0));
+    const scheduled = [];
+    for (const { date, todo } of scheduledRows.sort((a, b) => a.date.localeCompare(b.date))) {
+        const last = scheduled[scheduled.length - 1];
+        if (last && last.date === date)
+            last.items.push(todo);
+        else
+            scheduled.push({ date, items: [todo] });
+    }
+    return {
+        project,
+        active,
+        headings: headings.map((heading) => ({
+            heading,
+            items: byHeading.get(heading.uuid) ?? [],
+        })),
+        later: { scheduled, repeating, someday },
+        logged,
+        trashed,
+    };
+}
+//# sourceMappingURL=project-view.js.map

package/dist/read/project-view.js.map

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