Skip to content
4 changes: 3 additions & 1 deletion .gitignore
Original file line number Diff line number Diff line change
@@ -1,8 +1,10 @@
# Financial data — never commit real transaction exports or backups
data/
finlens-data.json
# State backup (all transactions + settings) — ignored wherever the CSV folder lives
# State backup (all transactions + settings), plus copies archived by "Start over" —
# ignored wherever the CSV folder lives
finlens-state.json
finlens-state-backup-*.json
# Settings exports and saved AI analyses
finlens-export-*.json
finlens-analysis-*.md
Expand Down
42 changes: 42 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,48 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).

---

## [1.9.0] — 2026-10-23

### Settings → 🧹 Data & Reset (new tab, `views-cleanup.js`)
- **One place for all cleanup.** The Danger Zone moved here from General, which now keeps Display and the API key plus a link to the new tab.
- **Imported data & database:**
- Clear imported transactions & accounts (memory + `transactions`/`accounts` stores). Plans, edits, account names and balances are kept.
- **Clearing sticks across reloads.** With a folder connected, boot used to re-import its CSVs into the empty database, so cleared transactions came back on F5. Clearing now sets `csvAutoImportPaused` (browser storage only), which skips that boot re-import. Any import you start ends the pause: Reload or Reconnect, Rebuild, picking a folder or files, Disconnect and Start over. The tab and Settings → Import both say when it's paused.
- Clear the import log.
- Clear transaction edits (also rebuilds the loaded transactions without overrides).
- Each row shows live counts from memory and IndexedDB.
- **Rebuild from folder** — clears imported transactions, accounts and the import log, then re-imports every CSV in the connected folder. It fixes a messy database without touching plans.
- **Plans & history** — clear budgets, bills, savings buckets, debts or AI history individually.
- **CSV folder & backup file** — disconnect the folder (FinLens forgets the handle; nothing on disk changes).
- **Start over from scratch:**
- Type `RESET` to erase everything: both IndexedDB databases, all `finlens_*` localStorage keys (including the API key), the folder connection, then reload.
- `finlens-state.json` is either renamed to `finlens-state-backup-DDMMYYYY.json` (API key stripped; a second reset the same day gets `-2`, `-3`, … so no copy is overwritten) or deleted, so reconnecting the folder later starts fresh.
- CSV files are never touched.
- **Safer confirmations** — destructive buttons use click-again-to-confirm, so the folder-permission prompt that may follow gets a fresh user gesture. An alert can't outlast the browser's activation window.

### Display — readable secondary text (all views)
- **Darker gray text.** `--text-3` (descriptions, counts, footnotes, `.muted`) was `#94A3B8` on white, about 2.5:1 contrast. It's now `#5B6B80` in light mode and `#8190A6` in dark mode, at least 4.7:1 on every surface (WCAG AA). One token change, so it applies to every tab.
- **Sidebar.** Group headers, the brand subtitle and the version footer used hard-coded `#475569`/`#64748b` (2.3–3.6:1 on the sidebar). They now share a new `--sidebar-muted` token (`#94A3B8`, 6.7:1).
- **Charts.** Axis labels and legends used Chart.js's default `#666`, which was hard to read in dark mode. `applyTheme()` now sets `Chart.defaults.color` to `--text-2`.

### Fixed
- **"Clear All Data" didn't clear anything.** `clearAllData()` only removed localStorage keys, so on reload `DB.loadAll()` (and `finlens-state.json`) restored every transaction, budget and setting. It now runs the full Start over.
- **Cleared data could come back on reload.** The state file is loaded first at boot but was only rewritten by the 5-second debounced save, so a quick reload restored it. Clearing now writes it immediately via `saveStateNow()`, and warns if write access is refused.
- **Clearing transactions left empty account cards.** The `accounts` store is now cleared too, and the account filter is rebuilt.
- **"Pick CSV Files" landed on Overview.** `handleFilePick()` showed the non-existent `db-import` view, which hid the file-assignment card. It now opens Settings → Import.
- **`finlens_fs` connections were never closed.** `idbGet`/`idbSet`/`idbDel` now close them, so the database can be deleted.
- **Other tabs could block a reset.** `DB.open()` now releases the connection on `versionchange`.

### Technical
- **New `DB` methods:** `STORES`, `counts()`, `clearStores(names)`, `destroy()`.
- **New `core.js` helpers:** `lsClearAll()`, `deleteIndexedDB()`, `folderWithWriteAccess()`, `saveStateNow()`, `retireStateFile()`, `forgetDataFolder()`.
- **Auto-save guard:** `saveStateToFile()` does nothing while `State._resetInProgress` is set.
- **Disabled-button style:** new `.btn:disabled` rule.
- **`.gitignore`:** also ignores `finlens-state-backup-*.json`.
- **Docs:** CLAUDE.md §20 documents where data lives and the cleanup rules; README tip on cleaning up and starting over.

