@everystack/mcp 0.2.0

package/src/resources/plugins.md

@@ -0,0 +1,68 @@
+# Plugin Architecture
+
+> Composable handler system for everystack packages. Import plugin system from `@everystack/server/plugin`.
+
+## When to Use
+Read this when composing multiple everystack packages into a single Lambda handler.
+
+## Setup
+
+```typescript
+import { createPluginLambdaHandler, type Plugin, type PluginContext } from '@everystack/server/plugin';
+
+const handler = createPluginLambdaHandler({
+  plugins: [authPlugin, jobsPlugin, storagePlugin, apiPlugin],
+  schema,
+  // ... other options
+});
+```
+
+## Plugin Type
+
+```typescript
+type Plugin = (ctx: PluginContext) => Promise<Record<string, Handler>>;
+
+interface PluginContext {
+  db: DrizzleDb;
+  schema: Record<string, Table>;
+  verifyToken: (token: string) => Promise<Record<string, unknown> | null>;
+}
+```
+
+A plugin receives context and returns a map of named handlers.
+
+## Available Plugins
+
+| Plugin | Package | Routes |
+|--------|---------|--------|
+| `authPlugin` | `@everystack/auth/plugin` | signup, signin, refresh, verify, signout |
+| `jobsPlugin` | `@everystack/jobs/plugin` | job dispatch, status |
+| `storagePlugin` | `@everystack/storage/plugin` | upload, confirm, list, delete |
+| `loggingPlugin` | `@everystack/logging/plugin` | log ingestion, query |
+| `cliPlugin` | `@everystack/cli/plugin` | OTA updates, manifest |
+
+## Writing a Custom Plugin
+
+```typescript
+const myPlugin: Plugin = async (ctx) => {
+  return {
+    myHandler: async (request: Request) => {
+      // Use ctx.db, ctx.schema, ctx.verifyToken
+      return new Response(JSON.stringify({ ok: true }));
+    },
+  };
+};
+```
+
+## Plugin vs Standalone Routes
+
+**Plugins:** Compose into a single Lambda handler. Share db connection pool and auth. Use for production.
+
+**Standalone Expo Router routes:** Each route is a separate file. Filesystem-based fallbacks for local dev. Use when plugins depend on AWS resources not available locally.
+
+## Gotchas
+
+- Plugin registration order matters for route matching
+- Plugins share the same database connection pool
+- Each plugin's handlers are merged into the route table
+- The API handler (PostgREST) should be the last plugin (catch-all)

package/src/resources/project-claude-md.md

