actual-jev 0.1.0

package/dist/setup.js

@@ -0,0 +1,84 @@
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { saveConfig, validateConfig } from './config.js';
+async function secretSetting(port, name, previous, clear = false) {
+    if (previous !== undefined) {
+        const action = await port.select(name, [
+            { name: 'Keep saved value', value: 'keep' },
+            { name: 'Replace', value: 'replace' },
+            ...(clear ? [{ name: 'Clear', value: 'clear' }] : []),
+        ]);
+        if (action === 'keep')
+            return previous;
+        if (action === 'clear')
+            return undefined;
+    }
+    return port.secret(name);
+}
+export async function runSetup(saved, configFile, port) {
+    port.print(`Credentials will be saved locally in ${configFile}.`);
+    const serverURL = (await port.input('Actual server URL', saved.serverURL)).trim();
+    validateConfig({ version: 1, serverURL });
+    const password = (await secretSetting(port, 'Actual server password', saved.password));
+    const candidate = { ...saved, version: 1, serverURL, password };
+    const dataDir = await mkdtemp(join(tmpdir(), 'actual-jev-setup-'));
+    let initialized = false;
+    let budgetName;
+    try {
+        try {
+            await port.actual.init({ serverURL, password, dataDir, verbose: false });
+            initialized = true;
+        }
+        catch {
+            throw new Error('Could not connect to Actual. Check the server URL and password, then run actual-jev setup again.');
+        }
+        let budgets;
+        try {
+            budgets = await port.actual.getBudgets();
+        }
+        catch {
+            throw new Error('Could not list budgets. Check the Actual connection and run actual-jev setup again.');
+        }
+        // Actual downloads by groupId (the sync ID); cloudFileId identifies the server file.
+        const unique = [
+            ...new Map(budgets
+                .filter((budget) => Boolean(budget.cloudFileId && budget.groupId))
+                .map((budget) => [budget.groupId, budget])).values(),
+        ];
+        if (!unique.length)
+            throw new Error('No synced budgets found. Upload a budget to your Actual server, then run actual-jev setup again.');
+        const syncId = await port.select('Choose your budget', unique.map((budget) => ({
+            name: unique.filter((other) => other.name === budget.name).length > 1
+                ? `${budget.name} (${budget.groupId})`
+                : budget.name,
+            value: budget.groupId,
+        })), saved.serverURL === serverURL ? saved.syncId : undefined);
+        const budget = unique.find((budget) => budget.groupId === syncId);
+        candidate.syncId = syncId;
+        budgetName = budget.name;
+        const previousEncryption = saved.serverURL === serverURL && saved.syncId === syncId ? saved.encryptionPassword : undefined;
+        candidate.encryptionPassword = budget.encryptKeyId
+            ? await secretSetting(port, 'Budget encryption password', previousEncryption, true)
+            : undefined;
+        try {
+            await port.actual.downloadBudget(syncId, { password: candidate.encryptionPassword });
+        }
+        catch {
+            throw new Error('Could not open the budget. Check its encryption password and connection, then run actual-jev setup again.');
+        }
+        candidate.apiKey = await secretSetting(port, 'TypeSafe API key', saved.apiKey);
+        validateConfig(candidate);
+    }
+    finally {
+        try {
+            if (initialized)
+                await port.actual.shutdown();
+        }
+        finally {
+            await rm(dataDir, { recursive: true, force: true });
+        }
+    }
+    await saveConfig(configFile, candidate);
+    port.print(`Saved configuration to ${configFile}.\nBudget: ${budgetName}\nTry actual-jev --dry-run to preview suggestions and verify your TypeSafe API key.`);
+}

package/dist/setup.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/setup.test.js

