@everystack/mcp 0.2.3 → 0.3.1

package/src/prompts/governance-setup.ts

@@ -0,0 +1,85 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+
+/**
+ * `governance_setup` — guide the agent to wire the everystack governance hooks
+ * into the project's `.claude/settings.json`. The server instructions tell the
+ * agent that enforcement runs via hooks; this prompt produces the exact block and
+ * the confirm-first procedure.
+ */
+export function registerGovernanceSetupPrompt(server: McpServer): void {
+  server.prompt(
+    'governance_setup',
+    'Install the everystack governance hooks (grounding gate + cheat gates) into .claude/settings.json. The MCP server alone does not enforce — the hooks are the teeth.',
+    {
+      projectPath: z.string().optional().describe('Absolute path to the project root'),
+      mode: z
+        .enum(['workspace', 'installed'])
+        .optional()
+        .describe('"workspace" (run from this monorepo via tsx) or "installed" (the published @everystack/mcp bin). Default: detect.'),
+    },
+    async ({ projectPath, mode }) => {
+      const cmd =
+        mode === 'workspace'
+          ? 'npx tsx packages/mcp/src/index.ts'
+          : mode === 'installed'
+            ? 'everystack-mcp'
+            : 'everystack-mcp';
+      const hooks = {
+        hooks: {
+          SessionStart: [{ hooks: [{ type: 'command', command: `${cmd} context` }] }],
+          PreToolUse: [{ matcher: '*', hooks: [{ type: 'command', command: `${cmd} gate` }] }],
+          PostToolUse: [
+            { matcher: 'Read', hooks: [{ type: 'command', command: `${cmd} mark` }] },
+            { matcher: 'Write|Edit', hooks: [{ type: 'command', command: `${cmd} validate` }] },
+          ],
+        },
+      };
+
+      return {
+        messages: [
+          {
+            role: 'user' as const,
+            content: {
+              type: 'text' as const,
+              text: [
+                `Install the everystack governance hooks for ${projectPath ? 'the project at ' + projectPath : 'this project'}.`,
+                '',
+                '## Why',
+                '',
+                'The everystack MCP server provides knowledge, but ENFORCEMENT (the grounding gate and',
+                'cheat gates) runs only when these Claude Code hooks are installed. Without them, nothing',
+                'catches off-script work (hand-written migrations, data bundled into the app, secrets behind',
+                'EXPO_PUBLIC_*).',
+                '',
+                '## Procedure (confirm-first — never silent)',
+                '',
+                '1. Read `docs/governance-setup.md` and `hooks.example.json` from the @everystack/mcp package.',
+                `2. Check whether ${projectPath ? projectPath + '/.claude/settings.json' : '.claude/settings.json'} already has these hooks (commands calling \`${cmd} gate\`).`,
+                '3. If absent, show the human the exact block below and confirm the command form before writing:',
+                '   - **Workspace (this monorepo):** `npx tsx packages/mcp/src/index.ts <sub>`',
+                '   - **Installed package:** `everystack-mcp <sub>` (install `@everystack/mcp`; in a hook prefer',
+                '     `pnpm exec everystack-mcp <sub>` over bare `npx`, which re-resolves on every tool call).',
+                '4. Merge the `hooks` block into `.claude/settings.json` (preserve any existing `hooks`/`permissions`).',
+                '5. Remind the human: hooks run a shell command on every tool call. This is a deliberate,',
+                '   security-relevant change — it is their call, not yours to make silently.',
+                '',
+                '## The block to merge',
+                '',
+                '```json',
+                JSON.stringify(hooks, null, 2),
+                '```',
+                '',
+                '## After install',
+                '',
+                '- A fresh session denies every non-Read tool until the project contract (CLAUDE.md + its',
+                '  REQUIRED-READS) is read. That is the grounding gate working.',
+                '- `everystack-mcp report` summarizes what the agent tried (the telemetry sensor).',
+              ].join('\n'),
+            },
+          },
+        ],
+      };
+    },
+  );
+}

package/src/prompts/index.ts

@@ -5,6 +5,9 @@ import { registerDesignSchemaPrompt } from './design-schema.js';
 import { registerDeployPrompt } from './deploy.js';
 import { registerDebugPrompt } from './debug.js';
 import { registerSecurePrompt } from './secure.js';
