@morroc/open-ledger 0.14.1

package/dist/cli/commands/ingest.js

@@ -0,0 +1,203 @@
+import { EXIT, currentMode, emit, emitList, emitObject, emitSummary, fail, readSecretFromStdin, runAction, } from "../output.js";
+import { openDb } from "../db.js";
+import { commitIngest } from "./ingest-commit.js";
+/**
+ * The accepted-input facts, so help text can't drift from the enforcing table;
+ * source.ts avoids mupdf/libsql, so it's safe on the startup path.
+ */
+import { MAX_SOURCE_BYTES, SUPPORTED_EXTS } from "../../extract/source.js";
+const INGEST_COLUMNS = [
+    { header: "Status", value: (r) => r.status },
+    { header: "Enc", value: (r) => (r.encrypted ? `yes(${r.vaultCandidates})` : "no") },
+    { header: "File ID", value: (r) => r.fileId ?? "-" },
+    { header: "Path", value: (r) => r.relPath },
+    { header: "Note", value: (r) => r.note ?? "" },
+];
+async function listIngest(opts) {
+    const db = await openDb();
+    const { discoverFiles } = await import("../../ingest/prepare.js");
+    let regex;
+    if (opts.regex) {
+        try {
+            regex = new RegExp(opts.regex);
+        }
+        catch (err) {
+            fail("USAGE", `invalid --regex: ${err.message}`);
+        }
+    }
+    const entries = await discoverFiles(db, { regex });
+    const counts = {
+        new: 0,
+        pending: 0,
+        ingested: 0,
+        failed: 0,
+        unreadable: 0,
+    };
+    for (const e of entries)
+        counts[e.status]++;
+    const total = entries.length;
+    const mode = currentMode();
+    if (mode.json) {
+        for (const e of entries) {
+            emit({
+                type: "file",
+                path: e.path,
+                rel_path: e.relPath,
+                hash: e.hash,
+                file_id: e.fileId,
+                status: e.status,
+                encrypted: e.encrypted,
+                vault_candidates: e.vaultCandidates,
+                note: e.note ?? null,
+            });
+        }
+        emitSummary({ ...counts, total });
+        return;
+    }
+    emitList(entries, INGEST_COLUMNS);
+    if (mode.tty) {
+        process.stdout.write(`\n${counts.new} new, ${counts.pending} pending, ${counts.ingested} ingested, ${counts.failed} failed, ${counts.unreadable} unreadable (${total} total)\n`);
+    }
+}
+const PASSWORD_HINT = "pipe the password with --password-stdin, or store it once via `oled vault add <pattern>`";
+const ACCEPTED_EXTS = SUPPORTED_EXTS.join(" ");
+const SIZE_LIMIT = `${MAX_SOURCE_BYTES / (1024 * 1024)} MB`;
+const PREPARE_FAILURES = {
+    not_found: { code: "NOT_FOUND", hint: "run `oled ingest list --json` to see what is discoverable" },
+    unsupported_extension: {
+        code: "USAGE",
+        hint: `supported: ${ACCEPTED_EXTS} — export other formats first`,
+    },
+    kind_mismatch: { code: "USAGE", hint: "the bytes disagree with the extension; re-export or rename" },
+    too_large: {
+        code: "INVALID",
+        hint: `the limit is ${SIZE_LIMIT} — split the file or export it smaller`,
+    },
+    unreadable: { code: "NOT_FOUND", hint: "check the path and its permissions" },
+    pdf_unreadable: { code: "INVALID", hint: "the PDF may be corrupt; re-download or re-export it" },
+    password_required: { code: "INPUT_REQUIRED", hint: PASSWORD_HINT },
+    wrong_password: { code: "INPUT_REQUIRED", hint: PASSWORD_HINT },
+    ocr_unreachable: { code: "NOT_READY", hint: "start the OCR server, or re-run with --no-ocr" },
+    ocr_rejected: {
+        code: "NOT_READY",
+        hint: "check the model against `oled doctor --json`, or re-run with --no-ocr",
+    },
+};
+/** What each route adds to the shared head: a document to read, or page images. */
+const PREPARE_PAYLOAD = {
+    text: (result) => ({
+        ...(result.model ? { ocr_model: result.model } : {}),
+        document: result.document,
+        pages: result.pages,
+        // Only the OCR route reads page by page, so only it can lose one.
+        ...(result.source === "ocr" ? { failed_pages: result.failedPages } : {}),
+    }),
+    images: (result) => ({ ...(result.dpi ? { dpi: result.dpi } : {}), pages: result.pages }),
+};
+async function prepareIngest(pathOrId, opts) {
+    const db = await openDb();
+    const { prepareFile } = await import("../../ingest/prepare.js");
+    const password = opts.passwordStdin ? await readSecretFromStdin() : undefined;
+    const result = await prepareFile(db, pathOrId, {
+        password,
+        force: !!opts.force,
+        rescan: !!opts.rescan,
+        noOcr: opts.ocr === false,
+    });
+    if (!result.ok) {
+        const { code, hint } = PREPARE_FAILURES[result.reason];
+        fail(code, result.message, { hint });
+    }
+    emitObject({
+        file_id: result.fileId,
+        kind: result.kind,
+        source: result.source,
+        text_layer: result.textLayer,
+        page_count: result.pageCount,
+        ...PREPARE_PAYLOAD[result.kind](result),
+    });
+    // A page the endpoint could not read is a hole in the document, not a failed run.
+    if (result.kind === "text" && result.failedPages.length > 0)
+        process.exitCode = EXIT.PARTIAL;
+}
+async function completeIngest(id, opts) {
+    const db = await openDb();
+    const { markFileIngested } = await import("../../db/queries/files.js");
+    const changes = markFileIngested(db, id, { source: opts.agent ?? "external" });
+    if (changes === 0)
+        fail("NOT_FOUND", `no ingest entry: ${id}`);
+    const { cleanCache } = await import("../../ingest/prepare.js");
+    const { removed } = cleanCache(id);
+    emitObject({ file_id: id, status: "ingested", cache_removed: removed });
+}
+async function failIngest(id, opts) {
+    if (!opts.error)
+        fail("USAGE", "`ingest fail` requires --error <text>");
+    const db = await openDb();
+    const { markFileFailed } = await import("../../db/queries/files.js");
+    const changes = markFileFailed(db, id, { source: opts.agent ?? "external", error: opts.error });
+    if (changes === 0)
+        fail("NOT_FOUND", `no ingest entry: ${id}`);
+    const { cleanCache } = await import("../../ingest/prepare.js");
+    const { removed } = cleanCache(id);
+    emitObject({ file_id: id, status: "failed", cache_removed: removed });
+}
+export function registerIngest(program) {
+    const ingest = program
+        .command("ingest")
+        .description("Ingest pipeline: list / prepare / commit / done / fail")
+        .addHelpText("after", [
+        "",
+        "Behavior: the statement pipeline, list the files waiting, prepare one for reading, commit its rows, mark it done or failed.",
+        "Typical flow: list, prepare <id>, read what prepare returns, commit --file <sf:id> with the rows on stdin (or --input <batch>), then done <sf:id>.",
+        `Accepts ${ACCEPTED_EXTS}, up to ${SIZE_LIMIT}. Locked PDFs exit 4: pass the password with --password-stdin, or store it once with vault add <pattern>.`,
+        "Example: oled ingest prepare statement.pdf --json",
+    ].join("\n"));
+    ingest
+        .command("list")
+        .description("List items in the ingest pipeline")
+        .option("--regex <pattern>", "filter items by regex")
+        .action(runAction(listIngest));
+    ingest
+        .command("prepare <pathOrId>")
+        .description("Extract a statement file into text (or page images) to read")
+        .option("--password-stdin", "read the password for a locked PDF from stdin")
+        .option("--force", "re-register the file, dropping the prior ingest's rows and artifacts")
+        .option("--rescan", "ignore the text layer and read the page images instead")
+        .option("--no-ocr", "ignore the OCR server and return the page images to you")
+        .addHelpText("after", [
+        "",
+        'Behavior: reads the file once and returns text whenever it can. A PDF carrying its own text layer is extracted directly. Otherwise the pages become images — a scan is rasterized, a photo is taken as it lies — and the OCR server reads them when one is configured (`oled config --ocr-url <url>`); with none configured they come back to you. The reader is named in source: "text-layer" or "ocr" when kind is "text", "raster" or "original" when kind is "images".',
+        'Output kind "text": one `document` path to read. Inside it, pages are separated by `--- page N ---` markers; cite the row\'s page as source_page on commit. Page numbers count from 1 everywhere — the markers, the pages[] entries, and source_page.',
+        'Output kind "images": one path per page under pages[], in order — read them yourself.',
+        "Escape hatches: --rescan ignores a garbled text layer and reads the pages instead; --no-ocr ignores the OCR server and returns the page images. Both together always return images.",
+        "Exits: 2 the file type is not supported, 3 the OCR server is misconfigured or unreachable, 4 the PDF needs a password, 5 nothing at that path or id, 6 the file is too large or corrupt, 7 the OCR server failed on some pages — each carries a `[page N: OCR failed]` line in the document and is listed in failed_pages; re-run with --no-ocr to read those pages yourself.",
+        "Example: oled ingest prepare statement.pdf --json",
+    ].join("\n"))
+        .action(runAction(prepareIngest));
+    ingest
+        .command("commit")
+        .description("Commit extracted transactions (NDJSON/JSON array via --input file or stdin) into the ledger")
+        .option("--file <id>", "default source file id for committed rows")
+        .option("--input <path>", "read the batch from an NDJSON/JSON file instead of stdin")
+        .addHelpText("after", [
+        "",
+        "Behavior: posts one batch of statement rows; each item resolves account hints, links merchants, and raises questions instead of failing.",
+        'Item: {"date":"YYYY-MM-DD","description":"...","debit_account":"expense:food","credit_account":"asset:bank:kbank","amount":135.00,"source_page":2,"row_index":0,"raw_descriptor":"<verbatim bank text>","merchant":{"canonical_name":"..."}}',
+        "Rules: amount > 0, direction comes from the two accounts, never a sign; account ids are hints (resolved exact, then fuzzy, then placeholder); set row_index + source_page and pass --file <sf:id> so a re-run is an idempotent duplicate:true no-op.",
+        "Compound rows (payslip, FX): replace debit/credit/amount with linked:[{debit_account,credit_account,amount},...] sharing one account; legs commit atomically under one group_id. Cross-currency rows become two linked legs through equity:conversion:<ccy>.",
+        "Output: one result per item, then a summary with batch_id/posted/duplicates/failed. Exit 7 = some rows failed; duplicate:true is a success.",
+    ].join("\n"))
+        .action(runAction(commitIngest));
+    ingest
+        .command("done <id>")
+        .description("Mark an ingest item as done")
+        .option("--agent <name>", "name of the completing agent")
+        .action(runAction(completeIngest));
+    ingest
+        .command("fail <id>")
+        .description("Mark an ingest item as failed")
+        .option("--agent <name>", "name of the failing agent")
+        .option("--error <text>", "failure reason")
+        .action(runAction(failIngest));
+}

