spendwise 1.0.0

package/src/main/ipc.js

@@ -0,0 +1,187 @@
+import { app, ipcMain, dialog, shell, BrowserWindow } from 'electron';
+import path from 'node:path';
+import fs from 'node:fs';
+import { openDb, resolveDbPath, loadConfig, saveConfig, migrateLegacyUserData } from './storage/local.js';
+import { backupDb, backupsDir } from './backup.js';
+import { importLegacy } from './migrate.js';
+import { createCore } from './api-core.js';
+import { createWebServer } from './webserver.js';
+import { RELEASES_URL } from './update-check.js';
+import '../shared/engine.js';
+
+const E = globalThis.FinEngine;
+
+// Live db context shared with the api core (and the web server, which the
+// main process starts against the same ctx - one process owns db.json).
+export const ctx = { db: null, dbPath: null };
+export let core = null;
+export let webServer = null;
+
+const ok = (extra = {}) => ({ ok: true, ...extra });
+
+// Reverse-proxy settings resolve config-over-env: a value saved from the
+// Settings panel wins; otherwise fall back to the FINANCES_* env vars the CLI
+// uses; otherwise the safe default (no trusted proxy, cookie auto-detected).
+// ?? not || so an explicit saved 0 / false isn't overridden by the env value.
+function resolveWebProxy (config) {
+    const w = (config && config.webServer) || {};
+    const envTP = process.env.FINANCES_TRUST_PROXY;
+    const envSC = process.env.FINANCES_SECURE_COOKIE === '1' || process.env.FINANCES_SECURE_COOKIE === 'true';
+    return {
+        trustProxy: w.trustProxy ?? (envTP !== undefined ? Math.max(0, Number(envTP) || 0) : 0),
+        secureCookie: w.secureCookie ?? envSC,
+    };
+}
+const fail = (error) => ({ ok: false, error: String(error && error.message || error) });
+
+export async function registerIpc () {
+    migrateLegacyUserData(); // must run before the config is read
+    ctx.dbPath = resolveDbPath();
+    ctx.db = await openDb(ctx.dbPath);
+    ctx.version = app.getVersion();
+    core = createCore(ctx);
+
+    const handle = (channel, fn) => ipcMain.handle(channel, async (event, payload) => {
+        try {
+            return await fn(payload || {}, event);
+        } catch (err) {
+            return fail(err);
+        }
+    });
+
+    // core-backed handlers (same handlers serve the web clients)
+    handle('db:load', async () => ok(await core.loadDb()));
+    handle('db:rev', async () => ok(core.rev()));
+    handle('db:saveMonth', async (p) => ok(await core.saveMonth(p)));
+    handle('db:saveClosedMonth', async (p) => ok(await core.saveClosedMonth(p)));
+    handle('db:closeMonth', async (p) => ok(await core.closeMonth(p)));
+    handle('db:saveSettings', async (p) => ok(await core.saveSettings(p)));
+    handle('db:apply-tags', async (p) => ok(await core.applyTagsEverywhere(p)));
+    handle('backups:list', async () => ok(await core.listBackups()));
+    handle('backups:restore', async (p) => ok(await core.restoreBackup(p)));
+    handle('db:migrate-legacy', async (p) => ok(await core.migrateLegacy(p)));
+    handle('auth:has', async () => ok(core.authHas()));
+    handle('auth:verify', async (p) => ok(core.authVerify(p)));
+    handle('auth:set', async (p) => ok(await core.authSet(p)));
+    handle('update:check', async (p) => ok(await core.checkUpdate(p)));
+
+    // Opening the release page is the ONLY external URL the app will launch,
+    // so it's pinned to the project's own releases rather than taking a URL
+    // from the renderer - a compromised page can't turn this into a launcher.
+    handle('update:open', async () => {
+        await shell.openExternal(RELEASES_URL);
+        return ok();
+    });
+
+    // ------------------------------------------------------------ web access
+
+    webServer = createWebServer(ctx, core);
+    const bootConfig = loadConfig();
+    if (bootConfig.webServer && bootConfig.webServer.enabled && core.authHas().hasPassword) {
+        try {
+            await webServer.start(bootConfig.webServer.port || 4180, undefined, resolveWebProxy(bootConfig));
+            console.log('[web] serving on port ' + (bootConfig.webServer.port || 4180));
+        } catch (e) {
+            console.error('[web] failed to start: ' + e.message);
+        }
+    }
+
+    handle('web:status', async () => {
+        const config = loadConfig();
+        return ok({
+            enabled: !!(config.webServer && config.webServer.enabled),
+            port: (config.webServer && config.webServer.port) || 4180,
+            hasPassword: core.authHas().hasPassword,
+            ...webServer.status(),      // running/urls/sessions
+            // config intent wins for the proxy fields: while stopped the server
+            // still holds its boot default (0), which would misreport a saved
+            // setup. When running the two agree - start() derives from the same
+            // config - so overriding here is only ever a correction, never a lie.
+            ...resolveWebProxy(config),
+        });
+    });
+
+    handle('web:set', async ({ enabled, port, trustProxy, secureCookie }) => {
+        port = Math.max(1024, Math.min(65535, E.num(port) || 4180));
+        if (enabled && !core.authHas().hasPassword) {
+            throw new Error('Set an app password first - web access requires a login.');
+        }
+        const prev = loadConfig();
+        const webCfg = { ...(prev.webServer || {}), enabled: !!enabled, port };
+        // only persist proxy fields the caller actually sent, so unrelated
+        // toggles (on/off, port) don't wipe a saved reverse-proxy setup
+        if (trustProxy !== undefined) webCfg.trustProxy = Math.max(0, Math.min(10, Math.floor(Number(trustProxy) || 0)));
+        if (secureCookie !== undefined) webCfg.secureCookie = !!secureCookie;
+        saveConfig({ ...prev, webServer: webCfg });
+        const resolved = resolveWebProxy({ webServer: webCfg });
+        await webServer.stop();
+        if (enabled) await webServer.start(port, undefined, resolved);
+        // resolved last: while web access is off the server keeps its boot
+        // default (0), which would otherwise stomp the value just saved
+        return ok({ enabled: !!enabled, port, hasPassword: core.authHas().hasPassword, ...webServer.status(), ...resolved });
+    });
+
+    // ------------------------------------------- dialog-based (desktop only)
+
+    handle('backups:open-folder', async () => {
+        const dir = backupsDir(ctx.dbPath);
+        fs.mkdirSync(dir, { recursive: true });
+        await shell.openPath(dir);
+        return ok();
+    });
+
+    handle('db:export', async (payload, event) => {
+        const win = BrowserWindow.fromWebContents(event.sender);
+        const res = await dialog.showSaveDialog(win, {
+            title: 'Export a copy of your data',
+            defaultPath: 'spend-wise-export.json',
+            filters: [{ name: 'JSON', extensions: ['json'] }],
+        });
+        if (res.canceled || !res.filePath) return ok({ exported: null });
+        fs.copyFileSync(ctx.dbPath, res.filePath);
+        return ok({ exported: res.filePath });
+    });
+
+    // Move the database to a new location (e.g. a synced folder).
+    handle('db:change-location', async (payload, event) => {
+        const win = BrowserWindow.fromWebContents(event.sender);
+        const res = await dialog.showSaveDialog(win, {
+            title: 'Choose where to keep db.json',
+            defaultPath: path.join(path.dirname(ctx.dbPath), 'db.json'),
+            filters: [{ name: 'JSON', extensions: ['json'] }],
+        });
+        const snapshot = () => ({ data: E.clone(ctx.db.data), path: ctx.dbPath });
+        if (res.canceled || !res.filePath) return ok(snapshot());
+        const newPath = res.filePath;
+        if (path.resolve(newPath) !== path.resolve(ctx.dbPath)) {
+            if (fs.existsSync(newPath)) {
+                // adopting an existing file (multi-machine case): keep it, don't overwrite
+                backupDb(ctx.dbPath, 'pre-move');
+            } else {
+                fs.mkdirSync(path.dirname(newPath), { recursive: true });
+                fs.copyFileSync(ctx.dbPath, newPath);
+            }
+            saveConfig({ ...loadConfig(), dbPath: newPath });
+            ctx.dbPath = newPath;
+            ctx.db = await openDb(ctx.dbPath);
+        }
+        return ok(snapshot());
+    });
+
+    // Phase 1 of legacy import: pick the folder and report the groups found,
+    // so the user can adjust each group's kind before anything is written.
+    handle('db:migrate-scan', async (payload, event) => {
+        const win = BrowserWindow.fromWebContents(event.sender);
+        const res = await dialog.showOpenDialog(win, {
+            title: 'Select the legacy data folder (contains files like "january-26")',
+            properties: ['openDirectory'],
+        });
+        if (res.canceled || !res.filePaths.length) return ok({ scanned: false });
+        const { data } = importLegacy(res.filePaths[0]);
+        return ok({
+            scanned: true,
+            folder: res.filePaths[0],
+            groups: data.settings.groups.map((g) => ({ title: g.title, kind: g.kind })),
+        });
+    });
+}

