@everystack/mcp 0.3.2 → 0.4.0

package/dist/schema-patterns.md

@@ -1,167 +1,153 @@
 # Schema Design Patterns
 
-> Drizzle schema design, migrations, and RLS setup for everystack apps.
+> Declaring TABLES with `defineModel` in `db/models/` — fields, authz, relations, indexes.
 
 ## When to Use
-Read this when designing your database schema or adding tables to an existing app.
+Read this when designing your database schema or adding tables to an existing app. This
+resource covers **tables** (`defineModel`). For the derived layer —
+views, materialized views, functions, triggers, standalone sequences — read
+`everystack://derived-objects` (they deploy via `db:reconcile`, not migrations). For the
+operational verbs that move a database (`db:sync`, `db:generate`, `db:plan`/`db:apply`,
+`db:check`), read `everystack://database-operations`.
 
 ## 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.
+The whole declared database lives in `db/models/` — one `defineModel` per table, composed
+onto a `defineModule`. This is the single source of truth for the handler, SSR, RLS, and
+grants. You do **not** hand-write `db/schema.ts`, and you do **not** run
+`drizzle-kit generate`/`drizzle-kit migrate` — the Model is authored, and everystack
+generates the migration (`db:generate`) and the typed artifact (`db/schema.generated.ts`,
+never edited). Never hand-write a SQL migration.
 
 ## 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'),
+import { defineModel, field, can } from '@everystack/model';
+
+export const Post = defineModel('posts', {
+  fields: {
+    id: field.uuid().primaryKey().defaultRandom(),
+    body: field.text().notNull(),
+    authorId: field.uuid().notNull().references('users', 'id'),
+    status: field.text().notNull().default('draft'),
+    createdAt: field.timestamptz().notNull().defaultNow(),
+    updatedAt: field.timestamptz().notNull().defaultNow(),
+    deletedAt: field.timestamptz(),
+  },
+  abilities: [can('read'), can('create'), can('update'), can('delete')],
 });
 ```
 
+Column names are `snake_case` in the database; the field key is the app-side name — the
+generator maps `authorId` → `author_id` for you.
+
 ## 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
+id: field.uuid().primaryKey().defaultRandom(),  // Preferred for API-exposed tables
+id: field.serial().primaryKey(),                 // OK for internal tables
 ```
 
 ### Timestamps
 Always include `createdAt` and `updatedAt`:
 ```typescript
-createdAt: timestamp('created_at').defaultNow().notNull(),
-updatedAt: timestamp('updated_at').defaultNow().notNull(),
+createdAt: field.timestamptz().notNull().defaultNow(),
+updatedAt: field.timestamptz().notNull().defaultNow(),
 ```
 
 ### Soft Delete
 Add `deletedAt` for soft-deletable tables:
 ```typescript
-deletedAt: timestamp('deleted_at'),
+deletedAt: field.timestamptz(),
 ```
 Configure in handler: `softDelete: { column: 'deletedAt', tables: ['posts'] }`.
 
 ### Foreign Keys
 ```typescript
-authorId: uuid('author_id').notNull().references(() => users.id),
+authorId: field.uuid().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(),
-});
+role: field.enum('role', ['user', 'admin']).notNull().default('user'),
 ```
 
-## Relations (Drizzle)
+## Relations
 
-```typescript
-import { relations } from 'drizzle-orm';
+Declare relations on the Model — the generator emits both the Drizzle relations (used by
+the relational query API, `db.query.posts.findMany({ with: { author: true } })`) and the
+handler's embedding config, so they can't drift apart.
 
-export const postsRelations = relations(posts, ({ one, many }) => ({
-  author: one(users, { fields: [posts.authorId], references: [users.id] }),
-  comments: many(comments),
-}));
+```typescript
+export const Post = defineModel('posts', {
+  fields: { /* … */ },
+  relations: {
+    author: { model: 'users', from: 'authorId', to: 'id' },
+    comments: { model: 'comments', from: 'id', to: 'postId', many: true },
+  },
+  abilities: [can('read')],
+});
 ```
 
-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),
-]);
+import { defineModel, field, can, index } from '@everystack/model';
+
+export const Post = defineModel('posts', {
+  fields: { /* … */ },
+  indexes: [
+    index(['authorId']),
+    index(['slug']).unique(),
+  ],
+  abilities: [can('read')],
+});
 ```
 