package/dist/cli/commands/merchants.js

@@ -0,0 +1,140 @@
+import { emitList, emitObject, fail, mapNotFoundError, requireYes, runAction, } from "../output.js";
+import { openDb } from "../db.js";
+import { listMerchants as queryMerchants, findMerchantByAlias, findMerchantById, upsertMerchant as upsertMerchantRow, setMerchantDefaultAccount, clearMerchantDefaultAccount, mergeMerchants as mergeMerchantRows, } from "../../db/queries/merchants.js";
+import { findAccountById } from "../../db/queries/accounts.js";
+import { applyRedaction } from "../../privacy/redactor.js";
+import * as z from "zod";
+import { parseInput, str, bool } from "../../lib/validate.js";
+// `canonical_name` is the only free-text field; ids and the default-account link are structured data left verbatim.
+const MERCHANT_REDACT_FIELDS = ["canonical_name"];
+const MERCHANT_COLUMNS = [
+    { header: "ID", value: (m) => m.id },
+    { header: "Name", value: (m) => m.canonical_name },
+    { header: "Default Account", value: (m) => m.default_account_id ?? "" },
+    { header: "Aliases", value: (m) => String(m.alias_count), align: "right" },
+];
+async function listMerchants(opts) {
+    const db = await openDb();
+    const rows = applyRedaction(queryMerchants(db), !!opts.redact, MERCHANT_REDACT_FIELDS);
+    emitList(rows, MERCHANT_COLUMNS);
+}
+const RESOLVE_MERCHANT_SPEC = z.object({ descriptor: str() });
+async function resolveMerchant(opts) {
+    const parsed = parseInput(RESOLVE_MERCHANT_SPEC, opts);
+    const db = await openDb();
+    const match = findMerchantByAlias(db, parsed.descriptor);
+    if (!match) {
+        emitObject({ found: false });
+        return;
+    }
+    emitObject({
+        found: true,
+        merchant_id: match.merchant.id,
+        canonical_name: match.merchant.canonical_name,
+        default_account_id: match.default_account_id,
+    });
+}
+const UPSERT_MERCHANT_SPEC = z.object({
+    name: str(),
+    alias: str().optional(),
+    default_account: str().optional(),
+});
+async function upsertMerchant(opts) {
+    const parsed = parseInput(UPSERT_MERCHANT_SPEC, opts);
+    const db = await openDb();
+    if (parsed.default_account && !findAccountById(db, parsed.default_account)) {
+        fail("NOT_FOUND", `account "${parsed.default_account}" not found`);
+    }
+    const input = { canonical_name: parsed.name };
+    if (parsed.alias)
+        input.alias = parsed.alias;
+    if (parsed.default_account)
+        input.default_account_id = parsed.default_account;
+    emitObject({ ...upsertMerchantRow(db, input) });
+}
+const SET_DEFAULT_SPEC = z.object({
+    merchant: str(),
+    account: str().optional(),
+    clear: bool().optional(),
+});
+async function setMerchantDefault(opts) {
+    const parsed = parseInput(SET_DEFAULT_SPEC, opts);
+    if (!!parsed.account === !!parsed.clear) {
+        fail("USAGE", "exactly one of --account or --clear is required");
+    }
+    const db = await openDb();
+    if (!findMerchantById(db, parsed.merchant)) {
+        fail("NOT_FOUND", `merchant "${parsed.merchant}" not found`);
+    }
+    if (parsed.clear) {
+        const result = clearMerchantDefaultAccount(db, parsed.merchant);
+        if (!result)
+            fail("NOT_FOUND", `merchant "${parsed.merchant}" not found`);
+        emitObject({ merchant_id: parsed.merchant, before: result.before, after: null });
+        return;
+    }
+    if (!findAccountById(db, parsed.account)) {
+        fail("NOT_FOUND", `account "${parsed.account}" not found`);
+    }
+    const result = setMerchantDefaultAccount(db, parsed.merchant, parsed.account);
+    emitObject({ merchant_id: parsed.merchant, ...result });
+}
+const MERGE_MERCHANTS_SPEC = z.object({
+    from: str(),
+    to: str(),
+});
+async function mergeMerchants(opts) {
+    const parsed = parseInput(MERGE_MERCHANTS_SPEC, opts);
+    requireYes(opts, "merging merchants");
+    const db = await openDb();
+    let result;
+    try {
+        result = mergeMerchantRows(db, parsed.from, parsed.to);
+    }
+    catch (err) {
+        mapNotFoundError(err);
+    }
+    emitObject({ from: parsed.from, to: parsed.to, ...result });
+}
+export function registerMerchants(program) {
+    const merchants = program
+        .command("merchants")
+        .description("Manage merchants and their default accounts")
+        .addHelpText("after", [
+        "",
+        "Behavior: manages merchants and their default accounts; an alias maps raw bank text to a merchant.",
+        "Typical flow: resolve a descriptor; if unknown, upsert with a name and alias, then set-default.",
+        "Example: oled merchants resolve --descriptor \"POS STARBUCKS\" --json",
+    ].join("\n"));
+    merchants
+        .command("list")
+        .description("List merchants")
+        .option("--no-redact", "skip PII redaction (on by default)")
+        .action(runAction(listMerchants));
+    merchants
+        .command("resolve")
+        .description("Resolve a merchant from a descriptor")
+        .option("--descriptor <text>", "raw transaction descriptor")
+        .action(runAction(resolveMerchant));
+    merchants
+        .command("upsert")
+        .description("Create or update a merchant")
+        .option("--name <name>", "merchant canonical name")
+        .option("--alias <alias>", "merchant alias to add")
+        .option("--default-account <id>", "default account id")
+        .action(runAction(upsertMerchant));
+    merchants
+        .command("set-default")
+        .description("Set or clear a merchant's default account")
+        .option("--merchant <id>", "merchant id")
+        .option("--account <id>", "account id")
+        .option("--clear", "clear the default account instead of setting one")
+        .action(runAction(setMerchantDefault));
+    merchants
+        .command("merge")
+        .description("Merge one merchant into another")
+        .option("--from <id>", "merchant id to merge from")
+        .option("--to <id>", "merchant id to merge into")
+        .option("--yes", "skip confirmation")
+        .action(runAction(mergeMerchants));
+}