package/src/main/main.js

@@ -0,0 +1,125 @@
+import { app, BrowserWindow, dialog } from 'electron';
+import path from 'node:path';
+import fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { registerIpc } from './ipc.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Closing with edits in flight would drop them silently — nothing is written
+ * until Update. This has to live here rather than in the renderer: Electron
+ * does not prompt for beforeunload, it just cancels the close without telling
+ * anyone. So intercept, ask the page what's unsaved, and confirm natively.
+ */
+function guardClose (win) {
+    let allowClose = false;
+    // tests exit unattended, so the gate is off under FINANCES_E2E — unless
+    // FINANCES_CLOSE_ANSWER names the button to auto-click, which is how the
+    // gate itself gets tested without leaving a modal on screen
+    const autoAnswer = process.env.FINANCES_E2E && process.env.FINANCES_CLOSE_ANSWER;
+
+    win.on('close', (e) => {
+        if (allowClose || (process.env.FINANCES_E2E && !autoAnswer)) return;
+        e.preventDefault();
+        win.webContents
+            .executeJavaScript('window.__unsavedSummary ? window.__unsavedSummary() : null')
+            .catch(() => null) // a broken page must never trap the user inside the app
+            .then(async (unsaved) => {
+                if (!unsaved) { allowClose = true; win.close(); return; }
+                const { response } = autoAnswer
+                    ? { response: autoAnswer === 'discard' ? 0 : 1 }
+                    : await dialog.showMessageBox(win, {
+                        type: 'warning',
+                        buttons: ['Discard & quit', 'Keep editing'],
+                        defaultId: 1,
+                        cancelId: 1,
+                        title: 'Unsaved changes',
+                        message: `Discard unsaved changes to ${unsaved}?`,
+                        detail: 'They have not been written to your database yet. Closing now loses them.',
+                    });
+                if (response === 0) { allowClose = true; win.close(); }
+            });
+    });
+}
+
+function createWindow () {
+    const win = new BrowserWindow({
+        width: 1500,
+        height: 960,
+        minWidth: 900,
+        minHeight: 600,
+        icon: path.join(__dirname, '../renderer/assets/icon.ico'),
+        backgroundColor: '#fafafa',
+        webPreferences: {
+            preload: path.join(__dirname, '../preload.cjs'),
+            contextIsolation: true,
+            nodeIntegration: false,
+            sandbox: true,
+        },
+    });
+    win.removeMenu();
+    guardClose(win);
+    win.loadFile(path.join(__dirname, '../renderer/index.html'));
+    if (process.env.FINANCES_DEVTOOLS) win.webContents.openDevTools({ mode: 'detach' });
+    if (process.env.FINANCES_LOG_CONSOLE) {
+        win.webContents.on('console-message', (e, level, message, line, sourceId) => {
+            console.log(`[renderer:${level}] ${message} (${sourceId}:${line})`);
+        });
+    }
+    if (process.env.FINANCES_SCREENSHOT) {
+        win.webContents.once('did-finish-load', () => {
+            setTimeout(async () => {
+                const image = await win.webContents.capturePage();
+                fs.writeFileSync(process.env.FINANCES_SCREENSHOT, image.toPNG());
+                console.log('[screenshot] written to ' + process.env.FINANCES_SCREENSHOT);
+            }, 2000);
+        });
+    }
+    if (process.env.FINANCES_E2E) {
+        win.webContents.setBackgroundThrottling(false); // keep painting for capturePage
+        win.webContents.once('did-finish-load', () => {
+            setTimeout(async () => {
+                const script = fs.readFileSync(process.env.FINANCES_E2E, 'utf8');
+                let dbg = null;
+                if (process.env.FINANCES_PROFILE) {
+                    dbg = win.webContents.debugger;
+                    dbg.attach('1.3');
+                    await dbg.sendCommand('Profiler.enable');
+                    await dbg.sendCommand('Profiler.start');
+                }
+                try {
+                    const result = await win.webContents.executeJavaScript(script);
+                    console.log('[e2e] ' + JSON.stringify(result, null, 2));
+                } catch (err) {
+                    console.log('[e2e:error] ' + (err && err.message || err));
+                }
+                if (dbg) {
+                    const { profile } = await dbg.sendCommand('Profiler.stop');
+                    fs.writeFileSync(process.env.FINANCES_PROFILE, JSON.stringify(profile));
+                    console.log('[profile] written to ' + process.env.FINANCES_PROFILE);
+                }
+                if (process.env.FINANCES_E2E_SCREENSHOT) {
+                    const image = await win.webContents.capturePage();
+                    fs.writeFileSync(process.env.FINANCES_E2E_SCREENSHOT, image.toPNG());
+                    console.log('[screenshot] written to ' + process.env.FINANCES_E2E_SCREENSHOT);
+                }
+                app.quit();
+            }, 2500);
+        });
+    }
+    return win;
+}
+
+app.whenReady().then(async () => {
+    await registerIpc();
+    createWindow();
+
+    app.on('activate', () => {
+        if (BrowserWindow.getAllWindows().length === 0) createWindow();
+    });
+});
+
+app.on('window-all-closed', () => {
+    if (process.platform !== 'darwin') app.quit();
+});