@@ -0,0 +1,127 @@
+# {PROJECT_NAME}
+
+> {ONE_LINE_DESCRIPTION}
+
+## Start Here
+
+- `app/` — Expo Router pages (screens, navigation, API routes)
+- `server/` — Lambda handlers (api.ts, worker.ts, image.ts)
+- `db/` — Drizzle schema, migrations, seed data
+- `lib/` — Shared code (auth context, API client)
+- `sst.config.ts` — AWS infrastructure definition
+
+## Structure
+
+{ANNOTATED_DIRECTORY_TREE}
+
+## Commands
+
+```bash
+pnpm install                              # Install dependencies
+pnpm dev                                  # Start Expo dev server
+pnpm test                                 # Run all tests
+npx drizzle-kit generate                  # Generate migration from schema changes
+npx drizzle-kit migrate                   # Apply migrations locally
+pnpm sst deploy --stage dev               # Deploy to AWS
+everystack update --channel production    # OTA update (no redeploy)
+everystack db:migrate                     # Run migrations on deployed Lambda
+everystack db:seed                        # Seed database (dev only)
+everystack db:psql --stage dev            # Connect to database
+```
+
+## Key Principles
+
+### Always TypeScript
+
+Strict mode, no exceptions. Prefer `unknown` over `any`. Explicit return types on exported functions. Named exports only (no default exports).
+
+### Always TDD
+
+Every feature starts with a failing test.
+
+1. Write a failing test that describes expected behavior
+2. Implement the minimum code to make it pass
+3. Refactor while keeping tests green
+
+Tests live in `__tests__/` mirroring source structure, named `{feature}.test.ts`. Run from package dir: `npx jest __tests__/path/to/test.ts`
+
+### Platform Security Over All Else
+
+Three layers of defense. Each is a complete security boundary:
+
+1. **Edge (CloudFront)** — JWT signature + expiry check. Invalid tokens never reach Lambda.
+2. **Handler (Lambda)** — `SET LOCAL ROLE` via pgSettings, RPC role gates, rowOwnership, exposedTables.
+3. **Database (PostgreSQL)** — GRANTs + RLS policies. The single source of truth for authorization.
+
+Even if the handler has a bug, the database enforces access. Never skip RLS. Never connect as superuser in production.
+
+### Progressive Complexity
+
+Each tier builds on the previous. You never rip out what you have, you add to it.
+
+- **V1:** Static site. Expo + S3 + CloudFront + Lambda SSR + OTA updates. No database.
+- **V2:** Add PostgreSQL, PostgREST API, JWT auth, admin dashboard, logging.
+- **V3:** Add SQS workers, Sharp image processing, S3 file storage.
+
+### Web Standards
+
+Handler uses `Request`/`Response` interface. No Express, no Fastify. Works with Expo Router API routes, Cloudflare Workers, Deno, Bun, or any Web Standard runtime.
+
+### Schema-Agnostic
+
+The library knows nothing about your tables. You pass your Drizzle schema to `createHandler()`. Your schema, your migrations, your database — the library provides the protocol.
+
+## The Stack
+
+**App:**
+- TypeScript (strict mode)
+- Expo + expo-router (file-based routing)
+- React Native + react-native-web (cross-platform)
+- @mgcrea/react-native-tailwind (Tailwind CSS styling)
+
+**Data:**
+- drizzle-orm + drizzle-kit (schema, queries, migrations)
+- postgres (postgres.js driver)
+- PostgreSQL (database)
+
+**Infrastructure:**
+- SST (infrastructure as code)
+- AWS (S3, CloudFront, Lambda, RDS Aurora Serverless, SQS)
+
+**Dev Tooling:**
+- jest + ts-jest (testing)
+- esbuild (Lambda bundling)
+- pnpm (package management)
+
+## Conventions
+
+### Naming
+
+- Package scope: `@everystack/*`
+- Files: `kebab-case.ts`
+- Exports: named (no default exports)
+- Types: PascalCase, no `I` prefix
+- Functions: camelCase
+
+### Git
+
+- Conventional commits: `feat:`, `fix:`, `chore:`, `docs:`, `test:`, `refactor:`
+- Scope optional: `feat(handler):`, `fix(client):`
+- Tests must pass before commit
+
+### Code
+
+- TypeScript strict mode
+- Prefer `unknown` over `any`
+- Explicit return types on exported functions
+- Prefer pure functions over classes
+- Web Standard APIs (Request/Response)
+- Error handling at boundaries only
+
+### What NOT to Do
+
+- Don't put schema or migrations in the library — they belong to the app
+- Don't couple to Express/Fastify — use Request/Response
+- Don't skip tests to ship faster
+- Don't add features beyond what's tested
+- Don't require a database for V1 — the stack works without one

package/src/resources/query-protocol.md

