@everystack/mcp 0.2.0

package/src/resources/client-api.md

@@ -0,0 +1,145 @@
+# Client API
+
+> Typed query builder for everystack PostgREST APIs. Import from `@everystack/api/client`.
+
+## When to Use
+Read this when building client-side data fetching in React Native, Expo, or web apps.
+
+## Setup
+
+```typescript
+import { createClient } from '@everystack/api/client';
+
+const api = createClient({
+  baseUrl: '/api',
+  getToken: () => localStorage.getItem('everystack-token'),
+  onTokenExpired: async () => {
+    const res = await fetch('/api/auth/refresh', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ refreshToken: localStorage.getItem('everystack-refresh') }),
+    });
+    const { token } = await res.json();
+    localStorage.setItem('everystack-token', token);
+    return token;
+  },
+});
+```
+
+### Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `baseUrl` | `string` | API base URL (e.g., `/api` or `https://api.example.com`) |
+| `getToken` | `() => string \| null` | Returns current JWT token |
+| `onTokenExpired` | `() => Promise<string>` | Called on 401 to refresh token. Concurrent 401s deduplicated (one refresh per batch) |
+| `headers` | `Record<string, string>` | Additional headers for every request |
+
+## Queries (GET)
+
+```typescript
+// Basic query
+const { data, error } = await api.from('posts').execute();
+
+// Filters
+const { data } = await api.from('posts')
+  .eq('status', 'published')
+  .neq('authorId', blockedUser)
+  .gt('createdAt', yesterday)
+  .order('createdAt', 'desc')
+  .limit(10)
+  .offset(20)
+  .execute();
+
+// Column selection
+const { data } = await api.from('posts').select('id,title,body').execute();
+
+// Relation embedding
+const { data } = await api.from('posts').select('*,author(name,email)').execute();
+
+// Logical groups
+const { data } = await api.from('posts')
+  .or('status.eq.draft,status.eq.pending')
+  .execute();
+
+// Exact count
+const { data, count } = await api.from('posts')
+  .eq('status', 'published')
+  .count()
+  .execute();
+```
+
+### Filter Methods
+
+| Method | Example |
+|--------|---------|
+| `.eq(col, val)` | `?col=eq.val` |
+| `.neq(col, val)` | `?col=neq.val` |
+| `.gt(col, val)` | `?col=gt.val` |
+| `.gte(col, val)` | `?col=gte.val` |
+| `.lt(col, val)` | `?col=lt.val` |
+| `.lte(col, val)` | `?col=lte.val` |
+| `.like(col, pattern)` | `?col=like.pattern` |
+| `.ilike(col, pattern)` | `?col=ilike.pattern` |
+| `.is(col, val)` | `?col=is.val` (null/not.null) |
+| `.in(col, vals)` | `?col=in.(a,b,c)` |
+| `.not(col, op, val)` | `?col=not.op.val` |
+| `.or(expr)` | `?or=(a.eq.1,b.eq.2)` |
+| `.select(cols)` | `?select=cols` |
+| `.order(col, dir)` | `?order=col.dir` |
+| `.limit(n)` | `?limit=n` |
+| `.offset(n)` | `?offset=n` |
+| `.count()` | Adds `Prefer: count=exact` |
+
+## Mutations
+
+```typescript
+// Insert
+const { data, error } = await api.from('posts')
+  .insert({ body: 'Hello world', authorId: user.sub });
+
+// Update
+const { data, error } = await api.from('posts')
+  .eq('id', postId)
+  .update({ body: 'Updated content' });
+
+// Delete
+const { data, error } = await api.from('posts')
+  .eq('id', postId)
+  .delete();
+```
+
+## RPC
+
+```typescript
+const { data, error } = await api.rpc('timeline', { limit: 20, offset: 0 });
+const { data } = await api.rpc('search', { query: 'hiking trails', limit: 10 });
+```
+
+## Response Shape
+
+All methods return `{ data, error, count? }`:
+
+```typescript
+interface ApiResponse<T> {
+  data: T | null;
+  error: { status: number; message: string; details?: string } | null;
+  count?: number;  // Only with .count()
+}
+```
+
+## Token Refresh
+
+When a request returns 401:
+1. Client calls `onTokenExpired()` to get a new token
+2. If multiple concurrent 401s fire, they all wait for the SAME refresh (deduplication)
+3. Client retries the original request with the new token
+4. If refresh fails, returns `{ data: null, error: { status: 401, ... } }`
+
+## Gotchas
+
+- `.execute()` is required to send the request. The builder is lazy.
+- `.insert()`, `.update()`, `.delete()` send immediately (no `.execute()` needed).
+- Filters on `.update()` and `.delete()` scope which rows are affected.
+- The client auto-adds `Content-Type: application/json` for mutations.
+- `baseUrl` should NOT include a trailing slash.

