@morroc/open-ledger 0.14.1

package/dist/cli/commands/vault.js

@@ -0,0 +1,65 @@
+import { config } from "../../config.js";
+import { emitList, emitObject, fail, readSecretFromStdin, requireYes, runAction, } from "../output.js";
+import { openDb } from "../db.js";
+const VAULT_COLUMNS = [
+    { header: "ID", value: (r) => r.id },
+    { header: "Pattern", value: (r) => r.pattern },
+    { header: "Uses", value: (r) => String(r.use_count), align: "right" },
+    { header: "Last Used", value: (r) => r.last_used_at ?? "-" },
+];
+async function addVaultEntry(pattern) {
+    try {
+        new RegExp(pattern);
+    }
+    catch (err) {
+        fail("USAGE", `invalid regex pattern: ${err.message}`, {
+            hint: "a pattern is a regex matched against the file name, e.g. '^kbank.*' — see `oled vault add --help`",
+        });
+    }
+    const password = await readSecretFromStdin();
+    if (!password) {
+        fail("INPUT_REQUIRED", "no password on stdin", {
+            hint: "the password is read from stdin, e.g. `printf %s 'secret' | oled vault add <pattern>`",
+        });
+    }
+    const db = await openDb();
+    const { upsertPassword } = await import("../../db/queries/vault.js");
+    const id = upsertPassword(db, pattern, password, config.dbEncryptionKey);
+    emitObject({ id, pattern });
+}
+async function listVaultEntries() {
+    const db = await openDb();
+    const { listPasswords } = await import("../../db/queries/vault.js");
+    const rows = listPasswords(db);
+    emitList(rows, VAULT_COLUMNS);
+}
+async function removeVaultEntry(patternOrId, opts) {
+    requireYes(opts, `removing vault entry "${patternOrId}"`);
+    const db = await openDb();
+    const { deletePassword } = await import("../../db/queries/vault.js");
+    if (!deletePassword(db, patternOrId)) {
+        fail("NOT_FOUND", `no vault entry matching "${patternOrId}"`);
+    }
+    emitObject({ pattern_or_id: patternOrId, removed: true });
+}
+export function registerVault(program) {
+    const vault = program.command("vault").description("Manage file-password patterns for encrypted statements");
+    vault
+        .command("add <pattern>")
+        .description("Add a vault entry for a file-name pattern (pipe the password on stdin)")
+        .addHelpText("after", [
+        "",
+        "Pattern: a regex matched case-insensitively against the file NAME only — not the relative path `ingest list` shows.",
+        "Example: printf %s 'secret' | oled vault add '^kbank.*' --json",
+    ].join("\n"))
+        .action(runAction(addVaultEntry));
+    vault
+        .command("list")
+        .description("List vault entries (never prints stored passwords)")
+        .action(runAction(listVaultEntries));
+    vault
+        .command("rm <patternOrId>")
+        .description("Remove a vault entry")
+        .option("--yes", "skip confirmation")
+        .action(runAction(removeVaultEntry));
+}

package/dist/cli/currency.js

@@ -0,0 +1,28 @@
+import { config } from "../config.js";
+/**
+ * buildConfig() resolves these with `||` over its own non-empty defaults, so
+ * config.displayLocale/displayCurrency are never empty; last-resort constants live in config.ts.
+ */
+export function getDisplayLocale() {
+    return config.displayLocale;
+}
+export function getDisplayCurrency() {
+    return config.displayCurrency;
+}
+export function formatCurrencyAmount(amount, options = {}) {
+    const locale = getDisplayLocale();
+    const currency = options.currency || getDisplayCurrency();
+    return new Intl.NumberFormat(locale, {
+        style: "currency",
+        currency,
+        minimumFractionDigits: options.minimumFractionDigits,
+        maximumFractionDigits: options.maximumFractionDigits,
+    }).format(Math.abs(amount));
+}
+export function formatAmount(amount, currency) {
+    return formatCurrencyAmount(amount, {
+        minimumFractionDigits: 2,
+        maximumFractionDigits: 2,
+        currency,
+    });
+}

package/dist/cli/db.js