---

## [1.8.1] — 2026-10-23

### Fixed (Technical)
Expand Down
78 changes: 67 additions & 11 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@

FinLens is a **single-origin, zero-build, vanilla JavaScript personal finance dashboard** that runs entirely in the browser. There is no server, no npm, no bundler, no framework, and no TypeScript. The entry point is `index.html`; everything else is a plain `.js` file in the `js/` folder.

**Current version:** v1.8.1 (updated in `index.html` footer, `README.md`, and `CHANGELOG.md` on every release).
**Current version:** v1.9.0 (updated in `index.html` footer, `README.md`, and `CHANGELOG.md` on every release).

**What it does:** Imports CSV exports from Ally Bank (Checking + Savings) and Chase credit cards, parses and normalizes them into a unified transaction model, and renders a multi-tab financial dashboard with budgeting, debt tracking, savings forecasting, investment planning, and Claude-powered AI analysis.

Expand Down Expand Up @@ -65,7 +65,8 @@ FinLens/
├── views-forecast.js ← Forecast Savings + Forecast Investments tabs
├── views-ai.js ← AI Analysis tab (Claude integration)
├── views-data.js ← Import, Accounts, Credit Cards, Categories (Settings tabs) + Import Logs
├── views-settings.js ← Settings shell + General tab (display, Anthropic API key, danger zone)
├── views-settings.js ← Settings shell (tab bar) + General tab (display, Anthropic API key)
├── views-cleanup.js ← Settings → Data & Reset: clean up imported data, DB, logs; start over (§20)
├── views-db.js ← DB Schema diagram, DB Inspector, Changelog views (developer only)
├── views-database.js ← Unused — not loaded by index.html; retained for reference
└── init.js ← App boot IIFE — event wiring, DB.open(), DB.loadAll(), first render
Expand All @@ -76,7 +77,7 @@ FinLens/
```
core.js → aggregation.js → db.js → ui.js → views-main.js → views-plan.js → views-invest.js
→ views-forecast.js → views-ai.js → views-data.js
→ views-settings.js → views-db.js → init.js
→ views-settings.js → views-cleanup.js → views-db.js → init.js
```