package/dist/cli/commands/notes.js

@@ -0,0 +1,71 @@
+import { emitList, fail, requireYes, runAction } from "../output.js";
+import { openDb } from "../db.js";
+import * as z from "zod";
+import { parseInput, str, num } from "../../lib/validate.js";
+const VALID_CATEGORIES = ["rule", "preference", "fact"];
+// `content` is the only free-text field; id/category/created_at are
+// structured data left verbatim.
+const NOTE_REDACT_FIELDS = ["content"];
+const NOTE_COLUMNS = [
+    { header: "ID", value: (r) => String(r.id), align: "right" },
+    { header: "Category", value: (r) => r.category },
+    { header: "Content", value: (r) => r.content },
+    { header: "Created At", value: (r) => r.created_at },
+];
+async function listNotes(opts) {
+    const { listNotes: queryNotes } = await import("../../db/queries/notes.js");
+    const db = await openDb();
+    let rows = queryNotes(db);
+    if (opts.redact) {
+        const { applyRedaction } = await import("../../privacy/redactor.js");
+        rows = applyRedaction(rows, true, NOTE_REDACT_FIELDS);
+    }
+    emitList(rows, NOTE_COLUMNS);
+}
+const ADD_NOTE_SPEC = z.object({
+    content: str(),
+    category: z.enum(VALID_CATEGORIES).default("fact"),
+});
+async function addNote(opts) {
+    const parsed = parseInput(ADD_NOTE_SPEC, opts);
+    const { listNotes: queryNotes, addNote: addNoteRow } = await import("../../db/queries/notes.js");
+    const db = await openDb();
+    addNoteRow(db, parsed.content, parsed.category);
+    const saved = queryNotes(db)
+        .filter((m) => m.content === parsed.content && m.category === parsed.category)
+        .sort((a, b) => b.id - a.id)[0];
+    emitList(saved ? [saved] : [], NOTE_COLUMNS);
+}
+// Positional `<id>` args aren't commander opts; parsed through the same spec
+// API with an ad hoc raw object so the coercion message stays consistent.
+const NOTE_ID_SPEC = z.object({ id: num() });
+const NOTE_ID_LABELS = { id: "note id" };
+async function removeNote(id, opts) {
+    requireYes(opts, "removing this note");
+    const parsed = parseInput(NOTE_ID_SPEC, { id }, { labels: NOTE_ID_LABELS });
+    const { deleteNote: deleteNoteRow } = await import("../../db/queries/notes.js");
+    const db = await openDb();
+    const deleted = deleteNoteRow(db, parsed.id);
+    if (!deleted)
+        fail("NOT_FOUND", `note "${id}" not found`);
+    emitList([deleted], NOTE_COLUMNS);
+}
+export function registerNotes(program) {
+    const notes = program.command("notes").description("Manage freeform notes");
+    notes
+        .command("list")
+        .description("List notes")
+        .option("--no-redact", "skip PII redaction (on by default)")
+        .action(runAction(listNotes));
+    notes
+        .command("add")
+        .description("Add a note")
+        .option("--content <text>", "note content")
+        .option("--category <cat>", "note category: rule, preference, or fact")
+        .action(runAction(addNote));
+    notes
+        .command("rm <id>")
+        .description("Remove a note")
+        .option("--yes", "skip confirmation")
+        .action(runAction(removeNote));
+}

