actual-jev 0.1.0

package/dist/cli.js

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+import * as actual from '@actual-app/api';
+import { TypeSafeClient } from '@typesafe-ai/sdk';
+import search from '@inquirer/search';
+import { input, password as passwordPrompt, confirm } from '@inquirer/prompts';
+import { stdin, stdout } from 'node:process';
+import { mkdir } from 'node:fs/promises';
+import { createActualClassifier } from './actual.js';
+import { categoryChoices } from './choices.js';
+import { runCategorization } from './workflow.js';
+import { parseArgs } from './args.js';
+import { budgetDataDir, configSummary, missingSettings, readConfig, resolveConfig, userPaths } from './config.js';
+import { runSetup } from './setup.js';
+import { resolve } from 'node:path';
+export { parseArgs } from './args.js';
+function usage() {
+    return `Usage: actual-jev [--interactive | --auto | --dry-run] [options]
+       actual-jev setup
+       actual-jev config show [--env-file PATH]
+
+Run setup once to save your connection settings. config show hides secrets.
+
+Modes: --interactive (default), --auto, --dry-run
+Interactive: type to search grouped categories, use arrow keys to move,
+and press Enter to select the highlighted category or Skip.
+Options:
+  --threshold NUMBER                   Minimum confidence for auto/dry-run (default: 0.9)
+  --max-examples-per-category NUMBER    Historical examples per category, 0–100 (default: 3)
+  --account ID_OR_NAME                  Limit to one account
+  --from YYYY-MM-DD                     Inclusive start date
+  --to YYYY-MM-DD                       Inclusive end date
+  --data-dir PATH                       Override the user Actual cache directory
+  --env-file PATH                       Read environment settings from a file
+  --help
+
+Use setup for saved settings, or supply all connection settings through
+exported environment variables and/or --env-file:
+  ACTUAL_SERVER_URL, ACTUAL_PASSWORD, ACTUAL_SYNC_ID, TYPESAFE_API_KEY
+  ACTUAL_ENCRYPTION_PASSWORD (only for encrypted budgets)
+
+Environment configuration never uses saved settings. Exported variables
+win over values in --env-file. No .env file is loaded automatically.
+Use command flags for run options. The saved maxExamplesPerCategory setting
+provides the example limit for saved configuration; the flag overrides it.`;
+}
+async function main() {
+    const options = parseArgs(process.argv.slice(2));
+    if (options.help) {
+        console.log(usage());
+        return;
+    }
+    const paths = userPaths();
+    const setup = async () => {
+        if (!stdin.isTTY || !stdout.isTTY)
+            throw new Error('Setup requires a terminal. Use environment variables for unattended runs.');
+        await runSetup(await readConfig(paths.configFile), paths.configFile, {
+            input: (message, initial) => input({ message, default: initial, validate: (value) => Boolean(value.trim()) || 'Enter a value' }),
+            secret: (message) => passwordPrompt({ message, mask: '*', validate: (value) => Boolean(value.trim()) || 'Enter a value' }),
+            select: (message, choices, initial) => search({
+                message,
+                default: initial,
+                source: (term) => choices.filter((choice) => choice.name.toLowerCase().includes((term ?? '').toLowerCase())),
+            }),
+            print: (line) => console.log(line),
+            actual,
+        });
+    };
+    if (options.command === 'setup') {
+        await setup();
+        return;
+    }
+    const { config, source } = await resolveConfig(paths.configFile, process.env, options.envFile);
+    const maxExamplesPerCategory = options.maxExamplesPerCategory ?? config.maxExamplesPerCategory ?? 3;
+    const dataDir = options.dataDir ? resolve(options.dataDir) : budgetDataDir(paths.dataRoot, config);
+    if (options.command === 'config-show') {
+        console.log([
+            `Configuration: ${source}${source === 'saved configuration' ? ` (${paths.configFile})` : ''}`,
+            `Actual data: ${dataDir} (${options.dataDir ? '--data-dir' : 'default'})`,
+            ...configSummary(config),
+            `threshold: ${options.threshold}`,
+            `maxExamplesPerCategory: ${maxExamplesPerCategory}`,
+        ].join('\n'));
+        return;
+    }
+    const missing = missingSettings(config);
+    if (missing.length) {
+        if (source === 'saved configuration' &&
+            options.mode === 'interactive' &&
+            stdin.isTTY &&
+            stdout.isTTY &&
+            (await confirm({ message: 'Configuration is incomplete. Start setup?', default: true }))) {
+            await setup();
+            return;
+        }
+        throw new Error(`Missing configuration: ${missing.join(', ')}. ${source === 'environment' ? 'Provide all connection settings through environment variables or --env-file (see --help). Saved settings are not used.' : 'Run actual-jev setup.'}`);
+    }
+    const { serverURL, password, syncId } = config;
+    if (options.mode === 'interactive' && (!stdin.isTTY || !stdout.isTTY))
+        throw new Error('Interactive mode requires a terminal; use --dry-run or --auto');
+    let initialized = false;
+    let writes = false;
+    try {
+        await mkdir(dataDir, { recursive: true, mode: 0o700 });
+        await actual.init({ serverURL: serverURL, password: password, dataDir, verbose: false });
+        initialized = true;
+        await actual.downloadBudget(syncId, { password: config.encryptionPassword });
+        await actual.sync();
+        const [accounts, payees, queryResult] = await Promise.all([
+            actual.getAccounts(),
+            actual.getPayees(),
+            actual.aqlQuery(actual.q('transactions').select('*').options({ splits: 'grouped' })),
+        ]);
+        const transactions = queryResult.data;
+        if (!Array.isArray(transactions))
+            throw new Error('ActualQL did not return transaction rows');
+        const jev = new TypeSafeClient({ apiKey: config.apiKey });
+        const classifier = await createActualClassifier(actual, {
+            client: jev,
+            maxExamplesPerCategory,
+            history: transactions,
+            eligibleAccountIds: new Set(accounts.filter((account) => !account.offbudget).map((account) => account.id)),
+        });
+        const transferPayeeAccountIds = new Map(payees.flatMap((payee) => (payee.transfer_acct ? [[payee.id, payee.transfer_acct]] : [])));
+        const categories = classifier.categories;
+        const summary = await runCategorization({
+            accounts,
+            transactions,
+            transferPayeeAccountIds,
+            payeeNames: new Map(payees.map((payee) => [payee.id, payee.name])),
+            categories,
+            classify: (transaction) => classifier.classify(transaction),
+            updateTransaction: async (id, fields) => {
+                await actual.updateTransaction(id, fields);
+                writes = true;
+            },
+            print: (line) => console.log(line),
+            color: Boolean(stdout.isTTY && !('NO_COLOR' in process.env)),
+            choose: options.mode === 'interactive'
+                ? async (_transaction, result) => search({
+                    message: 'Category (type to search, arrows to move, Enter to select)',
+                    source: (term) => categoryChoices(categories, term),
+                    default: result.categoryId,
+                    pageSize: Math.max(7, Math.min((stdout.rows ?? 20) - 6, 20)),
+                })
+                : undefined,
+        }, options);
+        console.log(`Examined ${summary.examined}; applied ${summary.applied}; would apply ${summary.wouldApply}; skipped ${summary.skipped}; transfers skipped ${summary.transfersSkipped}.`);
+    }
+    finally {
+        if (initialized) {
+            try {
+                if (writes)
+                    await actual.sync();
+            }
+            finally {
+                await actual.shutdown();
+            }
+        }
+    }
+}
+main().catch((error) => {
+    if (error instanceof Error && error.name === 'ExitPromptError') {
+        console.error('Setup or selection cancelled.');
+        process.exitCode = 130;
+        return;
+    }
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+});

