cata-centavo 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marcus Xavier
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,159 @@
+<div align="center">
+
+<img src="https://github.com/user-attachments/assets/e990ea13-b266-4def-917f-afc15c1b4275" alt="cata-centavo" width="200" height="200">
+
+# Cata-centavo
+**Ask an agent about your own money.** Brazilian Open Finance data over [MCP](https://modelcontextprotocol.io), via [Pluggy](https://pluggy.ai).
+
+<p>
+  <a href="https://www.npmjs.com/package/cata-centavo"><img src="https://img.shields.io/npm/v/cata-centavo?logo=npm&logoColor=white&color=cb3837" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/cata-centavo"><img src="https://img.shields.io/npm/dm/cata-centavo?logo=npm&logoColor=white" alt="npm downloads"></a>
+  <a href="https://github.com/MarcusXavierr/cata-centavo/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/MarcusXavierr/cata-centavo/ci.yml?branch=main&logo=githubactions&logoColor=white&label=CI" alt="CI"></a>
+  <a href="https://github.com/MarcusXavierr/cata-centavo/blob/main/LICENSE"><img src="https://img.shields.io/github/license/MarcusXavierr/cata-centavo?color=blue" alt="MIT license"></a>
+  <img src="https://img.shields.io/badge/node-%3E%3D22.13-5FA04E?logo=nodedotjs&logoColor=white" alt="node >= 22.13">
+  <img src="https://img.shields.io/badge/MCP-server-0A7CFF" alt="MCP server">
+</p>
+
+<a href="#install">Install</a> ·
+<a href="#commands">Commands</a> ·
+<a href="#categories">Categories</a> ·
+<a href="#what-it-cannot-see">Limits</a> ·
+<a href="#tools">Tools</a> ·
+<a href="#license">License</a>
+
+</div>
+
+<p align="center">
+  <img width="855" height="352" alt="image" src="https://github.com/user-attachments/assets/ee489a5c-1024-4a93-b476-32dec8f6cad6" />
+</p>
+
+---
+
+Cata-centavo lets you ask an agent about your own money. Point it at your bank and credit card accounts and ask what you spent on food last month, how the current card statement is going, or where a strange charge came from.
+
+You run it on your machine, against your own accounts, and the categories you correct stay there. There is no hosted version and nothing multi-user about it.
+
+## Install
+
+You need Node 22.13 or newer, and a Pluggy account with your banks already connected.
+
+### Getting your Pluggy keys
+
+The bank data comes from [Pluggy](https://pluggy.ai), the Open Finance provider that does the talking to the banks. Cata-centavo only reads connections that already exist, so make them first.
+
+
+
+1. At [MeuPluggy](https://meu.pluggy.ai/en), create your account and connect your banks
+<img width="1530" height="617" alt="image" src="https://github.com/user-attachments/assets/15bde1c7-dfd9-4f9e-9f6b-e254522afd58" />
+
+2. Then go to the other [Pluggy portal](https://pluggy.ai/), log in, and connect your MeuPluggy accounts to the Demo app. Also copy your `PLUGGY_CLIENT_ID` and `PLUGGY_CLIENT_SECRET` from this page
+<img width="1918" height="595" alt="image" src="https://github.com/user-attachments/assets/be7670e9-35fc-4ea3-98d3-115298cd488f" />
+
+3. Then connect your MeuPluggy accounts one by one into the Demo App
+<img width="1206" height="813" alt="image" src="https://github.com/user-attachments/assets/66402550-ebeb-43ba-962b-3d091242e807" />
+
+
+4. And then copy the `PLUGGY_ITEM_IDS`, one by one
+<img width="1851" height="627" alt="image" src="https://github.com/user-attachments/assets/16fc1d2a-39b2-4531-9ae6-487ade128006" />
+
+
+That gives you three values, all required:
+
+```
+PLUGGY_CLIENT_ID        from your Pluggy dashboard
+PLUGGY_CLIENT_SECRET    from your Pluggy dashboard
+PLUGGY_ITEM_IDS         connection ids, separated by commas
+```
+
+The plain way is to export them from your `.zshrc` or `.bashrc`, and in the MCP configuration file write `"PLUGGY_CLIENT_ID": "${PLUGGY_CLIENT_ID}"`. That leaves your keys in a file every shell reads. If you would rather not, `secret-tool` keeps them in your keyring and a small wrapper script can pull them out right before the server starts. Setups differ enough that it is worth pointing your agent at this page and asking it which one fits your machine.
+
+After configuring this, run `npx cata-centavo doctor` to check that your environment variables are working
+
+<img width="894" height="191" alt="image" src="https://github.com/user-attachments/assets/adc2bb35-a161-4241-a33a-42846aa507a1" />
+
+
+### Adding it to Claude Code
+
+```bash
+claude mcp add cata-centavo \
+  -e PLUGGY_CLIENT_ID=... \
+  -e PLUGGY_CLIENT_SECRET=... \
+  -e PLUGGY_ITEM_IDS=... \
+  -- npx -y cata-centavo
+```
+
+Drop the `-e` flags if the three variables are already exported in the shell you start Claude Code from, since the server inherits that environment.
+
+Other clients take the same thing as JSON:
+
+```json
+{
+  "mcpServers": {
+    "cata-centavo": {
+      "command": "npx",
+      "args": ["-y", "cata-centavo"],
+      "env": {
+        "PLUGGY_CLIENT_ID": "...",
+        "PLUGGY_CLIENT_SECRET": "...",
+        "PLUGGY_ITEM_IDS": "..."
+      }
+    }
+  }
+}
+```
+
+## Commands
+
+- `cata-centavo` (no argument): runs the MCP server over stdio.
+- `cata-centavo init`: checks that the credentials and every configured connection are readable, and reports which ones are not.
+- `cata-centavo doctor`: a fuller diagnosis, covering connection status, consent state, what is cached locally, and whether the learned categorization map has anything in it yet.
+
+## Categories
+
+Categories come from your provider while your plan includes transaction enrichment. Every sync copies them into `data.db`, which is never dropped, so they survive the day the enrichment stops and the day the cache is rebuilt.
+
+Alongside that, the server learns which categories go with which CNPJs from your own transactions. Only from a CNPJ, never from a CPF, and only when that merchant's transactions actually agree. A CNPJ has a line of business. A CPF is a person, and guessing that everything you send your sister is a "transfer" would then be applied backwards over everything you ever sent her.
+
+That learned map is built from your data, on your machine, and is not shipped with the tool, because a CNPJ-to-category table is a line of somebody's bank statement. **So there is a real asymmetry: if you install this after your own enrichment has already stopped, the map starts empty and has nothing to learn from.** You still get merchant-code categorization on card purchases, plus whatever you correct by hand, and corrections apply retroactively. But you will be doing more of the work than someone who installed earlier.
+
+Ask the agent to show you what is uncategorized and tell it what those merchants are; both kinds of correction stick.
+
+## What it cannot see
+
+- A bank linked in MeuPluggy whose UUID never reached `PLUGGY_ITEM_IDS` is invisible to this server. No endpoint lists the items on a Pluggy account, so this cannot be fixed in software. Compare `doctor`'s list against the banks you know you linked.
+- Freshness is Pluggy's schedule, not this server's. There is no "sync now": on-demand refresh is refused outright. One of the author's own three connections went three days without syncing while still reporting itself up to date, with nothing in the response explaining why.
+- A credit card's `usedCredit` figure is not what the card owes this month. It mixes the current billing cycle with instalments that have not been charged yet, and will not match what a banking app shows. `getBillSummary` answers that question instead, and it answers with a range rather than one number.
+
+## Tools
+
+**Accounts and balances**
+- `getAccounts`: lists every account across your configured connections, with balances and credit card limits.
+- `getBalance`: consolidated cash and credit-used figures across all connections, reported separately because they are not the same kind of number.
+- `getBalanceByAccount`: the current figures and details for one account.
+
+**Spending**
+- `getTransactions`: totals spending and income over a date range, grouped by category.
+- `listTransactions`: individual transactions over a date range, paged.
+- `getTransactionDetails`: full details for a bounded set of transaction ids.
+
+**Credit cards**
+- `getBills`: statements for one card, newest first.
+- `getBillSummary`: the cycle still in progress, as two independent estimates rather than one invented number.
+- `setClosingDay`: records a card's closing day locally, for banks that do not report it.
+- `listClosingDays`: the closing days stored so far.
+- `deleteClosingDay`: drops a stored closing day.
+
+**Categories**
+- `setCategory`: corrects the category of specific transactions.
+- `setCounterpartyCategory`: assigns a category to everyone a CPF or CNPJ identifies, backwards and forwards.
+
+**Diagnostics**
+- `listSources`: lists every configured connection with its sync status and consent state.
+
+Each tool's exact parameters and return shape are published in its own MCP description, which is what a model actually reads and the one version that cannot drift out of sync with a signature.
+
+Instalment purchases do not have a tool of their own yet. Card transactions do carry instalment metadata, so `getTransactionDetails` will show it per transaction, but nothing reconstructs a purchase across its instalments.
+
+## License
+
+MIT. See [LICENSE](https://github.com/MarcusXavierr/cata-centavo/blob/main/LICENSE).

package/dist/bin/cata-centavo.js

@@ -0,0 +1,226 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { COMMANDS, resolveInvocation } from "../cli/dispatch.js";
+import * as doctor from "../cli/doctor.js";
+import { exitCodeFor, formatInit, runInit } from "../cli/init.js";
+import { loadConfig, resolvePaths } from "../config.js";
+import { createLogger } from "../logging.js";
+import { createServer } from "../mcp/server.js";
+import { createTransactionReader } from "../core/transactions.js";
+import { createPluggyClient } from "../pluggy/client.js";
+import { toFailure } from "../pluggy/errors.js";
+import { createCategoryWriter } from "../storage/categories.js";
+import { createClosingDayStore } from "../storage/closing-days.js";
+import { createTransactionStore } from "../storage/transactions.js";
+import { readLocalState } from "../storage/diagnostics.js";
+import { openDatabases, schemaVersion } from "../storage/db.js";
+const USAGE = `cata-centavo — Brazilian Open Finance over MCP
+
+Usage:
+  cata-centavo            MCP server over stdio (default mode)
+  cata-centavo init       validates the credentials and every configured connection
+  cata-centavo doctor     diagnostics: consent, connection status, last sync
+
+Options:
+  -h, --help              show this help
+  -v, --version           show the version
+
+Configuration comes from the environment:
+  PLUGGY_CLIENT_ID        from your Pluggy dashboard
+  PLUGGY_CLIENT_SECRET    from your Pluggy dashboard
+  PLUGGY_ITEM_IDS         connection ids from MeuPluggy, separated by commas
+
+An MCP client does not read your shell profile, so declare these in the "env"
+block of its config as well.
+`;
+/**
+ * We read package.json at runtime rather than with `import ... with { type: "json" }`.
+ * An import would enter the tsc module graph and clash with "rootDir": "src".
+ * With `new URL(..., import.meta.url)` the path resolves identically whether we
+ * run from src/bin/ or dist/bin/ — both sit two levels below the package root.
+ */
+function readVersion() {
+    const raw = readFileSync(new URL("../../package.json", import.meta.url), "utf8");
+    const parsed = JSON.parse(raw);
+    if (typeof parsed === "object" && parsed !== null && "version" in parsed) {
+        const { version } = parsed;
+        if (typeof version === "string")
+            return version;
+    }
+    return "unknown";
+}
+/**
+ * ADR §4: nothing but JSON-RPC may reach stdout, because in server mode stdout
+ * *is* the protocol channel. All human-facing output goes to stderr.
+ */
+function say(message) {
+    if (message.endsWith("\n")) {
+        process.stderr.write(message);
+    }
+    else {
+        process.stderr.write(`${message}\n`);
+    }
+}
+const systemClock = { now: () => new Date() };
+/** Creates both files, runs their migrations, and lets go of the handles. */
+function prepareStorage(paths) {
+    const databases = openDatabases(paths);
+    try {
+        return {
+            cacheDb: paths.cacheDb,
+            dataDb: paths.dataDb,
+            cacheVersion: schemaVersion(databases.db),
+            dataVersion: schemaVersion(databases.db, "userdata"),
+        };
+    }
+    finally {
+        databases.close();
+    }
+}
+const sleep = (milliseconds) => new Promise((resolve) => {
+    setTimeout(resolve, milliseconds);
+});
+/** Builds the source the server runs against, or the problems that block it, from a loaded config. */
+function toSource(result, log, services) {
+    if (!result.ok) {
+        return { ok: false, problems: result.problems };
+    }
+    if (services === undefined) {
+        const problem = "Local transaction cache is unavailable.";
+        return { ok: false, problems: [problem], databaseProblems: [problem] };
+    }
+    return {
+        ok: true,
+        connections: result.config.itemIds,
+        bank: createPluggyClient({
+            credentials: result.config.credentials,
+            clock: systemClock,
+            fetch: globalThis.fetch,
+            sleep,
+            log,
+        }),
+        toFailure,
+        reader: services.reader,
+        writer: services.writer,
+        closingDays: services.closingDays,
+    };
+}
+function describe(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return String(error);
+}
+function closeOnShutdown(databases) {
+    let closed = false;
+    const close = () => {
+        if (closed) {
+            return;
+        }
+        closed = true;
+        databases.close();
+    };
+    process.once("SIGINT", close);
+    process.once("SIGTERM", close);
+}
+async function run(command) {
+    if (command === COMMANDS.init) {
+        const paths = resolvePaths(process.env, { platform: process.platform, home: homedir() });
+        const log = createLogger({ env: process.env, logFile: paths.logFile });
+        const report = await runInit({
+            env: process.env,
+            prepareStorage: () => prepareStorage(paths),
+            createBank: (credentials) => createPluggyClient({ credentials, clock: systemClock, fetch: globalThis.fetch, sleep, log }),
+        });
+        for (const line of formatInit(report, systemClock)) {
+            say(line);
+        }
+        return exitCodeFor(report);
+    }
+    if (command === COMMANDS.doctor) {
+        const paths = resolvePaths(process.env, { platform: process.platform, home: homedir() });
+        const log = createLogger({ env: process.env, logFile: paths.logFile });
+        const report = await doctor.runDoctor({
+            env: process.env,
+            createBank: (credentials) => createPluggyClient({ credentials, clock: systemClock, fetch: globalThis.fetch, sleep, log }),
+            readLocalState: () => readLocalStateOf(paths),
+            toFailure,
+            clock: systemClock,
+        });
+        for (const line of doctor.formatDoctor(report, systemClock)) {
+            say(line);
+        }
+        return doctor.exitCodeFor(report);
+    }
+    return runServe();
+}
+/** Opens both files, reads their diagnostic state, and closes them again. */
+function readLocalStateOf(paths) {
+    const databases = openDatabases(paths);
+    try {
+        return readLocalState(databases.db);
+    }
+    finally {
+        databases.close();
+    }
+}
+async function runServe() {
+    const paths = resolvePaths(process.env, { platform: process.platform, home: homedir() });
+    const log = createLogger({ env: process.env, logFile: paths.logFile });
+    const source = createServeSource(loadConfig(process.env), paths, log);
+    await createServer({ source, version: readVersion(), log }).connect(new StdioServerTransport());
+    return 0;
+}
+function createServeSource(result, paths, log) {
+    if (!result.ok) {
+        return toSource(result, log);
+    }
+    try {
+        const databases = openDatabases(paths);
+        closeOnShutdown(databases);
+        return createReadySource(result, databases, log);
+    }
+    catch (error) {
+        const problem = `Local storage is unavailable: ${describe(error)}`;
+        return { ok: false, problems: [problem], databaseProblems: [problem] };
+    }
+}
+function createReadySource(result, databases, log) {
+    const bank = createPluggyClient({
+        credentials: result.config.credentials,
+        clock: systemClock,
+        fetch: globalThis.fetch,
+        sleep,
+        log,
+    });
+    const reader = createTransactionReader({
+        bank,
+        store: createTransactionStore(databases.db, log),
+        toFailure,
+        log,
+        clock: systemClock,
+    });
+    const writer = createCategoryWriter(databases.db, systemClock);
+    const closingDays = createClosingDayStore(databases.db, systemClock);
+    return toSource(result, log, { reader, writer, closingDays });
+}
+const invocation = resolveInvocation(process.argv.slice(2));
+switch (invocation.kind) {
+    case "help":
+        say(USAGE);
+        break;
+    case "version":
+        say(readVersion());
+        break;
+    case "error":
+        say(`error: ${invocation.message}\n`);
+        say(USAGE);
+        process.exitCode = 2;
+        break;
+    case "command":
+        process.exitCode = await run(invocation.command);
+        break;
+}
+//# sourceMappingURL=cata-centavo.js.map

package/dist/bin/cata-centavo.js.map

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

package/dist/cli/dispatch.js

@@ -0,0 +1,67 @@
+import { parseArgs } from "node:util";
+/**
+ * A `const` object plus a derived union, instead of `enum`.
+ *
+ * ADR §13 recommends this: `enum` is not erasable syntax, so `erasableSyntaxOnly`
+ * rejects it — and a TS string enum is *nominal*, meaning a string arriving from
+ * JSON cannot be assigned to it without a cast, precisely where we want real
+ * validation instead.
+ */
+export const COMMANDS = {
+    init: "init",
+    doctor: "doctor",
+    serve: "serve",
+};
+function isCommand(value) {
+    return Object.hasOwn(COMMANDS, value);
+}
+/**
+ * Translates argv into an intent. Pure: reads no environment, writes nowhere,
+ * never exits the process. That is what makes it testable.
+ */
+export function resolveInvocation(argv) {
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: [...argv],
+            options: {
+                help: { type: "boolean", short: "h" },
+                version: { type: "boolean", short: "v" },
+            },
+            allowPositionals: true,
+            strict: true,
+        });
+    }
+    catch (error) {
+        // parseArgs throws on an unknown flag. Returning it as a value keeps this
+        // function pure and leaves the choice of how to fail with the caller.
+        let message;
+        if (error instanceof Error) {
+            message = error.message;
+        }
+        else {
+            message = String(error);
+        }
+        return { kind: "error", message };
+    }
+    if (parsed.values.help === true)
+        return { kind: "help" };
+    if (parsed.values.version === true)
+        return { kind: "version" };
+    return commandFrom(parsed.positionals);
+}
+function commandFrom(positionals) {
+    const [first, ...rest] = positionals;
+    if (rest.length > 0) {
+        return { kind: "error", message: `unexpected argument: ${rest[0]}` };
+    }
+    // No argument = MCP server over stdio (ADR §4).
+    if (first === undefined) {
+        return { kind: "command", command: COMMANDS.serve };
+    }
+    if (!isCommand(first)) {
+        return { kind: "error", message: `unknown command: ${first}` };
+    }
+    return { kind: "command", command: first };
+}
+//# sourceMappingURL=dispatch.js.map

package/dist/cli/dispatch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch.js","sourceRoot":"","sources":["../../src/cli/dispatch.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG;IACtB,IAAI,EAAE,MAAM;IACZ,MAAM,EAAE,QAAQ;IAChB,KAAK,EAAE,OAAO;CACN,CAAC;AAWX,SAAS,SAAS,CAAC,KAAa;IAC9B,OAAO,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;AACxC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAuB;IACvD,IAAI,MAAM,CAAC;IACX,IAAI,CAAC;QACH,MAAM,GAAG,SAAS,CAAC;YACjB,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC;YACf,OAAO,EAAE;gBACP,IAAI,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,EAAE;gBACrC,OAAO,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,EAAE;aACzC;YACD,gBAAgB,EAAE,IAAI;YACtB,MAAM,EAAE,IAAI;SACb,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,0EAA0E;QAC1E,sEAAsE;QACtE,IAAI,OAAe,CAAC;QACpB,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;YAC3B,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;QAC1B,CAAC;aAAM,CAAC;YACN,OAAO,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;QAC1B,CAAC;QACD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;IACpC,CAAC;IAED,IAAI,MAAM,CAAC,MAAM,CAAC,IAAI,KAAK,IAAI;QAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IACzD,IAAI,MAAM,CAAC,MAAM,CAAC,OAAO,KAAK,IAAI;QAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;IAE/D,OAAO,WAAW,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;AACzC,CAAC;AAED,SAAS,WAAW,CAAC,WAA8B;IACjD,MAAM,CAAC,KAAK,EAAE,GAAG,IAAI,CAAC,GAAG,WAAW,CAAC;IAErC,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACpB,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,wBAAwB,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;IACvE,CAAC;IAED,gDAAgD;IAChD,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,QAAQ,CAAC,KAAK,EAAE,CAAC;IACtD,CAAC;IAED,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;QACtB,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,oBAAoB,KAAK,EAAE,EAAE,CAAC;IACjE,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;AAC7C,CAAC"}

package/dist/cli/doctor.js

@@ -0,0 +1,178 @@
+import { loadConfig } from "../config.js";
+import { diagnose } from "../core/diagnose.js";
+import { describeSync, relativeAgo } from "./sync.js";
+export async function runDoctor(deps) {
+    const config = loadConfig(deps.env);
+    if (!config.ok) {
+        return { kind: "config", problems: config.problems };
+    }
+    let localState;
+    try {
+        localState = deps.readLocalState();
+    }
+    catch (error) {
+        return { kind: "storage", reason: describe(error) };
+    }
+    const bank = deps.createBank(config.config.credentials);
+    try {
+        await bank.verifyCredentials();
+    }
+    catch (error) {
+        return { kind: "credentials", localState, reason: describe(error) };
+    }
+    const diagnoses = await diagnose(bank, config.config.itemIds, deps.toFailure, deps.clock);
+    return { kind: "checked", localState, diagnoses };
+}
+function isUsable(diagnosis) {
+    return diagnosis.connection !== null && diagnosis.state !== "revoked" && diagnosis.state !== "expired";
+}
+export function exitCodeFor(report) {
+    switch (report.kind) {
+        case "config":
+            return 2;
+        case "storage":
+        case "credentials":
+            return 1;
+        case "checked":
+            if (report.diagnoses.every(isUsable)) {
+                return 0;
+            }
+            return 1;
+    }
+}
+/** Lines for stderr. Nothing here may reach stdout (ADR §4). */
+export function formatDoctor(report, clock) {
+    switch (report.kind) {
+        case "config":
+            return ["✗ configuration is incomplete", ...report.problems.map((problem) => `  ${problem}`)];
+        case "storage":
+            return [`✗ local storage is unreadable: ${report.reason}`];
+        case "credentials":
+            return [
+                ...formatStorage(report.localState),
+                "",
+                ...formatCache(report.localState, clock),
+                "",
+                ...formatCategorization(report.localState),
+                "",
+                `✗ ${report.reason}`,
+            ];
+        case "checked":
+            return formatChecked(report, clock);
+    }
+}
+function formatChecked(report, clock) {
+    const usable = report.diagnoses.filter(isUsable).length;
+    return [
+        "connections",
+        ...report.diagnoses.flatMap((diagnosis) => formatConnection(diagnosis, clock)),
+        "",
+        ...formatStorage(report.localState),
+        "",
+        ...formatCache(report.localState, clock),
+        "",
+        ...formatCategorization(report.localState),
+        "",
+        `${usable} of ${report.diagnoses.length} connections are usable`,
+    ];
+}
+function formatConnection(diagnosis, clock) {
+    if (diagnosis.connection === null) {
+        return [`  ✗ ${diagnosis.id} — ${diagnosis.failure?.message ?? "unknown failure"}`];
+    }
+    if (diagnosis.state === "revoked") {
+        return [`  ✗ ${diagnosis.id} — ${revokedReason(diagnosis.consent, diagnosis.id)}`];
+    }
+    if (diagnosis.state === "expired") {
+        return [`  ✗ ${diagnosis.id} — ${expiredReason(diagnosis.consent, diagnosis.id)}`];
+    }
+    return formatUsableConnection(diagnosis, diagnosis.connection, clock);
+}
+function revokedReason(consent, id) {
+    if (consent?.revokedAt === undefined || consent.revokedAt === null) {
+        return `${id} has an unreadable consent`;
+    }
+    return `consent revoked on ${dateOnly(consent.revokedAt)}; re-link this connection to restore access.`;
+}
+function expiredReason(consent, id) {
+    if (consent?.expiresAt === undefined || consent.expiresAt === null) {
+        return `${id} has an unreadable consent`;
+    }
+    return `consent expired on ${dateOnly(consent.expiresAt)}.`;
+}
+function connectionMarker(connection) {
+    if (connection.warnings.length > 0) {
+        return "!";
+    }
+    return "✓";
+}
+function formatUsableConnection(diagnosis, connection, clock) {
+    const { id, state, consent } = diagnosis;
+    const sync = describeSync(connection.lastUpdatedAt, clock.now());
+    return [
+        `  ${connectionMarker(connection)} ${id}  ${connection.institution}  ${connection.status}  ${sync}`,
+        `           ${consentLine(state, consent)}`,
+        ...connection.warnings.map((warning) => `    ${warning}`),
+    ];
+}
+function consentLine(state, consent) {
+    if (consent === null) {
+        return `consent: ${state}`;
+    }
+    return `consent: ${state}, ${consent.products.length} products`;
+}
+function dateOnly(date) {
+    return date.toISOString().slice(0, 10);
+}
+function formatStorage(state) {
+    return [
+        "storage",
+        `  ✓ cache  v${state.cacheVersion}  ${state.cacheDb}`,
+        `  ✓ data   v${state.dataVersion}  ${state.dataDb}`,
+    ];
+}
+function formatCache(state, clock) {
+    return [
+        "cache",
+        `  ${cacheSummaryLine(state)}`,
+        ...[...state.perConnection.entries()].map(([connectionId, entry]) => formatCacheConnection(connectionId, entry, clock)),
+    ];
+}
+function cacheSummaryLine(state) {
+    if (state.newestLocalDate === null) {
+        return "no transactions cached yet";
+    }
+    return `${state.accountsWalked} accounts walked, newest transaction ${state.newestLocalDate}`;
+}
+function formatCacheConnection(connectionId, entry, clock) {
+    const oldestWalkDate = oldestWalkDateOf(entry.oldestWalk);
+    return `  ${connectionId}  ${entry.accounts} accounts, oldest walk ${relativeAgo(oldestWalkDate, clock.now())}`;
+}
+function oldestWalkDateOf(oldestWalk) {
+    if (oldestWalk === null) {
+        return null;
+    }
+    return new Date(oldestWalk);
+}
+function merchantCodesLine(mccRows) {
+    if (mccRows > 0) {
+        return "merchant codes present";
+    }
+    return "merchant codes missing";
+}
+function formatCategorization(state) {
+    const merchantLine = merchantCodesLine(state.mccRows);
+    return [
+        "categorization",
+        `  snapshot      ${state.snapshotRows} transactions`,
+        `  counterparty  ${state.counterpartyDocuments} documents`,
+        `  ${merchantLine}`,
+    ];
+}
+function describe(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return String(error);
+}
+//# sourceMappingURL=doctor.js.map