@@ -0,0 +1,138 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { readConfig, saveConfig } from './config.js';
+import { runSetup } from './setup.js';
+function fixture(encrypted = false) {
+    const calls = [];
+    const port = {
+        input: () => Promise.resolve('https://actual.example'),
+        secret: (message) => {
+            calls.push(message);
+            return Promise.resolve('fixture-secret');
+        },
+        select: (message, choices) => {
+            calls.push(message);
+            return Promise.resolve(choices[0].value);
+        },
+        print: (message) => calls.push(message),
+        actual: {
+            init: () => {
+                calls.push('init');
+                return Promise.resolve();
+            },
+            getBudgets: () => Promise.resolve([
+                { name: 'Unsynced', cloudFileId: 'unsynced-file', groupId: null },
+                {
+                    name: 'Household',
+                    cloudFileId: 'cloud-file',
+                    groupId: 'budget',
+                    encryptKeyId: encrypted ? 'encryption-key' : null,
+                },
+            ]),
+            downloadBudget: (syncId, options) => {
+                assert.equal(syncId, 'budget', 'downloadBudget requires groupId, not cloudFileId');
+                calls.push(`download:${options.password ?? 'none'}`);
+                return Promise.resolve();
+            },
+            shutdown: () => {
+                calls.push('shutdown');
+                return Promise.resolve();
+            },
+        },
+    };
+    return { port, calls };
+}
+void test('setup opens and saves the sync ID rather than the cloud file ID, including encrypted budgets', async (t) => {
+    const dir = await mkdtemp(join(tmpdir(), 'jev-setup-'));
+    t.after(() => rm(dir, { recursive: true, force: true }));
+    for (const encrypted of [false, true]) {
+        const { port, calls } = fixture(encrypted);
+        const file = join(dir, `config-${encrypted}.json`);
+        await runSetup({ version: 1 }, file, port);
+        const config = await readConfig(file);
+        assert.equal(config.syncId, 'budget');
+        assert.equal(config.apiKey, 'fixture-secret');
+        assert.equal(config.encryptionPassword, encrypted ? 'fixture-secret' : undefined);
+        assert.ok(calls.includes('shutdown'));
+        assert.ok(calls.some((line) => line.includes('Budget: Household')));
+    }
+});
+void test('updates keep saved secrets and deduplicate budget choices', async (t) => {
+    const dir = await mkdtemp(join(tmpdir(), 'jev-setup-'));
+    t.after(() => rm(dir, { recursive: true, force: true }));
+    const file = join(dir, 'config.json');
+    const saved = {
+        version: 1,
+        serverURL: 'https://actual.example',
+        password: 'old-password',
+        apiKey: 'old-key',
+        syncId: 'budget',
+        encryptionPassword: 'old-encryption',
+        maxExamplesPerCategory: 2,
+    };
+    const { port } = fixture(true);
+    port.actual.getBudgets = () => Promise.resolve([
+        { name: 'Home', cloudFileId: 'cloud-file', groupId: 'budget', encryptKeyId: 'key' },
+        { name: 'Home', cloudFileId: 'cloud-file', groupId: 'budget', encryptKeyId: 'key' },
+    ]);
+    port.select = (message, choices, initial) => {
+        if (message === 'Choose your budget') {
+            assert.equal(choices.length, 1);
+            assert.equal(choices[0].value, 'budget');
+            assert.equal(initial, 'budget');
+        }
+        return Promise.resolve(choices[0].value);
+    };
+    port.secret = () => {
+        throw new Error('Should retain saved secret');
+    };
+    await runSetup(saved, file, port);
+    assert.deepEqual(await readConfig(file), saved);
+});
+void test('cancellation and connection failures preserve saved configuration', async (t) => {
+    const dir = await mkdtemp(join(tmpdir(), 'jev-setup-'));
+    t.after(() => rm(dir, { recursive: true, force: true }));
+    const file = join(dir, 'config.json');
+    const saved = { version: 1, apiKey: 'old-key' };
+    await saveConfig(file, saved);
+    for (const stage of ['init', 'list', 'empty', 'download', 'cancel']) {
+        const { port, calls } = fixture();
+        if (stage === 'init')
+            port.actual.init = () => Promise.reject(new Error('sensitive details'));
+        if (stage === 'list')
+            port.actual.getBudgets = () => Promise.reject(new Error('sensitive details'));
+        if (stage === 'empty')
+            port.actual.getBudgets = () => Promise.resolve([]);
+        if (stage === 'download')
+            port.actual.downloadBudget = () => Promise.reject(new Error('sensitive details'));
+        if (stage === 'cancel')
+            port.select = () => Promise.reject(new Error('Cancelled'));
+        await assert.rejects(runSetup(saved, file, port), (error) => error instanceof Error && !error.message.includes('sensitive details'));
+        assert.deepEqual(await readConfig(file), saved);
+        if (stage !== 'init')
+            assert.ok(calls.includes('shutdown'));
+    }
+});
+void test('setup replaces credentials and clears encryption for an unencrypted budget', async (t) => {
+    const dir = await mkdtemp(join(tmpdir(), 'jev-setup-'));
+    t.after(() => rm(dir, { recursive: true, force: true }));
+    const saved = {
+        version: 1,
+        serverURL: 'https://actual.example',
+        password: 'old',
+        apiKey: 'old',
+        syncId: 'budget',
+        encryptionPassword: 'old',
+    };
+    const { port } = fixture();
+    port.select = (_message, choices) => Promise.resolve(choices.find((choice) => choice.value === 'replace')?.value ?? choices[0].value);
+    const file = join(dir, 'config.json');
+    await runSetup(saved, file, port);
+    const config = await readConfig(file);
+    assert.equal(config.password, 'fixture-secret');
+    assert.equal(config.apiKey, 'fixture-secret');
+    assert.equal(config.encryptionPassword, undefined);
+});