-## Migration Workflow
-
-```bash
-# Generate migration from schema changes
-npx drizzle-kit generate
-
-# Apply migrations locally
-npx drizzle-kit migrate
+## Authorization is declared, not migrated
 
-# Apply migrations on deployed Lambda
-everystack db:migrate
-```
+You never hand-write `CREATE ROLE`, `GRANT`, or `CREATE POLICY`. Abilities on the Model
+compile to grants + RLS, and `db:sync`/`db:apply` deploy them. `can('read')` grants `anon`
++ `authenticated`; `can('read', { role: 'admin' })` narrows to a role. RLS is required —
+the CI gate (`db:check`) refuses a table without it. See `everystack://security` for the
+policy patterns the abilities compile to.
 
-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)
+```typescript
+export const Post = defineModel('posts', {
+  fields: { /* … */ },
+  abilities: [
+    can('read'),                              // anon + authenticated
+    can('create', { role: 'authenticated' }),
+    can('update', { role: 'authenticated', own: 'authorId' }),  // row ownership
+    can('delete', { role: 'admin' }),
+  ],
+});
 ```
 
 ## Handler Config for Schema
 
+The handler config is **derived** from the Models (`deriveHandlerConfig(models)`), so
+`exposedTables`, `hiddenColumns`, `protectedFields`, and `relations` come from the
+declarations rather than a hand-kept parallel list:
+
 ```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' } },
-  },
-});
+import { deriveHandlerConfig } from '@everystack/model';
+import { models } from '../db/models';
+
+createHandler(db, schema, deriveHandlerConfig(models));
 ```
 
 ## 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)
+- Field keys are app-side names (camelCase); the database column is `snake_case` — the
+  generator maps `authorId` → `author_id`.
+- Edit the Model, then move the database with `db:sync` (dev) or `db:generate` +
+  `db:plan`/`db:apply` (protected stages). Never run `drizzle-kit generate`.
+- RLS and grants are declared with `can()`, never hand-written; `db:check` fails a table
+  without RLS.
+- `db/schema.generated.ts` is a generated artifact — never edit it; `db:check` refuses
+  drift.
+- Connect as `authenticator` in production (never RDS master/superuser).

package/dist/tools/check-environment.d.ts

@@ -0,0 +1,25 @@
+export type EnvironmentPhase = 'local' | 'deploy';
+export interface PrerequisiteCheck {
+    name: string;
+    required: boolean;
+    status: 'found' | 'not_found';
+    version: string | null;
+    installHint: string;
+    tier: 'V1' | 'V2';
+    phase: 'local' | 'deploy';
+    description: string;
+    whyNeeded: string;
+    installCommands: string[];
+    serviceRunning?: boolean;
+}
+export interface EnvironmentReport {
+    phase: EnvironmentPhase;
+    prerequisites: PrerequisiteCheck[];
+    ready: boolean;
+    readyForTier: 'V1' | 'V2' | 'V3' | 'none';
+    suggestions: string[];
+    platform: 'macOS' | 'linux' | 'windows' | 'unknown';
+    nextSteps: string[];
+}
+export declare function checkEnvironment(phase?: EnvironmentPhase): EnvironmentReport;
+//# sourceMappingURL=check-environment.d.ts.map

package/dist/tools/check-environment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-environment.d.ts","sourceRoot":"","sources":["../../src/tools/check-environment.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,QAAQ,CAAC;AAElD,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,OAAO,GAAG,WAAW,CAAC;IAC9B,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,IAAI,GAAG,IAAI,CAAC;IAClB,KAAK,EAAE,OAAO,GAAG,QAAQ,CAAC;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,gBAAgB,CAAC;IACxB,aAAa,EAAE,iBAAiB,EAAE,CAAC;IACnC,KAAK,EAAE,OAAO,CAAC;IACf,YAAY,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,MAAM,CAAC;IAC1C,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,QAAQ,EAAE,OAAO,GAAG,OAAO,GAAG,SAAS,GAAG,SAAS,CAAC;IACpD,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAiCD,wBAAgB,gBAAgB,CAAC,KAAK,GAAE,gBAA0B,GAAG,iBAAiB,CAgQrF"}