package/dist/cli/commands/open.js

@@ -0,0 +1,54 @@
+import { spawn } from "child_process";
+import { existsSync, mkdirSync } from "fs";
+import chalk from "chalk";
+import { getDataDir } from "../../config.js";
+import { currentMode, emit, runAction } from "../output.js";
+function openerCommand() {
+    switch (process.platform) {
+        case "darwin": return "open";
+        case "win32": return "explorer";
+        case "linux": return "xdg-open";
+        default: return null;
+    }
+}
+// Never rejects: resolves with an error message on spawn failure, else undefined.
+function spawnOpener(cmd, dataDir) {
+    return new Promise((resolvePromise) => {
+        const child = spawn(cmd, [dataDir], { stdio: "ignore", detached: true });
+        child.once("error", (err) => resolvePromise(err.message));
+        child.once("spawn", () => resolvePromise(undefined));
+        child.unref();
+    });
+}
+// The path is reported even when the opener fails — it is still useful on its own.
+async function openDataDir() {
+    const dataDir = getDataDir();
+    if (!existsSync(dataDir))
+        mkdirSync(dataDir, { recursive: true });
+    const cmd = openerCommand();
+    const spawnError = cmd
+        ? await spawnOpener(cmd, dataDir)
+        : `don't know how to open the file manager on ${process.platform}`;
+    const mode = currentMode();
+    if (mode.json) {
+        const result = { path: dataDir };
+        if (spawnError)
+            result.spawn_error = spawnError;
+        emit(result);
+        return;
+    }
+    if (!mode.tty) {
+        process.stdout.write(dataDir + "\n");
+        return;
+    }
+    console.log(chalk.dim(`Data folder: ${dataDir}`));
+    if (spawnError) {
+        console.log(chalk.yellow(`Couldn't open the folder automatically: ${spawnError}. Open it manually with the path above.`));
+    }
+}
+export function registerOpen(program) {
+    program
+        .command("open")
+        .description("Open the data folder in file explorer")
+        .action(runAction(openDataDir));
+}

