@everystack/mcp 0.3.3 → 0.4.1

package/dist/adding-database.md

@@ -13,7 +13,7 @@ You already have a running Expo app. Now you're adding:
 - **@everystack/logging** — structured logging so you can see what your app is doing.
 - **@everystack/security** — device attestation and biometric auth.
 - **@everystack/query** — React hooks that make it easy to fetch and display data.
-- **Drizzle ORM** — defines your database tables in TypeScript. You describe what data you want to store, and Drizzle creates the tables for you.
+- **@everystack/model** — declares your database tables in TypeScript with `defineModel`. You describe what data you want to store and who can read/write it, and everystack generates the migration and the typed schema for you.
 
 ## Step 1: Install PostgreSQL
 
@@ -64,24 +64,31 @@ You should see a table with the value `1`. If so, your database is ready.
 From your project directory:
 
 ```bash
-pnpm add @everystack/api @everystack/auth @everystack/admin @everystack/logging @everystack/security @everystack/query
+pnpm add @everystack/api @everystack/auth @everystack/admin @everystack/logging @everystack/security @everystack/query @everystack/model
 pnpm add drizzle-orm
-pnpm add -D drizzle-kit
 ```
 
-## Step 4: Create your database schema
+## Step 4: Declare your database schema
 
-The schema defines what data your app stores. Create a file at `db/schema.ts`.
+The schema defines what data your app stores. Create your tables in `db/models/` — one
+`defineModel` per table (for example `db/models/post.ts`), composed onto a `defineModule`
+in `db/models/index.ts`.
 
-A schema is like designing a spreadsheet before you start filling in data. You decide what columns each table has, what type of data goes in each column, and how tables relate to each other.
+A model is like designing a spreadsheet before you start filling in data. You decide what columns each table has, what type of data goes in each column, and how tables relate to each other — plus who can read and write each table.
 
-Read everystack://schema-patterns for design patterns and examples. Key conventions:
+You do **not** hand-write `db/schema.ts` and you do **not** run `drizzle-kit generate` —
+everystack generates the migration and the typed artifact from your Models.
 
-- UUID primary keys with `defaultRandom()`
-- `created_at` and `updated_at` timestamps on all tables
-- Foreign key references with proper cascading
-- Relations defined for both SSR and API query embedding
-- Snake_case column names
+Read everystack://schema-patterns for the `defineModel` patterns and examples. Key conventions:
+
+- UUID primary keys with `field.uuid().primaryKey().defaultRandom()`
+- `createdAt` and `updatedAt` timestamps on all tables
+- Foreign key references with `.references('users', 'id')`
+- Relations declared on the Model (used for both SSR and API query embedding)
+- Authorization declared with `can()` abilities (compiles to grants + RLS)
+
+For views, materialized views, functions, and triggers, read everystack://derived-objects
+— they are declared as descriptors and deploy via `db:reconcile`, not migrations.
 
 ## Step 5: Configure the handler
 