package/dist/tools/check-environment.js

@@ -0,0 +1,281 @@
+import { execSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+function detectPlatform() {
+    const p = process.platform;
+    if (p === 'darwin')
+        return 'macOS';
+    if (p === 'linux')
+        return 'linux';
+    if (p === 'win32')
+        return 'windows';
+    return 'unknown';
+}
+function tryExec(cmd, timeout = 10000) {
+    try {
+        return execSync(cmd, { timeout, stdio: 'pipe', encoding: 'utf-8' }).trim();
+    }
+    catch {
+        return null;
+    }
+}
+function parseVersion(output, pattern) {
+    if (!output)
+        return null;
+    if (pattern) {
+        const match = output.match(pattern);
+        return match?.[1] ?? null;
+    }
+    return output.replace(/^v/, '');
+}
+function meetsMinVersion(version, major) {
+    if (!version)
+        return false;
+    const parsed = parseInt(version.split('.')[0], 10);
+    return !isNaN(parsed) && parsed >= major;
+}
+export function checkEnvironment(phase = 'local') {
+    const prerequisites = [];
+    const suggestions = [];
+    const platform = detectPlatform();
+    const isLocal = phase === 'local';
+    // Node.js
+    const nodeOutput = tryExec('node --version');
+    const nodeVersion = parseVersion(nodeOutput);
+    const nodeOk = meetsMinVersion(nodeVersion, 20);
+    prerequisites.push({
+        name: 'node',
+        required: true,
+        status: nodeVersion ? 'found' : 'not_found',
+        version: nodeVersion,
+        installHint: 'Install Node.js 20+ from https://nodejs.org',
+        tier: 'V1',
+        phase: 'local',
+        description: 'Node.js runs your code. Your app is written in TypeScript, and Node.js is the engine that executes it.',
+        whyNeeded: 'Without Node.js, none of the code can run.',
+        installCommands: platform === 'macOS'
+            ? ['brew install node', 'Or download from https://nodejs.org']
+            : platform === 'linux'
+                ? ['sudo apt install nodejs npm', 'Or download from https://nodejs.org']
+                : ['Download and install from https://nodejs.org'],
+    });
+    if (!nodeVersion) {
+        suggestions.push('Node.js is not installed. Install Node.js 20+ from https://nodejs.org');
+    }
+    else if (!nodeOk) {
+        suggestions.push(`Node.js ${nodeVersion} is installed but version 20+ is required. Upgrade at https://nodejs.org`);
+    }
+    // pnpm (recommended, not required)
+    const pnpmOutput = tryExec('pnpm --version');
+    const pnpmVersion = parseVersion(pnpmOutput);
+    prerequisites.push({
+        name: 'pnpm',
+        required: false,
+        status: pnpmVersion ? 'found' : 'not_found',
+        version: pnpmVersion,
+        installHint: 'Install pnpm: npm install -g pnpm (recommended for monorepos)',
+        tier: 'V1',
+        phase: 'local',
+        description: 'A faster way to install code libraries your app depends on. Recommended but not required.',
+        whyNeeded: 'Makes installing dependencies faster and more reliable.',
+        installCommands: ['npm install -g pnpm'],
+    });
+    if (!pnpmVersion) {
+        suggestions.push('pnpm is not installed. Recommended for monorepos: npm install -g pnpm');
+    }
+    // git
+    const gitOutput = tryExec('git --version');
+    const gitVersion = parseVersion(gitOutput, /git version (\d+\.\d+\.\d+)/);
+    prerequisites.push({
+        name: 'git',
+        required: true,
+        status: gitVersion ? 'found' : 'not_found',
+        version: gitVersion,
+        installHint: 'Install git from https://git-scm.com',
+        tier: 'V1',
+        phase: 'local',
+        description: 'Tracks every change to your code. Like an unlimited undo button for your entire project.',
+        whyNeeded: 'Without git, you cannot track changes, undo mistakes, or collaborate.',
+        installCommands: platform === 'macOS'
+            ? ['xcode-select --install']
+            : platform === 'linux'
+                ? ['sudo apt install git']
+                : ['Download from https://git-scm.com'],
+    });
+    if (!gitVersion) {
+        suggestions.push('git is not installed. Install from https://git-scm.com');
+    }
+    // Expo CLI
+    const expoOutput = tryExec('npx expo --version');
+    const expoVersion = parseVersion(expoOutput);
+    prerequisites.push({
+        name: 'expo',
+        required: true,
+        status: expoVersion ? 'found' : 'not_found',
+        version: expoVersion,
+        installHint: 'Expo is available via npx. Ensure Node.js is installed, then run: npx create-expo-app',
+        tier: 'V1',
+        phase: 'local',
+        description: 'The framework that makes your app work on phones, tablets, and the web from the same code.',
+        whyNeeded: 'Without Expo, you cannot create or run the app.',
+        installCommands: ['Runs via npx (no separate install needed). Requires Node.js.'],
+    });
+    if (!expoVersion) {
+        suggestions.push('Expo CLI not available. Ensure Node.js is installed — Expo runs via npx.');
+    }
+    // SST (deploy phase only)
+    const sstOutput = tryExec('npx sst version');
+    const sstVersion = parseVersion(sstOutput, /(\d+\.\d+\.\d+)/);
+    prerequisites.push({
+        name: 'sst',
+        required: !isLocal,
+        status: sstVersion ? 'found' : 'not_found',
+        version: sstVersion,
+        installHint: 'SST is installed as a dev dependency: pnpm add -D sst (or npx sst)',
+        tier: 'V1',
+        phase: 'deploy',
+        description: isLocal
+            ? 'Manages your cloud infrastructure. Not needed yet — you can build and run your app locally first.'
+            : 'Manages your cloud infrastructure. Tells AWS what servers, databases, and storage your app needs.',
+        whyNeeded: isLocal
+            ? 'Only needed when you are ready to deploy your app to the internet.'
+            : 'Without SST, you cannot deploy your app to the internet.',
+        installCommands: ['Installed as a project dependency when you create your app.'],
+    });
+    if (!sstVersion && !isLocal) {
+        suggestions.push('SST not found. It installs as a dev dependency: pnpm add -D sst');
+    }
+    // AWS CLI (deploy phase only)
+    const awsOutput = tryExec('aws --version');
+    const awsVersion = parseVersion(awsOutput, /aws-cli\/(\d+\.\d+\.\d+)/);
+    prerequisites.push({
+        name: 'aws-cli',
+        required: !isLocal,
+        status: awsVersion ? 'found' : 'not_found',
+        version: awsVersion,
+        installHint: 'Install AWS CLI from https://aws.amazon.com/cli/',
+        tier: 'V1',
+        phase: 'deploy',
+        description: isLocal
+            ? 'A command-line tool for Amazon Web Services. Not needed yet — you can build and run your app locally first.'
+            : 'A command-line tool that lets your computer talk to Amazon Web Services, where your app runs.',
+        whyNeeded: isLocal
+            ? 'Only needed when you are ready to deploy your app to the internet.'
+            : 'Without it, you cannot deploy or manage your app on AWS.',
+        installCommands: platform === 'macOS'
+            ? ['brew install awscli']
+            : platform === 'linux'
+                ? ['curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip" && unzip awscliv2.zip && sudo ./aws/install']
+                : ['Download from https://aws.amazon.com/cli/'],
+    });
+    if (!awsVersion && !isLocal) {
+        suggestions.push('AWS CLI is not installed. Install from https://aws.amazon.com/cli/');
+    }
+    // AWS credentials (deploy phase only)
+    const home = homedir();
+    const hasAwsCreds = existsSync(join(home, '.aws', 'credentials')) || existsSync(join(home, '.aws', 'config'));
+    prerequisites.push({
+        name: 'aws-credentials',
+        required: !isLocal,
+        status: hasAwsCreds ? 'found' : 'not_found',
+        version: null,
+        installHint: 'Read everystack://aws-setup for step-by-step AWS account and credential setup.',
+        tier: 'V1',
+        phase: 'deploy',
+        description: isLocal
+            ? 'A password file for your AWS account. Not needed yet — you can build and run your app locally first.'
+            : 'A password file that proves your computer is allowed to deploy to your AWS account.',
+        whyNeeded: isLocal
+            ? 'Only needed when you are ready to deploy your app to the internet.'
+            : 'Without credentials, AWS will reject all deploy commands.',
+        installCommands: ['Read everystack://aws-setup for full setup guide', 'aws configure'],
+    });
+    if (!hasAwsCreds && !isLocal) {
+        suggestions.push("AWS credentials not configured. Read everystack://aws-setup for step-by-step setup, or run 'aws configure' if you already have access keys.");
+    }
+    // PostgreSQL
+    const psqlOutput = tryExec('psql --version');
+    const psqlVersion = parseVersion(psqlOutput, /psql \(PostgreSQL\) (\d+\.\d+)/);
+    const pgReadyOutput = psqlVersion ? tryExec('pg_isready') : null;
+    const pgServiceUp = pgReadyOutput !== null && pgReadyOutput.includes('accepting connections');
+    prerequisites.push({
+        name: 'postgresql',
+        required: true,
+        status: psqlVersion ? 'found' : 'not_found',
+        version: psqlVersion,
+        serviceRunning: psqlVersion ? pgServiceUp : undefined,
+        installHint: 'Install PostgreSQL: brew install postgresql (macOS) or https://www.postgresql.org/download/',
+        tier: 'V2',
+        phase: 'local',
+        description: 'A database that stores your app data: users, posts, recipes, or whatever your app needs.',
+        whyNeeded: 'Without PostgreSQL, your app cannot have user accounts or saved data (needed for V2+).',
+        installCommands: platform === 'macOS'
+            ? ['brew install postgresql@16', 'brew services start postgresql@16']
+            : platform === 'linux'
+                ? ['sudo apt install postgresql', 'sudo systemctl start postgresql']
+                : ['Download from https://www.postgresql.org/download/'],
+    });
+    if (!psqlVersion) {
+        suggestions.push('PostgreSQL is not installed. Needed for V2+ (database tier). Install: brew install postgresql');
+    }
+    else if (!pgServiceUp) {
+        suggestions.push(platform === 'macOS'
+            ? 'PostgreSQL is installed but the service is not running. Start it: brew services start postgresql@16'
+            : platform === 'linux'
+                ? 'PostgreSQL is installed but the service is not running. Start it: sudo systemctl start postgresql'
+                : 'PostgreSQL is installed but the service is not running. Start the PostgreSQL service.');
+    }
+    // Determine readiness — in local phase, only local-phase prerequisites count
+    const relevant = isLocal
+        ? prerequisites.filter(c => c.phase === 'local')
+        : prerequisites;
+    const v1Required = relevant.filter(c => c.tier === 'V1' && c.required);
+    const v2Required = relevant.filter(c => c.tier === 'V2' && c.required);
+    const v1Ready = nodeOk && v1Required.every(c => c.status === 'found');
+    const v2Ready = v1Ready && v2Required.every(c => c.status === 'found');
+    // V3 uses same prerequisites as V2 (adds SQS/S3 which are AWS services, no local tooling)
+    const v3Ready = v2Ready;
+    const readyForTier = v3Ready ? 'V3' : v2Ready ? 'V2' : v1Ready ? 'V1' : 'none';
+    // Build nextSteps
+    const nextSteps = [];
+    const missing = relevant.filter(p => p.required && p.status === 'not_found');
+    if (missing.length === 0) {
+        if (isLocal) {
+            nextSteps.push('All local development prerequisites installed. Ready to create and run your app.');
+            // Hint about deploy-phase tools if not yet installed
+            const deployMissing = prerequisites.filter(p => p.phase === 'deploy' && p.status === 'not_found');
+            if (deployMissing.length > 0) {
+                nextSteps.push('When you are ready to put your app on the internet, run check_environment with phase "deploy" to see what else is needed.');
+            }
+        }
+        else {
+            nextSteps.push('All prerequisites installed. Ready to create a new app.');
+        }
+    }
+    else {
+        const installOrder = isLocal
+            ? ['node', 'git', 'pnpm', 'expo', 'postgresql']
+            : ['node', 'git', 'pnpm', 'aws-cli', 'aws-credentials', 'expo', 'sst', 'postgresql'];
+        const ordered = installOrder
+            .map(name => missing.find(p => p.name === name))
+            .filter((p) => p !== undefined);
+        for (const p of ordered) {
+            if (p.tier === 'V2') {
+                nextSteps.push(`Optional for now: Install ${p.name} — ${p.description.split('.')[0]}. Only needed for apps with user accounts or a database (V2+).`);
+            }
+            else {
+                nextSteps.push(`Install ${p.name} — ${p.description.split('.')[0]}. ${p.installCommands[0]}`);
+            }
+        }
+    }
+    return {
+        phase,
+        prerequisites,
+        ready: readyForTier !== 'none',
+        readyForTier,
+        suggestions,
+        platform,
+        nextSteps,
+    };
+}

package/dist/tools/index.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerTools(server: McpServer): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/tools/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AASzE,wBAAgB,aAAa,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAcrD"}

package/dist/tools/index.js

@@ -0,0 +1,18 @@
+import { z } from 'zod';
+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) {
+    server.tool('check_environment', 'Verify development prerequisites are installed (Node.js, pnpm, git, Expo, SST, AWS CLI, PostgreSQL). Run this first when a user wants to start a new project or is having setup issues. Use phase "local" (default) to check only what is needed to build and run locally. Use phase "deploy" when ready to deploy to AWS.', {
+        phase: z.enum(['local', 'deploy']).optional().describe('Check prerequisites for local development (default) or AWS deployment'),
+    }, async ({ phase }) => {
+        const report = checkEnvironment(phase ?? 'local');
+        return {
+            content: [{ type: 'text', text: JSON.stringify(report, null, 2) }],
+        };
+    });
+}

