things-api 0.5.0

package/dist/client.js

@@ -0,0 +1,187 @@
+import { createAuditWriter } from "./audit/log.js";
+import { loadConfig } from "./config.js";
+import { PKG_VERSION } from "./contracts.js";
+import { BASELINES } from "./db/baselines/index.js";
+import { openConnection } from "./db/connection.js";
+import { compareToBaseline, observeSchema } from "./db/fingerprint.js";
+import { locateThingsDb } from "./db/locate.js";
+import { auditDir, mutationLockPath } from "./paths.js";
+import { byUuid } from "./read/detail.js";
+import { projectView } from "./read/project-view.js";
+import { snapshotView } from "./read/snapshot.js";
+import { areasView, tagsView } from "./read/tags.js";
+import { anytimeView, changesView, inboxView, 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 { 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 an item by exact title — loud on missing/ambiguous (never guess). */
+function checklistIndex(items, ref) {
+    const matches = items.map((c, i) => ({ c, i })).filter(({ c }) => c.title === ref);
+    if (matches.length === 1)
+        return matches[0].i;
+    throw new RangeError(matches.length === 0
+        ? `no checklist item titled "${ref}"`
+        : `checklist item title "${ref}" is ambiguous (${matches.length} matches) — rename first`);
+}
+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(checklistIndex(next, edit.item), 1);
+            return next;
+        case "check":
+        case "uncheck": {
+            const target = next[checklistIndex(next, edit.item)];
+            target.completed = edit.action === "check";
+            return next;
+        }
+        case "rename": {
+            const target = next[checklistIndex(next, edit.item)];
+            target.title = edit.title;
+            return next;
+        }
+        case "move": {
+            const from = checklistIndex(next, edit.item);
+            const [moved] = next.splice(from, 1);
+            next.splice(Math.max(0, Math.min(next.length, edit.to - 1)), 0, moved);
+            return next;
+        }
+    }
+}
+export function openThings(options = {}) {
+    const located = locateThingsDb(options.dbPath ? { dbPath: options.dbPath } : undefined);
+    const conn = openConnection(located.path);
+    const now = options.now ?? (() => new Date());
+    const env = options.env ?? process.env;
+    const config = loadConfig(env);
+    let cachedStatus = null;
+    const fingerprint = () => {
+        cachedStatus ??= compareToBaseline(observeSchema(conn.db), BASELINES);
+        return cachedStatus;
+    };
+    const token = readAuthToken(conn.db);
+    const audit = options.writeOverrides?.audit ??
+        createAuditWriter({
+            dir: auditDir(env),
+            secrets: token === null ? [] : [token],
+            enabled: config.auditEnabled,
+        });
+    const writeDeps = {
+        db: conn.db,
+        vectors: options.vectors ?? defaultVectors(),
+        config,
+        audit,
+        fingerprint,
+        lockPath: mutationLockPath(env),
+        now,
+        ...(options.writeOverrides?.ensureRunning !== undefined && {
+            ensureRunning: options.writeOverrides.ensureRunning,
+        }),
+        ...(options.writeOverrides?.isAppRunning !== undefined && {
+            isAppRunning: options.writeOverrides.isAppRunning,
+        }),
+        ...(options.writeOverrides?.poller !== undefined && {
+            poller: options.writeOverrides.poller,
+        }),
+        ...(options.writeOverrides?.sdefProbe !== undefined && {
+            sdefProbe: options.writeOverrides.sdefProbe,
+        }),
+        environment: options.writeOverrides?.environment ?? createEnvironmentTracker(PKG_VERSION, env),
+    };
+    const run = (op, params, writeOptions) => runMutation(writeDeps, op, params, writeOptions ?? {});
+    return {
+        dbPath: located.path,
+        config,
+        fingerprint,
+        read: {
+            today: (f) => todayView(conn.db, now(), f),
+            inbox: (f) => inboxView(conn.db, f),
+            anytime: (f) => anytimeView(conn.db, now(), f),
+            upcoming: (f) => upcomingView(conn.db, now(), f),
+            someday: (f) => somedayView(conn.db, now(), f),
+            logbook: (o) => logbookView(conn.db, o),
+            trash: (o) => trashView(conn.db, o),
+            projects: (o) => projectsView(conn.db, o),
+            projectView: (uuid) => projectView(conn.db, uuid, now()),
+            areas: () => areasView(conn.db),
+            tags: () => tagsView(conn.db),
+            search: (query, o) => searchView(conn.db, query, o),
+            changes: (o) => changesView(conn.db, o),
+            byUuid: (uuid) => byUuid(conn.db, uuid),
+            snapshot: () => snapshotView(conn.db),
+        },
+        write: {
+            run,
+            addTodo: (params, o) => run("todo.add", params, o),
+            updateTodo: (uuid, patch, o) => run("todo.update", { uuid, ...patch }, o),
+            completeTodo: (uuid, o) => run("todo.complete", { uuid }, o),
+            cancelTodo: (uuid, o) => run("todo.cancel", { uuid }, o),
+            reopenTodo: (uuid, o) => run("todo.reopen", { uuid }, o),
+            moveTodo: (uuid, dest, o) => run("todo.move", { uuid, ...dest }, o),
+            setTags: (uuid, tags, o) => run("todo.set-tags", { uuid, tags }, o),
+            addTags(uuid, tags, o) {
+                const current = byUuid(conn.db, uuid);
+                const existing = current !== null && current.type !== "heading" ? current.tags.map((t) => t.title) : [];
+                const merged = [...new Set([...existing, ...tags])];
+                return run("todo.set-tags", { uuid, tags: merged }, o);
+            },
+            replaceChecklist: (uuid, items, o) => run("todo.replace-checklist", { uuid, items }, o),
+            deleteTodo: (uuid, o) => run("todo.delete", { uuid }, o),
+            duplicateTodo: (uuid, o) => run("todo.duplicate", { uuid }, o),
+            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),
+            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 });
+            },
+            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),
+            moveProject: (uuid, area, o) => run("project.move", { uuid, area }, o),
+            detachProject: (uuid, o) => run("project.move", { uuid, detach: true }, o),
+            cancelProject: (uuid, policy, o) => run("project.cancel", { uuid, children: policy.children }, o),
+            reopenProject: (uuid, o) => runProjectReopen(writeDeps, uuid, o ?? {}),
+            restoreProject: (uuid, o) => run("project.restore", { uuid }, o),
+            duplicateProject: (uuid, o) => run("project.duplicate", { uuid }, o),
+            deleteProject: (uuid, o) => run("project.delete", { uuid }, o),
+            setProjectTags: (uuid, tags, o) => run("project.set-tags", { uuid, tags }, o),
+            addProjectTags(uuid, tags, o) {
+                const current = byUuid(conn.db, uuid);
+                const existing = current !== null && current.type !== "heading" ? current.tags.map((t) => t.title) : [];
+                const merged = [...new Set([...existing, ...tags])];
+                return run("project.set-tags", { uuid, tags: merged }, o);
+            },
+            addArea: (params, o) => run("area.add", params, o),
+            updateArea: (target, patch, o) => run("area.update", { target, ...patch }, o),
+            deleteArea: (target, o) => run("area.delete", { target }, o),
+            addTag: (params, o) => run("tag.add", params, o),
+            updateTag: (target, patch, o) => run("tag.update", { target, ...patch }, o),
+            deleteTag: (target, o) => run("tag.delete", { target }, o),
+            emptyTrash: (o) => run("trash.empty", {}, o),
+            reorder: (params, o) => runReorder(writeDeps, params, o ?? {}),
+            batch: (ops, o, onResult) => runBatch(writeDeps, ops, o ?? {}, onResult),
+            undo: (o, onItem) => runUndo(writeDeps, auditDir(env), o ?? {}, onItem),
+        },
+        close: () => conn.close(),
+    };
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

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