@@ -0,0 +1,5 @@
+/** Dynamic import keeps libsql's native binding off the startup path of commands that never touch it (see status.ts). */
+export async function openDb() {
+    const { getDb } = await import("../db/connection.js");
+    return getDb();
+}

package/dist/cli/format.js

@@ -0,0 +1,71 @@
+import chalk from "chalk";
+// eslint-disable-next-line no-control-regex
+export const ANSI_RE = /\x1b\[[0-9;]*m/g;
+export function visibleLength(s) {
+    return s.replace(ANSI_RE, "").length;
+}
+export function formatInt(n) {
+    return n.toLocaleString("en-US");
+}
+/** Left-pad a key/value label to `width`, optionally bold (padding first so the ANSI codes don't count toward the width). */
+function padLabel(label, width, opts = {}) {
+    const padded = label.padEnd(width);
+    return opts.bold ? chalk.bold(padded) : padded;
+}
+/** Human output only (TTY: aligned two-column, piped: tab-separated) — never emits JSON; the caller owns --json. */
+export function printKeyValues(mode, rows, opts = {}) {
+    if (!mode.tty) {
+        process.stdout.write(rows.map(([k, v]) => `${k}\t${v}`).join("\n") + "\n");
+        return;
+    }
+    const width = Math.max(...rows.map(([k]) => k.length));
+    for (const [k, v] of rows) {
+        process.stdout.write(`${padLabel(k, width, { bold: !!opts.bold })}  ${v}\n`);
+    }
+}
+export function banner() {
+    return (chalk.bold("OpenLedger") +
+        chalk.dim("  ·  The Harness Layer for Personal Finance"));
+}
+const DISCLAIMER = "OpenLedger is an assistant, it only summarizes financial statements — verify amounts against your statements before relying on them.";
+const SCENARIO = [
+    "Drop bank statements in a folder; your AI posts each row to a local encrypted ledger.",
+    "Ask for net worth, spending, subscriptions, or debt payoff. Answers come from the ledger, not guesses.",
+    "Every entry is double-entry and stays on your machine.",
+];
+const CONTRACT = [
+    "Exit codes: 0 ok · 1 error · 2 usage · 3 not ready · 4 input required · 5 not found · 6 invalid · 7 partial.",
+    "Errors are one stderr JSON object with a hint; read output masks PII as [USER]/[CARD], masks are not data.",
+];
+function section(label, lines) {
+    return [chalk.bold.yellow(label), ...lines.map((l) => `  ${l}`)].join("\n");
+}
+export function helpScreen(commands, extraOptions = []) {
+    const options = [
+        ...extraOptions,
+        { name: "--version", desc: "Show the version and exit" },
+        { name: "--help", desc: "Show this help screen" },
+    ];
+    const nameWidth = Math.max(...commands.map((c) => c.name.length), ...options.map((o) => o.name.length));
+    const row = (name, desc) => `${chalk.cyan(name.padEnd(nameWidth))}    ${chalk.dim(desc)}`;
+    const usageLines = [
+        row("oled", "<command> [OPTIONS]"),
+        row("oled", "Show harness status (default)"),
+    ];
+    return [
+        "",
+        banner(),
+        "",
+        section("Usage", usageLines),
+        "",
+        section("What it does", SCENARIO),
+        "",
+        section("Commands", commands.map((c) => row(c.name, c.desc))),
+        "",
+        section("Options", options.map((o) => row(o.name, o.desc))),
+        "",
+        section("Contract", CONTRACT),
+        "",
+        chalk.dim(DISCLAIMER),
+    ].join("\n");
+}

package/dist/cli/index.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+import { buildProgram } from "./program.js";
+import { reportParseError } from "./output.js";
+// Exit quietly when a downstream pipe closes early (e.g. `oled transactions list --json | head`).
+const exitOnEpipe = (err) => {
+    if (err.code === "EPIPE")
+        process.exit(0);
+    throw err;
+};
+process.stdout.on("error", exitOnEpipe);
+process.stderr.on("error", exitOnEpipe);
+// Actions report their own failures inside runAction; only commander's parse
+// errors reach here, thrown by the exit override wired in buildProgram().
+try {
+    buildProgram().parse();
+}
+catch (err) {
+    reportParseError(err);
+}

package/dist/cli/output.js

@@ -0,0 +1,304 @@
+import chalk from "chalk";
+import { readFileSync } from "node:fs";
+import { Command } from "commander";
+import { visibleLength, ANSI_RE } from "./format.js";
+import { ValidationError } from "../lib/validate.js";
+import { errorMessage } from "../lib/result.js";
+/**
+ * emit()/emitSummary() no-op outside --json, so a stray call from a command's
+ * human layout can't corrupt it. A single-result command should use
+ * emitObject() instead, which renders in every mode.
+ */
+export const EXIT = {
+    OK: 0,
+    GENERIC: 1,
+    USAGE: 2,
+    NOT_READY: 3,
+    INPUT_REQUIRED: 4,
+    NOT_FOUND: 5,
+    INVALID: 6,
+    PARTIAL: 7,
+};
+class CliError extends Error {
+    code;
+    hint;
+    details;
+    constructor(code, message, opts) {
+        super(message);
+        this.name = "CliError";
+        this.code = code;
+        this.hint = opts?.hint;
+        this.details = opts?.details;
+    }
+}
+/** Never returns, so callers can use it as a value guard. */
+export function fail(code, message, opts) {
+    throw new CliError(code, message, opts);
+}
+/**
+ * ORs flags across the whole ancestor chain: commander leaves a global flag
+ * on whichever level declared/consumed it, so walking up finds it regardless.
+ */
+function resolveMode(cmd) {
+    let json = false;
+    let noColorFlag = false;
+    let c = cmd;
+    while (c) {
+        const o = c.opts();
+        if (o.json)
+            json = true;
+        if (o.color === false)
+            noColorFlag = true;
+        c = c.parent ?? undefined;
+    }
+    const tty = !!process.stdout.isTTY;
+    const envNoColor = !!process.env.NO_COLOR;
+    const noColor = json || noColorFlag || envNoColor || !tty;
+    return { json, noColor, tty, color: !noColor };
+}
+let current = null;
+function getOutputMode(cmd) {
+    current = resolveMode(cmd);
+    return current;
+}
+/** The mode resolved for the running action (lazily defaulted for direct calls). */
+export function currentMode() {
+    if (!current)
+        current = resolveMode(undefined);
+    return current;
+}
+/**
+ * libsql attaches `_metadata: { duration }` to every `.get()` row, so any
+ * command that spreads a row into its payload would publish it. Stripped once
+ * here at the boundary rather than at 39 query sites. Top level only: `.all()`
+ * rows carry no `_metadata`, so nested arrays never need it.
+ */
+function stripMetadata(value) {
+    if (value === null || typeof value !== "object" || !("_metadata" in value))
+        return value;
+    const rest = { ...value };
+    delete rest._metadata;
+    return rest;
+}
+function writeLine(stream, obj) {
+    stream.write(JSON.stringify(stripMetadata(obj)) + "\n");
+}
+export function emit(obj) {
+    if (currentMode().json)
+        writeLine(process.stdout, obj);
+}
+/** Terminal `{"type":"summary",...}` for a streaming command. */
+export function emitSummary(fields = {}) {
+    if (currentMode().json)
+        writeLine(process.stdout, { type: "summary", ...fields });
+}
+export function emitList(rows, columns) {
+    const m = currentMode();
+    if (m.json) {
+        for (const row of rows)
+            writeLine(process.stdout, row);
+        return;
+    }
+    if (m.tty) {
+        renderTable(rows, columns, m.color);
+        return;
+    }
+    renderPlain(rows, columns);
+}
+/** Human/plain output is tab-separated key/value lines, ANSI-free so it stays stable when piped. */
+export function emitObject(obj) {
+    const row = stripMetadata(obj);
+    if (currentMode().json) {
+        emit(row);
+        return;
+    }
+    for (const [k, v] of Object.entries(row)) {
+        const s = v !== null && typeof v === "object" ? JSON.stringify(v) : String(v);
+        process.stdout.write(`${k}\t${s}\n`);
+    }
+}
+function renderPlain(rows, columns) {
+    const lines = rows.map((row) => columns.map((c) => c.value(row).replace(ANSI_RE, "")).join("\t"));
+    if (lines.length)
+        process.stdout.write(lines.join("\n") + "\n");
+}
+function renderTable(rows, columns, color) {
+    const cells = rows.map((row) => columns.map((c) => c.value(row)));
+    const widths = columns.map((c, i) => Math.max(visibleLength(c.header), ...cells.map((r) => visibleLength(r[i]))));
+    const pad = (s, width, align) => {
+        const gap = " ".repeat(Math.max(0, width - visibleLength(s)));
+        return align === "right" ? gap + s : s + gap;
+    };
+    const header = columns
+        .map((c, i) => pad(color ? chalk.bold(c.header) : c.header, widths[i], c.align))
+        .join("  ")
+        .trimEnd();
+    const out = [header];
+    for (const r of cells) {
+        out.push(columns.map((c, i) => pad(r[i], widths[i], c.align)).join("  ").trimEnd());
+    }
+    process.stdout.write(out.join("\n") + "\n");
+}
+export function requireYes(opts, what) {
+    if (!opts.yes) {
+        fail("INPUT_REQUIRED", `${what} needs confirmation`, {
+            hint: "re-run with --yes to proceed",
+        });
+    }
+}
+/** Empty string when stdin is a TTY (no pipe). */
+export async function readStdinToEnd() {
+    if (process.stdin.isTTY)
+        return "";
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks).toString("utf8");
+}
+/** Trims a single trailing newline, CRLF-aware. */
+export async function readSecretFromStdin() {
+    const raw = await readStdinToEnd();
+    return raw.replace(/\r?\n$/, "");
+}
+/** Auto-detects a JSON array (first non-ws char is `[`) vs NDJSON. Row validation is the caller's job. */
+export async function readStdinBatch(inputPath) {
+    let source;
+    if (inputPath) {
+        try {
+            source = readFileSync(inputPath, "utf8");
+        }
+        catch (err) {
+            fail("NOT_FOUND", `cannot read --input file: ${err.message}`, {
+                hint: "pass a readable NDJSON (or JSON array) file path",
+            });
+        }
+    }
+    else {
+        source = await readStdinToEnd();
+    }
+    const raw = source.replace(/^\uFEFF/, "");
+    const firstNonWs = raw.match(/\S/);
+    if (!firstNonWs)
+        fail("USAGE", inputPath ? `no transaction data in ${inputPath}` : "no transaction data on stdin", {
+            hint: "pass NDJSON rows via --input <file> or pipe them on stdin",
+        });
+    if (firstNonWs[0] === "[") {
+        try {
+            const parsed = JSON.parse(raw);
+            if (!Array.isArray(parsed))
+                fail("USAGE", "stdin JSON must be an array of transactions");
+            return parsed;
+        }
+        catch (err) {
+            if (err instanceof CliError)
+                throw err;
+            fail("USAGE", `invalid JSON array on stdin: ${err.message}`);
+        }
+    }
+    const out = [];
+    const lines = raw.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i].trim();
+        if (!line)
+            continue;
+        try {
+            out.push(JSON.parse(line));
+        }
+        catch (err) {
+            fail("USAGE", `invalid JSON on line ${i + 1}: ${err.message}`, {
+                details: { line: i + 1 },
+            });
+        }
+    }
+    return out;
+}
+export function asRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : null;
+}
+const NOT_READY_PATTERNS = [
+    "failed to open database",
+    "wrong encryption key",
+    "corrupt database",
+    "not a database",
+    "file is encrypted",
+    "not configured",
+    "not an openledger database",
+];
+function isNotReadyError(err) {
+    const msg = err instanceof Error ? err.message.toLowerCase() : "";
+    return NOT_READY_PATTERNS.some((p) => msg.includes(p));
+}
+function toCliError(err) {
+    if (err instanceof CliError)
+        return err;
+    if (err instanceof ValidationError) {
+        return new CliError("USAGE", err.message, {
+            hint: "append --help to the command for its flags and usage",
+        });
+    }
+    if (isNotReadyError(err)) {
+        return new CliError("NOT_READY", err.message, {
+            hint: "run `oled config --generate-key` to configure the harness",
+        });
+    }
+    return new CliError("GENERIC", errorMessage(err));
+}
+/** Domain errors are thrown as plain `Error`s, so they're matched by message, not type. */
+export function mapNotFoundError(err, extraNotFound) {
+    const message = errorMessage(err);
+    if (/not found/i.test(message) || (extraNotFound && extraNotFound.test(message))) {
+        fail("NOT_FOUND", message);
+    }
+    fail("INVALID", message);
+}
+function reportError(err) {
+    const cliErr = toCliError(err);
+    if (currentMode().json) {
+        const payload = {
+            code: `E_${cliErr.code}`,
+            message: cliErr.message,
+        };
+        if (cliErr.hint !== undefined)
+            payload.hint = cliErr.hint;
+        if (cliErr.details !== undefined)
+            payload.details = cliErr.details;
+        process.stderr.write(JSON.stringify({ error: payload }) + "\n");
+    }
+    else {
+        process.stderr.write(`error: ${cliErr.message}\n`);
+        if (cliErr.hint)
+            process.stderr.write(`hint: ${cliErr.hint}\n`);
+    }
+    return EXIT[cliErr.code];
+}
+/**
+ * At the parse boundary commander aborts before any action runs, so nothing
+ * resolved the mode and `--json` may still be unparsed — argv is the only
+ * signal left.
+ */
+export function jsonRequested() {
+    return process.argv.includes("--json");
+}
+export function reportParseError(err) {
+    current = { json: jsonRequested(), noColor: true, tty: !!process.stdout.isTTY, color: false };
+    process.exitCode = reportError(err);
+}
+/**
+ * The command is commander's last positional arg. Sets `process.exitCode` rather
+ * than calling `process.exit` so buffered stdout/stderr flush before the process ends.
+ */
+export function runAction(fn) {
+    return async (...args) => {
+        const last = args[args.length - 1];
+        getOutputMode(last instanceof Command ? last : undefined);
+        try {
+            await fn(...args);
+        }
+        catch (err) {
+            process.exitCode = reportError(err);
+        }
+    };
+}