All scripts share the **global `window` scope**. A function defined in `core.js` is callable in any `views-*.js` without import statements.
Expand Down Expand Up @@ -113,6 +114,7 @@ const State = {
fileMeta: [], // Metadata about loaded CSV files
pendingFiles: [], // Files awaiting account assignment
lastFolderName: '',
csvAutoImportPaused: false, // true after "Clear transactions & accounts" with a folder connected (§20)
fileAssignments: {}, // { [filename]: kind }
accountOrder: [], // [accountId, ...] — user-defined display order
currentView: 'overview',
Expand Down Expand Up @@ -244,7 +246,7 @@ All CSS lives in a single `<style>` block in `index.html`. There are no external

```css
/* Light theme (default) */
--sidebar, --sidebar-2, --sidebar-text, --sidebar-text-active
--sidebar, --sidebar-2, --sidebar-text, --sidebar-text-active, --sidebar-muted
--bg, --surface, --surface-2, --border
--text, --text-2, --text-3
--teal (#00C49A), --teal-soft
Expand All @@ -256,6 +258,8 @@ All CSS lives in a single `<style>` block in `index.html`. There are no external

Dark mode is applied by setting `data-theme="dark"` on `<html>` and overriding the surface/text tokens only. **Never hard-code colors** — always use a CSS variable.

**Text contrast:** every text token must reach at least 4.5:1 (WCAG AA) on `--surface`, `--bg` and `--surface-2` in both themes. `--text-3` is the lightest allowed text color, so never fade text below it with `opacity`. Chart.js labels follow `--text-2` through `applyTheme()`.

### Key CSS component classes

```
Expand Down Expand Up @@ -352,6 +356,14 @@ hash(str) // Deterministic 'tx' + base36 hash for transaction I
escapeHtml(str) // Escape HTML entities for safe innerHTML insertion
escapeAttr(str) // Escape for use in HTML attribute strings
renderMarkdown(md) // marked → DOMPurify (no images/styles/forms) → safe HTML string; escaped-text fallback
lsClearAll() // Remove every finlens_* localStorage key — only "Start over" should call it
deleteIndexedDB(name) // Delete a whole IndexedDB database → 'deleted' | 'blocked' | 'error'

// Folder + state-file maintenance (call from a click handler — permission prompts need a user gesture)
folderWithWriteAccess() // Connected folder handle with read-write access, or null
saveStateNow() // Write finlens-state.json immediately → 'saved' | 'no-folder' | 'denied'
retireStateFile(mode) // 'archive' (→ finlens-state-backup-DDMMYYYY[-n].json, key stripped) | 'delete'
forgetDataFolder() // Forget the folder handle + name; nothing on disk changes
downloadFile(name, content, mime) // Trigger browser file download
debounce(fn, ms) // Returns debounced function
parseDate(s) // Parse date string/object → Date | null
Expand Down Expand Up @@ -394,7 +406,8 @@ editBucket(i), saveBucket(i), deleteBucket(i)
editDebt(i), saveDebt(i), deleteDebt(i), simulatePayoff(debts, extra)
confirmRecurring(...), dismissRecurring(key)
addCatRule(), delCatRule(i), recategorizeAll()
exportAllData(), importJsonFile(ev), clearAllData()
exportAllData(), importJsonFile(ev)
clearAllData() // = DataCleanup.startOver('archive') — full reset + reload (§20)
```

---
Expand Down Expand Up @@ -534,8 +547,8 @@ Plan: budgets, buckets, debt, investments, forecast
└─ Forecast has sub-tabs: Savings · Investments
Insights: trends, ai
⚙️ Settings ← standalone nav link, no section wrapper, no sub-items in sidebar
└─ Settings page has internal tabs: General · Import · Accounts · Credit Cards · Categories
(General holds Display, Anthropic API Key and Danger Zone)
└─ Settings page has internal tabs: General · Import · Accounts · Credit Cards · Categories · Data & Reset
(General holds Display and Anthropic API Key; all clearing/reset lives in Data & Reset)
```

View registrations by file:
Expand All @@ -546,6 +559,7 @@ View registrations by file:
- `views-ai.js` — ai
- `views-data.js` — import, accounts, credit-cards, categories
- `views-settings.js` — settings (internal use only, not in nav)
- `views-cleanup.js` — data-cleanup (Settings → Data & Reset tab)
- `views-db.js` — db-inspector, db-schema, changelog (not in nav; developer reference only)

The `data-section` attribute values are `finances`, `plan`, `insights` — the toggle JS derives section IDs as `ns-{data-section}`. Settings is a standalone `<a class="nav">` link at the bottom of the sidebar (no section wrapper, no sub-items).
Expand Down Expand Up @@ -605,7 +619,7 @@ The old `FileStorage` object and `finlens-data.json` were removed in v1.4.1.

`views-data.js` stores the user's selected CSV folder handle in `idbGet`/`idbSet('csvDirHandle')`. That one handle is used for two things:

1. **Auto-reloading CSVs** after a page refresh when IndexedDB has no transactions.
1. **Auto-reloading CSVs** after a page refresh when IndexedDB has no transactions, unless `State.csvAutoImportPaused` is set (§20).
2. **The state file** — `loadStateFromFile()` / `saveStateToFile()` read and write `finlens-state.json` in the same folder (the primary persistence source, §4.5).

The handle lives in a separate `finlens_fs` database (distinct from `finlens_db`), accessed through the lightweight `_idbOpen`/`idbGet`/`idbSet`/`idbDel` helpers in `core.js`. `finlens-state.json` is git-ignored by name, wherever the folder is.
Expand All @@ -625,7 +639,9 @@ The handle lives in a separate `finlens_fs` database (distinct from `finlens_db`
- **Do not create new global variables** — use `const`/`let` at module scope where possible, or attach to an existing namespace object.
- **Do not write secrets to disk** — `apiKey` must never appear in `finlens-state.json`, exports, or logs.
- **Do not call `marked.parse()` directly** — use `renderMarkdown()`.
- **Do not commit real financial data** — use `samples/` (synthetic) for demos; `data/`, `finlens-state.json` and exports are git-ignored.
- **Do not commit real financial data** — use `samples/` (synthetic) for demos; `data/`, `finlens-state.json` (and its `finlens-state-backup-*` copies) and exports are git-ignored.
- **Do not add a new place that stores data without updating §20** — "Start over" must erase it, or a reset silently leaves data behind.
- **Do not modify the user's CSV files** — cleanup and reset only ever touch FinLens's own storage and `finlens-state.json`.

---

Expand Down Expand Up @@ -685,7 +701,7 @@ Bump the patch version for bug fixes, minor version for new features, major vers
**On every version bump, all four of these must be updated — no exceptions:**

1. `CHANGELOG.md` — new entry at the top with the new version number and date.
2. `index.html` — version string in the sidebar footer (search for `· FinLens`); currently on line ~325:
2. `index.html` — version string in the sidebar footer (search for `· FinLens`); currently on line ~326:
```html
<div style="color:var(--text-3);font-size:11px">vX.Y.Z · FinLens</div>
```
Expand All @@ -709,7 +725,7 @@ Multiple Chase card files can be loaded simultaneously. Each gets a unique `acco

---

*Last updated: v1.8.1 — 2026-10-23 (§10 re-upload dedup rewritten for the occurrence-suffix fix; v1.8.0: AI Analysis restored with API-key and output hardening; `renderMarkdown()` added; `samples/` added; §1–3, §13, §14, §17 corrected to match the code)*
*Last updated: v1.9.0 — 2026-10-23 (§20 Data & Reset added; v1.8.1: §10 re-upload dedup rewritten for the occurrence-suffix fix; v1.8.0: AI Analysis restored with API-key and output hardening; `renderMarkdown()` added; `samples/` added; §1–3, §13, §14, §17 corrected to match the code)*

---

Expand All @@ -732,3 +748,43 @@ Add a new object to `BANK_SCHEMAS` in `core.js`. No other code changes needed if
### Deferred
- Column Mapping UI for truly unknown CSV formats (show a modal when `detectSchema()` returns null).
- Forecast Savings account-driven inputs (see §4 in INDEXEDDB_PLAN.md — separate task).

---

## 20. Data Cleanup & Reset (views-cleanup.js)

**Settings → 🧹 Data & Reset** is the only place that clears data. All actions live on the `DataCleanup` namespace object.

### Where FinLens keeps data

| Place | What | Cleared by |
|---|---|---|
| Memory | `State` | every action (then `renderActive()`) |
| `localStorage` | `finlens_*` keys via `lsSet`/`lsGet` (plus `finlens_navCollapsed`) | per-item `lsSet(key, [])`; Start over → `lsClearAll()` |
| IndexedDB `finlens_db` | `DB.STORES`: transactions, tx_overrides, accounts, import_log, app_state | `DB.clearStores([...])`; Start over → `DB.destroy()` |
| IndexedDB `finlens_fs` | `csvDirHandle` (the connected folder) | Disconnect → `forgetDataFolder()`; Start over → `deleteIndexedDB('finlens_fs')` |
| Disk | `finlens-state.json` in the connected folder | rewritten by `saveStateNow()` after clears; Start over → `retireStateFile()` |

CSV files on disk are **never** modified.

### Actions

| Action | Does | Keeps |
|---|---|---|
| Clear transactions & accounts | Empties memory + `transactions`/`accounts` stores; with a folder connected, sets `csvAutoImportPaused` | Plans, edits, account labels/balances, settings |
| Clear import log | Empties `import_log` | Everything else |
| Clear transaction edits | `txOverrides` + `tx_overrides` store; rebuilds loaded transactions with `reconstituteTx(raw, {})` | — |
| Clear budgets / bills / buckets / debts / AI history | `State[key] = []` + `lsSet` | — |
| Rebuild from folder | Clears transactions, accounts, import log, then `reloadFromDirHandle()` | Plans, edits, settings |
| Disconnect folder | `forgetDataFolder()` — stops CSV auto-reload and state-file writes | Files on disk |
| Start over | `retireStateFile()` → forget handle → `DB.destroy()` → delete `finlens_fs` → `lsClearAll()` → alert → reload | CSV files (and a backup copy of the state file, if chosen) |

### Rules

- **Rewrite the state file after clearing anything it holds.** `finlens-state.json` is the first thing loaded at boot, so a stale file would restore cleared data. `_finish()` calls `saveStateNow()` and warns if write access was refused.
- **Clearing transactions must survive a reload.** A connected folder re-imports its CSVs at boot whenever no transactions are loaded (§14), so `clearImported()` sets `State.csvAutoImportPaused` and `init.js` skips the boot re-import while it's set.
- **Ending the pause:** `loadFiles()` clears it, so any import the user starts ends it: Reload or Reconnect, Rebuild, picking a folder or files. `forgetDataFolder()` (Disconnect) clears it too, and Start over removes it with the other keys.
- **Browser storage only:** it lives in localStorage and IndexedDB `app_state`, never in `finlens-state.json`. Saves are debounced, so a backup file written before the pause ended could otherwise switch it back on. If browser storage is wiped, the folder re-imports as a recovery.
- **Permission prompts need a fresh user gesture.** Destructive buttons use click-again-to-confirm (no `confirm()` dialog, which can outlast the ~5 s activation window), and actions ask for folder access before doing slow work.
- **Start over must leave nothing behind.** It sets `State._resetInProgress` so a pending debounced save can't re-create the file, and `DB.open()` registers `onversionchange` so other tabs release the database. `idbGet`/`idbSet`/`idbDel` close their connections so `finlens_fs` can be deleted.
- `clearAllData()` is kept as a wrapper for `DataCleanup.startOver('archive')`. Up to v1.8.1 it only cleared `localStorage`, which IndexedDB and the state file then restored on reload.
Loading