package/dist/cli.test.d.ts

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

package/dist/cli.test.js

@@ -0,0 +1,130 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { spawn } from 'node:child_process';
+import { openSync, closeSync } from 'node:fs';
+import { mkdtemp, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { saveConfig, userPaths } from './config.js';
+void test('CLI works outside the project with saved settings and fixture clients', async (t) => {
+    const root = await mkdtemp(join(tmpdir(), 'jev-cli-'));
+    t.after(() => rm(root, { recursive: true, force: true }));
+    const first = join(root, 'first');
+    const second = join(root, 'second');
+    await Promise.all([mkdir(first), mkdir(second)]);
+    // Deliberately do not inherit any Actual or TypeSafe credentials from the environment.
+    const env = {
+        PATH: process.env.PATH,
+        HOME: root,
+        USERPROFILE: root,
+        XDG_CONFIG_HOME: join(root, 'config'),
+        XDG_DATA_HOME: join(root, 'data'),
+        APPDATA: join(root, 'roaming'),
+        LOCALAPPDATA: join(root, 'local'),
+        FIXTURE_LOG: join(root, 'calls.json'),
+    };
+    const hooks = join(root, 'hooks.mjs');
+    await writeFile(hooks, `import { registerHooks } from 'node:module';
+import { readFileSync } from 'node:fs';
+import ts from ${JSON.stringify(import.meta.resolve('typescript'))};
+const actual = ${JSON.stringify(`
+import { writeFile } from 'node:fs/promises';
+export async function init(options) {
+    if (options.password !== 'fixture-password') throw new Error('Incorrect resolved password');
+    await writeFile(process.env.FIXTURE_LOG, JSON.stringify(options));
+}
+export async function downloadBudget(id) { if (id !== 'fixture-budget') throw new Error('Incorrect budget'); }
+export async function sync() {}
+export async function shutdown() {}
+export async function getAccounts() { return []; }
+export async function getPayees() { return []; }
+export async function getCategoryGroups() { return []; }
+export async function getNote() { return {}; }
+export async function aqlQuery() { return { data: [] }; }
+export function q() { return { select() { return this; }, options() { return this; } }; }
+export async function updateTransaction() { throw new Error('Unexpected write'); }
+`)};
+const sdk = "export function choice() { throw new Error('Unexpected classification'); } export class TypeSafeClient { constructor(config) { if (config.apiKey !== 'fixture-key') throw new Error('Incorrect resolved API key'); } }";
+registerHooks({ resolve(specifier, context, next) {
+    if (specifier === '@actual-app/api' || specifier === '@typesafe-ai/sdk') return { url: 'data:text/javascript,' + encodeURIComponent(specifier === '@actual-app/api' ? actual : sdk), shortCircuit: true };
+    if (context.parentURL?.endsWith('.ts') && specifier.startsWith('./') && specifier.endsWith('.js')) return next(specifier.slice(0, -3) + '.ts', context);
+    return next(specifier, context);
+}, load(url, context, next) {
+    if (url.endsWith('.ts')) return { format: 'module', source: ts.transpileModule(readFileSync(new URL(url), 'utf8'), { compilerOptions: { module: ts.ModuleKind.ESNext, target: ts.ScriptTarget.ES2024 } }).outputText, shortCircuit: true };
+    return next(url, context);
+} });`);
+    const entry = process.env.JEV_TEST_CLI_ENTRY ?? fileURLToPath(new URL('./cli.ts', import.meta.url));
+    const run = async (args, cwd = first, connection = {}) => {
+        const outputPath = join(root, 'stdout');
+        const errorPath = join(root, 'stderr');
+        const out = openSync(outputPath, 'w');
+        const err = openSync(errorPath, 'w');
+        let code;
+        try {
+            code = await new Promise((resolve, reject) => {
+                const child = spawn(process.execPath, ['--import', hooks, entry, ...args], {
+                    cwd,
+                    env: { ...env, ...connection },
+                    stdio: ['ignore', out, err],
+                });
+                child.once('error', reject);
+                child.once('close', resolve);
+            });
+        }
+        finally {
+            closeSync(out);
+            closeSync(err);
+        }
+        const stdout = await readFile(outputPath, 'utf8');
+        const stderr = await readFile(errorPath, 'utf8');
+        if (code !== 0)
+            throw new Error(stderr || `CLI exited with ${code}`);
+        return { stdout, stderr };
+    };
+    const help = await run(['--help']);
+    assert.match(help.stdout, /actual-jev setup/);
+    await assert.rejects(run(['--dry-run']), (error) => error instanceof Error && error.message.includes('Missing configuration'));
+    await assert.rejects(run(['setup']), (error) => error instanceof Error && error.message.includes('requires a terminal'));
+    await saveConfig(userPaths(env, process.platform, root).configFile, {
+        version: 1,
+        serverURL: 'https://fixture.example',
+        password: 'fixture-password',
+        syncId: 'fixture-budget',
+        apiKey: 'fixture-key',
+        maxExamplesPerCategory: 2,
+    });
+    await writeFile(join(first, '.env'), 'ACTUAL_PASSWORD=wrong\nTYPESAFE_API_KEY=wrong');
+    const output = (await run(['--dry-run'])).stdout;
+    assert.match(output, /Examined 0; applied 0/);
+    const firstLog = await readFile(env.FIXTURE_LOG, 'utf8');
+    await run(['--dry-run'], second);
+    assert.equal(await readFile(env.FIXTURE_LOG, 'utf8'), firstLog);
+    const summary = (await run(['config', 'show'])).stdout;
+    assert.match(summary, /saved configuration/);
+    assert.ok(!summary.includes('fixture-password') && !summary.includes('fixture-key'));
+    assert.match(summary, /maxExamplesPerCategory: 2/);
+    const flags = (await run(['config', 'show', '--threshold', '0.6', '--max-examples-per-category', '0'])).stdout;
+    assert.match(flags, /threshold: 0.6/);
+    assert.match(flags, /maxExamplesPerCategory: 0/);
+    const connection = {
+        ACTUAL_SERVER_URL: 'https://fixture.example',
+        ACTUAL_PASSWORD: 'fixture-password',
+        ACTUAL_SYNC_ID: 'fixture-budget',
+        TYPESAFE_API_KEY: 'fixture-key',
+    };
+    await assert.rejects(run(['--dry-run'], first, { TYPESAFE_API_KEY: 'fixture-key' }), /Saved settings are not used/);
+    const envFile = join(root, 'automation.env');
+    await writeFile(envFile, Object.entries(connection)
+        .map(([key, value]) => `${key}=${value}`)
+        .join('\n'));
+    // Automation does not even read the personal config, including when it is malformed.
+    await writeFile(userPaths(env, process.platform, root).configFile, 'invalid JSON');
+    assert.match((await run(['--dry-run'], first, connection)).stdout, /Examined 0; applied 0/);
+    assert.match((await run(['--env-file', envFile, '--dry-run'])).stdout, /Examined 0; applied 0/);
+    const exportedSummary = (await run(['config', 'show'], first, connection)).stdout;
+    const fileSummary = (await run(['config', 'show', '--env-file', envFile])).stdout;
+    assert.equal(fileSummary, exportedSummary);
+    assert.match(fileSummary, /Configuration: environment/);
+    assert.match(fileSummary, /maxExamplesPerCategory: 3/);
+});

package/dist/config.d.ts

@@ -0,0 +1,28 @@
+export interface Config {
+    version: 1;
+    serverURL?: string;
+    password?: string;
+    syncId?: string;
+    encryptionPassword?: string;
+    apiKey?: string;
+    maxExamplesPerCategory?: number;
+}
+export type Environment = Record<string, string | undefined>;
+export declare function userPaths(env?: Environment, platform?: NodeJS.Platform, home?: string): {
+    configFile: string;
+    dataRoot: string;
+};
+export declare function validateConfig(value: unknown): Config;
+export declare function readConfig(path: string): Promise<Config>;
+export declare function saveConfig(path: string, config: Config): Promise<void>;
+/** Environment configuration is complete on its own and never reads saved credentials. */
+export declare function resolveConfig(configFile: string, env: Environment, envFile?: string): Promise<{
+    config: Config;
+    source: 'saved configuration';
+} | {
+    config: Config;
+    source: 'environment';
+}>;
+export declare function missingSettings(config: Config): string[];
+export declare function budgetDataDir(root: string, config: Config): string;
+export declare function configSummary(config: Config): string[];

package/dist/config.js

@@ -0,0 +1,135 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { chmod, mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { parseEnv } from 'node:util';
+export function userPaths(env = process.env, platform = process.platform, home = homedir()) {
+    const configRoot = platform === 'win32'
+        ? (env.APPDATA ?? join(home, 'AppData', 'Roaming'))
+        : platform === 'darwin'
+            ? join(home, 'Library', 'Application Support')
+            : env.XDG_CONFIG_HOME && isAbsolute(env.XDG_CONFIG_HOME)
+                ? env.XDG_CONFIG_HOME
+                : join(home, '.config');
+    const dataRoot = platform === 'win32'
+        ? (env.LOCALAPPDATA ?? join(home, 'AppData', 'Local'))
+        : platform === 'darwin'
+            ? join(home, 'Library', 'Application Support')
+            : env.XDG_DATA_HOME && isAbsolute(env.XDG_DATA_HOME)
+                ? env.XDG_DATA_HOME
+                : join(home, '.local', 'share');
+    return {
+        configFile: join(configRoot, 'actual-jev', 'config.json'),
+        dataRoot: join(dataRoot, 'actual-jev', 'budgets'),
+    };
+}
+export function validateConfig(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('Configuration must be an object');
+    const raw = value;
+    if (raw.version !== 1)
+        throw new Error('Unsupported configuration version');
+    const allowed = [
+        'version',
+        'serverURL',
+        'password',
+        'syncId',
+        'encryptionPassword',
+        'apiKey',
+        'maxExamplesPerCategory',
+    ];
+    for (const key of Object.keys(raw))
+        if (!allowed.includes(key))
+            throw new Error(`Unknown configuration setting: ${key}`);
+    for (const key of ['serverURL', 'password', 'syncId', 'encryptionPassword', 'apiKey']) {
+        if (raw[key] !== undefined && (typeof raw[key] !== 'string' || !raw[key].trim()))
+            throw new Error(`Invalid ${key}: expected a nonempty string`);
+    }
+    if (raw.serverURL !== undefined) {
+        let url;
+        try {
+            url = new URL(raw.serverURL);
+        }
+        catch {
+            throw new Error('serverURL must be an http or https URL');
+        }
+        if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password)
+            throw new Error('serverURL must be an http or https URL without embedded credentials');
+    }
+    if (raw.maxExamplesPerCategory !== undefined &&
+        (typeof raw.maxExamplesPerCategory !== 'number' ||
+            !Number.isSafeInteger(raw.maxExamplesPerCategory) ||
+            raw.maxExamplesPerCategory < 0 ||
+            raw.maxExamplesPerCategory > 100))
+        throw new Error('maxExamplesPerCategory must be an integer between 0 and 100');
+    return raw;
+}
+export async function readConfig(path) {
+    let content;
+    try {
+        content = await readFile(path, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return { version: 1 };
+        throw new Error(`Cannot read configuration at ${path}`, { cause: error });
+    }
+    try {
+        return validateConfig(JSON.parse(content));
+    }
+    catch (error) {
+        throw new Error(`Invalid configuration at ${path}. Correct or remove the file. ${error instanceof SyntaxError ? 'Invalid JSON.' : error.message}`, { cause: error });
+    }
+}
+export async function saveConfig(path, config) {
+    validateConfig(config);
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    if (process.platform !== 'win32')
+        await chmod(dirname(path), 0o700);
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temporary, JSON.stringify(config, null, 2) + '\n', { mode: 0o600, flag: 'wx' });
+        await rename(temporary, path);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}
+const envKeys = {
+    serverURL: 'ACTUAL_SERVER_URL',
+    password: 'ACTUAL_PASSWORD',
+    syncId: 'ACTUAL_SYNC_ID',
+    encryptionPassword: 'ACTUAL_ENCRYPTION_PASSWORD',
+    apiKey: 'TYPESAFE_API_KEY',
+};
+/** Environment configuration is complete on its own and never reads saved credentials. */
+export async function resolveConfig(configFile, env, envFile) {
+    const useEnvironment = envFile !== undefined || Object.values(envKeys).some((name) => env[name] !== undefined);
+    if (!useEnvironment)
+        return { config: await readConfig(configFile), source: 'saved configuration' };
+    const fileEnv = envFile ? parseEnv(await readFile(resolve(envFile), 'utf8')) : {};
+    const config = { version: 1 };
+    for (const key of Object.keys(envKeys)) {
+        const name = envKeys[key];
+        const value = env[name] ?? fileEnv[name];
+        if (value !== undefined && !(key === 'encryptionPassword' && value === ''))
+            config[key] = value;
+    }
+    return { config: validateConfig(config), source: 'environment' };
+}
+export function missingSettings(config) {
+    return ['serverURL', 'password', 'syncId', 'apiKey'].filter((key) => !config[key]);
+}
+export function budgetDataDir(root, config) {
+    const server = config.serverURL ? new URL(config.serverURL).href.replace(/\/$/, '') : '';
+    return join(root, createHash('sha256')
+        .update(JSON.stringify([server, config.syncId]))
+        .digest('hex'));
+}
+export function configSummary(config) {
+    return Object.keys(envKeys).map((key) => {
+        const value = config[key];
+        const secret = ['password', 'encryptionPassword', 'apiKey'].includes(key);
+        return `${key}: ${value === undefined ? '(not set)' : secret ? '[redacted]' : String(value)}`;
+    });
+}

package/dist/config.test.d.ts

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

package/dist/config.test.js

@@ -0,0 +1,98 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { mkdtemp, readFile, readdir, rm, stat, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { budgetDataDir, configSummary, missingSettings, readConfig, resolveConfig, saveConfig, userPaths, validateConfig, } from './config.js';
+const saved = {
+    version: 1,
+    serverURL: 'https://actual.example',
+    password: ' secret ',
+    syncId: 'budget',
+    apiKey: 'test-key',
+    maxExamplesPerCategory: 2,
+};
+void test('saved and environment configurations are independent', async (t) => {
+    const dir = await mkdtemp(join(tmpdir(), 'jev-config-'));
+    t.after(() => rm(dir, { recursive: true, force: true }));
+    const configFile = join(dir, 'config.json');
+    await saveConfig(configFile, { ...saved, encryptionPassword: 'saved-encryption' });
+    const personal = await resolveConfig(configFile, {});
+    assert.equal(personal.source, 'saved configuration');
+    assert.equal(personal.config.maxExamplesPerCategory, 2);
+    assert.equal(personal.config.apiKey, saved.apiKey);
+    const partial = await resolveConfig(configFile, { ACTUAL_SERVER_URL: 'https://automation.example' });
+    assert.equal(partial.source, 'environment');
+    assert.deepEqual(missingSettings(partial.config), ['password', 'syncId', 'apiKey']);
+    assert.equal(partial.config.encryptionPassword, undefined);
+    assert.equal(partial.config.maxExamplesPerCategory, undefined);
+    const envFile = join(dir, 'test.env');
+    await writeFile(envFile, 'ACTUAL_SERVER_URL=https://automation.example\nACTUAL_PASSWORD="file password"\nACTUAL_SYNC_ID=automation-budget\nTYPESAFE_API_KEY=automation-key\nACTUAL_ENCRYPTION_PASSWORD=');
+    const file = await resolveConfig(configFile, {}, envFile);
+    const exported = await resolveConfig(configFile, {
+        ACTUAL_SERVER_URL: 'https://automation.example',
+        ACTUAL_PASSWORD: 'file password',
+        ACTUAL_SYNC_ID: 'automation-budget',
+        TYPESAFE_API_KEY: 'automation-key',
+        ACTUAL_ENCRYPTION_PASSWORD: '',
+    });
+    assert.deepEqual(file, exported);
+    assert.deepEqual(missingSettings(file.config), []);
+    assert.equal((await resolveConfig(configFile, { ACTUAL_PASSWORD: 'exported' }, envFile)).config.password, 'exported');
+    await writeFile(configFile, 'invalid JSON');
+    assert.deepEqual(await resolveConfig(configFile, {}, envFile), file);
+    await assert.rejects(resolveConfig(configFile, {}), /Invalid configuration/);
+    await assert.rejects(resolveConfig(configFile, {}, join(dir, 'missing.env')), /ENOENT/);
+    await writeFile(envFile, '# An empty file must not fall back to saved credentials');
+    assert.deepEqual(missingSettings((await resolveConfig(configFile, {}, envFile)).config), [
+        'serverURL',
+        'password',
+        'syncId',
+        'apiKey',
+    ]);
+});
+void test('configuration roundtrips privately and invalid files give safe errors', async (t) => {
+    const dir = await mkdtemp(join(tmpdir(), 'jev-config-'));
+    t.after(() => rm(dir, { recursive: true, force: true }));
+    const file = join(dir, 'settings', 'config.json');
+    assert.deepEqual(await readConfig(file), { version: 1 });
+    await saveConfig(file, saved);
+    assert.deepEqual(await readConfig(file), saved);
+    await saveConfig(file, { ...saved, password: 'replacement' });
+    assert.equal((await readConfig(file)).password, 'replacement');
+    assert.deepEqual(await readdir(join(dir, 'settings')), ['config.json']);
+    if (process.platform !== 'win32') {
+        assert.equal((await stat(file)).mode & 0o777, 0o600);
+        assert.equal((await stat(join(dir, 'settings'))).mode & 0o777, 0o700);
+    }
+    await writeFile(file, '{"password":"sensitive",oops');
+    await assert.rejects(readConfig(file), (error) => error instanceof Error && error.message.includes(file) && !error.message.includes('sensitive'));
+    await writeFile(file, JSON.stringify({ version: 2 }));
+    await assert.rejects(readConfig(file), /Unsupported configuration version/);
+    assert.match(await readFile(file, 'utf8'), /version/);
+});
+void test('validation and redaction keep secrets out of displays', () => {
+    for (const value of [
+        { version: 1, threshold: 2 },
+        { version: 1, serverURL: 'ftp://example.com' },
+        { version: 1, serverURL: 'https://user:secret@example.com' },
+        { version: 1, apiKey: '' },
+        { version: 1, typo: true },
+    ])
+        assert.throws(() => validateConfig(value));
+    const output = configSummary({ ...saved, encryptionPassword: 'encrypted-secret' }).join('\n');
+    for (const value of [' secret ', 'test-key', 'encrypted-secret'])
+        assert.ok(!output.includes(value));
+    assert.match(output, /password: \[redacted\]/);
+    assert.match(output, /https:\/\/actual.example/);
+});
+void test('platform paths and budget cache identity are independent of working directory', () => {
+    assert.equal(userPaths({}, 'linux', '/users/test').configFile, '/users/test/.config/actual-jev/config.json');
+    assert.equal(userPaths({ XDG_CONFIG_HOME: '/config', XDG_DATA_HOME: '/data' }, 'linux', '/home/test').dataRoot, '/data/actual-jev/budgets');
+    assert.match(userPaths({}, 'darwin', '/users/test').configFile, /Library\/Application Support\/actual-jev/);
+    assert.match(userPaths({ APPDATA: '/roaming', LOCALAPPDATA: '/local' }, 'win32', '/test').configFile, /roaming\/actual-jev/);
+    const root = '/data/budgets';
+    assert.equal(budgetDataDir(root, saved), budgetDataDir(root, { ...saved, serverURL: `${saved.serverURL}/` }));
+    assert.notEqual(budgetDataDir(root, saved), budgetDataDir(root, { ...saved, syncId: 'other' }));
+    assert.notEqual(budgetDataDir(root, saved), budgetDataDir(root, { ...saved, serverURL: 'https://other.example' }));
+});

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export type { CategoryCandidate, CategorizedExample, TransactionDetails, RankedCategory, Classification, JevChoiceClient, } from './classifier.js';
+export { ActualJev } from './actual.js';
+export type { ActualDataClient, ActualJevConfig, ActualTransaction, ActualTransactionInput } from './actual.js';

package/dist/index.js

@@ -0,0 +1 @@
+export { ActualJev } from './actual.js';

package/dist/output.d.ts

@@ -0,0 +1,4 @@
+import type { ActualTransaction } from './actual.js';
+import type { CategoryCandidate } from './classifier.js';
+export declare function decision(value: string, color: boolean, applied?: boolean): string;
+export declare function describeSuggestion(transaction: ActualTransaction, accountName: string, category: CategoryCandidate | undefined, confidence: number, payeeNames?: ReadonlyMap<string, string>, color?: boolean): string;

package/dist/output.js

@@ -0,0 +1,36 @@
+function wrapText(value) {
+    const prefix = '  ';
+    const words = value.replace(/\s+/g, ' ').trim().split(' ');
+    const lines = [];
+    let line = prefix;
+    for (const word of words) {
+        if (line !== prefix && line.length + word.length + 1 > 88) {
+            lines.push(line);
+            line = `${prefix}${word}`;
+        }
+        else {
+            line += `${line === prefix ? '' : ' '}${word}`;
+        }
+    }
+    lines.push(line);
+    return lines;
+}
+function emphasize(value, code, color) {
+    return color ? `\u001b[${code}m${value}\u001b[0m` : value;
+}
+export function decision(value, color, applied = false) {
+    return `  Decision    ${emphasize(value, applied ? '32' : '33', color)}`;
+}
+function describe(transaction, accountName, payeeNames, color = false) {
+    const amount = (transaction.amount / 100).toFixed(2);
+    const namedPayee = transaction.payee ? payeeNames?.get(transaction.payee)?.trim() : undefined;
+    const importedPayee = transaction.imported_payee?.trim();
+    const merchant = importedPayee?.match(/\bPresso\s+(.+?)\s+-\s+Transazione\b/i)?.[1]?.trim();
+    const payee = namedPayee && namedPayee !== importedPayee ? namedPayee : (merchant ?? namedPayee ?? importedPayee);
+    const payeeLines = wrapText(payee || 'Unknown payee');
+    return `\n  ${emphasize(amount, '1;36', color)}\n${payeeLines.map((line) => emphasize(line, '1', color)).join('\n')}\n  ${emphasize(`${transaction.date} · ${accountName}`, '2', color)}`;
+}
+export function describeSuggestion(transaction, accountName, category, confidence, payeeNames, color = false) {
+    const name = category ? `${category.groupName} / ${category.name}` : 'no match';
+    return `${describe(transaction, accountName, payeeNames, color)}\n\n  Suggestion  ${emphasize(name, '36', color)} · ${Math.round(confidence * 100)}% confidence`;
+}

package/dist/setup.d.ts

@@ -0,0 +1,30 @@
+import { type Config } from './config.js';
+export interface BudgetChoice {
+    name: string;
+    cloudFileId: string;
+    groupId?: string | null;
+    encryptKeyId?: string | null;
+}
+export interface SetupPort {
+    input(message: string, initial?: string): Promise<string>;
+    secret(message: string): Promise<string>;
+    select(message: string, choices: {
+        name: string;
+        value: string;
+    }[], initial?: string): Promise<string>;
+    print(message: string): void;
+    actual: {
+        init(options: {
+            serverURL: string;
+            password: string;
+            dataDir: string;
+            verbose: boolean;
+        }): Promise<unknown>;
+        getBudgets(): Promise<BudgetChoice[]>;
+        downloadBudget(id: string, options: {
+            password?: string;
+        }): Promise<unknown>;
+        shutdown(): Promise<unknown>;
+    };
+}
+export declare function runSetup(saved: Config, configFile: string, port: SetupPort): Promise<void>;