@morroc/open-ledger 0.14.1

package/dist/cli/commands/setup.js

@@ -0,0 +1,61 @@
+import { currentMode, emit, fail, runAction } from "../output.js";
+import { installSkill, skillMd, SkillPackVersionError, } from "../../setup/install.js";
+import { SKILL_HOSTS, findHost, DEFAULT_HOST } from "../../setup/hosts.js";
+function hostIds() {
+    return SKILL_HOSTS.map((h) => h.id).join(", ");
+}
+async function setupSkill(opts) {
+    // --print dumps SKILL.md as raw markdown (not NDJSON) even when --json is set.
+    if (opts.print) {
+        const md = skillMd();
+        process.stdout.write(md);
+        if (!md.endsWith("\n"))
+            process.stdout.write("\n");
+        return;
+    }
+    const host = opts.host ?? DEFAULT_HOST;
+    if (!findHost(host)) {
+        fail("USAGE", `unknown --host ${host}`, { hint: `known hosts: ${hostIds()}` });
+    }
+    const installOpts = {
+        host,
+        global: opts.global,
+        dir: opts.dir,
+        force: opts.force,
+    };
+    let target;
+    try {
+        target = installSkill(installOpts);
+    }
+    catch (err) {
+        if (err instanceof SkillPackVersionError) {
+            fail("INVALID", err.message, {
+                hint: "re-run with --force to overwrite the installed skill pack",
+                details: {
+                    installed_version: err.installedVersion,
+                    cli_version: err.cliVersion,
+                    path: err.path,
+                },
+            });
+        }
+        throw err;
+    }
+    const mode = currentMode();
+    if (mode.json) {
+        emit({ installed: [target] });
+    }
+    else {
+        process.stdout.write(`${target.kind}\t${target.path}\t${target.version}\n`);
+    }
+}
+export function registerSetup(program) {
+    program
+        .command("setup")
+        .description("Install the skill for an agent CLI")
+        .option("--host <id>", `target agent host: ${hostIds()}`, DEFAULT_HOST)
+        .option("--global", "install under the host's home skills dir instead of the cwd")
+        .option("--dir <path>", "override the install base directory")
+        .option("--force", "overwrite an installed skill dir whose version differs")
+        .option("--print", "print SKILL.md to stdout as raw markdown and exit (ignores --json)")
+        .action(runAction(setupSkill));
+}

package/dist/cli/commands/status.js