package/src/main/migrate.js

@@ -0,0 +1,181 @@
+import path from 'node:path';
+import fs from 'node:fs';
+import '../shared/engine.js';
+
+const E = globalThis.FinEngine;
+
+const MONTH_NUM = {
+    january: '01', february: '02', march: '03', april: '04',
+    may: '05', june: '06', july: '07', august: '08',
+    september: '09', october: '10', november: '11', december: '12',
+};
+
+const KIND_MAP = {
+    income: 'income',
+    budgets: 'envelope',
+    expenses: 'expense',
+    miscBudgets: 'goal',
+};
+
+/**
+ * Import a legacy old-finances-app data directory into a fresh db shape.
+ *
+ * Legacy layout: one JSON file per month named `<monthname>-<yy>` containing
+ * `{ form: { data: [groups], savings } }`, plus a `savings_history` file
+ * keyed like "June '18". Field ids are 13-char uniqids reused across months
+ * for pinned fields - we map each legacy id to one uuid so cross-month
+ * identity (and budget links) survive.
+ *
+ * kindOverrides maps a legacy group TITLE to a kind, overriding the default
+ * type mapping everywhere that group appears.
+ */
+export function importLegacy (dataDir, kindOverrides = {}) {
+    const files = fs.readdirSync(dataDir);
+    const idMap = new Map();
+    const mapId = (oldId) => {
+        if (!oldId) return null;
+        if (!idMap.has(oldId)) idMap.set(oldId, E.uuid());
+        return idMap.get(oldId);
+    };
+
+    const groupDefs = [];
+    const defFor = (title, mappedKind) => {
+        let def = groupDefs.find((d) => d.title === title);
+        if (!def) {
+            const kind = kindOverrides[title] || mappedKind;
+            def = { id: E.uuid(), title, kind, order: groupDefs.length };
+            if (E.isEnvelopeKind(kind)) def.strictOverspend = false;
+            groupDefs.push(def);
+        }
+        return def;
+    };
+
+    const months = {};
+    let parsed = 0;
+    const warnings = [];
+
+    for (const file of files) {
+        const m = /^([a-z]+)-(\d{2})$/.exec(file);
+        if (!m || !MONTH_NUM[m[1]]) continue;
+        const key = `20${m[2]}-${MONTH_NUM[m[1]]}`;
+
+        let json;
+        try {
+            json = JSON.parse(fs.readFileSync(path.join(dataDir, file), 'utf8'));
+        } catch {
+            warnings.push(`${file}: unreadable JSON, skipped`);
+            continue;
+        }
+        const form = json && json.form;
+        if (!form || !Array.isArray(form.data)) {
+            warnings.push(`${file}: no form data, skipped`);
+            continue;
+        }
+
+        const month = {
+            key,
+            status: 'closed',
+            startingSavings: E.num(form.savings),
+            closingSavings: null,
+            groups: [],
+        };
+
+        for (const legacyGroup of form.data) {
+            const def = defFor(legacyGroup.title || 'Untitled', KIND_MAP[legacyGroup.type] || 'expense');
+            const kind = def.kind; // may differ from the legacy type via overrides
+            const group = { groupId: def.id, title: def.title, kind, fields: [] };
+
+            for (const lf of legacyGroup.fields || []) {
+                const field = {
+                    id: mapId(lf.id) || E.uuid(),
+                    label: lf.label || '',
+                    value: E.num(lf.value),
+                    pinned: E.truthy(lf.default),
+                    accounted: E.truthy(lf.accounted),
+                    tags: [],
+                };
+                if (kind === 'expense') field.budgetId = mapId(lf.budget);
+                if (E.isEnvelopeKind(kind)) {
+                    field.avail = E.num(lf.avail);
+                    field.spent = E.num(lf.spent);
+                }
+                if (kind === 'goal') field.target = null;
+                group.fields.push(field);
+            }
+            month.groups.push(group);
+        }
+
+        // Legacy 'budgets' stored spent as the DERIVED sum of linked expenses;
+        // our model stores only direct/manual spending and derives the linked
+        // part live - strip it so it isn't counted twice.
+        for (const group of month.groups) {
+            if (!E.isEnvelopeKind(group.kind)) continue;
+            for (const field of group.fields) {
+                field.spent = Math.max(0, E.num(field.spent) - E.linkedSpent(month, field.id));
+            }
+        }
+
+        months[key] = month;
+        parsed += 1;
+    }
+
+    if (!parsed) throw new Error('No legacy month files found in that folder.');
+
+    // most recent month stays open; every closed month gets a derived closing figure
+    const keys = Object.keys(months).sort();
+    months[keys[keys.length - 1]].status = 'open';
+    for (const key of keys) {
+        if (months[key].status === 'closed') {
+            months[key].closingSavings = E.savings(months[key]);
+        }
+    }
+
+    // savings_history: { "June '18": "3800" } → { "2018-06": 3800 }
+    const savingsHistory = {};
+    try {
+        const raw = JSON.parse(fs.readFileSync(path.join(dataDir, 'savings_history'), 'utf8'));
+        for (const [label, value] of Object.entries(raw)) {
+            const hm = /^([A-Za-z]+) '(\d{2})$/.exec(label.trim());
+            if (!hm) continue;
+            const mm = MONTH_NUM[hm[1].toLowerCase()];
+            if (!mm) continue;
+            savingsHistory[`20${hm[2]}-${mm}`] = E.num(value);
+        }
+    } catch {
+        warnings.push('savings_history missing or unreadable - rebuilt from month files');
+    }
+    // month files are authoritative where both exist
+    for (const key of keys) savingsHistory[key] = E.num(months[key].startingSavings);
+
+    // Only groups still present in the latest month become the go-forward
+    // settings; groups the user renamed/retired years ago live on inside the
+    // month snapshots (months are self-describing) without cluttering new months.
+    const latest = months[keys[keys.length - 1]];
+    const activeGroups = latest.groups.map((g, i) => {
+        const def = groupDefs.find((d) => d.id === g.groupId);
+        return { ...def, order: i };
+    });
+
+    return {
+        data: {
+            meta: { schemaVersion: 1, rev: 0 },
+            settings: {
+                currency: 'USD',
+                initialSavings: E.num(months[keys[0]].startingSavings),
+                groups: activeGroups,
+            },
+            months,
+            savingsHistory,
+        },
+        summary: {
+            months: parsed,
+            firstMonth: keys[0],
+            lastMonth: keys[keys.length - 1],
+            groups: activeGroups.map((g) => `${g.title} (${g.kind})`),
+            retiredGroups: groupDefs.filter((d) => !activeGroups.some((a) => a.id === d.id))
+                .map((g) => `${g.title} (${g.kind})`),
+            historyEntries: Object.keys(savingsHistory).length,
+            warnings,
+        },
+    };
+}

