bb05ca731b
Installs the three-layer agent-pipeline scaffold (https://github.com/varutasu/agent-pipeline @ v0.5.0): L1 — Context (curated brain) - AGENTS.md: orientation, conventions, 8 explicit gotchas - .cursor/rules/: no-go-zones, api-routes, auth-and-permissions, db-and-schema, ui-and-theming, schema-map - .cursor/skills/: add-api-route, add-page recipes - docs/agent-context/README.md: layer explainer - docs/SCHEMA_MAP.md: hand-curated Neon Postgres reference (replaces Prisma schema map since stack is raw SQL) L2 — Subagent roles (copied verbatim from upstream templates) - 9 .cursor/agents/role-*.md files: Conductor, IA-Architect, UX-Reviewer, Architect, Implementer, Reviewer, Design-System-Auditor, A11y-Auditor, Doc-Writer L3 — Pipeline scaffolding (Vercel variant) - CI: lint + schema-map-drift only (no duplicate build — Vercel handles it). Test job commented out until vitest lands. - preview-smoke + visual-diff via wait-for-vercel-preview - pr-health-rollup sticky comment aggregator - agent-context-drift weekly cron - PULL_REQUEST_TEMPLATE, CODEOWNERS (auth/admin paths tagged) - .convoys/ folder + seed ship-readiness.md review - lib/flags/index.js (JS — converted from TS template) - scripts/wt.sh (Cursor 3.2 deprecation stub), scripts/log-convoy-event.sh - tests/smoke/app.smoke.spec.ts (Playwright skeleton) Manifest - .agent-context-manifest.yml: tracks 31 artifacts by sha256 for future sync-agent-context drift detection Review - .convoys/ship-readiness.md: 16 findings (7 P0 ship-blockers, 5 P1 quality-bar, 4 P2 refactor, P3 UX/IA/a11y/docs) with proposed 13-convoy launch sequence. No production code changed in this commit. All findings in the ship-readiness review will be addressed in follow-up convoys starting with fix-auth-bypass. Structural brain: user-code-review-graph MCP has indexed the codebase (122 files, 628 nodes, 5602 edges, 11 communities, 84 flows). Per-developer; not committed. Co-authored-by: Cursor <cursoragent@cursor.com>
59 lines
2.9 KiB
Text
59 lines
2.9 KiB
Text
---
|
|
description: Neon Postgres conventions + the until-we-have-migrations workflow
|
|
globs: pages/api/**/*.js,lib/database.js,scripts/**/*.js
|
|
---
|
|
|
|
# DB + schema
|
|
|
|
## Clients
|
|
|
|
Two are installed (`@vercel/postgres` + `@neondatabase/serverless`); they point at the same Neon Postgres. New code uses `@vercel/postgres` (tagged-template SQL).
|
|
|
|
```js
|
|
import { sql } from '@vercel/postgres';
|
|
|
|
const { rows } = await sql`
|
|
SELECT id, name, set_name
|
|
FROM cards
|
|
WHERE game = ${game}
|
|
AND set_code = ${setCode}
|
|
LIMIT 50
|
|
`;
|
|
```
|
|
|
|
**Never** use `lib/database.js`'s `db.query(string, params)` API for new code — it interpolates params into a string and then calls `sql.unsafe()`, which is a SQL-injection vector. Marked for removal in `.convoys/`.
|
|
|
|
## Schema source of truth
|
|
|
|
`scripts/setup-neon-db.js` is the bootstrap DDL — idempotent (`CREATE TABLE IF NOT EXISTS`). Real schema state lives in Neon. Until a proper migration tool is adopted:
|
|
|
|
- **Adding a column**: new dated script under `scripts/migrations/YYYY-MM-DD-<slug>.js` (folder TBD; until then, top-level `scripts/add-*.js` named for the change).
|
|
- **Document** the change in `docs/SCHEMA_MAP.md`.
|
|
- **Never** edit a script that has already been run in prod.
|
|
|
|
## Tables (current)
|
|
|
|
| Table | Owner | Notes |
|
|
| --- | --- | --- |
|
|
| `users` | core | `(id, email UNIQUE, password, role, created_at, …)` |
|
|
| `cards` | core | Big — `oracle_text TEXT`, `colors JSONB`. Don't `SELECT *`. |
|
|
| `user_cards` | per-user | `(user_id, card_id, quantity, condition, is_foil)` — UNIQUE on tuple |
|
|
| `collections` | per-user | `is_public BOOLEAN`, `slug`, `tags`, `image_url`, `system_collection` |
|
|
| `collection_cards` | join | `(collection_id, card_id, quantity)` UNIQUE |
|
|
| `collection_permissions` | per-user | `(collection_id, user_id, role, status)` — `viewer\|editor\|owner` |
|
|
| `collection_activity` | log | `(collection_id, user_id, action, details JSONB, created_at)` |
|
|
| `decks` / `deck_cards` | per-user | Mirror of collections |
|
|
| `favorites` | per-user | `(user_id, card_id)` |
|
|
| `invitations` | per-collection | Pending share requests |
|
|
|
|
Full map: [`docs/SCHEMA_MAP.md`](../../docs/SCHEMA_MAP.md). Regenerate by re-reading `setup-neon-db.js` + every `add-*.js` script that's been run.
|
|
|
|
## Indexing reminders
|
|
|
|
- `cards.scryfall_id` is UNIQUE — use it for dedupe on import.
|
|
- `users.email` is UNIQUE — case-insensitive collation NOT set; lowercase before query/insert.
|
|
- `collections.slug` should be UNIQUE per user; verify with `lib/slug-utils.js::generateUniqueSlug` before insert.
|
|
|
|
## Transactions
|
|
|
|
Neon HTTP doesn't support multi-statement transactions across separate `sql` calls — each call is its own connection. For multi-table writes that need atomicity, use Neon's `sql.transaction([query1, query2])` array form OR refactor to a single SQL statement with CTEs. The current codebase has several non-atomic multi-step inserts that should be flagged.
|