projectionlab-mcp 1.0.1 → 1.2.0

package/SETUP-FOR-AGENTS.md

@@ -0,0 +1,37 @@
+# Setting up ProjectionLab MCP: instructions for AI assistants
+
+This file is for the AI agent doing the install. A person reading it can skip
+it: the [README](https://github.com/Backroads4Me/projectionlab-mcp#readme) has
+the steps for people.
+
+You are setting this up for a **non-technical user**. Explain each thing you need from them in plain language, one step at a time, and never ask them to do something you can do yourself.
+
+**1. Get the user's Plugin API key.** Ask them to open ProjectionLab → Account Settings → Plugins, enable plugins, and copy their **Plugin API Key**. Do **not** invent one, and never print, log, or commit it.
+
+**2. Store the key.** Write it to `~/.projectionlab-mcp/.env` as the line `PL_API_KEY=...` and make the file readable only by the user (`chmod 600`). Every MCP host on the machine reads this file, so the key lives in one place. Do not repeat the key back to the user. Writes stay disabled by default; do not set `PL_READ_ONLY=false` until the user has seen the tool working and explicitly asks.
+
+**3. Register the server with the user's MCP host.** The server runs with `npx`, which needs Node.js 20 or newer:
+```json
+{
+  "mcpServers": {
+    "projectionlab": {
+      "command": "npx",
+      "args": ["-y", "projectionlab-mcp"]
+    }
+  }
+}
+```
+The config location varies by host; see [Adding the server to your MCP host](https://github.com/Backroads4Me/projectionlab-mcp/blob/main/REFERENCE.md#adding-the-server-to-your-mcp-host) for common ones. Have the user restart the host so it starts the server. On first start the server creates the browser connection token at `~/.projectionlab-mcp/ws-token`.
+
+**4. Connect the browser.** The server reaches ProjectionLab through the user's own browser. Pick the path that fits:
+
+- **Recommended: the browser extension** (persists across restarts). Download the zip for the user's browser from the [latest release](https://github.com/Backroads4Me/projectionlab-mcp/releases/latest) and unzip it. Then walk the user through loading it (this is a click-by-click browser task; describe exactly what they'll see):
+  - **Chrome / Edge / Brave:** open `chrome://extensions`, turn on "Developer mode" (top-right), click "Load unpacked", and choose the unzipped Chromium folder.
+  - **Firefox (140+):** open `about:debugging` → "This Firefox" → "Load Temporary Add-on", and choose `manifest.json` in the unzipped Firefox folder. Firefox removes temporary add-ons when it restarts.
+  Then have them open the extension's **options page** and enter the WebSocket **port** (default `8788`) and the **shared token** from `~/.projectionlab-mcp/ws-token`.
+
+- **Quick alternative: no install.** Call the `projectionlab_get_bootstrap` tool, then have the user paste the returned snippet into their ProjectionLab tab's developer console (F12 → Console). It works the same way but must be re-pasted if they reload the page. Good for a first test drive.
+
+**5. Verify.** Have the user open [ProjectionLab](https://app.projectionlab.com), log in, and confirm plugins are enabled. Then call `projectionlab_check_connection`; it should report all checks passing. Do this before any other tool call.
+
+**6. Enabling changes (writes).** Leave everything read-only until the user explicitly asks to make changes. When they do: set `PL_READ_ONLY=false` in `~/.projectionlab-mcp/.env` or the host's `env` block, restart the host, and confirm with `projectionlab_check_connection` that `writesEnabled` is `true`. Every write tool still previews unless called with `confirm: true`: show the user each preview and confirm only the change they approve. Every confirmed change is snapshotted first so it can be rolled back. Tell the user this before the first change.

package/dist/bootstrap.js

@@ -1,5 +1,16 @@
 import { PROTOCOL_VERSION } from "./types/wire.js";
 import { VERSION } from "./version.js";
+/** The Plugin API calls the snippet will run; the meta-operations
+ * `describeApi` and `waitForApi` are handled by the snippet itself. */
+const PLUGIN_METHODS = [
+    "exportData",
+    "updateAccount",
+    "restoreCurrentFinances",
+    "restorePlans",
+    "restoreProgress",
+    "restoreSettings",
+    "validateApiKey",
+];
 /**
  * Tier 0 transport: a self-contained snippet the user pastes into the
  * ProjectionLab tab's devtools console. It plays the same executor role as
@@ -17,9 +28,11 @@ export function buildBootstrapSnippet(port, token) {
     });
     return `(() => {
   const cfg = ${cfg};
+  const PLUGIN_METHODS = ${JSON.stringify(PLUGIN_METHODS)};
   if (window.__plmcpBootstrap) { console.log("[plmcp] bootstrap already running"); return; }
   window.__plmcpBootstrap = true;
   let stopped = false;
+  const instanceId = crypto.randomUUID();
   const log = (m) => console.log("[plmcp]", m);
   function waitForApi(timeoutMs) {
     return new Promise((resolve, reject) => {
@@ -46,6 +59,9 @@ export function buildBootstrapSnippet(port, token) {
   }
   async function handle(frame, ws) {
     try {
+      if (frame.method !== "waitForApi" && frame.method !== "describeApi" && !PLUGIN_METHODS.includes(frame.method)) {
+        throw new Error("Not a wire protocol method: " + frame.method);
+      }
       const requested = frame.method === "waitForApi" ? Number((frame.params || [])[0]) : NaN;
       const api = await waitForApi(Number.isFinite(requested) && requested > 0 ? requested : 15000);
       let result;
@@ -60,14 +76,14 @@ export function buildBootstrapSnippet(port, token) {
     } catch (err) {
       const msg = err && err.message ? err.message : String(err);
       const code = err && err.code === "API_NOT_AVAILABLE" ? "API_NOT_AVAILABLE"
-        : /api.?key|invalid key|unauthori[sz]ed/i.test(msg) ? "API_KEY_INVALID" : "UNKNOWN";
+        : /api.?key|invalid key|unauthori[sz]ed|forbidden|\\b401\\b|\\b403\\b/i.test(msg) ? "API_KEY_INVALID" : "UNKNOWN";
       ws.send(JSON.stringify({ type: "response", id: frame.id, ok: false, error: { code, message: msg } }));
     }
   }
   function connect() {
     if (stopped) return;
     const ws = new WebSocket("ws://127.0.0.1:" + cfg.port);
-    ws.onopen = () => ws.send(JSON.stringify({ type: "hello", token: cfg.token, protocolVersion: cfg.protocolVersion, executor: cfg.executor }));
+    ws.onopen = () => ws.send(JSON.stringify({ type: "hello", token: cfg.token, protocolVersion: cfg.protocolVersion, executor: cfg.executor, instanceId }));
     ws.onmessage = (ev) => {
       let frame;
       try { frame = JSON.parse(ev.data); } catch { return; }
@@ -78,7 +94,8 @@ export function buildBootstrapSnippet(port, token) {
     ws.onclose = (ev) => {
       if (stopped) return;
       if (ev.code === 4001 || ev.code === 4002) { stopped = true; window.__plmcpBootstrap = false; log("stopped: " + (ev.reason || ev.code)); return; }
-      if (ev.code === 4003) { stopped = true; window.__plmcpBootstrap = false; log("replaced by another executor (probably the extension) - bootstrap no longer needed"); return; }
+      if (ev.code === 4004) { log("another executor is connected; this tab will connect if that one goes away (retrying in 30s)"); setTimeout(connect, 30000); return; }
+      if (ev.code === 4003) { log("another executor took over the connection (retrying in 30s)"); setTimeout(connect, 30000); return; }
       log("disconnected; retrying in 3s");
       setTimeout(connect, 3000);
     };

package/dist/bootstrap.js.map

@@ -1 +1 @@
-{"version":3,"file":"bootstrap.js","sourceRoot":"","sources":["../src/bootstrap.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEvC;;;;;;;GAOG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAAY,EAAE,KAAa;IAC/D,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC;QACzB,IAAI;QACJ,KAAK;QACL,eAAe,EAAE,gBAAgB;QACjC,QAAQ,EAAE,aAAa,OAAO,EAAE;KACjC,CAAC,CAAC;IACH,OAAO;gBACO,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MAqEb,CAAC;AACP,CAAC"}
+{"version":3,"file":"bootstrap.js","sourceRoot":"","sources":["../src/bootstrap.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAmB,MAAM,iBAAiB,CAAC;AACpE,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEvC;uEACuE;AACvE,MAAM,cAAc,GAAiE;IACnF,YAAY;IACZ,eAAe;IACf,wBAAwB;IACxB,cAAc;IACd,iBAAiB;IACjB,iBAAiB;IACjB,gBAAgB;CACjB,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAAY,EAAE,KAAa;IAC/D,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC;QACzB,IAAI;QACJ,KAAK;QACL,eAAe,EAAE,gBAAgB;QACjC,QAAQ,EAAE,aAAa,OAAO,EAAE;KACjC,CAAC,CAAC;IACH,OAAO;gBACO,GAAG;2BACQ,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MA0EnD,CAAC;AACP,CAAC"}

package/dist/bridge.d.ts

@@ -4,6 +4,8 @@ export interface ConnectionStatus {
     pageLoaded: boolean;
     apiAvailable: boolean;
     apiKeyValid: boolean;
+    /** Connected executor's identity, "extension/<version>" or "bootstrap/<version>". */
+    executor?: string;
     errors: string[];
 }
 /**

package/dist/clonePlan.d.ts

@@ -16,4 +16,13 @@ export declare function planNameTaken(plans: unknown[], name: string): boolean;
  * `plans` so the copy does not collide with an existing plan.
  */
 export declare function buildPlanClone(source: PlanObj, plans: unknown[], newName: string, now?: number): PlanObj;
+/**
+ * Check a fresh read after appending `clone` to `before`: every original plan
+ * is still present with its input content, its `simKey` did not vanish, its
+ * `lastUpdated` stamp never went backwards or disappeared, and the clone
+ * exists exactly once under its name with the input content that was sent.
+ * Returns the problems found; empty
+ * means verified. The Current Finances reads are checked by
+ * `currentFinancesProblems`, over the same two exports.
+ */
 export declare function verifyPlanClone(before: unknown[], after: unknown[], clone: PlanObj): string[];

package/dist/clonePlan.js

@@ -1,6 +1,6 @@
 import { randomUUID } from "node:crypto";
 import { ProjectionLabError } from "./errors.js";
-import { containsSubset } from "./plans.js";
+import { keptPlanIdentityProblems, samePlanContent, } from "./plans.js";
 function maxNumber(values) {
     const nums = values.filter((v) => typeof v === "number");
     return nums.length === 0 ? undefined : Math.max(...nums);
@@ -62,18 +62,13 @@ export function buildPlanClone(source, plans, newName, now = Date.now()) {
 }
 /**
  * Check a fresh read after appending `clone` to `before`: every original plan
- * is still present and unsaved, and the clone exists exactly once under its
- * name. Returns the problems found; empty means verified.
+ * is still present with its input content, its `simKey` did not vanish, its
+ * `lastUpdated` stamp never went backwards or disappeared, and the clone
+ * exists exactly once under its name with the input content that was sent.
+ * Returns the problems found; empty
+ * means verified. The Current Finances reads are checked by
+ * `currentFinancesProblems`, over the same two exports.
  */
-/**
- * True when `after` still holds every value of `before`. The `lastUpdated`
- * stamp is left out: restorePlans saves every plan, so ProjectionLab may
- * re-stamp originals that were not otherwise changed.
- */
-function samePlanContent(before, after) {
-    const { lastUpdated: _stamp, ...content } = before;
-    return containsSubset(content, after);
-}
 export function verifyPlanClone(before, after, clone) {
     const problems = [];
     const afterById = new Map();
@@ -87,11 +82,14 @@ export function verifyPlanClone(before, after, clone) {
             continue;
         const id = String(p.id ?? "");
         const post = afterById.get(id);
-        if (!post)
+        if (!post) {
             problems.push(`original plan ${id} is missing`);
-        else if (!samePlanContent(p, post)) {
+            continue;
+        }
+        if (!samePlanContent(p, post)) {
             problems.push(`original plan ${id} was modified`);
         }
+        problems.push(...keptPlanIdentityProblems(`original plan ${id}`, p, post));
     }
     const copies = after.filter((p) => !!p && typeof p === "object" && p.id === clone.id);
     if (copies.length !== 1) {
@@ -100,6 +98,9 @@ export function verifyPlanClone(before, after, clone) {
     else if (copies[0].name !== clone.name) {
         problems.push(`new plan is named "${String(copies[0].name)}", expected "${String(clone.name)}"`);
     }
+    else if (!samePlanContent(clone, copies[0])) {
+        problems.push(`new plan "${String(clone.name)}" differs from the copy that was sent`);
+    }
     if (after.length !== before.length + 1) {
         problems.push(`plan count is ${after.length}, expected ${before.length + 1}`);
     }

package/dist/clonePlan.js.map

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

package/dist/config.d.ts

@@ -1,5 +1,7 @@
 /** Per-user config file shared by every MCP host on the machine. */
 export declare const USER_ENV_FILE: string;
+declare const LOG_LEVELS: readonly ["error", "warn", "info", "debug"];
+export type LogLevel = (typeof LOG_LEVELS)[number];
 export declare const config: {
     readonly apiKey: string | undefined;
     readonly wsPort: number;
@@ -9,7 +11,9 @@ export declare const config: {
     readonly exportCacheMs: number;
     readonly prettyJson: boolean;
     readonly readOnly: boolean;
+    readonly updateCheck: boolean;
     readonly snapshotDir: string;
     readonly logLevel: "error" | "warn" | "info" | "debug";
 };
 export type Config = typeof config;
+export {};

package/dist/config.js

@@ -23,6 +23,36 @@ function optionalInt(name, fallback) {
     }
     return value;
 }
+/** A listen port: all digits, 1 to 65535. parseInt alone would accept
+ * "8788abc" and bind whatever number it reads out of it. */
+function portFromEnv(name, fallback) {
+    const raw = process.env[name];
+    if (!raw)
+        return fallback;
+    const value = /^\d+$/.test(raw.trim()) ? Number(raw.trim()) : NaN;
+    if (!Number.isInteger(value) || value < 1 || value > 65535) {
+        throw new Error(`Invalid value for ${name}: "${raw}" (expected a port number from 1 to 65535)`);
+    }
+    return value;
+}
+const LOG_LEVELS = ["error", "warn", "info", "debug"];
+/** The configured log level; anything else falls back to info. */
+function logLevel() {
+    const raw = process.env.LOG_LEVEL;
+    return LOG_LEVELS.includes(raw) ? raw : "info";
+}
+/** The app origin the browser executors come from; it must parse as a URL
+ * because the connection handler derives the allowed origin from it. */
+function appUrl() {
+    const raw = optional("PL_APP_URL", "https://app.projectionlab.com");
+    try {
+        new URL(raw);
+    }
+    catch {
+        throw new Error(`Invalid value for PL_APP_URL: "${raw}" (expected an absolute URL)`);
+    }
+    return raw;
+}
 function optionalBoolean(name) {
     const value = process.env[name];
     if (value === undefined)
@@ -41,11 +71,13 @@ export const config = {
     // what is missing; operations that need the key reject without it.
     apiKey: process.env.PL_API_KEY || undefined,
     // Localhost WebSocket the browser extension (or bootstrap snippet) connects
-    // to. The token is a shared secret the executor must present; if unset,
-    // ExtensionBridge generates one and persists it under the snapshot dir.
-    wsPort: optionalInt("PL_WS_PORT", 8788),
-    wsToken: process.env.PL_WS_TOKEN,
-    appUrl: optional("PL_APP_URL", "https://app.projectionlab.com"),
+    // to. The token is a shared secret the executor must present; if unset or
+    // blank, ExtensionBridge generates one and persists it next to
+    // USER_ENV_FILE. A blank value never counts as a token: it would let any
+    // client authenticate with an empty string.
+    wsPort: portFromEnv("PL_WS_PORT", 8788),
+    wsToken: process.env.PL_WS_TOKEN?.trim() || undefined,
+    appUrl: appUrl(),
     apiReadyTimeoutMs: optionalInt("PL_API_READY_TIMEOUT_MS", 30000),
     // How long a full export may be served from cache. Writes always invalidate,
     // so this can be generous for read-heavy analysis sessions.
@@ -54,7 +86,10 @@ export const config = {
     prettyJson: optionalBoolean("PL_PRETTY_JSON") ?? false,
     // Writes stay disabled unless PL_READ_ONLY is exactly "false".
     readOnly: (process.env.PL_READ_ONLY ?? "").trim().toLowerCase() !== "false",
+    // On unless PL_UPDATE_CHECK is exactly "false"; the only registry request
+    // the server makes is the one this gates.
+    updateCheck: (process.env.PL_UPDATE_CHECK ?? "").trim().toLowerCase() !== "false",
     snapshotDir: expandHome(optional("PL_SNAPSHOT_DIR", "~/.projectionlab-mcp/snapshots")),
-    logLevel: optional("LOG_LEVEL", "info"),
+    logLevel: logLevel(),
 };
 //# sourceMappingURL=config.js.map

package/dist/config.js.map

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

package/dist/currentFinances.d.ts

@@ -1,5 +1,5 @@
 import { ProjectionLabError } from "./errors.js";
-import type { PlanObj } from "./plans.js";
+import { type PlanObj } from "./plans.js";
 export declare const CURRENT_FINANCE_COLLECTIONS: readonly ["investmentAccounts", "savingsAccounts", "debts", "assets"];
 export interface CurrentFinanceEntry {
     collection: (typeof CURRENT_FINANCE_COLLECTIONS)[number];
@@ -10,3 +10,14 @@ export declare function listCurrentFinanceEntries(today: unknown): CurrentFinanc
 export declare function findCurrentFinanceEntry(today: unknown, accountId: string): CurrentFinanceEntry | undefined;
 export declare function requireCurrentFinances(today: unknown): PlanObj;
 export declare function currentFinanceAccountNotFoundError(today: unknown, accountId: string): ProjectionLabError;
+/**
+ * Problems for a Current Finances read taken before a write and one taken after
+ * it: an id-bearing account the second read dropped or added, and a money field
+ * that no longer holds the value the first read saw. Accounts are matched by
+ * collection and id, so a reordered list, an account without an id, and a field
+ * the first read did not carry never read as a change. A first read that is not
+ * an object, or that holds no id-bearing account, has nothing to compare; an
+ * id-bearing baseline that the second read does not return as an object is
+ * itself the problem.
+ */
+export declare function currentFinancesProblems(before: unknown, after: unknown): string[];

package/dist/currentFinances.js

@@ -1,4 +1,5 @@
 import { ProjectionLabError } from "./errors.js";
+import { containsSubset } from "./plans.js";
 export const CURRENT_FINANCE_COLLECTIONS = [
     "investmentAccounts",
     "savingsAccounts",
@@ -40,4 +41,63 @@ export function currentFinanceAccountNotFoundError(today, accountId) {
     const count = listCurrentFinanceEntries(today).length;
     return new ProjectionLabError("INVALID_INPUT", `No Current Finances account with ID "${accountId}" found`, `Call projectionlab_get_current_finances to inspect the ${count} available account record(s)`);
 }
+/** The money fields of a Current Finances account. */
+const BALANCE_FIELDS = ["balance", "amount", "value", "costBasis"];
+/** The id-bearing accounts of one read, keyed by collection and id. */
+function accountsById(today) {
+    const accounts = new Map();
+    for (const entry of listCurrentFinanceEntries(today)) {
+        const id = String(entry.account.id ?? "");
+        if (id)
+            accounts.set(`${entry.collection} ${id}`, entry.account);
+    }
+    return accounts;
+}
+/**
+ * Problems for a Current Finances read taken before a write and one taken after
+ * it: an id-bearing account the second read dropped or added, and a money field
+ * that no longer holds the value the first read saw. Accounts are matched by
+ * collection and id, so a reordered list, an account without an id, and a field
+ * the first read did not carry never read as a change. A first read that is not
+ * an object, or that holds no id-bearing account, has nothing to compare; an
+ * id-bearing baseline that the second read does not return as an object is
+ * itself the problem.
+ */
+export function currentFinancesProblems(before, after) {
+    if (!before || typeof before !== "object" || Array.isArray(before))
+        return [];
+    const beforeAccounts = accountsById(before);
+    if (beforeAccounts.size === 0)
+        return [];
+    if (!after || typeof after !== "object" || Array.isArray(after)) {
+        return ["Current Finances is missing from the re-read"];
+    }
+    const afterAccounts = accountsById(after);
+    const problems = [];
+    for (const [label, account] of beforeAccounts) {
+        const current = afterAccounts.get(label);
+        if (!current) {
+            problems.push(`Current Finances ${label} is missing`);
+            continue;
+        }
+        for (const field of BALANCE_FIELDS) {
+            const value = account[field];
+            if (value === undefined || value === null)
+                continue;
+            const now = current[field];
+            if (now === undefined || now === null) {
+                problems.push(`Current Finances ${label} lost its ${field}`);
+            }
+            else if (!containsSubset(value, now)) {
+                problems.push(`Current Finances ${label} ${field} changed from ${JSON.stringify(value)} to ${JSON.stringify(now)}`);
+            }
+        }
+    }
+    for (const label of afterAccounts.keys()) {
+        if (!beforeAccounts.has(label)) {
+            problems.push(`Current Finances ${label} was added`);
+        }
+    }
+    return problems;
+}
 //# sourceMappingURL=currentFinances.js.map

package/dist/currentFinances.js.map

@@ -1 +1 @@
-{"version":3,"file":"currentFinances.js","sourceRoot":"","sources":["../src/currentFinances.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAGjD,MAAM,CAAC,MAAM,2BAA2B,GAAG;IACzC,oBAAoB;IACpB,iBAAiB;IACjB,OAAO;IACP,QAAQ;CACA,CAAC;AAQX,MAAM,UAAU,yBAAyB,CACvC,KAAc;IAEd,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAC3E,MAAM,IAAI,GAAG,KAAgB,CAAC;IAC9B,MAAM,OAAO,GAA0B,EAAE,CAAC;IAC1C,KAAK,MAAM,UAAU,IAAI,2BAA2B,EAAE,CAAC;QACrD,MAAM,MAAM,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC;QAChC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;YAAE,SAAS;QACrC,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC;YACnD,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;YAC5B,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;gBAChE,OAAO,CAAC,IAAI,CAAC;oBACX,UAAU;oBACV,KAAK;oBACL,OAAO,EAAE,KAAgB;iBAC1B,CAAC,CAAC;YACL,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,UAAU,uBAAuB,CACrC,KAAc,EACd,SAAiB;IAEjB,OAAO,yBAAyB,CAAC,KAAK,CAAC,CAAC,IAAI,CAC1C,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,CAAC,KAAK,SAAS,CACxD,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,KAAc;IACnD,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAChE,MAAM,IAAI,kBAAkB,CAC1B,eAAe,EACf,iDAAiD,EACjD,gDAAgD,CACjD,CAAC;IACJ,CAAC;IACD,OAAO,KAAgB,CAAC;AAC1B,CAAC;AAED,MAAM,UAAU,kCAAkC,CAChD,KAAc,EACd,SAAiB;IAEjB,MAAM,KAAK,GAAG,yBAAyB,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC;IACtD,OAAO,IAAI,kBAAkB,CAC3B,eAAe,EACf,wCAAwC,SAAS,SAAS,EAC1D,0DAA0D,KAAK,8BAA8B,CAC9F,CAAC;AACJ,CAAC"}
+{"version":3,"file":"currentFinances.js","sourceRoot":"","sources":["../src/currentFinances.ts"],"names":[],"mappings":"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"}

package/dist/dataModel.d.ts

@@ -0,0 +1,58 @@
+import { ProjectionLabError } from "./errors.js";
+/**
+ * Verified field knowledge for the values this server reads and writes.
+ * Single source for the `projectionlab://data-model` resource, the
+ * `listPaths` annotations, and the enum refusals in the shared write path.
+ *
+ * Entries carry evidence:
+ * - "observed": a value was set through the UI and the stored value was
+ *   read back (or matched field-for-field against a known plan).
+ * - "ui-label": the control was seen in the UI but not confirmed by a
+ *   stored-value test.
+ * Only fields confirmed against ProjectionLab 4.6.0 are listed; fields known
+ * from names alone are left out entirely.
+ */
+export declare const DATA_MODEL_PROJECTIONLAB_VERSION = "4.6.0";
+export type DataModelEvidence = "observed" | "ui-label";
+export interface DataModelField {
+    description: string;
+    /** Scale for numeric fields, e.g. "percentage points" or "decimal fraction". */
+    units?: string;
+    /** Complete set of values an enum field accepts. */
+    allowedValues?: readonly string[];
+    /** Which other field must be set for this field to matter. */
+    enabledBy?: string;
+    note?: string;
+    evidence: DataModelEvidence;
+}
+export interface DataModelGroup {
+    /** Prefix the paths are listed and written under: a settings section,
+     * an event section, or a Current Finances collection. */
+    scope: string;
+    title: string;
+    fields: Record<string, DataModelField>;
+}
+export declare const DATA_MODEL_GROUPS: readonly DataModelGroup[];
+/** Field entry for a scope-prefixed concrete path, or undefined. */
+export declare function matchDataModelField(scope: string, path: string): DataModelField | undefined;
+export interface DataModelAnnotation {
+    description?: string;
+    units?: string;
+    allowedValues?: readonly string[];
+}
+/**
+ * Copy listed values, attaching description, units, and allowedValues for
+ * paths with a registry entry. Entries for unknown paths are returned
+ * unchanged, so existing listPaths fields never change.
+ */
+export declare function annotateAddressableValues<T extends {
+    path: string;
+}>(scope: string | undefined, values: readonly T[]): (T & DataModelAnnotation)[];
+/**
+ * Choices to refuse a value over: an observed enum's list when value is a
+ * string outside it. undefined when no refusal applies. Numeric and boolean
+ * values are never refused; ui-label enums are annotated but not enforced.
+ */
+export declare function refusedEnumChoices(scope: string | undefined, path: string, value: unknown): readonly string[] | undefined;
+/** Refusal for a value a write sets outside an observed enum's choices. */
+export declare function enumRefusalError(scope: string, path: string, value: unknown): ProjectionLabError | undefined;