package/src/main/storage/local.js

@@ -0,0 +1,55 @@
+import path from 'node:path';
+import fs from 'node:fs';
+import { app } from 'electron';
+export { openDb, currentMonthKey } from '../db-open.js';
+
+const configPath = () => path.join(app.getPath('userData'), 'config.json');
+
+// The app was called "Finances" before 1.1; Electron derives userData from the
+// app name, so the rename would strand the old folder's database, settings and
+// backups. Adopt them once, on first run of the renamed app.
+const LEGACY_APP_NAME = 'Finances';
+
+export function migrateLegacyUserData () {
+    const current = app.getPath('userData');
+    const legacy = path.join(path.dirname(current), LEGACY_APP_NAME);
+    if (path.resolve(legacy) === path.resolve(current) || !fs.existsSync(legacy)) return null;
+    // only ever adopt into a folder that has no data of its own
+    if (fs.existsSync(path.join(current, 'db.json')) || fs.existsSync(path.join(current, 'config.json'))) return null;
+
+    const copied = [];
+    fs.mkdirSync(current, { recursive: true });
+    for (const name of ['config.json', 'db.json']) {
+        const from = path.join(legacy, name);
+        if (fs.existsSync(from)) { fs.copyFileSync(from, path.join(current, name)); copied.push(name); }
+    }
+    const legacyBackups = path.join(legacy, 'backups');
+    if (fs.existsSync(legacyBackups)) {
+        // the user's history lives here - Settings → Backups must still find it
+        fs.cpSync(legacyBackups, path.join(current, 'backups'), { recursive: true });
+        copied.push(`backups/ (${fs.readdirSync(legacyBackups).length} files)`);
+    }
+    if (!copied.length) return null;
+    // copy, never move: the old folder stays as a safety net
+    console.log(`[migrate] adopted data from "${LEGACY_APP_NAME}": ${copied.join(', ')}`);
+    return { from: legacy, to: current, copied };
+}
+
+export function loadConfig () {
+    try {
+        return JSON.parse(fs.readFileSync(configPath(), 'utf8'));
+    } catch {
+        return {};
+    }
+}
+
+export function saveConfig (config) {
+    fs.mkdirSync(path.dirname(configPath()), { recursive: true });
+    fs.writeFileSync(configPath(), JSON.stringify(config, null, 2));
+}
+
+export function resolveDbPath () {
+    if (process.env.FINANCES_DB_PATH) return process.env.FINANCES_DB_PATH; // tests
+    const config = loadConfig();
+    return config.dbPath || path.join(app.getPath('userData'), 'db.json');
+}