package/dist/cli/commands/questions.js

@@ -0,0 +1,119 @@
+import { emitList, fail, runAction } from "../output.js";
+import { openDb } from "../db.js";
+import * as z from "zod";
+import { parseInput, str, int } from "../../lib/validate.js";
+import { parseJsonOrNull } from "../../lib/json.js";
+function toListRow(row) {
+    return {
+        id: row.id,
+        kind: row.kind,
+        prompt: row.prompt,
+        transaction_id: row.transaction_id,
+        account_id: row.account_id,
+        options: parseJsonOrNull(row.options_json),
+        context: parseJsonOrNull(row.context_json),
+        file_id: row.file_id,
+        created_at: row.created_at,
+    };
+}
+// `prompt` is the only free-text field; options/context are structured JSON
+// carrying ids the agent needs verbatim, so they're left intact.
+const QUESTION_REDACT_FIELDS = ["prompt"];
+const LIST_COLUMNS = [
+    { header: "ID", value: (r) => r.id },
+    { header: "Kind", value: (r) => r.kind ?? "" },
+    { header: "Prompt", value: (r) => r.prompt },
+    { header: "Transaction ID", value: (r) => r.transaction_id ?? "" },
+    { header: "Account ID", value: (r) => r.account_id ?? "" },
+    { header: "Options", value: (r) => (r.options != null ? JSON.stringify(r.options) : "") },
+    { header: "Context", value: (r) => (r.context != null ? JSON.stringify(r.context) : "") },
+    { header: "File ID", value: (r) => r.file_id ?? "" },
+    { header: "Created At", value: (r) => r.created_at },
+];
+const ANSWERED_COLUMNS = [
+    { header: "ID", value: (r) => r.id },
+    { header: "Kind", value: (r) => r.kind ?? "" },
+    { header: "Answer", value: (r) => r.answer },
+    { header: "Rule Key", value: (r) => r.rule_key ?? "" },
+];
+const DEFER_COLUMNS = [
+    { header: "ID", value: (r) => r.id },
+    { header: "Days", value: (r) => String(r.days) },
+];
+async function listQuestions(opts) {
+    const { listQuestions: queryQuestions } = await import("../../db/queries/questions.js");
+    const db = await openDb();
+    const rows = queryQuestions(db, {
+        batchId: opts.batch,
+        includeDeferred: !!opts.includeDeferred,
+    });
+    let listRows = rows.map(toListRow);
+    if (opts.redact) {
+        const { applyRedaction } = await import("../../privacy/redactor.js");
+        listRows = applyRedaction(listRows, true, QUESTION_REDACT_FIELDS);
+    }
+    emitList(listRows, LIST_COLUMNS);
+}
+const ANSWER_SPEC = z.object({
+    answer: str(),
+    also: str().optional(),
+});
+async function answerQuestion(id, opts) {
+    const parsed = parseInput(ANSWER_SPEC, opts);
+    const also = parsed.also
+        ? parsed.also.split(",").map((s) => s.trim()).filter(Boolean)
+        : [];
+    const ids = [id, ...also];
+    const { closeQuestion } = await import("../../db/queries/questions.js");
+    const db = await openDb();
+    const results = [];
+    for (const qid of ids) {
+        const closed = closeQuestion(db, qid, parsed.answer);
+        if (!closed)
+            fail("NOT_FOUND", `question "${qid}" not found`);
+        results.push({ id: qid, kind: closed.kind, answer: closed.answer, rule_key: closed.rule_key });
+    }
+    emitList(results, ANSWERED_COLUMNS);
+}
+const DEFER_SPEC = z.object({
+    days: int().default(7),
+});
+async function deferQuestion(id, opts) {
+    const parsed = parseInput(DEFER_SPEC, opts);
+    const { deferQuestion: deferQuestionRow } = await import("../../db/queries/questions.js");
+    const db = await openDb();
+    const ok = deferQuestionRow(db, id, parsed.days);
+    if (!ok)
+        fail("NOT_FOUND", `question "${id}" not found`);
+    emitList([{ id, days: parsed.days }], DEFER_COLUMNS);
+}
+export function registerQuestions(program) {
+    const questions = program
+        .command("questions")
+        .description("List, answer, and defer open questions")
+        .addHelpText("after", [
+        "",
+        "Behavior: the harness opens a question when a row is ambiguous; you list them, then answer or defer.",
+        "Typical flow: list --json, resolve each by kind, then answer (--also <id,id> closes siblings) or defer.",
+        "By kind: similar_accounts -> accounts merge; uncategorized -> transactions recategorize, then merchants set-default; unknown_merchant -> merchants upsert; currency_mismatch -> re-post as linked legs through equity:conversion:<ccy>.",
+        "Example: oled questions list --json",
+    ].join("\n"));
+    questions
+        .command("list")
+        .description("List questions")
+        .option("--batch <id>", "filter by batch id")
+        .option("--include-deferred", "include deferred questions")
+        .option("--no-redact", "skip PII redaction (on by default)")
+        .action(runAction(listQuestions));
+    questions
+        .command("answer <id>")
+        .description("Answer a question")
+        .option("--answer <text>", "the answer text")
+        .option("--also <ids>", "additional question ids to answer")
+        .action(runAction(answerQuestion));
+    questions
+        .command("defer <id>")
+        .description("Defer a question")
+        .option("--days <n>", "number of days to defer")
+        .action(runAction(deferQuestion));
+}