package/dist/tools/project-status.d.ts

@@ -0,0 +1,28 @@
+interface ProjectStatus {
+    tier: 'V1' | 'V2' | 'V3' | 'unknown';
+    tierExplanation: string;
+    packages: {
+        installed: string[];
+        missing: string[];
+    };
+    files: {
+        sstConfig: boolean;
+        schemaDir: boolean;
+        schemaFiles: string[];
+        migrationsDir: boolean;
+        serverDir: boolean;
+        handlerFile: string | null;
+        workerFile: string | null;
+        imageFile: string | null;
+        seedFile: string | null;
+    };
+    deployment: {
+        sstOutputs: boolean;
+        stage: string | null;
+        secrets: string[];
+    };
+    warnings: string[];
+}
+export declare function analyzeProjectStatus(projectPath: string): ProjectStatus;
+export {};
+//# sourceMappingURL=project-status.d.ts.map

package/dist/tools/project-status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-status.d.ts","sourceRoot":"","sources":["../../src/tools/project-status.ts"],"names":[],"mappings":"AAUA,UAAU,aAAa;IACrB,IAAI,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,SAAS,CAAC;IACrC,eAAe,EAAE,MAAM,CAAC;IACxB,QAAQ,EAAE;QACR,SAAS,EAAE,MAAM,EAAE,CAAC;QACpB,OAAO,EAAE,MAAM,EAAE,CAAC;KACnB,CAAC;IACF,KAAK,EAAE;QACL,SAAS,EAAE,OAAO,CAAC;QACnB,SAAS,EAAE,OAAO,CAAC;QACnB,WAAW,EAAE,MAAM,EAAE,CAAC;QACtB,aAAa,EAAE,OAAO,CAAC;QACvB,SAAS,EAAE,OAAO,CAAC;QACnB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;QAC3B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;QAC1B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;QACzB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;KACzB,CAAC;IACF,UAAU,EAAE;QACV,UAAU,EAAE,OAAO,CAAC;QACpB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;QACrB,OAAO,EAAE,MAAM,EAAE,CAAC;KACnB,CAAC;IACF,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAgCD,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa,CAoHvE"}