@everystack/mcp 0.3.2 → 0.4.0

package/src/prompts/design-schema.ts

@@ -4,10 +4,10 @@ import { z } from 'zod';
 export function registerDesignSchemaPrompt(server: McpServer): void {
   server.prompt(
     'design-schema',
-    'Interactive schema design: plain English description → Drizzle schema + migrations + RLS policies + handler config + testing checklist.',
+    'Interactive schema design (0.4.0): plain English description → declared Models (defineModel + can abilities) + derived descriptors + testing checklist. Authz and handler config are DERIVED from the Models, never hand-written.',
     {
       description: z.string().describe('Plain English description of the data model (e.g., "blog with posts, comments, and tags")'),
-      projectPath: z.string().optional().describe('Absolute path to project root (to analyze existing schema)'),
+      projectPath: z.string().optional().describe('Absolute path to project root (to read the existing db/models/)'),
     },
     async ({ description, projectPath }) => {
       return {
@@ -19,81 +19,67 @@ export function registerDesignSchemaPrompt(server: McpServer): void {
               text: [
                 `Design a database schema for: ${description}`,
                 '',
+                'IMPORTANT (0.4.0): you declare the schema, you do NOT hand-write it. Tables are',
+                '`defineModel` in `db/models/`; authorization is `can()` abilities on the Model that',
+                'COMPILE to RLS + grants; the handler config is DERIVED from the Models. Never hand-write',
+                '`db/schema.ts`, a SQL migration, `CREATE POLICY`, or `GRANT` — those are generated.',
+                '',
                 '## Instructions',
                 '',
-                '1. Read everystack://schema-patterns for Drizzle schema conventions.',
-                '2. Read everystack://security for RLS policy patterns.',
-                '3. Read everystack://handler-options for handler configuration.',
-                projectPath ? `4. Run schema_analyze with projectPath="${projectPath}" to understand the existing schema.` : '',
+                '1. Read everystack://schema-patterns for how to declare TABLES (defineModel, field, can, relations).',
+                '2. Read everystack://derived-objects IF the model needs views, materialized views, functions, or triggers.',
+                '3. Read everystack://security for the authorization model (how can() abilities become RLS + grants).',
+                '4. Read everystack://database-operations for how the declaration reaches a database (db:sync on dev).',
+                projectPath ? `5. Read the existing \`db/models/\` under "${projectPath}" to match its conventions before adding to it.` : '',
                 '',
                 '## Deliverables',
                 '',
                 'Generate ALL of the following:',
                 '',
-                '### 1. Drizzle Schema (db/schema.ts)',
-                '',
-                'Follow these conventions:',
-                '- UUID primary keys: `uuid(\'id\').primaryKey().defaultRandom()`',
-                '- Timestamps: `timestamp(\'created_at\', { withTimezone: true }).defaultNow().notNull()`',
-                '- Soft delete columns: `deletedAt` + `deletedBy` on user-facing tables',
-                '- Foreign keys with `.references(() => table.column)`',
-                '- Export all tables as named exports',
-                '- Add Drizzle `relations()` for SSR query building and API embedding',
-                '',
-                '### 2. SQL Migration with RLS',
-                '',
-                'Generate a custom SQL migration that includes:',
+                '### 1. Models (db/models/<table>.ts — one file per table)',
                 '',
-                '```sql',
-                '-- For each table:',
-                'ALTER TABLE table_name ENABLE ROW LEVEL SECURITY;',
+                'Declare each table with `defineModel`, following these conventions:',
+                '- UUID primary keys: `id: field.uuid().primaryKey().defaultRandom()`',
+                '- Timestamps: `createdAt: field.timestamptz().defaultNow().notNull()`',
+                '- Soft delete: a `deletedAt: field.timestamptz()` field opts the table into soft-delete',
+                '- Foreign keys via relations: `field.uuid().references(() => Author)` / `belongsTo`/`hasMany`',
+                '- Sensitive columns: `.private()` (hidden from the API); write-guarded: `.readonly()`',
+                '- Named exports (PascalCase model var, e.g. `export const Post = defineModel(\'posts\', …)`)',
                 '',
-                '-- Grant minimum required access per role:',
-                'GRANT SELECT ON table_name TO anon;',
-                'GRANT SELECT, INSERT, UPDATE, DELETE ON table_name TO authenticated;',
-                'GRANT ALL ON table_name TO admin;',
+                '### 2. Authorization — `can()` abilities ON each Model (NOT hand-written RLS)',
                 '',
-                '-- Policies per access pattern:',
-                '-- Public read:',
-                'CREATE POLICY "anon_select" ON table_name FOR SELECT TO anon USING (deleted_at IS NULL);',
+                'Declare the access pattern as abilities; the compiler emits the RLS policies and GRANTs.',
+                'Every table MUST make its read decision or `db:check` fails it:',
                 '',
-                '-- Own rows only:',
-                'CREATE POLICY "own_rows" ON table_name FOR ALL TO authenticated',
-                '  USING (user_id = current_setting(\'request.jwt.claims\', true)::json->>\'sub\');',
-                '',
-                '-- Admin full access:',
-                'CREATE POLICY "admin_all" ON table_name FOR ALL TO admin USING (true);',
+                '```ts',
+                'abilities: [',
+                "  can('read'),                              // public read (anon + authenticated)",
+                "  can('read', { owner: 'authorId' }),       // rows the caller owns",
+                "  can('manage', { owner: 'authorId' }),     // owner can write their own rows",
+                "  can('read', { role: 'admin' }),           // a specific role only",
+                '],',
                 '```',
                 '',
-                'Adapt the policies to the specific access patterns for each table.',
+                'A private/operational table declares `private: true` (generated, but not a generic-API',
+                'resource). Row ownership, soft-delete, hidden/protected columns, and relations are all',
+                'DERIVED from the Model into the handler config — do not write a createHandler options blob',
+                'by hand.',
                 '',
-                '### 3. Handler Configuration',
+                '### 3. Derived objects (only if the model needs compute)',
                 '',
-                'Generate the createHandler() config snippet:',
-                '- `exposedTables`: only tables that should be API-accessible',
-                '- `relations`: for embedding related data in API queries',
-                '- `rowOwnership`: for user-scoped tables',
-                '- `softDelete`: for tables with deletedAt columns',
-                '- `protectedFields`: fields users cannot set directly (role, deletedAt)',
-                '- `hiddenColumns`: sensitive columns not returned in API responses',
+                'If the design needs a view, materialized view, function, or trigger, declare it as a',
+                'descriptor in `db/models/derived.ts` per everystack://derived-objects — NOT as a SQL',
+                'migration. Wire them on `defineModule({ models, derived })`.',
                 '',
-                '### 4. Testing Checklist',
+                '### 4. Testing + apply checklist',
                 '',
-                'Generate a testing checklist:',
-                '- [ ] Anonymous users can read public data',
-                '- [ ] Anonymous users cannot write any data',
-                '- [ ] Authenticated users can only read/write their own data',
+                '- [ ] Every table declares a read ability or `private: true` (db:check gate)',
+                '- [ ] Anonymous users can read only what `can(\'read\')` (no owner/role) allows',
+                '- [ ] Owner-scoped rows are invisible and unwritable across users (IDOR)',
                 '- [ ] Soft-deleted rows are hidden from normal queries',
-                '- [ ] Admin users can access all data',
-                '- [ ] Foreign key constraints prevent orphaned rows',
-                '- [ ] RLS policies work with pgSettings claim injection',
-                '',
-                'Test each RLS policy with:',
-                '```sql',
-                'SET LOCAL ROLE authenticated;',
-                "SELECT set_config('request.jwt.claims', '{\"sub\": \"user-uuid\", \"role\": \"authenticated\"}', true);",
-                'SELECT * FROM table_name; -- should only return own rows',
-                '```',
+                '- [ ] `everystack db:sync --database-url "$DATABASE_URL"` applies cleanly on a dev DB',
+                '- [ ] `everystack db:check` passes (declared state composes; generated artifacts match)',
+                '- [ ] `everystack db:authz:test --stage dev` proves the compiled RLS enforces the abilities',
               ].filter(Boolean).join('\n'),
             },
           },

package/src/prompts/new-app.ts

@@ -106,7 +106,7 @@ export function registerNewAppPrompt(server: McpServer): void {
                 '```',
                 `${effectiveName}/`,
                 '├── app/              # Expo Router pages',
-                effectiveTier !== 'V1' ? '├── db/               # Schema, migrations, seed' : '',
+                effectiveTier !== 'V1' ? '├── db/               # models/ (declared schema), backfills/, seed' : '',
                 '├── server/           # Lambda handlers',
                 effectiveTier !== 'V1' ? '│   └── api.ts        # PostgREST handler' : '',
                 effectiveTier === 'V3' ? '│   ├── worker.ts     # SQS worker handler' : '',
@@ -117,27 +117,29 @@ export function registerNewAppPrompt(server: McpServer): void {
                 '```',
                 '',
                 effectiveTier !== 'V1' ? [
-                  '### 3. Database Schema',
-                  `Create db/schema.ts with tables for the ${description}.`,
+                  '### 3. Database Schema — declared Models (0.4.0)',
+                  `Declare tables for the ${description} as \`defineModel\` in \`db/models/\` (one file per table).`,
+                  'Do NOT hand-write db/schema.ts or run drizzle-kit — the schema is DECLARED, then compiled.',
                   'Follow the patterns from everystack://schema-patterns:',
-                  '- UUID primary keys with defaultRandom()',
-                  '- created_at timestamps on all tables',
-                  '- Foreign key references with proper cascading',
-                  '- Relations for both SSR and API query embedding',
+                  '- `field.uuid().primaryKey().defaultRandom()`; `field.timestamptz().defaultNow().notNull()`',
+                  '- Foreign keys via `.references(() => Model)` / relations for SSR + API embedding',
+                  '- Authorization as `can()` abilities ON the Model (compiles to RLS + grants — never hand-written)',
+                  '- Views/matviews/functions/triggers: descriptors in db/models/derived.ts (everystack://derived-objects)',
+                  '- Compose in db/models/index.ts: `defineModule({ models, derived })`',
                   '',
-                  '### 4. Migrations',
-                  '- Generate: `npx drizzle-kit generate`',
-                  '- Add RLS policies in a custom SQL migration',
-                  '- Reference the RLS templates from everystack://security',
+                  '### 4. Apply the schema',
+                  '- Dev database: `everystack db:sync --database-url "$DATABASE_URL"` (state + authz + compute, one verb)',
+                  '- CI gate: `everystack db:check`',
+                  '- Protected stages: `db:plan` → `db:apply` (everystack://database-operations)',
+                  '- No hand-written migration, no CREATE POLICY, no GRANT — all generated from the Models',
                   '',
                   '### 5. Handler Configuration',
                   'Create server/api.ts using createPluginLambdaHandler or createLambdaHandler.',
-                  'Include:',
+                  'The per-table access config (exposedTables, rowOwnership, softDelete, hidden/protected columns,',
+                  'relations) is DERIVED from your Models via `deriveHandlerConfig(models)` — do not hand-maintain it.',
+                  'Set only the app-level options by hand:',
                   '- auth.verifyToken for JWT verification',
                   '- pgSettings for RLS context injection',
-                  '- exposedTables to limit API surface',
-                  '- rowOwnership for user-scoped mutation control',
-                  '- softDelete for reversible deletes',
                   '',
                   '### 6. Auth Setup',
                   'Read everystack://auth for the full auth flow.',
@@ -148,7 +150,7 @@ export function registerNewAppPrompt(server: McpServer): void {
                 ].join('\n') : '',
                 '## Validation',
                 '',
-                'After scaffolding, run the project_validate tool to check for common mistakes.',
+                'After scaffolding, run `check_environment` to confirm prerequisites, and `everystack db:check` to confirm the declared schema composes.',
                 '',
                 '## Run Locally',
                 '',
@@ -200,10 +202,10 @@ export function registerNewAppPrompt(server: McpServer): void {
                 effectiveTier === 'V3' ? '- S3 bucket for file uploads' : '',
                 '',
                 '### Deploy',
-                'Read everystack://deployment for the full walkthrough.',
+                'Read everystack://deployment and everystack://database-operations for the full walkthrough.',
                 '1. `pnpm sst deploy --stage dev`',
-                effectiveTier !== 'V1' ? '2. `everystack db:migrate`' : '',
-                effectiveTier !== 'V1' ? '3. `everystack db:seed` (dev only)' : '',
+                effectiveTier !== 'V1' ? '2. `everystack db:plan --stage dev --out dev.plan.json` → review → `everystack db:apply --plan dev.plan.json --stage dev`' : '',
+                effectiveTier !== 'V1' ? '3. `everystack db:seed --stage dev` (dev only)' : '',
               ].filter(Boolean).join('\n'),
             },
           },

package/src/prompts/secure.ts

@@ -29,8 +29,8 @@ export function registerSecurePrompt(server: McpServer): void {
                 '',
                 '1. Read everystack://security for the complete security model.',
                 '2. Read everystack://auth for JWT authentication details.',
-                projectPath ? `3. Run project_validate with projectPath="${projectPath}" to find existing security gaps.` : '',
-                projectPath ? `4. Run schema_analyze with projectPath="${projectPath}" to check schema security.` : '',
+                projectPath ? `3. Read the project's \`db/models/\` under "${projectPath}" — the \`can()\` abilities ARE the authorization; confirm every table declares a read decision.` : '',
+                projectPath ? '4. Run the real security tooling: `everystack db:doctor` (least-privilege + RLS posture), `everystack db:authz:test --stage dev` (the compiled RLS enforces the abilities), and `everystack security:audit`.' : '',
                 '',
                 requested.includes('aws') ? [
                   '## AWS IAM Profiles',
@@ -215,7 +215,7 @@ export function registerSecurePrompt(server: McpServer): void {
                 '',
                 'After setup, verify security:',
                 '',
-                '1. Run project_validate to check for gaps',
+                '1. Run `everystack db:doctor` and `everystack db:authz:test --stage dev` to prove the RLS enforces the declared abilities',
                 '2. Test unauthenticated access returns 401',
                 '3. Test cross-user data isolation with RLS',
                 '4. Verify JWT claims propagate through pgSettings',

package/src/resources/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/src/resources/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/src/resources/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.