@@ -121,29 +128,35 @@ export async function POST(request: Request) {
 // ... PATCH, DELETE
 ```
 
-## Step 8: Run migrations
+## Step 8: Move your database to match your Models
 
-Migrations create the actual tables in your database based on your schema.
+`db:sync` makes your local dev database match your checkout — tables, authz, and the
+derived layer — in one command. You never run `drizzle-kit` or write a SQL migration.
 
 ```bash
-npx drizzle-kit generate
-npx drizzle-kit migrate
+everystack db:sync --database-url "$DATABASE_URL"
 ```
 
-The first command generates SQL files from your schema. The second runs them against your database.
+This is the dev edit loop: change `db/models/`, run `db:sync`, test, repeat. When you're
+ready to record the change as a migration for protected stages, run `everystack db:generate`
+(and later reach a deployed stage with `db:plan` → `db:apply`).
+
+Read everystack://database-operations for the full workflow — the dev loop, importing data,
+and safely migrating a deployed stage.
 
 ## Step 9: Security
 
 **This is not optional.** Read everystack://security for the three-layer security model.
 
-Your database needs Row Level Security (RLS) policies. These are rules that control who can see and change what data. Even if your app code has a bug, the database enforces access control.
+Your database needs Row Level Security (RLS) — rules that control who can see and change what data. Even if your app code has a bug, the database enforces access control.
 
-At minimum:
-- Create database roles (`anon`, `authenticated`, `admin`)
-- Add RLS policies to every table
-- Set up GRANTs so each role can only access what it should
+In everystack you **declare** this on your Models rather than hand-writing SQL: `can()`
+abilities on each `defineModel` compile to database roles (`anon`, `authenticated`,
+`admin`), GRANTs, and RLS policies, and `db:sync` deploys them. `db:check` (the CI gate)
+refuses a table without RLS. Never hand-write `CREATE ROLE`, `GRANT`, or `CREATE POLICY`.
 
-The security resource has copy-paste SQL templates for common patterns.
+The security resource explains the policies your abilities compile to and the patterns
+behind them.
 
 ## Step 10: Verify
 

package/dist/cli.md

@@ -28,11 +28,52 @@ everystack update --channel staging --platform web
 Flags: `--channel` (default: production), `--message`, `--platform` (ios/android/web/all), `--skip-export`.
 
 ### Database
+
+You declare tables in `db/models/` (`defineModel`) and derived objects as descriptors;
+these verbs move a database. Full operational guidance: everystack://database-operations.
+
+**Schema (declare → deploy)**
+```bash
+everystack db:sync            # Make a dev DB match your checkout — state + authz + compute, one verb
+everystack db:generate        # STATE layer (tables) → next migration file (--dry-run prints the SQL, writes nothing)
+everystack db:reconcile       # Deploy the compute layer only (views/matviews/functions/triggers)
+everystack db:check           # CI gate: declared state composes + generated artifacts match regeneration
+everystack db:fingerprint     # Content-address the live base schema vs the Models — MATCH/MISMATCH
+everystack db:diff            # The state edge between two declared states — no DB, CI-pure
+```
+
+**Safe remote migration (protected stages)**
+```bash
+everystack db:plan --stage X --out X.plan.json     # Mint a reviewable edge — read-only, ephemeral
+everystack db:apply --plan X.plan.json --stage X   # Verify → apply → verify, credential-free via the ops Lambda
+everystack db:approvers --stage X --set "…"        # Declare who may run destructive applies (STS-verified)
+```
+
+**Backups & safety**
+```bash
+everystack db:snapshot --stage X       # Physical RDS snapshot (instant DR)
+everystack db:snapshots --stage X       # List manual RDS snapshots
+everystack db:backup --stage X          # Logical pg_dump → private S3 backups bucket
+everystack db:backups --stage X         # List logical backups
+everystack db:backup:download <id> --stage X   # Presigned download URL (1h)
+everystack db:restore --from <id> --stage X --confirm   # Restore a backup INTO a stage (destructive)
+```
+
+**Local dev databases**
+```bash
+everystack db:template:refresh          # Build the dev template from declared state + seed
+everystack db:branch                    # Per-git-branch dev DB from the template (--list / --prune)
+everystack db:fork --from-stage src --stage tgt --confirm   # Fork a deployed stage's DB into a feature stage
+```
+
+**Data**
 ```bash
-everystack db:migrate                                    # Run migrations via Lambda
-everystack db:seed                                       # Seed database (dev only)
+everystack db:seed --stage dev          # Declarative seed script (dev only; refuses on production)
+everystack db:backfill --apply          # One-shot data moves from db/backfills/*.sql (own record)
+everystack pipeline:run --stage X       # Ingest pipeline (credential-free in the ops Lambda)
+everystack db:migrate                   # Run the generated migration on a deployed stage via Lambda invoke
 everystack db:psql --stage dev -c "SELECT * FROM posts"  # Read-only SQL via Lambda
-everystack console --stage dev                           # Interactive REPL with db + schema
+everystack console --stage dev          # Interactive REPL with db + schema
 ```
 
 The REPL has `db`, `schema`, `eq`, `and`, `or`, `gt`, `lt`, `count`, `sum`, `avg`, `sql`, `desc`, `asc` in scope.

package/dist/core.md

@@ -158,11 +158,24 @@ const { data } = await api.rpc('timeline', { limit: 20 });
 
 All infrastructure commands use **AWS IAM credentials** (not shared secrets).
 
+You declare tables in `db/models/` with `defineModel` and the derived layer as descriptors
+(see everystack://derived-objects); the CLI moves the database — you never run
+`drizzle-kit` or hand-write a migration. Full operational guidance:
+everystack://database-operations.
+
 | Command | What it does |
 |---------|-------------|
 | `everystack update --channel production` | OTA deploy (no infrastructure changes) |
-| `everystack db:migrate` | Run Drizzle migrations via Lambda invoke |
+| `everystack db:sync` | Dev DB ← your checkout (state + authz + compute), one verb |
+| `everystack db:generate` | STATE layer (tables) → next migration file |
+| `everystack db:reconcile` | Deploy the compute layer (views/matviews/functions/triggers) |
+| `everystack db:check` | CI gate: declared state composes + artifacts match regeneration |
+| `everystack db:plan --stage X` | Mint a reviewable, fingerprint-pinned edge (read-only) |
+| `everystack db:apply --plan … --stage X` | Verify → apply → verify, credential-free via the ops Lambda |
+| `everystack db:snapshot / db:backup --stage X` | Physical RDS snapshot / logical pg_dump before a risky migration |
 | `everystack db:seed` | Seed database via Lambda invoke (dev only) |
+| `everystack db:backfill --apply` | One-shot data moves from `db/backfills/*.sql` |
+| `everystack db:migrate` | Run the generated migration on a deployed stage via Lambda invoke |
 | `everystack db:psql --stage dev -c "SQL"` | Execute read-only SQL via Lambda |
 | `everystack console --stage dev` | Interactive REPL with db + schema in scope |
 | `everystack logs:errors --stage dev` | Query recent error logs |
@@ -173,6 +186,11 @@ All infrastructure commands use **AWS IAM credentials** (not shared secrets).
 | `everystack diag URL` | Diagnose deployed page freshness |
 | `everystack analyze:ssr` | Static analysis for SSR anti-patterns |
 
+On a dev database you `db:sync` freely; a protected stage takes `db:plan` → `db:apply`
+(fingerprint-verified, snapshot + approver gates on destructive plans); `db:check` is the
+per-PR CI gate; `db:reconcile` deploys compute; `db:seed`/`db:backfill` move data;
+`db:snapshot`/`db:backup` are the safety net.
+
 ## Key Patterns
 
 **Schema-agnostic.** The library knows nothing about your tables. You pass your Drizzle schema to `createHandler()`. Your schema, your migrations, your database.

package/dist/database-operations.md

@@ -0,0 +1,236 @@
+# Database Operations: local dev, data import, and SAFE remote migration
+
+> The one thing to internalize: **on a dev database you `db:sync` freely; on any protected
+> stage you `db:plan`, snapshot, `db:apply`, and a human approves destruction.** The
+> database's own declared state is the authority — every change is verified against a
+> content-addressed fingerprint, and the operator never holds a production database URL.
+
+Read this to change a deployed schema, import data, or set up a local dev database. For
+declaring the objects themselves, see `everystack://schema-patterns` (tables) and
+`everystack://derived-objects` (views/matviews/functions/triggers).
+
+## The model: two layers, three verbs by target
+
+The schema is **state** (tables, constraints, authz, sequences — migrated) and **compute**
+(functions, views, matviews, triggers — reconciled). You almost never run the layer verbs
+by hand; you run one of three verbs, chosen by WHERE you are applying:
+
+| Target | Verb | What it does |
+|--------|------|--------------|
+| **Dev database** (yours, direct URL) | `db:sync` | Make the database match your checkout — state + compute + authz, one verb. Fast, no ceremony. |
+| **Protected stage** (dev/staging/prod, deployed) | `db:plan` → `db:apply` | Mint a reviewable edge, then apply it credential-free with before/after verification. |
+| **CI / every PR** | `db:check` | Gate: the declared state composes and generated artifacts match regeneration. Exit 1 on drift. |
+
+`db:sync` is for databases you own directly. `db:plan`/`db:apply` is for databases you
+reach through the deployed ops Lambda — you never hold their URL.
+
+## Local development
+
+### A per-branch dev database
+
+```bash
+everystack db:template:refresh        # build the dev template <base>_tpl from the DECLARED
+                                      # state + the app's db:seed script (never a data copy)
+everystack db:branch                  # mint a dev DB for the current git branch from the template
+                                      # (seed rows inherited); db:sync evolves it as you edit
+everystack db:branch --list           # what branch DBs exist
+everystack db:branch --prune --confirm # drop DBs whose branches are gone (mapped via COMMENT)
+```
+
+The template is built from your **declared** models + seed, never copied from a real
+database — so a fresh branch DB is reproducible and PII-free.
+
+### The edit loop
+
+```bash
+# edit db/models/ — a table field, or a descriptor body in derived.ts
+everystack db:sync --database-url "$DATABASE_URL"   # the DB now matches your checkout
+pnpm test
+# iterate; commit when happy — the model/descriptor diff IS the change
+```
+
+`db:sync` flags: `--allow-drops` (include destructive changes; held back by default),
+`--overwrite-drift` (rebuild a hand-edited derived object from source).
+
+### Seeing the change as SQL first
+
+```bash
+everystack db:generate --dry-run --database-url "$DATABASE_URL"   # the edge as SQL, writes NOTHING
+everystack db:diff --from-models db/models/index.ts --check       # models-vs-models edge, no DB at all (CI-pure)
+```
+
+`db:generate` (without `--dry-run`) writes the next migration file for the STATE layer;
+`db:sync` and `db:apply` are how it reaches a database.
+
+## Importing data properly
+
+Data has three legitimate homes. **Never hand-write ad-hoc `INSERT`s in a migration or run
+them through `psql` for anything repeatable** — that is unversioned, unrepeatable, and a
+cheat gate flags bundled data.
+
+1. **`db:seed`** — the app's declarative seed script, for dev/demo rows. Runs on dev
+   databases (and dev-tier stages); refuses on production.
+   ```bash
+   everystack db:seed --stage dev
+   ```
+2. **`db:backfill`** — one-shot DATA moves authored as SQL in `db/backfills/*.sql`. Identity
+   is the file's **content hash** (renaming or reformatting is a no-op), each database keeps
+   its own record (`everystack.backfill_log`), an edited-after-run file is **BLOCKED**, and
+   it **never runs as a schema side effect** — you run it deliberately.
+   ```bash
+   everystack db:backfill              # list pending (dry)
+   everystack db:backfill --apply      # run the pending backfills
+   ```
+   Use it for expand → backfill → contract: add the new column (schema), move the data
+   (backfill), drop the old column later (a separate destructive plan).
+3. **The ingest pipeline** — for real, ongoing data ingestion (`defineStage`/`definePipeline`,
+   run via `pipeline:run`). This is the framework path for loading a dataset, not a script.
+   ```bash
+   everystack pipeline:run --stage dev            # credential-free, runs in the ops Lambda
+   ```
+
+## Migrating a REMOTE stage SAFELY
+
+This is the ceremony. Every step exists because a shortcut here loses data or races another
+operator. Do them in order.
+
+### 1. Gate it in CI
+
+```bash
+everystack db:check          # the declared state composes; generated artifacts match regeneration
+```
+
+`db:check` is the per-PR gate. With a scratch PostgreSQL it builds the whole declared
+database from scratch and requires a fingerprint MATCH. A PR that fails `db:check` is not
+mergeable — the schema is broken before it ever reaches a stage.
+
+### 2. Mint a reviewable plan
+
+```bash
+everystack db:plan --stage production --out prod.plan.json
+```
+
+`db:plan` is **read-only**. It asks the target its live fingerprint, diffs your checkout
+against it, and writes one plan file: the edge plus both endpoint fingerprints. It prints
+the **shape first** — a histogram (`shape: 402 policies, 398 grants, 201 rls, …`) before any
+SQL wall — and itemizes every DESTRUCTIVE statement in red with the rebuild cost. A plan
+with held drops refuses to mint unless you pass `--allow-drops` (destruction is carried
+explicitly). Plans are **ephemeral** — attach them to the PR/release, never commit them.
+
+### 3. Read the plan
+
+Look at the shape, the destructive itemization, and the rebuild estimate. This is the
+review surface — the point where a human (or you) decides the edge is what was intended.
+
+### 4. Apply it credential-free
+
+```bash
+everystack db:apply --plan prod.plan.json --stage production
+```
+
+With `--stage`, the WRITE runs **inside the ops Lambda over IAM — the operator never holds
+the database URL**. `db:apply` verifies → applies → verifies, and **refuses** unless:
+
+- **the live fingerprint still equals `plan.from`** (the concurrency lock — nobody changed
+  the target since you minted the plan; if they did, re-mint), AND
+- **your checkout descends from the commit that declares the target's state** (the
+  fast-forward rule — "rebase first"; a stale checkout can't silently revert merged work).
+
+Every refusal is recorded in `everystack.schema_log`. `--database-url` is local-dev-only;
+protected stages always go through `--stage`.
+
+### 5. Destructive plans carry more gates
+
+A plan is DESTRUCTIVE if it drops (table/column/type) or narrows a type (a lossy
+`SET DATA TYPE`). Those additionally require, all of them:
+
+- **`--confirm`** — always, explicitly.
+- **A snapshot** — taken automatically via `db:backup` when you pass `--stage` (or supply
+  one with `--snapshot-ref`). No snapshot, no destructive apply.
+- **The stage's approver set** — if declared, `db:apply` verifies the caller's AWS identity
+  (STS) against it. Set it with `db:approvers`:
+  ```bash
+  everystack db:approvers --stage production --set "cto,arn:aws:iam::…:user/cto"
+  everystack db:approvers --stage production --set ''     # disable destructive applies entirely
+  ```
+
+Prefer never to destroy in place. The safe path for removing a column is the **contract
+phase**: `field.deprecated()` first (the column stays readable, new writes are rejected,
+generated types strike it through), then the physical drop later as its own confirmed,
+snapshotted, approver-gated plan.
+
+## Snapshot-first: the safety net
+
+Two backup mechanisms, different shapes — know when to reach for each:
+
+| | `db:snapshot` | `db:backup` |
+|---|---|---|
+| Kind | **Physical** RDS snapshot (whole instance) | **Logical** `pg_dump` of one database → private S3 |
+| Speed to safety | Instant (control-plane, no VPC) | Minutes (dumps the data) |
+| Restore | RDS restore (new instance) — instant DR | `db:restore` INTO a stage; downloadable, portable |
+| Requires | RDS (not Aurora Serverless v2 the same way) | any Postgres reachable by the ops Lambda |
+
+```bash
+everystack db:snapshot  --stage production     # physical, instant — the "oh no" button
+everystack db:snapshots --stage production      # list manual snapshots
+everystack db:backup    --stage production      # logical pg_dump → S3 backups bucket
+everystack db:backups   --stage production      # list logical backups
+everystack db:backup:download <id> --stage production   # presigned download URL (1h)
+```
+
+**RDS snapshot first?** For a destructive apply, `db:apply` already forces a logical backup —
+you cannot destroy without one. But before any large or risky migration on a stage that
+holds real data, take a **physical `db:snapshot` first** as well: it is instant, it captures
+the whole instance, and restoring it is the fastest path back if something the plan didn't
+foresee goes wrong. Cheap insurance; take it.
+
+## Importing data into a REMOTE stage
+
+- **`db:seed --stage dev`** — the declarative seed, dev-tier only (refuses on production).
+- **`pipeline:run --stage <name>`** — the ingest pipeline, credential-free in the ops
+  Lambda. The way to load a real dataset into a deployed stage.
+- **`db:fork --from-stage <src> --stage <tgt> --confirm`** — copy a DEPLOYED stage's
+  database (schema + data) into a feature stage: backup → presigned URL (the cross-stage
+  hand-off) → restore via the target's ops Lambda. **Production is never a target**, and
+  forking FROM a prod-tier stage warns about PII. Use it to get realistic data into a
+  throwaway stage.
+- **`db:restore --from <id> --stage <name> --confirm`** — restore a logical backup INTO a
+  stage. Destructive (it replaces the target), so `--confirm` is required.
+
+## Why `--stage` is the safe boundary
+
+Operator verbs that touch a protected database run their WRITE inside that stage's **ops
+Lambda**, invoked over IAM. The operator's own credentials never resolve the database URL —
+your AWS identity IS the authorization, CloudTrail records the access, and a leaked laptop
+can't dump production. `--database-url` exists only for local dev databases you own outright.
+
+## Command index
+
+```bash
+# Declare (edit files), then:
+everystack db:sync            # dev DB ← your checkout (state + compute), one verb
+everystack db:reconcile       # compute layer only (views/matviews/functions/triggers)
+everystack db:generate        # STATE layer → migration file / --apply / --dry-run
+everystack db:check           # CI gate: declared state composes; artifacts match
+everystack db:fingerprint     # content-address live schema vs models — MATCH/MISMATCH
+
+# Reach a protected stage safely:
+everystack db:plan --stage X --out X.plan.json     # mint a reviewable edge (read-only)
+everystack db:apply --plan X.plan.json --stage X   # verify → apply → verify (credential-free)
+everystack db:approvers --stage X --set "…"        # who may run destructive applies
+
+# Back up / restore:
+everystack db:snapshot --stage X    # physical RDS snapshot (instant DR)
+everystack db:backup   --stage X    # logical pg_dump → S3
+everystack db:restore --from <id> --stage X --confirm
+
+# Local dev databases:
+everystack db:template:refresh      # build the dev template from declared state + seed
+everystack db:branch                # per-branch dev DB from the template
+
+# Data:
+everystack db:seed --stage dev      # declarative seed (dev only)
+everystack db:backfill --apply      # one-shot data moves (db/backfills/*.sql)
+everystack pipeline:run --stage X   # ingest pipeline (credential-free)
+everystack db:fork --from-stage prod --stage feature --confirm   # copy a stage's data
+```

package/dist/deployment.md

@@ -5,6 +5,8 @@
 ## When to Use
 Read this when deploying an everystack app to AWS for the first time or adding a new stage.
 
+If your app.json has `web.output: "server"` (SSR pages or `+api.ts` routes — most Expo Router apps), read everystack://expo-server-deploy next: it covers what deploys where for that shape, including where your `+api.ts` routes run.
+
 ## Prerequisites
 
 - Node.js 20+, pnpm