package/src/main/update-check.js

@@ -0,0 +1,99 @@
+/*
+ * Update check against the GitHub Releases API.
+ *
+ * Privacy: this is the ONLY outbound request the app ever makes, and it is a
+ * plain unauthenticated GET of a public URL - no query string, no body, no
+ * identifier, nothing about the user or their finances. GitHub sees an IP and
+ * a timestamp, the same as opening the releases page in a browser. It is off
+ * with one toggle (Settings → updateCheck: false) and silently skipped when
+ * offline, so the app still runs with the network unplugged.
+ *
+ * It runs in the main/server process, never the renderer: one check per
+ * install rather than one per open browser tab, and the renderer's CSP does
+ * not have to allow an external origin.
+ */
+'use strict';
+
+const REPO = 'blindmikey/spendwise';
+const ENDPOINT = `https://api.github.com/repos/${REPO}/releases/latest`;
+const RELEASES_URL = `https://github.com/${REPO}/releases/latest`;
+
+const TTL_MS = 24 * 60 * 60 * 1000; // a long-running server checks once a day
+const TIMEOUT_MS = 5000;            // never let a hung request stall the UI
+
+/**
+ * "v1.2.3" / "1.2.3" / "1.2.3-beta.1" → { parts:[1,2,3], pre:'beta.1'|null }.
+ * Returns null for anything unparseable, so a garbage tag can never be read
+ * as an update.
+ */
+export function parseVersion (v) {
+    const m = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/.exec(String(v || '').trim());
+    if (!m) return null;
+    return { parts: [Number(m[1]), Number(m[2]), Number(m[3])], pre: m[4] || null };
+}
+
+/** Is `latest` a newer release than `current`? Unparseable → false (never nag). */
+export function isNewer (latest, current) {
+    const a = parseVersion(latest);
+    const b = parseVersion(current);
+    if (!a || !b) return false;
+    for (let i = 0; i < 3; i++) {
+        if (a.parts[i] > b.parts[i]) return true;
+        if (a.parts[i] < b.parts[i]) return false;
+    }
+    // same x.y.z: a prerelease is OLDER than its final, and we never offer to
+    // "update" someone from a final onto a prerelease
+    if (a.pre && !b.pre) return false;
+    if (!a.pre && b.pre) return true;
+    return false;
+}
+
+/**
+ * `fetchImpl` / `now` are injectable so tests never touch the network.
+ */
+export function createUpdateChecker ({ currentVersion, fetchImpl, now } = {}) {
+    const doFetch = fetchImpl || globalThis.fetch;
+    const clock = now || (() => Date.now());
+    let cache = null; // { at, result }
+
+    async function fetchLatest () {
+        // AbortSignal.timeout needs node 17.3+; we support 18+
+        const res = await doFetch(ENDPOINT, {
+            headers: { Accept: 'application/vnd.github+json', 'User-Agent': 'spendwise' },
+            signal: AbortSignal.timeout(TIMEOUT_MS),
+        });
+        if (!res.ok) throw new Error(`GitHub returned ${res.status}`);
+        const body = await res.json();
+        const tag = body && (body.tag_name || body.name);
+        if (!parseVersion(tag)) throw new Error('No usable release tag');
+        return { tag: String(tag), url: (body && body.html_url) || RELEASES_URL };
+    }
+
+    return {
+        /** `force` bypasses the cache (the Settings "Check now" button). */
+        async check ({ force = false } = {}) {
+            if (!force && cache && clock() - cache.at < TTL_MS) return cache.result;
+
+            const base = { current: currentVersion || '', checkedAt: clock() };
+            let result;
+            try {
+                const { tag, url } = await fetchLatest();
+                result = {
+                    ...base,
+                    latest: tag,
+                    url,
+                    available: isNewer(tag, currentVersion),
+                };
+            } catch (err) {
+                // offline, rate-limited, no releases yet, DNS blocked: all the
+                // same non-event. Never surfaced as an error the user must act
+                // on - the app does not need GitHub to work.
+                result = { ...base, latest: null, url: RELEASES_URL, available: false, unreachable: true };
+            }
+            cache = { at: clock(), result };
+            return result;
+        },
+    };
+}
+
+export { RELEASES_URL };