@@ -0,0 +1,129 @@
+# Query Protocol
+
+> PostgREST-compatible HTTP query protocol used by the everystack handler.
+
+## When to Use
+Read this when building queries (client-side or debugging API calls). The handler converts these HTTP patterns into Drizzle ORM queries.
+
+## Filters
+
+Format: `?column=operator.value`
+
+| Operator | SQL | Example |
+|----------|-----|---------|
+| `eq` | `=` | `?id=eq.5` |
+| `neq` | `!=` | `?status=neq.deleted` |
+| `gt` | `>` | `?price=gt.100` |
+| `gte` | `>=` | `?age=gte.18` |
+| `lt` | `<` | `?price=lt.50` |
+| `lte` | `<=` | `?rating=lte.3` |
+| `like` | `LIKE` | `?title=like.*hiking*` (use `*` for wildcard) |
+| `ilike` | `ILIKE` | `?name=ilike.*john*` |
+| `is` | `IS NULL/NOT NULL` | `?deleted=is.null` or `?email=is.not.null` |
+| `in` | `IN (...)` | `?status=in.(draft,published)` |
+
+Multiple filters on the same request are ANDed: `?status=eq.published&authorId=eq.5`.
+
+Strict validation: unknown columns or operators return 400 (not silently ignored).
+
+## Negation
+
+Prefix any operator with `not.`:
+```
+?status=not.eq.draft          -> status != 'draft'
+?tags=not.in.(a,b)            -> tags NOT IN ('a', 'b')
+?deletedAt=not.is.null        -> deleted_at IS NOT NULL
+```
+
+## Logical Groups
+
+```
+?or=(status.eq.draft,status.eq.pending)
+-> WHERE status = 'draft' OR status = 'pending'
+
+?and=(price.gte.10,price.lte.100)
+-> WHERE price >= 10 AND price <= 100
+
+?category=eq.electronics&or=(status.eq.draft,status.eq.pending)
+-> WHERE category = 'electronics' AND (status = 'draft' OR status = 'pending')
+```
+
+Negation works inside groups: `?or=(category.not.eq.electronics,price.gt.100)`.
+
+## Column Selection
+
+```
+?select=id,title,body    -> Returns only { id, title, body }
+```
+
+## Relation Embedding
+
+```
+?select=*,author(*)               -> Each post includes { author: { ... } }
+?select=*,author(name,email)      -> Specific columns from relation
+?select=*,author(*),comments(*)   -> Multiple relations
+```
+
+Requires `relations` configured in handler options. Resolved via batched `WHERE IN` (not N+1).
+
+## Ordering
+
+```
+?order=created_at.desc
+?order=title.asc
+```
+
+## Pagination
+
+```
+?limit=10&offset=0     -> First page
+?limit=10&offset=10    -> Second page
+```
+
+Default limit: 1000. Max limit configurable via `maxLimit` option.
+
+## Exact Count
+
+Send `Prefer: count=exact` header to get total row count in `Content-Range`:
+```
+Content-Range: 0-9/42    (10 rows, 42 total)
+```
+
+## Aggregates
+
+```
+?select=count()                              -> SELECT count(*)
+?select=platform,total:amount.sum()          -> SELECT platform, sum(amount) AS total GROUP BY platform
+?select=count(distinct authorId)             -> SELECT count(DISTINCT author_id)
+```
+
+Supported: `count()`, `sum()`, `avg()`, `min()`, `max()`. Non-aggregate columns in select become GROUP BY columns. Alias syntax: `alias:column.function()`.
+
+## JSON Path Filtering
+
+```
+?metadata->>theme=eq.dark                    -> metadata->>'theme' = 'dark'
+?data->settings->>mode=eq.compact            -> data->'settings'->>'mode' = 'compact'
+```
+
+`->` returns JSON object (for nesting), `->>` returns text (for comparisons). Keys validated against `^[a-zA-Z_][a-zA-Z0-9_]*$`.
+
+## Mutations
+
+**POST** (insert): `POST /table` with JSON body. Returns created row, status 201.
+
+**PATCH** (update): `PATCH /table?filters` with JSON body. Returns updated rows, status 200.
+
+**DELETE**: `DELETE /table?filters`. Requires at least one filter (400 without). Returns deleted rows.
+
+**RPC**: `POST /rpc/name` with JSON body. Returns function result.
+
+## Content-Range Header
+
+Every GET response includes `Content-Range`:
+```
+0-9/*      10 rows, total unknown
+0-9/42     10 rows, 42 total (with Prefer: count=exact)
+*/*        no rows, total unknown
+*/0        no rows, 0 total
+```

package/src/resources/schema-patterns.md

