@everystack/mcp 0.2.0

package/src/resources/adding-database.md

@@ -0,0 +1,169 @@
+# Adding a Database to Your App
+
+Your app needs to remember things between sessions. User accounts, saved recipes, posts, settings — data that lives beyond a single visit. This guide walks you through adding a database and data layer to your existing Expo app.
+
+## What you're adding
+
+You already have a running Expo app. Now you're adding:
+
+- **PostgreSQL** — a database that stores your app's data. Think of it as a spreadsheet your app reads and writes automatically.
+- **@everystack/api** — handles requests from your app to the database. When the app asks "show me all recipes," this package translates that into a database query.
+- **@everystack/auth** — user signup, login, and session management. Handles passwords securely and issues tokens that prove who the user is.
+- **@everystack/admin** — a dashboard for managing your app's data (users, content, settings).
+- **@everystack/logging** — structured logging so you can see what your app is doing.
+- **@everystack/security** — device attestation and biometric auth.
+- **@everystack/query** — React hooks that make it easy to fetch and display data.
+- **Drizzle ORM** — defines your database tables in TypeScript. You describe what data you want to store, and Drizzle creates the tables for you.
+
+## Step 1: Install PostgreSQL
+
+PostgreSQL is the database. It runs as a service on your computer.
+
+**macOS:**
+
+```bash
+brew install postgresql@16
+brew services start postgresql@16
+```
+
+**Linux:**
+
+```bash
+sudo apt install postgresql
+sudo systemctl start postgresql
+```
+
+### Verify it's running
+
+```bash
+pg_isready
+```
+
+You should see: `accepting connections`. If not, the service isn't running — try the start command again.
+
+## Step 2: Create your database
+
+A database is like a blank spreadsheet. You need to create one for your app.
+
+```bash
+createdb my-app-dev
+```
+
+Replace `my-app-dev` with your app name plus `-dev` (the `-dev` helps you remember this is your local development database).
+
+### Verify it works
+
+```bash
+psql my-app-dev -c "SELECT 1"
+```
+
+You should see a table with the value `1`. If so, your database is ready.
+
+## Step 3: Install V2 packages
+
+From your project directory:
+
+```bash
+pnpm add @everystack/api @everystack/auth @everystack/admin @everystack/logging @everystack/security @everystack/query
+pnpm add drizzle-orm
+pnpm add -D drizzle-kit
+```
+
+## Step 4: Create your database schema
+
+The schema defines what data your app stores. Create a file at `db/schema.ts`.
+
+A schema is like designing a spreadsheet before you start filling in data. You decide what columns each table has, what type of data goes in each column, and how tables relate to each other.
+
+Read everystack://schema-patterns for design patterns and examples. Key conventions:
+
+- UUID primary keys with `defaultRandom()`
+- `created_at` and `updated_at` timestamps on all tables
+- Foreign key references with proper cascading
+- Relations defined for both SSR and API query embedding
+- Snake_case column names
+
+## Step 5: Configure the handler
+
+Create `server/api.ts`. This is the bridge between your app and the database.
+
+Read everystack://handler-options for the full reference. At minimum, configure:
+
+- `basePath` — the URL prefix for API routes (usually `/api`)
+- `auth.verifyToken` — how to verify JWT tokens
+- `pgSettings` — injects the user's identity into database queries for row-level security
+- `exposedTables` — which tables the API can access (whitelist)
+- `rowOwnership` — which column identifies the owner of each row
+
+## Step 6: Set up authentication
+
+Read everystack://auth for the full auth flow.
+
+- Create auth handlers with `createAuthHandlers()`
+- Create `lib/auth-context.tsx` with `AuthProvider` for your React components
+- Add signup and signin screens to your app
+
+## Step 7: Create an API route
+
+Create `app/api/[...path]+api.ts` — this is an Expo Router API route that mounts your handler:
+
+```typescript
+import { handler } from '../../server/api';
+
+export async function GET(request: Request) {
+  return handler(request);
+}
+
+export async function POST(request: Request) {
+  return handler(request);
+}
+
+// ... PATCH, DELETE
+```
+
+## Step 8: Run migrations
+
+Migrations create the actual tables in your database based on your schema.
+
+```bash
+npx drizzle-kit generate
+npx drizzle-kit migrate
+```
+
+The first command generates SQL files from your schema. The second runs them against your database.
+
+## Step 9: Security
+
+**This is not optional.** Read everystack://security for the three-layer security model.
+
+Your database needs Row Level Security (RLS) policies. These are rules that control who can see and change what data. Even if your app code has a bug, the database enforces access control.
+
+At minimum:
+- Create database roles (`anon`, `authenticated`, `admin`)
+- Add RLS policies to every table
+- Set up GRANTs so each role can only access what it should
+
+The security resource has copy-paste SQL templates for common patterns.
+
+## Step 10: Verify
+
+Run your app:
+
+```bash
+npx expo start
+```
+
+You should be able to:
+1. See the app in your browser
+2. Sign up for a new account
+3. Create data (a post, a recipe, etc.)
+4. Refresh the page and see the data persists
+5. Log out and log back in — your data is still there
+
+## What's next
+
+Continue building features. If your app later needs file uploads or background processing (like sending emails or resizing images), those are separate packages you can add incrementally:
+
+- **File uploads:** `@everystack/storage` — read everystack://storage
+- **Background jobs:** `@everystack/jobs` — read everystack://jobs
+- **Image processing:** `@everystack/images` — read everystack://images