package/dist/config.d.ts

@@ -0,0 +1,31 @@
+export type Profile = "workstation" | "dedicated-server";
+export type DisruptionTier = 0 | 1 | 2 | 3;
+export interface ThingsApiConfig {
+    profile: Profile;
+    /** Highest disruption tier allowed without explicit per-call escalation. */
+    maxDisruption: DisruptionTier;
+    /** Audit attribution when the caller does not pass one. */
+    actor: string;
+    /** JSONL audit trail on/off (default on). */
+    auditEnabled: boolean;
+    /** User-accepted drifted fingerprint (loud escape hatch; see design §6). */
+    acceptedFingerprint: string | null;
+    /**
+     * Opt-in to capabilities riding undocumented app surfaces (the private
+     * sdef reorder command). Guarded further by the pipeline's sdef canary.
+     */
+    allowExperimental: boolean;
+    host: string;
+}
+interface ConfigFile {
+    profile?: Profile;
+    maxDisruption?: DisruptionTier;
+    actor?: string;
+    auditEnabled?: boolean;
+    acceptedFingerprint?: string;
+    allowExperimental?: boolean;
+}
+export declare function loadConfig(env?: NodeJS.ProcessEnv): ThingsApiConfig;
+/** Persist one config key (CLI `things config set`). */
+export declare function saveConfigKey(key: keyof ConfigFile, value: string | number | boolean | null, env?: NodeJS.ProcessEnv): void;
+export {};

