imprnt-plugin-kopeika 0.1.0

package/README.md

@@ -0,0 +1,115 @@
+# imprnt-plugin-kopeika
+
+A deterministic, local-first personal-finance and net-worth CLI, packaged as an imprnt plugin. It
+parses bank CSV exports into one clean, deduplicated ledger, categorizes via ratified rules, tracks
+savings, and projects net worth, then renders a self-contained bilingual dashboard. No LLM touches a
+row at runtime. All personal data lives in the plugin's own `data/` folder (local only, never on a remote), never in a vault note.
+
+It is a sibling of [imprnt](https://github.com/aleksandr-bogdanov/imprnt). The shared idea: the LLM
+builds the tools at authoring time, the deterministic tools do the work at runtime, and verification is
+structural (golden tests plus reconcilable invariants). The problem it answers is the ZenMoney one:
+categorize each merchant once and it is automatic forever, with no per-transaction manual entry and no
+untrustworthy auto-categorization.
+
+## Install
+
+```bash
+imprnt plugin add kopeika
+```
+
+This fetches the package, copies it to `plugins/kopeika/` in your project, and wires
+`@plugins/kopeika/agent.md` into `CLAUDE.local.md` (gitignored, per-machine). To wire it by hand
+instead, add `@plugins/kopeika/agent.md` to `CLAUDE.local.md` yourself.
+
+Then create your profile: copy `plugins/kopeika/profile.example.json` to
+`plugins/kopeika/data/profile.json` and fill it in (see Profile below). Without a profile the tool
+runs in generic mode (raw labels, no net-worth layer).
+
+## Remove
+
+```bash
+imprnt plugin rm kopeika           # unwire it
+imprnt plugin rm kopeika --purge   # and delete plugins/kopeika/
+```
+
+## The monthly run
+
+kopeika does not take hand-typed transactions. You feed it the bank's CSV exports. Commands run as
+`imprnt kopeika <cmd>` (the core dispatches to `node plugins/kopeika/kopeika.js`).
+
+1. **Export** a fresh CSV from each account (re-importing an overlap is a safe no-op, dedup handles it).
+2. **Import** each file with its stable `--account` label:
+   ```bash
+   imprnt kopeika import <revolut|n26|trading212|tbank|alfa> <file> --account <label> --owner <owner>
+   ```
+3. **Categorize and match transfers:**
+   ```bash
+   imprnt kopeika categorize          # applies data/rules.csv
+   imprnt kopeika transfers           # pairs internal account-to-account legs
+   imprnt kopeika categorize --review # the one judgement step: new merchants by spend
+   ```
+   For each new merchant worth a label, add one line to `data/rules.csv` and re-run `categorize`.
+4. **Verify:** `imprnt kopeika report` and `imprnt kopeika project`.
+
+### Correcting an existing transaction
+
+The ledger is derived, so you rarely hand-edit a row. You change the data file that governs it, then
+re-run:
+
+| You want to change | Edit | Then |
+|---|---|---|
+| A wrong or blank category | `data/rules.csv` (one rule) | `categorize` |
+| Floor vs flex of a category | `data/tiers.csv` | nothing, `report` reads it live |
+| A savings destination | `data/savings.csv` | `project` |
+| A merchant display name / note, or net-worth marks | `data/profile.json` | re-render |
+
+A clean reset is `rm data/ledger.csv` then re-import every account.
+
+## Commands
+
+```
+imprnt kopeika import <revolut|n26|trading212|tbank|alfa> <file> --account <name> --owner <owner>
+imprnt kopeika categorize [--review]
+imprnt kopeika transfers
+imprnt kopeika recurring [--min-months N] [--from YYYY-MM]
+imprnt kopeika list [--source <x>] [--uncategorized] [--month YYYY-MM]
+imprnt kopeika report [--month YYYY-MM] [--from YYYY-MM] [--html <path> --lang <en|ru>]
+imprnt kopeika project [--rate <eur/mo>] [--lump-sum <eur>] [--years N]
+```
+
+`report --html <path> --lang <en|ru>` writes the self-contained dashboard. The deep model (raw vs
+clean, stock vs flow, the two axes, net worth, projection) is in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
+
+## Data files (all under `plugins/kopeika/data/`, local only)
+
+| File | Format |
+|------|--------|
+| `data/raw/<source>/` | archived immutable original exports |
+| `data/ledger.csv` | clean normalized ledger |
+| `data/rules.csv` | `pattern,match_type,field,category,type` |
+| `data/rates.csv` | `month,currency,rate_to_eur` |
+| `data/tiers.csv` | `scope,value,tier` (tier `mandatory` = floor, else flex) |
+| `data/savings.csv` | `scope,value,balance_eur` (`account` cost basis, `marker` pot, `anchor` manual) |
+| `data/profile.json` | your personal layer (see Profile) |
+
+## Profile
+
+Every personal fact lives in `data/profile.json`, kept local (never on a remote). The code ships generic. Copy
+`profile.example.json` and fill in: `owners` (allowed `--owner` labels), `ownNames` / `ownIbans` (for
+internal-transfer detection), `netWorth` (`flatsRub`, `mortgageRub`, `bcsNominalCny`, `propertyApr`),
+`accountLabels`, `merchantInfo`, and `footer`. Every field is optional. A missing profile runs in
+generic mode. Nothing here is hardcoded in the source, so the package carries no personal data.
+
+## Privacy
+
+Your `data/` folder holds raw financial data: the bank exports, the clean ledger, and
+`data/profile.json` with your names, IBANs, and net-worth marks. The one hard rule is that **it must
+never reach a remote.**
+
+There are two safe setups. In a private, remoteless store like the imprnt vault, `data/` is committed
+as the canonical source of truth - that is the intended arrangement, and the data never leaves the
+machine because the repo has no remote. Anywhere a remote exists, gitignore `data/` so it is never
+committed. `check.js` enforces exactly this: it fails if `data/` is tracked in a repo that has a
+remote, and passes otherwise. The published package itself ships no personal data (only the generic
+code and `profile.example.json`). The rendered `deploy/` bundle is derived, so it stays local. The
+hosted page carries no account numbers, IBANs, or balances, and sits behind a password.

package/agent.md

@@ -0,0 +1,89 @@
+# Plugin: Kopeika (personal finance & net worth)
+
+> The agent fragment — the plugin's entry point. The core never reads it; you (the assistant) do.
+> Install = `imprnt plugin add kopeika`, which wires `@plugins/kopeika/agent.md` into `CLAUDE.local.md`
+> (gitignored, per-machine). Remove = `imprnt plugin rm kopeika` (add `--purge` to delete the folder).
+
+## What this plugin is
+
+A deterministic, local-first personal-finance and net-worth CLI. It parses bank CSV exports into one
+clean, deduplicated ledger, categorizes rows via ratified rules, matches internal transfers, tracks
+savings destinations, and projects net worth. It renders a self-contained bilingual HTML dashboard. No
+LLM ever touches a row at runtime, so the same exports always produce the same ledger, report, and
+dashboard. It is the local money tool that lives next to the vault, not inside it.
+
+## Where its data lives
+
+Everything personal stays inside this plugin folder, gitignored, never in a vault note:
+
+- `data/ledger.csv` — the clean normalized ledger, built from the raw exports.
+- `data/raw/<source>/` — the immutable original bank exports.
+- `data/rules.csv`, `data/tiers.csv`, `data/rates.csv`, `data/savings.csv` — the edit layer
+  (categorization, floor vs flex, FX rates, savings destinations).
+- `data/profile.json` — the personal layer: own names and IBANs (for transfer detection), the
+  net-worth marks, account and merchant display labels, the footer. Copy `profile.example.json` to
+  start one. This file is the PII. It is gitignored and never leaves the machine.
+- `deploy/` — the optional hosted-dashboard bundle (the rendered HTML plus a tiny server). Gitignored.
+
+`data/` holds raw financial data and must never reach a remote. In a remoteless private store like the
+imprnt vault it is committed as the canonical source of truth; anywhere a remote exists, gitignore it.
+`deploy/` is derived and stays local. Neither ships with the plugin code.
+
+## Commands (you run these; nothing runs on its own)
+
+Run as `imprnt kopeika <cmd>` (the core dispatches to `node plugins/kopeika/kopeika.js`), or call
+`node plugins/kopeika/kopeika.js <cmd>` directly:
+
+- `imprnt kopeika import <revolut|n26|trading212|tbank|alfa> <file> --account <label> --owner <owner>`
+  archives the raw export, parses, FX-converts to EUR, dedups, and appends.
+- `imprnt kopeika categorize [--review]` applies `data/rules.csv`. `--review` lists new merchants by spend.
+- `imprnt kopeika transfers` pairs internal account-to-account legs.
+- `imprnt kopeika report [--month YYYY-MM] [--html <path> --lang <en|ru>]` gives income/spend/saved per
+  month, the category and floor/flex split, and optionally writes the self-contained dashboard.
+- `imprnt kopeika project [--rate <eur/mo>] [--years N]` rolls the savings stock forward 1 and 5 years.
+- `imprnt kopeika recurring` and `imprnt kopeika list` show the recurring backbone and a row table.
+
+The monthly procedure (export, import, categorize, transfers, review, report) is in README.md.
+
+## How to answer a money question
+
+When the user asks about their spending, savings, net worth, or a given month, run the relevant command
+(`report`, `project`, `list`) and read its output. The ledger is the source of truth and the numbers
+are deterministic. To change how a transaction is treated, edit the data file that governs it
+(`rules.csv` for category, `tiers.csv` for floor/flex, `savings.csv` for destinations, `profile.json`
+for display labels and net-worth marks), then re-run. Never hand-edit a ledger row.
+
+## Adding new data and publishing (the "eat this CSV" loop)
+
+When the user hands you a fresh export ("here is my Revolut CSV, add it and update the site"), run the
+loop and report what changed at each step:
+
+1. `imprnt kopeika import <connector> <path> --account <label> --owner <owner>` — confirm the
+   imported / skipped-dup counts and any missing FX rates it warns about.
+2. `imprnt kopeika categorize` then `imprnt kopeika transfers`.
+3. `imprnt kopeika categorize --review` — for each new merchant worth a label, add one line to
+   `data/rules.csv` and re-run `categorize`. This is the one judgement step.
+4. `imprnt kopeika report` (and `project`) to sanity-check the month against the known anchor.
+5. Publish: render both languages, then deploy the `deploy/` bundle to the host.
+   ```
+   imprnt kopeika report --html deploy/public/en.html --lang en
+   imprnt kopeika report --html deploy/public/ru.html --lang ru
+   # then deploy the deploy/ bundle (the exact host command is in the user's deploy note)
+   ```
+
+Reuse the same `--account` label for an account every month; the display aliases and savings
+destinations are keyed to them. The plugin's `data/` folder is the single source of truth for both the
+CLI and the hosted dashboard.
+
+## Rules (always-on while this fragment is installed)
+
+- **Personal data stays in `data/` (gitignored), never in a vault note.** The PII is `data/profile.json`.
+  To put something durable in the vault, propose a *summary* note (net worth, savings rate) into
+  `proposed/` for `imprnt ingest --apply`. Never a per-transaction dump, never account numbers or balances.
+- **The pipeline is deterministic; no LLM touches a row at runtime.** An LLM may propose a categorization
+  *rule* at authoring time, never mutate a ledger row directly.
+- **Financial data must never reach a remote.** `data/` holds the real exports, ledger, and profile.
+  Committing it in a remoteless private store (the imprnt vault) is the intended setup; anywhere with a
+  remote, gitignore `data/`. `check.js` fails if tracked `data/` meets a remote. `deploy/` stays local.
+- **Namespace any vault label** you ever add with `kopeika.*`.
+- The hosted dashboard carries no account numbers, IBANs, or balances, and sits behind a password.

package/check.js

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+
+// src/check.ts
+import { existsSync, readFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+var HERE = dirname(fileURLToPath(import.meta.url));
+var ROOT = basename(HERE) === "src" ? dirname(HERE) : HERE;
+var DATA = join(ROOT, "data");
+var problems = [];
+var notes = [];
+function git(args) {
+  const r = spawnSync("git", args, { cwd: ROOT, encoding: "utf8" });
+  return r.status === 0 ? (r.stdout ?? "").trim() : "";
+}
+var dataTracked = git(["ls-files", "data"]).length > 0;
+var hasRemote = git(["remote"]).length > 0;
+if (dataTracked && hasRemote) {
+  problems.push("data/ is git-tracked in a repo that HAS A REMOTE — your financial data (ledger, raw bank " + "exports, profile.json) could be pushed. Add data/ to .gitignore, or remove the remote. " + "Committing data/ is only safe in a remoteless local store like the imprnt vault.");
+} else if (dataTracked) {
+  notes.push("data: committed (no remote — canonical local store, safe)");
+} else {
+  notes.push("data: not tracked by git");
+}
+var profilePath = join(DATA, "profile.json");
+if (existsSync(profilePath)) {
+  try {
+    JSON.parse(readFileSync(profilePath, "utf8"));
+    notes.push("profile: present");
+  } catch (e) {
+    problems.push(`data/profile.json is not valid JSON (${e.message})`);
+  }
+} else {
+  notes.push("profile: none (generic mode — no net-worth layer, raw labels)");
+}
+var ledgerPath = join(DATA, "ledger.csv");
+if (existsSync(ledgerPath)) {
+  const lines = readFileSync(ledgerPath, "utf8").split(`
+`).filter((l) => l.trim() !== "");
+  const rows = Math.max(0, lines.length - 1);
+  notes.push(`ledger: ${rows} row(s)`);
+} else {
+  notes.push("ledger: none yet (import something first)");
+}
+console.log("kopeika check");
+for (const n of notes)
+  console.log(`  ${n}`);
+if (problems.length) {
+  console.log(`
+⚠ ${problems.length} issue(s):`);
+  for (const p of problems)
+    console.log(`  - ${p}`);
+  process.exit(1);
+}
+console.log(`
+sound.`);
+process.exit(0);

package/docs/ARCHITECTURE.md

@@ -0,0 +1,125 @@
+# Architecture
+
+How kopeika is built and why it is shaped this way. The [README](../README.md) is the front door and the command reference. [RUNBOOK.md](../RUNBOOK.md) is the monthly operating procedure. This document is the durable design: the model, the data layers, and the decisions that do not change month to month.
+
+## The core principle
+
+The LLM builds the tools at authoring time. The deterministic tools do the work at runtime. No model touches a transaction at runtime, so the same exports always produce the same ledger, report, and dashboard.
+
+Verification is structural, not a model's opinion:
+
+- **A golden test suite** over parsing, dedup, FX, rules, transfers, savings, and projection.
+- **Reconcilable invariants.** A known month must reproduce a known spend and saved figure. Income, spend, and saved are derived from the same signed rows, so they cannot silently drift apart. This is the lesson that started the project: an earlier money tool reported income and outflow that did not reconcile to the actual balance, a double-count no single test run catches. Reconciliation is the missing check.
+
+The cost of the principle is that vendor-specific logic is the one human-written surface (the connectors). Everything downstream is shared and deterministic.
+
+## The pipeline
+
+```
+bank CSV export
+   │  import      archive raw, parse, FX→EUR, dedup by id, append
+   ▼
+data/ledger.csv  (clean, normalized)
+   │  categorize  apply data/rules.csv, first match wins
+   │  transfers   pair internal account-to-account legs
+   ▼
+   ├─ report      income / spend / saved per month, category + floor/flex
+   ├─ project     roll the savings stock forward 1y / 5y at a set rate
+   └─ report --html   the self-contained net-worth dashboard
+```
+
+Each stage is a CLI command and is safe to re-run. Import dedups, so an overlapping re-export is a no-op. Transfers re-pairs idempotently. A full reset is `rm data/ledger.csv` then re-import every account.
+
+## Raw vs clean
+
+Original exports are archived under `data/raw/<source>/` and never edited. The clean ledger `data/ledger.csv` is rebuilt from them. Keeping both layers means a re-import or a rebuild can never lose the source of truth, and any categorization or transfer logic can be replayed from scratch.
+
+## Stock vs flow
+
+Two different questions about money:
+
+- **Flow:** transactions summed over a month. Income, spend, saved. This is what `report` answers.
+- **Stock:** an account level at a moment. The buffer balance, the savings total, the projection's starting point. The `balance` column carries the running level when an export reports it (Revolut does, N26 and Trading 212 do not).
+
+Savings is the stock that matters: money that has landed in a savings destination. Everything else on any account is spendable float. Money leaving a savings destination is a negative flow that lowers the stock, so a bad month reports itself with no penny-counting. The only glance needed is whether the buffer slid backwards, which is just "did we raid it."
+
+## The two axes
+
+A row has a **category** (what it is) and the ledger separately reads a **tier** (floor vs flex) from `data/tiers.csv`.
+
+- Category answers "what was this": Groceries, Rent, Shopping. It comes from the rules.
+- Tier answers "could we skip it": floor (mandatory) vs flex (optional). It is a property of the category, set in one file, not a per-row column and not derived from recurrence. A frequent buy recurs but can still be flex.
+
+Keeping them orthogonal means the spend view can split mandatory from discretionary without re-touching a single transaction. Changing a tier is a one-line data edit.
+
+## Savings as destinations
+
+The "saved this month" number is the inflow to the savings destinations, not income-minus-spend. Defining savings as the inflow to specific accounts means a bad month shows up as less landing there, without having to count every euro of spend first. The destinations are configured in `data/savings.csv`:
+
+- `account,<label>` builds the stock from that account's flow (the cost basis: cumulative deposits minus withdrawals).
+- `marker,<name>` is an in-account pot (a stash inside a regular account).
+- `anchor,<value>` is a manual balance, the last resort for an account with no export.
+
+## The net-worth layer
+
+On top of liquid savings sits an illiquid layer that the dashboard charts as its own toggleable lines:
+
+- **Property:** the flats, valued in RUB, net of their mortgage. The flats compound at a conservative nominal appreciation rate. The mortgage is carried flat (subtracted, never appreciating). The mortgage figure is the real current balance after prepayment, not the origination schedule.
+- **A structured note (BCS):** a nominal held flat in CNY.
+
+These marks (flat values, mortgage balance, note nominal, the appreciation rate) live in `data/profile.json` (see "The personal layer" below), not in code. They are facts about the world, not ledger rows, so they are a single edit point rather than transactions. With no marks declared, the chart shows liquid savings only.
+
+The dashboard's Total sums only the **visible** lines. Toggling real estate off collapses the headline number to the liquid, touchable amount. That is the point: a large net worth is real but not spendable, and the page lets you see the number you can actually touch.
+
+## Projection
+
+The projection rolls the savings stock forward 1 and 5 years at a monthly rate you set with a slider, defaulting to the recent actual. The slider is what keeps the forecast honest: the rate is an assumption you own, not a number the tool pretends to know.
+
+- The ETF is held flat at cost basis. Growth is unmodeled upside, a loss is not drawn either. The transactions export has no portfolio-value column, so cost basis is what a flat projection can carry. A live market value would be one number a month from a second source, an optional add.
+- Real estate compounds at its nominal rate, the mortgage stays flat.
+- Output is dual-currency, EUR and RUB, because the income mix is mostly RUB.
+
+## The dashboard
+
+One self-contained HTML file: inline CSS, a hand-rolled SVG chart, vanilla JS, no CDN, no fetch, no external JS. Rendered by `report --html`, deployed as a static file. It is bilingual (RU default, EN), light/dark, and mobile-first, and it follows the shared house style (Inter + Space Grotesk + JetBrains Mono, an emerald accent, mono stats and eyebrows). On a phone the chart runs full-bleed with the line labels floating over a soft right-edge fade, so the chart reads as the centerpiece rather than a cropped strip.
+
+The page carries no account numbers, no IBANs, and no balances. When hosted it sits behind a password. The display labels (clean merchant names, the "what for" note, account labels, the footer) come from `data/profile.json` at render time, so they survive ledger re-imports and keep personal text out of the code. The category colour palette is generic and stays in `src/dashboard.ts`.
+
+## FX
+
+`amount_eur = amount_native * rate_to_eur` for the row's month, from `data/rates.csv`. EUR converts at 1 with no row. A missing `(month, currency)` rate leaves `amount_eur` empty and is reported. kopeika never guesses a rate. Rates can be per-month, the schema has a `month` column.
+
+## Connectors
+
+A connector is `src/connectors/<name>.ts` exporting `parse<Name>(text: string): ParsedRow[]`. It translates the vendor CSV into the `ParsedRow` shape and filters out non-completed or invalid rows. It does not compute `id`, FX, dedup, or transfer grouping, the import pipeline owns those. Register it in `src/connectors/index.ts`. The built connectors are Revolut, N26, Trading 212, T-Bank, and Alfa. The Alfa connector keeps only savings-vehicle accounts by design, dropping card and current-account rows.
+
+Some connectors flag a row as a likely internal transfer when it names one of your own accounts. The names and IBANs that define "yours" are not hardcoded. They come from the profile and are installed at startup through `src/identity.ts`, so a connector carries vendor-format logic only, never a person. The `transfers` command pairs the authoritative legs by amount and date regardless, so a missed hint never loses a transfer.
+
+## The personal layer (the profile)
+
+Every personal fact lives in `data/profile.json` (kept local, never on a remote), never in the code. This is the same "data is the source of truth" rule the ledger config follows, applied to identity and display: own names and IBANs for transfer detection, the net-worth marks, the account and merchant display labels, and the footer. `src/profile.ts` loads it once at startup. A committed `profile.example.json` is the template.
+
+Loading is forgiving by design. A missing file yields an empty profile, so a fresh checkout runs in generic mode: no own-name matching, no net-worth layer, raw merchant and account strings. Filling the profile in lights those features up. The payoff is that the package ships with no personal data and the same binary works for anyone, while one local file holds everything specific to one household. That file, and the whole `data/` folder, must never reach a remote: committed in a remoteless private store (the imprnt vault) is the intended setup, and `check.js` fails if `data/` is tracked in a repo that has a remote.
+
+## Data scope
+
+What the ledger is allowed to contain, and why:
+
+- **EUR side: fully tracked.** Spend, income, floor/flex, and savings. German transactions are stable merchants, and the rules already strip internal transfers, so full tracking is cheap and honest.
+- **RU side: savings only.** The RU savings accounts are tracked as destinations (the accumulated stock). RU card spend and RU income are out of scope. RU income lands in a separate account and is taxed there.
+- **Off the books:** cash (logged only on demand, never reconciled, a missing cash row is never a gap), and accounts whose labor outweighs their signal.
+
+The scope is a policy choice, not a technical limit. Including an account is about whether it belongs in the household picture, not about effort. Cross-currency transfer matching is not needed because cross-border transfers do not happen.
+
+## Design decisions
+
+The durable choices, stated as principles rather than dated events:
+
+- The household number that gets surfaced is savings going up, never spending picked apart. Full books underneath, a calm outcome on top.
+- Savings is the inflow to named destinations, nothing else.
+- Projection is the reason the tool exists. The go-forward rate is a slider, defaulting to the recent actual.
+- The ETF is flat at cost basis. Live market value is an optional later add from a second source.
+- Dual currency throughout, EUR and RUB.
+- Net-worth marks are profile data, not ledger rows and not code.
+- The data files are the source of truth, the code reads them. Categorization, tiers, savings destinations, FX rates, and the whole personal layer (names, marks, display labels) are all data edits, never code changes. The code ships with no personal data.
+</content>