package/dist/workflow.d.ts

@@ -0,0 +1,38 @@
+import type { ActualTransaction } from './actual.js';
+import type { CategoryCandidate, Classification } from './classifier.js';
+export type RunMode = 'auto' | 'interactive' | 'dry-run';
+export interface RunOptions {
+    mode: RunMode;
+    threshold: number;
+    account?: string;
+    from?: string;
+    to?: string;
+}
+export interface AccountInfo {
+    id: string;
+    name: string;
+    offbudget?: boolean;
+}
+export interface RunSummary {
+    examined: number;
+    applied: number;
+    wouldApply: number;
+    skipped: number;
+    transfersSkipped: number;
+}
+export interface WorkflowPort {
+    accounts: readonly AccountInfo[];
+    transactions: readonly ActualTransaction[];
+    transferPayeeAccountIds: ReadonlyMap<string, string>;
+    payeeNames?: ReadonlyMap<string, string>;
+    categories: readonly CategoryCandidate[];
+    classify(transaction: ActualTransaction & {
+        accountName?: string;
+    }): Promise<Classification>;
+    updateTransaction(id: string, fields: Partial<ActualTransaction>): Promise<unknown>;
+    choose?(transaction: ActualTransaction, result: Classification): Promise<string | null>;
+    print(line: string): void;
+    color?: boolean;
+}
+/** Process grouped ActualQL rows, classifying each split child once. */
+export declare function runCategorization(port: WorkflowPort, options: RunOptions): Promise<RunSummary>;

package/dist/workflow.js

