spendwise 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 blindmikey
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,119 @@
+<div align="center">
+    <picture>
+        <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/blindmikey/spendwise/main/docs/spendwise.svg">
+        <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/blindmikey/spendwise/main/docs/spendwise-light.svg">
+        <img alt="Spend Wise" height="64" src="https://raw.githubusercontent.com/blindmikey/spendwise/main/docs/spendwise-w-bg.svg">
+    </picture>
+    <div><a href="https://www.npmjs.com/package/@blindmikey/spendwise"><img alt="npm" src="https://img.shields.io/npm/v/%40blindmikey%2Fspendwise?label=npm&color=009967"></a></div>
+    <h2>A Simple and easy-to-use envelope-budgeting app.</h2>
+    <div><a href='https://ko-fi.com/G0G2231VF9' target='_blank'><img height='36' style='border:0px;height:36px;' src='https://storage.ko-fi.com/cdn/kofi3.png?v=6' border='0' alt='Buy Me a Coffee at ko-fi.com' /></a></div>
+    <div><span>&nbsp;</span></div>
+</div>
+
+<div align="center">
+    <picture>
+        <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/blindmikey/spendwise/main/docs/screenshot-light.png">
+        <img alt="Spend Wise" src="https://raw.githubusercontent.com/blindmikey/spendwise/main/docs/screenshot-light.png">
+    </picture>
+</div>
+
+Spend Wise is envelope budgeting that runs where you
+want it - as a desktop app, or as a small server you host yourself and reach
+from any browser. Same app, same single data file.
+
+**No account. No cloud. No subscription. No telemetry.** Your finances are a
+JSON file on your own disk, and the app works with the network unplugged.
+
+The one request it ever makes is a public read of this project's latest release
+tag, so it can tell you an update exists - no identifier, nothing about your
+money, and one checkbox in Settings turns it off for good.
+
+## What it does
+
+**Budget in envelopes.** Each budget is a little savings account: it gets a
+monthly allotment, and unspent money stays in it. Groceries left over in May is
+still there in June - no zeroing out, no starting over.
+
+**Spending flows in on its own.** Assign an expense to an envelope and it draws
+from that balance instead of counting against the month twice. Every envelope
+shows what's left at a glance: a full green line when untouched, amber when it's
+nearly gone, red when it's overdrawn.
+
+**Save up for the big, irregular stuff.** Goal budgets fill toward a target -
+the annual insurance bill, a vacation - and stop contributing once they're full.
+Give one a due date and it works out the monthly deposit for you. Spend from it
+and contributions resume automatically.
+
+**Fund budgets from a percentage.** Point an envelope at other groups and it
+takes a cut of them, live - freelance tax savings at 33% of self-employment
+income minus expenses, recalculated as you type and carried forward every month.
+
+**Close out the month** when you're done: balances roll over, recurring lines
+copy forward, savings gets a snapshot, and next month is waiting for you.
+
+**See where it actually went.** Tag anything; the Insights view turns those tags
+into spending and income trends, per-tag averages, and your savings trajectory
+over the years.
+
+**Budget together.** Two people editing the same month merge field by field
+rather than one clobbering the other - you both keep your edits.
+
+**Change your mind later.** Past months are view-only until you unlock them.
+Edit one and every later month's balances and savings history recompute
+correctly, after taking a backup and showing you exactly what changed.
+
+## Install
+
+### Desktop Releases
+
+Grab the latest Windows installer or portable `.exe` from
+[Releases](https://github.com/blindmikey/spendwise/releases). That's the whole
+setup - it keeps its database in `%APPDATA%/Spend Wise/db.json`.
+
+On macOS or Linux, run it from source (see
+[docs/development.md](docs/development.md)) or host the web version below.
+
+## Web Version
+
+### NPM
+
+If NPM is your thing - Electron is never installed, just one process owns the
+database, so everyone editing through it merges cleanly.
+
+```bash
+npm i -g spendwise
+spendwise-server --set-password   # everyone signs in with this
+spendwise-server                  # → http://localhost:4180
+```
+
+### Docker
+
+Or with Docker:
+
+```bash
+docker build -t spendwise .
+docker run -d --name spendwise -p 4180:4180 \
+  -v /srv/spendwise:/data -e FINANCES_PASSWORD=change-me spendwise
+```
+
+The server speaks plain HTTP and has no TLS of its own. On a LAN that's fine;
+before putting it on the internet, read
+**[docs/hosting.md](docs/hosting.md)** - reverse proxy configs for Caddy, nginx
+and Apache, every setting, and an account of the security model.
+
+### No server? No problem.
+
+The desktop app can share itself. Set an app password, flip on **Web access**,
+and phones and laptops on your network open the printed URL and edit the same
+live data - until you close the app.
+
+## Docs
+
+- **[Hosting](docs/hosting.md)** - self-hosting, Docker, reverse proxies, TLS, configuration, security model.
+- **[Development](docs/development.md)** - how the money math works, architecture, scripts, tests.
+
+## License
+
+MIT - see [LICENSE](LICENSE).
+
+Icons are [Font Awesome Free](https://fontawesome.com) (CC BY 4.0).

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "spendwise",
+  "productName": "Spend Wise",
+  "version": "1.0.0",
+  "description": "A Simple and easy-to-use envelope-budgeting app",
+  "author": "blindmikey <github@blindmikey.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/blindmikey/spendwise.git"
+  },
+  "type": "module",
+  "main": "src/main/main.js",
+  "bin": {
+    "spendwise-server": "src/server/cli.mjs"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "files": [
+    "src/**/*",
+    "!src/renderer/css/input.css",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "electron .",
+    "serve": "node src/server/cli.mjs",
+    "css": "tailwindcss -i src/renderer/css/input.css -o src/renderer/css/app.css --minify",
+    "css:watch": "tailwindcss -i src/renderer/css/input.css -o src/renderer/css/app.css --watch",
+    "test": "vitest run",
+    "dist": "npm run css && electron-builder",
+    "prepublishOnly": "npm run css"
+  },
+  "dependencies": {
+    "lowdb": "^7.0.1"
+  },
+  "devDependencies": {
+    "@alpinejs/collapse": "^3.14.0",
+    "@tailwindcss/cli": "^4.0.0",
+    "alpinejs": "^3.14.0",
+    "apexcharts": "^4.0.0",
+    "electron": "^37.0.0",
+    "electron-builder": "^25.0.0",
+    "tailwindcss": "^4.0.0",
+    "vitest": "^3.0.0"
+  },
+  "build": {
+    "appId": "com.blindmikey.spendwise",
+    "files": [
+      "src/**/*",
+      "!src/renderer/css/input.css"
+    ],
+    "win": {
+      "target": ["nsis", "portable"],
+      "icon": "build/icon.ico"
+    },
+    "nsis": {
+      "oneClick": false,
+      "allowToChangeInstallationDirectory": true
+    }
+  }
+}

package/src/main/api-core.js

@@ -0,0 +1,231 @@
+/*
+ * Transport-agnostic API core: the same handlers sit behind Electron IPC,
+ * the built-in web server, and the dev preview server. Method names match
+ * the renderer's window.api surface so every transport maps 1:1.
+ *
+ * `ctx` owns the LIVE lowdb instance and path, mutable so restore /
+ * change-location can swap them: { db, dbPath }. Handlers THROW on failure -
+ * each transport wraps results in { ok, ... } / { ok:false, error }.
+ *
+ * No Electron imports here - dialog-based features (export, change location,
+ * import-folder picking) live with their transports.
+ */
+'use strict';
+
+import fs from 'node:fs';
+import '../shared/engine.js';
+import { backupDb, listBackups, backupPath } from './backup.js';
+import { importLegacy } from './migrate.js';
+import { openDb } from './db-open.js';
+import { hashPassword, verifyPassword } from './auth.js';
+import { createUpdateChecker, RELEASES_URL } from './update-check.js';
+
+const E = globalThis.FinEngine;
+
+export function createCore (ctx) {
+    const updater = createUpdateChecker({
+        currentVersion: ctx.version || '',
+        fetchImpl: ctx.fetchImpl, // tests inject; production uses global fetch
+    });
+    const assertRev = (expectedRev) => {
+        if (E.num(expectedRev) !== E.num(ctx.db.data.meta.rev)) {
+            throw new Error('stale: the data was changed by another session. Reload before saving.');
+        }
+    };
+
+    async function persist () {
+        ctx.db.data.meta.rev = E.num(ctx.db.data.meta.rev) + 1;
+        await ctx.db.write(); // lowdb/steno writes temp-file-then-rename (atomic)
+    }
+
+    const snapshot = () => ({ data: E.clone(ctx.db.data), path: ctx.dbPath, version: ctx.version || '' });
+
+    return {
+        async loadDb () {
+            await ctx.db.read();
+            if (!ctx.db.data) throw new Error('Database file is missing or unreadable.');
+            return snapshot();
+        },
+
+        rev () {
+            return { rev: E.num(ctx.db.data.meta.rev) };
+        },
+
+        /**
+         * Ask GitHub whether a newer release is tagged. Opt-out lives in
+         * settings so it travels with the database (a self-hoster decides once
+         * for everyone who uses their server). Never throws: a failed check is
+         * not the user's problem.
+         */
+        async checkUpdate ({ force = false } = {}) {
+            const enabled = ctx.db.data.settings.updateCheck !== false; // default on
+            if (!enabled) {
+                return { enabled: false, current: ctx.version || '', available: false, url: RELEASES_URL };
+            }
+            const res = await updater.check({ force });
+            return { enabled: true, ...res };
+        },
+
+        /**
+         * Save an OPEN month. Clean rev → write in place. Stale rev → field-
+         * level three-way merge against what the other session persisted
+         * (`base` is the month as this client loaded it), then recompute
+         * forward so derived chains stay consistent. True conflicts are
+         * reported, not fatal - co-editing must not hard-stop.
+         */
+        async saveMonth ({ key, month, base, expectedRev }) {
+            if (!ctx.db.data.months[key]) throw new Error('That month no longer exists - reload.');
+            E.applyAutoValues(month);
+
+            if (E.num(expectedRev) === E.num(ctx.db.data.meta.rev)) {
+                ctx.db.data.months[key] = month;
+                ctx.db.data.savingsHistory[key] = E.num(month.startingSavings);
+                await persist();
+                return { rev: ctx.db.data.meta.rev };
+            }
+
+            const theirs = ctx.db.data.months[key];
+            if (theirs.status === 'closed' && month.status !== 'closed') {
+                throw new Error(`${E.keyLabel(key)} was closed by another session. Reload before editing.`);
+            }
+            if (!base) assertRev(expectedRev); // client sent no base snapshot → legacy hard stop
+
+            const { month: merged, conflicts } = E.mergeMonth(base, month, theirs);
+            const staged = E.clone(ctx.db.data);
+            staged.months[key] = E.applyAutoValues(merged);
+            const { db: recomputed } = E.recomputeForward(staged, key);
+            ctx.db.data = recomputed;
+            ctx.db.data.savingsHistory[key] = E.num(ctx.db.data.months[key].startingSavings);
+            await persist();
+            return { ...snapshot(), rev: ctx.db.data.meta.rev, merged: true, conflicts };
+        },
+
+        // Save an edited CLOSED month: backup → apply → recompute → persist.
+        // History edits keep the hard rev gate - merging rewritten history is
+        // not worth the risk.
+        async saveClosedMonth ({ key, month, expectedRev }) {
+            assertRev(expectedRev);
+            backupDb(ctx.dbPath, 'pre-recompute');
+            const staged = E.clone(ctx.db.data);
+            staged.months[key] = E.applyAutoValues(month);
+            const { db: recomputed, changes } = E.recomputeForward(staged, key);
+            ctx.db.data = recomputed;
+            await persist();
+            return { ...snapshot(), changes };
+        },
+
+        // Close out a month: finalize it, materialize the next via rollover.
+        async closeMonth ({ key, month, expectedRev }) {
+            assertRev(expectedRev);
+            const nk = E.nextKey(key);
+            if (ctx.db.data.months[nk]) {
+                throw new Error(`${E.keyLabel(nk)} already exists - edit it instead of closing ${E.keyLabel(key)} again.`);
+            }
+            backupDb(ctx.dbPath, 'close-month');
+            E.applyAutoValues(month);
+            month.status = 'closed';
+            month.closingSavings = E.savings(month);
+            ctx.db.data.months[key] = month;
+            ctx.db.data.savingsHistory[key] = E.num(month.startingSavings);
+            const next = E.rollover(month, ctx.db.data.settings);
+            ctx.db.data.months[nk] = next;
+            ctx.db.data.savingsHistory[nk] = E.num(next.startingSavings);
+            await persist();
+            return { ...snapshot(), nextKey: nk };
+        },
+
+        // Save settings; open months re-sync to the new group list. The app
+        // password can NOT be changed through here - settings.auth is always
+        // preserved from the live db (see setPassword), so a web client can
+        // never overwrite it with a doctored settings blob.
+        async saveSettings ({ settings, expectedRev }) {
+            assertRev(expectedRev);
+            const prevInitial = E.num(ctx.db.data.settings.initialSavings);
+            const auth = ctx.db.data.settings.auth;
+            ctx.db.data.settings = { ...settings };
+            if (auth) ctx.db.data.settings.auth = auth;
+            else delete ctx.db.data.settings.auth;
+
+            for (const key of E.monthKeys(ctx.db.data)) {
+                if (ctx.db.data.months[key].status === 'open') {
+                    E.syncMonthWithSettings(ctx.db.data.months[key], ctx.db.data.settings);
+                }
+            }
+
+            let changes = [];
+            const keys = E.monthKeys(ctx.db.data);
+            const newInitial = E.num(settings.initialSavings);
+            if (keys.length && newInitial !== prevInitial) {
+                backupDb(ctx.dbPath, 'initial-savings');
+                const first = keys[0];
+                ctx.db.data.months[first].startingSavings = newInitial;
+                ctx.db.data.savingsHistory[first] = newInitial;
+                const res = E.recomputeForward(ctx.db.data, first);
+                ctx.db.data = res.db;
+                changes = res.changes;
+            }
+
+            await persist();
+            return { ...snapshot(), changes };
+        },
+
+        // Tag add/remove applies to the field across ALL months. No rev gate:
+        // tag ops are semantic and commute with concurrent edits - rebasing
+        // them onto the current state is always correct.
+        async applyTagsEverywhere ({ fieldId, add, remove }) {
+            const monthsTouched = E.applyTagsAcrossMonths(ctx.db.data, fieldId, add || [], remove || null);
+            await persist();
+            return { rev: ctx.db.data.meta.rev, monthsTouched };
+        },
+
+        async listBackups () {
+            return { backups: listBackups(ctx.dbPath) };
+        },
+
+        async restoreBackup ({ name }) {
+            const source = backupPath(ctx.dbPath, name);
+            if (!fs.existsSync(source)) throw new Error('Backup not found.');
+            backupDb(ctx.dbPath, 'pre-restore');
+            fs.copyFileSync(source, ctx.dbPath);
+            ctx.db = await openDb(ctx.dbPath);
+            await persist(); // bump rev so other sessions detect the change
+            return snapshot();
+        },
+
+        // Phase 2 of legacy import (folder picking is transport-specific).
+        async migrateLegacy ({ folder, overrides }) {
+            if (!folder) return { imported: false };
+            const { data, summary } = importLegacy(folder, overrides || {});
+            backupDb(ctx.dbPath, 'pre-import');
+            data.meta.rev = E.num(ctx.db.data.meta.rev); // persist() bumps it
+            data.settings.auth = ctx.db.data.settings.auth; // password survives an import
+            if (!data.settings.auth) delete data.settings.auth;
+            ctx.db.data = data;
+            await persist();
+            return { ...snapshot(), imported: true, summary };
+        },
+
+        // ------------------------------------------------------ app password
+
+        authHas () {
+            return { hasPassword: !!(ctx.db.data.settings && ctx.db.data.settings.auth) };
+        },
+
+        authVerify ({ password }) {
+            return { valid: verifyPassword(password, ctx.db.data.settings.auth) };
+        },
+
+        // Set / change / remove (next = empty). Changing or removing requires
+        // the current password.
+        async authSet ({ current, next }) {
+            const auth = ctx.db.data.settings.auth;
+            if (auth && !verifyPassword(current || '', auth)) {
+                throw new Error('Current password is incorrect.');
+            }
+            if (next) ctx.db.data.settings.auth = hashPassword(next);
+            else delete ctx.db.data.settings.auth;
+            await persist();
+            return { hasPassword: !!next, rev: ctx.db.data.meta.rev };
+        },
+    };
+}

package/src/main/auth.js

@@ -0,0 +1,29 @@
+/*
+ * App-password hashing: node's built-in scrypt, no dependencies. The hash
+ * lives in db.json settings.auth so it travels with the data (desktop lock
+ * and web login share one password). Threat model is casual privacy - anyone
+ * with filesystem access to db.json can read the data regardless.
+ */
+'use strict';
+
+import crypto from 'node:crypto';
+
+const SCRYPT = { N: 16384, r: 8, p: 1 };
+const KEYLEN = 64;
+
+export function hashPassword (password) {
+    const salt = crypto.randomBytes(16);
+    const hash = crypto.scryptSync(String(password), salt, KEYLEN, SCRYPT);
+    return { v: 1, salt: salt.toString('hex'), hash: hash.toString('hex') };
+}
+
+export function verifyPassword (password, auth) {
+    if (!auth || !auth.salt || !auth.hash) return false;
+    try {
+        const hash = crypto.scryptSync(String(password), Buffer.from(auth.salt, 'hex'), KEYLEN, SCRYPT);
+        const expected = Buffer.from(auth.hash, 'hex');
+        return hash.length === expected.length && crypto.timingSafeEqual(hash, expected);
+    } catch {
+        return false;
+    }
+}

package/src/main/backup.js

@@ -0,0 +1,48 @@
+import path from 'node:path';
+import fs from 'node:fs';
+
+const KEEP = 20;
+
+export function backupsDir (dbPath) {
+    return path.join(path.dirname(dbPath), 'backups');
+}
+
+/** Copy db.json to backups/db-<timestamp>.json before a risky write. Keeps last 20. */
+export function backupDb (dbPath, reason = 'backup') {
+    if (!fs.existsSync(dbPath)) return null;
+    const dir = backupsDir(dbPath);
+    fs.mkdirSync(dir, { recursive: true });
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+    const name = `db-${stamp}-${reason}.json`;
+    fs.copyFileSync(dbPath, path.join(dir, name));
+    prune(dir);
+    return name;
+}
+
+function prune (dir) {
+    const files = fs.readdirSync(dir)
+        .filter((f) => f.startsWith('db-') && f.endsWith('.json'))
+        .sort();
+    while (files.length > KEEP) {
+        fs.unlinkSync(path.join(dir, files.shift()));
+    }
+}
+
+export function listBackups (dbPath) {
+    const dir = backupsDir(dbPath);
+    if (!fs.existsSync(dir)) return [];
+    return fs.readdirSync(dir)
+        .filter((f) => f.startsWith('db-') && f.endsWith('.json'))
+        .sort()
+        .reverse()
+        .map((name) => {
+            const stat = fs.statSync(path.join(dir, name));
+            return { name, size: stat.size, mtime: stat.mtime.toISOString() };
+        });
+}
+
+export function backupPath (dbPath, name) {
+    // guard against path escape - only bare filenames from listBackups are valid
+    if (path.basename(name) !== name) throw new Error('Invalid backup name');
+    return path.join(backupsDir(dbPath), name);
+}

package/src/main/db-open.js

@@ -0,0 +1,77 @@
+/*
+ * Electron-free database opener + lazy migrations, shared by the Electron
+ * main process (storage/local.js), the web server, and the dev preview
+ * server - one place for healing logic instead of three copies.
+ */
+'use strict';
+
+import path from 'node:path';
+import fs from 'node:fs';
+import { Low } from 'lowdb';
+import { JSONFile } from 'lowdb/node';
+import '../shared/engine.js';
+
+const E = globalThis.FinEngine;
+
+export function currentMonthKey () {
+    const d = new Date();
+    return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}`;
+}
+
+/** Open (creating with default data if missing) the lowdb database at dbPath. */
+export async function openDb (dbPath) {
+    fs.mkdirSync(path.dirname(dbPath), { recursive: true });
+    const db = new Low(new JSONFile(dbPath), null);
+    await db.read();
+    if (!db.data || !db.data.meta) {
+        db.data = E.defaultData(currentMonthKey());
+        await db.write();
+    }
+    // lazy migration: seed initialSavings from the first month for older dbs
+    if (db.data.settings && db.data.settings.initialSavings === undefined) {
+        const first = E.monthKeys(db.data)[0];
+        db.data.settings.initialSavings = first ? E.num(db.data.months[first].startingSavings) : 0;
+        await db.write();
+    }
+    // heal budgetIds corrupted by the option-value fallback bug ("-" committed
+    // as the link target): truthy-but-dangling placeholder text → unlinked
+    let healed = 0;
+    for (const key of E.monthKeys(db.data)) {
+        for (const f of E.allFields(db.data.months[key])) {
+            if (f.budgetId === '-' || f.budgetId === '') { f.budgetId = null; healed += 1; }
+        }
+    }
+    if (healed) {
+        console.log(`[db] healed ${healed} dangling budget link(s)`);
+        await db.write();
+    }
+    // lazy migration: return-to-income lines no longer carry the auto tag,
+    // and their label prefix gained the word "budget"
+    let returns = 0;
+    for (const key of E.monthKeys(db.data)) {
+        for (const f of E.allFields(db.data.months[key])) {
+            if (!f.returnedFrom) continue;
+            let touched = false;
+            if ((f.tags || []).includes('returned-budget')) {
+                f.tags = f.tags.filter((t) => t !== 'returned-budget');
+                touched = true;
+            }
+            if ((f.label || '').startsWith('Returned from: ')) {
+                f.label = 'Returned from budget: ' + f.label.slice('Returned from: '.length);
+                touched = true;
+            }
+            if (touched) returns += 1;
+        }
+    }
+    if (returns) {
+        console.log(`[db] migrated ${returns} return-to-income line(s)`);
+        await db.write();
+    }
+    // lazy migration: months know their own key (scheduled goals need it)
+    let stamped = 0;
+    for (const key of E.monthKeys(db.data)) {
+        if (db.data.months[key].key !== key) { db.data.months[key].key = key; stamped += 1; }
+    }
+    if (stamped) await db.write();
+    return db;
+}