@morroc/open-ledger 0.14.1

package/dist/lib/json.js

@@ -0,0 +1,12 @@
+import { tryExecute } from "./result.js";
+/**
+ * For DB/JSON-column reads where a missing or corrupt blob should degrade to
+ * "nothing". Callers that must distinguish absent from corrupt should parse
+ * explicitly and branch instead.
+ */
+export function parseJsonOrNull(raw) {
+    if (raw == null)
+        return null;
+    const parsed = tryExecute(() => JSON.parse(raw));
+    return parsed.ok ? parsed.value : null;
+}

package/dist/lib/masked.js

@@ -0,0 +1,49 @@
+/**
+ * Masked account numbers: the canonical key behind both the stored form
+ * (`accounts.account_number_masked`) and the fuzzy matcher's number comparison,
+ * so a statement's `••7652-0` and `470686XXXXXX9483` resolve like a human reads
+ * them.
+ */
+// Characters statements use to blank out the hidden middle of an account
+// number (`470686XXXXXX9483`, `••7652`, `**1234`, `…9483`).
+const MASK_CHARS = "Xx•*…";
+/** Everything after the last mask char in `s` (or `s` unchanged if none), so a
+ *  masked run like `XXXXXX` isn't confused with a check-digit separator. */
+export function tailAfterMask(s) {
+    let lastAt = -1;
+    for (const ch of MASK_CHARS) {
+        const i = s.lastIndexOf(ch);
+        if (i > lastAt)
+            lastAt = i;
+    }
+    return lastAt === -1 ? s : s.slice(lastAt + 1);
+}
+/**
+ * Canonical key for an account number, tolerant of a trailing check digit
+ * (`xxx-7652-0` and `xxx-7652` both resolve to one account). Masked digits
+ * before the mask are stripped first via `tailAfterMask` so they can't
+ * corrupt the check-digit heuristic.
+ */
+export function accountNumberKey(raw) {
+    const tail = tailAfterMask(String(raw ?? ""));
+    const digits = tail.replace(/\D+/g, "");
+    if (!digits)
+        return "";
+    const core = digits.length >= 5 ? digits.slice(0, -1) : digits;
+    return core.slice(-4);
+}
+/**
+ * Normalizes for storage so a trailing check digit can't split one account
+ * into two (`••7652-0` and `••76520` both store as `••7652`). Preserves the
+ * leading mask prefix, defaulting to `••` when there isn't one to preserve.
+ */
+export function normalizeMaskedAccountNumber(masked) {
+    if (masked == null)
+        return null;
+    const s = String(masked);
+    const key = accountNumberKey(s);
+    if (!key)
+        return s;
+    const prefix = /^\D+/.exec(s)?.[0] ?? "••";
+    return prefix + key;
+}

package/dist/lib/money.js

@@ -0,0 +1,35 @@
+/**
+ * `transactions` stores amounts as integers in the currency's smallest unit
+ * (THB satang, JPY has none, KWD has three) to avoid float drift. Decimal
+ * conversion happens only at the CLI/pipeline boundary.
+ */
+const exponentCache = new Map();
+/**
+ * Resolved via Intl and memoized. Falls back to 2 on an unresolvable code,
+ * including empty/garbage input - which Intl rejects too.
+ */
+export function minorUnitExponent(currency) {
+    const code = currency.toUpperCase();
+    const cached = exponentCache.get(code);
+    if (cached !== undefined)
+        return cached;
+    let exp = 2;
+    try {
+        const resolved = new Intl.NumberFormat("en", {
+            style: "currency",
+            currency: code,
+        }).resolvedOptions();
+        exp = resolved.maximumFractionDigits ?? 2;
+    }
+    catch {
+        exp = 2;
+    }
+    exponentCache.set(code, exp);
+    return exp;
+}
+export function toMinorUnits(decimal, currency) {
+    return Math.round(decimal * 10 ** minorUnitExponent(currency));
+}
+export function fromMinorUnits(minor, currency) {
+    return minor / 10 ** minorUnitExponent(currency);
+}