@@ -0,0 +1,102 @@
+import { decision, describeSuggestion } from './output.js';
+function isSkippableTransfer(transaction, transferPayeeAccountIds, accountById, transactionById) {
+    const targetAccountId = (transaction.payee && transferPayeeAccountIds.get(transaction.payee)) ||
+        (transaction.transfer_id && transactionById.get(transaction.transfer_id)?.account);
+    if (targetAccountId && accountById.get(targetAccountId)?.offbudget)
+        return false;
+    return Boolean(transaction.transfer_id || (transaction.payee && transferPayeeAccountIds.has(transaction.payee)));
+}
+function inRange(transaction, options) {
+    return (!options.from || transaction.date >= options.from) && (!options.to || transaction.date <= options.to);
+}
+/** Process grouped ActualQL rows, classifying each split child once. */
+export async function runCategorization(port, options) {
+    const accountById = new Map(port.accounts.map((account) => [account.id, account]));
+    const selectedAccounts = options.account
+        ? port.accounts.filter((account) => account.id === options.account || account.name === options.account)
+        : port.accounts;
+    if (options.account && selectedAccounts.length !== 1) {
+        throw new Error(`Account must match exactly one ID or name: ${options.account}`);
+    }
+    const allowedAccounts = new Set(selectedAccounts.filter((account) => !account.offbudget).map((account) => account.id));
+    const transactionById = new Map(port.transactions
+        .flatMap((transaction) => [transaction, ...(transaction.subtransactions ?? [])])
+        .map((transaction) => [transaction.id, transaction]));
+    const categoryById = new Map(port.categories.map((category) => [category.id, category]));
+    const summary = { examined: 0, applied: 0, wouldApply: 0, skipped: 0, transfersSkipped: 0 };
+    const color = Boolean(port.color);
+    async function process(transaction, accountName) {
+        summary.examined++;
+        const result = await port.classify({ ...transaction, accountName });
+        const suggestion = result.categoryId ? categoryById.get(result.categoryId) : undefined;
+        if (result.categoryId && !suggestion)
+            throw new Error('Classifier returned a category outside the visible catalog');
+        const line = describeSuggestion(transaction, accountName, suggestion, result.confidence, port.payeeNames, color);
+        let selected = result.categoryId;
+        let skipped = 'Skipped';
+        const interactive = options.mode === 'interactive';
+        if (interactive) {
+            if (!port.choose)
+                throw new Error('Interactive mode requires a choice handler');
+            port.print(line);
+            selected = await port.choose(transaction, result);
+            if (selected && !categoryById.has(selected))
+                throw new Error('Selected category is outside the visible catalog');
+        }
+        else if (!selected || result.requiresReview || result.confidence < options.threshold) {
+            skipped += !selected
+                ? ' · no match'
+                : result.requiresReview
+                    ? ' · conflicting evidence'
+                    : ' · below threshold';
+            selected = null;
+        }
+        let message;
+        let applied = false;
+        if (!selected) {
+            summary.skipped++;
+            message = skipped;
+        }
+        else if (options.mode === 'dry-run') {
+            summary.wouldApply++;
+            message = 'Would apply';
+        }
+        else {
+            await port.updateTransaction(transaction.id, { category: selected });
+            summary.applied++;
+            applied = true;
+            const category = categoryById.get(selected);
+            message = interactive ? `Applied ${category.groupName} / ${category.name}` : 'Applied';
+        }
+        port.print(`${interactive ? '' : `${line}\n`}${decision(message, color, applied)}`);
+    }
+    for (const transaction of port.transactions) {
+        if (!allowedAccounts.has(transaction.account))
+            continue;
+        const accountName = accountById.get(transaction.account)?.name ?? transaction.account;
+        const children = transaction.subtransactions?.length ? transaction.subtransactions : undefined;
+        if (!children && transaction.is_child)
+            continue;
+        const parentTransfer = isSkippableTransfer(transaction, port.transferPayeeAccountIds, accountById, transactionById);
+        for (const row of children ?? [transaction]) {
+            if (row.category || !inRange(row, options))
+                continue;
+            if (parentTransfer ||
+                (children && isSkippableTransfer(row, port.transferPayeeAccountIds, accountById, transactionById))) {
+                summary.transfersSkipped++;
+                continue;
+            }
+            // Eligibility uses the original child; inherit display/classification details afterward.
+            const candidate = children
+                ? {
+                    ...row,
+                    payee: row.payee ?? transaction.payee,
+                    imported_payee: row.imported_payee ?? transaction.imported_payee,
+                    date: row.date ?? transaction.date,
+                }
+                : row;
+            await process(candidate, accountName);
+        }
+    }
+    return summary;
+}

package/dist/workflow.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/workflow.test.js