package/dist/cli/commands/report.js

@@ -0,0 +1,50 @@
+import { printKeyValues } from "../format.js";
+import { openDb } from "../db.js";
+import { currentMode, emit, fail, runAction } from "../output.js";
+import { ISO_DATE_RE } from "../../lib/date.js";
+async function showReport(opts) {
+    if (!opts.from || !opts.to)
+        fail("USAGE", "--from and --to are required");
+    if (!ISO_DATE_RE.test(opts.from)) {
+        fail("USAGE", `--from must be an ISO date (YYYY-MM-DD), got "${opts.from}"`);
+    }
+    if (!ISO_DATE_RE.test(opts.to)) {
+        fail("USAGE", `--to must be an ISO date (YYYY-MM-DD), got "${opts.to}"`);
+    }
+    const { getPeriodTotals } = await import("../../accounts/balances.js");
+    const db = await openDb();
+    const totals = getPeriodTotals(db, opts.from, opts.to);
+    const result = {
+        from: opts.from,
+        to: opts.to,
+        income: totals.income,
+        expenses: totals.expenses,
+        net: totals.income - totals.expenses,
+    };
+    const mode = currentMode();
+    if (mode.json) {
+        emit(result);
+        return;
+    }
+    printKeyValues(mode, [
+        ["from", result.from],
+        ["to", result.to],
+        ["income", result.income],
+        ["expenses", result.expenses],
+        ["net", result.net],
+    ], { bold: mode.color });
+}
+export function registerReport(program) {
+    program
+        .command("report")
+        .description("Income, expenses, and net")
+        .option("--from <date>", "start date")
+        .option("--to <date>", "end date")
+        .addHelpText("after", [
+        "",
+        "Behavior: sums income, expenses, and net over a date range. For net worth use oled status.",
+        "Typical flow: both dates are required and ISO (YYYY-MM-DD).",
+        "Example: oled report --from 2025-01-01 --to 2025-03-31 --json",
+    ].join("\n"))
+        .action(runAction(showReport));
+}