@@ -0,0 +1,167 @@
+# Schema Design Patterns
+
+> Drizzle schema design, migrations, and RLS setup for everystack apps.
+
+## When to Use
+Read this when designing your database schema or adding tables to an existing app.
+
+## Schema Location
+
+Schemas live in `db/schema.ts` (or `db/schema/` directory for larger apps). This file is the single source of truth for both the handler and SSR.
+
+## Basic Table
+
+```typescript
+import { pgTable, serial, text, integer, timestamp, uuid } from 'drizzle-orm/pg-core';
+
+export const posts = pgTable('posts', {
+  id: uuid('id').defaultRandom().primaryKey(),
+  body: text('body').notNull(),
+  authorId: uuid('author_id').notNull().references(() => users.id),
+  status: text('status').default('draft').notNull(),
+  createdAt: timestamp('created_at').defaultNow().notNull(),
+  updatedAt: timestamp('updated_at').defaultNow().notNull(),
+  deletedAt: timestamp('deleted_at'),
+});
+```
+
+## Common Patterns
+
+### UUID vs Serial Primary Keys
+Prefer UUID for user-facing IDs (prevents enumeration attacks). Use serial for internal-only tables.
+
+```typescript
+id: uuid('id').defaultRandom().primaryKey(),  // Preferred for API-exposed tables
+id: serial('id').primaryKey(),                 // OK for internal tables
+```
+
+### Timestamps
+Always include `createdAt` and `updatedAt`:
+```typescript
+createdAt: timestamp('created_at').defaultNow().notNull(),
+updatedAt: timestamp('updated_at').defaultNow().notNull(),
+```
+
+### Soft Delete
+Add `deletedAt` for soft-deletable tables:
+```typescript
+deletedAt: timestamp('deleted_at'),
+```
+Configure in handler: `softDelete: { column: 'deletedAt', tables: ['posts'] }`.
+
+### Foreign Keys
+```typescript
+authorId: uuid('author_id').notNull().references(() => users.id),
+```
+
+### Enums
+```typescript
+import { pgEnum } from 'drizzle-orm/pg-core';
+
+export const roleEnum = pgEnum('role', ['user', 'admin']);
+
+export const users = pgTable('users', {
+  role: roleEnum('role').default('user').notNull(),
+});
+```
+
+## Relations (Drizzle)
+
+```typescript
+import { relations } from 'drizzle-orm';
+
+export const postsRelations = relations(posts, ({ one, many }) => ({
+  author: one(users, { fields: [posts.authorId], references: [users.id] }),
+  comments: many(comments),
+}));
+```
+
+Drizzle relations are used by the relational query API (`db.query.posts.findMany({ with: { author: true } })`). The handler also needs its own `relations` config for embedding.
+
+## Indexes
+
+```typescript
+import { index, uniqueIndex } from 'drizzle-orm/pg-core';
+
+export const posts = pgTable('posts', {
+  // columns...
+}, (table) => [
+  index('posts_author_id_idx').on(table.authorId),
+  uniqueIndex('posts_slug_idx').on(table.slug),
+]);
+```
+
+## Migration Workflow
+
+```bash
+# Generate migration from schema changes
+npx drizzle-kit generate
+
+# Apply migrations locally
+npx drizzle-kit migrate
+
+# Apply migrations on deployed Lambda
+everystack db:migrate
+```
+
+Migration files go in `drizzle/` directory. Each migration is a SQL file.
+
+### RLS Migration Template
+
+After creating tables, add a migration for roles and policies:
+
+```sql
+-- Create roles (idempotent)
+DO $$ BEGIN
+  IF NOT EXISTS (SELECT FROM pg_roles WHERE rolname = 'authenticator') THEN
+    CREATE ROLE authenticator LOGIN NOINHERIT;
+  END IF;
+  IF NOT EXISTS (SELECT FROM pg_roles WHERE rolname = 'anon') THEN
+    CREATE ROLE anon NOLOGIN;
+  END IF;
+  IF NOT EXISTS (SELECT FROM pg_roles WHERE rolname = 'authenticated') THEN
+    CREATE ROLE authenticated NOLOGIN;
+  END IF;
+  IF NOT EXISTS (SELECT FROM pg_roles WHERE rolname = 'admin') THEN
+    CREATE ROLE admin NOLOGIN;
+  END IF;
+END $$;
+
+GRANT anon TO authenticator;
+GRANT authenticated TO authenticator;
+GRANT admin TO authenticator;
+
+-- Table grants
+GRANT USAGE ON SCHEMA public TO anon, authenticated, admin;
+GRANT SELECT ON posts TO anon;
+GRANT SELECT, INSERT, UPDATE, DELETE ON posts TO authenticated;
+GRANT SELECT, INSERT, UPDATE, DELETE ON posts TO admin;
+
+-- Enable RLS
+ALTER TABLE posts ENABLE ROW LEVEL SECURITY;
+ALTER TABLE posts FORCE ROW LEVEL SECURITY;
+
+-- Policies (see everystack://security for templates)
+```
+
+## Handler Config for Schema
+
+```typescript
+createHandler(db, schema, {
+  exposedTables: ['posts', 'profiles'],  // Only these are API-accessible
+  hiddenColumns: { users: ['passwordHash', 'resetToken'] },
+  protectedFields: { profiles: ['role', 'deletedAt'] },
+  relations: {
+    posts: { author: { table: 'users', from: 'authorId', to: 'id' } },
+  },
+});
+```
+
+## Gotchas
+
+- Drizzle column names (camelCase) and SQL column names (snake_case) are both specified: `authorId: uuid('author_id')`
+- The handler's `relations` config uses Drizzle property names, not SQL column names
+- `exposedTables` uses Drizzle table variable names, not SQL table names
+- Always run `drizzle-kit generate` after schema changes
+- RLS migration must be run AFTER table creation migration
+- Connect as `authenticator` in production (never RDS master/superuser)