package/src/resources/admin.md

@@ -0,0 +1,81 @@
+# Admin Dashboard
+
+> Declarative admin dashboard for everystack apps. Import from `@everystack/admin`.
+
+## When to Use
+Read this when adding an admin interface to a V2+ app.
+
+## Setup
+
+```typescript
+import { AdminRoot, AdminLayout, EverystackAdapter } from '@everystack/admin';
+
+const adapter = new EverystackAdapter({ baseUrl: '/api' });
+
+const config = {
+  resources: {
+    posts: {
+      fields: {
+        id: { type: 'text', label: 'ID' },
+        title: { type: 'text', label: 'Title' },
+        body: { type: 'textarea', label: 'Body' },
+        status: { type: 'select', label: 'Status', options: ['draft', 'published'] },
+        authorId: { type: 'reference', label: 'Author', reference: 'users' },
+        createdAt: { type: 'date', label: 'Created' },
+      },
+      list: { columns: ['title', 'status', 'createdAt'] },
+      edit: { fields: ['title', 'body', 'status'] },
+    },
+  },
+};
+
+export default function AdminRootLayout() {
+  return (
+    <AdminRoot config={config} adapter={adapter}>
+      <AdminLayout onNavigate={router.push}>
+        <Slot />
+      </AdminLayout>
+    </AdminRoot>
+  );
+}
+```
+
+## Field Types
+
+| Type | Description |
+|------|-------------|
+| `text` | Single-line text input |
+| `textarea` | Multi-line text |
+| `number` | Numeric input |
+| `date` | Date picker |
+| `boolean` | Toggle/checkbox |
+| `select` | Dropdown (requires `options`) |
+| `reference` | Foreign key reference (requires `reference` table name) |
+| `json` | JSON editor |
+| `image` | Image URL with preview |
+
+## EverystackAdapter
+
+Connects the admin dashboard to the PostgREST API:
+```typescript
+const adapter = new EverystackAdapter({
+  baseUrl: '/api',
+  getToken: () => token,
+});
+```
+
+Methods: `getList`, `getOne`, `create`, `update`, `delete`. Translates admin operations to PostgREST queries.
+
+## Presets
+
+```typescript
+import { twitterPreset } from '@everystack/admin/presets/twitter';
+```
+
+Presets provide pre-configured admin layouts for common app patterns.
+
+## Gotchas
+
+- Admin pages should be behind auth (add auth check in layout)
+- EverystackAdapter respects `exposedTables` and `hiddenColumns` from the handler
+- Reference fields require the referenced table to be in `exposedTables`

package/src/resources/auth.md