package/dist/config.js

@@ -0,0 +1,76 @@
+/**
+ * Config profiles + env overrides.
+ *
+ * `workstation` (default): a human may be at the screen — background app
+ * launch (tier 1) is acceptable, focus steal (tier 2) requires an explicit
+ * flag. `dedicated-server`: nobody is watching; tier 2 allowed by default.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { hostname, userInfo } from "node:os";
+import { join } from "node:path";
+import { configDir } from "./paths.js";
+const PROFILE_DEFAULT_TIER = {
+    workstation: 1,
+    "dedicated-server": 2,
+};
+function configFilePath(env) {
+    return join(configDir(env), "config.json");
+}
+export function loadConfig(env = process.env) {
+    let file = {};
+    const path = configFilePath(env);
+    if (existsSync(path)) {
+        try {
+            file = JSON.parse(readFileSync(path, "utf8"));
+        }
+        catch {
+            // Malformed config falls back to defaults; doctor reports it.
+        }
+    }
+    const profile = env["THINGS_API_PROFILE"] === "dedicated-server" || file.profile === "dedicated-server"
+        ? "dedicated-server"
+        : "workstation";
+    const envTier = env["THINGS_API_MAX_DISRUPTION"];
+    const maxDisruption = (envTier !== undefined && /^[0-3]$/.test(envTier)
+        ? Number(envTier)
+        : (file.maxDisruption ?? PROFILE_DEFAULT_TIER[profile]));
+    let username = "unknown";
+    try {
+        username = userInfo().username;
+    }
+    catch {
+        // leave "unknown"
+    }
+    return {
+        profile,
+        maxDisruption,
+        actor: env["THINGS_API_ACTOR"] ?? file.actor ?? `${username}@cli`,
+        auditEnabled: env["THINGS_API_AUDIT"] === "off" ? false : (file.auditEnabled ?? true),
+        acceptedFingerprint: file.acceptedFingerprint ?? null,
+        allowExperimental: env["THINGS_API_ALLOW_EXPERIMENTAL"] === "true" || file.allowExperimental === true,
+        host: hostname(),
+    };
+}
+/** Persist one config key (CLI `things config set`). */
+export function saveConfigKey(key, value, env = process.env) {
+    const dir = configDir(env);
+    mkdirSync(dir, { recursive: true });
+    const path = configFilePath(env);
+    let file = {};
+    if (existsSync(path)) {
+        try {
+            file = JSON.parse(readFileSync(path, "utf8"));
+        }
+        catch {
+            file = {};
+        }
+    }
+    if (value === null) {
+        delete file[key];
+    }
+    else {
+        file[key] = value;
+    }
+    writeFileSync(path, `${JSON.stringify(file, null, 2)}\n`);
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

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

package/dist/contracts.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Machine-facing contracts shared by every surface over the library (CLI
+ * --json envelopes, MCP tool results): the versioned envelope shape and the
+ * stable exit-code family. Lives in the CORE so thin surfaces depend on the
+ * library, never on each other (see docs/design/contracts.md).
+ *
+ * - Envelope JSON goes to stdout; all human/log chatter goes to stderr.
+ * - `apiVersion` is bumped only on breaking envelope-shape changes.
+ * - `data` is command-specific; `error` is present exactly when `ok` is false.
+ */
+export declare const API_VERSION = 1;
+/**
+ * Package version, surfaced by `things --version` and the MCP serverInfo.
+ * Kept in lockstep with package.json by a contract test.
+ */
+export declare const PKG_VERSION = "0.5.0";
+/**
+ * Stable exit-code contract for the `things` CLI (mirrored by MCP error
+ * codes). Part of the public API surface consumed by agents and scripts —
+ * values must never be renumbered; add new codes at the end.
+ */
+export declare const ExitCode: {
+    /** Success. */
+    readonly Ok: 0;
+    /** Unexpected internal error (bug, unhandled condition). */
+    readonly Unexpected: 1;
+    /** Usage error: unknown command, bad flags, invalid arguments. */
+    readonly Usage: 2;
+    /** Mutation executed but read-after-write verification failed (timeout, mismatch, or silent no-op). */
+    readonly VerifyFailed: 3;
+    /** Mutation refused before touching the app: hazard guard or disruption-tier policy. */
+    readonly Blocked: 4;
+    /** Writes disabled because the database schema fingerprint deviates from the known baseline. */
+    readonly DriftBlocked: 5;
+    /** Operation not supported by any available write vector. */
+    readonly Unsupported: 6;
+    /** Environment problem: database not found, Things not installed, permissions. */
+    readonly Environment: 7;
+};
+export type ExitCode = (typeof ExitCode)[keyof typeof ExitCode];
+export interface EnvelopeMeta {
+    /** Things database schema version (`Meta.databaseVersion`), null when no DB was opened. */
+    dbVersion: number | null;
+    /** Schema fingerprint status at the time of the command. */
+    fingerprint: "ok" | "drift" | "user-accepted" | "unknown";
+    /** Wall-clock duration of the command in milliseconds. */
+    elapsedMs: number;
+}
+export interface OkEnvelope<T> {
+    apiVersion: typeof API_VERSION;
+    ok: true;
+    /** Discriminator naming the payload shape, e.g. "today", "mutation-result". */
+    kind: string;
+    data: T;
+    meta: EnvelopeMeta;
+}
+export interface ErrorEnvelope {
+    apiVersion: typeof API_VERSION;
+    ok: false;
+    kind: "error";
+    error: {
+        /** Stable machine-readable code, mirrors the exit-code family (e.g. "verify-failed", "blocked"). */
+        code: string;
+        message: string;
+        /**
+         * Advisory attribution when failure signals point somewhere: e.g.
+         * "permission-denied", "permission-pending", "feature-disabled",
+         * "app-updated", "schema-drift", "app-behavior-change".
+         */
+        likelyCause?: string;
+        /** Actionable next step for the caller, when one exists. */
+        remediation?: string;
+        detail?: unknown;
+    };
+    meta: EnvelopeMeta;
+}
+export type Envelope<T> = OkEnvelope<T> | ErrorEnvelope;
+export declare function okEnvelope<T>(kind: string, data: T, meta: EnvelopeMeta): OkEnvelope<T>;
+export declare function errorEnvelope(error: ErrorEnvelope["error"], meta: EnvelopeMeta): ErrorEnvelope;

package/dist/contracts.js

@@ -0,0 +1,46 @@
+/**
+ * Machine-facing contracts shared by every surface over the library (CLI
+ * --json envelopes, MCP tool results): the versioned envelope shape and the
+ * stable exit-code family. Lives in the CORE so thin surfaces depend on the
+ * library, never on each other (see docs/design/contracts.md).
+ *
+ * - Envelope JSON goes to stdout; all human/log chatter goes to stderr.
+ * - `apiVersion` is bumped only on breaking envelope-shape changes.
+ * - `data` is command-specific; `error` is present exactly when `ok` is false.
+ */
+export const API_VERSION = 1;
+/**
+ * Package version, surfaced by `things --version` and the MCP serverInfo.
+ * Kept in lockstep with package.json by a contract test.
+ */
+export const PKG_VERSION = "0.5.0";
+/**
+ * Stable exit-code contract for the `things` CLI (mirrored by MCP error
+ * codes). Part of the public API surface consumed by agents and scripts —
+ * values must never be renumbered; add new codes at the end.
+ */
+export const ExitCode = {
+    /** Success. */
+    Ok: 0,
+    /** Unexpected internal error (bug, unhandled condition). */
+    Unexpected: 1,
+    /** Usage error: unknown command, bad flags, invalid arguments. */
+    Usage: 2,
+    /** Mutation executed but read-after-write verification failed (timeout, mismatch, or silent no-op). */
+    VerifyFailed: 3,
+    /** Mutation refused before touching the app: hazard guard or disruption-tier policy. */
+    Blocked: 4,
+    /** Writes disabled because the database schema fingerprint deviates from the known baseline. */
+    DriftBlocked: 5,
+    /** Operation not supported by any available write vector. */
+    Unsupported: 6,
+    /** Environment problem: database not found, Things not installed, permissions. */
+    Environment: 7,
+};
+export function okEnvelope(kind, data, meta) {
+    return { apiVersion: API_VERSION, ok: true, kind, data, meta };
+}
+export function errorEnvelope(error, meta) {
+    return { apiVersion: API_VERSION, ok: false, kind: "error", error, meta };
+}
+//# sourceMappingURL=contracts.js.map

package/dist/contracts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.js","sourceRoot":"","sources":["../src/contracts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAC;AAE7B;;;GAGG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,OAAO,CAAC;AAEnC;;;;GAIG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG;IACtB,eAAe;IACf,EAAE,EAAE,CAAC;IACL,4DAA4D;IAC5D,UAAU,EAAE,CAAC;IACb,kEAAkE;IAClE,KAAK,EAAE,CAAC;IACR,uGAAuG;IACvG,YAAY,EAAE,CAAC;IACf,wFAAwF;IACxF,OAAO,EAAE,CAAC;IACV,gGAAgG;IAChG,YAAY,EAAE,CAAC;IACf,6DAA6D;IAC7D,WAAW,EAAE,CAAC;IACd,kFAAkF;IAClF,WAAW,EAAE,CAAC;CACN,CAAC;AA6CX,MAAM,UAAU,UAAU,CAAI,IAAY,EAAE,IAAO,EAAE,IAAkB;IACrE,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AACjE,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,KAA6B,EAAE,IAAkB;IAC7E,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;AAC5E,CAAC"}

package/dist/db/baselines/db-v26.d.ts

@@ -0,0 +1,8 @@
+import type { Baseline } from "../fingerprint.ts";
+/**
+ * Schema baseline for Meta.databaseVersion = 26.
+ * Captured 2026-07-02 from a live Things 3.22.11 library; the fixture DDL
+ * (test/fixtures/schema-v26.sql) reproduces this fingerprint exactly
+ * (asserted by test/unit/fingerprint.test.ts).
+ */
+export declare const DB_V26: Baseline;

package/dist/db/baselines/db-v26.js

@@ -0,0 +1,16 @@
+/**
+ * Schema baseline for Meta.databaseVersion = 26.
+ * Captured 2026-07-02 from a live Things 3.22.11 library; the fixture DDL
+ * (test/fixtures/schema-v26.sql) reproduces this fingerprint exactly
+ * (asserted by test/unit/fingerprint.test.ts).
+ */
+export const DB_V26 = {
+    databaseVersion: 26,
+    // Recomputed 2026-07-04 (Phase 10b/10c): manifest gained
+    // rt1_instanceCreationPaused (occurrence synthesis) and
+    // deadlineSuppressionDate (deadline-driven Today membership); verified
+    // identical from the live library and the fixture DDL.
+    fingerprint: "sha256:5526059b10ffffe1b67f796d031857d030403bd5b747374646a2803a55c0e5c3",
+    knownThingsAppVersions: ["3.22.11"],
+};
+//# sourceMappingURL=db-v26.js.map

package/dist/db/baselines/db-v26.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"db-v26.js","sourceRoot":"","sources":["../../../src/db/baselines/db-v26.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,MAAM,CAAC,MAAM,MAAM,GAAa;IAC9B,eAAe,EAAE,EAAE;IACnB,yDAAyD;IACzD,wDAAwD;IACxD,uEAAuE;IACvE,uDAAuD;IACvD,WAAW,EAAE,yEAAyE;IACtF,sBAAsB,EAAE,CAAC,SAAS,CAAC;CACpC,CAAC"}

package/dist/db/baselines/index.d.ts

@@ -0,0 +1,3 @@
+import type { Baseline } from "../fingerprint.ts";
+/** All known-good schema baselines, keyed by Meta.databaseVersion. */
+export declare const BASELINES: readonly Baseline[];

package/dist/db/baselines/index.js

@@ -0,0 +1,4 @@
+import { DB_V26 } from "./db-v26.js";
+/** All known-good schema baselines, keyed by Meta.databaseVersion. */
+export const BASELINES = [DB_V26];
+//# sourceMappingURL=index.js.map

package/dist/db/baselines/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/db/baselines/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC,sEAAsE;AACtE,MAAM,CAAC,MAAM,SAAS,GAAwB,CAAC,MAAM,CAAC,CAAC"}

package/dist/db/connection.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Read-only connection to a Things database via node:sqlite.
+ *
+ * WAL policy (docs/design/architecture.md §0):
+ * - `readOnly: true`, never `immutable=1` — the DB changes while Things runs;
+ *   immutable would poison verification polling with stale snapshots.
+ * - Each statement outside a transaction gets a fresh WAL read snapshot;
+ *   the verification poller relies on this. Never wrap polling in a
+ *   long-lived transaction.
+ * - Requires the -shm/-wal sidecars to be accessible (present whenever
+ *   Things has run at least once).
+ */
+import { DatabaseSync } from "node:sqlite";
+export interface ThingsConnection {
+    db: DatabaseSync;
+    path: string;
+    close(): void;
+}
+export declare class ThingsDbOpenError extends Error {
+    constructor(path: string, cause: unknown);
+}
+export declare function openConnection(path: string): ThingsConnection;

package/dist/db/connection.js

@@ -0,0 +1,40 @@
+/**
+ * Read-only connection to a Things database via node:sqlite.
+ *
+ * WAL policy (docs/design/architecture.md §0):
+ * - `readOnly: true`, never `immutable=1` — the DB changes while Things runs;
+ *   immutable would poison verification polling with stale snapshots.
+ * - Each statement outside a transaction gets a fresh WAL read snapshot;
+ *   the verification poller relies on this. Never wrap polling in a
+ *   long-lived transaction.
+ * - Requires the -shm/-wal sidecars to be accessible (present whenever
+ *   Things has run at least once).
+ */
+import { DatabaseSync } from "node:sqlite";
+export class ThingsDbOpenError extends Error {
+    constructor(path, cause) {
+        super(`Could not open Things database read-only at ${path}. ` +
+            `If this is a WAL/-shm access error, launch Things once and retry.`, { cause });
+        this.name = "ThingsDbOpenError";
+    }
+}
+export function openConnection(path) {
+    let db;
+    try {
+        db = new DatabaseSync(path, {
+            readOnly: true,
+            timeout: 2000,
+        });
+    }
+    catch (cause) {
+        throw new ThingsDbOpenError(path, cause);
+    }
+    return {
+        db,
+        path,
+        close() {
+            db.close();
+        },
+    };
+}
+//# sourceMappingURL=connection.js.map

package/dist/db/connection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.js","sourceRoot":"","sources":["../../src/db/connection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAQ3C,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IAC1C,YAAY,IAAY,EAAE,KAAc;QACtC,KAAK,CACH,+CAA+C,IAAI,IAAI;YACrD,mEAAmE,EACrE,EAAE,KAAK,EAAE,CACV,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IAClC,CAAC;CACF;AAED,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,IAAI,EAAgB,CAAC;IACrB,IAAI,CAAC;QACH,EAAE,GAAG,IAAI,YAAY,CAAC,IAAI,EAAE;YAC1B,QAAQ,EAAE,IAAI;YACd,OAAO,EAAE,IAAI;SACd,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,iBAAiB,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IAC3C,CAAC;IACD,OAAO;QACL,EAAE;QACF,IAAI;QACJ,KAAK;YACH,EAAE,CAAC,KAAK,EAAE,CAAC;QACb,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/db/fingerprint.d.ts

@@ -0,0 +1,42 @@
+import type { DatabaseSync } from "node:sqlite";
+import { type DependedTable } from "./schema.ts";
+export interface ColumnShape {
+    name: string;
+    declaredType: string;
+    notnull: 0 | 1;
+    pk: number;
+}
+export interface TableShape {
+    table: DependedTable;
+    present: boolean;
+    /** Depended columns in manifest order; absent ones recorded as null. */
+    columns: Array<ColumnShape | null>;
+    /** Columns present in the DB but not in the manifest (informational). */
+    extraColumns: string[];
+}
+export interface SchemaObservation {
+    databaseVersion: number | null;
+    tables: TableShape[];
+    fingerprint: string;
+}
+export declare function observeSchema(db: DatabaseSync): SchemaObservation;
+/** Meta.databaseVersion is a plist blob/text wrapping an <integer>. */
+export declare function readDatabaseVersion(db: DatabaseSync): number | null;
+export type FingerprintStatus = {
+    kind: "ok";
+    observation: SchemaObservation;
+} | {
+    kind: "drift";
+    observation: SchemaObservation;
+    expected: string;
+    detail: string[];
+} | {
+    kind: "unknown-version";
+    observation: SchemaObservation;
+};
+export interface Baseline {
+    databaseVersion: number;
+    fingerprint: string;
+    knownThingsAppVersions: string[];
+}
+export declare function compareToBaseline(observation: SchemaObservation, baselines: readonly Baseline[]): FingerprintStatus;