@everystack/mcp 0.2.2 → 0.3.0

package/dist/jobs.md

@@ -0,0 +1,97 @@
+# Background Jobs
+
+> SQS background workers for everystack apps. Import from `@everystack/jobs`.
+
+## When to Use
+Read this when adding background processing (V3): email sending, image processing, analytics aggregation, etc.
+
+## Setup
+
+### Infrastructure
+```typescript
+// sst.config.ts
+const dlq = new sst.aws.Queue('DeadLetterQueue');
+const jobs = new sst.aws.Queue('Jobs', { dlq: dlq.arn });
+
+const worker = new sst.aws.Function('Worker', {
+  handler: 'server/worker.handler',
+  link: [database, jobs, media],
+  vpc,
+});
+
+jobs.subscribe(worker.arn);
+```
+
+### Worker Handler
+```typescript
+// server/worker.ts
+import { createWorkerHandler } from '@everystack/server/worker';
+
+export const handler = createWorkerHandler(async () => ({
+  'image:process': async (payload) => {
+    // payload: { imageId, variants: ['thumb', 'large'] }
+  },
+  'email:send': async (payload) => {
+    // payload: { to, subject, body }
+  },
+  'analytics:aggregate': async (payload) => {
+    // payload: { date, metrics: ['pageviews', 'signups'] }
+  },
+}));
+```
+
+### Dispatching Jobs
+```typescript
+import { publishJob } from '@everystack/jobs';
+
+await publishJob('image:process', {
+  imageId: 'abc-123',
+  variants: ['thumb', 'large'],
+});
+```
+
+## Client SDK
+
+```typescript
+import { createJobClient } from '@everystack/jobs/client';
+
+const jobs = createJobClient({ baseUrl: '/api' });
+await jobs.submit('email:send', { to: 'user@example.com', subject: 'Welcome' });
+```
+
+## SQS Adapter
+
+```typescript
+import { createSqsAdapter } from '@everystack/jobs';
+
+const adapter = createSqsAdapter({
+  queueUrl: Resource.Jobs.url,
+  region: 'us-east-1',
+});
+```
+
+Progressive dispatch: starts with direct function calls, moves to SQS when you need async processing.
+
+## Postgres Materialization
+
+Optional: materialize job state to PostgreSQL for dashboard visibility:
+
+```typescript
+import { jobsSchema } from '@everystack/jobs/schema';
+// Adds: jobs table with status, type, payload, result, timestamps
+```
+
+## Plugin
+
+```typescript
+import { jobsPlugin } from '@everystack/jobs/plugin';
+// Adds job dispatch routes to the handler
+```
+
+## Gotchas
+
+- Workers run in a separate Lambda (not the API Lambda)
+- Dead letter queue catches failed jobs after max retries
+- Job payloads must be JSON-serializable
+- SQS has a 256KB message size limit
+- Workers should be idempotent (SQS delivers at-least-once)

package/dist/logging.md

@@ -0,0 +1,91 @@
+# Logging & Analytics
+
+> Structured logging, crash reports, and analytics. Import from `@everystack/logging`.
+
+## When to Use
+Read this when adding observability to a V2+ app.
+
+## Setup
+
+### Server-side Logging
+```typescript
+import { createLogSink } from '@everystack/logging';
+
+const logSink = createLogSink({
+  storage: 's3',
+  bucket: Resource.LogsBucket.name,
+});
+
+// Pass to Lambda handler
+createLambdaHandler({ logSink, /* ... */ });
+```
+
+### Client-side SDK
+```typescript
+import { createLogClient } from '@everystack/logging/client';
+
+const logger = createLogClient({
+  baseUrl: '/api/logs',
+  batchSize: 10,
+  flushInterval: 30000,
+});
+
+logger.info('Page viewed', { page: '/home' });
+logger.error('Payment failed', { error, userId });
+logger.event('button_click', { button: 'signup' });
+```
+
+## Log Levels
+
+| Level | Use case |
+|-------|----------|
+| `debug` | Development-only, verbose details |
+| `info` | Normal operations, user actions |
+| `warn` | Degraded state, retries, fallbacks |
+| `error` | Failed operations, caught exceptions |
+| `fatal` | Unrecoverable errors, crash reports |
+
+## Schema
+
+```typescript
+import { loggingSchema } from '@everystack/logging/schema';
+// Adds: logs table with level, source, message, data, traceId, userId, deviceId, etc.
+```
+
+Include in your handler's schema for database-backed log querying.
+
+## CloudWatch Trigger
+
+```typescript
+import { createLogIngestionHandler } from '@everystack/logging/trigger';
+// Processes CloudWatch log events, extracts structured data, stores in S3/DB
+```
+
+## Admin Integration
+
+```typescript
+import { loggingAdminConfig } from '@everystack/logging/admin';
+// Adds log viewer widget to admin dashboard
+```
+
+## CLI Integration
+
+```bash
+everystack logs:errors --stage dev          # Recent errors (DB -> S3 fallback)
+everystack logs:query --stage dev --level error --source api
+everystack logs:tail --stage dev            # Raw CloudWatch output
+```
+
+## Plugin
+
+```typescript
+import { loggingPlugin } from '@everystack/logging/plugin';
+// Adds log ingestion routes and log query RPC
+```
+
+## Gotchas
+
+- Logs are stored in S3 (cheap, durable) with optional DB materialization
+- Client SDK batches logs and flushes periodically (not per-event)
+- `logs:errors` queries DB first, falls back to S3 if logs table doesn't exist
+- `logs:tail` reads CloudWatch (Lambda container output), not application logs