@@ -0,0 +1,115 @@
+# Authentication
+
+> JWT auth flows, OAuth, edge verification. Import from `@everystack/auth`.
+
+## When to Use
+Read this when adding user authentication to a V2+ app.
+
+## Setup
+
+```typescript
+import { createAuthHandlers } from '@everystack/auth';
+import { createDb, getJwtSecret } from '@everystack/server/db';
+
+const { db } = createDb(schema);
+const auth = createAuthHandlers(db, schema, getJwtSecret());
+```
+
+`getJwtSecret()` reads the JWT secret from SST Resource linking (`Resource.JwtSecret.value`).
+
+## Auth Handlers
+
+`createAuthHandlers()` returns Web Standard request handlers:
+
+| Handler | Method | Path | Description |
+|---------|--------|------|-------------|
+| `signup` | POST | `/api/auth/signup` | Create account (email + password) |
+| `signin` | POST | `/api/auth/signin` | Login, returns access + refresh token |
+| `refresh` | POST | `/api/auth/refresh` | Exchange refresh token for new access token |
+| `verifyToken` | - | - | JWT verification function (for handler auth config) |
+
+### Route Setup
+
+```typescript
+export const handler = createLambdaHandler({
+  init: async () => ({ api, ...auth }),
+  routes: (h) => [
+    { path: '/api/auth/signup', method: 'POST', exact: true, handler: h.signup },
+    { path: '/api/auth/signin', method: 'POST', exact: true, handler: h.signin },
+    { path: '/api/auth/refresh', method: 'POST', exact: true, handler: h.refresh },
+    { path: '/api', handler: h.api },
+  ],
+});
+```
+
+## Token Lifecycle
+
+1. **Signup**: creates user, hashes password (bcrypt, cost 12), returns access + refresh tokens
+2. **Signin**: verifies password, returns access + refresh tokens
+3. **Access token**: short-lived JWT (15 min recommended for edge, 1h otherwise)
+4. **Refresh token**: long-lived, DB-backed, one-time-use rotation (old token invalidated on use)
+
+## Edge JWT Verification
+
+CloudFront Functions verify JWTs before requests reach Lambda:
+
+```typescript
+import { generateCffVerifier } from '@everystack/auth/cff';
+
+const source = generateCffVerifier({
+  functionName: 'verifyJwt',
+  clockSkewSec: 30,
+});
+// source is portable ES2019 JS for CloudFront Functions runtime
+```
+
+Properties: HS256 only, constant-time comparison, algorithm pinning (prevents alg=none attacks), no external dependencies.
+
+## OAuth
+
+```typescript
+import { createOAuthHandlers } from '@everystack/auth/oauth';
+
+const oauth = createOAuthHandlers(db, schema, getJwtSecret(), {
+  providers: {
+    google: { clientId: '...', clientSecret: '...' },
+    apple: { clientId: '...', teamId: '...', keyId: '...', privateKey: '...' },
+  },
+});
+```
+
+## React Client
+
+```typescript
+import { AuthProvider, useAuth } from '@everystack/auth/client';
+
+// Wrap your app
+<AuthProvider baseUrl="/api/auth">
+  <App />
+</AuthProvider>
+
+// In components
+const { user, signIn, signUp, signOut, isLoading } = useAuth();
+```
+
+## Auth Plugin
+
+For plugin-based composition:
+
+```typescript
+import { authPlugin } from '@everystack/auth/plugin';
+
+// Adds signup, signin, refresh, verify, signout routes
+// Decorates verifyToken with audience check, client resolution, device attestation
+```
+
+Plugin layers: audience check -> client resolution -> device attestation -> custom claims validation -> claims enrichment.
+
+## Gotchas
+
+- JWT secret must be stored in SST secrets, never in code
+- Access tokens should be 15 min max when using edge verification
+- Refresh tokens are one-time-use: using a refresh token invalidates it
+- bcrypt cost factor defaults to 12 (configurable)
+- `verifyToken` returns the JWT payload (not just true/false)
+- The `publicRpc` array skips BOTH token auth AND client auth

package/src/resources/aws-setup.md