+import { registerGovernanceSetupPrompt } from './governance-setup.js';
+import { registerClaudeMdPrompt } from './claude-md.js';
+import { registerRunbookPrompt } from './runbook.js';
 
 export function registerPrompts(server: McpServer): void {
   registerNewAppPrompt(server);
@@ -13,4 +16,7 @@ export function registerPrompts(server: McpServer): void {
   registerDeployPrompt(server);
   registerDebugPrompt(server);
   registerSecurePrompt(server);
+  registerGovernanceSetupPrompt(server);
+  registerClaudeMdPrompt(server);
+  registerRunbookPrompt(server);
 }

package/src/prompts/new-app.ts

@@ -177,7 +177,10 @@ export function registerNewAppPrompt(server: McpServer): void {
                 ].join('\n') : '',
                 '',
                 '## Project Documentation',
-                'Read the everystack://project-claude-md resource and write a CLAUDE.md file to the project root.',
+                'Scaffold the project contract (use the claude_md prompt): read the everystack://project-claude-md',
+                'resource and write a CLAUDE.md to the project root. This file activates the grounding gate —',
+                'every later session must read it before editing — so it carries the non-negotiables the cheat',
+                'gates enforce. Keep it current as the project grows (claude_md reconciles it).',
                 `Replace {PROJECT_NAME} with "${effectiveName}", {ONE_LINE_DESCRIPTION} with "${description}",`,
                 'and {ANNOTATED_DIRECTORY_TREE} with the actual project structure created above.',
                 '',

package/src/prompts/runbook.ts

@@ -0,0 +1,77 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+
+/**
+ * `runbook` — generate or refresh docs/RUNBOOK.md, the per-app operations manual.
+ *
+ * The compiler lives in the CLI (`everystack runbook` — db:generate for docs:
+ * detection → sections keyed by the app's reality → es:gen/es:slot merge). This
+ * prompt is the thin agent layer on top: run the compiler, then fill the EMPTY
+ * slots with app-specific narrative the compiler cannot know. Generated blocks
+ * belong to the compiler — the agent never writes inside them.
+ */
+export function registerRunbookPrompt(server: McpServer): void {
+  server.prompt(
+    'runbook',
+    'Generate or refresh docs/RUNBOOK.md — the operations manual compiled from the app\'s detected reality (tier, Models, handlers). Runs `everystack runbook`, then fills empty slots with app narrative (confirm-first). Regenerate after the app grows or an everystack upgrade.',
+    {
+      projectPath: z.string().optional().describe('Absolute path to the project root (where docs/RUNBOOK.md lives)'),
+    },
+    async ({ projectPath }) => {
+      const root = projectPath ?? '.';
+      return {
+        messages: [
+          {
+            role: 'user' as const,
+            content: {
+              type: 'text' as const,
+              text: [
+                `Generate or refresh docs/RUNBOOK.md for the project at ${root}.`,
+                '',
+                '## What this is',
+                '',
+                'docs/RUNBOOK.md is the per-app operations manual — how to configure, extend, deploy,',
+                'monitor, and maintain THIS app. It is COMPILED, not authored: `everystack runbook`',
+                'derives it from the app\'s detected reality (installed packages → tier, Models,',
+                'handlers, crons) and regenerating after a change diffs in what\'s new. The division',
+                'of labor: CLAUDE.md is the terse contract (rules); the runbook is procedures.',
+                '',
+                '## Step 1 — run the compiler',
+                '',
+                `- If ${root}/docs/RUNBOOK.md exists, run \`everystack runbook --diff\` first and show`,
+                '  the human which sections would change.',
+                '- Then run `everystack runbook` to write it. If it reports hand-edited generated',
+                '  sections (a conflict), do NOT reach for --force — help the human move those words',
+                '  into a slot or the Notes section first, then regenerate. --force only with their',
+                '  explicit ok.',
+                '',
+                '## Step 2 — fill the EMPTY slots (and only the slots)',
+                '',
+                'The document has two kinds of content, mechanically marked:',
+                '- `<!-- es:gen section=... -->` blocks belong to the compiler. NEVER write inside one —',
+                '  your words would be overwritten on the next regeneration, and the hash check flags it.',
+                '- `<!-- es:slot name=... -->` blocks are the human/agent seam and survive every',
+                '  regeneration. A slot still holding its `_(Fill in: ...)_` placeholder is empty.',
+                '',
+                'For each empty slot, draft content from what you know of the project:',
+                '- `overview` — what the app is, who it serves, what an operator should know first.',
+                '- `stage-notes` — deployed URLs per stage, channel-to-stage mapping, release cadence',
+                '  (read `.sst/outputs.json` or ask; do not guess URLs).',
+                '- `notes` — anything project-specific that fits nowhere else. Leave it if nothing real.',
+                '',
+                'Show the human your draft slot content and let them approve before writing — the',
+                'runbook is theirs; you assist, you do not own it.',
+                '',
+                '## Step 3 — verify',
+                '',
+                'Run `everystack runbook --check`: it must exit clean (slot edits never make it stale).',
+                'Tell the human: regenerate any time with `everystack runbook`; CI can enforce currency',
+                'with `--check`; after an everystack upgrade the diff reads as release notes for this app.',
+              ].join('\n'),
+            },
+          },
+        ],
+      };
+    },
+  );
+}

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

@@ -2,13 +2,43 @@
 
 > {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/` — Drizzle schema, migrations, seed data
-- `lib/` — Shared code (auth context, API client)
+- `db/` — generated Drizzle schema + migrations (do not edit by hand)
+- `lib/` — shared code (auth context, API client)
 - `sst.config.ts` — AWS infrastructure definition
+- `docs/RUNBOOK.md` — how to operate this app; regenerate with `everystack runbook`
 
 ## Structure
 
@@ -17,111 +47,57 @@
 ## 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
+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
 
-### 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.
+### Models are the source of truth (v3)
 
-### Progressive Complexity
+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.
 
-Each tier builds on the previous. You never rip out what you have, you add to it.
+### Security over all else
 
-- **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.
+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.
 
-### Web Standards
+### Progressive complexity
 
-Handler uses `Request`/`Response` interface. No Express, no Fastify. Works with Expo Router API routes, Cloudflare Workers, Deno, Bun, or any Web Standard runtime.
+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.
 
-### Schema-Agnostic
+### Test-driven
 
-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)
+Every feature starts with a failing test. Tests in `__tests__/` mirroring source.
 
 ## 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
+- 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
+## 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
+- 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/src/tools/index.ts

@@ -1,10 +1,13 @@
 import { z } from 'zod';
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { analyzeProjectStatus } from './project-status.js';
-import { analyzeSchema } from './schema-analyze.js';
-import { validateProject } from './project-validate.js';
 import { checkEnvironment } from './check-environment.js';
 
+// NOTE (Brick 0): the legacy regex tools — project_status, schema_analyze,
+// project_validate — are intentionally NOT registered. They predate the v3
+// Model/Module surface and return wrong answers on Model-based apps (e.g. they
+// report a securely-derived handler config as "all tables accessible"). They are
+// rebuilt on @everystack/model in Brick 1 and re-registered there. Their source
+// files remain for that rewrite to reference.
 export function registerTools(server: McpServer): void {
   server.tool(
     'check_environment',
@@ -19,40 +22,4 @@ export function registerTools(server: McpServer): void {
       };
     },
   );
-
-  server.tool(
-    'project_status',
-    'Detect the everystack tier (V1/V2/V3), installed packages, project structure, and deployment state. Run this first to understand the user\'s project.',
-    { projectPath: z.string().describe('Absolute path to the project root (directory containing package.json)') },
-    async ({ projectPath }) => {
-      const status = analyzeProjectStatus(projectPath);
-      return {
-        content: [{ type: 'text' as const, text: JSON.stringify(status, null, 2) }],
-      };
-    },
-  );
-
-  server.tool(
-    'schema_analyze',
-    'Parse Drizzle schema files and cross-reference with handler configuration. Shows tables, columns, relations, and detects misconfigurations.',
-    { projectPath: z.string().describe('Absolute path to the project root (directory containing package.json)') },
-    async ({ projectPath }) => {
-      const analysis = analyzeSchema(projectPath);
-      return {
-        content: [{ type: 'text' as const, text: JSON.stringify(analysis, null, 2) }],
-      };
-    },
-  );
-
-  server.tool(
-    'project_validate',
-    'Check for common mistakes, security gaps, and convention violations. Returns errors (must fix), warnings (should fix), and info (nice to fix).',
-    { projectPath: z.string().describe('Absolute path to the project root (directory containing package.json)') },
-    async ({ projectPath }) => {
-      const report = validateProject(projectPath);
-      return {
-        content: [{ type: 'text' as const, text: JSON.stringify(report, null, 2) }],
-      };
-    },
-  );
 }