@@ -0,0 +1,187 @@
+import chalk from "chalk";
+import { config, getConfigPath, getDataDir, keyFingerprint } from "../../config.js";
+import { existsSync } from "fs";
+import { formatAmount } from "../currency.js";
+import { banner, visibleLength, ANSI_RE, formatInt } from "../format.js";
+import { currentMode, emit, runAction } from "../output.js";
+import { tryExecute } from "../../lib/result.js";
+import { openDb } from "../db.js";
+async function buildReport() {
+    const report = {
+        type: "status",
+        configured: existsSync(getConfigPath()) || existsSync(config.dbPath),
+        config_path: getConfigPath(),
+        data_dir: getDataDir(),
+        locale: config.displayLocale,
+        currency: config.displayCurrency,
+        user_name: config.userName,
+        db: {
+            path: config.dbPath,
+            reachable: false,
+            encrypted: !!config.dbEncryptionKey,
+            key_fingerprint: config.dbEncryptionKey ? keyFingerprint(config.dbEncryptionKey) : null,
+            error: null,
+        },
+        counts: null,
+        files: null,
+        questions: null,
+        net_worth: null,
+    };
+    // Deferred so non-db commands skip the libsql cost at startup.
+    const { getNetWorth } = await import("../../accounts/balances.js");
+    const { countAccounts } = await import("../../db/queries/accounts.js");
+    const { countTransactions } = await import("../../db/queries/transactions.js");
+    const { countFiles } = await import("../../db/queries/files.js");
+    const { countQuestions } = await import("../../db/queries/questions.js");
+    const { countMerchants } = await import("../../db/queries/merchants.js");
+    const { countNotes } = await import("../../db/queries/notes.js");
+    // Opening the db is the only reachability check; a failing count query must not read as not-ready.
+    const opened = await tryExecute(() => openDb());
+    if (!opened.ok) {
+        report.db.error = opened.error;
+        return report;
+    }
+    const db = opened.value;
+    report.db.reachable = true;
+    report.counts = {
+        accounts: countAccounts(db),
+        transactions: countTransactions(db),
+        merchants: countMerchants(db),
+        notes: countNotes(db),
+    };
+    report.files = countFiles(db);
+    const open = countQuestions(db);
+    const total = countQuestions(db, { includeDeferred: true });
+    report.questions = { open, deferred: Math.max(0, total - open) };
+    report.net_worth = getNetWorth(db);
+    return report;
+}
+// Fields that can leak the username or home dir ("error" can embed the db path).
+const STATUS_REDACT_FIELDS = ["config_path", "data_dir", "path", "error", "user_name"];
+/** Redaction is on unless `--no-redact` explicitly turned it off, so bare `oled`
+ *  (which has no such flag) masks the same fields `oled status` does. */
+export async function showStatus(opts = {}) {
+    let report = await buildReport();
+    if (opts.redact !== false) {
+        const { applyRedaction } = await import("../../privacy/redactor.js");
+        report = applyRedaction(report, true, STATUS_REDACT_FIELDS);
+    }
+    const mode = currentMode();
+    if (mode.json) {
+        emit(report);
+        return;
+    }
+    if (mode.tty) {
+        renderTty(report, mode.color);
+        return;
+    }
+    renderPlain(report);
+}
+function renderPlain(r) {
+    const lines = [
+        ["configured", r.configured],
+        ["config_path", r.config_path],
+        ["data_dir", r.data_dir],
+        ["locale", r.locale],
+        ["currency", r.currency],
+        ["user_name", r.user_name],
+        ["db_path", r.db.path],
+        ["db_reachable", r.db.reachable],
+        ["db_encrypted", r.db.encrypted],
+        ["db_key_fingerprint", r.db.key_fingerprint ?? "not set"],
+    ];
+    if (r.db.error)
+        lines.push(["db_error", r.db.error]);
+    if (r.counts) {
+        lines.push(["accounts", r.counts.accounts], ["transactions", r.counts.transactions], ["merchants", r.counts.merchants], ["notes", r.counts.notes]);
+    }
+    if (r.files) {
+        lines.push(["files_ingested", r.files.ingested], ["files_pending", r.files.pending], ["files_failed", r.files.failed]);
+    }
+    if (r.questions) {
+        lines.push(["questions_open", r.questions.open], ["questions_deferred", r.questions.deferred]);
+    }
+    if (r.net_worth) {
+        lines.push(["net_worth", r.net_worth.net_worth], ["assets", r.net_worth.assets], ["liabilities", r.net_worth.liabilities]);
+    }
+    process.stdout.write(lines.map(([k, v]) => `${k}\t${v}`).join("\n") + "\n");
+}
+const LABEL_WIDTH = 18;
+function renderTty(r, color) {
+    const dim = (s) => (color ? chalk.dim(s) : s);
+    const bold = (s) => (color ? chalk.bold.yellow(s) : s);
+    const section = (title, rows) => {
+        process.stdout.write(bold(title) + "\n");
+        const valueWidth = Math.max(0, ...rows.map(([, v]) => visibleLength(v)));
+        for (const [label, value] of rows) {
+            const pad = " ".repeat(Math.max(0, valueWidth - visibleLength(value)));
+            process.stdout.write(`  ${label.padEnd(LABEL_WIDTH)}${pad}${value}\n`);
+        }
+        process.stdout.write("\n");
+    };
+    process.stdout.write("\n" + (color ? banner() : stripBanner()) + "\n\n");
+    section("System", [
+        ["Configured", r.configured ? "yes" : dim("no")],
+        ["User", dim(r.user_name)],
+        ["Locale", dim(r.locale)],
+        ["Currency", dim(r.currency)],
+        ["Data dir", dim(r.data_dir)],
+        [
+            "Database",
+            r.db.reachable
+                ? `ready${r.db.encrypted ? dim(" (encrypted)") : ""}`
+                : dim(r.db.error ? `not ready — ${r.db.error}` : "not ready"),
+        ],
+        ["Key", r.db.key_fingerprint ? dim(r.db.key_fingerprint) : dim("not set")],
+    ]);
+    // status always exits 0, so an unreachable db needs a pointer to the surface
+    // that diagnoses it.
+    if (!r.db.reachable)
+        process.stdout.write(dim("  run `oled doctor` for details") + "\n\n");
+    if (r.counts) {
+        section("Ledger", [
+            ["Accounts", formatInt(r.counts.accounts)],
+            ["Transactions", formatInt(r.counts.transactions)],
+            ["Merchants", formatInt(r.counts.merchants)],
+            ["Notes", formatInt(r.counts.notes)],
+        ]);
+    }
+    if (r.files || r.questions) {
+        const rows = [];
+        if (r.files) {
+            const extras = [];
+            if (r.files.pending > 0)
+                extras.push(`${r.files.pending} pending`);
+            if (r.files.failed > 0)
+                extras.push(`${r.files.failed} failed`);
+            rows.push([
+                "Files",
+                `${formatInt(r.files.ingested)}${extras.length ? "  " + dim(`(${extras.join(", ")})`) : ""}`,
+            ]);
+        }
+        if (r.questions) {
+            rows.push([
+                "Questions",
+                `${formatInt(r.questions.open)} open${r.questions.deferred ? "  " + dim(`(${r.questions.deferred} deferred)`) : ""}`,
+            ]);
+        }
+        section("Pipeline", rows);
+    }
+    if (r.net_worth) {
+        section("Financial", [
+            ["Net worth", formatAmount(r.net_worth.net_worth)],
+            ["Assets", dim(formatAmount(r.net_worth.assets))],
+            ["Liabilities", dim(formatAmount(r.net_worth.liabilities))],
+        ]);
+    }
+}
+function stripBanner() {
+    return banner().replace(ANSI_RE, "");
+}
+export function registerStatus(program) {
+    program
+        .command("status")
+        .description("Status: config, database, ledger counts, net worth")
+        .option("--no-redact", "skip PII redaction (on by default)")
+        .action(runAction(showStatus));
+}

