@everystack/mcp 0.2.2 → 0.3.0

package/README.md

@@ -1,6 +1,13 @@
 # @everystack/mcp
 
-MCP server that makes Claude an everystack expert. Provides architecture knowledge, project introspection tools, and guided workflow prompts so Claude can help build apps from V1 (static) to V3 (full platform).
+The governance layer that governs how any agent builds everystack. Beyond architecture knowledge
+and guided prompts, it keeps the build **on-script**: a **grounding gate** (read the project
+contract before editing) and **cheat gates** (block the training-consensus shortcuts — bundling
+data instead of using the DB, hand-writing migrations, leaking a secret into the client bundle),
+with **telemetry** that records what the agent tried. The teeth run as Claude Code hooks; the same
+logic is importable so the operator CLI can self-gate at deploy.
+
+**Governance setup (hooks + telemetry): [docs/governance-setup.md](docs/governance-setup.md).**
 
 ## Setup
 
@@ -59,15 +66,28 @@ Claude reads these to understand everystack architecture and conventions.
 - `everystack://events` — Real-time events via LISTEN/NOTIFY + WebSocket
 - `everystack://cli` — CLI command reference
 
-### Tools (Project Introspection)
+### Governance (hooks)
+
+The teeth. Run as Claude Code hooks via the `everystack-mcp` bin — see
+[docs/governance-setup.md](docs/governance-setup.md).
 
-Read-only tools that analyze your project and return structured data.
+| Subcommand | Hook | Role |
+|------------|------|------|
+| `context` | SessionStart | inject the contract to read |
+| `gate` | PreToolUse | block until grounded; block cheat gates |
+| `mark` | PostToolUse(Read) | record a contract read |
+| `validate` | PostToolUse(Write\|Edit) | surface a cheat the write landed |
+| `report` | — | summarize the per-session telemetry |
+
+### Tools (Project Introspection)
 
 | Tool | Purpose |
 |------|---------|
-| `project_status` | Detect tier (V1/V2/V3), installed packages, project structure, deployment state |
-| `schema_analyze` | Parse Drizzle schema, cross-reference handler config, detect misconfigurations |
-| `project_validate` | Check for security gaps, missing dependencies, convention violations |
+| `check_environment` | Verify dev/deploy prerequisites (Node, pnpm, git, Expo, SST, AWS CLI, PostgreSQL) |
+
+> The legacy regex tools (`project_status`, `schema_analyze`, `project_validate`) were removed:
+> they predated the v3 Model/Module surface and returned wrong answers on Model-based apps. They are
+> being rebuilt on `@everystack/model` (the pure compiler) so introspection matches reality.
 
 ### Prompts (Guided Workflows)
 
@@ -84,17 +104,32 @@ Structured prompts that guide Claude through multi-step tasks.
 
 ## Design
 
-**Standalone.** Zero everystack peer dependencies. Only depends on `@modelcontextprotocol/sdk` and `zod`. Works even when the project is broken or partially set up.
+**Framework-aware.** Depends on `@everystack/model` and `@everystack/cli` (plus
+`@modelcontextprotocol/sdk` and `zod`). An enforcement layer must track the framework version — it
+cannot float free of it. The cheat detectors reuse the CLI's shipped scanners (e.g. the canonical
+secret-shape patterns from `@everystack/cli/audit`) rather than duplicating them, loaded lazily so
+the common tool call stays fast.
 
-**Local-only.** Runs via stdio transport. No network access, no AWS calls. The everystack CLI handles remote infrastructure — the MCP teaches Claude how to use it.
+**Local-only.** No network, no AWS. The grounding gate and cheat gates observe tool-call metadata
+and the proposed file content; they never write files themselves. Telemetry is a local JSONL under
+`~/.everystack/governance`.
 
-**Read-only tools.** Tools read files and return structured data. Claude does the reasoning. No file writes, no imports from other packages.
+**Fail-open.** A governance bug never bricks tool use — only the explicit "ungrounded" and "cheat
+detected" conditions fail closed.
 
 **Curated resources.** The markdown files are optimized for Claude consumption — organized by task, not by package. Each follows a consistent structure: When to Use, Setup, API Reference, Common Patterns, Gotchas.
 
 ## Development
 
 ```bash
-pnpm --filter @everystack/mcp test     # Run tests (58 passing)
+pnpm --filter @everystack/mcp test     # Run tests (206 passing)
 pnpm --filter @everystack/mcp lint     # Type check
 ```
+
+## License
+
+[AGPL-3.0-only](https://www.gnu.org/licenses/agpl-3.0.html) © Scalable Technology, Inc.
+
+A commercial license is available for organizations that cannot or do not wish to
+comply with the AGPL-3.0 terms. For commercial licensing, contact
+licensing@scalable.technology.

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