package/dist/lib/patch.js

@@ -0,0 +1,29 @@
+/**
+ * Builds `SET` fragments, params, and before/after snapshots for every `spec`
+ * key present in `patch`. A key participates only when `patch[key] !==
+ * undefined` (absent leaves the column untouched; explicit `null` binds SQL
+ * NULL). No `changed` flag: callers test `sets.length` themselves after
+ * appending any hand-written fields.
+ */
+export function buildPatch(spec, current, patch) {
+    const currentRecord = current;
+    const patchRecord = patch;
+    const sets = [];
+    const params = [];
+    const before = {};
+    const after = {};
+    for (const key of Object.keys(spec)) {
+        if (patchRecord[key] === undefined)
+            continue;
+        const field = spec[key];
+        const column = field.column ?? key;
+        const value = field.transform ? field.transform(patchRecord[key]) : patchRecord[key];
+        sets.push(`${column} = ?`);
+        // libsql cannot bind `undefined`; a transform should never produce one,
+        // but this keeps the "params never contain undefined" contract airtight.
+        params.push(value === undefined ? null : value);
+        before[key] = currentRecord[column];
+        after[key] = value;
+    }
+    return { sets, params, before, after };
+}

package/dist/lib/result.js

@@ -0,0 +1,15 @@
+export function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+export function tryExecute(fn) {
+    try {
+        const value = fn();
+        if (value instanceof Promise) {
+            return value.then((v) => ({ ok: true, value: v }), (err) => ({ ok: false, error: errorMessage(err) }));
+        }
+        return { ok: true, value };
+    }
+    catch (err) {
+        return { ok: false, error: errorMessage(err) };
+    }
+}

package/dist/lib/validate.js

