@everystack/mcp 0.4.0 → 0.4.1

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

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.

package/dist/index.cjs

@@ -21652,6 +21652,12 @@ var RESOURCES = [
     description: "SST deployment: sst.config.ts setup, secrets, stages (dev/production), CloudFront, Lambda configuration, VPC, RDS Aurora Serverless, resource linking.",
     filename: "deployment.md"
   },
+  {
+    uri: "everystack://expo-server-deploy",
+    name: "Deploying an Expo Router Server App",
+    description: 'How web.output:"server" maps to AWS: the two-deployable model (sst deploy vs everystack update), where +api.ts routes run (the SSR fallback serves the published bundle), the one-plugin-list/two-venues pattern (local catch-all route + deployed Lambda entrypoint), the ops entrypoint for db:migrate, custom domains on the Router, and the local-vs-deployed database URL (sslmode). Read this when deploying any Expo Router app with SSR or +api.ts routes.',
+    filename: "expo-server-deploy.md"
+  },
   {
     uri: "everystack://admin",
     name: "Admin Dashboard",
@@ -23717,7 +23723,7 @@ async function runGovernanceCli(argv) {
 }
 
 // src/index.ts
-var version2 = (true ? "0.4.0" : null) ?? "0.3.0-dev";
+var version2 = (true ? "0.4.1" : null) ?? "0.3.0-dev";
 var INSTRUCTIONS = [
   "You govern how any agent builds everystack \u2014 a self-hosted application stack for Expo apps on AWS.",
   "Your job is not only to advise but to keep the build on-script: the architecture the maintainer",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/mcp",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Governance layer that governs how any agent builds everystack — grounding, cheat gates, and Model-aware tooling over MCP",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",
@@ -40,8 +40,8 @@
     "tsx": "4.21.0",
     "typescript": "5.9.3",
     "zod": "3.25.67",
-    "@everystack/cli": "0.4.2",
-    "@everystack/model": "0.4.1"
+    "@everystack/cli": "0.4.19",
+    "@everystack/model": "0.4.4"
   },
   "scripts": {
     "test": "jest",

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

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

package/src/resources/index.ts

@@ -140,6 +140,13 @@ const RESOURCES: ResourceDef[] = [
       'SST deployment: sst.config.ts setup, secrets, stages (dev/production), CloudFront, Lambda configuration, VPC, RDS Aurora Serverless, resource linking.',
     filename: 'deployment.md',
   },
+  {
+    uri: 'everystack://expo-server-deploy',
+    name: 'Deploying an Expo Router Server App',
+    description:
+      'How web.output:"server" maps to AWS: the two-deployable model (sst deploy vs everystack update), where +api.ts routes run (the SSR fallback serves the published bundle), the one-plugin-list/two-venues pattern (local catch-all route + deployed Lambda entrypoint), the ops entrypoint for db:migrate, custom domains on the Router, and the local-vs-deployed database URL (sslmode). Read this when deploying any Expo Router app with SSR or +api.ts routes.',
+    filename: 'expo-server-deploy.md',
+  },
   {
     uri: 'everystack://admin',
     name: 'Admin Dashboard',