package/dist/cli/program.js

@@ -0,0 +1,140 @@
+import { Command, Help } from "commander";
+import { createRequire } from "module";
+// Side-effect import: loads .env and resolves the config singleton first.
+import "../config.js";
+import { helpScreen } from "./format.js";
+import { fail, jsonRequested, runAction } from "./output.js";
+import { registerStatus, showStatus } from "./commands/status.js";
+import { registerDoctor } from "./commands/doctor.js";
+import { registerSetup } from "./commands/setup.js";
+import { registerConfig } from "./commands/config.js";
+import { registerIngest } from "./commands/ingest.js";
+import { registerFiles } from "./commands/files.js";
+import { registerVault } from "./commands/vault.js";
+import { registerTransactions } from "./commands/transactions.js";
+import { registerAccounts } from "./commands/accounts.js";
+import { registerMerchants } from "./commands/merchants.js";
+import { registerQuestions } from "./commands/questions.js";
+import { registerReport } from "./commands/report.js";
+import { registerNotes } from "./commands/notes.js";
+import { registerDatasets } from "./commands/datasets.js";
+import { registerOpen } from "./commands/open.js";
+export const COMMANDS = [
+    { name: "status", desc: "Status: config, database, ledger counts, net worth (default)" },
+    { name: "doctor", desc: "Diagnose the harness environment" },
+    { name: "setup", desc: "Install the skill for an agent CLI (--host <id> | --dir <path>)" },
+    { name: "config", desc: "Configuration" },
+    { name: "ingest", desc: "Ingest pipeline: list / prepare / commit / done / fail" },
+    { name: "files", desc: "Browse ingested files (list / show / drop)" },
+    { name: "vault", desc: "Manage file-password patterns for encrypted statements" },
+    { name: "transactions", desc: "Transactions: list / show / add / update / delete / recategorize / dedupe / merge" },
+    { name: "accounts", desc: "Manage the chart of accounts" },
+    { name: "merchants", desc: "Manage merchants and their default accounts" },
+    { name: "questions", desc: "List, answer, and defer open questions" },
+    { name: "report", desc: "Income, expenses, and net" },
+    { name: "notes", desc: "Manage freeform notes" },
+    { name: "datasets", desc: "Reference datasets" },
+    { name: "open", desc: "Open the data folder in file explorer" },
+];
+const GLOBAL_OPTIONS = [
+    { name: "--json", desc: "Emit NDJSON (machine-readable) instead of human output" },
+    { name: "--no-color", desc: "Disable ANSI color output" },
+];
+/** `oled ingest list` for a leaf, `oled` for the root: the command whose help answers the error. */
+function commandPath(cmd) {
+    const names = [];
+    for (let c = cmd; c; c = c.parent)
+        names.unshift(c.name());
+    return names.join(" ");
+}
+/**
+ * Parse failures never reach runAction, so they are mapped onto the same error
+ * contract here — USAGE, with the erroring command's own help as the hint.
+ * --help and --version already printed and keep their exit code.
+ */
+function parseFailureHandler(cmd) {
+    return (err) => {
+        if (err.exitCode === 0)
+            return;
+        // A noun reached without a verb: commander printed the noun's help screen,
+        // which is the answer for a human. --json promised one error line instead.
+        if (err.code === "commander.help") {
+            if (!jsonRequested())
+                return;
+            fail("USAGE", `${commandPath(cmd)} needs a subcommand`, {
+                hint: `one of: ${cmd.commands.map((sub) => sub.name()).join(", ")}`,
+            });
+        }
+        // The root takes no positional argument, so a stray one is a mistyped command.
+        if (err.code === "commander.excessArguments" && !cmd.parent) {
+            fail("USAGE", `unknown command '${cmd.args[0]}'`, {
+                hint: "run `oled --help` for the list of commands",
+            });
+        }
+        fail("USAGE", err.message.replace(/^error:\s*/, ""), {
+            hint: `run \`${commandPath(cmd)} --help\` for its flags and usage`,
+        });
+    };
+}
+/** Builds the full commander program: pure construction — callers own `.parse()` / `.parseAsync()`. */
+export function buildProgram() {
+    const require = createRequire(import.meta.url);
+    const { version } = require("../../package.json");
+    const program = new Command();
+    // Required so a command with BOTH a bare action and subcommands (config)
+    // dispatches the subcommand instead of swallowing its options into the bare action.
+    program.enablePositionalOptions();
+    program
+        .name("oled")
+        .description("The Harness Layer for Personal Finance")
+        .version(version)
+        .addHelpCommand(false)
+        // Bare `oled` reports harness status — the same action as `status`, which
+        // redacts by default; `oled status --no-redact` is the way to opt out.
+        .action(runAction(showStatus));
+    registerOpen(program);
+    registerStatus(program);
+    registerDoctor(program);
+    registerSetup(program);
+    registerConfig(program);
+    registerIngest(program);
+    registerFiles(program);
+    registerVault(program);
+    registerTransactions(program);
+    registerAccounts(program);
+    registerMerchants(program);
+    registerQuestions(program);
+    registerReport(program);
+    registerNotes(program);
+    registerDatasets(program);
+    // --json/--no-color on every command so they work before or after the
+    // subcommand name (getOutputMode() OR-walks the chain to find them), and an
+    // exit override per command so a parse failure names its own help.
+    function configureEveryLevel(cmd) {
+        cmd
+            .option("--json", "Emit NDJSON (machine-readable) instead of human output")
+            .option("--no-color", "Disable ANSI color output")
+            .exitOverride(parseFailureHandler(cmd))
+            // Commander writes its own plain-text error line, and a help screen for a
+            // verbless noun, before exiting; under --json the CliError contract is the
+            // only thing allowed on stderr.
+            .configureOutput({
+            outputError: () => { },
+            writeErr: (str) => {
+                if (!jsonRequested())
+                    process.stderr.write(str);
+            },
+        });
+        for (const sub of cmd.commands)
+            configureEveryLevel(sub);
+    }
+    configureEveryLevel(program);
+    program.configureHelp({
+        // configureHelp is inherited by subcommands, so guard explicitly: only the
+        // root gets the branded screen; subcommands keep commander's default formatter.
+        formatHelp: (cmd, helper) => cmd === program
+            ? helpScreen(COMMANDS, GLOBAL_OPTIONS)
+            : Help.prototype.formatHelp.call(helper, cmd, helper),
+    });
+    return program;
+}