@everystack/mcp 0.2.2 → 0.3.0

package/dist/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/dist/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. Deploy infrastructure + code
+pnpm sst deploy --stage dev
+
+# 2. Export + publish app bundles
+everystack update --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/dist/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/dist/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.

package/dist/getting-started.md

@@ -0,0 +1,75 @@
+# What is everystack?
+
+everystack helps you build apps. Real apps that work on iPhones, Android phones, tablets, computers, and the web — all from the same code.
+
+You describe what you want. Claude helps you build it. everystack provides the building blocks.
+
+**A note about difficulty:** Building software is hard. Professional engineers are paid well to do this, and projects often take months or years. Claude and everystack make it much more accessible, but you are still building real software with real infrastructure. Things will break. You will hit errors you don't understand. That's normal. The key is to keep going, ask questions, and learn as you go.
+
+## How it works
+
+You start simple: a running app on your screen. Then you build from there.
+
+Every app starts the same way — a basic Expo app that works on phones, tablets, and the web. You build the screens, the navigation, the look and feel. Everything is visual and immediate.
+
+When your app needs more — user accounts, saved data, file uploads — you add those capabilities one at a time. You never throw away what you already built. Your app grows with you.
+
+## What you need to get started
+
+These are tools that run on your computer. Claude will help you install each one.
+
+**Node.js** — Runs your code. Your app is written in TypeScript (a programming language). Node.js is the engine that makes it work, like how a car needs an engine to drive.
+- Without it: Nothing runs.
+
+**git** — Tracks every change you make to your code. Like an unlimited undo button for your entire project. You can always go back to any previous version.
+- Without it: You cannot track changes or undo mistakes.
+
+**pnpm** (recommended) — A faster way to install code libraries your app depends on. Recommended but Claude can work without it.
+
+That's it. Those three tools are all you need to create an app and see it running on your computer.
+
+### When your app needs a database (later)
+
+If your app needs user accounts or saved data, you'll add a database. This is not needed to start — only when a feature demands it.
+
+**PostgreSQL** — A database that stores your app's data: users, posts, recipes, or whatever your app needs. Like a spreadsheet that your app reads and writes automatically. Read everystack://adding-database when you're ready for this step.
+
+### To deploy to the internet (later)
+
+You don't need these right away. Install them when you're ready to put your app online so other people can use it.
+
+**AWS account + AWS CLI** — AWS (Amazon Web Services) is where your app lives on the internet. Other people's computers run your app so anyone can use it. The AWS CLI is a tool that lets Claude talk to AWS from your computer.
+- Without it: Your app only works on your computer. Nobody else can use it.
+- Setting up AWS requires a credit card for verification. AWS has a free tier for the first 12 months. You control all costs and can delete everything at any time.
+
+**AWS credentials** — A password file that proves your computer is allowed to deploy to your AWS account. You create this once during setup.
+- Without them: AWS will reject all deploy commands.
+- New to AWS? Read everystack://aws-setup for a complete walkthrough of creating an account and setting up credentials.
+
+## The path from idea to running app
+
+1. **You describe your idea.** "I want to build a recipe sharing app."
+2. **Claude checks your computer.** Runs a tool to see what's installed and what's missing.
+3. **Claude helps you install anything missing.** Step by step, one tool at a time. Each one explained before you install it.
+4. **Claude creates your app.** A stock Expo app with the everystack building blocks installed.
+5. **You see it running on your computer.** Your app opens in a browser. You can change things and see updates instantly. Read everystack://first-run for details on this step.
+6. **You build together.** Describe what you want — screens, buttons, colors, layout. Claude builds it. You see changes in real time. This is where most of the work happens.
+7. **Your app grows when it needs to.** When a feature needs user accounts or saved data, Claude helps you add a database. When you need file uploads, you add that too. One thing at a time.
+8. **When you're ready, you deploy.** Your app gets a real URL that anyone can visit. This is a separate step — there's no rush.
+
+## Common questions
+
+**Do I need to know how to code?**
+Not to start. Claude writes the code and explains what it's doing. But you're building real software — the same kind that teams of engineers get paid to build. Things will break. You'll need to learn as you go. The more you understand, the better your app will be.
+
+**How much does AWS cost?**
+For a small app with low traffic, typically under $5/month for a static site and around $20/month once you add a database (the database is the main cost). AWS has a free tier for the first 12 months that covers most of what everystack uses. You can build and run locally for free with no AWS account at all.
+
+**Can I change things later?**
+Yes. everystack is built for this. Start with a simple app, add user accounts when you need them, add file uploads when you need them. You never throw away what you already built.
+
+**What if something goes wrong?**
+Claude can debug it. everystack has built-in tools that check your project for common mistakes and security issues. And git tracks every change, so you can always go back. Expect things to go wrong — that's part of building software. The tools are here to help you recover.
+
+**Do I need a Mac?**
+For now, yes. everystack's setup tools are designed for macOS. Windows and Linux support may come later.