@everystack/cli 0.3.0 → 0.3.4

package/src/cli/commands/lighthouse.ts

@@ -0,0 +1,104 @@
+/**
+ * `everystack audit:lighthouse [--stage <name>] [--host <url>] [--runs N] [--path /]`
+ *
+ * Mobile Lighthouse audit (Perf / A11y / Best-Practices / SEO) reported as a
+ * distribution over N runs, because the Performance score swings run-to-run with
+ * LCP. Warms the CloudFront edge first, then measures the warm-HTML path.
+ *
+ * Config-free: the target URL is the deployed router URL from SST outputs
+ * (resolveConfig), or --host. Requires `npx lighthouse` and a headless Chrome.
+ */
+
+import { execFileSync } from 'node:child_process';
+import { readFileSync, mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import {
+  CATEGORIES,
+  extractRun,
+  aggregate,
+  formatLighthouseReport,
+  type ExtractedRun,
+  type LhReport,
+} from '../lighthouse.js';
+import { resolveConfig } from '../config.js';
+import { step, info, fail, warn } from '../output.js';
+
+function runLighthouse(url: string, outPath: string): LhReport {
+  // Warm the edge so we measure the real-user (cached-HTML) experience.
+  try {
+    execFileSync('curl', ['-s', '-o', '/dev/null', url], { timeout: 30_000 });
+  } catch {
+    // warming is best-effort
+  }
+  execFileSync(
+    'npx',
+    [
+      'lighthouse',
+      url,
+      `--only-categories=${CATEGORIES.join(',')}`,
+      '--chrome-flags=--headless=new --no-sandbox',
+      '--output=json',
+      `--output-path=${outPath}`,
+      '--quiet',
+    ],
+    { stdio: ['ignore', 'ignore', 'ignore'], timeout: 120_000 },
+  );
+  return JSON.parse(readFileSync(outPath, 'utf8'));
+}
+
+/** Run Lighthouse N times and return the per-run extracts. Shared with the
+ *  `audit` capstone. */
+export async function collectLighthouseRuns(url: string, runs: number): Promise<ExtractedRun[]> {
+  const tmp = mkdtempSync(join(tmpdir(), 'everystack-lh-'));
+  const extracts: ExtractedRun[] = [];
+  for (let i = 0; i < runs; i++) {
+    step(`Lighthouse run ${i + 1}/${runs} on ${url} ...`);
+    try {
+      const report = runLighthouse(url, join(tmp, `lh-${i}.json`));
+      extracts.push(extractRun(report));
+    } catch (err: any) {
+      warn(`run ${i + 1} failed: ${err.message?.split('\n')[0] ?? err}`);
+    }
+  }
+  return extracts;
+}
+
+export async function auditLighthouseCommand(flags: Record<string, string>): Promise<void> {
+  let host = flags.host;
+  if (!host) {
+    try {
+      const config = await resolveConfig(flags.stage);
+      host = config.baseUrl;
+    } catch (err: any) {
+      fail(err.message);
+      info('Pass --host <url> to audit a specific URL without resolving a stage.');
+      process.exit(1);
+    }
+  }
+  if (!host) {
+    fail('No URL to audit. Pass --host <url> or --stage <name>.');
+    process.exit(1);
+  }
+
+  const runs = flags.runs ? parseInt(flags.runs, 10) : 3;
+  const pathName = flags.path || '/';
+  const url = host.replace(/\/+$/, '') + (pathName.startsWith('/') ? pathName : '/' + pathName);
+
+  const extracts = await collectLighthouseRuns(url, runs);
+
+  if (extracts.length === 0) {
+    fail('All Lighthouse runs failed. Is `npx lighthouse` installed and Chrome available?');
+    process.exit(1);
+  }
+
+  const agg = aggregate(extracts);
+  console.log('');
+  console.log(formatLighthouseReport(url, extracts.length, agg).join('\n'));
+
+  if (flags.json) {
+    writeFileSync(flags.json, JSON.stringify(agg, null, 2));
+    info(`Raw results → ${flags.json}`);
+  }
+  process.exit(0);
+}

package/src/cli/commands/security-probe.ts

@@ -0,0 +1,213 @@
+/**
+ * `everystack security:probe --stage <name>` — live black-box security probe.
+ *
+ * Config-free. Two instruments meeting in the middle:
+ *   1. White-box introspection: reads the live DB catalog (grants, columns, RLS)
+ *      via the ops-Lambda `db:query` path to learn what the deployed app exposes.
+ *   2. Black-box probing: hits the deployed router URL and asserts the surface
+ *      behaves safely against that discovered truth.
+ *
+ * No fixtures, no config — the plan is derived from the database itself. When the
+ * v3 Model lands, the plan source moves from catalog to the Model's abilities and
+ * this command becomes the generated `diff(declared, live)` red-team.
+ */
+
+import {
+  buildProbePlan,
+  assessRlsCoverage,
+  assessColumnExposure,
+  assessLimitCap,
+  assessInjection,
+  assessEmbedDepth,
+  summarizeProbe,
+  type Catalog,
+  type CatalogTable,
+  type CatalogColumn,
+  type CatalogGrant,
+  type ProbeResult,
+} from '../security-probe.js';
+import { resolveConfig, opsFunction } from '../config.js';
+import { invokeAction } from '../aws.js';
+import { step, info, fail, success, warn } from '../output.js';
+
+const SYS_SCHEMAS = "('pg_catalog','information_schema','pg_toast')";
+
+const TABLES_SQL = `
+  SELECT n.nspname AS schema, c.relname AS "table", c.relrowsecurity AS rls_enabled
+  FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
+  WHERE c.relkind = 'r' AND n.nspname NOT IN ${SYS_SCHEMAS}`;
+
+const COLUMNS_SQL = `
+  SELECT table_schema AS schema, table_name AS "table", column_name AS "column", data_type
+  FROM information_schema.columns
+  WHERE table_schema NOT IN ${SYS_SCHEMAS}`;
+
+const GRANTS_SQL = `
+  SELECT table_schema AS schema, table_name AS "table", grantee, privilege_type AS privilege
+  FROM information_schema.role_table_grants
+  WHERE table_schema NOT IN ${SYS_SCHEMAS}`;
+
+async function catalogQuery(region: string, fn: string, sql: string): Promise<any[]> {
+  const result: any = await invokeAction(region, fn, 'db:query', { sql });
+  if (result?.error) throw new Error(`Catalog query failed: ${result.error}`);
+  return result?.rows ?? [];
+}
+
+function toCatalog(tables: any[], columns: any[], grants: any[]): Catalog {
+  return {
+    tables: tables.map(
+      (r): CatalogTable => ({ schema: r.schema, table: r.table, rlsEnabled: r.rls_enabled === true }),
+    ),
+    columns: columns.map(
+      (r): CatalogColumn => ({ schema: r.schema, table: r.table, column: r.column, dataType: r.data_type }),
+    ),
+    grants: grants.map(
+      (r): CatalogGrant => ({ schema: r.schema, table: r.table, grantee: r.grantee, privilege: r.privilege }),
+    ),
+  };
+}
+
+interface GetResult {
+  status: number;
+  rows: Record<string, unknown>[];
+}
+
+async function apiGet(base: string, pathAndQuery: string): Promise<GetResult> {
+  const res = await fetch(`${base}${pathAndQuery}`, { redirect: 'follow' });
+  let rows: Record<string, unknown>[] = [];
+  try {
+    const body = await res.json();
+    if (Array.isArray(body)) rows = body;
+    else if (Array.isArray((body as any)?.data)) rows = (body as any).data;
+  } catch {
+    // non-JSON body
+  }
+  return { status: res.status, rows };
+}
+
+export interface ProbeRunOptions {
+  region: string;
+  opsFn: string;
+  base: string;
+  maxLimit?: number;
+}
+
+/** Result-producing core, shared by the command wrapper and the `audit` capstone. */
+export async function runSecurityProbe(opts: ProbeRunOptions): Promise<ProbeResult[]> {
+  const { region, opsFn, base } = opts;
+
+  step('Introspecting database catalog (grants, columns, RLS)...');
+  const [t, c, g] = await Promise.all([
+    catalogQuery(region, opsFn, TABLES_SQL),
+    catalogQuery(region, opsFn, COLUMNS_SQL),
+    catalogQuery(region, opsFn, GRANTS_SQL),
+  ]);
+  const plan = buildProbePlan(toCatalog(t, c, g));
+  info(
+    `Surface: ${plan.anonReadableTables.length} anon-readable, ${plan.authReadableTables.length} auth-readable table(s).`,
+  );
+
+  const results: ProbeResult[] = [];
+  const maxLimit = opts.maxLimit ?? 10000;
+
+  // 1. RLS coverage — pure, from the catalog (no HTTP).
+  results.push(...assessRlsCoverage(plan));
+
+  // 2. Sensitive-column exposure — anon GET each readable table that has them.
+  step('Probing anon column exposure...');
+  for (const table of plan.anonReadableTables) {
+    const sensitive = plan.sensitiveColumns[table];
+    if (!sensitive?.length) continue;
+    try {
+      const { status, rows } = await apiGet(base, `/api/${table}?limit=5`);
+      if (status === 404) {
+        warn(`/api/${table} → 404 (route naming differs from DB table; skipped)`);
+        continue;
+      }
+      results.push(assessColumnExposure(table, rows, sensitive));
+    } catch (err: any) {
+      warn(`column-exposure ${table} inconclusive: ${err.message}`);
+    }
+  }
+
+  // 3/4/5 — pick a representative anon-readable table for the protocol probes.
+  const probeTable = plan.anonReadableTables[0];
+  if (probeTable) {
+    step(`Probing query protocol on /api/${probeTable}...`);
+    try {
+      const cap = await apiGet(base, `/api/${probeTable}?limit=999999999`);
+      results.push(assessLimitCap(cap.status, cap.rows.length, maxLimit));
+    } catch (err: any) {
+      warn(`limit-cap inconclusive: ${err.message}`);
+    }
+
+    const jsonCol = plan.jsonbColumns[probeTable]?.[0];
+    if (jsonCol) {
+      try {
+        const payload = encodeURIComponent("' OR '1'='1");
+        const inj = await apiGet(base, `/api/${probeTable}?${jsonCol}->>x=eq.${payload}`);
+        results.push(assessInjection(inj.status));
+      } catch (err: any) {
+        warn(`json-path-injection inconclusive: ${err.message}`);
+      }
+    }
+
+    try {
+      const deep = 'select=*,a(*,b(*,c(*,d(*,e(*)))))';
+      const depth = await apiGet(base, `/api/${probeTable}?${deep}`);
+      results.push(assessEmbedDepth(depth.status));
+    } catch (err: any) {
+      warn(`embed-depth inconclusive: ${err.message}`);
+    }
+  }
+
+  return results;
+}
+
+/** Print probe results; returns the number of failures (for exit-code logic). */
+export function reportProbeResults(results: ProbeResult[]): number {
+  for (const r of results) {
+    const tag = `[${r.severity}]`;
+    if (r.pass) success(`${tag} ${r.name} — ${r.detail}`);
+    else fail(`${tag} ${r.name} — ${r.detail}`);
+  }
+  const s = summarizeProbe(results);
+  console.log('');
+  const summary = `security:probe — ${s.pass} passed, ${s.fail} failed (${s.critical} critical)`;
+  if (s.fail > 0) fail(summary);
+  else success(summary);
+  return s.fail;
+}
+
+export async function securityProbeCommand(flags: Record<string, string>): Promise<void> {
+  step('Resolving deployed config...');
+  let config;
+  try {
+    config = await resolveConfig(flags.stage);
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+  const base = (flags.host || config.baseUrl || '').replace(/\/+$/, '');
+  if (!base) {
+    fail('No router URL to probe. Pass --host or ensure the stage has a deployed URL.');
+    process.exit(1);
+  }
+  info(`Region: ${config.region}, Function: ${opsFunction(config)}, URL: ${base}`);
+
+  let results: ProbeResult[];
+  try {
+    results = await runSecurityProbe({
+      region: config.region,
+      opsFn: opsFunction(config),
+      base,
+      maxLimit: flags.maxLimit ? Number(flags.maxLimit) : undefined,
+    });
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+
+  console.log('');
+  process.exit(reportProbeResults(results) > 0 ? 1 : 0);
+}

package/src/cli/commands/security.ts

@@ -104,10 +104,18 @@ async function runCatalogAudit(flags: Record<string, string>, waivers: Waivers):
   step('Resolving deployed config...');
   const config = await resolveConfig(flags.stage);
   info(`Region: ${config.region}, Function: ${opsFunction(config)}`);
+  return auditDeployedSql(config.region, opsFunction(config), waivers);
+}
 
+/** Catalog-audit core, shared by the command and the `audit` capstone. */
+export async function auditDeployedSql(
+  region: string,
+  opsFn: string,
+  waivers: Waivers = {},
+): Promise<AuditReport> {
   step('Introspecting database catalog (functions + relations)...');
-  const fnRows = await catalogQuery(config.region, opsFunction(config), FUNCTIONS_SQL);
-  const relRows = await catalogQuery(config.region, opsFunction(config), RELATIONS_SQL);
+  const fnRows = await catalogQuery(region, opsFn, FUNCTIONS_SQL);
+  const relRows = await catalogQuery(region, opsFn, RELATIONS_SQL);
 
   const functions: FunctionDescriptor[] = fnRows.map(catalogFunctionToDescriptor);
   const views: ViewDescriptor[] = relRows.map(catalogRelationToDescriptor);
@@ -125,7 +133,7 @@ async function catalogQuery(region: string, fn: string, sql: string): Promise<an
 // Waivers + reporting.
 // ---------------------------------------------------------------------------
 
-async function loadWaivers(flag?: string): Promise<Waivers> {
+export async function loadWaivers(flag?: string): Promise<Waivers> {
   const candidates = flag ? [flag] : WAIVER_FILES;
   for (const candidate of candidates) {
     const abs = path.resolve(candidate);
@@ -141,7 +149,7 @@ async function loadWaivers(flag?: string): Promise<Waivers> {
   return {};
 }
 
-function printReport(report: AuditReport, instrument: 'static' | 'catalog'): void {
+export function printReport(report: AuditReport, instrument: 'static' | 'catalog'): void {
   const reds = [
     ...report.functions.filter((f) => f.severity === 'red'),
     ...report.views.filter((v) => v.severity === 'red'),

package/src/cli/index.ts

@@ -21,6 +21,10 @@ import { analyzeSSRCommand } from './commands/analyze.js';
 import { logsErrorsCommand, logsTailCommand, logsQueryCommand } from './commands/logs.js';
 import { secretsCommand } from './commands/secrets.js';
 import { securityAuditCommand } from './commands/security.js';
+import { securityProbeCommand } from './commands/security-probe.js';
+import { bundleAnalyzeCommand, bundleAuditCommand } from './commands/bundle.js';
+import { auditLighthouseCommand } from './commands/lighthouse.js';
+import { auditCommand } from './commands/audit.js';
 import { fail } from './output.js';
 
 const args = process.argv.slice(2);
@@ -206,6 +210,25 @@ async function main() {
     case 'security:audit':
       await securityAuditCommand(flags);
       break;
+    case 'security:probe':
+      await securityProbeCommand(flags);
+      break;
+    case 'bundle:analyze': {
+      const positional = args[1] && !args[1].startsWith('--') ? args[1] : undefined;
+      await bundleAnalyzeCommand(positional, flags);
+      break;
+    }
+    case 'audit':
+      await auditCommand(flags);
+      break;
+    case 'audit:lighthouse':
+      await auditLighthouseCommand(flags);
+      break;
+    case 'bundle:audit': {
+      const positional = args[1] && !args[1].startsWith('--') ? args[1] : undefined;
+      await bundleAuditCommand(positional, flags);
+      break;
+    }
     case 'secrets': {
       // secrets <subcommand> [positional...] [--flags]
       // Extract positional args: everything after subcommand that isn't a flag or flag value
@@ -262,6 +285,11 @@ Usage:
   everystack status            [--stage <name>] [--hours <n>]  Platform health: CDN, Lambda, rollup summary
   everystack security:audit    [--dir <path>] [--config <file>]  Static scan of migration SQL (pre-merge gate)
   everystack security:audit    --stage <name> [--config <file>]  Live catalog scan of a deployed stage (post-deploy)
+  everystack security:probe    --stage <name> [--host <url>]  Live black-box probe: introspects RLS/grants, then tests the deployed surface (RLS coverage, column exposure, injection, limit cap, embed depth)
+  everystack audit             --stage <name> [--host <url>] [--dir <export>] [--lighthouse]  Capstone: security:audit + security:probe + bundle:audit (+ optional lighthouse), combined report + exit code (CI gate); --dir adds the weight/size gate over a local export
+  everystack bundle:analyze    [dir]            Client web-bundle size + composition (run after \`expo export -p web --source-maps\`)
+  everystack audit:lighthouse  [--stage <name>] [--host <url>] [--runs 3] [--path /] [--json out.json]  Mobile Lighthouse (perf/a11y/bp/seo), median over N runs
+  everystack bundle:audit      [url|--dir <export>] [--stage <name>] [--values-from <.env>] [--leak-only] [--max-file-mb N] [--max-total-mb N] [--max-js-mb N] [--max-data-mb N]  Audit a bundle for leaked secrets AND weight (oversized assets, data that belongs in the DB, JS bloat). A URL/stage weighs the remote bundle (assets sized via HEAD, no download); --dir scans a local export; --leak-only skips the weight gate
   everystack certs:generate    [--output ./certs]
   everystack certs:configure   [--input ./certs] [--keyid main]
   everystack cache:purge       [--stage <name>]                  Bust all cached content (global epoch)

package/src/cli/lighthouse.ts

@@ -0,0 +1,155 @@
+/**
+ * Lighthouse audit — pure, Lighthouse-free parsing/aggregation logic for
+ * `everystack audit:lighthouse`.
+ *
+ * Why N runs: the category scores are stable but Performance swings run-to-run
+ * because LCP does under throttled-mobile simulation. A single run can read 92
+ * or 65. We run each host several times and report the DISTRIBUTION (median +
+ * min/max) — the median is the honest number, the spread shows how noisy LCP is.
+ *
+ * Measurement rule (in the command): warm the CloudFront edge first, then
+ * measure WITHOUT a cache-buster, so we score the real-user warm-HTML path, not
+ * a pessimistic cold-origin SSR render.
+ *
+ * Config-free: the target URL comes from the deployed SST outputs (or --host),
+ * never a hand-maintained env map.
+ */
+
+export const CATEGORIES = ['performance', 'accessibility', 'best-practices', 'seo'] as const;
+export const METRICS = [
+  'first-contentful-paint',
+  'largest-contentful-paint',
+  'total-blocking-time',
+  'cumulative-layout-shift',
+  'speed-index',
+] as const;
+
+export type Category = (typeof CATEGORIES)[number];
+export type Metric = (typeof METRICS)[number];
+
+export interface LhAudit {
+  title: string;
+  score: number | null;
+  numericValue?: number;
+  scoreDisplayMode?: string;
+}
+
+export interface LhReport {
+  categories: Record<string, { score: number; auditRefs: { id: string }[] }>;
+  audits: Record<string, LhAudit>;
+}
+
+export interface ExtractedRun {
+  scores: Record<string, number>; // category → 0..100
+  metrics: Record<string, number>; // metric → numericValue
+  imperfect: { id: string; title: string; cat: string }[];
+}
+
+export interface Aggregate {
+  scores: Record<string, number[]>;
+  metrics: Record<string, number[]>;
+  failing: { id: string; title: string; cat: string; count: number }[];
+  noindex: boolean;
+}
+
+export function median(xs: number[]): number {
+  const s = [...xs].sort((a, b) => a - b);
+  const m = Math.floor(s.length / 2);
+  return s.length % 2 ? s[m] : Math.round((s[m - 1] + s[m]) / 2);
+}
+
+/** Pull scores, metrics, and imperfect audits out of one Lighthouse report. */
+export function extractRun(report: LhReport): ExtractedRun {
+  const scores: Record<string, number> = {};
+  const metrics: Record<string, number> = {};
+  const imperfect: { id: string; title: string; cat: string }[] = [];
+
+  for (const c of CATEGORIES) {
+    scores[c] = Math.round((report.categories[c]?.score ?? 0) * 100);
+  }
+  for (const m of METRICS) {
+    metrics[m] = report.audits[m]?.numericValue ?? 0;
+  }
+  for (const c of CATEGORIES) {
+    for (const ref of report.categories[c]?.auditRefs ?? []) {
+      const au = report.audits[ref.id];
+      if (au && au.score !== null && au.score < 1 && au.scoreDisplayMode !== 'informative') {
+        imperfect.push({ id: ref.id, title: au.title, cat: c });
+      }
+    }
+  }
+  return { scores, metrics, imperfect };
+}
+
+/** Aggregate the per-run extracts into score/metric distributions + flags. */
+export function aggregate(runs: ExtractedRun[]): Aggregate {
+  const scores: Record<string, number[]> = Object.fromEntries(CATEGORIES.map((c) => [c, []]));
+  const metrics: Record<string, number[]> = Object.fromEntries(METRICS.map((m) => [m, []]));
+  const failingMap = new Map<string, { title: string; cat: string; count: number }>();
+  let noindex = false;
+
+  for (const run of runs) {
+    for (const c of CATEGORIES) scores[c].push(run.scores[c] ?? 0);
+    for (const m of METRICS) metrics[m].push(run.metrics[m] ?? 0);
+    for (const imp of run.imperfect) {
+      if (imp.id === 'is-crawlable') noindex = true;
+      const e = failingMap.get(imp.id) || { title: imp.title, cat: imp.cat, count: 0 };
+      e.count++;
+      failingMap.set(imp.id, e);
+    }
+  }
+
+  const failing = [...failingMap.entries()]
+    .map(([id, e]) => ({ id, ...e }))
+    .sort((a, b) => b.count - a.count);
+  return { scores, metrics, failing, noindex };
+}
+
+/** extractRun + aggregate over a set of raw reports. */
+export function summarize(reports: LhReport[]): Aggregate {
+  return aggregate(reports.map(extractRun));
+}
+
+function fmtMs(v: number): string {
+  return v >= 1000 ? `${(v / 1000).toFixed(1)}s` : `${Math.round(v)}ms`;
+}
+
+export function formatLighthouseReport(url: string, runs: number, agg: Aggregate): string[] {
+  const lines: string[] = [];
+  lines.push('='.repeat(64));
+  lines.push(`${url}   (${runs} run${runs === 1 ? '' : 's'})`);
+  lines.push('='.repeat(64));
+  lines.push('Category        median   runs');
+  for (const c of CATEGORIES) {
+    const xs = agg.scores[c];
+    const spread = xs.length > 1 ? `  [${Math.min(...xs)}–${Math.max(...xs)}]` : '';
+    lines.push(`  ${c.padEnd(14)} ${String(median(xs)).padStart(3)}     ${xs.join(' ')}${spread}`);
+  }
+  lines.push('');
+  lines.push('Metric                  median        spread');
+  for (const m of METRICS) {
+    const xs = agg.metrics[m];
+    const cls = m === 'cumulative-layout-shift';
+    const f = cls ? (v: number) => v.toFixed(3) : fmtMs;
+    lines.push(`  ${m.padEnd(24)} ${f(median(xs)).padStart(7)}   ${f(Math.min(...xs))}–${f(Math.max(...xs))}`);
+  }
+  if (agg.failing.length) {
+    lines.push('');
+    lines.push('Imperfect audits (count = runs flagged):');
+    for (const e of agg.failing) {
+      const note =
+        e.id === 'is-crawlable'
+          ? '  ← expected when the stage is noindex (true SEO only on the indexable domain)'
+          : '';
+      lines.push(`  [${e.cat}] ${e.id} (${e.count}/${runs}) — ${e.title}${note}`);
+    }
+  }
+  if (agg.noindex) {
+    lines.push('');
+    lines.push(
+      'NOTE: is-crawlable fails because this stage is noindex (robots Disallow: /).',
+    );
+    lines.push('      That suppresses SEO ~20pts. Re-measure the indexable production domain for the true score.');
+  }
+  return lines;
+}

package/src/cli/migration-compile.ts

@@ -19,9 +19,9 @@
  * lands with whole-DB introspection. The emission is identical either way.
  */
 
-import type { ModelDescriptor } from '@everystack/model';
+import type { ModelDescriptor, Module } from '@everystack/model';
 import type { AuthzContract, TableContract } from './authz-contract.js';
-import { compileCreateTable, compileEnums, foreignKeySql, modelConstraintSpecs, type CompileTableOptions } from './schema-compile.js';
+import { compileCreateTable, compileEnums, foreignKeySql, modelConstraintSpecs, qualifiedTable, type CompileTableOptions } from './schema-compile.js';
 import { compileTableContract } from './authz-compile.js';
 import { emitReconcileSql } from './authz-reconcile.js';
 import { emitSchemaSql, type SchemaChange } from './schema-diff.js';
@@ -38,8 +38,36 @@ function emptyTable(table: string): TableContract {
  */
 export function compileMigration(models: ModelDescriptor[], opts: CompileTableOptions = {}): string[] {
   const sql: string[] = [];
+  const schemaOf = (m: ModelDescriptor): string => m.schema ?? 'public';
 
-  // 0. Enum types — `CREATE TYPE … AS ENUM`, before any table/column references them.
+  // 0a. Non-public schemas — `CREATE SCHEMA` for each distinct one a model lives in,
+  //     before any table is created in it. public is the implicit default, never emitted.
+  const schemas = [...new Set(models.map(schemaOf))].filter((s) => s !== 'public').sort();
+  sql.push(...schemas.map((s) => `CREATE SCHEMA IF NOT EXISTS "${s}";`));
+
+  // The authz contracts — computed once, used for the schema USAGE grants here and the
+  // table-level reconcile below.
+  const contracts = models.map((m) => compileTableContract(m));
+
+  // 0a-bis. Schema USAGE — a role can't reach a table in a non-public schema without USAGE on
+  //   it, so a table/column grant there is dead without this. Derived from the grants: every
+  //   role that holds any privilege on a table in a non-public schema gets USAGE on that schema
+  //   (public USAGE is granted to PUBLIC by default, so it is never emitted). This replaces the
+  //   hand-written `GRANT USAGE ON SCHEMA auth/ops/dist …` the old bootstrap carried.
+  for (const schema of schemas) {
+    const roles = new Set<string>();
+    for (const c of contracts) {
+      if (!c.table.startsWith(`${schema}.`)) continue;
+      for (const r of Object.keys(c.grants)) roles.add(r);
+      for (const r of Object.keys(c.columnGrants ?? {})) roles.add(r);
+    }
+    if (roles.size) {
+      const targets = [...roles].sort().map((r) => (r.toUpperCase() === 'PUBLIC' ? 'PUBLIC' : r)).join(', ');
+      sql.push(`GRANT USAGE ON SCHEMA "${schema}" TO ${targets};`);
+    }
+  }
+
+  // 0b. Enum types — `CREATE TYPE … AS ENUM`, before any table/column references them.
   const enumCreates: SchemaChange[] = compileEnums(models).map((e) => ({ kind: 'createType', name: e.name, values: e.values }));
   sql.push(...emitSchemaSql(enumCreates));
 
@@ -49,11 +77,12 @@ export function compileMigration(models: ModelDescriptor[], opts: CompileTableOp
   // 2. Foreign keys — after every table exists.
   for (const model of models) sql.push(...foreignKeySql(model));
 
-  // 2b. Standalone indexes — after the columns they cover exist.
+  // 2b. Standalone indexes — after the columns they cover exist. The ON clause is the
+  //     schema-qualified table, so a non-public index targets the right table.
   const indexCreates: SchemaChange[] = [];
   for (const model of models) {
     for (const ix of modelConstraintSpecs(model).indexes) {
-      indexCreates.push({ kind: 'createIndex', table: `"${model.table}"`, name: ix.name, columns: ix.columns, unique: ix.unique, ...(ix.where ? { where: ix.where } : {}) });
+      indexCreates.push({ kind: 'createIndex', table: qualifiedTable(model), name: ix.name, columns: ix.columns, unique: ix.unique, ...(ix.where ? { where: ix.where } : {}) });
     }
   }
   sql.push(...emitSchemaSql(indexCreates));
@@ -61,9 +90,44 @@ export function compileMigration(models: ModelDescriptor[], opts: CompileTableOp
   // 3. Authz — RLS + policies + grants, after the columns they reference. Reuse
   //    the reconcile emitter against the empty baseline: every policy/grant is a
   //    pure creation, in the same dependency-correct order reconcile already uses.
-  const desired: AuthzContract = { tables: models.map((m) => compileTableContract(m)), functions: [] };
-  const baseline: AuthzContract = { tables: models.map((m) => emptyTable(`public.${m.table}`)), functions: [] };
+  //    The baseline keys on each model's resolved schema, so a non-public table
+  //    diffs against its own empty state, not a phantom public one.
+  const desired: AuthzContract = { tables: contracts, functions: [] };
+  const baseline: AuthzContract = { tables: models.map((m) => emptyTable(`${schemaOf(m)}.${m.table}`)), functions: [] };
   sql.push(...emitReconcileSql(desired, baseline));
 
   return sql;
 }
+
+/**
+ * Compile a set of Modules into one COMPLETE greenfield migration — the whole deploy, no
+ * hand-written bootstrap left:
+ *
+ *   1. CREATE EXTENSION (deduped, sorted)        — the bootstrap a package's SQL needs
+ *   2. compileMigration(flattened models)        — schemas, tables, FKs, indexes, RLS, authz
+ *   3. package functions/triggers (each thunk)   — imperative package SQL, AFTER the tables
+ *
+ * Roles are NOT emitted — they are cluster-global (`db:provision`), and the GRANTs in step 2
+ * assume they exist (as the dogfood pre-creates them). `compileMigration` is left untouched as
+ * the schema+authz core the contract round-trips through; the functions are emitted verbatim
+ * here, outside that round-trip (they are imperative, package-owned — not modeled).
+ */
+export function compileModuleMigration(modules: Module[], opts: CompileTableOptions = {}): string[] {
+  const sql: string[] = [];
+
+  // 1. Extensions — deduped + sorted, quoted so a hyphenated name (`uuid-ossp`) is valid.
+  const extensions = [...new Set(modules.flatMap((m) => m.extensions))].sort();
+  sql.push(...extensions.map((e) => `CREATE EXTENSION IF NOT EXISTS "${e}";`));
+
+  // 2. Schema + authz for every modeled table.
+  sql.push(...compileMigration(modules.flatMap((m) => m.models), opts));
+
+  // 3. Package SQL — functions + triggers, after the tables they reference. Each thunk's
+  //    output is a self-contained multi-statement block applied as one unit.
+  for (const fn of modules.flatMap((m) => m.functions)) {
+    const text = fn().trim();
+    if (text) sql.push(text);
+  }
+
+  return sql;
+}