@@ -0,0 +1,154 @@
+import * as z from "zod";
+/** Thrown by `parseInput` on a failed parse. `src/lib/` has no dependency on
+ *  `src/cli/`, so the CLI layer maps this to its own error/exit-code type. */
+export class ValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ValidationError";
+    }
+}
+// Each preprocess below passes undefined through, so an absent required key
+// surfaces as a missing-required issue rather than a coerced value.
+const toStringInput = (value) => typeof value === "string" || value === undefined ? value : String(value);
+/** Non-finite results pass the raw value through so z.number rejects it and the
+ *  formatter echoes the original in `got "…"`; "" and null coerce to 0 via Number(). */
+const toNumberInput = (value) => {
+    if (typeof value === "number")
+        return value;
+    const n = Number(value);
+    return Number.isFinite(n) ? n : value;
+};
+const toBooleanInput = (value) => {
+    if (value === "true")
+        return true;
+    if (value === "false")
+        return false;
+    return value;
+};
+export function str() {
+    return z.preprocess(toStringInput, z.string());
+}
+export function num() {
+    return z.preprocess(toNumberInput, z.number());
+}
+export function int() {
+    return z.preprocess(toNumberInput, z.number().int());
+}
+export function bool() {
+    return z.preprocess(toBooleanInput, z.boolean());
+}
+/** A parse failure raises a custom issue carrying the JSON.parse message. */
+export function json() {
+    return z.unknown().transform((value, ctx) => {
+        if (typeof value !== "string")
+            return value;
+        try {
+            return JSON.parse(value);
+        }
+        catch (err) {
+            ctx.addIssue({ code: "custom", message: err.message });
+            return z.NEVER;
+        }
+    });
+}
+function defaultLabel(key) {
+    return "--" + key.replace(/_/g, "-");
+}
+function toCamelCase(key) {
+    return key.replace(/_([a-zA-Z0-9])/g, (_, c) => c.toUpperCase());
+}
+function toSnakeCase(key) {
+    return key.replace(/[A-Z]/g, (c) => "_" + c.toLowerCase());
+}
+/** Auto-bridges commander's camelCase opts to the snake_case names specs are
+ *  written in; first non-`undefined` candidate wins. */
+function resolveRaw(raw, key, aliases) {
+    const candidates = [key, toCamelCase(key), toSnakeCase(key), ...aliases];
+    for (const candidate of candidates) {
+        const value = raw[candidate];
+        if (value !== undefined)
+            return value;
+    }
+    return undefined;
+}
+// Absent keys are omitted so zod's optional/default/required handling stays authoritative.
+function normalizeRaw(shape, raw, aliases = {}) {
+    const out = {};
+    for (const key of Object.keys(shape)) {
+        const value = resolveRaw(raw, key, aliases[key] ?? []);
+        if (value !== undefined)
+            out[key] = value;
+    }
+    return out;
+}
+/** Render one non-missing issue into the pinned `<label> <constraint>` clause,
+ *  echoing the raw pre-coercion value in `got "…"`. */
+function constraintClause(label, issue, raw) {
+    if (issue.code === "custom")
+        return `${label} must be valid JSON: ${issue.message}`;
+    if (issue.code === "invalid_value") {
+        return `${label} must be one of ${(issue.values ?? []).join(", ")}, got "${String(raw)}"`;
+    }
+    if (issue.expected === "int")
+        return `${label} must be an integer, got "${String(raw)}"`;
+    if (issue.expected === "number")
+        return `${label} must be a number, got "${String(raw)}"`;
+    if (issue.expected === "boolean")
+        return `${label} must be a boolean, got "${String(raw)}"`;
+    return `${label} ${issue.message}`;
+}
+/** An issue whose normalized value is `undefined` is a missing-required field.
+ *  All-missing groups as `--a, --b required`; otherwise clauses join with "; ". */
+function formatError(shape, normalized, issues, opts) {
+    const first = new Map();
+    for (const issue of issues) {
+        const key = String(issue.path[0]);
+        if (!first.has(key))
+            first.set(key, issue);
+    }
+    const missing = [];
+    const clauses = [];
+    let hasConstraint = false;
+    for (const key of Object.keys(shape)) {
+        const issue = first.get(key);
+        if (!issue)
+            continue;
+        const label = opts?.labels?.[key] ?? defaultLabel(key);
+        if (normalized[key] === undefined) {
+            missing.push(label);
+            clauses.push(`${label} required`);
+        }
+        else {
+            hasConstraint = true;
+            clauses.push(constraintClause(label, issue, normalized[key]));
+        }
+    }
+    if (!hasConstraint)
+        return `${missing.join(", ")} required`;
+    return clauses.join("; ");
+}
+function parse(schema, raw, opts) {
+    const shape = schema.shape;
+    const normalized = normalizeRaw(shape, raw, opts?.aliases);
+    const parsed = schema.safeParse(normalized);
+    if (parsed.success)
+        return { ok: true, value: parsed.data };
+    return {
+        ok: false,
+        error: formatError(shape, normalized, parsed.error.issues, opts),
+    };
+}
+/** Accumulates every missing-required and coercion error into one thrown `ValidationError`. */
+export function parseInput(schema, raw, opts) {
+    const result = parse(schema, raw, opts);
+    if (!result.ok)
+        throw new ValidationError(result.error);
+    if (opts?.atLeastOne && Object.keys(result.value).length === 0) {
+        throw new ValidationError(opts.atLeastOne);
+    }
+    return result.value;
+}
+/** For batch rows, which must keep the PARTIAL exit-code contract instead of throwing. */
+export function safeParse(schema, raw, opts) {
+    return parse(schema, raw, opts);
+}

package/dist/privacy/redactor.js