@@ -0,0 +1,173 @@
+# Setting Up AWS for everystack
+
+AWS (Amazon Web Services) rents you computers on the internet. When you deploy your app, it runs on AWS servers so anyone in the world can use it. This guide walks you through creating an account and giving your computer permission to deploy.
+
+## What does everystack use on AWS?
+
+Your app is made up of a few building blocks. Each one is an AWS service:
+
+| Service | What it does | Plain English | Tier | Typical cost |
+|---------|-------------|---------------|------|-------------|
+| **S3** | File storage | Holds your app's files (HTML, CSS, JavaScript, images) | V1+ | Pennies/month |
+| **CloudFront** | Content delivery network | Makes your app load fast for users worldwide | V1+ | Free tier covers most small apps |
+| **Lambda** | Serverless compute | Runs your server code only when someone visits | V1+ | Free tier: 1M requests/month |
+| **RDS** | Managed database | Stores your users, posts, and data (Aurora Serverless) | V2+ | ~$15/month minimum |
+| **SQS** | Message queue | Processes background tasks like sending emails | V3 | Pennies/month |
+
+**Total cost for a small app with low traffic:** Under $5/month for V1, ~$20/month for V2+ (the database is the main cost).
+
+AWS has a **free tier** for the first 12 months that covers most of what everystack uses at low traffic. You will not be charged anything significant while learning.
+
+## Step 1: Create an AWS account
+
+1. Go to https://aws.amazon.com/free
+2. Click **Create a Free Account**
+3. You will need:
+   - An email address
+   - A credit card (required for verification, but free tier usage will not be charged)
+   - A phone number for verification
+4. Choose the **Basic Support** plan (free)
+5. After account creation, sign in to the AWS Console at https://console.aws.amazon.com to confirm it works
+
+## Step 2: Create an IAM user for everystack
+
+Your AWS account has a "root user" (the email you signed up with). The root user has unlimited power over your account. You should never use it for daily work. Instead, create a dedicated user just for everystack.
+
+**IAM** stands for Identity and Access Management. It controls who can do what in your AWS account.
+
+### Create the user
+
+1. Sign in to the **AWS Console** at https://console.aws.amazon.com
+2. In the top search bar, type **IAM** and click on it
+3. Click **Users** in the left sidebar
+4. Click **Create user**
+5. Enter the user name: `everystack-dev`
+6. Click **Next**
+
+### Create the permissions policy
+
+This policy gives the user exactly the permissions SST needs to deploy your app.
+
+7. Select **Attach policies directly**
+8. Click **Create policy** (this opens a new tab)
+9. Click the **JSON** tab
+10. Delete anything in the editor and paste this:
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Sid": "EverystackDeploy",
+      "Effect": "Allow",
+      "Action": [
+        "cloudformation:*",
+        "s3:*",
+        "lambda:*",
+        "cloudfront:*",
+        "iam:CreateRole",
+        "iam:DeleteRole",
+        "iam:GetRole",
+        "iam:GetRolePolicy",
+        "iam:PassRole",
+        "iam:AttachRolePolicy",
+        "iam:DetachRolePolicy",
+        "iam:PutRolePolicy",
+        "iam:DeleteRolePolicy",
+        "iam:ListRolePolicies",
+        "iam:ListAttachedRolePolicies",
+        "iam:TagRole",
+        "iam:UntagRole",
+        "iam:CreateServiceLinkedRole",
+        "rds:*",
+        "ec2:DescribeVpcs",
+        "ec2:DescribeSubnets",
+        "ec2:DescribeSecurityGroups",
+        "ec2:DescribeRouteTables",
+        "ec2:DescribeAvailabilityZones",
+        "ec2:DescribeVpcEndpoints",
+        "ec2:CreateSecurityGroup",
+        "ec2:DeleteSecurityGroup",
+        "ec2:AuthorizeSecurityGroupIngress",
+        "ec2:RevokeSecurityGroupIngress",
+        "ec2:AuthorizeSecurityGroupEgress",
+        "ec2:RevokeSecurityGroupEgress",
+        "ec2:CreateVpcEndpoint",
+        "ec2:DeleteVpcEndpoint",
+        "ec2:CreateTags",
+        "ec2:DeleteTags",
+        "route53:*",
+        "sqs:*",
+        "ssm:*",
+        "logs:*",
+        "sts:GetCallerIdentity",
+        "sts:AssumeRole"
+      ],
+      "Resource": "*"
+    }
+  ]
+}
+```
+
+11. Click **Next**
+12. Name the policy: `everystack-dev-policy`
+13. Optionally add a description: "Permissions for everystack SST deploys"
+14. Click **Create policy**
+
+### Attach the policy to the user
+
+15. Go back to the **Create user** tab in your browser
+16. Click the refresh button on the policy list
+17. Search for `everystack-dev-policy`
+18. Check the box next to it
+19. Click **Next**, then **Create user**
+
+### Create an access key
+
+20. Click on the user name **everystack-dev**
+21. Go to the **Security credentials** tab
+22. Under **Access keys**, click **Create access key**
+23. Select **Command Line Interface (CLI)**
+24. Check the confirmation checkbox, click **Next**, then **Create access key**
+25. **Save both keys now.** You will not see the secret key again after this page:
+    - **Access key ID** (looks like: `AKIAIOSFODNN7EXAMPLE`)
+    - **Secret access key** (looks like: `wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY`)
+
+## Step 3: Configure your computer
+
+Open a terminal and run:
+
+```bash
+aws configure
+```
+
+It will ask four questions:
+
+- **AWS Access Key ID:** Paste the access key ID from Step 2
+- **AWS Secret Access Key:** Paste the secret access key from Step 2
+- **Default region name:** `us-east-1` (recommended, or choose your nearest region)
+- **Default output format:** `json`
+
+## Step 4: Verify it works
+
+Run this command:
+
+```bash
+aws sts get-caller-identity
+```
+
+You should see something like:
+
+```json
+{
+    "UserId": "AIDAIOSFODNN7EXAMPLE",
+    "Account": "123456789012",
+    "Arn": "arn:aws:iam::123456789012:user/everystack-dev"
+}
+```
+
+If you see your account number and `everystack-dev`, your credentials are working. You are ready to deploy.
+
+## Production hardening
+
+The `everystack-dev` user above has broad permissions suitable for getting started. When you are ready to harden your setup for production, read `everystack://security` for a three-profile model that separates infrastructure creation, day-to-day operations, and CI/CD into distinct IAM users with minimal permissions.

