@everystack/mcp 0.3.3 → 0.4.1

package/dist/derived-objects.md

@@ -0,0 +1,225 @@
+# Derived Objects: functions, views, materialized views, triggers, sequences
+
+> Derived objects don't migrate — they **deploy**. Base tables hold irreplaceable data
+> and change through generated migrations. Functions, views, and materialized views are
+> **compute**: declared source whose results are rebuildable from the tables at any time.
+> You edit their descriptors, and `db:reconcile` makes the database match — no migration
+> file, no journal entry, no numbered anything. Git is the history.
+
+Read this when you need to add or change a view, materialized view, function, trigger, or
+standalone sequence. For tables (`defineModel`) and the operational verbs
+(`db:sync`/`db:plan`/`db:apply`), see `everystack://schema-patterns` and
+`everystack://database-operations`.
+
+## Two layers, two lifecycles
+
+A schema is two different things, and conflating them is the mistake:
+
+| Layer | Objects | Changes via | History |
+|-------|---------|-------------|---------|
+| **State** | tables, constraints, authz, sequences | Models → `db:generate` → migration | migration + `db:pull` |
+| **Compute** | functions, views, matviews, triggers | descriptors → `db:reconcile` | git |
+
+Versioning compute through migrations is a category error — the same as writing a
+migration to edit a Lambda handler. A one-line fix to a materialized view should be a
+one-line git diff, not a restatement of the whole view inside a numbered file. (In one
+real analytics app, 34 of 43 migrations were pure derived-layer churn, including a 701 KB
+migration that fixed a one-line regex.) Descriptors end that.
+
+## The declared home
+
+The whole database — both layers — lives in `db/models/`, in one format:
+
+```
+db/
+├── models/          # the declared database: defineModel tables + derived descriptors
+│   ├── post.ts
+│   ├── derived.ts   # defineView / defineMaterializedView / defineFunction / defineSql
+│   └── index.ts     # defineModule({ models, sequences, derived })
+└── schema.generated.ts   # generated artifact (never edited; db:check refuses drift)
+```
+
+**`db/sql/` is retired.** Raw-SQL derived objects moved into descriptors, and every CLI
+verb hard-fails on a `db/sql/` directory that still carries `.sql` files. If you are
+adopting an app that still has one, see "Adopting an existing database" below.
+
+The boundary rule, uniform with models: **structure is declared** (identity,
+dependencies, authz, security posture, indexes, signatures, trigger events);
+**expressions stay `sql``** (the SELECT, the function body, a WHEN predicate). No query
+DSL, no string mini-grammars in declared properties.
+
+```ts
+import { defineView, defineMaterializedView, defineFunction, defineSql, defineModule,
+         trigger, arg, setof, field, can, index, sql } from '@everystack/model';
+
+// A VIEW — securityInvoker is the one forced decision.
+export const activeUsers = defineView('active_users', {
+  securityInvoker: true,            // REQUIRED, no default:
+                                    // true  = readers' own RLS/grants apply through the view
+                                    // false = definer semantics (the sealed-slice pattern —
+                                    //         a view grant WITHOUT a table grant; the body must seal)
+  abilities: [can('read')],         // grants are AUTHORED, never inherited
+  dependsOn: [users],               // declared, then VERIFIED against the live edges (drift-checked)
+  fields: { id: field.uuid().notNull(), name: field.text().notNull() },  // OPTIONAL: typed SSR
+                                    // reads — emits a pgView().existing() into schema.generated.ts;
+                                    // never touches the DDL or the content hash
+  as: sql`SELECT id, name FROM users WHERE deleted_at IS NULL`,
+});
+
+// A MATERIALIZED VIEW — grants-only authz; refresh/populate declare the HOW.
+export const leaderboard = defineMaterializedView('leaderboard', {
+  abilities: [can('read')],
+  dependsOn: [scores, activeUsers],
+  indexes: [index(['user_id']).unique(), index('tags').using('gin')],
+  refresh: 'concurrently',          // compile-gated: REQUIRES a unique, non-partial index
+  populate: 'deferred',             // create WITH NO DATA, refresh outside the creation lock
+  as: sql`SELECT user_id, sum(points) AS points FROM scores GROUP BY user_id`,
+});
+
+// A FUNCTION — signature structured, body raw.
+export const searchPosts = defineFunction('search_posts', {
+  args: [arg('query', 'text')],
+  returns: setof(posts),            // a descriptor ref — a typo is a TS error, the dep comes free
+  language: 'sql',
+  volatility: 'stable',             // default 'volatile'; 'immutable' enables expression indexes
+  abilities: [can('execute', { role: 'authenticated' })],  // role REQUIRED; PUBLIC is always revoked
+  body: sql`SELECT * FROM posts WHERE ts @@ websearch_to_tsquery(query)`,
+});
+
+// A SECURITY DEFINER function MUST pin its search_path (the classic landmine):
+export const promote = defineFunction('promote_user', {
+  args: [arg('uid', 'uuid')], returns: 'void', language: 'plpgsql',
+  security: 'definer', searchPath: ['pg_catalog', 'public'],   // required with definer
+  abilities: [can('execute', { role: 'admin' })],
+  body: sql`BEGIN UPDATE users SET role = 'admin' WHERE id = uid; END`,
+});
+
+// A TRIGGER FUNCTION is a standalone function returning 'trigger'…
+export const touchUpdatedAt = defineFunction('touch_updated_at', {
+  returns: 'trigger', language: 'plpgsql',
+  body: sql`BEGIN NEW.updated_at = now(); RETURN NEW; END`,
+});
+
+// …and the TRIGGER is declared ON THE MODEL it fires on (owner consent, visible where the
+// table lives) — see defineModel below.
+
+export const appModule = defineModule({
+  models: [posts, users],
+  derived: [activeUsers, leaderboard, searchPosts, promote, touchUpdatedAt],
+  // sequences: [invoiceNo],   // standalone sequences are STATE — see below
+});
+```
+
+Triggers ride the model:
+
+```ts
+export const Post = defineModel('posts', {
+  fields: { id: field.uuid().primaryKey(), updatedAt: field.timestamptz() },
+  abilities: [can('read')],
+  triggers: [trigger('touch', {
+    timing: 'before', events: ['update'], forEach: 'row',
+    execute: touchUpdatedAt,        // the trigger function MUST be in the module's derived set
+  })],
+});
+```
+
+## The rules that make it safe (all enforced)
+
+- **`securityInvoker` is a required decision** on every view — no default. Pick `true`
+  (readers' own RLS applies) or `false` (definer semantics, the sealed slice).
+- **Grants are authored, never inherited.** `can('read')` on a relation → `anon` +
+  `authenticated`; `can('read', { role })` narrows. A granted view whose readers can't
+  reach its underlying tables is a **compile error** — the reachability gate.
+- **SECURITY DEFINER without a pinned `searchPath` is rejected** at define time.
+- **`can('execute')` needs a role** — bare execute has no safe audience; PUBLIC is always
+  revoked by the compiler.
+- **A missing import is caught loudly.** An `undefined` in `dependsOn`/`derived`/a
+  trigger's `execute` (a renamed or missing named import) is rejected at define time,
+  naming the descriptor and the index — never a silent drop.
+- **`dependsOn` is declared, then verified.** The reachability gate walks it at compile
+  time; the live catalog's actual edges check it at plan time. A view that reads a table
+  it never declared (or declares one it never reads) is a `db:check` failure.
+- **REFRESH CONCURRENTLY requires a unique, non-partial index** — compile-gated.
+- **Content hashing is comment- and whitespace-insensitive** — reformatting a body is a
+  no-op; only a real change reconciles.
+
+The escape hatch `defineSql` handles what the structured vocabulary can't say yet
+(aggregates, operators, event triggers) — still declared, hashed, dependency-ordered. It
+refuses a `CREATE [MATERIALIZED] VIEW` so accidental relations land in the read model
+where the gates can see them; its SQL is otherwise trusted as authored.
+
+## Sequences are STATE, not compute
+
+A standalone sequence (one not owned by a serial column) holds a counter value, so it
+migrates with the base schema — declare it with `defineSequence` and pass it on
+`defineModule({ sequences })`. It is fingerprinted with the tables and created before them.
+This is the one derived-looking object that is state, not compute.
+
+```ts
+export const invoiceNo = defineSequence('invoice_no', { start: 1000 });
+```
+
+## Deploying: `db:reconcile`
+
+```bash
+everystack db:reconcile                          # plan (read-only; works via --stage or --database-url)
+everystack db:reconcile --check                  # CI gate: exit 1 when anything differs
+everystack db:reconcile --apply --database-url … # execute (direct connection required)
+```
+
+Planning works over the read-only ops Lambda (`--stage`); **`--apply` needs a direct
+connection** — the deployed query path is read-only by design. On a dev database, prefer
+`db:sync` (it does state + compute in one verb); reach for `db:reconcile --apply` when you
+want compute only.
+
+A plan shows the rebuild cost before you say yes — dependent cascades, matview sizes, row
+counts:
+
+```
+= 51 up to date
+~ replace public.score (source changed)
+↻ refresh public.season_scores (depends on replaced function public.score; 1.2 GB, ~4M rows)
++ create public.weekly_top (new in source)
+≠ regrant public.leaderboard — live grants differ (REVOKE SELECT ON leaderboard FROM intern)
+estimated rebuild: 1.2 GB across 1 matview(s)
+```
+
+`--apply` sends all DDL as **one transaction** (a failed create rolls back the drops
+before it), records provenance and a `schema_log` memoir (the full DDL, when, by whom,
+from which git commit), and rebuilds dependents automatically in dependency order.
+
+## Semantics worth knowing
+
+- **Drift is never overwritten silently.** A hand-edited managed object (someone ran
+  `CREATE OR REPLACE` against the DB) makes the plan report drift and `--apply` refuse.
+  Fix the source to match, or rebuild from source with `--overwrite-drift`.
+- **Grant drift converges without ceremony** — a hand-run GRANT/REVOKE surfaces as an
+  idempotent `regrant` back to the declared abilities. Declared authz is authoritative.
+- **Changing a function REFRESHes the matviews that call it** — their rows are stale the
+  moment the function changes, and the reconciler knows it.
+- **Unmanaged objects are never touched** — live derived objects with no source and no
+  provenance are listed and left alone.
+
+## Adopting an existing database (baseline / rebaseline)
+
+- **First contact wants `--baseline`.** Against a database that already has your derived
+  layer (built by old migrations), the reconciler refuses to guess whether live matches
+  source. `everystack db:pull` renders the live layer as descriptors (bodies from the
+  catalog's canonical deparse, grants as abilities, `dependsOn` from live edges). The path:
+  **pull → review → commit → `db:reconcile --apply --baseline` → a silent check.**
+  Use `db:pull --derived-out db/models/derived.ts` to write the derived layer straight
+  into its own file when you already have a hand-maintained models barrel.
+- **A `db/sql`-era migration wants `--rebaseline`.** When provenance exists but the source
+  was re-rendered (descriptors render canonical SQL, so the source hash differs even for
+  identical SQL), `--rebaseline` re-records the new source hash for every object whose live
+  definition still matches what the reconciler last applied — no drop, no create, no
+  matview repopulation. The live side is VERIFIED; the source side is TRUSTED. Migrate
+  first (verbatim), edit after. `--baseline` and `--rebaseline` compose in one run.
+
+## Current limitations
+
+- **Function identity is by name** — overloads are rejected at define time. Rename one.
+- **Function signature changes** (return/arg types) can't `CREATE OR REPLACE` — drop the
+  old function in a reviewed step, or rename.
+- Postgres can't see function→function dependencies inside bodies — `dependsOn` is your
+  declaration there.

package/dist/expo-server-deploy.md

@@ -0,0 +1,208 @@
+# Deploying an Expo Router Server App
+
+> How `web.output: "server"` maps to AWS: what deploys where, where your `+api.ts` routes run, and where the everystack handler sits among them.
+
+## When to Use
+
+Read this when your app.json has `web.output: "server"` (SSR pages, `+api.ts` API routes) and you are deploying to AWS. This is the deploy chapter for the most common Expo Router app shape — if your app is fully static (`web.output: "static"`), everystack://deployment alone is enough.
+
+## The Two-Deployable Model
+
+The single most important fact: **the Expo server export is NOT the Lambda handler.** There are two deployables with two verbs:
+
+| Deployable | Contains | Verb | Frequency |
+|---|---|---|---|
+| Infrastructure + entrypoints | VPC, RDS, buckets, Router, the Lambda entry files in `server/` | `sst deploy` | Rarely (infra changes) |
+| App code | Your entire Expo export: SSR pages, ALL `+api.ts` routes, client bundles | `everystack update --channel <name>` | Every ship (same verb as OTA) |
+
+`everystack update` runs the expo export and publishes it as a compressed archive to the Updates bucket. At runtime, the Lambda's SSR fallback downloads that archive to `/tmp` (cached across warm invocations) and serves it with `expo-server` — Expo's own server runtime. Your app code never gets bundled into the Lambda; it ships like an OTA update.
+
+## Request Flow
+
+```
+CloudFront Router
+  └─ Api Lambda (server/api.ts — createPluginLambdaHandler)
+       ├─ plugin routes claim their paths first (e.g. /api → everystack handler)
+       └─ everything else → ssrPlugin fallback → expo-server runs YOUR export:
+            ├─ SSR pages (with loader())
+            └─ your +api.ts routes (mcp+api.ts, app/games/[id]+api.ts, ...)
+```
+
+**Your `+api.ts` routes ship and serve as-is.** They ride the published bundle and expo-server dispatches to them inside the Lambda. Nothing has to be collapsed into the everystack handler.
+
+## The Lambda Entrypoint
+
+```typescript
+// server/api.ts — the Function handler for `sst deploy`
+import { createPluginLambdaHandler, ssrPlugin } from '@everystack/server/plugin';
+import { createAppContext, appPlugins } from './context';
+
+export const handler = createPluginLambdaHandler({
+  context: () => createAppContext(),
+  plugins: appPlugins,
+  fallback: ssrPlugin(),   // serves the published Expo export: SSR + your +api.ts routes
+});
+```
+
+## One Plugin List, Two Venues
+
+Define your plugins once; mount them in both places. Locally, Expo Router serves them through a catch-all route. Deployed, the Lambda mounts the same list and claims those paths BEFORE the fallback — so the deployed `/api` runs with SST Resource linking, never the bundle's copy.
+
+```typescript
+// server/context.ts — shared by local dev and every Lambda
+import { createDb } from '@everystack/server/db';
+import { apiPlugin } from './plugins/api';       // your everystack createHandler, as a plugin
+import { authPlugin } from '@everystack/auth/plugin';
+import { schema } from '../db';
+
+export async function createAppContext() {
+  const { db } = createDb(schema);   // Resource-linked on Lambda, DATABASE_URL locally
+  return { db, schema, environment: process.env.ENVIRONMENT ?? 'dev', /* verifyToken, ... */ };
+}
+
+export const appPlugins = [authPlugin, apiPlugin];
+```
+
+```typescript
+// server/plugins/api.ts — the everystack handler as ONE plugin among your routes
+import { createHandler } from '@everystack/api';
+
+export async function apiPlugin(ctx) {
+  const handler = createHandler(ctx.db, ctx.schema, { basePath: '/api', /* options */ });
+  return { routes: [{ path: '/api', handler }] };
+}
+```
+
+```typescript
+// app/api/[...path]+api.ts — LOCAL DEV venue (Expo Router serves this; the
+// deployed Lambda claims /api first, so this copy never runs in production)
+import { createPluginHandler } from '@everystack/server/plugin';
+import { createAppContext, appPlugins } from '../../server/context';
+
+const handler = createPluginHandler({ context: createAppContext, plugins: appPlugins });
+export const GET = handler; export const POST = handler;
+export const PATCH = handler; export const DELETE = handler;
+```
+
+Your OTHER `+api.ts` routes (`app/mcp+api.ts`, `app/games/[id]+api.ts`, ...) need no counterpart: local dev serves them directly, deployed they serve through the fallback.
+
+## The Ops Entrypoint (db:migrate, db:seed, console)
+
+`everystack db:migrate` invokes a dedicated, privileged Lambda over IAM — it has no public URL and holds the operator credential so the API Lambda never does.
+
+```typescript
+// server/ops.ts
+import { createPluginLambdaHandler, dbPlugin } from '@everystack/server/plugin';
+import { createAppContext, appPlugins } from './context';
+
+export const handler = createPluginLambdaHandler({
+  http: false,   // actions-only: rejects HTTP, answers IAM invokes
+  context: () => createAppContext({ admin: true }),
+  plugins: [
+    ...appPlugins,
+    dbPlugin({
+      migrationsFolder: 'drizzle',
+      seed: async (db, schema) => (await import('../db/seed.js')).runSeed(db, schema),
+      //    ^ lazy import — a top-level import would run at Lambda INIT and crash the boot
+    }),
+  ],
+});
+```
+
+## Minimal sst.config.ts
+
+The complete infrastructure for this app shape (V2: server app + PostgreSQL). Copy, rename, deploy.
+
+```typescript
+/// <reference path="./.sst/platform/config.d.ts" />
+export default $config({
+  app(input) {
+    return {
+      name: 'my-app',
+      removal: input?.stage === 'production' ? 'retain' : 'remove',
+      home: 'aws',
+    };
+  },
+  async run() {
+    const vpc = new sst.aws.Vpc('Vpc');
+    const database = new sst.aws.Postgres('Database', {
+      vpc,
+      // Local dev: `sst dev` uses this instead of RDS
+      dev: { host: 'localhost', port: 5432, username: 'postgres', password: 'postgres', database: 'my_app_dev' },
+    });
+
+    const updates = new sst.aws.Bucket('Updates');            // published Expo exports (server bundles)
+    const clientBundles = new sst.aws.Bucket('ClientBundles', { access: 'cloudfront' });
+
+    const jwtSecret = new sst.Secret('JwtSecret');
+    // Least-privilege API credential — written by `everystack db:provision`.
+    const databaseUrl = new sst.Secret('DATABASE_URL');
+
+    const router = new sst.aws.Router('Router', {
+      // Custom domain: Route 53 is the default DNS adapter. With your zone
+      // delegated to Route 53, this one line provisions the ACM certificate
+      // and DNS records automatically.
+      domain: $app.stage === 'production'
+        ? 'my-app.com'
+        : `${$app.stage}.my-app.com`,
+    });
+
+    const api = new sst.aws.Function('Api', {
+      handler: 'server/api.handler',
+      runtime: 'nodejs20.x',
+      timeout: '30 seconds',
+      vpc,
+      link: [databaseUrl, updates, clientBundles, jwtSecret],
+      url: { router: { instance: router, path: '/' } },
+      environment: { ENVIRONMENT: $app.stage, SITE_URL: router.url },
+    });
+
+    const ops = new sst.aws.Function('Ops', {
+      handler: 'server/ops.handler',
+      runtime: 'nodejs20.x',
+      timeout: '120 seconds',
+      vpc,
+      link: [database, databaseUrl, updates, clientBundles, jwtSecret],
+      copyFiles: [{ from: 'drizzle', to: 'drizzle' }],   // migrations must ship with the ops bundle
+    });
+
+    // The CLI discovers resources through these outputs — all five are required.
+    return {
+      routerUrl: router.url,
+      apiFunctionName: api.name,
+      opsFunctionName: ops.name,
+      updatesBucket: updates.name,
+      clientBundlesBucket: clientBundles.name,
+    };
+  },
+});
+```
+
+## Local vs Deployed Database Connection
+
+`createDb()` from `@everystack/server/db` serves both venues with one code path (requires `@everystack/server` >= 0.4.4):
+
+- **Deployed:** the linked `DATABASE_URL` secret resolves via SST Resource; TLS defaults to `require` (RDS).
+- **Local:** set `DATABASE_URL=postgres://user@localhost:5432/my_app_dev?sslmode=disable`. An explicit `sslmode` in the URL wins; the handler code does not change.
+
+Do not hand-build a `postgres()` client from env vars to escape TLS — the URL is the contract.
+
+## Deploy Loop
+
+```bash
+sst deploy --stage dev                       # infrastructure + entrypoints (rare)
+everystack db:provision --stage dev          # mint the least-privilege API credential (once per stage)
+everystack update --channel dev              # export + publish the app code (every ship)
+everystack db:migrate --stage dev            # run migrations via the ops Lambda
+everystack db:seed --stage dev               # dev only
+```
+
+Subsequent app-code ships are `everystack update` alone — no `sst deploy`, no Lambda redeploy.
+
+## Gotchas
+
+- **Nothing serves until the first `everystack update`** — the fallback has no bundle to download yet, so `/` returns 404 while `/api` (plugin-claimed) already works.
+- **A path claimed by a plugin never reaches your bundle's route.** If you mount the everystack handler at `/api`, a bundle route at `app/api/foo+api.ts` is shadowed in production (it still serves in local dev unless the catch-all shadows it there too — keep the surfaces aligned).
+- **Lazy-load your seed** (shown above). A top-level `import { runSeed }` in an entrypoint runs at Lambda INIT, tries to reach the database before configuration, and kills the boot.
+- **`copyFiles` the migrations folder** into the ops function, or `db:migrate` fails with ENOENT.
+- **`+api.ts` routes run with the bundle's environment**, not per-route SST links. Resource-linked work (secrets, buckets) belongs in plugins on the Lambda side; keep bundle routes to app logic over the request.