@@ -0,0 +1,140 @@
+import { config } from "../config.js";
+import { readContext } from "../context.js";
+const SECTION_RULES = [
+    {
+        heading: "Family",
+        token: "[PARTNER]",
+        stripParen: true,
+        skipIfUser: true,
+        patterns: [
+            /^(?:partner|spouse|wife|husband|child|kid|son|daughter|dependent)[:\s]+(.+)/i,
+            /^([\p{Lu}\p{Lo}][\p{L}\s]+)/u,
+        ],
+    },
+    {
+        heading: "Income",
+        token: "[EMPLOYER]",
+        patterns: [
+            /(?:employer|works? (?:at|for)|employed (?:at|by))[:\s]+([A-Z][\w\s&.,-]+?)(?:\s*[-–—|,;(\n]|$)/i,
+            /\bfrom ([A-Z][A-Za-z\s&.,-]+?)(?:\s*[-–—|,;(\n]|$)/,
+            /\bat ([A-Z][A-Za-z\s&.,-]+?)(?:\s*[-–—|,;(\n]|$)/,
+        ],
+    },
+];
+const NUMERIC_PII_PATTERNS = [
+    // Thai national ID with dashes: 1-2345-67890-12-3
+    [/\b\d-\d{4}-\d{5}-\d{2}-\d\b/g, "[NATID]"],
+    // Thai national ID without dashes (13 digits): must precede the generic ACCT pattern.
+    [/\b\d{13}\b/g, "[NATID]"],
+    // Thai mobile numbers: 0[689]xxxxxxxx (10 digits starting 06/08/09)
+    [/\b0[689]\d{8}\b/g, "[PHONE]"],
+    // 16-digit credit card (with optional separators)
+    [/\b\d{4}[\s-]?\d{4}[\s-]?\d{4}[\s-]?\d{4}\b/g, "[CARD]"],
+    // 10-12 digit account / routing numbers at a word boundary
+    [/\b\d{10,12}\b(?=\s|$|[,.])/g, "[ACCT]"],
+];
+function extractSectionLines(context, heading) {
+    const re = new RegExp(`## ${heading}\\n([\\s\\S]*?)(?=\\n##|$)`);
+    const match = context.match(re);
+    if (!match)
+        return [];
+    return match[1]
+        .split("\n")
+        .filter((l) => l.trim().startsWith("-"))
+        .map((l) => l.replace(/^-\s*/, "").trim())
+        .filter((text) => text.length > 0 && !text.startsWith("("));
+}
+function applyRule(rule, context, userName, push) {
+    for (const line of extractSectionLines(context, rule.heading)) {
+        if (rule.skipIfUser && line.toLowerCase() === userName.toLowerCase())
+            continue;
+        for (const pattern of rule.patterns) {
+            const match = line.match(pattern);
+            if (!match)
+                continue;
+            let name = match[1].trim();
+            if (rule.stripParen)
+                name = name.replace(/\s*\(.*\)/, "").trim();
+            if (!name)
+                break;
+            if (rule.skipIfUser && name.toLowerCase() === userName.toLowerCase())
+                break;
+            push(name, rule.token);
+            break;
+        }
+    }
+}
+function buildRedactions() {
+    const entries = [];
+    const seen = new Set();
+    const push = (real, token) => {
+        const trimmed = real.trim();
+        if (trimmed.length < 2)
+            return;
+        const key = trimmed.toLowerCase();
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        entries.push({ real: trimmed, token });
+    };
+    const userName = config.userName;
+    if (userName && userName !== "User") {
+        push(userName, "[USER]");
+        const parts = userName.split(/\s+/);
+        if (parts.length > 1) {
+            push(parts[0], "[USER_FIRST]");
+            push(parts[parts.length - 1], "[USER_LAST]");
+        }
+    }
+    const context = readContext();
+    if (context) {
+        for (const rule of SECTION_RULES) {
+            applyRule(rule, context, userName, push);
+        }
+    }
+    entries.sort((a, b) => b.real.length - a.real.length);
+    return entries;
+}
+/** Builds name rules from config.userName + context.md once, returning a reusable
+ *  masker that amortizes that cost across many values. */
+function createRedactor() {
+    const redactions = buildRedactions();
+    return (text) => {
+        let result = text;
+        for (const { real, token } of redactions) {
+            result = result.replaceAll(real, token);
+        }
+        for (const [pattern, replacement] of NUMERIC_PII_PATTERNS) {
+            result = result.replace(pattern, replacement);
+        }
+        return result;
+    };
+}
+/**
+ * Deep-walks `data`, redacting a string value only when its key is in the
+ * per-command `fields` allowlist — ids/enums/amounts the agent needs verbatim
+ * stay untouched. Returns a fresh structure (input untouched); a no-op when
+ * `enabled` is false.
+ */
+export function applyRedaction(data, enabled, fields) {
+    if (!enabled)
+        return data;
+    const redactor = createRedactor();
+    const allow = new Set(fields);
+    const walk = (value, key) => {
+        if (typeof value === "string") {
+            return key !== undefined && allow.has(key) ? redactor(value) : value;
+        }
+        if (Array.isArray(value)) {
+            return value.map((item) => walk(item, key));
+        }
+        if (value !== null && typeof value === "object") {
+            const out = {};
+            for (const [k, v] of Object.entries(value))
+                out[k] = walk(v, k);
+            return out;
+        }
+        return value;
+    };
+    return walk(data, undefined);
+}

package/dist/setup/hosts.js

@@ -0,0 +1,32 @@
+import { homedir } from "os";
+import { resolve } from "path";
+/**
+ * Any coding agent compatible with the shared .agents/skills dir (Codex,
+ * OpenCode, Pi, Kimi global, …) is served by this default entry; only hosts
+ * that cannot read it get their own.
+ */
+const agents = {
+    id: "agents",
+    label: "Agent Skills standard directory",
+    projectDir: ".agents/skills",
+    globalDir: () => resolve(homedir(), ".agents/skills"),
+};
+const claude = {
+    id: "claude",
+    label: "Claude Code",
+    projectDir: ".claude/skills",
+    globalDir: () => resolve(homedir(), ".claude/skills"),
+};
+// Kimi's project dir is its own .skills; its global reads the shared
+// ~/.agents/skills, so the global install goes there.
+const kimi = {
+    id: "kimi",
+    label: "Kimi",
+    projectDir: ".skills",
+    globalDir: () => resolve(homedir(), ".agents/skills"),
+};
+export const SKILL_HOSTS = [agents, claude, kimi];
+export const DEFAULT_HOST = agents.id;
+export function findHost(id) {
+    return SKILL_HOSTS.find((h) => h.id === id) ?? null;
+}

package/dist/setup/install.js

@@ -0,0 +1,60 @@
+import { createRequire } from "module";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { join, resolve } from "path";
+import { findHost, DEFAULT_HOST } from "./hosts.js";
+/** Thrown when an installed skill dir is at a DIFFERENT version and --force wasn't given;
+ *  the CLI maps this to exit code INVALID with a --force hint. */
+export class SkillPackVersionError extends Error {
+    installedVersion;
+    cliVersion;
+    path;
+    constructor(args) {
+        super(`skill pack already installed at ${args.path} (version ${args.installedVersion}); ` +
+            `this CLI is ${args.cliVersion}`);
+        this.name = "SkillPackVersionError";
+        this.installedVersion = args.installedVersion;
+        this.cliVersion = args.cliVersion;
+        this.path = args.path;
+    }
+}
+// install.ts compiles to dist/setup/install.js; ../../package.json from there is
+// the package root (same 2-level depth as src/cli/index.ts uses).
+const require = createRequire(import.meta.url);
+export function getVersion() {
+    const { version } = require("../../package.json");
+    return version;
+}
+export function skillMd() {
+    return readFileSync(new URL("../../skills/SKILL.md", import.meta.url), "utf8");
+}
+// --dir D is host-agnostic: resolve(D)/skills/open-ledger. Otherwise <cwd or
+// home>/<host skills dir>/open-ledger (the host dir already ends in skills).
+function resolveTarget(opts) {
+    if (opts.dir) {
+        return { kind: "dir", dir: join(resolve(opts.dir), "skills", "open-ledger") };
+    }
+    const host = findHost(opts.host ?? DEFAULT_HOST);
+    if (!host)
+        throw new Error(`unknown skill host: ${opts.host}`);
+    const base = opts.global ? host.globalDir() : resolve(process.cwd(), host.projectDir);
+    return { kind: host.id, dir: join(base, "open-ledger") };
+}
+function readVersionFile(skillDir) {
+    const versionPath = join(skillDir, "VERSION");
+    if (!existsSync(versionPath))
+        return null;
+    return readFileSync(versionPath, "utf8").trim();
+}
+/** Idempotent at the same version; throws SkillPackVersionError on a clash without --force. */
+export function installSkill(opts = {}) {
+    const version = getVersion();
+    const { kind, dir } = resolveTarget(opts);
+    const existing = readVersionFile(dir);
+    if (existing !== null && existing !== version && !opts.force) {
+        throw new SkillPackVersionError({ installedVersion: existing, cliVersion: version, path: dir });
+    }
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, "SKILL.md"), skillMd());
+    writeFileSync(join(dir, "VERSION"), version + "\n");
+    return { kind, path: dir, version };
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@morroc/open-ledger",
+  "version": "0.14.1",
+  "description": "OpenLedger — The Harness Layer for Personal Finance",
+  "keywords": [
+    "finance",
+    "harness",
+    "personal",
+    "ledger",
+    "bookkeeping",
+    "cli",
+    "ai"
+  ],
+  "homepage": "https://github.com/phureewat29/open-ledger#readme",
+  "bugs": {
+    "url": "https://github.com/phureewat29/open-ledger/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/phureewat29/open-ledger.git"
+  },
+  "license": "Apache-2.0",
+  "author": "Phureewat A",
+  "type": "module",
+  "bin": {
+    "oled": "dist/cli/index.js"
+  },
+  "files": [
+    "dist/",
+    "skills/",
+    "datasets/"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc",
+    "test": "vitest run --typecheck --typecheck.tsconfig ./tsconfig.typecheck.json",
+    "dev": "tsx src/cli/index.ts",
+    "release": "tsx scripts/release.ts",
+    "integration": "npm run build && tsx scripts/integration.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^13.0.0",
+    "dotenv": "^16.4.0",
+    "libsql": "^0.5.0",
+    "mupdf": "^1.27.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/semver": "^7.7.1",
+    "semver": "^7.8.4",
+    "tsx": "^4.7.0",
+    "typescript": "^5.5.0",
+    "vitest": "^3.2.4"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/skills/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: open-ledger
+description: A local double-entry personal-finance harness driven through the `oled` cli. Use for anything about the ledger, bank or credit-card statements, net worth, spending, accounts, transactions, or merchants.
+---
+
+# OpenLedger
+
+`oled` is a deterministic CLI over a local, encrypted, double-entry ledger; you supply the intelligence. The CLI is the manual: `oled --help` lists the commands and the output contract, `oled <noun> --help` gives each command's behavior, flow, and flags, and every error carries a code and a message, often a `hint`. When you do not understand something, ask the CLI before guessing — never invent flags, subcommands, or ids.
+
+Pass `--json` on every command. With a shell, run `oled` yourself, one command per call. Human is your terminal: send one command per message, wait for the pasted output; ask for uploads instead of reading files.
+
+## Setup
+
+`oled --version` prints a version when installed. To install: check `node --version` >= 18, then `npm install -g @morroc/open-ledger`. First run: `oled config --generate-key --json` unless `oled status --json` shows `"configured":true`. Statements go in the `dataDir` from `oled config show --json`, as PDFs or as photos/scans (PNG/JPEG/WebP); `oled open` opens it.
+
+## Commands
+
+Start with `oled status --json`; descriptions live in `oled --help`. commands: `oled doctor --json` · `oled setup --force` · `oled config show --json` · `oled ingest list --json` · `oled files list --json` · `oled vault add <pattern>` · `oled transactions list --json` · `oled accounts tree --json` · `oled merchants list --json` · `oled questions list --json` · `oled report --from <date> --to <date> --json` · `oled notes list --json` · `oled datasets --json` · `oled open`.