@@ -0,0 +1,284 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { runCategorization } from './workflow.js';
+const category = { id: 'groceries', name: 'Groceries', groupName: 'Food' };
+const base = { account: 'checking', date: '2026-09-01', amount: -1000 };
+function fixture(confidence = 0.95) {
+    const updates = [];
+    const lines = [];
+    const port = {
+        accounts: [{ id: 'checking', name: 'Checking' }],
+        transactions: [
+            { ...base, id: 'ordinary', payee: 'shop' },
+            { ...base, id: 'transfer', payee: 'transfer-payee', transfer_id: 'other-side' },
+            {
+                ...base,
+                id: 'split',
+                is_parent: true,
+                amount: -3000,
+                subtransactions: [
+                    { ...base, id: 'child-1', parent_id: 'split', is_child: true, amount: -1000 },
+                    { ...base, id: 'child-2', parent_id: 'split', is_child: true, amount: -2000, category: 'rent' },
+                ],
+            },
+        ],
+        transferPayeeAccountIds: new Map([['transfer-payee', 'checking']]),
+        payeeNames: new Map([['shop', 'shop']]),
+        categories: [category],
+        classify() {
+            return Promise.resolve({
+                categoryId: category.id,
+                confidence,
+                candidates: [{ ...category, probability: 0.95 }],
+                noMatchProbability: 0.05,
+            });
+        },
+        updateTransaction(id, fields) {
+            updates.push({ id, fields });
+            return Promise.resolve();
+        },
+        print(line) {
+            lines.push(line);
+        },
+    };
+    return { port, updates, lines };
+}
+void test('automatic mode updates ordinary transactions and only eligible split children', async () => {
+    const { port, updates, lines } = fixture();
+    const summary = await runCategorization(port, { mode: 'auto', threshold: 0.9 });
+    assert.equal(summary.applied, 2);
+    assert.equal(summary.transfersSkipped, 1);
+    assert.deepEqual(updates.map((update) => update.id), ['ordinary', 'child-1']);
+    assert.deepEqual(updates[0]?.fields, { category: 'groceries' });
+    assert.deepEqual(updates[1]?.fields, { category: 'groceries' });
+    assert.equal(lines.filter((line) => /Decision\s+Applied/.test(line)).length, 2);
+});
+void test('skips off-budget accounts before classifying ordinary or split transactions', async () => {
+    const { port, updates, lines } = fixture();
+    port.accounts = [...port.accounts, { id: 'tracking', name: 'Tracking', offbudget: true }];
+    port.transactions = [
+        ...port.transactions,
+        { ...base, id: 'off-budget', account: 'tracking' },
+        {
+            ...base,
+            id: 'off-budget-split',
+            account: 'tracking',
+            is_parent: true,
+            subtransactions: [{ ...base, id: 'off-budget-child', account: 'tracking', is_child: true }],
+        },
+    ];
+    const classified = [];
+    const classify = port.classify.bind(port);
+    port.classify = (transaction) => {
+        classified.push(transaction.id);
+        return classify(transaction);
+    };
+    const summary = await runCategorization(port, { mode: 'auto', threshold: 0.9 });
+    assert.equal(summary.examined, 2);
+    assert.deepEqual(classified, ['ordinary', 'child-1']);
+    assert.deepEqual(updates.map((update) => update.id), ['ordinary', 'child-1']);
+    assert.equal(lines.length, 2);
+});
+void test('categorizes on-budget transfers to off-budget accounts but skips their off-budget sides', async () => {
+    const { port, updates } = fixture();
+    port.accounts = [...port.accounts, { id: 'tracking', name: 'Tracking', offbudget: true }];
+    port.transferPayeeAccountIds = new Map([
+        ['transfer-payee', 'checking'],
+        ['tracking-payee', 'tracking'],
+    ]);
+    port.transactions = [
+        ...port.transactions,
+        { ...base, id: 'to-tracking', payee: 'tracking-payee', transfer_id: 'tracking-side' },
+        { ...base, id: 'tracking-side', account: 'tracking', transfer_id: 'to-tracking' },
+        { ...base, id: 'to-tracking-by-id', transfer_id: 'tracking-side-by-id' },
+        { ...base, id: 'tracking-side-by-id', account: 'tracking', transfer_id: 'to-tracking-by-id' },
+    ];
+    const summary = await runCategorization(port, { mode: 'auto', threshold: 0.9 });
+    assert.equal(summary.applied, 4);
+    assert.equal(summary.transfersSkipped, 1);
+    assert.deepEqual(updates.map((update) => update.id), ['ordinary', 'child-1', 'to-tracking', 'to-tracking-by-id']);
+});
+void test('dry-run simulates auto without any writes', async () => {
+    const { port, updates, lines } = fixture();
+    const summary = await runCategorization(port, { mode: 'dry-run', threshold: 0.9 });
+    assert.equal(summary.wouldApply, 2);
+    assert.deepEqual(updates, []);
+    assert.equal(lines.length, 2);
+    assert.deepEqual((lines[0] ?? '').split('\n').slice(0, 4), ['', '  -10.00', '  shop', '  2026-09-01 · Checking']);
+    assert.match(lines[0] ?? '', /Suggestion\s+Food \/ Groceries · 95% confidence/);
+    assert.match(lines[0] ?? '', /Decision\s+Would apply/);
+});
+void test('weak suggestions are skipped automatically but can be chosen interactively', async () => {
+    const { port, updates, lines } = fixture(0.4);
+    const automatic = await runCategorization(port, { mode: 'auto', threshold: 0.9 });
+    assert.equal(automatic.applied, 0);
+    assert.equal(lines.filter((line) => line.includes('Skipped · below threshold')).length, 2);
+    port.choose = (transaction) => Promise.resolve(transaction.id === 'ordinary' ? 'groceries' : null);
+    const interactive = await runCategorization(port, { mode: 'interactive', threshold: 0.9 });
+    assert.equal(interactive.applied, 1);
+    assert.ok(lines.some((line) => /Decision\s+Applied Food \/ Groceries/.test(line)));
+    assert.ok(lines.some((line) => /Decision\s+Skipped/.test(line)));
+    assert.deepEqual(updates.map((update) => update.id), ['ordinary']);
+});
+void test('conflicting evidence blocks automatic writes but remains selectable interactively', async () => {
+    const { port, updates, lines } = fixture(0.99);
+    const classify = port.classify.bind(port);
+    port.classify = async (transaction) => ({ ...(await classify(transaction)), requiresReview: true });
+    const automatic = await runCategorization(port, { mode: 'auto', threshold: 0.9 });
+    assert.equal(automatic.applied, 0);
+    assert.ok(lines.some((line) => line.includes('conflicting evidence')));
+    port.choose = () => Promise.resolve('groceries');
+    const interactive = await runCategorization(port, { mode: 'interactive', threshold: 0.9 });
+    assert.equal(interactive.applied, 2);
+    assert.equal(updates.length, 2);
+});
+void test('no-match decisions are visible without making writes', async () => {
+    const { port, updates, lines } = fixture();
+    port.classify = () => Promise.resolve({ categoryId: null, confidence: 0.8, candidates: [], noMatchProbability: 0.8 });
+    const summary = await runCategorization(port, { mode: 'auto', threshold: 0.9 });
+    assert.equal(summary.skipped, 2);
+    assert.deepEqual(updates, []);
+    assert.equal(lines.filter((line) => /Suggestion\s+no match · 80% confidence/.test(line)).length, 2);
+    assert.equal(lines.filter((line) => /Decision\s+Skipped · no match/.test(line)).length, 2);
+});
+void test('presents the merchant from a verbose card description', async () => {
+    const { port, lines } = fixture(0.53);
+    port.transactions = [
+        {
+            ...base,
+            id: 'card',
+            date: '2026-09-23',
+            amount: -660,
+            imported_payee: 'Operazione Mastercard Del 21/09/2026 Alle Ore 08:10 Con Carta Xxxxxxxxxxxx0230 Div=Eur Importo in Divisa=6.6 / Importo in Euro=6.6 Presso Pasticceria San Marone - Transazione C-Less',
+        },
+    ];
+    const summary = await runCategorization(port, { mode: 'dry-run', threshold: 0.9 });
+    assert.equal(summary.skipped, 1);
+    assert.deepEqual((lines[0] ?? '').split('\n').slice(0, 4), [
+        '',
+        '  -6.60',
+        '  Pasticceria San Marone',
+        '  2026-09-23 · Checking',
+    ]);
+    assert.doesNotMatch(lines[0] ?? '', /Xxxxxxxxxxxx0230/);
+});
+void test('wraps long unrecognized payees without dropping their text', async () => {
+    const { port, lines } = fixture();
+    const description = 'A long imported description with no merchant marker '.repeat(3).trim();
+    port.transactions = [{ ...base, id: 'long-payee', imported_payee: description }];
+    await runCategorization(port, { mode: 'dry-run', threshold: 0.9 });
+    assert.ok((lines[0] ?? '').includes('\n  A long imported description'));
+    assert.match(lines[0] ?? '', /merchant marker$/m);
+    assert.ok((lines[0] ?? '').split('\n').filter((line) => line.includes('merchant marker')).length > 1);
+});
+void test('uses emphasis only for terminal output', async () => {
+    const { port, lines } = fixture();
+    port.color = true;
+    await runCategorization(port, { mode: 'dry-run', threshold: 0.9 });
+    assert.ok((lines[0] ?? '').includes('\u001b[1;36m-10.00\u001b[0m'));
+    assert.ok((lines[0] ?? '').includes('\u001b[1m  shop\u001b[0m'));
+    assert.ok((lines[0] ?? '').includes('\u001b[36mFood / Groceries\u001b[0m'));
+});
+void test('filters split children before inheriting details and skips duplicate top-level children', async () => {
+    const { port, updates } = fixture();
+    const child = { ...base, id: 'child', is_child: true };
+    port.transactions = [
+        {
+            ...base,
+            id: 'parent',
+            payee: 'shop',
+            imported_payee: 'Imported shop',
+            subtransactions: [child, { ...child, id: 'old', date: '2026-08-31' }],
+        },
+        child,
+        { ...base, id: 'later', date: '2026-09-02' },
+    ];
+    const classified = [];
+    const classify = port.classify.bind(port);
+    port.classify = (transaction) => {
+        classified.push(transaction);
+        return classify(transaction);
+    };
+    const summary = await runCategorization(port, {
+        mode: 'auto',
+        threshold: 0.95,
+        account: 'Checking',
+        from: base.date,
+        to: base.date,
+    });
+    assert.deepEqual(summary, { examined: 1, applied: 1, wouldApply: 0, skipped: 0, transfersSkipped: 0 });
+    assert.deepEqual(classified, [
+        { ...child, payee: 'shop', imported_payee: 'Imported shop', accountName: 'Checking' },
+    ]);
+    assert.deepEqual(updates, [{ id: 'child', fields: { category: 'groceries' } }]);
+});
+void test('counts eligible split transfers once using both parent and child transfer metadata', async () => {
+    const { port, updates } = fixture();
+    port.accounts = [...port.accounts, { id: 'tracking', name: 'Tracking', offbudget: true }];
+    port.transferPayeeAccountIds = new Map([
+        ['internal', 'checking'],
+        ['external', 'tracking'],
+    ]);
+    const child = { ...base, is_child: true };
+    port.transactions = [
+        {
+            ...base,
+            id: 'internal-parent',
+            payee: 'internal',
+            subtransactions: [
+                { ...child, id: 'inherited-transfer' },
+                { ...child, id: 'categorized', category: 'rent' },
+                { ...child, id: 'old', date: '2026-08-31' },
+            ],
+        },
+        {
+            ...base,
+            id: 'external-parent',
+            payee: 'external',
+            subtransactions: [
+                { ...child, id: 'eligible' },
+                { ...child, id: 'child-transfer', payee: 'internal' },
+                { ...child, id: 'unresolved-transfer', transfer_id: 'missing' },
+            ],
+        },
+    ];
+    const summary = await runCategorization(port, { mode: 'auto', threshold: 0.9, from: base.date });
+    assert.deepEqual(summary, { examined: 1, applied: 1, wouldApply: 0, skipped: 0, transfersSkipped: 3 });
+    assert.deepEqual(updates, [{ id: 'eligible', fields: { category: 'groceries' } }]);
+});
+void test('requires a unique account match and excludes explicitly selected off-budget accounts', async () => {
+    const { port } = fixture();
+    await assert.rejects(runCategorization(port, { mode: 'auto', threshold: 0.9, account: 'missing' }), /exactly one/);
+    port.accounts = [...port.accounts, { id: 'tracking', name: 'Checking', offbudget: true }];
+    await assert.rejects(runCategorization(port, { mode: 'auto', threshold: 0.9, account: 'Checking' }), /exactly one/);
+    const summary = await runCategorization(port, { mode: 'auto', threshold: 0.9, account: 'tracking' });
+    assert.equal(summary.examined, 0);
+});
+void test('rejects invalid suggestions and interactive choices before writing', async () => {
+    const { port, updates } = fixture();
+    const classify = port.classify.bind(port);
+    port.classify = async (transaction) => ({ ...(await classify(transaction)), categoryId: 'unknown' });
+    await assert.rejects(runCategorization(port, { mode: 'auto', threshold: 0.9 }), /Classifier returned/);
+    port.classify = classify;
+    await assert.rejects(runCategorization(port, { mode: 'interactive', threshold: 0.9 }), /choice handler/);
+    port.choose = () => Promise.resolve('unknown');
+    await assert.rejects(runCategorization(port, { mode: 'interactive', threshold: 0.9 }), /Selected category/);
+    assert.deepEqual(updates, []);
+});
+void test('prints the suggestion before prompting and stops on a failed write', async () => {
+    const { port, lines } = fixture();
+    const events = [];
+    port.choose = () => {
+        assert.match(lines.at(-1) ?? '', /Suggestion/);
+        events.push('choose');
+        return Promise.resolve('groceries');
+    };
+    port.updateTransaction = () => {
+        events.push('write');
+        return Promise.reject(new Error('write failed'));
+    };
+    await assert.rejects(runCategorization(port, { mode: 'interactive', threshold: 0.9 }), /write failed/);
+    assert.deepEqual(events, ['choose', 'write']);
+    assert.equal(lines.length, 1);
+    assert.doesNotMatch(lines[0] ?? '', /Decision/);
+});