package/dist/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/dist/project-claude-md.md

@@ -0,0 +1,102 @@
+# {PROJECT_NAME}
+
+> {ONE_LINE_DESCRIPTION}
+
+This file is the contract for how this project is built. Read it before writing code; it
+overrides convenience. When a rule is hard to follow, that is the signal you are about to
+introduce drift — stop and do it the right way.
+
+<!--
+  REQUIRED-READS: (optional) a comma-separated list of companion files that must also be
+  read before non-Read tools, e.g. `REQUIRED-READS: docs/architecture.md, db/SCHEMA.md`.
+  This CLAUDE.md is required automatically — add the line only if real companion docs exist.
+-->
+
+## Non-negotiables
+
+These are enforced (everystack cheat gates) and load-bearing. Do not work around them.
+
+- **Data lives in PostgreSQL, served through the API — never bundle data into the app.** A
+  large `.json`/`.csv` of computed data in the bundle is wrong; model it and serve it, or
+  render an empty state if it does not exist yet.
+- **Schema and migrations are generated from Models.** Declare tables with `defineModel`
+  (in `models/`), run `everystack db:generate`. Never hand-write a SQL migration, never edit
+  the generated `db/schema.ts`. After any change, `db:generate` must be a clean no-op.
+- **Authorization is declared, not hand-written.** Use `can()` abilities on the Model; they
+  compile to RLS + grants. Never hand-write `CREATE POLICY`/`GRANT`. RLS is required.
+- **Reuse `@everystack/ui`.** Do not hand-roll a component that already exists there. Style
+  with classNames (light + dark), not inline `StyleSheet`.
+- **Secrets stay server-side.** Never put a DB URL, key, or token behind an `EXPO_PUBLIC_*`
+  name — those are compiled into the client bundle forever. Use `everystack secrets`.
+- **Apps stay thin.** Screens wire routing and UI; reusable logic lives in packages/`lib`.
+
+## Start Here
+
+- `models/` — `defineModel` tables (the source of truth for schema + authz)
+- `app/` — Expo Router pages (screens, navigation, API routes)
+- `server/` — Lambda handlers (api.ts, worker.ts, image.ts)
+- `db/` — generated Drizzle schema + migrations (do not edit by hand)
+- `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 the Expo dev server
+pnpm test                                    # Run all tests (TDD)
+everystack db:generate                       # Models → next migration (data + authz)
+everystack db:migrate                        # Apply migrations on the deployed Lambda
+everystack db:seed                           # Seed the database (dev only)
+everystack deploy --stage dev                # Deploy infrastructure (SST)
+everystack update --channel production        # OTA update (no redeploy)
+everystack secrets set KEY "value" --stage dev   # Set a server-side secret
+everystack bundle:audit <url>                # Audit a deployed bundle (weight + leaks)
+```
+
+## Key Principles
+
+### Models are the source of truth (v3)
+
+Declare tables with `defineModel` (`field`, `can`, relations). A package's full DB slice is a
+`defineModule`; the app composes Modules. `everystack db:generate` compiles them to one
+migration (schema + RLS + grants); `deriveHandlerConfig(models)` derives the API config. You
+never hand-write migrations, RLS, or handler access-control — they are derived, so they cannot
+drift.
+
+### Security over all else
+
+Three layers, each a complete boundary: edge (CloudFront JWT check), handler (pgSettings role +
+ownership), and database (GRANTs + RLS — the source of truth). Even if the handler has a bug,
+the database enforces access. Never skip RLS. Never connect as superuser in production.
+
+### Progressive complexity
+
+Each tier adds to the previous; you never rip out what you have.
+- **V1:** Static. Expo + S3 + CloudFront + Lambda SSR + OTA. No database.
+- **V2:** Add PostgreSQL, the API, JWT auth, admin, logging.
+- **V3:** Add SQS workers, image processing, S3 file storage.
+
+### Test-driven
+
+Every feature starts with a failing test. Tests in `__tests__/` mirroring source.
+
+## Conventions
+
+- Package scope `@everystack/*`; files `kebab-case.ts`; named exports (no defaults); types
+  PascalCase (no `I` prefix); functions camelCase; DB columns `snake_case`.
+- TypeScript strict; prefer `unknown` over `any`; explicit return types on exports.
+- Conventional commits (`feat:`, `fix:`, `chore:`, `docs:`); tests pass before commit.
+
+## What NOT to Do
+
+- Don't bundle large data into the app — it lives in the DB, served by the API.
+- Don't hand-write migrations or edit `db/schema.ts` — edit the Model, run `db:generate`.
+- Don't hand-write RLS — declare `can()` abilities.
+- Don't hand-roll a component that exists in `@everystack/ui`; don't use inline `StyleSheet`.
+- Don't put a secret behind `EXPO_PUBLIC_*` — that ships to the client.
+- Don't skip RLS, skip tests, or build features beyond what's tested.

package/dist/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/dist/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)