diff --git a/.env.example b/.env.example index 7e5b414..c606a8d 100644 --- a/.env.example +++ b/.env.example @@ -7,6 +7,10 @@ DATABASE_URL=postgresql://user:password@ep-example-pooler.us-east-1.aws.neon.tech/neondb?sslmode=require # Migrations only: the DIRECT string (same host without "-pooler"). DATABASE_URL_UNPOOLED=postgresql://user:password@ep-example.us-east-1.aws.neon.tech/neondb?sslmode=require +# Optional: websocket for a workspace that allows HTTPS but cannot reach +# Postgres over TCP. Leave empty for the default pg driver on deployments. +# WebSocket and storage clients honor HTTPS_PROXY and NO_PROXY (Node 24.5+). +DATABASE_TRANSPORT= # Better Auth (ADR-006). Secret: 32+ random characters, e.g. # openssl rand -base64 32 diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index c5a7a64..dfe2d6c 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -87,6 +87,7 @@ jobs: cache: pnpm - run: pnpm install --frozen-lockfile - run: pnpm db:migrate + - run: pnpm db:verify --target app - run: pnpm test:unit - uses: actions/upload-artifact@v7 if: always() @@ -129,6 +130,7 @@ jobs: - run: pnpm install --frozen-lockfile - run: pnpm exec playwright install --with-deps chromium - run: pnpm db:migrate + - run: pnpm db:verify --target app - run: pnpm build - name: Scan client bundle for secrets run: pnpm scan:bundle diff --git a/AGENTS.md b/AGENTS.md index 617b951..cb4f91e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -213,6 +213,7 @@ fails if this table and `package.json` differ. | `pnpm db:migrate` | Apply migrations (uses `DATABASE_URL_UNPOOLED` when set) | | `pnpm db:migrate:to` | Apply migrations to a named database: `local`, `branch` or `production` (ADR-049) | | `pnpm db:whoami` | Show which database a target is and which migrations it has; no secrets printed | +| `pnpm db:verify` | Read-only financial schema and SELECT-access preflight for a named target; no repairs | | `pnpm ai:check` | Ask each test model one question with the real `GEMINI_API_KEY` from `.env.local`; prints which answer. `pnpm ai:check users` asks the models that answer users, which spends their small daily allowance (ADR-059). `pnpm ai:check receipt` sends each test model a made-up receipt photo and says whether it read the total (ADR-067) | | `pnpm batch` | Synthetic batches: `load`, `list`, `report`, `delete`, `promote`, `rollup`; `give` and `take-back` for developer accounts (`docs/SYNTHETIC.md`) | | `pnpm nessie` | Nessie demo customers: `seed` a synthetic year into Nessie, `link` it to a user, `status`, and live `demo` changes (`docs/NESSIE_PLAN.md`) | @@ -266,7 +267,7 @@ src/ / built so far: accounts, agent, alerts, auth, bills, budgets, cashflow, categorization, imports, insights, landing, messaging, plans, recurring, - synthetic, transactions + synthetic, transactions, transfers domain/ pure TypeScript logic, no I/O (most unit tests here) server/ repositories, server actions ('server-only') ui/ React components for this feature diff --git a/README.md b/README.md index 37401d5..a42a94c 100644 --- a/README.md +++ b/README.md @@ -23,3 +23,25 @@ pnpm dev ``` Open http://localhost:3000. Every command is listed in AGENTS.md section 5. + +In a cloud workspace that allows HTTPS but cannot reach PostgreSQL over TCP, +set `DATABASE_TRANSPORT=websocket` in `.env.local`. The app then uses Neon's +WebSocket Pool; deployments still use `pg` when this variable is empty. The +WebSocket and storage clients honor the runtime's `HTTPS_PROXY` and `NO_PROXY` +settings on Node 24.5 or later. Migrations still use a direct TCP connection. + +Local statement imports need the five storage variables in `.env.example` +from the Neon `storage-tests` branch. Put them in `.env.local` for the app and +`.env.storage-tests` for tests. Both files are ignored by Git; tests always use +local PostgreSQL and never the production storage bucket. + +Before release, run `pnpm db:verify --target app` with the intended runtime +connection role. It checks financial schema and read access without changing +data; a successful health check or migration journal alone is insufficient. +See [database readiness](docs/DATABASE_READINESS.md) for targets, limitations +and the migrate/verify/release sequence. + +Review recorded transfers from Transactions → **Review transfers**. Choose a +specific counterpart and confirm the classification; removing a pairing keeps +the existing labels. See [transfer review](docs/TRANSFER_REVIEW.md) for the +window, limits, Bills evidence rules and the separate normal-activity action. diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index adfbb18..312bd9d 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -194,6 +194,24 @@ Caching: pages that show workspace data render dynamically. No `unstable_cache` or fetch caching of workspace data. Client state is keyed by workspace id and cleared on workspace switch and sign-out. +### Web transfer review (built, ADR-066) + +The Transactions subroute uses `features/transfers` for a bounded read-only +snapshot and explicit metadata writes. Every entry point authorizes before +financial reads; the repository scopes every row and account join by workspace. +Candidates use posted, safe integer, nonzero opposite cents on different owned +accounts within three calendar days. The UI requires a specific choice and +confirmation, including for an unambiguous suggestion. + +Review writes and ordinary transaction update/delete acquire Bills' workspace +advisory lock (seed 53) before transaction locks sorted by ID. The shared +`lib/db/transaction-guards` module checks allocated evidence without feature +dependency cycles. Pair creation validates both expected states and updates +only flags, pair IDs and timestamps. Detachment retains flags; paired financial +edits are refused; deletion keeps its balance undo and detaches surviving owned +rows. Account deletion keeps its cascade; remaining orphans are reviewed +explicitly. Labels cannot change allocated Bills snapshots before unlinking. + ## ARCH-05: Import pipeline Governed by: ADR-009, ADR-010, ADR-012, ADR-020, ADR-025, ADR-044 @@ -248,6 +266,11 @@ Governed by: ADR-014, ADR-018, ADR-026, ADR-042 4. The headline, day panel and accessible labels come from the same results, so the visual and the text can never disagree. +Liquid recorded transfer movements are kept as `balanceOnly` entries for the +calendar's opening and daily balance calculation. They never enter activity, +income, spending or recurring totals. Thus classification changes totals while +preserving the balance line, including transfers posted on different days. + ## ARCH-07: AI layer Governed by: ADR-019, ADR-045, ADR-059 @@ -304,6 +327,7 @@ Governed by: ADR-006, ADR-007, ADR-010, ADR-012, ADR-019, ADR-025 | Variable | Used by | Secret | |---|---|---| | `DATABASE_URL` | Drizzle at runtime, through `pg` (Neon's pooled connection string in production) | Yes | +| `DATABASE_TRANSPORT` | Optional: `websocket` uses Neon's serverless Pool and Drizzle's matching driver where TCP is unavailable. Empty or `tcp` keeps `pg`. Test runners always use `tcp` with local PostgreSQL | No | | `DATABASE_URL_UNPOOLED` | Drizzle Kit migrations only (Neon's direct connection string); optional, falls back to `DATABASE_URL` | Yes | | `BETTER_AUTH_SECRET` | Better Auth | Yes | | `BETTER_AUTH_URL` | Better Auth | No | @@ -381,6 +405,12 @@ deletes or rewrites data needs its own ADR. - **`pnpm db:whoami [--target app|local|branch|production]`** prints the endpoint id, the database it recognises, the migrations applied and pending, and the synthetic batch count. It never prints a password. +- **`pnpm db:verify --target app|local|branch|production`** checks the + financial-page schema contract and zero-row SELECT access independently + of journal timestamps. CI runs it against its disposable service after + migrations. The [release procedure](DATABASE_READINESS.md) also requires + the intended runtime role and real-page smoke tests; the CLI does not gate + an independent auto-deployment or repair schema. **Drizzle's rule:** it applies every migration newer than the newest one recorded. If a migration is regenerated after it was applied somewhere, that diff --git a/docs/DATABASE_READINESS.md b/docs/DATABASE_READINESS.md new file mode 100644 index 0000000..e49cb78 --- /dev/null +++ b/docs/DATABASE_READINESS.md @@ -0,0 +1,62 @@ +# Database readiness before release + +Run `pnpm db:verify --target app|local|branch|production` from the repository +root. It prints the selected endpoint and database without a connection URL, +then checks this checkout's bounded financial-page contract. It does not +repair schema, apply migrations, read financial rows or change `/api/health`. + +The contract covers Accounts, Transactions, statement-import references, +Categorization, Recurring payments, Budgets and Bills. Required columns come +from their current Drizzle tables, including transfer flags/pair IDs and Bills +evidence. Workspace/user references are limited to their IDs. Column types +and nullability, valid unconditional uniqueness and validated foreign-key +ownership/reference semantics must match. Constraint names and compatible +additional objects do not matter. This is not a complete database diff or a +validation of every auth, agent or calendar object. + +Each required table is checked with a zero-row SELECT of the required columns +under the selected role. Write privileges, row-level-security policies, +defaults, arbitrary check expressions and stored data correctness are not +verified. No INSERT, UPDATE, DELETE or DDL probe runs. Checks use a read-only +repeatable-read transaction, a ten-second connection/client-query timeout, +five-second statement timeout and two-second lock timeout; the client closes +on success and failure. Permission, connection/query and required-schema +failures exit nonzero. A missing or inaccessible migration journal is a +diagnostic warning, as are unrecorded or newer migration timestamps. + +For example, 0012 may have recovered `budget` while the original 0010 timestamp +is absent. Compatible schema passes with that journal warning. Conversely, +SELECT 1 and a fully populated journal do not make a missing table ready. +Use `pnpm db:whoami --target ` and the migration SQL to investigate; +do not replay migrations or rewrite history based on a warning alone. + +## Release sequence + +1. Identify the intended database and both runtime/migration connection roles. + `app` selects `DATABASE_URL`; `production` prefers + `DATABASE_URL_UNPOOLED`, which may have a more privileged role. Inspect + the secret-safe target display and use the existing named-target guard + for authorized production writes (ADR-049). +2. If a migration is needed, apply the reviewed migrations before traffic + reaches the new app version. Never infer production success from a local + migration. Migrations continue to require a direct TCP connection. +3. Run `pnpm db:verify --target app` using the intended runtime URL and app + role. A pass with the migration role alone does not establish app access. + A read-only check of the named deployment target is useful additionally. + In this HTTPS-only cloud workspace the verifier can use the user-selected + `DATABASE_TRANSPORT=websocket`; it honors inherited proxy/CA settings. +4. Release and smoke-test the real financial pages with the intended app + connection. Preserve any environment-blocked checks in the handoff. + +CI's existing unit and E2E PostgreSQL jobs run the verifier after migration +with `--target app`, selecting their service on port 5432. `--target local` +selects Docker's port 5433. These are disposable CI databases, not production +verification. The CLI does not prevent a separate Vercel auto-deployment: +the team's release process must actually run this check before deployment. +No page gate, public endpoint, startup migration or offline-build database +dependency is introduced. + +Fault tests create separate local databases. They never remove shared-suite +tables or production objects, and cover healthy SELECT 1 with missing schema, +column/type/nullability faults, ownership/uniqueness, read permissions, +compatible extras, journal discrepancies and command-level secret redaction. diff --git a/docs/DECISIONS.md b/docs/DECISIONS.md index 73398a8..6c999de 100644 --- a/docs/DECISIONS.md +++ b/docs/DECISIONS.md @@ -2325,3 +2325,30 @@ Rules: delivery are unchanged. No worker, messaging, AI, cron, job, notification preferences or dashboard integration is implemented here. Those integrations must explicitly adopt these invoice semantics if they consume the public API. + +### ADR-066: Explicit web transfer review and reversible pair relationships + +- **Status:** Accepted (2026-10-11), user authorized the supplied implementation plan. +- **Context:** Imported repayments can be counted twice. Transfer labels have + no provenance, and Bills evidence snapshots include the transfer flag. +- **Decision:** Review existing transactions on a Transactions subroute. + Suggest equal/opposite posted amounts on different owned accounts within + three calendar days (ADR-020); the user chooses and confirms every pair. + Review reads never classify automatically; this feature adds no import hook. + Pair exactly two rows atomically. + Remove pairing clears only the relationship and keeps each transfer label; + counting standalone rows as normal activity is a separate explicit action. + Legacy/orphan groups remain visible and require explicit detachment, with + no ownership inferred from pair IDs and no automatic repair on reads. + Classification changes no ledger fact or recorded balance. Serialize writes + with Bills' workspace advisory lock before deterministic transaction locks. + Reject stale/competing forms and flag changes on allocated payment evidence. + Paired financial fields/flags cannot be edited until detachment; deletion + preserves the existing balance undo and detaches surviving owned members. +- **Consequences:** Reuse existing transfer fields with no migration. Removing + pairing alone does not return amounts to spending/income. Bill evidence must + be explicitly unlinked before reclassification; labelled debt repayments + may gain/lose a relationship without changing that evidence. Default review + covers 90 days with explicit bounded older-date/account navigation. + The user approved the focused cashflow correction: liquid transfer amounts + move historical and daily balances without becoming spending or income. diff --git a/docs/HANDOFF.md b/docs/HANDOFF.md index 34b7a48..fa9cb89 100644 --- a/docs/HANDOFF.md +++ b/docs/HANDOFF.md @@ -4159,3 +4159,190 @@ rows", transactions 2 "show more" in steps of 20, plus a view-only list. there are digits on the lock screen, but never an amount. - The weekly recap and stale Nessie syncs are not on the tick yet. - Previews in the iOS lock screen were not tested with a real phone. + +## HO-116: Database readiness preflight and verified cloud Neon access + +- **Date:** 2026-10-11 07:43 (EDT) +- **Author:** Muhammad Tahub Khatri with Codex +- **Branch / PR:** `chore/database-readiness` (local commits) / not opened + +### What changed +- Based this isolated checkout on main `1cdb016`, including Bills and F-27. + Preserved the earlier user-approved optional Neon WebSocket runtime, + proxy-aware statement storage and test-database guards. Credentials remain + ignored; tests use local PostgreSQL and the dedicated storage-tests bucket. +- Added `pnpm db:verify --target app|local|branch|production`. Its bounded + financial-page contract checks actual column types/nullability, valid + unconditional uniqueness, validated ownership/reference semantics and + zero-row SELECT access in a read-only snapshot. Equivalent constraint names + and compatible extras pass. Journal mismatches are independent warnings. +- Added the preflight after migrations in both existing CI PostgreSQL jobs, + retaining their required job names. Documented release sequencing, app-role + verification and limits in DATABASE_READINESS, TESTING and ARCHITECTURE. +- All 2,008 unit/integration tests and 115 browser tests passed, including + real Neon test storage. Commands used pnpm 12.9.1, a 30-second test timeout + for proxy/storage latency, and four browser workers with a 60-second timeout. + Lint, formatting, typecheck, docs, build, bundle scan and diff checks passed. + Final focused verifier/unchanged-health rerun passed 24 tests. Generated + browser screenshots were restored rather than included as feature changes. +- Actual Neon app and named production preflights both report schema READY. + They warn about the unrecorded 0010 budget checkpoint and one extra journal + timestamp; the recovered budget and Bills schema pass. No production writes + or migrations ran. Local app_test was explicitly identified and migrated + through 0014; its app-role preflight passes. Direct TCP remains unavailable + in this cloud workspace; migrations still use TCP. + +- After merging main `e75fc63`, the standalone readiness branch passed 25 + verifier/driver tests plus all 3 unchanged health-helper tests, docs and the + migrated local app-role preflight. Main's migration 0015 was applied only to + the explicitly identified local test database. Final actual Neon app and + named production preflights report READY for the financial contract, with + the recovered 0010 checkpoint and two outside journal timestamps reported + separately. No production rows, schema or journal were modified. + +### What's next +- Transfer review is implemented and verified on `feat/transfer-review`. The + user authorized local commits and merging main into both branches; no push, + PR or deployment has been requested. +- The user reports no teammate overlap in Transactions, Bills linkage or CI + and approved the focused historical/daily cashflow balance correction. That + correction and its consumer regressions belong to the transfer branch. +- A full merged browser run exposed an existing Budgets test pool reused after + cleanup. Its isolated test-lifecycle correction is also retained here; no + production Budgets behavior or assertions changed. + +### Open problems +- Readiness checks no write privileges, RLS policies, defaults, arbitrary check + expressions or financial-row correctness. They do not gate Vercel auto-deploy. +- Main now uses all earlier handoff slots in Muhammad's block. The next + reserved block is added separately, and this entry uses its first slot. It + preserves main's independently numbered Bills and agent history; + the earlier Neon-only entry remains in the original `work` checkout. + +## HO-117: Explicit web transfer review and preserved cashflow balances + +- **Date:** 2026-10-11 (EDT) +- **Author:** Muhammad Tahub Khatri with Codex +- **Branch / PR:** `feat/transfer-review` (local commits) / not opened + +### What changed +- Built the supplied transfer plan on the separate readiness branch's commit. + Transactions links to explicit candidates, paired/individual and legacy + states, old date filters and complete bounded counterpart pagination. +- Added atomic metadata-only confirmation, detachment retaining labels and + separate normal-activity actions. Shared Bills advisory locking precedes + sorted row locks. Expected facts/version reject stale and competing saves; + allocated evidence blocks transfer flag changes in both review and the + original transaction editor. Paired financial edits are guarded; ordinary + deletion undoes its balance effect once and detaches surviving owned rows. +- Included the user's approved cashflow correction: liquid transfer amounts + retain their posted-day balance effects without entering spending/income. + No dashboard UI, Insights algorithm, importer or agent code was changed. +- The user reports no overlapping teammate work and authorizes local commits, + merging current main into the branches and resolving merge conflicts. + Renumbered the transfer ADR to ADR-066 because main now owns ADR-065. + Readiness uses HO-116; main's handoff history is preserved. + +### Verified +- Merged main `e75fc63` into both implementation branches. The handoff was the + merge conflict; kept main's complete history and our separately numbered + entries. Both branches contain main, with no unresolved conflicts. +- All 2,297 unit/integration tests in 129 files pass with unchanged thresholds, + including real Neon test storage. Coverage: 90.77% lines, 88.51% branches. + The earlier 320 focused tests and final 72 transfer tests also pass. +- All 124 non-external browser tests pass against the merged production build, + including all eight transfer flows. Tests use local PostgreSQL, four workers + and a 60-second timeout; no assertions or storage checks were skipped. + Pending controls, stale selection, aborted-save retry, edited/deleted rows, + allocated evidence, historical padding, access and themes were exercised. +- Browser verification exposed React's native form reset on validation errors; + retained choices until fresh data replaces the form, and caught request + failures with retry feedback. Fixed the existing Budgets suite's closed-pool + reuse across parallel groups and used the same lifecycle in this new suite. + The first full browser run was 123/124; the corrected full run is 124/124. +- Lint, format, app/worker typecheck, docs, production build, bundle scan and + diff checks pass. Synthetic 360px/1280px light/dark transfer screenshots are + retained; unrelated regenerated screenshots were restored. +- Actual Neon app and named production financial-schema preflights report + READY. Journal discrepancies remain diagnostic warnings. Main's migration + 0015 ran only on the verified local test database; no transfer migration and + no production writes were made. + +### What's next +- Local commits and main merges are complete. No push, PR or deployment has + been requested; published CI and teammate review remain future work. + +### Open problems +- Reviews remain bounded and do not claim complete all-time history. Oversized + candidate/group/account scopes show refinement or retry feedback. +- Publication and deployed CI results remain outside this local verification. + +## HO-118: Combine Neon readiness and transfer review for one PR + +- **Date:** 2026-10-11 +- **Author:** Muhammad Tahub Khatri with Codex +- **Branch / PR:** `feat/transfer-review` / [PR #44](https://github.com/TahubCS/Reeflect/pull/44) + +### What changed +- The user requested merging both implementation branches and opening one PR. + Merged `chore/database-readiness` into `feat/transfer-review`, then merged + current main `5a60b11`, including quiet hours, UI improvements and receipt + photos. This combined branch contains both implementations and main. +- Resolved documentation conflicts by preserving all team history and both + commands in AGENTS.md. Main owns HO-115 for receipt photos; renumbered our + readiness entry to HO-116 and transfer entry to HO-117. ADR-066 remains the + accepted transfer decision; main's ADR-067 is preserved. +- Kept original `work` checkout changes untouched. Only the combined feature + branch will be published; no deployment or merge into main is requested. + +### Verified +- Lint, formatting, app/worker typechecks, docs, production build, bundle scan + (50 files) and diff checks pass after consolidation. +- The configured Neon app database reports READY through the optional + WebSocket transport. Missing journal entries 0010/0017 and one timestamp + remain diagnostic warnings; the financial-page schema and SELECT contract + pass. The check performs no production writes or repairs. +- Verified local `app_test`, applied main's pending migrations 0016/0017 only + there, and ran its read-only readiness check successfully. Created a + separate local database for browser tests so concurrent unit isolation + checks cannot observe browser fixture writes. +- The first full unit run passed 2,684/2,685 tests; one real Neon storage + prefix test exceeded its unchanged 5-second timeout. All four storage tests + passed on immediate retry. Before the final refresh from main, the full unit run passes all 2,685 tests + in 138 files, including real Neon storage, with unchanged thresholds: + 91.90% lines and 89.09% branches. +- The first browser run passed 128/131. A categorization fixture reused an + ended pool across parallel groups; moved creation to beforeAll, matching + the existing Budgets and transfer fixes. Navigation and planned-spending + timing failures both pass on focused retry after the unit run finishes; + all three failed checks plus setup pass in 12.9 seconds with traces. + Before the final refresh from main, the full browser run passes all 131 non-external tests in 2.8 minutes, + including all eight transfer flows, with four workers and the same timeout. +- Scroll to the top after keyboard focus before full-page transfer screenshots, + so the sticky header is captured in its normal position. Browser assertions + and timeouts remain unchanged. Test changes pass lint and formatting. + +- PR #44 is open and attached to the chat. Main advanced to `5116fb5` while + verification ran, adding proactive alerts and an opaque-header correction. + Refreshed main again; only the append-only handoff conflicted. Preserved + HO-097 and all of our entries. Main's migration 0018 ran only on the two + verified local test databases; no Neon schema or journal writes were made. +- After that refresh, 544 affected unit/integration checks are verified. A + readiness CLI subprocess timed out under concurrent build load (543/544); + all 21 readiness tests pass separately in 7.3 seconds with the original + timeout. Transfer, transaction, alert, messaging and isolation checks pass. +- All 33 affected browser checks now pass, including transfer review, alerts, + navigation and categorization. Main's new alerts fixture had the same ended + pool problem; initialize its pool per group and clear its cleanup IDs. + Wait for each clicked navigation link's hydration. Assertions are unchanged. +- Final lint, formatting, app/worker typechecks, docs, rebuilt production + bundle and bundle scan pass. The transfer screenshots include the opaque + header from main; unrelated regenerated screenshots are restored. + +### What's next +- GitHub CI and teammate review; merge only after the repository's required + checks and review. No deployment or merge into main was requested. + +### Open problems +- Published CI and teammate review remain pending. Transfer review + bounds and readiness limits remain as documented in HO-116 and HO-117. diff --git a/docs/PROJECT.md b/docs/PROJECT.md index 73fd704..6c2d4be 100644 --- a/docs/PROJECT.md +++ b/docs/PROJECT.md @@ -119,6 +119,11 @@ Priorities follow ADR-043. Lanes: A = Data, B = Web, C = Agent. | F-36 | Retirement question | Later | B | An action-required item: is money going into a retirement plan through your employer, your own account, or not right now. Retirement and investing count as saving. | ADR-055 | | F-37 | Planned transactions | P1 | B | On the calendar, plan money out or in on a later day and see the expected balance and what is owed before payday change. When the day comes, confirm "It happened" (it becomes a manual transaction) or remove it. Plans are not transactions. | ADR-102, ADR-042 | +Transactions now includes an explicit transfer review subroute (ADR-066). +Suggestions require a selected counterpart and confirmation; independent +labels and pair relationships are reversible metadata, with Bills evidence +guards and no change to recorded account balances. + ## 6. The calendar (summary; full spec in ADR-042) The home screen is a cash-flow calendar built for people who are not diff --git a/docs/TESTING.md b/docs/TESTING.md index 3ed116f..543f1c7 100644 --- a/docs/TESTING.md +++ b/docs/TESTING.md @@ -76,6 +76,7 @@ and never connects to a database. | `lib/money` | Parsing "$1,234.56", "(12.00)", "-12", "12.5" (→ 1250 cents); rejecting non-USD and malformed input; rounding half to even; splitting without losing cents (e.g. $10.00 / 3); formatting negatives; `Number.isSafeInteger` enforcement | | Money properties (fast-check) | Sum of category spending equals total spending; splitting then summing returns the original; add/subtract are inverse; no operation produces a non-integer | | Cash flow (`src/features/cashflow/domain`, ADR-042) | Per-day amount with balance above, equal to and below what is due before payday (never negative); payday tomorrow (N = 1) and no expected income; repeating items clamped to the last day of short months; a month's end balance equals its start plus its items; later months carry the earlier months' balance; a no-spend day needs nothing going out; yearly subscription cost and saving; every number shown has a text label | +| Transfer review (ADR-066) | Calendar boundaries, safe opposite cents, explicit choice/confirmation, immutable expected states and legacy group validity. Real PG: metadata-only snapshots, rollback, duplicate/competing confirmation, edit/delete races, scoped orphans, Bills evidence races and unchanged labelled debt evidence. Test actual Budgets, Insights, recurring and daily cashflow results through pair/detach/reclassification. All six read/write entries join the isolation matrix | | Web Bills (ADR-063) | Stable monthly/day anchors; bounded projections without invented overdue history; explicit due/expected provenance; zero vs unknown invoice; variable amounts; partial/full/overpayment; manual marks; edited/deleted/pending/future/refund evidence; repayment transfers; integer cash coverage; validation and pagination | | Budgets | Calendar month boundaries and DST in the app's zone; leap years and year navigation; mid-month edits; posted/current-day cutoff; refunds including negative net spending; marked transfers, income and saving excluded; unknown credits not treated as refunds; zero vs unset; bounded progress; immutable paged reductions and integer overflow | | Categorization | Rule priority and deterministic ties; `contains` / `starts_with` / `exact`; merchant normalization (store numbers, reference codes); manual override including Uncategorized beats rules; form validation and limits | @@ -162,6 +163,7 @@ and never connects to a database. | `bills.spec.ts` | Add a manual car payment due in 7 days; run the reminder job; reminder appears in Upcoming bills with amount and date; mark it paid by adding the payment; reminder disappears | | `recurring.spec.ts` | Confirm fixed subscriptions and variable bills; show evidence and actual spending separately from estimates; preserve Keep/planning-to-cancel through refresh; later imports/credits and fingerprint duplicates; manual rent create/edit/remove/restore; persistent dismissal; kind/amount corrections and invalid inputs; viewers/outsiders; filtering/pagination; retry boundary and 360px dark/reduced-motion layout | | `budgets.spec.ts` | Set/edit/remove/zero allocations; retained validation input; refunds, card spending, transfers, pending/future rows and Uncategorized; copy without overwriting zero or history; next-month planning; over 500 monthly rows and a year of historical data; changed rules/renames; viewer/outsider access; failed-read retry without fake totals; keyboard, 360px, themes and reduced motion | +| `transfers.spec.ts` | Explicit ambiguous choice and confirmation; persistence; detach keeps labels; separate normal activity; stale retained selection; paired edit/delete cleanup; old-window padding and counterpart pages; viewer/outsider; Bills allocation feedback; failed-read retry; keyboard, 360px, light/dark and reduced motion. Synthetic screenshots are in `docs/screenshots/transfers/` | | `demo-path.spec.ts` | The exact demo script from sign-in to final screen, on the seeded workspace | | `a11y.spec.ts` | axe checks on every main page in light and dark themes; zero serious or critical violations | | `reduced-motion.spec.ts` | With reduced motion emulated, no animation runs and all labels still show | @@ -201,14 +203,16 @@ must match the required checks in `.github/rulesets/main.json`. | CI job | Runs | |---|---| | `lint-typecheck` | `pnpm lint`, `pnpm format:check`, `pnpm typecheck`, `pnpm docs:check` | -| `unit` | `pnpm db:migrate` on a fresh database, then `pnpm test:unit` with coverage thresholds | -| `e2e` | `pnpm db:migrate`, `pnpm build`, `pnpm scan:bundle`, `pnpm test:e2e --grep-invert @external` | +| `unit` | `pnpm db:migrate` on a fresh database, `pnpm db:verify --target app`, then `pnpm test:unit` with coverage thresholds | +| `e2e` | `pnpm db:migrate`, `pnpm db:verify --target app`, `pnpm build`, `pnpm scan:bundle`, `pnpm test:e2e --grep-invert @external` | | `security` | `pnpm audit --prod --audit-level high` | | `codeql` (separate workflow) | Static analysis for JavaScript/TypeScript | `unit` and `e2e` each start a PostgreSQL service and apply every migration to it first. Locally the same database comes from `docker compose up -d`. -Tests never connect to Neon. +Database tests never connect to Neon; storage tests use the dedicated test +bucket. [Database readiness](DATABASE_READINESS.md) explains the verifier's +isolated fault fixtures, permission checks and release limitations. The workspace isolation matrix (TEST-06) includes `/api/agent/turn`: a linked handle for user A can never cause a tool call against user B's diff --git a/docs/TRANSFER_REVIEW.md b/docs/TRANSFER_REVIEW.md new file mode 100644 index 0000000..72dda5d --- /dev/null +++ b/docs/TRANSFER_REVIEW.md @@ -0,0 +1,52 @@ +# Recorded transfer review + +Open Transactions → Review transfers at +`/w/[workspaceId]/transactions/transfers` (ADR-066). This classifies recorded +activity; it never moves money or changes account balances. + +Choose a specific counterpart and check the confirmation before saving. The +page shows each account, posted date, signed amount and description, plus the +matching reason. Several candidates remain explicitly ambiguous. A match uses +posted transactions no later than today in America/New_York, different owned +accounts, nonzero safe integer cents of equal/opposite value, and no more than +three calendar days between dates. Existing pair IDs exclude candidates. +Individual transfer labels may acquire a relationship without changing flags. + +Pairing atomically labels exactly two owned rows. Remove pairing clears only +the relationship and keeps each current transfer label, including mixed legacy +flags. Count as normal activity is a separate confirmed action on a standalone +row. Existing confirmed pairs, individual labels, invalid groups and incomplete +relationships have separate states. Reads never repair old data. Account +cascade deletion can leave an orphan that is explicitly detached here. + +Review defaults to 90 inclusive days; select older dates or accounts as needed. +One review spans at most 366 days. Activity pages contain 20 rows, with at most +1,000 pages before refining the date/account scope. Counterparts are looked up +independently of the activity page and include the three-day window padding. +Up to 2,000 candidates are counted completely and paged by 20 in a focused +review. Above that cap, choose a counterpart account; no truncated candidate +list is presented as complete. Legacy groups over 50 rows have no partial +repair action. More than 1,000 accounts fails into the retry boundary. + +Every write rechecks expected facts, labels, pair IDs and the precise update +version under the same workspace advisory lock used by Bills, then locks +transaction IDs in order. A repeated identical pair confirmation succeeds +without another update; stale or competing forms fail with retained selection +and a reload instruction. Pairing and standalone labelling change only transfer +metadata and timestamps. Amounts, accounts, dates, statuses, descriptions, +categories, source/import facts and stored balances are preserved. + +Paired transactions allow description edits; detach first to change financial +fields or a transfer flag. Transaction deletion retains its existing manual +balance undo and atomically detaches surviving owned members, preserving flags. +A label change affecting allocated Bills evidence is rejected in both the new +review and the original checkbox. Explicitly unlink that evidence in Bills +first. An already-labelled debt payment can gain or lose a relationship without +rewriting its payment snapshot. Viewing requires viewer membership; all writes +require editor or owner membership. Foreign IDs never grant access. + +Cashflow keeps recorded liquid transfer amounts in opening and daily balances, +while excluding them from activity totals. Card purchases still count as +spending; repayments do not. Budgets, Insights and recurring use their existing +transfer exclusions; Insights retains its existing saving-category semantics. +There is no new importer, worker, agent protocol, dashboard UI or schema change. diff --git a/docs/screenshots/transfers/1280-dark.png b/docs/screenshots/transfers/1280-dark.png new file mode 100644 index 0000000..948e6b6 Binary files /dev/null and b/docs/screenshots/transfers/1280-dark.png differ diff --git a/docs/screenshots/transfers/1280-light.png b/docs/screenshots/transfers/1280-light.png new file mode 100644 index 0000000..03ad5f4 Binary files /dev/null and b/docs/screenshots/transfers/1280-light.png differ diff --git a/docs/screenshots/transfers/360-dark.png b/docs/screenshots/transfers/360-dark.png new file mode 100644 index 0000000..d210378 Binary files /dev/null and b/docs/screenshots/transfers/360-dark.png differ diff --git a/docs/screenshots/transfers/360-light.png b/docs/screenshots/transfers/360-light.png new file mode 100644 index 0000000..1b5cde2 Binary files /dev/null and b/docs/screenshots/transfers/360-light.png differ diff --git a/package.json b/package.json index e4937f3..76f4853 100644 --- a/package.json +++ b/package.json @@ -18,6 +18,7 @@ "db:migrate": "drizzle-kit migrate", "db:migrate:to": "node --disable-warning=MODULE_TYPELESS_PACKAGE_JSON --import ./scripts/register-paths.ts scripts/db/migrate-to.ts", "db:whoami": "node --disable-warning=MODULE_TYPELESS_PACKAGE_JSON --import ./scripts/register-paths.ts scripts/db/whoami.ts", + "db:verify": "node --disable-warning=MODULE_TYPELESS_PACKAGE_JSON --import ./scripts/register-paths.ts scripts/db/verify.ts", "ai:check": "node --disable-warning=MODULE_TYPELESS_PACKAGE_JSON --import ./scripts/register-paths.ts scripts/ai-check.ts", "batch": "node --disable-warning=MODULE_TYPELESS_PACKAGE_JSON --import ./scripts/register-paths.ts scripts/batch/cli.ts", "nessie": "node --disable-warning=MODULE_TYPELESS_PACKAGE_JSON --import ./scripts/register-paths.ts scripts/nessie/cli.ts" @@ -29,6 +30,7 @@ "@aws-sdk/s3-request-presigner": "3.1149.0", "@better-auth/infra": "^0.4.16", "@google/genai": "2.28.0", + "@neondatabase/serverless": "^1.2.0", "@reeflect/agent-protocol": "workspace:*", "better-auth": "^1.7.7", "drizzle-orm": "^0.45.4", @@ -41,6 +43,7 @@ "resend": "^6.32.1", "server-only": "^0.0.1", "unpdf": "^1.8.1", + "ws": "^8.22.0", "zod": "^4.6.5" }, "devDependencies": { @@ -51,6 +54,7 @@ "@types/pg": "^8.23.1", "@types/react": "^19", "@types/react-dom": "^19", + "@types/ws": "^8.18.2", "@vitest/coverage-v8": "^5.0.3", "drizzle-kit": "^0.31.11", "eslint": "^9", diff --git a/playwright.config.ts b/playwright.config.ts index 848f333..068d2dc 100644 --- a/playwright.config.ts +++ b/playwright.config.ts @@ -1,6 +1,16 @@ import { defineConfig, devices } from "@playwright/test"; import { testStorageEnv } from "./tests/support/storage-env"; +// Apply this to the runner too: specs that seed data construct their own +// pg pools, outside the webServer environment below. +if ( + process.env.DATABASE_URL && + new URL(process.env.DATABASE_URL).hostname.endsWith(".neon.tech") +) { + process.env.DATABASE_URL = "postgres://test:test@localhost:5433/app_test"; + process.env.DATABASE_URL_UNPOOLED = process.env.DATABASE_URL; +} + const isCi = Boolean(process.env.CI); // Set PORT when something else (such as `pnpm dev`) already uses 3000. const port = process.env.PORT ?? "3000"; @@ -50,6 +60,7 @@ export default defineConfig({ DATABASE_URL: process.env.DATABASE_URL ?? "postgres://test:test@localhost:5433/app_test", + DATABASE_TRANSPORT: "tcp", // The server under test is always on localhost, whatever .env.local says. BETTER_AUTH_URL: baseURL, // Test sign-ups never reach the Better Auth dashboard (ADR-047). An diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 415afbc..786c034 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -180,19 +180,22 @@ importers: version: 3.1149.0 '@better-auth/infra': specifier: ^0.4.16 - version: 0.4.16(@better-auth/core@1.7.7(@better-auth/utils@0.4.2)(@better-fetch/fetch@1.3.2)(@opentelemetry/api@1.9.1)(better-call@1.4.0(zod@4.6.5))(jose@6.2.12)(kysely@0.29.6)(nanostores@1.5.5))(better-auth@1.7.7(@opentelemetry/api@1.9.1)(drizzle-kit@0.31.11)(drizzle-orm@0.45.4(@opentelemetry/api@1.9.1)(@types/pg@8.23.1)(kysely@0.29.6)(pg@8.23.1))(next@16.4.0(@babel/core@7.29.7(supports-color@7.2.0))(@opentelemetry/api@1.9.1)(@playwright/test@1.64.0)(@types/node@24.19.1)(react-dom@19.3.0(react@19.3.0))(react@19.3.0))(pg@8.23.1)(react-dom@19.3.0(react@19.3.0))(react@19.3.0)(vitest@5.0.3))(zod@4.6.5) + version: 0.4.16(@better-auth/core@1.7.7(@better-auth/utils@0.4.2)(@better-fetch/fetch@1.3.2)(@opentelemetry/api@1.9.1)(better-call@1.4.0(zod@4.6.5))(jose@6.2.12)(kysely@0.29.6)(nanostores@1.5.5))(better-auth@1.7.7(@opentelemetry/api@1.9.1)(drizzle-kit@0.31.11)(drizzle-orm@0.45.4(@neondatabase/serverless@1.2.0)(@opentelemetry/api@1.9.1)(@types/pg@8.23.1)(kysely@0.29.6)(pg@8.23.1))(next@16.4.0(@babel/core@7.29.7(supports-color@7.2.0))(@opentelemetry/api@1.9.1)(@playwright/test@1.64.0)(@types/node@24.19.1)(react-dom@19.3.0(react@19.3.0))(react@19.3.0))(pg@8.23.1)(react-dom@19.3.0(react@19.3.0))(react@19.3.0)(vitest@5.0.3))(zod@4.6.5) '@google/genai': specifier: 2.28.0 version: 2.28.0(@modelcontextprotocol/sdk@1.32.1(supports-color@7.2.0)(zod@4.6.5))(supports-color@7.2.0) + '@neondatabase/serverless': + specifier: ^1.2.0 + version: 1.2.0 '@reeflect/agent-protocol': specifier: workspace:* version: link:packages/agent-protocol better-auth: specifier: ^1.7.7 - version: 1.7.7(@opentelemetry/api@1.9.1)(drizzle-kit@0.31.11)(drizzle-orm@0.45.4(@opentelemetry/api@1.9.1)(@types/pg@8.23.1)(kysely@0.29.6)(pg@8.23.1))(next@16.4.0(@babel/core@7.29.7(supports-color@7.2.0))(@opentelemetry/api@1.9.1)(@playwright/test@1.64.0)(@types/node@24.19.1)(react-dom@19.3.0(react@19.3.0))(react@19.3.0))(pg@8.23.1)(react-dom@19.3.0(react@19.3.0))(react@19.3.0)(vitest@5.0.3) + version: 1.7.7(@opentelemetry/api@1.9.1)(drizzle-kit@0.31.11)(drizzle-orm@0.45.4(@neondatabase/serverless@1.2.0)(@opentelemetry/api@1.9.1)(@types/pg@8.23.1)(kysely@0.29.6)(pg@8.23.1))(next@16.4.0(@babel/core@7.29.7(supports-color@7.2.0))(@opentelemetry/api@1.9.1)(@playwright/test@1.64.0)(@types/node@24.19.1)(react-dom@19.3.0(react@19.3.0))(react@19.3.0))(pg@8.23.1)(react-dom@19.3.0(react@19.3.0))(react@19.3.0)(vitest@5.0.3) drizzle-orm: specifier: ^0.45.4 - version: 0.45.4(@opentelemetry/api@1.9.1)(@types/pg@8.23.1)(kysely@0.29.6)(pg@8.23.1) + version: 0.45.4(@neondatabase/serverless@1.2.0)(@opentelemetry/api@1.9.1)(@types/pg@8.23.1)(kysely@0.29.6)(pg@8.23.1) files-sdk: specifier: 2.6.0 version: 2.6.0(@aws-sdk/client-s3@3.1149.0)(@aws-sdk/lib-storage@3.1149.0(@aws-sdk/client-s3@3.1149.0))(@aws-sdk/s3-presigned-post@3.1149.0)(@aws-sdk/s3-request-presigner@3.1149.0)(@opentelemetry/api@1.9.1)(google-auth-library@10.9.1(supports-color@7.2.0))(hono@4.13.13)(next@16.4.0(@babel/core@7.29.7(supports-color@7.2.0))(@opentelemetry/api@1.9.1)(@playwright/test@1.64.0)(@types/node@24.19.1)(react-dom@19.3.0(react@19.3.0))(react@19.3.0))(react-dom@19.3.0(react@19.3.0))(react@19.3.0)(supports-color@7.2.0)(zod@4.6.5) @@ -220,6 +223,9 @@ importers: unpdf: specifier: ^1.8.1 version: 1.8.1 + ws: + specifier: ^8.22.0 + version: 8.22.0 zod: specifier: ^4.6.5 version: 4.6.5 @@ -245,6 +251,9 @@ importers: '@types/react-dom': specifier: ^19 version: 19.3.0(@types/react@19.3.0) + '@types/ws': + specifier: ^8.18.2 + version: 8.18.2 '@vitest/coverage-v8': specifier: ^5.0.3 version: 5.0.3(vitest@5.0.3) @@ -1320,6 +1329,10 @@ packages: resolution: {integrity: sha512-Zyo84tVyK3cO/vkREgFSPZ0llGoWNgcbbz38/UkqyqKN/Ky6huHibTCyvnlnBV1aeWnJhEhg9W0HIylE6sCS0g==} engines: {node: '>=20.19.0'} + '@neondatabase/serverless@1.2.0': + resolution: {integrity: sha512-tnaqgixUengZQNd9ZrS3ytQfamJzLKY8QxgqWQTNHHtB+KrFQWk77JTbbpg4RD+J3qE4eO2lVytvGDX5Kj6FdQ==} + engines: {node: '>=19.0.0'} + '@next/env@16.4.0': resolution: {integrity: sha512-pyLlT5oafGlX8X7xjgGNXz5dNIDSxREm+qD6i9VLSZiZFopA/XWl8NM/KPmLx/8EG/++c49iid3gNWSQW1+2dQ==} @@ -1907,6 +1920,9 @@ packages: '@types/retry@0.12.0': resolution: {integrity: sha512-wWKOClTTiizcZhXnPY4wikVAwmdYHp8q6DmC+EJUzAMsycb7HB32Kh9RN4+0gExjmPmZSAQjgURXIGATPegAvA==} + '@types/ws@8.18.2': + resolution: {integrity: sha512-67MQl+fpWKVTT1NYdnmo3U4sc/xPo/zQBncVnI74qmQa0z/b+1g6iYqNmGCPbxO+zz2aklb08a0oHfegiVd0/w==} + '@typescript-eslint/eslint-plugin@8.71.1': resolution: {integrity: sha512-nNlBf6HuotqMgZvSkWD5hNdemiBIxQ2NmrlgfcUIeZRs+BbakjscCQRq/Hb74EFVnFiSWWdL12JruqwBy3ERDw==} engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0} @@ -2144,6 +2160,11 @@ packages: ajv-formats@3.0.1: resolution: {integrity: sha512-8iUql50EUR+uUcdRQ3HDqa6EVyo3docL8g5WJ3FNcWmu62IbkGUue/pEyLBW8VGKKucTPgqeks4fIU1DA4yowQ==} + peerDependencies: + ajv: ^8.0.0 + peerDependenciesMeta: + ajv: + optional: true ajv@6.15.0: resolution: {integrity: sha512-fgFx7Hfoq60ytK2c7DhnF8jIvzYgOMxfugjLOSMHjLIPgenqa7S7oaagATUq99mV6IYvN2tRmC0wnTYX6iPbMw==} @@ -4994,21 +5015,21 @@ snapshots: optionalDependencies: '@opentelemetry/api': 1.9.1 - '@better-auth/drizzle-adapter@1.7.7(@better-auth/core@1.7.7(@better-auth/utils@0.4.2)(@better-fetch/fetch@1.3.2)(@opentelemetry/api@1.9.1)(better-call@1.4.0(zod@4.6.5))(jose@6.2.12)(kysely@0.29.6)(nanostores@1.5.5))(@better-auth/utils@0.4.2)(drizzle-orm@0.45.4(@opentelemetry/api@1.9.1)(@types/pg@8.23.1)(kysely@0.29.6)(pg@8.23.1))': + '@better-auth/drizzle-adapter@1.7.7(@better-auth/core@1.7.7(@better-auth/utils@0.4.2)(@better-fetch/fetch@1.3.2)(@opentelemetry/api@1.9.1)(better-call@1.4.0(zod@4.6.5))(jose@6.2.12)(kysely@0.29.6)(nanostores@1.5.5))(@better-auth/utils@0.4.2)(drizzle-orm@0.45.4(@neondatabase/serverless@1.2.0)(@opentelemetry/api@1.9.1)(@types/pg@8.23.1)(kysely@0.29.6)(pg@8.23.1))': dependencies: '@better-auth/core': 1.7.7(@better-auth/utils@0.4.2)(@better-fetch/fetch@1.3.2)(@opentelemetry/api@1.9.1)(better-call@1.4.0(zod@4.6.5))(jose@6.2.12)(kysely@0.29.6)(nanostores@1.5.5) '@better-auth/utils': 0.4.2 optionalDependencies: - drizzle-orm: 0.45.4(@opentelemetry/api@1.9.1)(@types/pg@8.23.1)(kysely@0.29.6)(pg@8.23.1) + drizzle-orm: 0.45.4(@neondatabase/serverless@1.2.0)(@opentelemetry/api@1.9.1)(@types/pg@8.23.1)(kysely@0.29.6)(pg@8.23.1) - '@better-auth/infra@0.4.16(@better-auth/core@1.7.7(@better-auth/utils@0.4.2)(@better-fetch/fetch@1.3.2)(@opentelemetry/api@1.9.1)(better-call@1.4.0(zod@4.6.5))(jose@6.2.12)(kysely@0.29.6)(nanostores@1.5.5))(better-auth@1.7.7(@opentelemetry/api@1.9.1)(drizzle-kit@0.31.11)(drizzle-orm@0.45.4(@opentelemetry/api@1.9.1)(@types/pg@8.23.1)(kysely@0.29.6)(pg@8.23.1))(next@16.4.0(@babel/core@7.29.7(supports-color@7.2.0))(@opentelemetry/api@1.9.1)(@playwright/test@1.64.0)(@types/node@24.19.1)(react-dom@19.3.0(react@19.3.0))(react@19.3.0))(pg@8.23.1)(react-dom@19.3.0(react@19.3.0))(react@19.3.0)(vitest@5.0.3))(zod@4.6.5)': + '@better-auth/infra@0.4.16(@better-auth/core@1.7.7(@better-auth/utils@0.4.2)(@better-fetch/fetch@1.3.2)(@opentelemetry/api@1.9.1)(better-call@1.4.0(zod@4.6.5))(jose@6.2.12)(kysely@0.29.6)(nanostores@1.5.5))(better-auth@1.7.7(@opentelemetry/api@1.9.1)(drizzle-kit@0.31.11)(drizzle-orm@0.45.4(@neondatabase/serverless@1.2.0)(@opentelemetry/api@1.9.1)(@types/pg@8.23.1)(kysely@0.29.6)(pg@8.23.1))(next@16.4.0(@babel/core@7.29.7(supports-color@7.2.0))(@opentelemetry/api@1.9.1)(@playwright/test@1.64.0)(@types/node@24.19.1)(react-dom@19.3.0(react@19.3.0))(react@19.3.0))(pg@8.23.1)(react-dom@19.3.0(react@19.3.0))(react@19.3.0)(vitest@5.0.3))(zod@4.6.5)': dependencies: '@better-auth/core': 1.7.7(@better-auth/utils@0.4.2)(@better-fetch/fetch@1.3.2)(@opentelemetry/api@1.9.1)(better-call@1.4.0(zod@4.6.5))(jose@6.2.12)(kysely@0.29.6)(nanostores@1.5.5) '@better-auth/utils': 0.4.2 '@better-fetch/fetch': 1.3.2 '@noble/hashes': 2.4.0 '@xmldom/xmldom': 0.9.12 - better-auth: 1.7.7(@opentelemetry/api@1.9.1)(drizzle-kit@0.31.11)(drizzle-orm@0.45.4(@opentelemetry/api@1.9.1)(@types/pg@8.23.1)(kysely@0.29.6)(pg@8.23.1))(next@16.4.0(@babel/core@7.29.7(supports-color@7.2.0))(@opentelemetry/api@1.9.1)(@playwright/test@1.64.0)(@types/node@24.19.1)(react-dom@19.3.0(react@19.3.0))(react@19.3.0))(pg@8.23.1)(react-dom@19.3.0(react@19.3.0))(react@19.3.0)(vitest@5.0.3) + better-auth: 1.7.7(@opentelemetry/api@1.9.1)(drizzle-kit@0.31.11)(drizzle-orm@0.45.4(@neondatabase/serverless@1.2.0)(@opentelemetry/api@1.9.1)(@types/pg@8.23.1)(kysely@0.29.6)(pg@8.23.1))(next@16.4.0(@babel/core@7.29.7(supports-color@7.2.0))(@opentelemetry/api@1.9.1)(@playwright/test@1.64.0)(@types/node@24.19.1)(react-dom@19.3.0(react@19.3.0))(react@19.3.0))(pg@8.23.1)(react-dom@19.3.0(react@19.3.0))(react@19.3.0)(vitest@5.0.3) better-call: 1.4.0(zod@4.6.5) jose: 6.2.12 libphonenumber-js: 1.13.15 @@ -5538,7 +5559,7 @@ snapshots: dependencies: '@hono/node-server': 2.1.4(hono@4.13.13) ajv: 8.20.0 - ajv-formats: 3.0.1 + ajv-formats: 3.0.1(ajv@8.20.0) content-type: 1.0.5 cors: 2.8.6 cross-spawn: 7.0.6 @@ -5572,6 +5593,8 @@ snapshots: '@neon/sdk@7.0.1': {} + '@neondatabase/serverless@1.2.0': {} + '@next/env@16.4.0': {} '@next/eslint-plugin-next@16.4.0(eslint@9.39.5(jiti@2.7.0)(supports-color@7.2.0))': @@ -6111,6 +6134,10 @@ snapshots: '@types/retry@0.12.0': {} + '@types/ws@8.18.2': + dependencies: + '@types/node': 24.19.1 + '@typescript-eslint/eslint-plugin@8.71.1(@typescript-eslint/parser@8.71.1(eslint@9.39.5(jiti@2.7.0)(supports-color@7.2.0))(supports-color@7.2.0)(typescript@5.9.3))(eslint@9.39.5(jiti@2.7.0)(supports-color@7.2.0))(supports-color@7.2.0)(typescript@5.9.3)': dependencies: '@eslint-community/regexpp': 4.12.2 @@ -6319,8 +6346,8 @@ snapshots: agent-base@7.1.4: {} - ajv-formats@3.0.1: - dependencies: + ajv-formats@3.0.1(ajv@8.20.0): + optionalDependencies: ajv: 8.20.0 optional: true @@ -6446,10 +6473,10 @@ snapshots: baseline-browser-mapping@2.11.28: {} - better-auth@1.7.7(@opentelemetry/api@1.9.1)(drizzle-kit@0.31.11)(drizzle-orm@0.45.4(@opentelemetry/api@1.9.1)(@types/pg@8.23.1)(kysely@0.29.6)(pg@8.23.1))(next@16.4.0(@babel/core@7.29.7(supports-color@7.2.0))(@opentelemetry/api@1.9.1)(@playwright/test@1.64.0)(@types/node@24.19.1)(react-dom@19.3.0(react@19.3.0))(react@19.3.0))(pg@8.23.1)(react-dom@19.3.0(react@19.3.0))(react@19.3.0)(vitest@5.0.3): + better-auth@1.7.7(@opentelemetry/api@1.9.1)(drizzle-kit@0.31.11)(drizzle-orm@0.45.4(@neondatabase/serverless@1.2.0)(@opentelemetry/api@1.9.1)(@types/pg@8.23.1)(kysely@0.29.6)(pg@8.23.1))(next@16.4.0(@babel/core@7.29.7(supports-color@7.2.0))(@opentelemetry/api@1.9.1)(@playwright/test@1.64.0)(@types/node@24.19.1)(react-dom@19.3.0(react@19.3.0))(react@19.3.0))(pg@8.23.1)(react-dom@19.3.0(react@19.3.0))(react@19.3.0)(vitest@5.0.3): dependencies: '@better-auth/core': 1.7.7(@better-auth/utils@0.4.2)(@better-fetch/fetch@1.3.2)(@opentelemetry/api@1.9.1)(better-call@1.4.0(zod@4.6.5))(jose@6.2.12)(kysely@0.29.6)(nanostores@1.5.5) - '@better-auth/drizzle-adapter': 1.7.7(@better-auth/core@1.7.7(@better-auth/utils@0.4.2)(@better-fetch/fetch@1.3.2)(@opentelemetry/api@1.9.1)(better-call@1.4.0(zod@4.6.5))(jose@6.2.12)(kysely@0.29.6)(nanostores@1.5.5))(@better-auth/utils@0.4.2)(drizzle-orm@0.45.4(@opentelemetry/api@1.9.1)(@types/pg@8.23.1)(kysely@0.29.6)(pg@8.23.1)) + '@better-auth/drizzle-adapter': 1.7.7(@better-auth/core@1.7.7(@better-auth/utils@0.4.2)(@better-fetch/fetch@1.3.2)(@opentelemetry/api@1.9.1)(better-call@1.4.0(zod@4.6.5))(jose@6.2.12)(kysely@0.29.6)(nanostores@1.5.5))(@better-auth/utils@0.4.2)(drizzle-orm@0.45.4(@neondatabase/serverless@1.2.0)(@opentelemetry/api@1.9.1)(@types/pg@8.23.1)(kysely@0.29.6)(pg@8.23.1)) '@better-auth/kysely-adapter': 1.7.7(@better-auth/core@1.7.7(@better-auth/utils@0.4.2)(@better-fetch/fetch@1.3.2)(@opentelemetry/api@1.9.1)(better-call@1.4.0(zod@4.6.5))(jose@6.2.12)(kysely@0.29.6)(nanostores@1.5.5))(@better-auth/utils@0.4.2)(kysely@0.29.6) '@better-auth/memory-adapter': 1.7.7(@better-auth/core@1.7.7(@better-auth/utils@0.4.2)(@better-fetch/fetch@1.3.2)(@opentelemetry/api@1.9.1)(better-call@1.4.0(zod@4.6.5))(jose@6.2.12)(kysely@0.29.6)(nanostores@1.5.5))(@better-auth/utils@0.4.2) '@better-auth/mongo-adapter': 1.7.7(@better-auth/core@1.7.7(@better-auth/utils@0.4.2)(@better-fetch/fetch@1.3.2)(@opentelemetry/api@1.9.1)(better-call@1.4.0(zod@4.6.5))(jose@6.2.12)(kysely@0.29.6)(nanostores@1.5.5))(@better-auth/utils@0.4.2) @@ -6467,7 +6494,7 @@ snapshots: zod: 4.6.5 optionalDependencies: drizzle-kit: 0.31.11 - drizzle-orm: 0.45.4(@opentelemetry/api@1.9.1)(@types/pg@8.23.1)(kysely@0.29.6)(pg@8.23.1) + drizzle-orm: 0.45.4(@neondatabase/serverless@1.2.0)(@opentelemetry/api@1.9.1)(@types/pg@8.23.1)(kysely@0.29.6)(pg@8.23.1) next: 16.4.0(@babel/core@7.29.7(supports-color@7.2.0))(@opentelemetry/api@1.9.1)(@playwright/test@1.64.0)(@types/node@24.19.1)(react-dom@19.3.0(react@19.3.0))(react@19.3.0) pg: 8.23.1 react: 19.3.0 @@ -6740,8 +6767,9 @@ snapshots: esbuild: 0.25.12 tsx: 4.23.15 - drizzle-orm@0.45.4(@opentelemetry/api@1.9.1)(@types/pg@8.23.1)(kysely@0.29.6)(pg@8.23.1): + drizzle-orm@0.45.4(@neondatabase/serverless@1.2.0)(@opentelemetry/api@1.9.1)(@types/pg@8.23.1)(kysely@0.29.6)(pg@8.23.1): optionalDependencies: + '@neondatabase/serverless': 1.2.0 '@opentelemetry/api': 1.9.1 '@types/pg': 8.23.1 kysely: 0.29.6 diff --git a/scripts/db/catalog.ts b/scripts/db/catalog.ts new file mode 100644 index 0000000..6dab563 --- /dev/null +++ b/scripts/db/catalog.ts @@ -0,0 +1,101 @@ +import type pg from "pg"; +import type { TableContract, Reference } from "./contract"; +import type { TableFacts } from "./schema-check"; + +export type CatalogClient = Pick; +const quoted = (name: string) => `"${name.replaceAll('"', '""')}"`; +const deleteActions: Record = { + a: "no action", + r: "restrict", + c: "cascade", + n: "set null", + d: "set default", +}; + +/** Only catalog SELECTs and zero-row SELECTs; caller starts a read-only snapshot. */ +export async function inspectSchema( + client: CatalogClient, + contract: readonly TableContract[], + schema = "public", +): Promise { + const names = contract.map((t) => t.name); + const tables = await client.query<{ name: string }>( + ` + SELECT c.relname AS name FROM pg_class c JOIN pg_namespace n ON n.oid=c.relnamespace + WHERE n.nspname=$1 AND c.relname=ANY($2::text[]) AND c.relkind IN ('r','p')`, + [schema, names], + ); + const columns = await client.query<{ + table: string; + name: string; + type: string; + notNull: boolean; + }>( + ` + SELECT c.relname AS table, a.attname AS name, + format_type(a.atttypid,a.atttypmod) AS type, a.attnotnull AS "notNull" + FROM pg_class c JOIN pg_namespace n ON n.oid=c.relnamespace + JOIN pg_attribute a ON a.attrelid=c.oid + WHERE n.nspname=$1 AND c.relname=ANY($2::text[]) AND a.attnum>0 AND NOT a.attisdropped`, + [schema, names], + ); + const unique = await client.query<{ + table: string; + columns: string[]; + valid: boolean; + }>( + ` + SELECT c.relname AS table, + ARRAY(SELECT a.attname::text FROM unnest(i.indkey::smallint[]) WITH ORDINALITY k(num,pos) + JOIN pg_attribute a ON a.attrelid=c.oid AND a.attnum=k.num + WHERE k.pos<=i.indnkeyatts ORDER BY k.pos) AS columns, + (i.indisvalid AND i.indisready AND i.indislive AND i.indpred IS NULL AND i.indexprs IS NULL) AS valid + FROM pg_index i JOIN pg_class c ON c.oid=i.indrelid JOIN pg_namespace n ON n.oid=c.relnamespace + WHERE n.nspname=$1 AND c.relname=ANY($2::text[]) AND i.indisunique`, + [schema, names], + ); + const references = await client.query< + Reference & { localTable: string; schema: string; validated: boolean } + >( + ` + SELECT c.relname AS "localTable", f.relname AS table, fn.nspname AS schema, + ARRAY(SELECT a.attname::text FROM unnest(con.conkey) WITH ORDINALITY k(num,pos) + JOIN pg_attribute a ON a.attrelid=c.oid AND a.attnum=k.num ORDER BY k.pos) AS columns, + ARRAY(SELECT a.attname::text FROM unnest(con.confkey) WITH ORDINALITY k(num,pos) + JOIN pg_attribute a ON a.attrelid=f.oid AND a.attnum=k.num ORDER BY k.pos) AS "foreignColumns", + con.confdeltype AS "onDelete", con.convalidated AS validated + FROM pg_constraint con JOIN pg_class c ON c.oid=con.conrelid + JOIN pg_namespace n ON n.oid=c.relnamespace JOIN pg_class f ON f.oid=con.confrelid + JOIN pg_namespace fn ON fn.oid=f.relnamespace + WHERE n.nspname=$1 AND c.relname=ANY($2::text[]) AND con.contype='f'`, + [schema, names], + ); + const facts: TableFacts[] = []; + for (const { name } of tables.rows) { + const expected = contract.find((t) => t.name === name)!; + let readable = false; + await client.query("SAVEPOINT read_probe"); + try { + await client.query( + `SELECT ${expected.columns.map((c) => quoted(c.name)).join(",")} FROM ${quoted(schema)}.${quoted(name)} LIMIT 0`, + ); + readable = true; + } catch (error) { + await client.query("ROLLBACK TO SAVEPOINT read_probe"); + const code = (error as { code?: string }).code; + if (code !== "42501" && code !== "42703" && code !== "42P01") throw error; + } finally { + await client.query("RELEASE SAVEPOINT read_probe"); + } + facts.push({ + name, + readable, + columns: columns.rows.filter((c) => c.table === name), + unique: unique.rows.filter((i) => i.table === name), + references: references.rows + .filter((f) => f.localTable === name) + .map((f) => ({ ...f, onDelete: deleteActions[f.onDelete]! })), + }); + } + return facts; +} diff --git a/scripts/db/contract.ts b/scripts/db/contract.ts new file mode 100644 index 0000000..bb7a2fd --- /dev/null +++ b/scripts/db/contract.ts @@ -0,0 +1,86 @@ +// A bounded release contract for the financial pages, not a schema diff. +import { getTableConfig, type PgTable } from "drizzle-orm/pg-core"; +import { + billCycle, + billDetails, + billPayment, + budget, + category, + categoryRule, + financialAccount, + importBatch, + organization, + recurringSeries, + transaction, + user, +} from "../../src/lib/db/schema"; + +export type Reference = { + columns: string[]; + table: string; + foreignColumns: string[]; + onDelete: string; +}; +export type TableContract = { + feature: string; + name: string; + columns: { name: string; type: string; notNull: boolean }[]; + unique: string[][]; + references: Reference[]; +}; + +function required( + feature: string, + table: PgTable, + only?: string[], +): TableContract { + const config = getTableConfig(table); + const columns = config.columns.filter((c) => !only || only.includes(c.name)); + return { + feature, + name: config.name, + columns: columns.map((c) => ({ + name: c.name, + type: c.getSQLType(), + notNull: c.notNull, + })), + unique: [ + ...columns.filter((c) => c.primary).map((c) => [c.name]), + ...config.indexes + .filter((i) => i.config.unique) + .map((i) => + i.config.columns.map((c) => { + if (!("name" in c) || typeof c.name !== "string") + throw new Error("Contract requires simple index columns"); + return c.name; + }), + ), + ], + references: config.foreignKeys.map((fk) => { + const ref = fk.reference(); + return { + columns: ref.columns.map((c) => c.name), + table: getTableConfig(ref.foreignTable).name, + foreignColumns: ref.foreignColumns.map((c) => c.name), + onDelete: fk.onDelete ?? "no action", + }; + }), + }; +} + +// These repositories select complete financial rows. Auth is limited to the +// owned references, rather than claiming to validate all of Better Auth. +export const FINANCIAL_CONTRACT: TableContract[] = [ + required("Owned workspace references", organization, ["id"]), + required("Import author references", user, ["id"]), + required("Accounts", financialAccount), + required("Transactions", transaction), + required("Statement imports", importBatch), + required("Categorization", category), + required("Categorization", categoryRule), + required("Recurring payments", recurringSeries), + required("Budgets", budget), + required("Bills", billDetails), + required("Bills", billCycle), + required("Bills", billPayment), +]; diff --git a/scripts/db/schema-check.ts b/scripts/db/schema-check.ts new file mode 100644 index 0000000..4127810 --- /dev/null +++ b/scripts/db/schema-check.ts @@ -0,0 +1,78 @@ +import type { Reference, TableContract } from "./contract"; + +export type TableFacts = { + name: string; + columns: { name: string; type: string; notNull: boolean }[]; + unique: { columns: string[]; valid: boolean }[]; + references: (Reference & { validated: boolean; schema: string })[]; + readable: boolean; +}; +export type SchemaIssue = { feature: string; object: string; problem: string }; + +const sameColumns = (a: string[], b: string[]) => + a.length === b.length && + [...a].sort().every((c, i) => c === [...b].sort()[i]); +function sameReference(a: Reference, b: Reference): boolean { + const mapping = (r: Reference) => + r.columns + .map((c, i) => `${c}:${r.foreignColumns[i]}`) + .sort() + .join(","); + return ( + a.table === b.table && + a.onDelete === b.onDelete && + mapping(a) === mapping(b) + ); +} + +/** Names of constraints/indexes are immaterial; their valid semantics matter. */ +export function compareSchema( + contract: readonly TableContract[], + facts: readonly TableFacts[], + schema = "public", +): SchemaIssue[] { + const issues: SchemaIssue[] = []; + for (const expected of contract) { + const issue = (object: string, problem: string) => + issues.push({ + feature: expected.feature, + object: `${expected.name}${object}`, + problem, + }); + const actual = facts.find((t) => t.name === expected.name); + if (!actual) { + issue("", "required table is missing"); + continue; + } + for (const column of expected.columns) { + const found = actual.columns.find((c) => c.name === column.name); + if (!found) issue(`.${column.name}`, "required column is missing"); + else if (found.type !== column.type || found.notNull !== column.notNull) + issue( + `.${column.name}`, + `requires ${column.type}${column.notNull ? " NOT NULL" : " nullable"}`, + ); + } + for (const columns of expected.unique) + if ( + !actual.unique.some((i) => i.valid && sameColumns(columns, i.columns)) + ) + issue( + ` (${columns.join(", ")})`, + "valid unconditional uniqueness is missing", + ); + for (const ref of expected.references) + if ( + !actual.references.some( + (f) => f.validated && f.schema === schema && sameReference(ref, f), + ) + ) + issue( + ` (${ref.columns.join(", ")})`, + `validated ownership/reference to ${ref.table} is missing`, + ); + if (!actual.readable) + issue("", "required columns cannot be read by this role"); + } + return issues; +} diff --git a/scripts/db/verify.test.ts b/scripts/db/verify.test.ts new file mode 100644 index 0000000..44c4bc5 --- /dev/null +++ b/scripts/db/verify.test.ts @@ -0,0 +1,433 @@ +import { execFileSync, spawnSync } from "node:child_process"; +import { randomUUID } from "node:crypto"; +import { drizzle } from "drizzle-orm/node-postgres"; +import { migrate } from "drizzle-orm/node-postgres/migrator"; +import pg from "pg"; +import { describe, expect, it, vi } from "vitest"; +import { FINANCIAL_CONTRACT } from "./contract"; +import { compareSchema, type TableFacts } from "./schema-check"; +import { readJournal } from "./inspect"; +import { TargetError } from "./target"; +import { + formatVerification, + runVerification, + safeFailure, + verifyConnected, +} from "./verify"; + +function compatible(): TableFacts[] { + return FINANCIAL_CONTRACT.map((t) => ({ + ...structuredClone(t), + readable: true, + unique: t.unique.map((columns) => ({ columns, valid: true })), + references: t.references.map((f) => ({ + ...f, + validated: true, + schema: "public", + })), + })); +} +describe("schema contract comparison", () => { + it("accepts equivalent renamed/reordered uniqueness, owned references and extras without mutating inputs", () => { + const facts = compatible(); + facts.forEach((t) => + t.unique.forEach((i) => (i.columns = [...i.columns].reverse())), + ); + facts[0]!.columns.push({ + name: "future_column", + type: "text", + notNull: false, + }); + const before = structuredClone(facts); + expect(compareSchema(FINANCIAL_CONTRACT, facts)).toEqual([]); + expect(facts).toEqual(before); + }); + it("rejects missing tables, columns, nullability, types and invalid/partial uniqueness", () => { + const facts = compatible().filter((t) => t.name !== "budget"); + const row = facts.find((t) => t.name === "transaction")!; + row.columns = row.columns.filter((c) => c.name !== "transfer_pair_id"); + row.columns.find((c) => c.name === "amount_cents")!.type = "integer"; + row.columns.find((c) => c.name === "is_transfer")!.notNull = false; + row.unique.forEach((i) => (i.valid = false)); + const issues = compareSchema(FINANCIAL_CONTRACT, facts); + expect(issues.some((i) => i.object === "budget")).toBe(true); + expect( + issues.some((i) => i.object === "transaction.transfer_pair_id"), + ).toBe(true); + expect(issues.some((i) => i.object === "transaction.amount_cents")).toBe( + true, + ); + expect(issues.some((i) => i.object === "transaction.is_transfer")).toBe( + true, + ); + expect(issues.some((i) => i.problem.includes("uniqueness"))).toBe(true); + }); + it("rejects unvalidated, wrong-schema and incorrect-delete ownership references and inaccessible reads", () => { + const facts = compatible(); + const bill = facts.find((t) => t.name === "bill_payment")!; + bill.readable = false; + bill.references.forEach((f) => (f.validated = false)); + expect( + compareSchema(FINANCIAL_CONTRACT, facts).some((i) => + i.problem.includes("cannot be read"), + ), + ).toBe(true); + bill.references.forEach((f) => { + f.validated = true; + f.schema = "other"; + }); + expect( + compareSchema(FINANCIAL_CONTRACT, facts).filter((i) => + i.problem.includes("reference"), + ).length, + ).toBe(bill.references.length); + bill.references.forEach((f) => { + f.schema = "public"; + f.onDelete = "restrict"; + }); + expect( + compareSchema(FINANCIAL_CONTRACT, facts).some((i) => + i.problem.includes("reference"), + ), + ).toBe(true); + }); +}); +describe("secret-safe diagnostics", () => { + it("keeps journal warnings distinct from schema availability", () => { + const text = formatVerification({ + issues: [], + migrations: { + applied: [], + pending: ["0010_monthly_budgets"], + unknown: 1, + }, + }).join("\n"); + expect(text).toContain("Schema: READY"); + expect(text).toContain("later recovery"); + expect(text).toContain("outside this checkout"); + expect(text).toContain("Write privileges were not checked"); + expect( + formatVerification({ issues: [], migrations: null }).join("\n"), + ).toContain("journal is unreadable"); + }); + it("prints required feature/object and diagnostic steps on failure", () => { + expect( + formatVerification({ + issues: [ + { + feature: "Budgets", + object: "budget", + problem: "required table is missing", + }, + ], + migrations: null, + }).join("\n"), + ).toMatch(/NOT READY[\s\S]*Budgets: budget[\s\S]*No repairs/); + }); + it("suppresses arbitrary errors, including URLs, passwords and driver messages", () => { + const secret = "postgres://name:private-secret@host/database"; + expect(safeFailure(new Error(secret))).not.toContain(secret); + expect(safeFailure(null)).toContain("suppressed"); + expect(safeFailure({ code: "42501", message: secret })).toContain( + "permission denied", + ); + expect(safeFailure(new TargetError(secret))).not.toContain(secret); + expect(safeFailure(new TargetError("Choose a target"))).toContain( + "--target", + ); + }); + it("bounds and closes a client even when connecting fails", async () => { + const end = vi.fn(); + const connect = vi.fn().mockRejectedValue(new Error("private URL")); + const Constructor = vi.spyOn(pg, "Client").mockImplementation(function () { + return { connect, end, on: vi.fn() } as unknown as pg.Client; + }); + try { + await expect( + runVerification("postgres://test:test@localhost:1/test"), + ).rejects.toThrow("private URL"); + expect(Constructor).toHaveBeenCalledWith( + expect.objectContaining({ + connectionTimeoutMillis: 10000, + query_timeout: 10000, + }), + ); + expect(end).toHaveBeenCalledOnce(); + } finally { + Constructor.mockRestore(); + } + }); +}); + +async function isolated( + run: (client: pg.Client, url: string) => Promise, +) { + const url = new URL(process.env.DATABASE_URL!); + if (!["localhost", "127.0.0.1", "[::1]"].includes(url.hostname)) + throw new Error("Readiness fault fixtures require local PostgreSQL"); + const name = `readiness_test_${randomUUID().replaceAll("-", "")}`; + const admin = new pg.Client({ connectionString: url.toString() }); + await admin.connect(); + let client: pg.Client | undefined; + let created = false; + try { + await admin.query(`CREATE DATABASE "${name}"`); + created = true; + url.pathname = `/${name}`; + client = new pg.Client({ connectionString: url.toString() }); + await client.connect(); + await migrate(drizzle(client), { + migrationsFolder: "src/lib/db/migrations", + }); + await run(client, url.toString()); + } finally { + try { + await client?.end(); + if (created) await admin.query(`DROP DATABASE "${name}"`); + } finally { + await admin.end(); + } + } +} + +describe("real PostgreSQL readiness", () => { + it("is schema-ready and performs only read-only queries without touching facts or schema", async () => { + await isolated(async (client) => { + const before = await client.query( + "SELECT table_name FROM information_schema.tables WHERE table_schema='public' ORDER BY table_name", + ); + const query = vi.spyOn(client, "query"); + const result = await verifyConnected(client); + expect(result.issues).toEqual([]); + expect(result.migrations?.pending).toEqual([]); + const statements = query.mock.calls.map((args) => String(args[0]).trim()); + expect(statements[0]).toContain("READ ONLY"); + expect( + statements.every((q) => + /^(SELECT|BEGIN|COMMIT|SET LOCAL|SAVEPOINT|RELEASE|ROLLBACK)/i.test( + q, + ), + ), + ).toBe(true); + expect(statements.filter((q) => q.includes("LIMIT 0"))).toHaveLength( + FINANCIAL_CONTRACT.length, + ); + query.mockRestore(); + expect( + ( + await client.query( + "SELECT table_name FROM information_schema.tables WHERE table_schema='public' ORDER BY table_name", + ) + ).rows, + ).toEqual(before.rows); + expect( + (await client.query('SELECT count(*) AS count FROM "transaction"')) + .rows[0]?.count, + ).toBe("0"); + }); + }); + it.each(["budget", "recurring_series", "bill_cycle"])( + "SELECT 1 succeeds while missing %s fails readiness", + async (table) => { + await isolated(async (client) => { + await client.query(`DROP TABLE "${table}" CASCADE`); + expect((await client.query("SELECT 1 AS connected")).rows[0]).toEqual({ + connected: 1, + }); + expect( + (await verifyConnected(client)).issues.some( + (i) => i.object === table, + ), + ).toBe(true); + }); + }, + ); + it.each([ + [ + 'ALTER TABLE "transaction" DROP COLUMN transfer_pair_id', + "transaction.transfer_pair_id", + ], + [ + 'ALTER TABLE "transaction" ALTER COLUMN amount_cents TYPE numeric', + "transaction.amount_cents", + ], + [ + 'ALTER TABLE "transaction" ALTER COLUMN is_transfer DROP NOT NULL', + "transaction.is_transfer", + ], + [ + "ALTER TABLE budget DROP CONSTRAINT budget_workspace_category_fk", + "budget (workspace_id, category_id)", + ], + [ + "DROP INDEX budget_workspace_month_category_uidx", + "budget (workspace_id, month, category_id)", + ], + ])("detects schema fault: %s", async (fault, object) => { + await isolated(async (client) => { + await client.query(fault); + expect( + (await verifyConnected(client)).issues.some((i) => i.object === object), + ).toBe(true); + }); + }); + it("accepts renamed constraints and compatible extras, but rejects unvalidated references", async () => { + await isolated(async (client) => { + await client.query( + "ALTER TABLE budget RENAME CONSTRAINT budget_workspace_category_fk TO compatible_owned_category", + ); + await client.query( + "ALTER INDEX budget_workspace_month_category_uidx RENAME TO compatible_unique", + ); + await client.query( + "ALTER TABLE budget ADD COLUMN future_metadata text; CREATE TABLE future_feature (id text)", + ); + expect((await verifyConnected(client)).issues).toEqual([]); + await client.query( + "ALTER TABLE budget DROP CONSTRAINT compatible_owned_category", + ); + await client.query( + "ALTER TABLE budget ADD CONSTRAINT unvalidated_owned_category FOREIGN KEY (workspace_id, category_id) REFERENCES category(workspace_id,id) ON DELETE CASCADE NOT VALID", + ); + expect( + (await verifyConnected(client)).issues.some( + (i) => i.object === "budget (workspace_id, category_id)", + ), + ).toBe(true); + }); + }); + it("does not accept a partial or failed concurrent unique index", async () => { + await isolated(async (client) => { + await client.query("DROP INDEX budget_workspace_month_category_uidx"); + await client.query( + "CREATE UNIQUE INDEX partial_budget_unique ON budget(workspace_id,month,category_id) WHERE amount_cents > 0", + ); + expect( + (await verifyConnected(client)).issues.some( + (i) => i.object === "budget (workspace_id, month, category_id)", + ), + ).toBe(true); + await client.query("DROP INDEX partial_budget_unique"); + await client.query( + "INSERT INTO organization(id,name,slug,created_at) VALUES('w','Synthetic','readiness-test',now())", + ); + await client.query( + "INSERT INTO category(id,workspace_id,name,sort_order,preset_key) VALUES('c','w','Synthetic',1,'test')", + ); + await client.query( + "INSERT INTO budget(id,workspace_id,category_id,month,amount_cents) VALUES('b1','w','c','2026-10',100),('b2','w','c','2026-10',200)", + ); + await expect( + client.query( + "CREATE UNIQUE INDEX CONCURRENTLY invalid_budget_unique ON budget(workspace_id,month,category_id)", + ), + ).rejects.toMatchObject({ code: "23505" }); + expect( + ( + await client.query( + "SELECT indisvalid FROM pg_index WHERE indexrelid='invalid_budget_unique'::regclass", + ) + ).rows[0]?.indisvalid, + ).toBe(false); + expect( + (await verifyConnected(client)).issues.some( + (i) => i.object === "budget (workspace_id, month, category_id)", + ), + ).toBe(true); + }); + }); + it("requires zero-row read access, but treats journal access as diagnostic", async () => { + await isolated(async (client) => { + const role = `readiness_role_${randomUUID().replaceAll("-", "")}`; + await client.query(`CREATE ROLE "${role}"`); + try { + await client.query( + `GRANT USAGE ON SCHEMA public TO "${role}"; GRANT SELECT ON ALL TABLES IN SCHEMA public TO "${role}"`, + ); + await client.query(`SET ROLE "${role}"`); + const result = await verifyConnected(client); + expect(result.issues).toEqual([]); + expect(result.migrations).toBeNull(); + await client.query("RESET ROLE"); + await client.query( + `REVOKE SELECT ON budget FROM "${role}"; SET ROLE "${role}"`, + ); + expect( + (await verifyConnected(client)).issues.some( + (i) => + i.object === "budget" && i.problem.includes("cannot be read"), + ), + ).toBe(true); + } finally { + await client.query("RESET ROLE"); + await client.query(`DROP OWNED BY "${role}"; DROP ROLE "${role}"`); + } + }); + }); + it("accepts recovered schema despite a skipped timestamp and newer journal entries", async () => { + await isolated(async (client) => { + const original = readJournal().find( + (e) => e.tag === "0010_monthly_budgets", + )!; + await client.query( + "DELETE FROM drizzle.__drizzle_migrations WHERE created_at=$1", + [original.when], + ); + await client.query( + "INSERT INTO drizzle.__drizzle_migrations(hash,created_at) VALUES('future-test',9999999999999)", + ); + const result = await verifyConnected(client); + expect(result.issues).toEqual([]); + expect(result.migrations).toMatchObject({ + pending: [original.tag], + unknown: 1, + }); + await client.query("DROP TABLE budget CASCADE"); + expect( + (await verifyConnected(client)).issues.some( + (i) => i.object === "budget", + ), + ).toBe(true); + }); + }); + it("runs the actual command against a disposable app target, and fails on missing schema", async () => { + await isolated(async (client, url) => { + const args = [ + "--disable-warning=MODULE_TYPELESS_PACKAGE_JSON", + "--import", + "./scripts/register-paths.ts", + "scripts/db/verify.ts", + "--target", + "app", + ]; + const env = { + ...process.env, + DATABASE_URL: url, + DATABASE_TRANSPORT: "tcp", + }; + expect( + execFileSync(process.execPath, args, { env, encoding: "utf8" }), + ).toContain("Schema: READY"); + await client.query("DROP TABLE budget CASCADE"); + const failure = spawnSync(process.execPath, args, { + env, + encoding: "utf8", + }); + expect(failure.status).toBe(1); + expect(failure.stdout).toContain("Budgets: budget"); + expect(failure.stdout + failure.stderr).not.toContain(url); + const unavailable = spawnSync(process.execPath, args, { + env: { + ...env, + DATABASE_URL: "postgres://name:private-secret@127.0.0.1:1/test", + }, + encoding: "utf8", + }); + expect(unavailable.status).toBe(1); + expect(unavailable.stderr).toContain( + "connection or catalog query unavailable", + ); + expect(unavailable.stderr).not.toContain("private-secret"); + }); + }); +}); diff --git a/scripts/db/verify.ts b/scripts/db/verify.ts new file mode 100644 index 0000000..2373c91 --- /dev/null +++ b/scripts/db/verify.ts @@ -0,0 +1,155 @@ +// `pnpm db:verify --target app|local|branch|production`: no repair or writes. +import { Agent } from "node:https"; +import { parseArgs } from "node:util"; +import { Client as NeonClient, neonConfig } from "@neondatabase/serverless"; +import pg from "pg"; +import WebSocket from "ws"; +import { inspectSchema } from "./catalog"; +import { FINANCIAL_CONTRACT } from "./contract"; +import { compareMigrations, readJournal, type MigrationState } from "./inspect"; +import { compareSchema, type SchemaIssue } from "./schema-check"; +import { + loadLocalEnv, + parseTargetName, + resolveTarget, + TargetError, +} from "./target"; +import { formatTarget } from "./whoami"; + +export type Verification = { + issues: SchemaIssue[]; + migrations: MigrationState | null; +}; + +export async function verifyConnected( + client: pg.Client | Pick, +): Promise { + await client.query("BEGIN ISOLATION LEVEL REPEATABLE READ READ ONLY"); + try { + await client.query("SET LOCAL statement_timeout = '5s'"); + await client.query("SET LOCAL lock_timeout = '2s'"); + const issues = compareSchema( + FINANCIAL_CONTRACT, + await inspectSchema(client, FINANCIAL_CONTRACT), + ); + let migrations: MigrationState | null = null; + await client.query("SAVEPOINT journal_probe"); + try { + const exists = await client.query<{ found: string | null }>( + "SELECT to_regclass('drizzle.__drizzle_migrations') AS found", + ); + const rows = exists.rows[0]?.found + ? ( + await client.query<{ created_at: string }>( + "SELECT created_at FROM drizzle.__drizzle_migrations", + ) + ).rows + : []; + migrations = compareMigrations( + readJournal(), + rows.map((r) => Number(r.created_at)), + ); + } catch (error) { + await client.query("ROLLBACK TO SAVEPOINT journal_probe"); + if ((error as { code?: string }).code !== "42501") throw error; + } finally { + await client.query("RELEASE SAVEPOINT journal_probe"); + } + await client.query("COMMIT"); + return { issues, migrations }; + } catch (error) { + await client.query("ROLLBACK"); + throw error; + } +} + +export function formatVerification(result: Verification): string[] { + const lines = [ + result.issues.length + ? "Schema: NOT READY" + : "Schema: READY for this checkout's financial-page contract", + ]; + for (const issue of result.issues) + lines.push(` ${issue.feature}: ${issue.object}: ${issue.problem}`); + if (!result.migrations) + lines.push( + "Warning: migration journal is unreadable by this role; schema checks are independent.", + ); + else { + if (result.migrations.pending.length) + lines.push( + `Warning: unrecorded migrations: ${result.migrations.pending.join(", ")}. A later recovery may provide compatible schema.`, + ); + if (result.migrations.unknown) + lines.push( + `Warning: ${result.migrations.unknown} migration timestamp(s) are outside this checkout.`, + ); + } + lines.push( + "Checked SELECT access with zero-row queries. Write privileges were not checked.", + ); + if (result.issues.length) + lines.push( + "Next: confirm the target/app role, inspect db:whoami and migration SQL; diagnose missing objects before any separately authorized migration. No repairs were attempted.", + ); + return lines; +} + +export function safeFailure(error: unknown): string { + if (error instanceof TargetError) + return "Verification refused: choose --target app, local, branch or production and check its configured connection variable."; + if ((error as { code?: string } | null)?.code === "42501") + return "Verification failed: permission denied. Check catalog/schema access for the intended app role."; + return "Verification failed: connection or catalog query unavailable. Check target credentials, approved network access and timeouts. Driver details are suppressed."; +} + +export async function runVerification( + url: string, + websocket = false, +): Promise { + if (websocket) { + const agent = new Agent({ keepAlive: true, proxyEnv: process.env }); + neonConfig.webSocketConstructor = class extends WebSocket { + constructor(address: string, protocols?: string | string[]) { + super(address, protocols, { agent }); + } + }; + } + const Constructor = websocket ? NeonClient : pg.Client; + const runtimeClient = new Constructor({ + connectionString: url, + connectionTimeoutMillis: 10_000, + query_timeout: 10_000, + }); + // An idle disconnect must not print an unhandled driver's error. + runtimeClient.on("error", () => {}); + const client: Pick & { + connect(): Promise; + } = runtimeClient; + try { + await client.connect(); + return await verifyConnected(client); + } finally { + await client.end(); + } +} + +async function main() { + loadLocalEnv(); + const { values } = parseArgs({ + options: { target: { type: "string", default: "app" } }, + }); + const target = resolveTarget(parseTargetName(values.target), process.env); + console.log(formatTarget(target, process.env).join("\n")); + const result = await runVerification( + target.url, + target.name !== "local" && process.env.DATABASE_TRANSPORT === "websocket", + ); + console.log(formatVerification(result).join("\n")); + if (result.issues.length) process.exitCode = 1; +} +if (import.meta.main) + main().catch((error: unknown) => { + console.error(safeFailure(error)); + process.exitCode = 1; + }); diff --git a/src/app/(app)/w/[workspaceId]/transactions/[transactionId]/page.tsx b/src/app/(app)/w/[workspaceId]/transactions/[transactionId]/page.tsx index 2774928..c87dcc4 100644 --- a/src/app/(app)/w/[workspaceId]/transactions/[transactionId]/page.tsx +++ b/src/app/(app)/w/[workspaceId]/transactions/[transactionId]/page.tsx @@ -62,8 +62,11 @@ async function EditTransaction({ params }: Props) { nickname, type, }))} - ledgerEditable={transaction.editableInFull} - fixedSummary={`${formatSigned(transaction.amountCents)} on ${transaction.accountNickname}, ${formatDay(transaction.postedOn)}. This transaction was ${SOURCE_NAMES[transaction.source]}, so its account, date and amount stay as they came.`} + ledgerEditable={ + transaction.editableInFull && transaction.transferPairId === null + } + paired={transaction.transferPairId !== null} + fixedSummary={`${formatSigned(transaction.amountCents)} on ${transaction.accountNickname}, ${formatDay(transaction.postedOn)}. ${transaction.transferPairId !== null ? "Remove pairing in Review transfers before changing financial details or its transfer label." : `This transaction was ${SOURCE_NAMES[transaction.source]}, so its account, date and amount stay as they came.`}`} today={isoDateIn(new Date(), DEFAULT_TIME_ZONE)} submitLabel="Save changes" busyLabel="Saving…" diff --git a/src/app/(app)/w/[workspaceId]/transactions/transfers/error.tsx b/src/app/(app)/w/[workspaceId]/transactions/transfers/error.tsx new file mode 100644 index 0000000..e916b60 --- /dev/null +++ b/src/app/(app)/w/[workspaceId]/transactions/transfers/error.tsx @@ -0,0 +1,19 @@ +"use client"; +export default function TransferError({ + retry, +}: { + error: Error & { digest?: string }; + retry: () => void; +}) { + return ( +
+

