You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
**Verification (local):**`npm run lint`, `npm run test` (81/81), `npx playwright install chromium`, `npm run test:e2e` (2/2, from `apps/money-mirror`); `npm run check:all` (repo root); `npm run db:upgrade` (success — Neon via `.env.local`).
10
+
11
+
**Learnings / corrections:** (1) **`db:upgrade` script shape** — an initial version used top-level `await`, which breaks `tsx`/`esbuild` execution; wrapping the script in `main()` fixed `npm run db:upgrade` (see earlier 2026-04-06 changelog entry). (2) **Schema drift vs “app bug”** — Neon DBs created before Phase 3 columns can throw Postgres `42703` (undefined column); API routes return `code: SCHEMA_DRIFT` with `SCHEMA_UPGRADE_HINT` so operators run `npm run db:upgrade` or rely on auto DDL on server boot (unless `MONEYMIRROR_SKIP_AUTO_SCHEMA=1`). (3) **No PM-pasted mistake list in this session** — additional bullets can be appended to `project-state.md` Decisions Log under the same date if needed.
12
+
13
+
---
14
+
15
+
## 2026-04-06 — MoneyMirror: `db:upgrade` + schema drift API hints
16
+
17
+
**App:**`apps/money-mirror`
18
+
19
+
**What:** Idempotent `npm run db:upgrade` (`scripts/apply-schema-upgrades.ts`, shared `applyIdempotentSchemaUpgrades` in `src/lib/schema-upgrades.ts`) adds `merchant_key` + partial index and statement label columns when missing. `GET /api/transactions` and `GET /api/insights/merchants` return `code: SCHEMA_DRIFT` with upgrade instructions on Postgres undefined-column errors; Transactions tab and `MerchantRollups` surface `detail` for that code. Dev dependency: `tsx`.
20
+
21
+
**Follow-up:**`runAutoSchemaUpgradeOnBoot` (`src/lib/run-schema-upgrade-on-boot.ts`) runs the same DDL from `instrumentation.ts` on Node server start when `DATABASE_URL` is set (opt out with `MONEYMIRROR_SKIP_AUTO_SCHEMA=1`). UI shows a single PM-friendly paragraph for `SCHEMA_DRIFT` (no duplicated title + hint). **Docs:**`docs/SCHEMA-DRIFT.md` (RCA + local verification).
22
+
23
+
**Fix:**`scripts/apply-schema-upgrades.ts` — wrap in `main()` (no top-level `await`) so `tsx`/`esbuild` can run `npm run db:upgrade`.
|`NEON_AUTH_BASE_URL`| Yes | Base URL for your Neon Auth project |
58
+
|`NEON_AUTH_COOKIE_SECRET`| No | Optional only if Neon explicitly gives one for your project/runtime |
59
+
|`GEMINI_API_KEY`| Yes | Google AI Studio API key |
60
+
|`RESEND_API_KEY`| Yes | Resend API key |
61
+
|`POSTHOG_KEY`| Yes | Server-side PostHog key |
62
+
|`POSTHOG_HOST`| Yes | PostHog host URL |
63
+
|`NEXT_PUBLIC_POSTHOG_KEY`| No | Same key as `POSTHOG_KEY` — enables client `web_vital` (CWV) events |
64
+
|`NEXT_PUBLIC_POSTHOG_HOST`| No | Defaults to `https://app.posthog.com` if unset |
65
+
|`NEXT_PUBLIC_APP_URL`| Yes | Public app URL used in recap links |
66
+
|`CRON_SECRET`| Yes | Shared secret for cron routes |
67
+
|`NEXT_PUBLIC_SENTRY_DSN`| No | Client Sentry DSN — optional locally if you skip browser reporting |
68
+
|`SENTRY_AUTH_TOKEN`| Yes\*|\*Required for production builds that upload source maps to Sentry |
69
+
|`SENTRY_ORG`| No | Optional locally — used by Sentry CLI / webpack plugin for releases |
70
+
|`SENTRY_PROJECT`| No | Optional locally — same as above |
71
+
|`CI`| No | Optional CI build flag |
72
+
|`MONEYMIRROR_SKIP_AUTO_SCHEMA`| No | Set to `1` to skip automatic idempotent DDL on server boot (`instrumentation.ts`); default is to run when `DATABASE_URL` is set |
70
73
71
74
### 3. Create Neon project and enable Neon Auth
72
75
@@ -81,6 +84,18 @@ Fill in these values:
81
84
82
85
Run the full contents of [`schema.sql`](./schema.sql) against your Neon database.
83
86
87
+
**Already have a DB from before Phase 2 / Phase 3?** Your `transactions` table may be missing `merchant_key` (and related indexes), which breaks the Transactions tab and merchant insights. From this app directory, with `DATABASE_URL` in `.env.local`:
88
+
89
+
```bash
90
+
npm run db:upgrade
91
+
```
92
+
93
+
That runs idempotent `ALTER TABLE … ADD COLUMN IF NOT EXISTS` and `CREATE INDEX IF NOT EXISTS` statements (same as the tail of `schema.sql`). Safe to run multiple times.
94
+
95
+
**Automatic upgrades on server start:** When the Node server boots (`next dev` / `next start` / Vercel), MoneyMirror runs the same idempotent DDL once if `DATABASE_URL` is set and `MONEYMIRROR_SKIP_AUTO_SCHEMA` is not `1`. After pulling new code, **restart the dev server** so this runs; you usually do not need a separate migration step for missing `merchant_key` on Neon.
96
+
97
+
Full **root cause, verification steps, and opt-out** for schema drift: [`docs/SCHEMA-DRIFT.md`](./docs/SCHEMA-DRIFT.md).
**Dev server: `uv_interface_addresses` / `getNetworkHosts` warning** — In some restricted environments Next may log an unhandled rejection while resolving the LAN URL; the app often still serves on `http://localhost:3000`. Use `npm run dev:loopback` to bind only to `127.0.0.1` and avoid that code path, or run the dev server outside a sandbox.
|`npm run test`| Vitest — API routes, libs, parsers |
143
+
|`npm run test:e2e`| Playwright — builds, serves on port **3333**, smoke-tests `/` and `/login`|
144
+
145
+
First-time E2E setup: `npx playwright install chromium`. See [`docs/PERFORMANCE-REVIEW.md`](./docs/PERFORMANCE-REVIEW.md) for Lighthouse and performance notes.
146
+
147
+
Optional: set `NEXT_PUBLIC_POSTHOG_KEY` (same project as `POSTHOG_KEY`) to send **Core Web Vitals** (`web_vital` events) from the browser.
148
+
121
149
## API
122
150
123
151
### `POST /api/onboarding/complete`
@@ -179,7 +207,7 @@ Returns all processed statements for the authenticated user, sorted by creation
179
207
180
208
### `GET /api/dashboard`
181
209
182
-
Returns the full dashboard state for the authenticated user (Overview aggregates + generated advisories + optional `coaching_facts` Layer A JSON + Gemini-enriched `narrative` / `cited_fact_ids` on each advisory when AI succeeds).
210
+
Returns the full dashboard state for the authenticated user (Overview aggregates + generated advisories + optional `coaching_facts` Layer A JSON). **Does not** call Gemini — responses are fast for Overview and Transactions. Rule-based advisory copy is returned immediately.
183
211
184
212
**Auth**: Neon Auth session cookie required.
185
213
@@ -190,7 +218,7 @@ Returns the full dashboard state for the authenticated user (Overview aggregates
190
218
191
219
### `GET /api/dashboard/advisories`
192
220
193
-
Same query parameters as `GET /api/dashboard`. Returns `{ advisories, coaching_facts }` (same shapes as the parent dashboard payload).
221
+
Same query parameters as `GET /api/dashboard`. Returns `{ advisories, coaching_facts }`. This endpoint runs the **Gemini coaching narrative** step (can take up to ~9s) and is what the **Insights** tab calls after the fast dashboard load.
-[`docs/COACHING-TONE.md`](./docs/COACHING-TONE.md) — Coaching language guide: consequence-first nudge patterns, Layer A facts-only numerics, Gemini narrative guardrails, tone constraints for advisory copy.
0 commit comments