package/src/resources/core.md

@@ -0,0 +1,196 @@
+# everystack
+
+Self-hosted application stack for Expo apps on AWS. Start with a static site, add database/auth/jobs as you grow. Each tier builds on the previous -- you never rip out what you have, you add to it.
+
+## Tiers
+
+### V1: Static Site (no database)
+- Expo app exported to static assets, served from CloudFront
+- Lambda SSR for SEO (server-rendered HTML with OG meta, JSON-LD)
+- OTA updates via `everystack update` (instant deploys without redeploying infrastructure)
+- **Packages:** `@everystack/server`, `@everystack/cli`, `@everystack/ui`
+- **Infrastructure:** S3 + CloudFront + Lambda + S3 (updates bucket)
+
+### V2: Dynamic App (database + auth)
+- PostgreSQL via RDS Aurora Serverless
+- PostgREST-compatible REST API (filters, pagination, relations, RPC)
+- JWT auth (signup, signin, refresh, edge verification)
+- Admin dashboard (config-driven, EverystackAdapter)
+- Structured logging and analytics
+- **Adds:** `@everystack/api`, `@everystack/auth`, `@everystack/admin`, `@everystack/logging`, `@everystack/query`, `@everystack/security`
+- **Infrastructure:** V1 + RDS Aurora Serverless
+
+### V3: Full Platform (jobs + media)
+- SQS background workers with dead letter queue
+- On-demand image resizing via Sharp on Lambda
+- S3 file uploads with presigned URLs and CDN delivery
+- **Adds:** `@everystack/jobs`, `@everystack/storage`, `@everystack/images`
+- **Infrastructure:** V2 + SQS + Worker Lambda + Image Lambda + Media S3
+
+## Package Map
+
+| Package | Purpose |
+|---------|---------|
+| `@everystack/server` | Lambda handler, router, DB connection, SSR, image processing, worker, plugin system |
+| `@everystack/api` | PostgREST-compatible handler (`createHandler`) + typed client (`createClient`) |
+| `@everystack/auth` | JWT auth flows, OAuth, password hashing, edge verification, React AuthProvider |
+| `@everystack/cli` | CLI binary (`everystack`), OTA updates handler, storage adapters |
+| `@everystack/admin` | Declarative admin dashboard, EverystackAdapter, presets |
+| `@everystack/logging` | Structured logging, crash reports, analytics, S3 storage, CloudWatch trigger |
+| `@everystack/query` | React Query hooks for PostgREST APIs |
+| `@everystack/security` | Device attestation (Apple/Google), biometric auth, RS256 keys |
+| `@everystack/jobs` | SQS background workers, job dispatch, Postgres materialization |
+| `@everystack/storage` | S3 uploads, presigned URLs, MIME validation, ownership enforcement |
+| `@everystack/images` | Sharp image processing, variant generation, EXIF extraction |
+| `@everystack/events` | PostgreSQL LISTEN/NOTIFY, WebSocket fan-out, Lambda event bridge |
+| `@everystack/ui` | React Native components, charts, MDX support |
+
+## Core Insight: Two Paths, One Database
+
+The central design decision (V2+). SSR and mobile share the same PostgreSQL database but access it differently:
+
+- **Mobile app** -> HTTP -> PostgREST handler -> Drizzle -> PostgreSQL
+- **SSR loader** -> Drizzle directly -> PostgreSQL (same Lambda process, zero network overhead)
+
+Both paths use the same Drizzle schema as source of truth. One deployment unit (single Lambda), shared connection pool, no inter-service latency.
+
+## Project Structure Conventions
+
+```
+my-app/
+├── app/                    # Expo Router pages + API routes
+│   ├── api/
+│   │   └── [...path]+api.ts  # Catch-all API route (mounts handler)
+│   ├── admin/              # Admin dashboard pages
+│   └── (tabs)/             # App screens
+├── db/
+│   └── schema.ts           # Drizzle schema (your tables)
+├── drizzle/                # SQL migration files (generated by drizzle-kit)
+├── server/
+│   ├── api.ts              # Main Lambda handler (createLambdaHandler)
+│   ├── worker.ts           # Background worker handler (V3)
+│   ├── image.ts            # Image processing handler (V3)
+│   ├── rpc/                # Custom RPC functions
+│   └── plugins/            # Plugin compositions
+├── lib/
+│   ├── api.ts              # Client re-exports (createClient config)
+│   └── auth-context.tsx    # Auth context provider
+├── sst.config.ts           # Infrastructure definition
+├── app.json                # Expo config
+└── package.json
+```
+
+## Handler Quick Reference
+
+```typescript
+import { createHandler } from '@everystack/api/handler';
+
+const handler = createHandler(db, schema, {
+  basePath: '/api',                    // URL prefix to strip
+  auth: {
+    verifyToken: async (token) => payload,  // JWT verification
+    publicRoutes: ['GET'],             // Methods that skip auth
+    publicRpc: ['health'],             // RPC functions that skip auth
+    roleHierarchy: ['public', 'authenticated', 'admin'],
+  },
+  pgSettings: (user, client) => ({    // RLS context injection
+    role: user?.role === 'admin' ? 'admin' : user ? 'authenticated' : 'anon',
+    'request.jwt.claims': JSON.stringify(user || { role: 'anon' }),
+  }),
+  relations: { posts: { author: { table: 'users', from: 'authorId', to: 'id' } } },
+  rpc: { timeline: { fn: async (body, user) => {}, role: 'authenticated' } },
+  exposedTables: ['posts', 'profiles'],   // Whitelist (404 for others)
+  hiddenColumns: { users: ['passwordHash'] },  // Strip from responses
+  protectedFields: { profiles: ['role'] },      // Strip from writes
+  rowOwnership: { posts: { column: 'authorId', userField: 'sub' } },
+  hooks: { posts: { beforeCreate: async (body, user) => ({ ...body, authorId: user?.sub }) } },
+  softDelete: { column: 'deletedAt', tables: ['posts'] },
+  maxEmbedDepth: 3,
+  maxLimit: 1000,
+});
+```
+
+Returns `(request: Request) => Promise<Response>` -- Web Standard interface. Works with Expo Router, Cloudflare Workers, Deno, Bun.
+
+## Lambda Handler
+
+```typescript
+import { createLambdaHandler } from '@everystack/server';
+
+export const handler = createLambdaHandler({
+  init: async () => ({ api, auth }),        // Lazy init, returns handler map
+  routes: (h) => [                          // Route dispatch
+    { path: '/api/auth/signup', method: 'POST', exact: true, handler: h.signup },
+    { path: '/api', handler: h.api },       // Catch-all for PostgREST
+  ],
+  onAction: async (action, payload) => {    // CLI invocations via IAM
+    if (action === 'migrate') return runMigrations();
+    if (action === 'seed') return runSeed();
+  },
+});
+```
+
+## Client
+
+```typescript
+import { createClient } from '@everystack/api/client';
+
+const api = createClient({
+  baseUrl: '/api',
+  getToken: () => token,
+  onTokenExpired: async () => newToken,  // Auto-refresh with deduplication
+});
+
+// Queries
+const { data } = await api.from('posts').eq('status', 'published').order('createdAt', 'desc').limit(10).execute();
+const { data } = await api.from('posts').select('*,author(email)').execute();
+
+// Mutations
+await api.from('posts').insert({ body: 'Hello', authorId: user.sub });
+await api.from('posts').eq('id', 1).update({ body: 'Updated' });
+await api.from('posts').eq('id', 1).delete();
+
+// RPC
+const { data } = await api.rpc('timeline', { limit: 20 });
+```
+
+## CLI Commands
+
+All infrastructure commands use **AWS IAM credentials** (not shared secrets).
+
+| Command | What it does |
+|---------|-------------|
+| `everystack update --channel production` | OTA deploy (no infrastructure changes) |
+| `everystack db:migrate` | Run Drizzle migrations via Lambda invoke |
+| `everystack db:seed` | Seed database via Lambda invoke (dev only) |
+| `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 |
+| `everystack logs:tail --stage dev` | Tail CloudWatch Lambda logs |
+| `everystack logs:query --stage dev` | Flexible log search with filters |
+| `everystack cache:purge` | Bust CloudFront cache via KVS |
+| `everystack certs:generate` | Generate RSA key pair for code signing |
+| `everystack diag URL` | Diagnose deployed page freshness |
+| `everystack analyze:ssr` | Static analysis for SSR anti-patterns |
+
+## Key Patterns
+
+**Schema-agnostic.** The library knows nothing about your tables. You pass your Drizzle schema to `createHandler()`. Your schema, your migrations, your database.
+
+**Web Standards.** Handler uses Request/Response. No Express, no Fastify. Works with any Web Standard runtime.
+
+**SST for infrastructure.** Resource linking injects secrets at deploy time (no env vars). `_action` dispatch lets the CLI invoke Lambda directly via IAM.
+
+**Progressive complexity.** Install only what you need. V1 has zero database code. V2 adds it. V3 adds workers. Each tier is additive.
+
+**Plugin architecture.** Packages provide plugins (`@everystack/auth/plugin`, `@everystack/jobs/plugin`) that compose into a single Lambda handler via `createPluginLambdaHandler`.
+
+## Conventions
+
+- TypeScript strict mode, named exports only (no default exports)
+- Files: `kebab-case.ts`. Types: `PascalCase`. Functions: `camelCase`
+- Tests in `__tests__/` mirroring source, named `{feature}.test.ts`
+- Conventional commits: `feat:`, `fix:`, `chore:`, `docs:`, `test:`
+- TDD: write failing test first, implement, refactor
+- Zero runtime dependencies in the API library
+- Peer dependencies for optional integrations

package/src/resources/deployment.md

@@ -0,0 +1,146 @@
+# Deployment Guide
+
+> SST deployment: infrastructure setup, secrets, stages, CloudFront configuration.
+
+## When to Use
+Read this when deploying an everystack app to AWS for the first time or adding a new stage.
+
+## Prerequisites
+
+- Node.js 20+, pnpm
+- AWS account with credentials (`aws configure`)
+- SST CLI (`pnpm add -g sst`)
+
+## SST Config
+
+```typescript
+// sst.config.ts
+export default $config({
+  app(input) {
+    return {
+      name: 'my-app',
+      removal: input?.stage === 'production' ? 'retain' : 'remove',
+      home: 'aws',
+    };
+  },
+  async run() {
+    // V1: Static site
+    const updates = new sst.aws.Bucket('Updates');
+
+    // V2: Add database
+    const vpc = new sst.aws.Vpc('Vpc');
+    const database = new sst.aws.Postgres('Database', {
+      vpc,
+      scaling: { min: '0.5 ACU', max: '2 ACU' },
+    });
+
+    // V3: Add queues + media
+    const media = new sst.aws.Bucket('Media');
+    const dlq = new sst.aws.Queue('DeadLetterQueue');
+    const jobs = new sst.aws.Queue('Jobs', { dlq: dlq.arn });
+
+    // Lambda functions
+    const api = new sst.aws.Function('Api', {
+      handler: 'server/api.handler',
+      link: [database, updates],
+      vpc,
+    });
+
+    // V3: Worker + Image Lambdas
+    const worker = new sst.aws.Function('Worker', {
+      handler: 'server/worker.handler',
+      link: [database, jobs, media],
+      vpc,
+    });
+
+    // CDN
+    const router = new sst.aws.Router('Router', {
+      routes: { '/*': api.url },
+    });
+
+    // CLI needs these outputs
+    return {
+      routerUrl: router.url,
+      apiFunctionName: api.name,
+      updatesBucket: updates.name,
+      clientBundlesBucket: updates.name,
+    };
+  },
+});
+```
+
+## Secrets
+
+SST secrets are per-stage, encrypted, stored in S3:
+
+```bash
+pnpm sst secret set JwtSecret "$(openssl rand -base64 32)" --stage dev
+pnpm sst secret set JwtSecret "$(openssl rand -base64 64)" --stage production
+```
+
+Access in code via Resource linking: `Resource.JwtSecret.value`. Never in env vars or code.
+
+## Stages
+
+```bash
+pnpm sst deploy --stage dev          # Development
+pnpm sst deploy --stage production   # Production
+```
+
+Each stage gets isolated resources (separate database, buckets, Lambda functions). Use `removal: 'retain'` for production to prevent accidental deletion.
+
+## Deploy Flow
+
+```bash
+# 1. Export Expo app
+pnpm export
+
+# 2. Deploy infrastructure + code
+pnpm sst deploy --stage dev
+
+# 3. Run migrations
+everystack db:migrate
+
+# 4. Seed database (dev only)
+everystack db:seed
+
+# 5. Subsequent content updates (no deploy needed)
+everystack update --channel production
+```
+
+## Resource Linking
+
+SST injects resource details into Lambda at deploy time:
+
+```typescript
+import { Resource } from 'sst';
+
+// Database credentials (automatic from sst.aws.Postgres)
+Resource.Database.host
+Resource.Database.port
+Resource.Database.database
+Resource.Database.username
+Resource.Database.password
+
+// Secrets
+Resource.JwtSecret.value
+
+// Buckets
+Resource.Updates.name
+Resource.Media.name
+```
+
+No env vars needed. `@everystack/server/db` provides `createDb()` which reads these automatically.
+
+## AWS IAM Profiles
+
+See everystack://security for the three-profile model (everystack-create, everystack-manage, everystack-deploy).
+
+## Gotchas
+
+- First deploy creates VPC + RDS (can take 10-15 minutes)
+- Database credentials are managed by SST/RDS (no manual password management)
+- `sst dev` provides live Lambda debugging with hot reload
+- `removal: 'remove'` deletes all resources when the stage is removed
+- `removal: 'retain'` keeps RDS and S3 even if the stage is removed
+- Outputs are written to `.sst/outputs.json` (used by CLI for auto-discovery)

package/src/resources/events.md

@@ -0,0 +1,87 @@
+# Events & WebSocket
+
+> Real-time events via PostgreSQL LISTEN/NOTIFY and WebSocket fan-out. Import from `@everystack/events`.
+
+## When to Use
+Read this when adding real-time updates: live feeds, notifications, collaborative editing.
+
+## Setup
+
+```typescript
+import { createEventHandler } from '@everystack/events/handler';
+
+const events = createEventHandler({
+  db,
+  channels: ['table:posts', 'table:profiles', 'user:notifications'],
+});
+```
+
+## How It Works
+
+1. Database change triggers NOTIFY on a channel
+2. Listener Lambda receives the notification
+3. Fan-out via WebSocket to connected clients
+4. Client `useSignal` hook fires callback
+
+## Client Hook
+
+```typescript
+import { useSignal } from '@everystack/events/client';
+
+function PostList() {
+  const [posts, setPosts] = useState(initialPosts);
+
+  useSignal('table:posts', () => {
+    // Refetch when posts table changes
+    refetchPosts().then(setPosts);
+  });
+
+  return <FlatList data={posts} />;
+}
+```
+
+## Database Trigger
+
+```sql
+CREATE OR REPLACE FUNCTION notify_table_change()
+RETURNS trigger AS $$
+BEGIN
+  PERFORM pg_notify('table:' || TG_TABLE_NAME, json_build_object(
+    'operation', TG_OP,
+    'id', COALESCE(NEW.id, OLD.id)
+  )::text);
+  RETURN COALESCE(NEW, OLD);
+END;
+$$ LANGUAGE plpgsql;
+
+CREATE TRIGGER posts_notify
+  AFTER INSERT OR UPDATE OR DELETE ON posts
+  FOR EACH ROW EXECUTE FUNCTION notify_table_change();
+```
+
+## Actions
+
+```typescript
+import { createEventActions } from '@everystack/events/actions';
+
+const actions = createEventActions({
+  invokeFunction: Resource.ListenerFunction.name,
+});
+
+// Trigger from API handler
+await actions.notify('user:notifications', { userId: 'abc', message: 'New follower' });
+```
+
+## Schema
+
+```typescript
+import { eventsSchema } from '@everystack/events/schema';
+// Adds: event_subscriptions table for persistent subscriptions
+```
+
+## Gotchas
+
+- LISTEN/NOTIFY is per-database-connection (not per-Lambda)
+- The listener Lambda must maintain a persistent connection
+- WebSocket connections are managed separately from HTTP
+- Payload size limit for NOTIFY is 8000 bytes

package/src/resources/first-run.md

@@ -0,0 +1,100 @@
+# Running Your App Locally
+
+You have a project. Now let's see it work.
+
+## Starting the dev server
+
+Run this command from your project directory:
+
+```bash
+npx expo start
+```
+
+Or if you have pnpm installed:
+
+```bash
+pnpm dev
+```
+
+## What you'll see
+
+The terminal will show output like this:
+
+```
+Starting Metro Bundler
+▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
+█ QR CODE HERE  █
+▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
+
+› Press w │ open web
+› Press i │ open iOS simulator
+› Press a │ open Android emulator
+› Press r │ reload app
+› Press j │ open debugger
+```
+
+**Metro Bundler** is the tool that packages your code so a browser or phone can run it. It starts automatically.
+
+## Opening in a browser
+
+Press **w** in the terminal. Your browser will open to something like `http://localhost:8081`. You should see your app's home screen.
+
+If `w` doesn't work, open your browser manually and go to `http://localhost:8081`.
+
+## Opening on your phone
+
+Install the **Expo Go** app from the App Store (iPhone) or Google Play (Android). Then scan the QR code shown in the terminal with your phone's camera. The app will load on your phone over your local Wi-Fi network.
+
+Your phone and computer must be on the same Wi-Fi network for this to work.
+
+## Hot reload
+
+When you change a file and save it, the app updates automatically. You don't need to restart anything. This is called **hot reload**.
+
+Try it: open `app/index.tsx` in your editor, change some text, save the file, and watch the browser or phone update.
+
+## Stopping the server
+
+Press **Ctrl+C** in the terminal. This stops the dev server. Your app will stop working in the browser until you start it again.
+
+## Common issues
+
+### "Port 8081 is already in use"
+
+Something else is using that port. Either stop the other program, or start Expo on a different port:
+
+```bash
+npx expo start --port 8082
+```
+
+### "Unable to resolve module"
+
+A package is missing. Run:
+
+```bash
+pnpm install
+```
+
+Then try starting again.
+
+### The app is stuck or shows an old version
+
+Clear the Metro cache and restart:
+
+```bash
+npx expo start --clear
+```
+
+### "Network response timed out" on phone
+
+Your phone and computer aren't on the same network, or a firewall is blocking the connection. Make sure both are on the same Wi-Fi.
+
+### White screen or "Something went wrong"
+
+Check the terminal for red error text. The error message will tell you what's wrong. Copy the error and ask Claude for help.
+
+## What's next
+
+Once your app runs locally and you can see changes in real time, you're ready to start building. Describe what you want to add and Claude will help you implement it.
+
+When you're ready to put your app on the internet so others can use it, you'll set up AWS and deploy. That's a separate step — there's no rush. Build locally first, deploy when you're ready.