package/src/resources/cli.md

@@ -0,0 +1,108 @@
+# CLI Reference
+
+> Full command reference for the `everystack` CLI. Import from `@everystack/cli`.
+
+## When to Use
+Read this when deploying, debugging, or managing a deployed everystack app. All commands use AWS IAM credentials (not shared secrets).
+
+## Authentication
+
+| Operation | Auth Mechanism |
+|-----------|---------------|
+| `db:migrate`, `db:seed`, `console` | IAM -> Lambda invoke |
+| `update --platform web` | IAM -> S3 PutObject + Lambda invoke |
+| `update --platform ios/android` | `EVERYSTACK_TOKEN` -> HTTP POST |
+| `logs:errors`, `logs:query` | IAM -> Lambda invoke |
+| `logs:tail` | IAM -> CloudWatch FilterLogEvents |
+| `cache:purge` | IAM -> CloudFront KVS |
+| `certs:*` | Local only (no network) |
+
+## Commands
+
+### OTA Updates
+```bash
+everystack update --channel production --message "Fix login bug"
+everystack update --channel production --platform ios --message "iOS fix"
+everystack update --channel staging --platform web
+```
+Flags: `--channel` (default: production), `--message`, `--platform` (ios/android/web/all), `--skip-export`.
+
+### Database
+```bash
+everystack db:migrate                                    # Run migrations via Lambda
+everystack db:seed                                       # Seed database (dev only)
+everystack db:psql --stage dev -c "SELECT * FROM posts"  # Read-only SQL via Lambda
+everystack console --stage dev                           # Interactive REPL with db + schema
+```
+
+The REPL has `db`, `schema`, `eq`, `and`, `or`, `gt`, `lt`, `count`, `sum`, `avg`, `sql`, `desc`, `asc` in scope.
+
+### Logs
+```bash
+everystack logs:errors --stage dev                       # Recent errors (DB -> S3 fallback)
+everystack logs:errors --stage dev --limit 50 --level fatal
+everystack logs:tail --stage dev                         # CloudWatch Lambda output
+everystack logs:tail --stage dev --filter ERROR --since 1h
+everystack logs:query --stage dev --level error --source api
+everystack logs:query --stage dev --traceId "abc123"
+everystack logs:query --stage dev --userId "user_123" --since 30m
+```
+
+### Cache
+```bash
+everystack cache:purge                                   # Global cache bust
+everystack cache:purge --origin web                      # Per-origin
+everystack cache:purge --path "/api/posts"               # Per-path
+```
+
+### Code Signing
+```bash
+everystack certs:generate --output ./certs               # Generate RSA key pair
+everystack certs:configure --input ./certs --keyid main  # Add to app.json
+```
+
+### Channels
+```bash
+everystack channels list
+everystack channels create --name staging
+```
+
+### SSR Debugging
+```bash
+everystack diag https://myapp.com                        # Version + cache check
+everystack diag https://myapp.com/page --hydration       # Runtime hydration analysis
+everystack analyze:ssr                                   # Static analysis for SSR anti-patterns
+```
+
+## Configuration
+
+The CLI auto-discovers resources from `.sst/outputs.json` (written by `sst deploy`). Required outputs:
+```typescript
+return {
+  routerUrl: router.url,
+  apiFunctionName: api.name,
+  updatesBucket: updates.name,
+  clientBundlesBucket: clientBundles.name,
+};
+```
+
+Use `--stage` flag to target specific deployments: reads from `.sst/outputs.{stage}.json`.
+
+## Environment Variables
+
+| Variable | Purpose |
+|----------|---------|
+| `AWS_REGION` | AWS region (default: us-east-1) |
+| `AWS_PROFILE` | AWS credentials profile |
+| `EVERYSTACK_TOKEN` | JWT for authenticated mobile uploads |
+
+## Lambda onAction Integration
+
+The CLI invokes Lambda with `_action` payloads. Your handler must dispatch them:
+```typescript
+onAction: async (action, payload) => {
+  if (action === 'migrate') return runMigrations(db, './drizzle');
+  if (action === 'seed') return runSeed(db, schema);
+  // ... console, db:psql, logs:errors, logs:query, etc.
+}
+```