package/dist/cli/commands/transactions.js

@@ -0,0 +1,420 @@
+import { currentMode, emit, emitList, emitObject, emitSummary, fail, mapNotFoundError, readStdinToEnd, requireYes, runAction, } from "../output.js";
+import { openDb } from "../db.js";
+import { insertTransaction, deleteTransaction as deleteTransactionRow, updateTransactionMeta, bulkRecategorize, listTransactions as queryTransactions, countTransactions, clampListLimit, findTransactionById, voidTransactionAsMirror, } from "../../db/queries/transactions.js";
+import { findDuplicateTransactions, } from "../../db/queries/transactions-dedup.js";
+import { findAccountById } from "../../db/queries/accounts.js";
+import { commitTransaction, defaultTransactionCommitHooks, CURRENCY_MISMATCH_HINT, } from "../../ingest/commit.js";
+import { autoMergeStrictDuplicateTransactions } from "../../ingest/dedup.js";
+import { fromMinorUnits, toMinorUnits } from "../../lib/money.js";
+import { getDisplayCurrency } from "../currency.js";
+import { newBatchId } from "../../lib/ids.js";
+import { applyRedaction } from "../../privacy/redactor.js";
+import { todayIso } from "../../lib/date.js";
+import * as z from "zod";
+import { parseInput, str, num, json } from "../../lib/validate.js";
+// Amounts are minor units in the DB; this module converts to/from decimals at the CLI boundary.
+// Free-text fields on a transaction that may carry PII. Ids, amount, currency, and
+// dates are structured data the agent needs verbatim and are left intact.
+const TRANSACTION_REDACT_FIELDS = [
+    "description",
+    "raw_descriptor",
+    "merchant_name",
+    "debit_account_name",
+    "credit_account_name",
+];
+function presentTransaction(row) {
+    return { ...row, amount: fromMinorUnits(row.amount, row.currency) };
+}
+const LIST_COLUMNS = [
+    { header: "ID", value: (t) => t.id },
+    { header: "Date", value: (t) => t.date },
+    { header: "Description", value: (t) => t.description },
+    { header: "Debit", value: (t) => t.debit_account_name ?? t.debit_account_id },
+    { header: "Credit", value: (t) => t.credit_account_name ?? t.credit_account_id },
+    { header: "Amount", value: (t) => t.amount.toFixed(2), align: "right" },
+    { header: "Currency", value: (t) => t.currency },
+];
+const LIST_TRANSACTIONS_SPEC = z.object({
+    account: str().optional(),
+    from: str().optional(),
+    to: str().optional(),
+    query: str().optional(),
+    amount: num().optional(),
+    currency: str().optional(),
+    limit: num().optional(),
+});
+async function listTransactions(opts) {
+    const db = await openDb();
+    const parsed = parseInput(LIST_TRANSACTIONS_SPEC, opts);
+    const listOpts = {};
+    if (parsed.account)
+        listOpts.account = parsed.account;
+    if (parsed.from)
+        listOpts.from = parsed.from;
+    if (parsed.to)
+        listOpts.to = parsed.to;
+    if (parsed.query)
+        listOpts.query = parsed.query;
+    // Amount crosses the decimal -> minor-unit boundary here; currency defaults
+    // to the configured display currency when the caller doesn't pin one.
+    if (parsed.amount !== undefined) {
+        listOpts.amount = toMinorUnits(parsed.amount, parsed.currency ?? getDisplayCurrency());
+    }
+    if (parsed.limit !== undefined)
+        listOpts.limit = parsed.limit;
+    const total = countTransactions(db, listOpts);
+    const limit = clampListLimit(listOpts.limit);
+    if (opts.group) {
+        const clusters = queryTransactions(db, { ...listOpts, group: true });
+        emitClusters(clusters, !!opts.redact);
+        const returned = clusters.reduce((n, c) => n + c.transactions.length, 0);
+        emitSummary({ total, returned, has_more: total > returned, limit });
+        return;
+    }
+    const rows = applyRedaction(queryTransactions(db, listOpts).map(presentTransaction), !!opts.redact, TRANSACTION_REDACT_FIELDS);
+    emitList(rows, LIST_COLUMNS);
+    emitSummary({ total, returned: rows.length, has_more: total > rows.length, limit });
+}
+function emitClusters(clusters, redact) {
+    const view = clusters.map((c) => ({
+        group_id: c.group_id,
+        transactions: applyRedaction(c.transactions.map(presentTransaction), redact, TRANSACTION_REDACT_FIELDS),
+    }));
+    const mode = currentMode();
+    if (mode.json) {
+        for (const c of view)
+            emit(c);
+        return;
+    }
+    for (const c of view) {
+        process.stdout.write(`${c.group_id ?? "(ungrouped)"}\n`);
+        for (const t of c.transactions) {
+            process.stdout.write(`  ${t.id}  ${t.date}  ${t.description}  ${t.debit_account_name ?? t.debit_account_id} -> ${t.credit_account_name ?? t.credit_account_id}  ${t.amount.toFixed(2)} ${t.currency}\n`);
+        }
+    }
+}
+async function showTransaction(id, opts) {
+    const db = await openDb();
+    const detail = findTransactionById(db, id);
+    if (!detail)
+        fail("NOT_FOUND", `transaction "${id}" not found`);
+    const view = presentTransaction(detail);
+    if (detail.group)
+        view.group = detail.group.map(presentTransaction);
+    emitObject(applyRedaction(view, !!opts.redact, TRANSACTION_REDACT_FIELDS));
+}
+const DUPLICATE_COLUMNS = [
+    { header: "Group", value: (r) => String(r.group), align: "right" },
+    { header: "ID", value: (r) => r.id },
+    { header: "Date", value: (r) => r.date },
+    { header: "Amount", value: (r) => r.amount.toFixed(2), align: "right" },
+    { header: "Currency", value: (r) => r.currency },
+    { header: "Description", value: (r) => r.description },
+    {
+        header: "Accounts",
+        value: (r) => `${r.debit_account_name ?? r.debit_account_id} -> ${r.credit_account_name ?? r.credit_account_id}`,
+    },
+    { header: "Source File ID", value: (r) => r.source_file_id ?? "" },
+    { header: "Merchant ID", value: (r) => r.merchant_id ?? "" },
+];
+async function dedupeTransactions(opts) {
+    const db = await openDb();
+    let autoMerged;
+    if (opts.autoMerge) {
+        autoMerged = autoMergeStrictDuplicateTransactions(db).merged;
+    }
+    const groups = findDuplicateTransactions(db);
+    const rows = applyRedaction(groups.flatMap((group, i) => group.map((t) => ({ ...t, amount: fromMinorUnits(t.amount, t.currency), group: i }))), !!opts.redact, TRANSACTION_REDACT_FIELDS);
+    emitList(rows, DUPLICATE_COLUMNS);
+    emitSummary({
+        groups: groups.length,
+        ...(autoMerged !== undefined ? { auto_merged: autoMerged } : {}),
+    });
+}
+const MERGE_TRANSACTIONS_SPEC = z.object({
+    from: str(),
+    to: str(),
+});
+async function mergeTransactions(opts) {
+    const parsed = parseInput(MERGE_TRANSACTIONS_SPEC, opts);
+    requireYes(opts, "merging transactions");
+    const db = await openDb();
+    let result;
+    try {
+        result = voidTransactionAsMirror(db, parsed.from, parsed.to);
+    }
+    catch (err) {
+        mapNotFoundError(err);
+    }
+    if (result.alreadyVoid) {
+        emitObject({ from: parsed.from, to: parsed.to, voided: false, already_void: true });
+        return;
+    }
+    emitObject({ from: parsed.from, to: parsed.to, voided: true });
+}
+const ADD_TRANSACTION_FLAGS_SPEC = z.object({
+    debit_account_id: str(),
+    credit_account_id: str(),
+    amount: num(),
+    date: str().optional(),
+    description: str().optional(),
+});
+const ADD_TRANSACTION_FLAGS_OPTS = {
+    labels: { debit_account_id: "--debit-account", credit_account_id: "--credit-account" },
+    aliases: { debit_account_id: ["debitAccount"], credit_account_id: ["creditAccount"] },
+};
+// Deliberately loose (debit/credit default to "", amount passes through
+// unchecked) — addTransaction's strict/resolve checks own exit codes and messages.
+const ADD_TRANSACTION_STDIN_SPEC = z.object({
+    date: str().default(""),
+    description: str().optional(),
+    debit_account_id: str().default(""),
+    credit_account_id: str().default(""),
+    currency: str().nullable().default(null),
+    merchant: json().nullable().default(null),
+    merchant_id: str().nullable().default(null),
+    raw_descriptor: str().nullable().default(null),
+    source_page: num().nullable().default(null),
+    code: str().nullable().default(null),
+});
+const ADD_TRANSACTION_STDIN_ALIASES = {
+    debit_account_id: ["debit_account"],
+    credit_account_id: ["credit_account"],
+};
+// Decimal amount, no account validation — that's the caller's job.
+async function buildRawTransaction(opts) {
+    const anyFlag = opts.debitAccount !== undefined || opts.creditAccount !== undefined || opts.amount !== undefined;
+    if (anyFlag) {
+        const parsed = parseInput(ADD_TRANSACTION_FLAGS_SPEC, opts, ADD_TRANSACTION_FLAGS_OPTS);
+        const raw = {
+            date: parsed.date ?? todayIso(),
+            description: parsed.description ?? opts.merchantName ?? "Manual entry",
+            debit_account_id: parsed.debit_account_id,
+            credit_account_id: parsed.credit_account_id,
+            amount: parsed.amount,
+            currency: null,
+        };
+        if (opts.merchantName)
+            raw.merchant = { canonical_name: opts.merchantName };
+        return raw;
+    }
+    const stdin = await readStdinToEnd();
+    if (!stdin.trim()) {
+        fail("USAGE", "provide --debit-account/--credit-account/--amount, or pipe a transaction JSON object on stdin");
+    }
+    let decoded;
+    try {
+        decoded = JSON.parse(stdin);
+    }
+    catch (err) {
+        fail("USAGE", `invalid JSON on stdin: ${err.message}`);
+    }
+    if (typeof decoded !== "object" || decoded === null || Array.isArray(decoded)) {
+        fail("USAGE", "stdin must contain a single JSON transaction object (not an array)");
+    }
+    const record = decoded;
+    const parsed = parseInput(ADD_TRANSACTION_STDIN_SPEC, record, {
+        aliases: ADD_TRANSACTION_STDIN_ALIASES,
+    });
+    return {
+        ...parsed,
+        description: parsed.description ?? parsed.merchant?.canonical_name ?? "Manual entry",
+        // Un-coerced by design: record.amount, not parsed.amount — the validators below own the number check.
+        amount: record.amount,
+    };
+}
+function addViaResolve(db, raw) {
+    const batchId = newBatchId();
+    const ctx = {
+        batchId,
+        fileId: null,
+        fileHash: null,
+    };
+    const outcome = commitTransaction(db, ctx, raw, defaultTransactionCommitHooks(db, ctx));
+    if (!outcome.ok) {
+        if (outcome.reason === "currency_mismatch") {
+            fail("INVALID", outcome.message, { hint: CURRENCY_MISMATCH_HINT });
+        }
+        fail("INVALID", outcome.message);
+    }
+    emitObject({
+        transaction_id: outcome.transactionId,
+        duplicate: outcome.duplicate,
+        raised_questions: outcome.raisedQuestions,
+        currency_overridden: outcome.currencyOverridden,
+    });
+}
+function addStrict(db, raw) {
+    if (!raw.debit_account_id || !raw.credit_account_id) {
+        fail("USAGE", "debit_account_id and credit_account_id are required");
+    }
+    if (typeof raw.amount !== "number" || !Number.isFinite(raw.amount)) {
+        fail("USAGE", "amount must be a number");
+    }
+    const accountHint = "create it with `oled accounts create`, or find a close match with `oled accounts match --query <name>`, or re-run with --resolve";
+    const debit = findAccountById(db, raw.debit_account_id);
+    if (!debit)
+        fail("NOT_FOUND", `account "${raw.debit_account_id}" not found`, { hint: accountHint });
+    const credit = findAccountById(db, raw.credit_account_id);
+    if (!credit)
+        fail("NOT_FOUND", `account "${raw.credit_account_id}" not found`, { hint: accountHint });
+    /**
+     * Ledger-design §5 currency rule, applied inline: this strict path requires
+     * both accounts to pre-exist and raises no questions, so it can't delegate to
+     * commitTransaction's currency_mismatch path — only CURRENCY_MISMATCH_HINT is shared.
+     */
+    const currency = debit.currency || getDisplayCurrency();
+    const creditCurrency = credit.currency || getDisplayCurrency();
+    if (creditCurrency !== currency) {
+        fail("INVALID", `debit ${debit.id} is ${currency}, credit ${credit.id} is ${creditCurrency}; a single transaction can't cross currencies`, { hint: CURRENCY_MISMATCH_HINT });
+    }
+    let result;
+    try {
+        result = insertTransaction(db, {
+            date: raw.date,
+            description: raw.description,
+            debit_account_id: raw.debit_account_id,
+            credit_account_id: raw.credit_account_id,
+            amount: toMinorUnits(raw.amount, currency),
+            currency,
+            merchant: raw.merchant ?? null,
+            merchant_id: raw.merchant_id ?? null,
+            raw_descriptor: raw.raw_descriptor ?? null,
+            source_page: raw.source_page ?? null,
+            code: raw.code ?? null,
+        });
+    }
+    catch (err) {
+        fail("INVALID", err.message);
+    }
+    emitObject({ transaction_id: result.id, duplicate: result.duplicate });
+}
+async function addTransaction(opts) {
+    const db = await openDb();
+    const raw = await buildRawTransaction(opts);
+    if (opts.resolve)
+        return addViaResolve(db, raw);
+    return addStrict(db, raw);
+}
+const UPDATE_TRANSACTION_SPEC = z.object({
+    date: str().optional(),
+    description: str().optional(),
+    merchant_id: str().optional(),
+});
+const UPDATE_TRANSACTION_ALIASES = { merchant_id: ["merchant"] };
+async function updateTransaction(id, opts) {
+    const fields = parseInput(UPDATE_TRANSACTION_SPEC, opts, {
+        aliases: UPDATE_TRANSACTION_ALIASES,
+        atLeastOne: "at least one of --date, --description, --merchant is required",
+    });
+    const db = await openDb();
+    const changes = updateTransactionMeta(db, id, fields);
+    if (changes === 0)
+        fail("NOT_FOUND", `transaction "${id}" not found`);
+    emitObject({ transaction_id: id, updated: true });
+}
+async function deleteTransaction(id, opts) {
+    requireYes(opts, "deleting this transaction");
+    const db = await openDb();
+    if (!deleteTransactionRow(db, id))
+        fail("NOT_FOUND", `transaction "${id}" not found`);
+    emitObject({ transaction_id: id, deleted: true });
+}
+const RECATEGORIZE_SPEC = z.object({
+    set_account: str(),
+    filter_account: str(),
+});
+// The `--filter-account` clarification is folded into the label so a missing
+// flag still explains what that account controls.
+const RECATEGORIZE_LABELS = {
+    filter_account: "--filter-account (recategorize moves that account's transactions)",
+};
+async function recategorizeTransactions(opts) {
+    const parsed = parseInput(RECATEGORIZE_SPEC, opts, { labels: RECATEGORIZE_LABELS });
+    const db = await openDb();
+    const filter = { accountId: parsed.filter_account };
+    let result;
+    try {
+        result = bulkRecategorize(db, filter, { accountId: parsed.set_account });
+    }
+    catch (err) {
+        fail("INVALID", err.message);
+    }
+    emitObject({
+        affected: result.affected,
+        skipped_self_transaction: result.skipped_self_transaction,
+        sample_transaction_ids: result.sample_transaction_ids,
+    });
+}
+export function registerTransactions(program) {
+    const transactions = program
+        .command("transactions")
+        .description("Transactions: list / show / add / update / delete / recategorize / dedupe / merge")
+        .addHelpText("after", [
+        "",
+        "Behavior: reads the ledger (list, show) and edits it (add, update, delete, recategorize, dedupe, merge).",
+        "Typical flow: list to find a tx:id, then show, recategorize, or delete it. Statement rows go through ingest commit, not add.",
+        "Direction, not sign: debit the account that grows, amount always positive. Card purchase: debit expense:<cat>, credit liability:credit_card:<x>. Bank spend: debit expense:<cat>, credit asset:bank:<x>. Salary: debit asset:bank:<x>, credit income:salary. A refund reverses the purchase's accounts; a card payment debits the liability and credits the bank; opening balances post against equity:opening-balance.",
+        "Example: oled transactions list --account expense:food --json",
+    ].join("\n"));
+    transactions
+        .command("list")
+        .description("List transactions with optional filters")
+        .option("--account <id>", "filter by account id (matches either side)")
+        .option("--from <date>", "filter from date")
+        .option("--to <date>", "filter to date")
+        .option("--query <text>", "filter by search text")
+        .option("--amount <decimal>", "filter by exact amount (decimal)")
+        .option("--currency <code>", "currency for --amount (defaults to the configured display currency)")
+        .option("--limit <n>", "max rows (default 50, max 500)")
+        .option("--group", "fold linked transactions into their group clusters")
+        .option("--no-redact", "skip PII redaction (on by default)")
+        .action(runAction(listTransactions));
+    transactions
+        .command("show <id>")
+        .description("Show a transaction's details (with its linked group when present)")
+        .option("--no-redact", "skip PII redaction (on by default)")
+        .action(runAction(showTransaction));
+    transactions
+        .command("add")
+        .description("Add a manual transaction; statement rows belong in `ingest commit`")
+        .option("--resolve", "fuzzy-resolve account/merchant hints and raise questions instead of failing")
+        .option("--debit-account <id>", "debit account id")
+        .option("--credit-account <id>", "credit account id")
+        .option("--amount <n>", "transaction amount (decimal)")
+        .option("--date <date>", "transaction date (defaults to today)")
+        .option("--description <text>", "transaction description")
+        .option("--merchant-name <name>", "merchant name to upsert and link")
+        .action(runAction(addTransaction));
+    transactions
+        .command("update <id>")
+        .description("Update a transaction's metadata")
+        .option("--date <date>", "transaction date")
+        .option("--description <text>", "transaction description")
+        .option("--merchant <id>", "merchant id to set")
+        .action(runAction(updateTransaction));
+    transactions
+        .command("delete <id>")
+        .description("Delete a transaction")
+        .option("--yes", "skip confirmation")
+        .action(runAction(deleteTransaction));
+    transactions
+        .command("recategorize")
+        .description("Bulk re-point one account's transactions onto another")
+        .option("--set-account <id>", "account id to move matching transactions to")
+        .option("--filter-account <id>", "account whose transactions are moved (required)")
+        .action(runAction(recategorizeTransactions));
+    transactions
+        .command("dedupe")
+        .description("Find likely duplicate transactions (optionally auto-merge them)")
+        .option("--auto-merge", "automatically merge detected duplicates")
+        .option("--no-redact", "skip PII redaction (on by default)")
+        .action(runAction(dedupeTransactions));
+    transactions
+        .command("merge")
+        .description("Merge a mirror transaction into its surviving twin (voids --from)")
+        .option("--from <id>", "mirror transaction id to void")
+        .option("--to <id>", "surviving transaction id")
+        .option("--yes", "skip confirmation")
+        .action(runAction(mergeTransactions));
+}