package/src/resources/security-device.md

@@ -0,0 +1,99 @@
+# Device Security
+
+> Device attestation and biometric auth. Import from `@everystack/security`.
+
+## When to Use
+Read this when adding hardware-backed security: device trust verification, biometric authentication, or certificate pinning.
+
+## Setup
+
+```typescript
+import { createSecurityHandler } from '@everystack/security';
+
+const security = createSecurityHandler({
+  apple: { teamId: '...', bundleId: '...' },
+  google: { packageName: '...' },
+});
+```
+
+## Device Attestation
+
+Verify that requests come from genuine devices (not emulators or modified apps).
+
+### Apple App Attest
+```typescript
+import { verifyAppleAttestation } from '@everystack/security';
+
+const result = await verifyAppleAttestation({
+  attestation: base64AttestationData,
+  challenge: serverChallenge,
+  teamId: 'TEAM_ID',
+  bundleId: 'com.example.app',
+});
+```
+
+### Google Play Integrity
+```typescript
+import { verifyPlayIntegrity } from '@everystack/security';
+
+const result = await verifyPlayIntegrity({
+  token: integrityToken,
+  packageName: 'com.example.app',
+});
+```
+
+## RS256 Device Keys
+
+Per-device RSA key pairs for request signing:
+
+```typescript
+import { generateDeviceKey, signRequest, verifySignature } from '@everystack/security/crypto';
+
+// Client: generate and store key pair
+const { publicKey, privateKey } = await generateDeviceKey();
+
+// Client: sign requests
+const signature = await signRequest(privateKey, requestBody);
+
+// Server: verify signature
+const valid = await verifySignature(publicKey, requestBody, signature);
+```
+
+## Auth Plugin Integration
+
+```typescript
+import { authPlugin } from '@everystack/auth/plugin';
+
+authPlugin({
+  device: {
+    verify: async (attestation, claims) => {
+      // Verify device attestation
+      return true; // or false to reject
+    },
+    require: 'always', // or 'optional'
+  },
+});
+```
+
+## Schema
+
+```typescript
+import { securitySchema } from '@everystack/security/schema';
+// Adds: device_attestations, device_keys tables
+```
+
+## Client SDK
+
+```typescript
+import { createSecurityClient } from '@everystack/security/client';
+
+const security = createSecurityClient({ baseUrl: '/api/security' });
+await security.registerDevice({ publicKey, attestation });
+```
+
+## Gotchas
+
+- Apple App Attest requires iOS 14+ and a real device (not simulator)
+- Google Play Integrity requires Google Play Services
+- Device keys should be stored in the device's secure enclave/keystore
+- Attestation verification should be done server-side only