Review transfers

+

+ Transfer review is temporarily unavailable. Please try again. +

+ +
+ ); +} diff --git a/src/app/(app)/w/[workspaceId]/transactions/transfers/page.tsx b/src/app/(app)/w/[workspaceId]/transactions/transfers/page.tsx new file mode 100644 index 0000000..2454fdb --- /dev/null +++ b/src/app/(app)/w/[workspaceId]/transactions/transfers/page.tsx @@ -0,0 +1,28 @@ +import type { Metadata } from "next"; +import { Suspense } from "react"; +import { PageLoading } from "@/components/ui/page-loading"; +import { + TransferReviewPage, + loadTransferReview, + reviewTransferAction, +} from "@/features/transfers"; +export const metadata: Metadata = { title: "Review transfers" }; +type Props = PageProps<"/w/[workspaceId]/transactions/transfers">; +async function Review({ params, searchParams }: Props) { + const { workspaceId } = await params; + const data = await loadTransferReview(workspaceId, await searchParams); + return ( + + ); +} +export default function TransfersRoute(props: Props) { + return ( + }> + + + ); +} diff --git a/src/features/cashflow/domain/cashflow.ts b/src/features/cashflow/domain/cashflow.ts index bd31f1c..9e98f04 100644 --- a/src/features/cashflow/domain/cashflow.ts +++ b/src/features/cashflow/domain/cashflow.ts @@ -89,6 +89,8 @@ export type CashflowData = { openingBalance: Cents; entries: Entry[]; recurring: Recurring[]; + /** Recorded liquid-account transfers affect balances, but never activity totals. */ + balanceOnly?: { date: IsoDate; amount: Cents }[]; }; export type Item = Omit & { @@ -205,9 +207,17 @@ function balanceBefore( ): Cents { let balance = data.openingBalance; for (let i = 0; i < monthsApart(data.start, month); i += 1) { + const previous = addMonths(data.start, i); balance = add( balance, - balanceChange(monthItems(data, addMonths(data.start, i), today)), + add( + balanceChange(monthItems(data, previous, today)), + sum( + (data.balanceOnly ?? []) + .filter((row) => row.date.startsWith(monthPrefix(previous))) + .map((row) => row.amount), + ), + ), ); } return balance; @@ -238,7 +248,17 @@ export function buildMonth( ); if (everydaySpent > largestEverydaySpend) largestEverydaySpend = everydaySpent; - balance = add(balance, balanceChange(dayItems)); + balance = add( + balance, + add( + balanceChange(dayItems), + sum( + (data.balanceOnly ?? []) + .filter((row) => row.date === date) + .map((row) => row.amount), + ), + ), + ); return { date, day: index + 1, diff --git a/src/features/cashflow/domain/from-records.test.ts b/src/features/cashflow/domain/from-records.test.ts index fef64df..1c09c3f 100644 --- a/src/features/cashflow/domain/from-records.test.ts +++ b/src/features/cashflow/domain/from-records.test.ts @@ -292,3 +292,112 @@ describe("toCashflowData", () => { expect(summarize(data, TODAY).balanceToday).toBe(150000); }); }); + +describe("recorded transfers preserve every balance", () => { + it("keeps a card purchase as spending, excludes repayment from totals and preserves daily balances", () => { + const accounts = [{ ...CHECKING, balanceCents: cents(50000) }, CARD]; + const transactions = [ + row({ + postedOn: "2026-10-01", + accountId: CARD.id, + amountCents: cents(-4500), + }), + row({ postedOn: "2026-10-05", amountCents: cents(-20000) }), + row({ + postedOn: "2026-10-06", + accountId: CARD.id, + amountCents: cents(20000), + }), + ]; + const before = toCashflowData({ accounts, transactions, today: TODAY }); + const after = toCashflowData({ + accounts, + transactions: transactions.map((r, i) => ({ ...r, isTransfer: i > 0 })), + today: TODAY, + }); + expect(after.openingBalance).toBe(70000); + expect( + buildMonth(after, { year: 2026, month: 10 }, TODAY).days.map( + (d) => d.endBalance, + ), + ).toEqual( + buildMonth(before, { year: 2026, month: 10 }, TODAY).days.map( + (d) => d.endBalance, + ), + ); + expect(summarize(after, TODAY)).toMatchObject({ + balanceToday: 50000, + monthIn: 0, + monthOut: 4500, + biggestCategory: { total: 4500, count: 1 }, + }); + }); + it.each([ + ["2026-09-30", "2026-10-02", TODAY], + ["2026-12-31", "2027-01-02", "2027-01-05"], + ])( + "preserves liquid transfer timing across %s to %s", + (outOn, inOn, today) => { + const transactions = [ + row({ postedOn: outOn, amountCents: cents(-10001) }), + row({ + postedOn: inOn, + accountId: SAVINGS.id, + amountCents: cents(10001), + }), + ]; + const before = toCashflowData({ + accounts: [CHECKING, SAVINGS], + transactions, + today, + }); + const after = toCashflowData({ + accounts: [CHECKING, SAVINGS], + transactions: transactions.map((r) => ({ ...r, isTransfer: true })), + today, + }); + expect(after.start).toEqual(before.start); + for (const month of [ + before.start, + { year: Number(today.slice(0, 4)), month: Number(today.slice(5, 7)) }, + ]) + expect( + buildMonth(after, month, today).days.map((d) => d.endBalance), + ).toEqual( + buildMonth(before, month, today).days.map((d) => d.endBalance), + ); + expect(summarize(after, today)).toMatchObject({ + balanceToday: 200000, + monthIn: 0, + monthOut: 0, + }); + expect(after.entries).toEqual([]); + }, + ); + it("preserves same-day checking to savings and excludes a labelled loan leg", () => { + const data = toCashflowData({ + accounts: [CHECKING, SAVINGS, LOAN], + transactions: [ + row({ postedOn: TODAY, amountCents: cents(-10000), isTransfer: true }), + row({ + postedOn: TODAY, + accountId: SAVINGS.id, + amountCents: cents(10000), + isTransfer: true, + }), + row({ + postedOn: TODAY, + accountId: LOAN.id, + amountCents: cents(10000), + isTransfer: true, + }), + ], + today: TODAY, + }); + expect(summarize(data, TODAY)).toMatchObject({ + balanceToday: 200000, + monthIn: 0, + monthOut: 0, + }); + }); +}); diff --git a/src/features/cashflow/domain/from-records.ts b/src/features/cashflow/domain/from-records.ts index 958d94b..6a615bd 100644 --- a/src/features/cashflow/domain/from-records.ts +++ b/src/features/cashflow/domain/from-records.ts @@ -86,8 +86,8 @@ export function kindOf(record: { * checking and savings accounts, as the Accounts page shows it; the opening * balance is worked back from it through this window's transactions up to * today. Card rows show as spending without moving that balance. Transfers - * between the workspace's own accounts (ADR-020) and loan accounts' own rows - * are left out. + * affect the balance line without counting as spending or income (ADR-020). + * Loan accounts' own rows are left out. */ export function toCashflowData({ accounts, @@ -100,19 +100,18 @@ export function toCashflowData({ }): CashflowData { const byId = new Map(accounts.map((account) => [account.id, account])); const window = dashboardWindow(today); - const shown = transactions.filter((record) => { + const recorded = transactions.filter((record) => { const account = byId.get(record.accountId); return ( account !== undefined && account.type !== "loan" && - !record.isTransfer && record.postedOn >= window.from && record.postedOn <= window.to ); }); const thisMonth = monthOf(today); - const oldest = shown.reduce( + const oldest = recorded.reduce( (found, record) => found === null || record.postedOn < found ? record.postedOn : found, null, @@ -123,35 +122,46 @@ export function toCashflowData({ : thisMonth; const named = accounts.length > 1; - const entries = shown.map((record): Entry => { - const account = byId.get(record.accountId)!; - return { - id: record.id, - date: record.postedOn, - name: record.description, - amount: record.amountCents, - kind: kindOf(record), - category: record.categoryName ?? UNCATEGORIZED, - source: sourceOf(record.source), - accountName: named ? account.nickname : undefined, - onCard: !isLiquid(account), - removable: record.editableInFull, - }; - }); + const entries = recorded + .filter((record) => !record.isTransfer) + .map((record): Entry => { + const account = byId.get(record.accountId)!; + return { + id: record.id, + date: record.postedOn, + name: record.description, + amount: record.amountCents, + kind: kindOf(record), + category: record.categoryName ?? UNCATEGORIZED, + source: sourceOf(record.source), + accountName: named ? account.nickname : undefined, + onCard: !isLiquid(account), + removable: record.editableInFull, + }; + }); const balanceToday = sum( accounts.filter(isLiquid).map((a) => a.balanceCents), ); const sinceStart = sum( - entries - .filter((entry) => !entry.onCard && entry.date <= today) - .map((entry) => entry.amount), + recorded + .filter( + (record) => + isLiquid(byId.get(record.accountId)!) && record.postedOn <= today, + ) + .map((record) => record.amountCents), ); + const balanceOnly = recorded + .filter( + (record) => record.isTransfer && isLiquid(byId.get(record.accountId)!), + ) + .map((record) => ({ date: record.postedOn, amount: record.amountCents })); return { start, openingBalance: subtract(balanceToday, sinceStart), entries, recurring: [], + ...(balanceOnly.length ? { balanceOnly } : {}), }; } diff --git a/src/features/transactions/domain/transaction-input.test.ts b/src/features/transactions/domain/transaction-input.test.ts index fb107cc..3eaeb62 100644 --- a/src/features/transactions/domain/transaction-input.test.ts +++ b/src/features/transactions/domain/transaction-input.test.ts @@ -185,6 +185,7 @@ describe("formValues", () => { description: "Lunch", status: "pending", isTransfer: false, + transferPairId: null, source: "manual", editableInFull: true, }; diff --git a/src/features/transactions/domain/transaction-input.ts b/src/features/transactions/domain/transaction-input.ts index 52dcca3..5cc449b 100644 --- a/src/features/transactions/domain/transaction-input.ts +++ b/src/features/transactions/domain/transaction-input.ts @@ -30,6 +30,7 @@ export type TransactionSummary = { description: string; status: "pending" | "posted"; isTransfer: boolean; + transferPairId: string | null; source: DataSource; /** * Only manual transactions can change account, date, amount or status; diff --git a/src/features/transactions/server/actions.ts b/src/features/transactions/server/actions.ts index 39482d3..9a2de79 100644 --- a/src/features/transactions/server/actions.ts +++ b/src/features/transactions/server/actions.ts @@ -94,7 +94,7 @@ export async function updateTransactionAction( const parsed = parseTransactionForm(Object.fromEntries(formData), { today: today(), - ledgerEditable: existing.editableInFull, + ledgerEditable: existing.editableInFull && existing.transferPairId === null, }); if (!parsed.ok) return rejected(parsed.errors, formData); @@ -103,6 +103,22 @@ export async function updateTransactionAction( if (result === "no such account") { return rejected({ accountId: NO_SUCH_ACCOUNT }, formData); } + if (result === "paired") + return rejected( + { + transfer: + "Remove pairing in Review transfers before changing its financial fields or transfer label.", + }, + formData, + ); + if (result === "payment evidence") + return rejected( + { + transfer: + "This transaction is linked to a bill. Unlink its payment evidence in Bills before changing its transfer label.", + }, + formData, + ); redirect(listHref(verified)); } diff --git a/src/features/transactions/server/repository.test.ts b/src/features/transactions/server/repository.test.ts index 8eb0e08..810266d 100644 --- a/src/features/transactions/server/repository.test.ts +++ b/src/features/transactions/server/repository.test.ts @@ -98,6 +98,7 @@ describe("createTransaction", () => { description: "Lunch", status: "posted", isTransfer: false, + transferPairId: null, source: "manual", editableInFull: true, }); diff --git a/src/features/transactions/server/repository.ts b/src/features/transactions/server/repository.ts index c9b0e89..0d41b6f 100644 --- a/src/features/transactions/server/repository.ts +++ b/src/features/transactions/server/repository.ts @@ -1,8 +1,12 @@ import "server-only"; -import { and, asc, count, desc, eq, gte, lte } from "drizzle-orm"; +import { and, asc, count, desc, eq, gte, inArray, lte } from "drizzle-orm"; import { db } from "@/lib/db/client"; import { getCategoryMetadata } from "@/features/categorization"; import { uuidv7 } from "@/lib/db/id"; +import { + hasBillEvidence, + lockLedgerWorkspace, +} from "@/lib/db/transaction-guards"; import { category, financialAccount, transaction } from "@/lib/db/schema"; import { type Cents, add, cents, negate } from "@/lib/money"; import { @@ -32,6 +36,7 @@ const columns = { description: transaction.descriptionRaw, status: transaction.status, isTransfer: transaction.isTransfer, + transferPairId: transaction.transferPairId, source: transaction.source, }; @@ -310,7 +315,8 @@ export async function countTextTransactions( return row?.logged ?? 0; } -export type UpdateResult = "updated" | "not found" | "no such account"; +export type UpdateResult = + "updated" | "not found" | "no such account" | "paired" | "payment evidence"; /** * Updates a transaction. Account, date, amount and status change only on a @@ -323,6 +329,7 @@ export async function updateTransaction( input: TransactionInput, ): Promise { return db.transaction(async (tx) => { + await lockLedgerWorkspace(tx, workspaceId); const [existing] = await tx .select({ accountId: transaction.financialAccountId, @@ -331,6 +338,9 @@ export async function updateTransaction( source: transaction.source, categoryId: transaction.categoryId, categoryIsManual: transaction.categoryIsManual, + status: transaction.status, + isTransfer: transaction.isTransfer, + transferPairId: transaction.transferPairId, }) .from(transaction) .where(inWorkspace(workspaceId, transactionId)) @@ -338,6 +348,21 @@ export async function updateTransaction( if (!existing) return "not found"; const ledger = isTyped(existing.source) ? input.ledger : null; + if ( + existing.transferPairId !== null && + (existing.isTransfer !== input.isTransfer || + (ledger && + (ledger.accountId !== existing.accountId || + ledger.postedOn !== existing.postedOn || + ledger.amountCents !== existing.amountCents || + ledger.status !== existing.status))) + ) + return "paired"; + if ( + existing.isTransfer !== input.isTransfer && + (await hasBillEvidence(tx, workspaceId, [transactionId])) + ) + return "payment evidence"; if (ledger) { // Lock both accounts in id order, so two edits cannot deadlock. const ids = [...new Set([existing.accountId, ledger.accountId])].sort(); @@ -410,6 +435,38 @@ export async function deleteTransaction( transactionId: string, ): Promise { return db.transaction(async (tx) => { + await lockLedgerWorkspace(tx, workspaceId); + const [existing] = await tx + .select({ pairId: transaction.transferPairId }) + .from(transaction) + .where(inWorkspace(workspaceId, transactionId)); + if (!existing) return false; + const affected = + existing.pairId === null + ? [transactionId] + : ( + await tx + .select({ id: transaction.id }) + .from(transaction) + .where( + and( + eq(transaction.workspaceId, workspaceId), + eq(transaction.transferPairId, existing.pairId), + ), + ) + .orderBy(asc(transaction.id)) + ).map((r) => r.id); + await tx + .select({ id: transaction.id }) + .from(transaction) + .where( + and( + eq(transaction.workspaceId, workspaceId), + inArray(transaction.id, affected), + ), + ) + .orderBy(asc(transaction.id)) + .for("update"); const [deleted] = await tx .delete(transaction) .where(inWorkspace(workspaceId, transactionId)) @@ -421,6 +478,18 @@ export async function deleteTransaction( }); if (!deleted) return false; + const survivors = affected.filter((id) => id !== transactionId); + if (survivors.length) + await tx + .update(transaction) + .set({ transferPairId: null }) + .where( + and( + eq(transaction.workspaceId, workspaceId), + inArray(transaction.id, survivors), + ), + ); + if (isTyped(deleted.source)) { const account = await lockAccount(tx, workspaceId, deleted.accountId); if (account) { diff --git a/src/features/transactions/ui/transaction-form.tsx b/src/features/transactions/ui/transaction-form.tsx index 9282e51..ca838bd 100644 --- a/src/features/transactions/ui/transaction-form.tsx +++ b/src/features/transactions/ui/transaction-form.tsx @@ -25,6 +25,7 @@ type Props = { */ ledgerEditable: boolean; fixedSummary?: string; + paired?: boolean; /** "YYYY-MM-DD": the latest date the date field accepts. */ today: string; submitLabel: string; @@ -74,6 +75,7 @@ export function TransactionForm({ accounts, ledgerEditable, fixedSummary, + paired = false, today, submitLabel, busyLabel, @@ -86,6 +88,7 @@ export function TransactionForm({ direction: useId(), amount: useId(), description: useId(), + transfer: useId(), }; const { errors } = state; // After a rejected submit, show what was typed rather than the start values. @@ -226,9 +229,27 @@ export function TransactionForm({ type="checkbox" name="transfer" defaultChecked={value("transfer") === "on"} + disabled={paired} + aria-invalid={errors.transfer !== undefined} + aria-describedby={ + errors.transfer ? `${ids.transfer}-error` : undefined + } /> Transfer between my own accounts (not spending or income) + {paired && ( + + )} + +

+ Review transfers to pair + activity or remove a relationship. Linked bill evidence must be reviewed + in{" "} + + Bills + {" "} + before changing its transfer label. +

+

+ Review transfers between your + own accounts and credit-card repayments. +

+ {accounts.length === 0 ? (

Add an account first, then its transactions.{" "} diff --git a/src/features/transfers/client.ts b/src/features/transfers/client.ts new file mode 100644 index 0000000..4409df4 --- /dev/null +++ b/src/features/transfers/client.ts @@ -0,0 +1 @@ +export * from "./domain/review"; diff --git a/src/features/transfers/domain/review.test.ts b/src/features/transfers/domain/review.test.ts new file mode 100644 index 0000000..8fb4619 --- /dev/null +++ b/src/features/transfers/domain/review.test.ts @@ -0,0 +1,209 @@ +import { describe, expect, it } from "vitest"; +import { + calendarGap, + eligible, + matchesFacts, + matchesState, + pairStatus, + reviewQuery, + shiftDay, + writeSchema, + type ReviewRow, +} from "./review"; +const today = "2026-10-11"; +const a: ReviewRow = { + id: crypto.randomUUID(), + workspaceId: crypto.randomUUID(), + accountId: crypto.randomUUID(), + postedOn: today, + amountCents: -20000, + description: "Repayment", + status: "posted", + isTransfer: false, + pairId: null, + updatedAt: "2026-10-11T12:00:00.123456Z", + accountName: "Cash", + accountType: "checking", + ownedAccount: true, +}; +const b = { + ...a, + id: crypto.randomUUID(), + accountId: crypto.randomUUID(), + amountCents: 20000, +}; +describe("explicit transfer review", () => { + it("defaults to 90 inclusive days and accepts older bounded windows", () => { + expect(reviewQuery({}, today)).toMatchObject({ + from: "2026-07-14", + to: today, + page: 1, + matchPage: 1, + view: "review", + }); + expect( + reviewQuery( + { + from: "2025-12-31", + to: "2026-01-03", + account: "", + other: "", + source: "", + page: "2", + matchPage: "3", + view: "all", + }, + today, + ), + ).toMatchObject({ + from: "2025-12-31", + page: 2, + matchPage: 3, + account: undefined, + }); + expect(reviewQuery({ to: "2026-01-01" }, today)?.from).toBe("2025-10-04"); + expect(reviewQuery({ from: "2025-10-11" }, today)).not.toBeNull(); + }); + it.each([ + { from: "2026-02-30" }, + { account: "guess" }, + { page: 0 }, + { matchPage: 101 }, + { from: [today] }, + { from: "1999-12-31" }, + { to: "2026-10-12" }, + { from: "2026-10-10", to: "2026-10-09" }, + { from: "2025-10-10" }, + ])("rejects invalid or excessive query %j", (query) => + expect(reviewQuery(query, today)).toBeNull(), + ); + it("uses calendar days across years, leap days and DST", () => { + expect(shiftDay("2026-01-01", -3)).toBe("2025-12-29"); + expect(shiftDay("2024-02-28", 1)).toBe("2024-02-29"); + expect(calendarGap("2026-03-07", "2026-03-10")).toBe(3); + expect( + eligible( + { ...a, postedOn: "2025-12-31" }, + { ...b, postedOn: "2026-01-03" }, + today, + ), + ).toBe(true); + expect(eligible({ ...a, postedOn: "2026-10-08" }, b, today)).toBe(true); + }); + it("allows individually labelled rows and requires explicit confirmation", () => { + expect(eligible({ ...a, isTransfer: true }, b, today)).toBe(true); + expect( + writeSchema.safeParse({ + operation: "pair", + expected: [a, b], + confirmed: true, + }).success, + ).toBe(true); + expect( + writeSchema.safeParse({ operation: "pair", expected: [a, b] }).success, + ).toBe(false); + expect( + writeSchema.safeParse({ + operation: "pair", + expected: [a], + confirmed: true, + }).success, + ).toBe(false); + expect( + writeSchema.safeParse({ + operation: "detach", + expected: [], + confirmed: true, + }).success, + ).toBe(false); + expect( + writeSchema.safeParse({ + operation: "detach", + expected: Array(51).fill(a), + confirmed: true, + }).success, + ).toBe(false); + expect( + writeSchema.safeParse({ + operation: "label", + expected: [a], + transfer: true, + confirmed: true, + }).success, + ).toBe(true); + }); + it.each([ + { id: a.id }, + { workspaceId: crypto.randomUUID() }, + { accountId: a.accountId }, + { ownedAccount: false }, + { status: "pending" as const }, + { amountCents: 0 }, + { amountCents: -20000 }, + { amountCents: 20001 }, + { amountCents: Number.MAX_SAFE_INTEGER + 1 }, + { postedOn: "2026-02-30" }, + { postedOn: "2026-10-12" }, + { postedOn: "2026-10-07" }, + { pairId: "existing" }, + ])("rejects an ineligible counterpart %j", (patch) => + expect(eligible(a, { ...b, ...patch }, today)).toBe(false), + ); + it.each([ + { ownedAccount: false }, + { status: "pending" as const }, + { amountCents: Number.MAX_SAFE_INTEGER + 1 }, + { amountCents: 0 }, + { postedOn: "invalid" }, + { postedOn: "2026-10-12" }, + { pairId: "old" }, + ])("rejects an ineligible source %j", (patch) => + expect(eligible({ ...a, ...patch }, b, today)).toBe(false), + ); + it("distinguishes confirmed, individual, orphan and invalid legacy groups", () => { + const paired = [ + { ...a, pairId: "p", isTransfer: true }, + { ...b, pairId: "p", isTransfer: true }, + ]; + expect(pairStatus(paired, today)).toBe("confirmed"); + expect(pairStatus([paired[0]!], today)).toBe("incomplete"); + for (const group of [ + [], + [...paired, a], + [a, b], + [paired[0]!, { ...paired[1]!, pairId: "other" }], + [paired[0]!, { ...paired[1]!, isTransfer: false }], + [paired[0]!, { ...paired[1]!, amountCents: 20001 }], + [paired[0]!, { ...paired[1]!, ownedAccount: false }], + [ + { ...a, pairId: "", isTransfer: true }, + { ...b, pairId: "", isTransfer: true }, + ], + ]) + expect(pairStatus(group, today)).toBe("invalid"); + }); + it("compares all expected facts, classification and microsecond version", () => { + expect(matchesFacts(a, a)).toBe(true); + expect(matchesState(a, a)).toBe(true); + for (const patch of [ + { id: b.id }, + { accountId: b.accountId }, + { postedOn: "2026-10-10" }, + { amountCents: -19999 }, + { status: "pending" as const }, + { description: "Changed" }, + { isTransfer: true }, + { pairId: "p" }, + { updatedAt: "2026-10-11T12:00:00.123457Z" }, + ]) + expect(matchesState(a, { ...a, ...patch })).toBe(false); + expect( + matchesFacts(a, { + ...a, + isTransfer: true, + pairId: "p", + updatedAt: b.updatedAt, + }), + ).toBe(true); + }); +}); diff --git a/src/features/transfers/domain/review.ts b/src/features/transfers/domain/review.ts new file mode 100644 index 0000000..e03388b --- /dev/null +++ b/src/features/transfers/domain/review.ts @@ -0,0 +1,180 @@ +import { z } from "zod"; +import { cents, negate } from "@/lib/money"; + +export const PAGE_SIZE = 20; +export const MATCH_CAP = 2000; +export const PAIR_CAP = 50; +export const dateSchema = z.iso.date(); +const optionalId = z.preprocess( + (v) => (v === "" ? undefined : v), + z.uuid().optional(), +); +export const querySchema = z.object({ + from: dateSchema.optional(), + to: dateSchema.optional(), + account: optionalId, + other: optionalId, + source: optionalId, + view: z.enum(["review", "pairs", "individual", "all"]).default("review"), + page: z.coerce.number().int().min(1).max(1000).default(1), + matchPage: z.coerce.number().int().min(1).max(100).default(1), +}); +export type ReviewQuery = z.infer & { + from: string; + to: string; +}; +export function shiftDay(day: string, days: number): string { + const date = new Date(`${day}T00:00:00Z`); + date.setUTCDate(date.getUTCDate() + days); + return date.toISOString().slice(0, 10); +} +export function calendarGap(a: string, b: string): number { + return ( + Math.abs( + new Date(`${a}T00:00:00Z`).getTime() - + new Date(`${b}T00:00:00Z`).getTime(), + ) / 86400000 + ); +} +export function reviewQuery(raw: unknown, today: string): ReviewQuery | null { + const parsed = querySchema.safeParse(raw); + if (!parsed.success) return null; + const to = parsed.data.to ?? today; + const from = parsed.data.from ?? shiftDay(to, -89); + if ( + from < "2000-01-01" || + to > today || + from > to || + calendarGap(from, to) > 365 + ) + return null; + return { ...parsed.data, from, to }; +} + +// Expected state also supports malformed legacy rows. Safe cents are checked +// explicitly before matching; metadata-only detachment does no money math. +export const stateSchema = z.object({ + id: z.uuid(), + accountId: z.uuid(), + postedOn: dateSchema, + amountCents: z.number().refine(Number.isInteger), + status: z.enum(["posted", "pending"]), + description: z.string().max(10000), + isTransfer: z.boolean(), + pairId: z.string().max(500).nullable(), + updatedAt: z.iso.datetime(), +}); +export type RowState = z.infer; +export type ReviewRow = RowState & { + workspaceId: string; + accountName: string; + accountType: string | null; + ownedAccount: boolean; +}; +export const writeSchema = z.discriminatedUnion("operation", [ + z.object({ + operation: z.literal("pair"), + expected: z.array(stateSchema).length(2), + confirmed: z.literal(true), + }), + z.object({ + operation: z.literal("detach"), + expected: z.array(stateSchema).min(1).max(PAIR_CAP), + confirmed: z.literal(true), + }), + z.object({ + operation: z.literal("label"), + expected: z.array(stateSchema).length(1), + transfer: z.boolean(), + confirmed: z.literal(true), + }), +]); +export type ReviewWrite = z.infer; +export type WriteResult = + | "ok" + | "already" + | "not_found" + | "stale" + | "ineligible" + | "paired" + | "allocated" + | "limit"; +export type ReviewFormState = { message?: string; ok?: boolean }; + +export function eligible( + a: ReviewRow, + b: ReviewRow, + today: string, + allowPaired = false, +): boolean { + return ( + a.id !== b.id && + a.workspaceId === b.workspaceId && + a.ownedAccount && + b.ownedAccount && + a.accountId !== b.accountId && + a.status === "posted" && + b.status === "posted" && + Number.isSafeInteger(a.amountCents) && + Number.isSafeInteger(b.amountCents) && + a.amountCents !== 0 && + negate(cents(a.amountCents)) === b.amountCents && + dateSchema.safeParse(a.postedOn).success && + dateSchema.safeParse(b.postedOn).success && + a.postedOn <= today && + b.postedOn <= today && + calendarGap(a.postedOn, b.postedOn) <= 3 && + (allowPaired || (a.pairId === null && b.pairId === null)) + ); +} +export function matchesFacts(a: RowState, b: RowState): boolean { + return ( + a.id === b.id && + a.accountId === b.accountId && + a.postedOn === b.postedOn && + a.amountCents === b.amountCents && + a.status === b.status && + a.description === b.description + ); +} +export function matchesState(a: RowState, b: RowState): boolean { + return ( + matchesFacts(a, b) && + a.isTransfer === b.isTransfer && + a.pairId === b.pairId && + a.updatedAt === b.updatedAt + ); +} +export function pairStatus( + members: readonly ReviewRow[], + today: string, +): "confirmed" | "incomplete" | "invalid" { + if (members.length === 1) return "incomplete"; + if (members.length !== 2) return "invalid"; + const [a, b] = members as [ReviewRow, ReviewRow]; + return Boolean(a.pairId) && + a.pairId === b.pairId && + a.isTransfer && + b.isTransfer && + eligible(a, b, today, true) + ? "confirmed" + : "invalid"; +} +export type RowReview = { + row: ReviewRow; + members: ReviewRow[]; + pairStatus: ReturnType | null; + candidates: ReviewRow[]; + candidateCount: number; + matchesLimited: boolean; + groupLimited: boolean; +}; +export type ReviewData = { + workspaceId: string; + today: string; + query: ReviewQuery; + canEdit: boolean; + accounts: { id: string; name: string }[]; + rows: RowReview[]; + hasMore: boolean; +}; diff --git a/src/features/transfers/index.ts b/src/features/transfers/index.ts new file mode 100644 index 0000000..3eceb5b --- /dev/null +++ b/src/features/transfers/index.ts @@ -0,0 +1,4 @@ +import "server-only"; +export { loadTransferReview } from "./server/load"; +export { reviewTransferAction } from "./server/actions"; +export { TransferReviewPage } from "./ui/review-page"; diff --git a/src/features/transfers/server/actions.test.ts b/src/features/transfers/server/actions.test.ts new file mode 100644 index 0000000..c531dbc --- /dev/null +++ b/src/features/transfers/server/actions.test.ts @@ -0,0 +1,207 @@ +import { + afterAll, + beforeAll, + beforeEach, + describe, + expect, + it, + vi, +} from "vitest"; +import { fixtures, isNotFound } from "../../../../tests/support/db-fixtures"; +import type { ReviewRow, WriteResult } from "../domain/review"; +const mocks = vi.hoisted(() => ({ + getSession: vi.fn(), + readReview: vi.fn(), + writeReview: vi.fn(), + refresh: vi.fn(), +})); +vi.mock("@/lib/auth/session", () => ({ getSession: mocks.getSession })); +vi.mock("./repository", () => ({ + readReview: mocks.readReview, + writeReview: mocks.writeReview, +})); +vi.mock("next/cache", () => ({ refresh: mocks.refresh })); +import { loadTransferReview } from "./load"; +import { reviewTransferAction } from "./actions"; +const f = fixtures(); +let ws: string, editor: string, viewer: string, outsider: string; +const row: ReviewRow = { + id: crypto.randomUUID(), + workspaceId: "unused", + accountId: crypto.randomUUID(), + postedOn: "2026-10-11", + amountCents: -20000, + description: "Repayment", + status: "posted", + isTransfer: false, + pairId: null, + updatedAt: "2026-10-11T12:00:00.123456Z", + accountName: "Cash", + accountType: "checking", + ownedAccount: true, +}; +const partner = { + ...row, + id: crypto.randomUUID(), + accountId: crypto.randomUUID(), + amountCents: 20000, +}; +function form( + value: unknown = { operation: "pair", expected: [row, partner] }, + confirmed = true, +) { + const form = new FormData(); + form.set("review", JSON.stringify(value)); + if (confirmed) form.set("confirm", "on"); + return form; +} +beforeAll(async () => { + editor = await f.newUser(); + viewer = await f.newUser(); + outsider = await f.newUser(); + ws = await f.newWorkspace({ [editor]: "editor", [viewer]: "viewer" }); +}); +afterAll(() => f.cleanUp()); +beforeEach(() => { + vi.clearAllMocks(); + mocks.getSession.mockResolvedValue({ user: { id: editor } }); + mocks.readReview.mockResolvedValue({ + accounts: [{ id: row.accountId, name: "Cash" }], + rows: [], + hasMore: false, + }); + mocks.writeReview.mockResolvedValue("ok"); +}); +describe("transfer boundaries", () => { + it.each(["anonymous", "viewer", "outsider"])( + "denies %s writes before reading financial data", + async (who) => { + mocks.getSession.mockResolvedValue( + who === "anonymous" + ? null + : { user: { id: who === "viewer" ? viewer : outsider } }, + ); + expect( + isNotFound( + await reviewTransferAction(ws, {}, form()).catch((e: unknown) => e), + ), + ).toBe(true); + expect(mocks.writeReview).not.toHaveBeenCalled(); + expect(mocks.readReview).not.toHaveBeenCalled(); + }, + ); + it.each([null, "outsider"])( + "denies unauthorized reads for %s", + async (who) => { + mocks.getSession.mockResolvedValue( + who === null ? null : { user: { id: outsider } }, + ); + expect( + isNotFound(await loadTransferReview(ws).catch((e: unknown) => e)), + ).toBe(true); + expect(mocks.readReview).not.toHaveBeenCalled(); + }, + ); + it("allows viewer reads, validates filters and uses the application timezone", async () => { + mocks.getSession.mockResolvedValue({ user: { id: viewer } }); + const data = await loadTransferReview( + ws, + {}, + new Date("2026-10-12T01:00:00Z"), + ); + expect(data).toMatchObject({ canEdit: false, today: "2026-10-11" }); + expect( + isNotFound( + await loadTransferReview(ws, { account: crypto.randomUUID() }).catch( + (e: unknown) => e, + ), + ), + ).toBe(true); + expect( + isNotFound( + await loadTransferReview(ws, { other: crypto.randomUUID() }).catch( + (e: unknown) => e, + ), + ), + ).toBe(true); + expect( + isNotFound( + await loadTransferReview(ws, { source: row.id }).catch( + (e: unknown) => e, + ), + ), + ).toBe(true); + mocks.readReview.mockClear(); + expect( + isNotFound( + await loadTransferReview(ws, { from: "bad" }).catch((e: unknown) => e), + ), + ).toBe(true); + expect(mocks.readReview).not.toHaveBeenCalled(); + }); + it("allows editor read controls and a focused owned source", async () => { + mocks.readReview.mockResolvedValue({ + accounts: [{ id: row.accountId, name: "Cash" }], + rows: [{ row }], + hasMore: false, + }); + expect( + await loadTransferReview( + ws, + { source: row.id, account: row.accountId, other: row.accountId }, + new Date("2026-10-11T16:00:00Z"), + ), + ).toMatchObject({ canEdit: true, rows: [{ row }] }); + }); + it("requires valid JSON, complete snapshots and explicit confirmation before writing", async () => { + for (const data of [ + new FormData(), + form({}, false), + form({ operation: "pair", expected: [row] }), + form(null), + form({ operation: "pair", expected: [row, partner] }, false), + ]) + expect((await reviewTransferAction(ws, {}, data)).ok).toBe(false); + const bad = form(); + bad.set("review", "{"); + expect((await reviewTransferAction(ws, {}, bad)).message).toContain( + "invalid", + ); + const long = form(); + long.set("review", "x".repeat(100001)); + expect((await reviewTransferAction(ws, {}, long)).ok).toBe(false); + const file = form(); + file.set("review", new File(["x"], "invalid.json")); + expect((await reviewTransferAction(ws, {}, file)).ok).toBe(false); + expect(mocks.writeReview).not.toHaveBeenCalled(); + }); + it.each([ + "ok", + "already", + "not_found", + "stale", + "ineligible", + "paired", + "allocated", + "limit", + ] as WriteResult[])("provides useful feedback for %s", async (result) => { + mocks.writeReview.mockResolvedValue(result); + const state = await reviewTransferAction(ws, {}, form()); + expect(state.message).toBeTruthy(); + expect(state.ok).toBe(result === "ok" || result === "already"); + expect(mocks.refresh).toHaveBeenCalledTimes(state.ok ? 1 : 0); + expect(mocks.writeReview.mock.calls[0]![0]).toBe(ws); + }); + it("redacts failure details and retains a retryable state", async () => { + mocks.writeReview.mockRejectedValue( + new Error("postgres://role:secret@host/database"), + ); + const state = await reviewTransferAction(ws, {}, form()); + expect(state).toEqual({ + ok: false, + message: + "The review could not be saved. Your selection is kept; try again.", + }); + expect(mocks.refresh).not.toHaveBeenCalled(); + }); +}); diff --git a/src/features/transfers/server/actions.ts b/src/features/transfers/server/actions.ts new file mode 100644 index 0000000..c8cddc6 --- /dev/null +++ b/src/features/transfers/server/actions.ts @@ -0,0 +1,80 @@ +"use server"; +import { refresh } from "next/cache"; +import { DEFAULT_TIME_ZONE } from "@/config/app"; +import { isoDateIn } from "@/features/accounts"; +import { requireWorkspaceAccess } from "@/lib/auth/authz"; +import { getSession } from "@/lib/auth/session"; +import { + writeSchema, + type ReviewFormState, + type WriteResult, +} from "../domain/review"; +import { writeReview } from "./repository"; + +const messages: Record = { + ok: "Review saved.", + already: "This review was already saved.", + not_found: "This activity is unavailable. Reload and review again.", + stale: + "This activity changed since the form was opened. Reload and review again.", + ineligible: + "Choose two posted, equal and opposite amounts on different owned accounts within three days.", + paired: "Remove the existing pairing before changing this activity.", + allocated: + "This label change would affect a linked bill payment. Unlink its evidence in Bills first, then review again.", + limit: + "This legacy group exceeds the review limit. Refine the review before making changes.", +}; +export async function reviewTransferAction( + workspaceId: unknown, + _previous: ReviewFormState, + form: FormData, +): Promise { + const access = await requireWorkspaceAccess( + await getSession(), + workspaceId, + "editor", + ); + const raw = form.get("review"); + if (typeof raw !== "string" || raw.length > 100000) + return { + message: "Choose a review action and confirm its effect.", + ok: false, + }; + let value: unknown; + try { + value = JSON.parse(raw); + } catch { + return { + message: "This review form is invalid. Reload and try again.", + ok: false, + }; + } + const parsed = writeSchema.safeParse({ + ...(typeof value === "object" && value !== null ? value : {}), + confirmed: form.get("confirm") === "on", + }); + if (!parsed.success) + return { + message: + "Choose a specific counterpart and confirm the effect before saving.", + ok: false, + }; + let result: WriteResult; + try { + result = await writeReview( + access.workspaceId, + parsed.data, + isoDateIn(new Date(), DEFAULT_TIME_ZONE), + ); + } catch { + return { + message: + "The review could not be saved. Your selection is kept; try again.", + ok: false, + }; + } + const ok = result === "ok" || result === "already"; + if (ok) refresh(); + return { message: messages[result], ok }; +} diff --git a/src/features/transfers/server/consumers.test.ts b/src/features/transfers/server/consumers.test.ts new file mode 100644 index 0000000..14d873a --- /dev/null +++ b/src/features/transfers/server/consumers.test.ts @@ -0,0 +1,265 @@ +import { eq } from "drizzle-orm"; +import { afterAll, describe, expect, it } from "vitest"; +import { db } from "@/lib/db/client"; +import { + recurringSeries, + financialAccount, + transaction, +} from "@/lib/db/schema"; +import { fixtures } from "../../../../tests/support/db-fixtures"; +import { ensureCategories, listCategories } from "@/features/categorization"; +import { readBudgetMonth } from "@/features/budgets"; +import { loadCashflowData, summarize } from "@/features/cashflow"; +import { buildMonth } from "@/features/cashflow/domain/cashflow"; +import { loadWorkspaceData } from "@/features/insights/server"; +import { periodEnding, workspaceMeasures } from "@/features/insights"; +import { listRecurringPayments } from "@/features/recurring"; +import { reviewQuery, type ReviewWrite } from "../domain/review"; +import { readReview, writeReview } from "./repository"; +const f = fixtures(), + today = "2026-10-11", + now = new Date(`${today}T16:00:00Z`); +afterAll(() => f.cleanUp()); +async function setup() { + const ws = await f.newWorkspace(); + await ensureCategories(ws); + const categories = await listCategories(ws); + const accounts = await db + .insert(financialAccount) + .values([ + { + workspaceId: ws, + institutionName: "Test", + type: "checking" as const, + nickname: "Cash", + source: "synthetic", + currentBalanceCents: 50000, + balanceAsOf: today, + }, + { + workspaceId: ws, + institutionName: "Test", + type: "credit_card" as const, + nickname: "Card", + source: "synthetic", + currentBalanceCents: -4500, + balanceAsOf: today, + }, + { + workspaceId: ws, + institutionName: "Test", + type: "savings" as const, + nickname: "Savings", + source: "synthetic", + currentBalanceCents: 10001, + balanceAsOf: today, + }, + ]) + .returning(); + return { + ws, + cash: accounts[0]!.id, + card: accounts[1]!.id, + savings: accounts[2]!.id, + category: (key: string) => categories.find((c) => c.presetKey === key)!.id, + }; +} +type Fixture = Awaited>; +async function add( + fx: Fixture, + accountId: string, + amountCents: number, + extra: Partial = {}, +) { + const [row] = await db + .insert(transaction) + .values({ + workspaceId: fx.ws, + financialAccountId: accountId, + postedOn: "2026-10-05", + amountCents, + descriptionRaw: "Activity", + categoryId: fx.category("groceries"), + categoryIsManual: true, + source: "csv", + fingerprint: crypto.randomUUID(), + ...extra, + }) + .returning(); + return row!.id; +} +async function expected(fx: Fixture, ids: string[]) { + return Promise.all( + ids.map( + async (source) => + ( + await readReview( + fx.ws, + reviewQuery({ view: "all", source, from: "2026-07-01" }, today)!, + today, + ) + ).rows[0]!.row, + ), + ); +} +async function figures(fx: Fixture) { + const calendar = await loadCashflowData(fx.ws, now); + return { + budget: await readBudgetMonth(fx.ws, "2026-10", today), + summary: summarize(calendar.data, today), + daily: buildMonth(calendar.data, { year: 2026, month: 10 }, today).days.map( + (d) => d.endBalance, + ), + insights: workspaceMeasures( + await loadWorkspaceData(fx.ws, "2026-09-12"), + periodEnding(today, 30), + ), + }; +} +describe("financial consumers of saved transfer metadata", () => { + it("changes actual spending and income figures, preserves savings semantics and every daily balance through pair/detach/normal activity", async () => { + const fx = await setup(); + await add(fx, fx.cash, 0, { postedOn: "2026-09-12", categoryId: null }); + await add(fx, fx.card, -4500, { descriptionRaw: "Groceries purchase" }); + await add(fx, fx.cash, 100000, { + categoryId: fx.category("income"), + descriptionRaw: "Salary", + }); + await add(fx, fx.cash, -3000, { + categoryId: fx.category("retirement"), + descriptionRaw: "Retirement saving", + isTransfer: true, + }); + const repayment = [ + await add(fx, fx.cash, -20000), + await add(fx, fx.card, 20000, { + categoryId: null, + categoryIsManual: false, + }), + ]; + const saving = [ + await add(fx, fx.cash, -10001), + await add(fx, fx.savings, 10001, { + categoryId: null, + categoryIsManual: false, + }), + ]; + const before = await figures(fx), + accounts = await db + .select() + .from(financialAccount) + .where(eq(financialAccount.workspaceId, fx.ws)); + expect(before.budget.totals.totalSpending).toBe(34501); + for (const ids of [repayment, saving]) + expect( + await writeReview( + fx.ws, + { + operation: "pair", + expected: await expected(fx, ids), + confirmed: true, + }, + today, + ), + ).toBe("ok"); + const after = await figures(fx); + expect(after.budget.totals.totalSpending).toBe(4500); + expect(after.summary).toMatchObject({ + balanceToday: 60001, + monthIn: 100000, + monthOut: 4500, + }); + expect(after.insights).toMatchObject({ + takeHome: 101458, + spending: 4566, + saved: 13191, + byCategory: { groceries: 4566 }, + }); + expect(after.insights?.lowestBalance).toBe(before.insights?.lowestBalance); + expect(after.daily).toEqual(before.daily); + expect( + await db + .select() + .from(financialAccount) + .where(eq(financialAccount.workspaceId, fx.ws)), + ).toEqual(accounts); + const members = ( + await readReview( + fx.ws, + reviewQuery({ source: repayment[0], view: "pairs" }, today)!, + today, + ) + ).rows[0]!.members; + expect( + await writeReview( + fx.ws, + { operation: "detach", expected: members, confirmed: true }, + today, + ), + ).toBe("ok"); + expect(await figures(fx)).toEqual(after); + for (const id of repayment) { + const request: ReviewWrite = { + operation: "label", + expected: await expected(fx, [id]), + transfer: false, + confirmed: true, + }; + expect(await writeReview(fx.ws, request, today)).toBe("ok"); + } + const restored = await figures(fx); + expect(restored.budget.totals.totalSpending).toBe(24500); + expect(restored.summary).toMatchObject({ + monthIn: 120000, + monthOut: 24500, + balanceToday: 60001, + }); + expect(restored.daily).toEqual(before.daily); + }); + it("excludes labelled repayments from recurring pattern evidence without rewriting or refreshing saved series", async () => { + const fx = await setup(), + ids = []; + const saved = await db + .select() + .from(recurringSeries) + .where(eq(recurringSeries.workspaceId, fx.ws)); + for (const postedOn of ["2026-07-05", "2026-08-05", "2026-09-05"]) + ids.push( + await add(fx, fx.cash, -20000, { + descriptionRaw: "Card repayment", + categoryId: fx.category("utilities"), + postedOn, + }), + ); + expect((await listRecurringPayments(fx.ws, now)).summary.candidates).toBe( + 1, + ); + for (const id of ids) + expect( + await writeReview( + fx.ws, + { + operation: "label", + expected: await expected(fx, [id]), + transfer: true, + confirmed: true, + }, + today, + ), + ).toBe("ok"); + const result = await listRecurringPayments(fx.ws, now); + expect(result.payments).toEqual([]); + expect(result.summary).toMatchObject({ + candidates: 0, + monthly: 0, + yearly: 0, + actual: 0, + }); + expect( + await db + .select() + .from(recurringSeries) + .where(eq(recurringSeries.workspaceId, fx.ws)), + ).toEqual(saved); + }); +}); diff --git a/src/features/transfers/server/entry-points.ts b/src/features/transfers/server/entry-points.ts new file mode 100644 index 0000000..ea24af9 --- /dev/null +++ b/src/features/transfers/server/entry-points.ts @@ -0,0 +1,72 @@ +import "server-only"; +import type { EntryPoint, EntryPointTarget } from "@/lib/auth/entry-point"; +import type { RowState } from "../domain/review"; +import { loadTransferReview } from "./load"; +import { reviewTransferAction } from "./actions"; +function expected(t: EntryPointTarget): RowState { + return { + id: t.transactionId, + accountId: t.accountId, + postedOn: "2026-01-10", + amountCents: -500, + description: "Isolation target", + status: "posted", + isTransfer: false, + pairId: null, + updatedAt: "2026-01-10T00:00:00Z", + }; +} +function call(t: EntryPointTarget, operation: "pair" | "detach" | "label") { + const row = expected(t); + const form = new FormData(); + form.set("confirm", "on"); + form.set( + "review", + JSON.stringify({ + operation, + expected: + operation === "pair" + ? [ + row, + { + ...row, + id: "00000000-0000-4000-8000-000000000001", + accountId: "00000000-0000-4000-8000-000000000002", + amountCents: 500, + }, + ] + : [{ ...row, pairId: operation === "detach" ? "matrix" : null }], + ...(operation === "label" ? { transfer: true } : {}), + }), + ); + return reviewTransferAction(t.workspaceId, {}, form); +} +export const TRANSFER_ENTRY_POINTS: EntryPoint[] = [ + { + name: "loadTransferReview", + minimumRole: "viewer", + call: ({ workspaceId }) => loadTransferReview(workspaceId), + }, + { + name: "loadTransferAccount", + minimumRole: "viewer", + call: ({ workspaceId, accountId }) => + loadTransferReview(workspaceId, { account: accountId }), + }, + { + name: "loadTransferSource", + minimumRole: "viewer", + call: ({ workspaceId, transactionId }) => + loadTransferReview(workspaceId, { + from: "2026-01-01", + to: "2026-01-31", + source: transactionId, + view: "all", + }), + }, + ...(["pair", "detach", "label"] as const).map((operation) => ({ + name: `reviewTransferAction:${operation}`, + minimumRole: "editor" as const, + call: (t: EntryPointTarget) => call(t, operation), + })), +]; diff --git a/src/features/transfers/server/load.ts b/src/features/transfers/server/load.ts new file mode 100644 index 0000000..d6a4ad9 --- /dev/null +++ b/src/features/transfers/server/load.ts @@ -0,0 +1,39 @@ +import "server-only"; +import { notFound } from "next/navigation"; +import { DEFAULT_TIME_ZONE } from "@/config/app"; +import { isoDateIn } from "@/features/accounts"; +import { requireWorkspaceAccess } from "@/lib/auth/authz"; +import { getSession } from "@/lib/auth/session"; +import { roleAtLeast } from "@/lib/auth/roles"; +import { reviewQuery, type ReviewData } from "../domain/review"; +import { readReview } from "./repository"; + +export async function loadTransferReview( + workspaceId: unknown, + rawQuery: unknown = {}, + now?: Date, +): Promise { + const access = await requireWorkspaceAccess( + await getSession(), + workspaceId, + "viewer", + ); + const today = isoDateIn(now ?? new Date(), DEFAULT_TIME_ZONE); + const query = reviewQuery(rawQuery, today); + if (!query) notFound(); + const data = await readReview(access.workspaceId, query, today); + if ( + [query.account, query.other].some( + (id) => id && !data.accounts.some((a) => a.id === id), + ) + ) + notFound(); + if (query.source && !data.rows.length) notFound(); + return { + ...data, + workspaceId: access.workspaceId, + today, + query, + canEdit: roleAtLeast(access.role, "editor"), + }; +} diff --git a/src/features/transfers/server/repository.test.ts b/src/features/transfers/server/repository.test.ts new file mode 100644 index 0000000..27a51e5 --- /dev/null +++ b/src/features/transfers/server/repository.test.ts @@ -0,0 +1,740 @@ +import { eq } from "drizzle-orm"; +import { afterAll, afterEach, describe, expect, it, vi } from "vitest"; +import { db } from "@/lib/db/client"; +import { billPayment, financialAccount, transaction } from "@/lib/db/schema"; +import { fixtures } from "../../../../tests/support/db-fixtures"; +import { + createTransaction, + deleteTransaction, + updateTransaction, +} from "@/features/transactions/server/repository"; +import { deleteAccount } from "@/features/accounts/server/repository"; +import { + linkBillPayment, + readBills, + saveBill, + unlinkBillPayment, +} from "@/features/bills"; +import { cents } from "@/lib/money"; +import { + reviewQuery, + type ReviewRow, + type ReviewWrite, +} from "../domain/review"; +import { readReview, writeReview } from "./repository"; +const f = fixtures(); +const today = "2026-10-11", + now = new Date(`${today}T16:00:00Z`); +afterAll(() => f.cleanUp()); +afterEach(() => vi.restoreAllMocks()); +async function setup() { + const ws = await f.newWorkspace(); + const accounts = await db + .insert(financialAccount) + .values([ + { + workspaceId: ws, + institutionName: "Test", + nickname: "Cash", + type: "checking" as const, + source: "manual", + currentBalanceCents: 50000, + balanceAsOf: "2026-10-01", + }, + { + workspaceId: ws, + institutionName: "Test", + nickname: "Card", + type: "credit_card" as const, + source: "manual", + currentBalanceCents: -10000, + balanceAsOf: "2026-10-01", + }, + ]) + .returning(); + return { ws, cash: accounts[0]!, card: accounts[1]! }; +} +type Fixture = Awaited>; +async function row( + fx: Fixture, + extra: Partial = {}, +) { + const [r] = await db + .insert(transaction) + .values({ + workspaceId: fx.ws, + financialAccountId: fx.cash.id, + postedOn: today, + amountCents: -20000, + descriptionRaw: "Repayment", + source: "csv" as const, + fingerprint: crypto.randomUUID(), + ...extra, + }) + .returning(); + return r!; +} +async function pair( + fx: Fixture, + extra: Partial = {}, +) { + const a = await row(fx, extra); + const b = await row(fx, { + financialAccountId: fx.card.id, + amountCents: 20000, + ...extra, + }); + return [a.id, b.id]; +} +const read = (fx: Fixture, query = {}) => + readReview(fx.ws, reviewQuery({ view: "all", ...query }, today)!, today); +async function states(fx: Fixture, ids: string[]): Promise { + return Promise.all( + ids.map( + async (source) => + ( + await readReview( + fx.ws, + reviewQuery({ view: "all", source }, "2026-10-12")!, + "2026-10-12", + ) + ).rows[0]!.row, + ), + ); +} +const request = (expected: ReviewRow[]): ReviewWrite => ({ + operation: "pair", + expected, + confirmed: true, +}); +const records = (ws: string) => + db + .select() + .from(transaction) + .where(eq(transaction.workspaceId, ws)) + .orderBy(transaction.id); +const balances = (ws: string) => + db + .select() + .from(financialAccount) + .where(eq(financialAccount.workspaceId, ws)) + .orderBy(financialAccount.id); +const withoutLabels = (rows: Awaited>) => + rows.map((row) => + Object.fromEntries( + Object.entries(row).filter( + ([key]) => !["isTransfer", "transferPairId", "updatedAt"].includes(key), + ), + ), + ); +async function detach(fx: Fixture, id: string) { + const data = (await read(fx, { source: id })).rows[0]!; + return writeReview( + fx.ws, + { operation: "detach", expected: data.members, confirmed: true }, + today, + ); +} +async function label(fx: Fixture, id: string, transfer: boolean) { + return writeReview( + fx.ws, + { + operation: "label", + expected: await states(fx, [id]), + transfer, + confirmed: true, + }, + today, + ); +} +async function bill(fx: Fixture, debt = false) { + const target = { accountId: fx.cash.id, merchant: "repayment" }; + expect( + await saveBill(fx.ws, { + ...target, + name: "Repayment", + kind: "bill", + amountMode: "fixed", + unit: "months", + every: 1, + amountCents: 20000, + nextOn: today, + useHistory: false, + autopay: false, + liabilityAccountId: debt ? fx.card.id : null, + invoiceCents: 20000, + }), + ).toBe("ok"); + return target; +} +describe("transfer review on PostgreSQL", () => { + it("reads suggestions without changing any row, and confirms atomically with exact metadata-only changes", async () => { + const fx = await setup(), + ids = await pair(fx); + const before = await records(fx.ws), + accounts = await balances(fx.ws); + const data = await read(fx); + expect( + data.rows.find((r) => r.row.id === ids[0])?.candidates.map((r) => r.id), + ).toEqual([ids[1]]); + expect(await records(fx.ws)).toEqual(before); + const expected = await states(fx, ids); + expect(await writeReview(fx.ws, request(expected), today)).toBe("ok"); + const after = await records(fx.ws); + expect( + after.every( + (r) => r.isTransfer && r.transferPairId === after[0]!.transferPairId, + ), + ).toBe(true); + expect(after[0]!.transferPairId).not.toBeNull(); + expect(withoutLabels(after)).toEqual(withoutLabels(before)); + expect(await balances(fx.ws)).toEqual(accounts); + expect(await writeReview(fx.ws, request(expected), today)).toBe("already"); + expect(await records(fx.ws)).toEqual(after); + }); + it("serializes duplicate and competing confirmations", async () => { + const fx = await setup(), + ids = await pair(fx); + const third = await row(fx, { + financialAccountId: fx.card.id, + amountCents: 20000, + }); + const first = request(await states(fx, ids)); + const competing = request(await states(fx, [ids[0]!, third.id])); + expect( + ( + await Promise.all([ + writeReview(fx.ws, first, today), + writeReview(fx.ws, first, today), + ]) + ).sort(), + ).toEqual(["already", "ok"]); + expect(await writeReview(fx.ws, competing, today)).toBe("stale"); + const fx2 = await setup(), + ids2 = await pair(fx2), + third2 = await row(fx2, { + financialAccountId: fx2.card.id, + amountCents: 20000, + }); + const [one, two] = await Promise.all([ + states(fx2, ids2), + states(fx2, [ids2[0]!, third2.id]), + ]); + expect( + ( + await Promise.all([ + writeReview(fx2.ws, request(one), today), + writeReview(fx2.ws, request(two), today), + ]) + ).sort(), + ).toEqual(["ok", "stale"]); + expect( + (await records(fx2.ws)).filter((r) => r.transferPairId), + ).toHaveLength(2); + }); + it("rejects stale facts, labels, timestamps, missing and foreign ids without touching balances", async () => { + const fx = await setup(), + ids = await pair(fx), + expected = await states(fx, ids), + before = await balances(fx.ws); + await db + .update(transaction) + .set({ descriptionRaw: "Changed" }) + .where(eq(transaction.id, ids[0]!)); + expect(await writeReview(fx.ws, request(expected), today)).toBe("stale"); + expect( + await writeReview(fx.ws, request([expected[0]!, expected[0]!]), today), + ).toBe("ineligible"); + const other = await setup(), + foreign = await pair(other); + expect( + await writeReview(fx.ws, request(await states(other, foreign)), today), + ).toBe("not_found"); + expect( + await writeReview( + fx.ws, + request([{ ...expected[0]!, id: crypto.randomUUID() }, expected[1]!]), + today, + ), + ).toBe("not_found"); + const fresh = await states(fx, ids); + expect( + await writeReview( + fx.ws, + request([ + { ...fresh[0]!, updatedAt: "2026-10-11T00:00:00Z" }, + fresh[1]!, + ]), + today, + ), + ).toBe("stale"); + expect(await balances(fx.ws)).toEqual(before); + expect((await records(other.ws)).every((r) => !r.isTransfer)).toBe(true); + }); + it.each([ + { amountCents: 0 }, + { amountCents: 19999 }, + { status: "pending" as const }, + { postedOn: "2026-10-12" }, + { postedOn: "2026-10-07" }, + ])("refuses changed eligibility %j", async (extra) => { + const fx = await setup(); + const a = await row(fx), + b = await row(fx, { + financialAccountId: fx.card.id, + amountCents: 20000, + ...extra, + }); + const expected = await states(fx, [a.id, b.id]); + expect(await writeReview(fx.ws, request(expected), today)).toBe( + "ineligible", + ); + }); + it("does not match same-account, zero, pending, future, unsafe or already paired rows", async () => { + const fx = await setup(), + source = await row(fx); + for (const extra of [ + { financialAccountId: fx.cash.id }, + { amountCents: 0 }, + { status: "pending" as const }, + { postedOn: "2026-10-12" }, + { transferPairId: "legacy" }, + { amountCents: Number.MAX_SAFE_INTEGER + 1 }, + ]) + await row(fx, { + financialAccountId: fx.card.id, + amountCents: 20000, + ...extra, + }); + expect((await read(fx, { source: source.id })).rows[0]!.candidates).toEqual( + [], + ); + expect( + await writeReview( + fx.ws, + request( + await states(fx, [ + source.id, + (await row(fx, { amountCents: 20000 })).id, + ]), + ), + today, + ), + ).toBe("ineligible"); + }); + it("loads padded and off-page counterparts, with explicit ambiguous pagination and older dates", async () => { + const fx = await setup(), + a = await row(fx, { postedOn: "2026-01-01" }); + const candidates = []; + for (let i = 0; i < 22; i++) + candidates.push( + await row(fx, { + financialAccountId: fx.card.id, + amountCents: 20000, + postedOn: "2025-12-31", + isTransfer: i === 0, + }), + ); + const query = { from: "2026-01-01", to: "2026-01-01", source: a.id }; + const first = (await read(fx, query)).rows[0]!, + second = (await read(fx, { ...query, matchPage: 2 })).rows[0]!; + expect(first.candidateCount).toBe(22); + expect(first.candidates).toHaveLength(20); + expect(second.candidates).toHaveLength(2); + expect( + new Set([...first.candidates, ...second.candidates].map((r) => r.id)) + .size, + ).toBe(22); + expect( + (await read(fx, { ...query, other: fx.cash.id })).rows[0]!.candidates, + ).toEqual([]); + const pageOne = await read(fx, { from: "2025-12-01", to: "2026-01-02" }); + expect(pageOne.hasMore).toBe(true); + const pageTwo = await read(fx, { + from: "2025-12-01", + to: "2026-01-02", + page: 2, + }); + expect( + new Set([...pageOne.rows, ...pageTwo.rows].map((r) => r.row.id)).size, + ).toBe(23); + }); + it("refuses truncated counterpart lists and large legacy repairs", async () => { + const fx = await setup(), + a = await row(fx); + await db.insert(transaction).values( + Array.from({ length: 2001 }, () => ({ + workspaceId: fx.ws, + financialAccountId: fx.card.id, + postedOn: today, + amountCents: 20000, + descriptionRaw: "Many", + source: "csv" as const, + fingerprint: crypto.randomUUID(), + })), + ); + const result = (await read(fx, { source: a.id })).rows[0]!; + expect(result.matchesLimited).toBe(true); + expect(result.candidates).toEqual([]); + const group = await db + .insert(transaction) + .values( + Array.from({ length: 51 }, () => ({ + workspaceId: fx.ws, + financialAccountId: fx.cash.id, + postedOn: today, + amountCents: -1, + descriptionRaw: "Legacy", + source: "csv" as const, + fingerprint: crypto.randomUUID(), + transferPairId: "huge", + })), + ) + .returning(); + const legacy = (await read(fx, { source: group[0]!.id })).rows[0]!; + expect(legacy.groupLimited).toBe(true); + expect( + await writeReview( + fx.ws, + { + operation: "detach", + expected: legacy.members.slice(0, 50), + confirmed: true, + }, + today, + ), + ).toBe("limit"); + }); + it("detaches explicitly, retaining each label even on invalid and orphan legacy groups", async () => { + const fx = await setup(), + ids = await pair(fx); + expect(await label(fx, ids[0]!, true)).toBe("ok"); + expect(await label(fx, ids[0]!, true)).toBe("already"); + expect( + ( + await readReview( + fx.ws, + reviewQuery({ view: "individual" }, today)!, + today, + ) + ).rows, + ).toHaveLength(1); + expect( + await writeReview(fx.ws, request(await states(fx, ids)), today), + ).toBe("ok"); + expect(await label(fx, ids[0]!, false)).toBe("paired"); + expect(await detach(fx, ids[0]!)).toBe("ok"); + expect( + (await records(fx.ws)).every( + (r) => r.isTransfer && r.transferPairId === null, + ), + ).toBe(true); + expect(await label(fx, ids[0]!, false)).toBe("ok"); + for (const pairId of ["", "legacy"]) { + const legacy = await row(fx, { + transferPairId: pairId, + isTransfer: false, + }); + expect((await read(fx, { source: legacy.id })).rows[0]!.pairStatus).toBe( + "incomplete", + ); + expect(await detach(fx, legacy.id)).toBe("ok"); + expect((await states(fx, [legacy.id]))[0]).toMatchObject({ + pairId: null, + isTransfer: false, + }); + } + const group = await row(fx, { transferPairId: "bad", isTransfer: true }); + await row(fx, { + transferPairId: "bad", + isTransfer: false, + amountCents: -10, + }); + expect((await read(fx, { source: group.id })).rows[0]!.pairStatus).toBe( + "invalid", + ); + const stale = (await read(fx, { source: group.id })).rows[0]!.members; + await row(fx, { transferPairId: "bad" }); + expect( + await writeReview( + fx.ws, + { operation: "detach", expected: stale, confirmed: true }, + today, + ), + ).toBe("stale"); + expect( + await writeReview( + fx.ws, + { + operation: "detach", + expected: await states(fx, [ids[0]!]), + confirmed: true, + }, + today, + ), + ).toBe("ineligible"); + expect(await detach(fx, group.id)).toBe("ok"); + }); + it("rolls back both label updates if the transaction fails before commit", async () => { + const fx = await setup(), + ids = await pair(fx), + expected = await states(fx, ids), + before = await records(fx.ws), + accounts = await balances(fx.ws); + const original = db.transaction.bind(db); + vi.spyOn(db, "transaction").mockImplementationOnce((callback, config) => + original(async (tx) => { + await callback(tx); + throw new Error("forced rollback after update"); + }, config), + ); + await expect(writeReview(fx.ws, request(expected), today)).rejects.toThrow( + "forced rollback", + ); + expect(await records(fx.ws)).toEqual(before); + expect(await balances(fx.ws)).toEqual(accounts); + }); + it("guards paired edits, permits descriptions, and undoes a deleted manual leg once while keeping the survivor label", async () => { + const fx = await setup(); + const a = await createTransaction(fx.ws, { + description: "Repayment", + isTransfer: false, + ledger: { + accountId: fx.cash.id, + postedOn: today, + amountCents: cents(-20000), + status: "posted", + }, + }); + const b = await createTransaction(fx.ws, { + description: "Repayment", + isTransfer: false, + ledger: { + accountId: fx.card.id, + postedOn: today, + amountCents: cents(20000), + status: "posted", + }, + }); + expect( + await writeReview(fx.ws, request(await states(fx, [a!, b!])), today), + ).toBe("ok"); + const accounts = await balances(fx.ws); + for (const ledger of [ + { + accountId: fx.cash.id, + postedOn: today, + amountCents: cents(-19999), + status: "posted" as const, + }, + { + accountId: fx.cash.id, + postedOn: "2026-10-10", + amountCents: cents(-20000), + status: "posted" as const, + }, + { + accountId: fx.card.id, + postedOn: today, + amountCents: cents(-20000), + status: "posted" as const, + }, + { + accountId: fx.cash.id, + postedOn: today, + amountCents: cents(-20000), + status: "pending" as const, + }, + ]) + expect( + await updateTransaction(fx.ws, a!, { + description: "Repayment", + isTransfer: true, + ledger, + }), + ).toBe("paired"); + expect( + await updateTransaction(fx.ws, a!, { + description: "Edited", + ledger: null, + isTransfer: false, + }), + ).toBe("paired"); + expect( + await updateTransaction(fx.ws, a!, { + description: "Edited", + ledger: null, + isTransfer: true, + }), + ).toBe("updated"); + expect(await balances(fx.ws)).toEqual(accounts); + expect(await deleteTransaction(fx.ws, a!)).toBe(true); + expect(await deleteTransaction(fx.ws, a!)).toBe(false); + expect((await states(fx, [b!]))[0]).toMatchObject({ + pairId: null, + isTransfer: true, + }); + expect( + (await balances(fx.ws)).find((r) => r.id === fx.cash.id) + ?.currentBalanceCents, + ).toBe(50000); + }); + it("leaves an account-deletion orphan for explicit detachment without auto reclassification", async () => { + const fx = await setup(), + ids = await pair(fx); + await writeReview(fx.ws, request(await states(fx, ids)), today); + await deleteAccount(fx.ws, fx.card.id); + expect((await read(fx, { source: ids[0] })).rows[0]!.pairStatus).toBe( + "incomplete", + ); + expect((await states(fx, [ids[0]!]))[0]!.isTransfer).toBe(true); + expect(await detach(fx, ids[0]!)).toBe("ok"); + }); + it("refuses Bills snapshot changes through review and the old transaction checkbox, then allows explicit unlink", async () => { + const fx = await setup(), + ids = await pair(fx), + target = await bill(fx); + expect(await linkBillPayment(fx.ws, target, today, 1, ids[0]!, now)).toBe( + "ok", + ); + const before = await db + .select() + .from(billPayment) + .where(eq(billPayment.workspaceId, fx.ws)); + expect(await label(fx, ids[0]!, true)).toBe("allocated"); + expect( + await writeReview(fx.ws, request(await states(fx, ids)), today), + ).toBe("allocated"); + expect( + await updateTransaction(fx.ws, ids[0]!, { + description: "Repayment", + ledger: null, + isTransfer: true, + }), + ).toBe("payment evidence"); + expect( + await db + .select() + .from(billPayment) + .where(eq(billPayment.workspaceId, fx.ws)), + ).toEqual(before); + const c = (await readBills(fx.ws, now)).bills[0]!.cycles.find( + (c) => c.scheduledOn === today, + )!; + expect( + await unlinkBillPayment( + fx.ws, + target, + today, + c.revision, + before[0]!.id, + now, + ), + ).toBe("ok"); + expect( + await writeReview(fx.ws, request(await states(fx, ids)), today), + ).toBe("ok"); + }); + it("permits pairing and detaching an already-labelled debt payment without altering evidence", async () => { + const fx = await setup(), + ids = await pair(fx, { isTransfer: true }), + target = await bill(fx, true); + expect(await linkBillPayment(fx.ws, target, today, 1, ids[0]!, now)).toBe( + "ok", + ); + const evidence = await db + .select() + .from(billPayment) + .where(eq(billPayment.workspaceId, fx.ws)); + const view = await readBills(fx.ws, now), + accounts = await balances(fx.ws); + expect( + await writeReview(fx.ws, request(await states(fx, ids)), today), + ).toBe("ok"); + expect(await detach(fx, ids[0]!)).toBe("ok"); + expect(await readBills(fx.ws, now)).toEqual(view); + expect( + await db + .select() + .from(billPayment) + .where(eq(billPayment.workspaceId, fx.ws)), + ).toEqual(evidence); + expect(await balances(fx.ws)).toEqual(accounts); + expect(await label(fx, ids[0]!, false)).toBe("allocated"); + }); + it("serializes a Bills link against classification and edit/delete against pairing", async () => { + const fx = await setup(), + ids = await pair(fx), + target = await bill(fx), + expected = await states(fx, ids); + const [linked, paired] = await Promise.all([ + linkBillPayment(fx.ws, target, today, 1, ids[0]!, now), + writeReview(fx.ws, request(expected), today), + ]); + expect([ + ["ok", "allocated"], + ["invalid_payment", "ok"], + ]).toContainEqual([linked, paired]); + const evidence = await db + .select() + .from(billPayment) + .where(eq(billPayment.workspaceId, fx.ws)); + expect( + evidence.length + ? evidence[0]!.isTransfer + : (await states(fx, ids))[0]!.isTransfer, + ).toBe(evidence.length === 0); + const second = await setup(), + next = await pair(second), + state = await states(second, next); + const [updated, paired2] = await Promise.all([ + updateTransaction(second.ws, next[0]!, { + description: "Changed", + ledger: null, + isTransfer: false, + }), + writeReview(second.ws, request(state), today), + ]); + expect([ + ["updated", "stale"], + ["paired", "ok"], + ]).toContainEqual([updated, paired2]); + const third = await setup(), + last = await pair(third), + before = await states(third, last); + const [deleted, paired3] = await Promise.all([ + deleteTransaction(third.ws, last[0]!), + writeReview(third.ws, request(before), today), + ]); + expect(deleted).toBe(true); + expect(["not_found", "ok"]).toContain(paired3); + const survivor = (await states(third, [last[1]!]))[0]!; + expect(survivor.pairId).toBeNull(); + expect(survivor.isTransfer).toBe(paired3 === "ok"); + }); + it("never leaks foreign account names or modifies a foreign row carrying the same legacy pair id", async () => { + const fx = await setup(), + other = await setup(); + const a = await row(fx, { transferPairId: "shared", isTransfer: true }), + b = await row(other, { transferPairId: "shared", isTransfer: true }); + const malformed = await row(fx, { + financialAccountId: other.cash.id, + descriptionRaw: "Malformed", + }); + expect( + (await read(fx, { source: malformed.id })).rows[0]!.row, + ).toMatchObject({ + ownedAccount: false, + accountName: "Account unavailable", + accountType: null, + }); + expect(await label(fx, malformed.id, true)).toBe("not_found"); + expect(await detach(fx, a.id)).toBe("ok"); + expect((await states(other, [b.id]))[0]!.pairId).toBe("shared"); + expect( + (await read(fx, { account: other.cash.id })).accounts.some( + (a) => a.id === other.cash.id, + ), + ).toBe(false); + }); +}); diff --git a/src/features/transfers/server/repository.ts b/src/features/transfers/server/repository.ts new file mode 100644 index 0000000..afa1742 --- /dev/null +++ b/src/features/transfers/server/repository.ts @@ -0,0 +1,322 @@ +import "server-only"; +import { + and, + asc, + desc, + eq, + gte, + inArray, + isNotNull, + isNull, + lte, + ne, + sql, +} from "drizzle-orm"; +import { db } from "@/lib/db/client"; +import { uuidv7 } from "@/lib/db/id"; +import { financialAccount, transaction } from "@/lib/db/schema"; +import { + hasBillEvidence, + lockLedgerWorkspace, + type LedgerTx, +} from "@/lib/db/transaction-guards"; +import { cents, negate } from "@/lib/money"; +import { + MATCH_CAP, + PAGE_SIZE, + PAIR_CAP, + eligible, + matchesFacts, + matchesState, + pairStatus, + shiftDay, + writeSchema, + type ReviewQuery, + type ReviewRow, + type ReviewWrite, + type RowReview, + type WriteResult, +} from "../domain/review"; + +const columns = { + id: transaction.id, + workspaceId: transaction.workspaceId, + accountId: transaction.financialAccountId, + postedOn: transaction.postedOn, + amountCents: transaction.amountCents, + description: transaction.descriptionRaw, + status: transaction.status, + isTransfer: transaction.isTransfer, + pairId: transaction.transferPairId, + updatedAt: sql`to_char(${transaction.updatedAt} at time zone 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.US"Z"')`, + accountName: financialAccount.nickname, + accountType: financialAccount.type, +}; +const joinAccount = and( + eq(financialAccount.id, transaction.financialAccountId), + eq(financialAccount.workspaceId, transaction.workspaceId), +); +type Stored = Omit & { + accountName: string | null; +}; +const readable = (row: Stored): ReviewRow => ({ + ...row, + accountName: row.accountName ?? "Account unavailable", + ownedAccount: row.accountName !== null, +}); +const queryRows = (tx: LedgerTx | typeof db) => + tx.select(columns).from(transaction).leftJoin(financialAccount, joinAccount); +const inWorkspace = (workspaceId: string) => + eq(transaction.workspaceId, workspaceId); + +/** One consistent, bounded snapshot; reads never change classification. */ +export async function readReview( + workspaceId: string, + query: ReviewQuery, + today: string, +) { + return db.transaction( + async (tx) => { + const accounts = await tx + .select({ id: financialAccount.id, name: financialAccount.nickname }) + .from(financialAccount) + .where(eq(financialAccount.workspaceId, workspaceId)) + .orderBy(asc(financialAccount.id)) + .limit(1001); + if (accounts.length > 1000) + throw new Error("Refine the workspace account scope"); + const selected = await queryRows(tx) + .where( + and( + inWorkspace(workspaceId), + gte(transaction.postedOn, query.from), + lte(transaction.postedOn, query.to), + query.account + ? eq(transaction.financialAccountId, query.account) + : undefined, + query.source ? eq(transaction.id, query.source) : undefined, + !query.source && query.view === "pairs" + ? isNotNull(transaction.transferPairId) + : undefined, + !query.source && query.view === "individual" + ? and( + eq(transaction.isTransfer, true), + isNull(transaction.transferPairId), + ) + : undefined, + !query.source && query.view === "review" + ? and( + eq(transaction.isTransfer, false), + isNull(transaction.transferPairId), + ) + : undefined, + ), + ) + .orderBy(desc(transaction.postedOn), asc(transaction.id)) + .limit(PAGE_SIZE + 1) + .offset(query.source ? 0 : (query.page - 1) * PAGE_SIZE); + const rows: RowReview[] = []; + for (const row of selected.slice(0, PAGE_SIZE).map(readable)) { + let members: ReviewRow[] = [], + candidates: ReviewRow[] = []; + let groupLimited = false, + matchesLimited = false; + if (row.pairId !== null) { + members = ( + await queryRows(tx) + .where( + and( + inWorkspace(workspaceId), + eq(transaction.transferPairId, row.pairId), + ), + ) + .orderBy(asc(transaction.id)) + .limit(PAIR_CAP + 1) + ).map(readable); + groupLimited = members.length > PAIR_CAP; + } else if ( + row.ownedAccount && + row.status === "posted" && + row.postedOn <= today && + Number.isSafeInteger(row.amountCents) && + row.amountCents !== 0 + ) { + candidates = ( + await queryRows(tx) + .where( + and( + inWorkspace(workspaceId), + isNotNull(financialAccount.id), + isNull(transaction.transferPairId), + eq(transaction.status, "posted"), + eq(transaction.amountCents, negate(cents(row.amountCents))), + ne(transaction.financialAccountId, row.accountId), + gte(transaction.postedOn, shiftDay(row.postedOn, -3)), + lte(transaction.postedOn, shiftDay(row.postedOn, 3)), + lte(transaction.postedOn, today), + query.other + ? eq(transaction.financialAccountId, query.other) + : undefined, + ), + ) + .orderBy(asc(transaction.postedOn), asc(transaction.id)) + .limit(MATCH_CAP + 1) + ).map(readable); + matchesLimited = candidates.length > MATCH_CAP; + } + rows.push({ + row, + members, + groupLimited, + matchesLimited, + pairStatus: row.pairId === null ? null : pairStatus(members, today), + candidateCount: candidates.length, + candidates: matchesLimited + ? [] + : candidates.slice( + (query.source ? query.matchPage - 1 : 0) * PAGE_SIZE, + (query.source ? query.matchPage : 1) * PAGE_SIZE, + ), + }); + } + return { accounts, rows, hasMore: selected.length > PAGE_SIZE }; + }, + { isolationLevel: "repeatable read", accessMode: "read only" }, + ); +} + +async function lockedRows( + tx: LedgerTx, + workspaceId: string, + ids: string[], +): Promise { + // Lock only transactions (a nullable account join cannot be FOR UPDATE). + const locked = await tx + .select({ id: transaction.id }) + .from(transaction) + .where( + and(inWorkspace(workspaceId), inArray(transaction.id, [...ids].sort())), + ) + .orderBy(asc(transaction.id)) + .for("update"); + if (!locked.length) return []; + return ( + await queryRows(tx) + .where( + and( + inWorkspace(workspaceId), + inArray( + transaction.id, + locked.map((r) => r.id), + ), + ), + ) + .orderBy(asc(transaction.id)) + ).map(readable); +} +/** Metadata only. Caller authorizes editor access; every lookup is scoped. */ +export async function writeReview( + workspaceId: string, + input: ReviewWrite, + today: string, +): Promise { + writeSchema.parse(input); + if (new Set(input.expected.map((r) => r.id)).size !== input.expected.length) + return "ineligible"; + return db.transaction(async (tx) => { + await lockLedgerWorkspace(tx, workspaceId); + let ids = input.expected.map((r) => r.id); + if (input.operation === "detach") { + const pairId = input.expected[0]!.pairId; + if (pairId === null || !input.expected.every((r) => r.pairId === pairId)) + return "ineligible"; + const group = await tx + .select({ id: transaction.id }) + .from(transaction) + .where( + and(inWorkspace(workspaceId), eq(transaction.transferPairId, pairId)), + ) + .orderBy(asc(transaction.id)) + .limit(PAIR_CAP + 1); + if (group.length > PAIR_CAP) return "limit"; + ids = group.map((r) => r.id); + if ( + ids.length !== input.expected.length || + !ids.every((id) => input.expected.some((r) => r.id === id)) + ) + return "stale"; + } + const rows = await lockedRows(tx, workspaceId, ids); + if (rows.length !== input.expected.length) return "not_found"; + const unchanged = rows.every((r) => + matchesState( + r, + input.expected.find((e) => e.id === r.id)!, + ), + ); + if (input.operation === "pair") { + const [a, b] = rows as [ReviewRow, ReviewRow]; + if ( + a.pairId !== null && + a.pairId === b.pairId && + a.isTransfer && + b.isTransfer && + eligible(a, b, today, true) && + rows.every((r) => + matchesFacts( + r, + input.expected.find((e) => e.id === r.id)!, + ), + ) + ) { + const count = await tx + .select({ n: sql`count(*)::int` }) + .from(transaction) + .where( + and( + inWorkspace(workspaceId), + eq(transaction.transferPairId, a.pairId), + ), + ); + return count[0]?.n === 2 ? "already" : "paired"; + } + if (!unchanged) return "stale"; + if (!eligible(a, b, today)) return "ineligible"; + if ( + await hasBillEvidence( + tx, + workspaceId, + rows.filter((r) => !r.isTransfer).map((r) => r.id), + ) + ) + return "allocated"; + await tx + .update(transaction) + .set({ + isTransfer: true, + transferPairId: uuidv7(), + updatedAt: new Date(), + }) + .where(and(inWorkspace(workspaceId), inArray(transaction.id, ids))); + } else { + if (!unchanged) return "stale"; + if (input.operation === "detach") { + await tx + .update(transaction) + .set({ transferPairId: null, updatedAt: new Date() }) + .where(and(inWorkspace(workspaceId), inArray(transaction.id, ids))); + } else { + const row = rows[0]!; + if (!row.ownedAccount) return "not_found"; + if (row.pairId !== null) return "paired"; + if (row.isTransfer === input.transfer) return "already"; + if (await hasBillEvidence(tx, workspaceId, ids)) return "allocated"; + await tx + .update(transaction) + .set({ isTransfer: input.transfer, updatedAt: new Date() }) + .where(and(inWorkspace(workspaceId), eq(transaction.id, row.id))); + } + } + return "ok"; + }); +} diff --git a/src/features/transfers/ui/review-page.tsx b/src/features/transfers/ui/review-page.tsx new file mode 100644 index 0000000..20e9a23 --- /dev/null +++ b/src/features/transfers/ui/review-page.tsx @@ -0,0 +1,524 @@ +"use client"; +import Link from "next/link"; +import { useActionState, useId, useState } from "react"; +import { cents, formatSigned } from "@/lib/money"; +import { + PAGE_SIZE, + calendarGap, + type ReviewData, + type ReviewFormState, + type ReviewQuery, + type ReviewRow, + type RowReview, +} from "../client"; +import styles from "./review.module.css"; + +type Action = ( + previous: ReviewFormState, + form: FormData, +) => Promise; +function href( + workspaceId: string, + query: ReviewQuery, + changes: Partial, +) { + const next = { ...query, ...changes }; + const search = new URLSearchParams(); + for (const [key, value] of Object.entries(next)) + if (value !== undefined) search.set(key, String(value)); + return `/w/${workspaceId}/transactions/transfers?${search}`; +} +function amount(row: ReviewRow) { + return Number.isSafeInteger(row.amountCents) + ? formatSigned(cents(row.amountCents)) + : "Amount needs review"; +} +function Fact({ row }: { row: ReviewRow }) { + return ( +

+ {row.accountName} + + {row.postedOn} · {amount(row)} + + {row.description} + + {row.status === "pending" ? "Pending · " : ""} + {row.isTransfer ? "Transfer label" : "Normal activity"} + +
+ ); +} +function ReviewForm({ + review, + operation, + action, + workspaceId, + feedback, +}: { + review: RowReview; + operation: "pair" | "detach" | "label"; + action: Action; + workspaceId: string; + feedback: (state: ReviewFormState) => void; +}) { + const id = useId(); + const [selected, setSelected] = useState(""); + const [state, formAction, pending] = useActionState( + async (previous: ReviewFormState, form: FormData) => { + feedback({}); + try { + const result = await action(previous, form); + if (result.ok) feedback(result); + return result; + } catch { + return { + ok: false, + message: + "The review could not be saved. Your selection is kept; try again.", + }; + } + }, + {}, + ); + const partner = review.candidates.find((r) => r.id === selected); + const expected = + operation === "detach" + ? review.members + : operation === "pair" && partner + ? [review.row, partner] + : [review.row]; + const title = + operation === "pair" + ? "Confirm pairing" + : operation === "detach" + ? "Remove pairing, keep transfer labels" + : review.row.isTransfer + ? "Count as normal activity" + : "Mark as an individual transfer"; + const effect = + operation === "pair" + ? "Both rows will be labelled transfers and excluded from spending, income and budgets." + : operation === "detach" + ? "Only the relationship is removed. Each current label stays as shown; labelled transfers remain excluded from spending and income." + : review.row.isTransfer + ? "This row will be counted according to its category and direction." + : "This row will be excluded from spending, income and budgets without a paired counterpart."; + return ( +
event.preventDefault()} + className={styles.controls} + aria-label={`${title}: ${review.row.description}`} + > + {operation === "pair" && ( +
+ Choose a specific counterpart + {review.candidates.map((row) => ( + + ))} +
+ )} + +

+ {effect} +

+ + + {state.message && !state.ok &&

{state.message}

} + {state.message?.includes("Bills") && ( + + Review payment evidence in Bills + + )} +
+ ); +} + +export function TransferReviewPage({ + data, + action, +}: { + data: ReviewData; + action: Action; +}) { + const [feedback, setFeedback] = useState({}); + const { query } = data; + const base = `/w/${data.workspaceId}/transactions/transfers`; + const defaultWindow = + query.from === + new Date(new Date(`${data.today}T00:00:00Z`).getTime() - 89 * 86400000) + .toISOString() + .slice(0, 10) && query.to === data.today; + const seen = new Set(); + const rows = data.rows.filter((r) => { + if (r.row.pairId === null) return true; + if (seen.has(r.row.pairId)) return false; + seen.add(r.row.pairId); + return true; + }); + return ( +
+
+

Review transfers

+ + Back to Transactions + +
+

+ Review recorded transfers between your accounts, including credit-card + repayments. Equal amounts suggest a match; choose and confirm the + transactions yourself. +

+

+ {defaultWindow ? "90-day review window" : "Selected review window"}:{" "} + {query.from} through {query.to}. This page shows bounded recorded + activity, not a complete account history. +

+ {!data.canEdit && ( +

+ Viewer access: you can read reviews; an editor or owner can change + labels and pairings. +

+ )} +
+ + + + + + +
+ + {feedback.message && ( +

+ {feedback.message} +

+ )} + {!rows.length && ( +

+ No recorded activity in this review. Try another account, view or + earlier dates. +

+ )} +
+ {rows.map((review) => ( +
+

+ {review.pairStatus === "confirmed" + ? "Confirmed pair" + : review.pairStatus === "incomplete" + ? "Incomplete pairing" + : review.pairStatus === "invalid" + ? "Invalid existing pair" + : review.row.isTransfer + ? "Individual transfer" + : "Activity to review"} +

+
+ {(review.members.length ? review.members : [review.row]).map( + (row) => ( + + ), + )} +
+ {review.row.pairId !== null ? ( + <> + {review.pairStatus !== "confirmed" && ( +

+ This relationship needs review. No labels have been changed + automatically. +

+ )} + {review.groupLimited ? ( +

+ This legacy group exceeds 50 rows. No repair is offered for + a partial group. +

+ ) : ( + data.canEdit && ( + + ) + )} + + ) : ( + <> + {review.matchesLimited ? ( +

+ More than 2,000 eligible counterparts. Select a counterpart + account to refine the review; no partial match list is + shown. +

+ ) : ( + <> +

+ {review.candidateCount === 0 + ? "No eligible counterpart in the owned accounts and selected counterpart filter." + : `${review.candidateCount} eligible counterpart${review.candidateCount === 1 ? "" : "s"}${review.candidateCount > 1 ? "; choose carefully—this match is ambiguous" : "; confirmation is still required"}.`} +

+ {review.candidates.length > 0 && + (data.canEdit ? ( + + ) : ( +
+ {review.candidates.map((row) => ( + + ))} +
+ ))} + {review.candidateCount > PAGE_SIZE && ( + + )} + + )} + {data.canEdit && ( + + )} + + )} + {data.canEdit && ( + + Edit transaction + + )} +
+ ))} +
+ + {data.hasMore && query.page === 1000 && ( +

+ More activity exists beyond this 20,000-row review. Select an account + or a shorter date range to continue. +

+ )} +

+ Review at most 366 days at a time. Counterparts include the three-day + padding beyond the selected window. Removing a pairing keeps existing + labels; normal activity requires a separate explicit change. +

+
+ ); +} diff --git a/src/features/transfers/ui/review.module.css b/src/features/transfers/ui/review.module.css new file mode 100644 index 0000000..1a94edd --- /dev/null +++ b/src/features/transfers/ui/review.module.css @@ -0,0 +1,154 @@ +.page { + max-width: 70rem; + padding: clamp(1.5rem, 3vw, 2.5rem) clamp(1rem, 3vw, 3rem) 3rem; +} +.heading, +.actions { + display: flex; + flex-wrap: wrap; + gap: 1rem; + align-items: center; +} +.heading { + justify-content: space-between; +} +.page h1 { + font-size: clamp(1.75rem, 1.2rem + 2vw, 2.5rem); + line-height: 1.15; +} +.page h2 { + font-size: 1.15rem; +} +.lead { + max-width: 70ch; + margin: 1rem 0; +} +.hint { + color: var(--ink-soft); + font-size: 0.875rem; +} +.filters { + display: flex; + flex-wrap: wrap; + align-items: end; + gap: 1rem; + margin: 1.5rem 0; +} +.filters label { + display: grid; + gap: 0.3rem; + min-width: 0; + max-width: 100%; +} +.page input, +.page select, +.page button { + font: inherit; +} +.page input[type="date"], +.page select { + padding: 0.5rem; + border: 1px solid var(--line); + border-radius: 6px; + background: var(--surface); + color: var(--ink); + min-width: 0; + max-width: 100%; +} +.page button { + padding: 0.6rem 0.85rem; + border: 1px solid var(--ink); + border-radius: 8px; + color: var(--surface); + background: var(--ink); + cursor: pointer; + min-height: 44px; +} +.page button:disabled { + opacity: 0.65; + cursor: wait; +} +.page a { + color: var(--ink); + text-decoration: underline; + text-underline-offset: 0.2em; +} +.page :focus-visible { + outline: 2px solid var(--ink); + outline-offset: 3px; +} +.cards { + display: grid; + gap: 1.25rem; + margin: 1.5rem 0; +} +.card { + border: 1px solid var(--line); + border-radius: 12px; + background: var(--surface); + padding: 1rem; + overflow-wrap: anywhere; + min-width: 0; +} +.card h2 { + margin-bottom: 0.75rem; +} +.facts { + display: flex; + flex-wrap: wrap; + gap: 1rem; +} +.fact { + display: grid; + gap: 0.2rem; + flex: 1 1 16rem; + min-width: 0; +} +.controls { + display: grid; + gap: 0.75rem; + padding: 1rem 0; + border-top: 1px solid var(--line); + margin-top: 1rem; +} +.controls button { + justify-self: start; +} +.choices { + display: grid; + gap: 0.5rem; + border: 0; + padding: 0; + min-width: 0; +} +.choices legend { + margin-bottom: 0.5rem; + font-weight: 600; +} +.choice { + display: flex; + align-items: start; + gap: 0.6rem; + padding: 0.4rem 0; +} +.choice input { + flex: 0 0 auto; + margin-top: 0.25rem; + width: 1.1rem; + height: 1.1rem; +} +.status { + margin: 1rem 0; + padding: 0.85rem; + border: 1px solid var(--line); + border-radius: 8px; +} +@media (max-width: 480px) { + .filters { + display: grid; + grid-template-columns: minmax(0, 1fr); + } + .card { + padding: 0.85rem; + } +} diff --git a/src/lib/auth/isolation.test.ts b/src/lib/auth/isolation.test.ts index 0bbcdf8..20643c2 100644 --- a/src/lib/auth/isolation.test.ts +++ b/src/lib/auth/isolation.test.ts @@ -2,6 +2,7 @@ import { afterAll, beforeAll, describe, expect, it, vi } from "vitest"; import { ACCOUNT_ENTRY_POINTS } from "@/features/accounts/server/entry-points"; import { CASHFLOW_ENTRY_POINTS } from "@/features/cashflow/server/entry-points"; import { BUDGET_ENTRY_POINTS } from "@/features/budgets/server/entry-points"; +import { TRANSFER_ENTRY_POINTS } from "@/features/transfers/server/entry-points"; import { BILL_ENTRY_POINTS } from "@/features/bills/server/entry-points"; import { saveBill } from "@/features/bills"; import { CATEGORIZATION_ENTRY_POINTS } from "@/features/categorization/server/entry-points"; @@ -62,6 +63,7 @@ const ENTRY_POINTS: EntryPoint[] = [ ...CASHFLOW_ENTRY_POINTS, ...BUDGET_ENTRY_POINTS, ...BILL_ENTRY_POINTS, + ...TRANSFER_ENTRY_POINTS, ]; const getSession = vi.hoisted(() => vi.fn()); diff --git a/src/lib/db/client.test.ts b/src/lib/db/client.test.ts new file mode 100644 index 0000000..c12cda4 --- /dev/null +++ b/src/lib/db/client.test.ts @@ -0,0 +1,91 @@ +import { sql } from "drizzle-orm"; +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; + +const calls = vi.hoisted(() => { + const result = { rows: [{ value: 1 }], rowCount: 1, fields: [] }; + return { + poolQuery: vi.fn().mockResolvedValue(result), + clientQuery: vi.fn().mockResolvedValue(result), + release: vi.fn(), + }; +}); + +vi.mock("pg", async (importOriginal) => { + const actual = await importOriginal(); + class TcpPool { + query = calls.poolQuery; + on() { + return this; + } + async connect() { + return { query: calls.clientQuery, release: calls.release }; + } + } + return { + ...actual, + Pool: TcpPool, + default: { ...actual.default, Pool: TcpPool }, + }; +}); + +vi.mock("@neondatabase/serverless", async (importOriginal) => { + const actual = + await importOriginal(); + // Drizzle recognizes a Neon pool with instanceof, including subclasses. + class WebSocketPool extends actual.Pool { + query = calls.poolQuery; + connect = vi.fn().mockResolvedValue({ + query: calls.clientQuery, + release: calls.release, + }); + } + return { ...actual, Pool: WebSocketPool }; +}); + +beforeEach(() => { + vi.resetModules(); + vi.clearAllMocks(); + globalThis.reeflectPool = undefined; +}); + +afterEach(() => { + vi.unstubAllEnvs(); + globalThis.reeflectPool = undefined; +}); + +describe.each(["tcp", "websocket"])("database transport %s", (transport) => { + it("keeps a transaction on one client and releases it after commit", async () => { + vi.stubEnv("DATABASE_TRANSPORT", transport); + const { db } = await import("./client"); + const result = await db.transaction(async (tx) => { + await tx.execute(sql`select 1`); + await tx.execute(sql`select 2`); + return "committed"; + }); + + expect(result).toBe("committed"); + expect(calls.poolQuery).not.toHaveBeenCalled(); + expect( + calls.clientQuery.mock.calls.map(([query]) => query.text.trim()), + ).toEqual(["begin", "select 1", "select 2", "commit"]); + expect(calls.release).toHaveBeenCalledOnce(); + }); + + it("rolls back and releases the client when the transaction fails", async () => { + vi.stubEnv("DATABASE_TRANSPORT", transport); + const { db } = await import("./client"); + const failure = new Error("abort transaction"); + await expect( + db.transaction(async (tx) => { + await tx.execute(sql`select 1`); + throw failure; + }), + ).rejects.toBe(failure); + + expect(calls.poolQuery).not.toHaveBeenCalled(); + expect( + calls.clientQuery.mock.calls.map(([query]) => query.text.trim()), + ).toEqual(["begin", "select 1", "rollback"]); + expect(calls.release).toHaveBeenCalledOnce(); + }); +}); diff --git a/src/lib/db/client.ts b/src/lib/db/client.ts index 498ad03..4d7f195 100644 --- a/src/lib/db/client.ts +++ b/src/lib/db/client.ts @@ -1,11 +1,25 @@ import "server-only"; +import { Agent } from "node:https"; +import { Pool as NeonPool, neonConfig } from "@neondatabase/serverless"; +import { drizzle as drizzleNeon } from "drizzle-orm/neon-serverless"; import { drizzle } from "drizzle-orm/node-postgres"; -import { Pool } from "pg"; +import { Pool, type PoolClient } from "pg"; +import WebSocket from "ws"; import { env } from "@/lib/env"; import * as schema from "./schema"; -function createPool(): Pool { - const pool = new Pool({ +function createPool(): Pool | NeonPool { + if (env.DATABASE_TRANSPORT === "websocket") { + const agent = new Agent({ keepAlive: true, proxyEnv: process.env }); + neonConfig.webSocketConstructor = class extends WebSocket { + constructor(address: string, protocols?: string | string[]) { + super(address, protocols, { agent }); + } + }; + } + const PoolConstructor = + env.DATABASE_TRANSPORT === "websocket" ? NeonPool : Pool; + const pool = new PoolConstructor({ connectionString: env.DATABASE_URL, // Neon's pooler does the real pooling; each server instance stays small. max: 5, @@ -17,7 +31,7 @@ function createPool(): Pool { }); // An idle client can fail when Neon suspends. Without a listener that // error would crash the process; the pool already discards the client. - pool.on("error", (error) => { + pool.on("error", (error: Error) => { console.error("database pool: idle client error", { message: error.message, }); @@ -26,11 +40,21 @@ function createPool(): Pool { } declare global { - var reeflectPool: Pool | undefined; + var reeflectPool: Pool | NeonPool | undefined; } // Next.js reloads modules in development; keep one pool across reloads. -export const pool: Pool = globalThis.reeflectPool ?? createPool(); -if (process.env.NODE_ENV !== "production") globalThis.reeflectPool = pool; +const runtimePool = globalThis.reeflectPool ?? createPool(); +if (process.env.NODE_ENV !== "production") + globalThis.reeflectPool = runtimePool; -export const db = drizzle(pool, { schema }); +// Expose the shared pg pool methods; the drivers' full client types differ. +export const pool: { + connect(): Promise>; + end(): Promise; +} = runtimePool; + +export const db = + runtimePool instanceof NeonPool + ? drizzleNeon(runtimePool, { schema }) + : drizzle(runtimePool, { schema }); diff --git a/src/lib/db/transaction-guards.ts b/src/lib/db/transaction-guards.ts new file mode 100644 index 0000000..9bac7f1 --- /dev/null +++ b/src/lib/db/transaction-guards.ts @@ -0,0 +1,31 @@ +import "server-only"; +import { and, eq, inArray, sql } from "drizzle-orm"; +import type { db } from "./client"; +import { billPayment } from "./schema"; + +export type LedgerTx = Parameters[0]>[0]; +/** Shared with Bills; acquire BEFORE transaction/account row locks. */ +export async function lockLedgerWorkspace(tx: LedgerTx, workspaceId: string) { + await tx.execute( + sql`select pg_advisory_xact_lock(hashtextextended(${workspaceId}, 53))`, + ); +} +/** Metadata reclassification must not invalidate saved invoice evidence. */ +export async function hasBillEvidence( + tx: LedgerTx, + workspaceId: string, + ids: string[], +): Promise { + if (!ids.length) return false; + const rows = await tx + .select({ id: billPayment.id }) + .from(billPayment) + .where( + and( + eq(billPayment.workspaceId, workspaceId), + inArray(billPayment.originalTransactionId, ids), + ), + ) + .limit(1); + return rows.length > 0; +} diff --git a/src/lib/env.test.ts b/src/lib/env.test.ts index 5795c20..720382e 100644 --- a/src/lib/env.test.ts +++ b/src/lib/env.test.ts @@ -26,6 +26,21 @@ describe("parseEnv", () => { expect(env.DATABASE_URL_UNPOOLED).toBe(DIRECT); }); + it("accepts optional database transports and rejects unsupported ones", () => { + const base = { DATABASE_URL: POOLED, ...AUTH }; + expect( + parseEnv({ ...base, DATABASE_TRANSPORT: "" }).DATABASE_TRANSPORT, + ).toBeUndefined(); + for (const DATABASE_TRANSPORT of ["tcp", "websocket"]) { + expect(parseEnv({ ...base, DATABASE_TRANSPORT }).DATABASE_TRANSPORT).toBe( + DATABASE_TRANSPORT, + ); + } + expect(() => parseEnv({ ...base, DATABASE_TRANSPORT: "http" })).toThrow( + /DATABASE_TRANSPORT/, + ); + }); + it("names every missing variable", () => { const attempt = (): unknown => parseEnv({}); diff --git a/src/lib/env.ts b/src/lib/env.ts index 0f7ade5..8b17e92 100644 --- a/src/lib/env.ts +++ b/src/lib/env.ts @@ -25,6 +25,10 @@ const envSchema = z .object({ /** Runtime connection. On Neon, the pooled string (host contains "-pooler"). */ DATABASE_URL: postgresUrl, + /** Optional Neon WebSocket transport for environments without TCP access. */ + DATABASE_TRANSPORT: optionalText.pipe( + z.enum(["tcp", "websocket"]).optional(), + ), /** Direct connection, used only by Drizzle Kit migrations. */ DATABASE_URL_UNPOOLED: postgresUrl.optional(), /** Signs sessions and cookies (ADR-006). 32+ random characters. */ diff --git a/src/lib/storage/index.ts b/src/lib/storage/index.ts index f4f151a..c09ffa0 100644 --- a/src/lib/storage/index.ts +++ b/src/lib/storage/index.ts @@ -1,4 +1,5 @@ import "server-only"; +import { Agent } from "node:https"; import { Files, FilesError } from "files-sdk"; import { neon } from "files-sdk/neon"; import { env } from "@/lib/env"; @@ -33,15 +34,28 @@ export type NeonStorageConfig = { export function createObjectStore(config: NeonStorageConfig): ObjectStore { // Credentials are passed in, never taken from a machine-wide default, so // only the validated Neon branch values are ever used. - const files = new Files({ - adapter: neon({ - bucket: config.bucket, - endpoint: config.endpoint, - region: config.region, - accessKeyId: config.accessKeyId, - secretAccessKey: config.secretAccessKey, - }), + const adapter = neon({ + bucket: config.bucket, + endpoint: config.endpoint, + region: config.region, + accessKeyId: config.accessKeyId, + secretAccessKey: config.secretAccessKey, }); + // The SDK creates its own agent, so Node's global proxy flag alone does + // not route storage requests through a managed workspace's HTTPS proxy. + if (process.env.HTTPS_PROXY || process.env.https_proxy) { + const handler = adapter.raw.config.requestHandler; + if ( + "updateHttpClientConfig" in handler && + typeof handler.updateHttpClientConfig === "function" + ) { + handler.updateHttpClientConfig( + "httpsAgent", + new Agent({ keepAlive: true, proxyEnv: process.env }), + ); + } + } + const files = new Files({ adapter }); async function listKeys(prefix: string): Promise { const keys: string[] = []; let cursor: string | undefined; diff --git a/tests/e2e/app-nav.spec.ts b/tests/e2e/app-nav.spec.ts index 93c1fb2..aa7756e 100644 --- a/tests/e2e/app-nav.spec.ts +++ b/tests/e2e/app-nav.spec.ts @@ -31,6 +31,7 @@ test.describe("signed in", () => { ); for (const [label, url] of PAGES) { + await hydrated(page, `nav[aria-label='Pages'] a[href$='${url}']`); await nav.getByRole("link", { name: label }).click(); await expect(page).toHaveURL(new RegExp(`/w/[^/]+${url}$`)); diff --git a/tests/e2e/budgets.spec.ts b/tests/e2e/budgets.spec.ts index 48ffbee..74432fc 100644 --- a/tests/e2e/budgets.spec.ts +++ b/tests/e2e/budgets.spec.ts @@ -10,10 +10,15 @@ import { import { Pool } from "pg"; import { hydrated, ownClientAddress, signUpVerified } from "./support"; -const pool = new Pool({ - connectionString: - process.env.DATABASE_URL ?? "postgres://test:test@localhost:5433/app_test", - max: 2, +let pool: Pool; +test.beforeAll(() => { + // Parallel test groups can return to this cached module after afterAll. + pool = new Pool({ + connectionString: + process.env.DATABASE_URL ?? + "postgres://test:test@localhost:5433/app_test", + max: 2, + }); }); const users: string[] = []; const contexts: BrowserContext[] = []; @@ -147,6 +152,9 @@ test.afterAll(async () => { } await pool.end(); expect(errors).toEqual([]); + contexts.length = 0; + users.length = 0; + errors.length = 0; }); test("starts without invented spending, saves and edits a plan, and leaves ledger balances intact", async ({ diff --git a/tests/e2e/categorization.spec.ts b/tests/e2e/categorization.spec.ts index 5a0203a..de4cdb2 100644 --- a/tests/e2e/categorization.spec.ts +++ b/tests/e2e/categorization.spec.ts @@ -11,10 +11,15 @@ import { hydrated, ownClientAddress, signUpVerified } from "./support"; // Real browser + real local PostgreSQL. Fixtures enter transactions as an // importer would; categorization and all corrections use the production UI. -const pool = new Pool({ - connectionString: - process.env.DATABASE_URL ?? "postgres://test:test@localhost:5433/app_test", - max: 2, +let pool: Pool; +test.beforeAll(() => { + // Parallel groups can return to this module after its pool was closed. + pool = new Pool({ + connectionString: + process.env.DATABASE_URL ?? + "postgres://test:test@localhost:5433/app_test", + max: 2, + }); }); const userIds: string[] = []; const contexts: BrowserContext[] = []; diff --git a/tests/e2e/proactive-alerts.spec.ts b/tests/e2e/proactive-alerts.spec.ts index 0366467..f3281d4 100644 --- a/tests/e2e/proactive-alerts.spec.ts +++ b/tests/e2e/proactive-alerts.spec.ts @@ -19,10 +19,14 @@ const SERVICE_TOKEN = "e2e-only-agent-service-token-0123456789"; const WORKER_URL = `http://localhost:${process.env.STAND_IN_WORKER_PORT ?? "8799"}`; const MONEY = /[$¢€£]|\d+\.\d{2}\b/; -const pool = new Pool({ - connectionString: - process.env.DATABASE_URL ?? "postgres://test:test@localhost:5433/app_test", - max: 2, +let pool: Pool; +test.beforeAll(() => { + pool = new Pool({ + connectionString: + process.env.DATABASE_URL ?? + "postgres://test:test@localhost:5433/app_test", + max: 2, + }); }); const users: string[] = []; @@ -60,6 +64,7 @@ test.afterAll(async () => { await pool.query(`DELETE FROM "user" WHERE id = ANY($1::text[])`, [users]); } await pool.end(); + users.length = 0; }); async function textsSentTo( diff --git a/tests/e2e/transfers.spec.ts b/tests/e2e/transfers.spec.ts new file mode 100644 index 0000000..f1f0dc9 --- /dev/null +++ b/tests/e2e/transfers.spec.ts @@ -0,0 +1,553 @@ +import { mkdir } from "node:fs/promises"; +import { + type Browser, + type BrowserContext, + type Page, + expect, + test, +} from "@playwright/test"; +import { Pool } from "pg"; +import { hydrated, ownClientAddress, signUpVerified } from "./support"; +let pool: Pool; +test.beforeAll(() => { + pool = new Pool({ + connectionString: + process.env.DATABASE_URL ?? + "postgres://test:test@localhost:5433/app_test", + max: 2, + }); +}); +const contexts: BrowserContext[] = [], + users: string[] = [], + errors: string[] = []; +const expectedFailure = new WeakSet(); +const today = new Intl.DateTimeFormat("en-CA", { + timeZone: "America/New_York", + year: "numeric", + month: "2-digit", + day: "2-digit", +}).format(new Date()); +const shift = (date: string, days: number) => { + const day = new Date(`${date}T00:00:00Z`); + day.setUTCDate(day.getUTCDate() + days); + return day.toISOString().slice(0, 10); +}; +async function signUp(browser: Browser, baseURL: string | undefined) { + const context = await browser.newContext({ + extraHTTPHeaders: ownClientAddress(), + }); + contexts.push(context); + await signUpVerified(context.request, baseURL, { + name: "Transfer Tester", + email: `transfer-${crypto.randomUUID()}@example.test`, + }); + const session = await ( + await context.request.get("/api/auth/get-session") + ).json(); + users.push(session.user.id); + const page = await context.newPage(); + page.on("pageerror", (error) => { + if ( + expectedFailure.has(page) && + /Minified React error #(419|441)/.test(error.message) + ) + return; + errors.push(error.message); + }); + return { context, page, userId: session.user.id as string }; +} +async function fixture(browser: Browser, baseURL: string | undefined) { + const fx = await signUp(browser, baseURL); + await fx.page.goto("/transactions"); + await expect( + fx.page.getByRole("heading", { name: "Transactions", exact: true }), + ).toBeVisible(); + const ws = new URL(fx.page.url()).pathname.split("/")[2]!; + const cash = crypto.randomUUID(), + card = crypto.randomUUID(); + await pool.query( + `INSERT INTO financial_account (id,workspace_id,institution_name,type,nickname,source,current_balance_cents,balance_as_of) VALUES ($1,$3,'Synthetic','checking','Everyday','manual',50000,$4),($2,$3,'Synthetic','credit_card','Card','manual',-10000,$4)`, + [cash, card, ws, today], + ); + return { ...fx, ws, cash, card, path: `/w/${ws}/transactions/transfers` }; +} +type Fixture = Awaited>; +async function activity( + fx: Fixture, + account: string, + amount: number, + description: string, + extra: { + on?: string; + transfer?: boolean; + pair?: string; + status?: string; + } = {}, +) { + const id = crypto.randomUUID(); + await pool.query( + `INSERT INTO "transaction" (id,workspace_id,financial_account_id,posted_on,amount_cents,description_raw,source,fingerprint,is_transfer,transfer_pair_id,status) VALUES ($1,$2,$3,$4,$5,$6,'manual',$1,$7,$8,$9)`, + [ + id, + fx.ws, + account, + extra.on ?? today, + amount, + description, + extra.transfer ?? false, + extra.pair ?? null, + extra.status ?? "posted", + ], + ); + return id; +} +async function open(fx: Fixture, source?: string, query = "") { + await fx.page.goto( + `${fx.path}?view=all${source ? `&source=${source}` : ""}${query}`, + ); + await expect( + fx.page.getByRole("heading", { name: "Review transfers", exact: true }), + ).toBeVisible(); + await hydrated(fx.page, 'form[aria-label="Transfer filters"] button'); +} +async function confirmPair(page: Page, description: string, candidate = 0) { + const form = page.getByRole("form", { + name: `Confirm pairing: ${description}`, + exact: true, + }); + await form.getByRole("radio").nth(candidate).check(); + await form.getByRole("checkbox").check(); + await form + .getByRole("button", { name: "Confirm pairing", exact: true }) + .click(); + await expect(form).toHaveCount(0); + await expect(page.getByText("Review saved.", { exact: true })).toBeVisible(); +} +async function change(page: Page, name: string, description: string) { + const form = page.getByRole("form", { + name: `${name}: ${description}`, + exact: true, + }); + await form.getByRole("checkbox").check(); + await form.getByRole("button", { name, exact: true }).click(); + await expect(form).toHaveCount(0); + await expect(page.getByText("Review saved.", { exact: true })).toBeVisible(); +} +const snapshot = async (ws: string) => + ( + await pool.query( + `SELECT * FROM "transaction" WHERE workspace_id=$1 ORDER BY id`, + [ws], + ) + ).rows; +const balances = async (ws: string) => + ( + await pool.query( + `SELECT * FROM financial_account WHERE workspace_id=$1 ORDER BY id`, + [ws], + ) + ).rows; +test.afterAll(async () => { + for (const context of contexts) await context.close(); + if (users.length) { + await pool.query( + `DELETE FROM organization WHERE id IN (SELECT organization_id FROM member WHERE user_id=ANY($1::text[]) AND role='owner')`, + [users], + ); + await pool.query(`DELETE FROM "user" WHERE id=ANY($1::text[])`, [users]); + } + await pool.end(); + expect(errors).toEqual([]); + contexts.length = 0; + users.length = 0; + errors.length = 0; +}); +test("requires a specific ambiguous counterpart and confirmation, persists pairing and separates detach from normal activity", async ({ + browser, + baseURL, +}) => { + const fx = await fixture(browser, baseURL); + const source = await activity(fx, fx.cash, -20000, "Cash repayment"); + await activity(fx, fx.card, 20000, "Card credit one"); + await activity(fx, fx.card, 20000, "Card credit two"); + await fx.page.reload(); + await fx.page + .getByRole("link", { name: "Review transfers", exact: true }) + .click(); + await expect(fx.page.getByText(/90-day review window/)).toBeVisible(); + await open(fx, source); + const before = await snapshot(fx.ws), + accounts = await balances(fx.ws); + const form = fx.page.getByRole("form", { + name: "Confirm pairing: Cash repayment", + exact: true, + }); + await expect(form.getByRole("radio", { checked: true })).toHaveCount(0); + await form + .getByRole("button", { name: "Confirm pairing", exact: true }) + .click(); + await expect(form.getByRole("alert")).toContainText( + "Choose a specific counterpart", + ); + expect(await snapshot(fx.ws)).toEqual(before); + await confirmPair(fx.page, "Cash repayment", 1); + await expect( + fx.page.getByRole("heading", { name: "Confirmed pair", exact: true }), + ).toBeVisible(); + const saved = await snapshot(fx.ws); + expect(saved.filter((r) => r.transfer_pair_id)).toHaveLength(2); + expect(await balances(fx.ws)).toEqual(accounts); + await fx.page.reload(); + await expect( + fx.page.getByRole("heading", { name: "Confirmed pair", exact: true }), + ).toBeVisible(); + await change( + fx.page, + "Remove pairing, keep transfer labels", + "Cash repayment", + ); + const detached = await snapshot(fx.ws); + expect(detached.filter((r) => r.is_transfer)).toHaveLength(2); + expect(detached.every((r) => r.transfer_pair_id === null)).toBe(true); + await expect( + fx.page.getByRole("heading", { name: "Individual transfer", exact: true }), + ).toBeVisible(); + await change(fx.page, "Count as normal activity", "Cash repayment"); + expect( + (await snapshot(fx.ws)).find((r) => r.id === source)?.is_transfer, + ).toBe(false); + expect(await balances(fx.ws)).toEqual(accounts); +}); +test("retains a stale selection, rejects a competing match and permits retry after reloading", async ({ + browser, + baseURL, +}) => { + const fx = await fixture(browser, baseURL), + source = await activity(fx, fx.cash, -20000, "Stale cash"), + partner = await activity(fx, fx.card, 20000, "Stale card"); + await open(fx, source); + const form = fx.page.getByRole("form", { + name: "Confirm pairing: Stale cash", + exact: true, + }); + await form.getByRole("radio").check(); + await form.getByRole("checkbox").check(); + await pool.query( + `UPDATE "transaction" SET description_raw='Changed card',updated_at=now() WHERE id=$1`, + [partner], + ); + await form + .getByRole("button", { name: "Confirm pairing", exact: true }) + .click(); + await expect(form.getByRole("alert")).toContainText( + "changed since the form was opened", + ); + await expect(form.getByRole("radio")).toBeChecked(); + await expect(form.getByRole("checkbox")).toBeChecked(); + expect((await snapshot(fx.ws)).every((r) => !r.is_transfer)).toBe(true); + await fx.page.reload(); + await hydrated(fx.page, 'form[aria-label="Transfer filters"] button'); + await confirmPair(fx.page, "Stale cash"); +}); +test("protects paired transaction edits and atomically detaches the survivor on delete with normal balance undo", async ({ + browser, + baseURL, +}) => { + const fx = await fixture(browser, baseURL), + source = await activity(fx, fx.cash, -20000, "Delete cash"), + partner = await activity(fx, fx.card, 20000, "Survivor card"); + await pool.query( + `UPDATE financial_account SET current_balance_cents=30000 WHERE id=$1`, + [fx.cash], + ); + await open(fx, source); + await confirmPair(fx.page, "Delete cash"); + await fx.page + .getByRole("link", { name: "Edit transaction", exact: true }) + .click(); + await hydrated(fx.page, 'form input[name="description"]'); + await expect( + fx.page.getByRole("textbox", { name: "Amount", exact: true }), + ).toHaveCount(0); + await expect( + fx.page.getByRole("checkbox", { name: /Transfer/ }), + ).toBeDisabled(); + await fx.page + .getByRole("textbox", { name: "Description", exact: true }) + .fill("Edited cash description"); + await fx.page + .getByRole("button", { name: "Save changes", exact: true }) + .click(); + await fx.page.goto(`/w/${fx.ws}/transactions/${source}`); + await hydrated(fx.page, 'form input[name="description"]'); + await fx.page + .getByRole("button", { name: "Delete transaction", exact: true }) + .click(); + await fx.page.getByRole("button", { name: "Delete", exact: true }).click(); + await expect(fx.page).toHaveURL(new RegExp(`/w/${fx.ws}/transactions$`)); + expect((await snapshot(fx.ws)).find((r) => r.id === partner)).toMatchObject({ + is_transfer: true, + transfer_pair_id: null, + }); + expect( + (await balances(fx.ws)).find((r) => r.id === fx.cash) + ?.current_balance_cents, + ).toBe("50000"); +}); +test("loads older padded counterparts across pages and supports narrow screens, keyboard focus and dark mode", async ({ + browser, + baseURL, +}) => { + const fx = await fixture(browser, baseURL), + sourceOn = shift(today, -100), + source = await activity(fx, fx.cash, -10001, "Older cash", { + on: sourceOn, + }); + for (let i = 0; i < 22; i++) + await activity(fx, fx.card, 10001, `Older counterpart ${i}`, { + on: shift(sourceOn, -1), + }); + await open(fx); + await expect( + fx.page.getByText("No recorded activity in this review.", { exact: false }), + ).toBeVisible(); + const filters = fx.page.getByRole("form", { + name: "Transfer filters", + exact: true, + }); + await filters.getByLabel("From", { exact: true }).fill(sourceOn); + await filters.getByLabel("Through", { exact: true }).fill(sourceOn); + await filters.getByRole("button", { name: "Apply filters" }).click(); + await expect(fx.page.getByText(/22 eligible counterparts/)).toBeVisible(); + await fx.page + .getByRole("link", { name: "More counterparts", exact: true }) + .click(); + const form = fx.page.getByRole("form", { + name: "Confirm pairing: Older cash", + exact: true, + }); + await expect(form.getByRole("radio")).toHaveCount(2); + await expect(form.getByRole("radio", { checked: true })).toHaveCount(0); + await expect( + fx.page.getByRole("link", { name: "Previous counterparts", exact: true }), + ).toBeVisible(); + await mkdir("docs/screenshots/transfers", { recursive: true }); + for (const width of [360, 1280]) + for (const colorScheme of ["light", "dark"] as const) { + await fx.page.setViewportSize({ width, height: 900 }); + await fx.page.emulateMedia({ colorScheme, reducedMotion: "reduce" }); + expect( + await fx.page.evaluate( + () => document.documentElement.scrollWidth <= window.innerWidth, + ), + ).toBe(true); + await form.getByRole("radio").first().focus(); + await fx.page.keyboard.press("Space"); + await expect(form.getByRole("radio").first()).toBeChecked(); + // Focus scrolls the form into view; capture the sticky header at the top. + await fx.page.evaluate(() => + window.scrollTo({ top: 0, behavior: "instant" }), + ); + await fx.page.screenshot({ + path: `docs/screenshots/transfers/${width}-${colorScheme}.png`, + fullPage: true, + }); + } + await confirmPair(fx.page, "Older cash"); + await fx.page.reload(); + await expect( + fx.page.getByRole("heading", { name: "Confirmed pair", exact: true }), + ).toBeVisible(); + expect( + (await snapshot(fx.ws)).find((r) => r.id === source)?.is_transfer, + ).toBe(true); +}); +test("shows invalid and orphan groups without repairing them and lets viewers read while excluding outsiders", async ({ + browser, + baseURL, +}) => { + const fx = await fixture(browser, baseURL); + const orphan = await activity(fx, fx.cash, -20000, "Orphan transfer", { + transfer: true, + pair: "orphan", + }); + await activity(fx, fx.cash, -50, "Invalid first", { + transfer: true, + pair: "invalid", + }); + await activity(fx, fx.card, -60, "Invalid second", { pair: "invalid" }); + await fx.page.goto(`${fx.path}?view=pairs`); + await expect( + fx.page.getByRole("heading", { name: "Review transfers", exact: true }), + ).toBeVisible(); + await expect( + fx.page.getByRole("heading", { name: "Incomplete pairing", exact: true }), + ).toBeVisible(); + await expect( + fx.page.getByRole("heading", { + name: "Invalid existing pair", + exact: true, + }), + ).toBeVisible(); + const viewer = await signUp(browser, baseURL); + await pool.query( + `INSERT INTO member (id,organization_id,user_id,role,created_at) VALUES ($1,$2,$3,'viewer',now())`, + [crypto.randomUUID(), fx.ws, viewer.userId], + ); + await viewer.page.goto(`${fx.path}?view=pairs`); + await expect(viewer.page.getByText(/Viewer access:/)).toBeVisible(); + await expect( + viewer.page.getByRole("button", { + name: /pairing|transfer|normal activity/, + }), + ).toHaveCount(0); + await expect( + viewer.page.getByRole("link", { name: "Edit transaction", exact: true }), + ).toHaveCount(0); + const outsider = await signUp(browser, baseURL); + await outsider.page.goto(`${fx.path}?source=${orphan}&view=all`); + await expect( + outsider.page.getByText("This page could not be found."), + ).toBeVisible(); + await expect( + outsider.page.getByText("Orphan transfer", { exact: true }), + ).toHaveCount(0); + await open(fx, orphan); + await change( + fx.page, + "Remove pairing, keep transfer labels", + "Orphan transfer", + ); + expect((await snapshot(fx.ws)).find((r) => r.id === orphan)).toMatchObject({ + is_transfer: true, + transfer_pair_id: null, + }); +}); +test("blocks label changes to allocated Bills evidence and shows the explicit unlink route", async ({ + browser, + baseURL, +}) => { + const fx = await fixture(browser, baseURL), + source = await activity(fx, fx.cash, -20000, "Evidence cash"); + const series = crypto.randomUUID(), + detail = crypto.randomUUID(), + cycle = crypto.randomUUID(), + payment = crypto.randomUUID(); + await pool.query( + `INSERT INTO recurring_series (id,workspace_id,financial_account_id,merchant_normalized,name,kind,decision,amount_mode,schedule_unit,schedule_every,amount_cents,baseline_amount_cents,next_on) VALUES ($1,$2,$3,'evidence cash','Evidence','bill','confirmed','fixed','months',1,20000,20000,$4)`, + [series, fx.ws, fx.cash, today], + ); + await pool.query( + `INSERT INTO bill_details (id,workspace_id,financial_account_id,merchant_normalized,anchor_on,date_source) VALUES ($1,$2,$3,'evidence cash',$4,'user')`, + [detail, fx.ws, fx.cash, today], + ); + await pool.query( + `INSERT INTO bill_cycle (id,workspace_id,bill_id,scheduled_on,due_on,invoice_cents,estimate_cents,date_source) VALUES ($1,$2,$3,$4,$4,20000,20000,'user')`, + [cycle, fx.ws, detail, today], + ); + await pool.query( + `INSERT INTO bill_payment (id,workspace_id,cycle_id,evidence_workspace_id,transaction_id,original_transaction_id,financial_account_id,amount_cents,posted_on,description,is_transfer) VALUES ($1,$2,$3,$2,$4,$4,$5,20000,$6,'Evidence cash',false)`, + [payment, fx.ws, cycle, source, fx.cash, today], + ); + await open(fx, source); + const form = fx.page.getByRole("form", { + name: "Mark as an individual transfer: Evidence cash", + exact: true, + }); + await form.getByRole("checkbox").check(); + await form + .getByRole("button", { + name: "Mark as an individual transfer", + exact: true, + }) + .click(); + await expect(form.getByRole("alert")).toContainText( + "Unlink its evidence in Bills first", + ); + await expect( + form.getByRole("link", { name: "Review payment evidence in Bills" }), + ).toHaveAttribute("href", `/w/${fx.ws}/bills?account=${fx.cash}`); + expect( + (await snapshot(fx.ws)).find((r) => r.id === source)?.is_transfer, + ).toBe(false); +}); +test("recovers a failed review read without showing a false empty state", async ({ + browser, + baseURL, +}) => { + const fx = await fixture(browser, baseURL); + await activity(fx, fx.cash, -100, "Recovery activity"); + const result = await pool.query( + `INSERT INTO financial_account (id,workspace_id,institution_name,type,nickname,source,current_balance_cents) SELECT gen_random_uuid()::text,$1,'Test','checking','Overflow','synthetic',0 FROM generate_series(1,999) RETURNING id`, + [fx.ws], + ); + expectedFailure.add(fx.page); + await fx.page.goto(fx.path); + await expect(fx.page.getByRole("main").getByRole("alert")).toContainText( + "Transfer review is temporarily unavailable", + ); + await expect( + fx.page.getByText(/No recorded activity in this review/), + ).toHaveCount(0); + await pool.query(`DELETE FROM financial_account WHERE id=ANY($1::text[])`, [ + result.rows.map((r) => r.id), + ]); + await hydrated(fx.page, "main button"); + await fx.page.getByRole("button", { name: "Try again", exact: true }).click(); + await expect( + fx.page.getByRole("heading", { name: "Review transfers", exact: true }), + ).toBeVisible(); + await expect( + fx.page.getByRole("article", { name: "Recovery activity" }), + ).toBeVisible(); + expectedFailure.delete(fx.page); +}); + +test("retains selection after a failed save request and retries without reclassification", async ({ + browser, + baseURL, +}) => { + const fx = await fixture(browser, baseURL), + source = await activity(fx, fx.cash, -20000, "Retry cash"); + await activity(fx, fx.card, 20000, "Retry card"); + await open(fx, source); + const form = fx.page.getByRole("form", { + name: "Confirm pairing: Retry cash", + exact: true, + }); + await form.getByRole("radio").check(); + await form.getByRole("checkbox").check(); + const requestStarted = Promise.withResolvers(); + const releaseRequest = Promise.withResolvers(); + await fx.page.route( + (url) => url.pathname === fx.path, + async (route) => { + if (route.request().method() !== "POST") return route.continue(); + requestStarted.resolve(); + await releaseRequest.promise; + await route.abort("failed"); + }, + ); + await form + .getByRole("button", { name: "Confirm pairing", exact: true }) + .click(); + await requestStarted.promise; + await expect( + form.getByRole("button", { name: "Saving…", exact: true }), + ).toBeDisabled(); + await expect(form.getByRole("checkbox")).toBeDisabled(); + releaseRequest.resolve(); + await expect(form.getByRole("alert")).toContainText( + "Your selection is kept; try again", + ); + await expect(form.getByRole("radio")).toBeChecked(); + await expect(form.getByRole("checkbox")).toBeChecked(); + expect((await snapshot(fx.ws)).every((r) => !r.is_transfer)).toBe(true); + await fx.page.unrouteAll({ behavior: "wait" }); + await form + .getByRole("button", { name: "Confirm pairing", exact: true }) + .click(); + await expect( + fx.page.getByRole("heading", { name: "Confirmed pair", exact: true }), + ).toBeVisible(); +}); diff --git a/vitest.config.mts b/vitest.config.mts index f8e0251..b8c0573 100644 --- a/vitest.config.mts +++ b/vitest.config.mts @@ -2,6 +2,16 @@ import { fileURLToPath } from "node:url"; import { defineConfig } from "vitest/config"; import { testStorageEnv } from "./tests/support/storage-env"; +// Cloud workspaces may inject the app's Neon production URL. Test workers +// and any scripts they launch must use local PostgreSQL instead. +if ( + process.env.DATABASE_URL && + new URL(process.env.DATABASE_URL).hostname.endsWith(".neon.tech") +) { + process.env.DATABASE_URL = "postgres://test:test@localhost:5433/app_test"; + process.env.DATABASE_URL_UNPOOLED = process.env.DATABASE_URL; +} + const fromRoot = (path: string): string => fileURLToPath(new URL(path, import.meta.url)); @@ -25,6 +35,7 @@ export default defineConfig({ DATABASE_URL: process.env.DATABASE_URL ?? "postgres://test:test@localhost:5433/app_test", + DATABASE_TRANSPORT: "tcp", BETTER_AUTH_SECRET: "test-only-not-a-real-secret-0123456789", BETTER_AUTH_URL: "http://localhost:3000", AGENT_SERVICE_TOKEN: "test-only-agent-service-token-0123456789",