@supatype/cli 0.1.6 → 0.1.9

package/src/commands/dev.ts

@@ -1,9 +1,9 @@
 /**
- * supatype dev — start local Postgres, apply schema, run supatype-server.
+ * supatype dev: start local Postgres, apply schema, run supatype-server.
  *
  * Runtime provider (top-level `provider` or legacy `database.provider`):
- *   native — host Postgres + host server + host engine (default)
- *   docker — full self-host Compose stack (Kong :18473); see dev-compose.ts
+ *   native: host Postgres + host server + host engine (default)
+ *   docker: full self-host Compose stack (Kong :18473); see dev-compose.ts
  *
  * Edge functions (when a functions/ dir exists): Deno is resolved from the CDN cache
  * (auto-download on miss). Self-host/cloud Docker stacks use supatype-server in-container;
@@ -18,13 +18,21 @@ import { isAbsolute, join, relative, resolve } from "node:path"
 import { loadConfig } from "../config.js"
 import type { ExtractedSchemaAstV2 } from "../schema-ast-v2.js"
 import {
+  apiSchemaList,
   functionsPathCandidatesFromProject,
   resolveRuntimeProvider,
   schemaPathFromProject,
   type SupatypeProjectConfig,
 } from "../project-config.js"
 import { discoverTsFunctionsInDir, writeDevFunctionsRouter } from "../functions-router-gen.js"
+import { fieldMaskingTierFromProject } from "../field-masking-tier.js"
 import { signJwt } from "../jwt.js"
+import {
+  devAuthenticatorPassword,
+  devJwtSecret,
+  devPostgresPassword,
+  secretFingerprint,
+} from "../local-secrets.js"
 import {
   normalisePlatformPath,
   cachePath,
@@ -50,6 +58,7 @@ import { writeAppViteEnv } from "../app-vite-env.js"
 import { ensureValkeySidecar, stopValkeySidecar } from "../valkey-sidecar.js"
 import {
   initdb,
+  nativeMaskLibraryPresent,
   start as pgStart,
   stop as pgStop,
   waitReady as pgWaitReady,
@@ -118,7 +127,7 @@ export function registerDev(program: Command): void {
     .action(async (opts: { watch: boolean; stream?: boolean; port?: string }) => {
       const cwd = process.cwd()
 
-      // ── 1. Load project config (before TUI — fatal errors must hit real stderr) ──
+      // ── 1. Load project config (before TUI, fatal errors must hit real stderr) ──
       const config = loadConfig(cwd)
       const provider = resolveRuntimeProvider(config)
 
@@ -172,15 +181,21 @@ export function registerDev(program: Command): void {
 
       // ── 5–7. Start Postgres ───────────────────────────────────────────────
       let dbURL: string
+      /** What PostgREST connects as, deliberately not `dbURL`, which is a superuser. */
+      let postgrestDbURL: string
       let stopPostgres: () => void | Promise<void>
       const pgPort = NATIVE_PG_PORT
-      const pgPassword = "postgres"
+      const pgPassword = devPostgresPassword(cwd)
+      // Distinct from pgPassword even locally, so the split the other paths enforce is the
+      // one developers see. Read from .env when present so it matches a stack the user has
+      // already provisioned.
+      const authenticatorPassword = devAuthenticatorPassword(cwd)
       // pgBinDir is set on the native path and used to add DLL search path for
       // PostgREST on Windows (PostgREST links against libpq + SSL from MinGW).
       let pgBinDir: string | null = null
 
       {
-        // native — resolve pg bin dir and manage with pg_ctl
+        // native: resolve pg bin dir and manage with pg_ctl
         pgBinDir = await resolvePgBinDir(config)
         const dataDir = config.database.data_dir ?? join(stateRoot, "data")
         mkdirSync(dataDir, { recursive: true })
@@ -192,7 +207,8 @@ export function registerDev(program: Command): void {
         pgStart(pgOpts)
         await pgWaitReady(pgOpts, 15_000)
         console.log("[supatype] Postgres is ready.")
-        dbURL = `postgres://postgres:postgres@127.0.0.1:${pgPort}/${projectName}?sslmode=disable`
+        dbURL = `postgres://postgres:${pgPassword}@127.0.0.1:${pgPort}/${projectName}?sslmode=disable`
+        postgrestDbURL = `postgres://authenticator:${authenticatorPassword}@127.0.0.1:${pgPort}/${projectName}?sslmode=disable`
         stopPostgres = () => pgStop(pgOpts)
 
         // Create project database if it doesn't exist (native only).
@@ -219,8 +235,25 @@ export function registerDev(program: Command): void {
         //   anon          – unauthenticated requests (RLS enforced)
         //   authenticated – signed-in user requests  (RLS enforced)
         //   service_role  – developer/admin bypass   (BYPASSRLS)
+        //   authenticator – the role PostgREST *connects* as, and nothing else
+        //
+        // `authenticator` is NOINHERIT and holds no privileges of its own: it can only
+        // SET ROLE to the three above. That containment is the point. Connecting as
+        // `postgres`: a superuser: meant a request whose JWT named *any* role in the
+        // cluster got it, because a superuser may SET ROLE to anything. Verified: as
+        // postgres, `SET ROLE supatype_replication_admin` succeeds; as authenticator the
+        // same statement is refused. Mirrors the image, which has had this role all along.
+        // Created here rather than during the push, because the engine chooses how to enforce field
+        // rules from the extensions present *when it diffs*. Creating it later would leave the tier
+        // decided against a database that no longer looks like that.
+        //
+        // Conditional on the library being bundled: an archive downloaded before it was would fail
+        // the CREATE, and there is nothing the developer could do about it from here.
+        const maskSql = nativeMaskLibraryPresent(pgBinDir)
+          ? "CREATE EXTENSION IF NOT EXISTS supatype_mask;\n"
+          : ""
         const rolesSql = `
-CREATE SCHEMA IF NOT EXISTS auth;
+${maskSql}CREATE SCHEMA IF NOT EXISTS auth;
 DO $$ BEGIN
   IF NOT EXISTS (SELECT FROM pg_roles WHERE rolname = 'anon')
     THEN CREATE ROLE anon NOLOGIN; END IF;
@@ -228,8 +261,11 @@ DO $$ BEGIN
     THEN CREATE ROLE authenticated NOLOGIN; END IF;
   IF NOT EXISTS (SELECT FROM pg_roles WHERE rolname = 'service_role')
     THEN CREATE ROLE service_role NOLOGIN BYPASSRLS; END IF;
+  IF NOT EXISTS (SELECT FROM pg_roles WHERE rolname = 'authenticator')
+    THEN CREATE ROLE authenticator LOGIN NOINHERIT PASSWORD '${authenticatorPassword}'; END IF;
 END $$;
 GRANT anon, authenticated, service_role TO postgres;
+GRANT anon, authenticated, service_role TO authenticator;
 GRANT USAGE ON SCHEMA public TO anon, authenticated, service_role;
 -- Table-level privileges (RLS restricts rows; roles still need table access)
 GRANT SELECT ON ALL TABLES IN SCHEMA public TO anon;
@@ -246,7 +282,7 @@ ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON SEQUENCES TO authenticate
           { stdio: "pipe", encoding: "utf8", env: pgEnv })
       }
 
-      const LOCAL_JWT_SECRET = "super-secret-jwt-token-with-at-least-32-characters-long"
+      const LOCAL_JWT_SECRET = devJwtSecret(cwd)
       const authDbURL = dbURL.includes("?")
         ? `${dbURL}&search_path=auth`
         : `${dbURL}?search_path=auth`
@@ -264,7 +300,7 @@ ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON SEQUENCES TO authenticate
       mkdirSync(supatypeDir, { recursive: true })
 
       const localStoragePath = config.storage?.provider !== "s3" ? join(stateRoot, "storage") : undefined
-      // Native Postgres builds don't include PostGIS — skip geo fields rather than failing.
+      // Native Postgres builds don't include PostGIS, skip geo fields rather than failing.
       const skipFieldKinds: ReadonlySet<string> = new Set(["geo", "vector"])
 
       await runSchemaPush(cwd, engineBin, schemaPath, dbURL, manifestPath, adminConfigPath, localStoragePath, skipFieldKinds, config).catch(
@@ -305,7 +341,7 @@ ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON SEQUENCES TO authenticate
           }
         } catch (err) {
           console.warn(
-            `[supatype] ⚠  Found ${functionsDir} but could not provision Deno — edge functions will not run.\n` +
+            `[supatype] ⚠  Found ${functionsDir} but could not provision Deno, edge functions will not run.\n` +
               `  ${(err as Error).message}\n` +
               "  (Functions still appear in Studio; invocations need Deno.)",
           )
@@ -340,14 +376,14 @@ ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON SEQUENCES TO authenticate
             JWT_SECRET: LOCAL_JWT_SECRET,
             PORT: REALTIME_PORT,
             SLOT_NAME: "supatype_realtime",
-            PUBLICATION_NAME: "supatype_realtime_pub",
+            PUBLICATION_NAME: "supatype_realtime",
           },
         })
         realtimeProc.start()
         console.log(`[supatype] Realtime service: ${realtimeUrl}`)
       } catch (err) {
         console.warn(
-          `[supatype] ⚠  Realtime unavailable — WebSocket subscriptions will not work.\n` +
+          `[supatype] ⚠  Realtime unavailable, WebSocket subscriptions will not work.\n` +
             `  ${(err as Error).message}`,
         )
       }
@@ -472,8 +508,21 @@ ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON SEQUENCES TO authenticate
         }
 
         const postgrestEnv: Record<string, string> = {
-          PGRST_DB_URI: dbURL,
-          PGRST_DB_SCHEMA: "public, supatype, graphql_public",
+          PGRST_DB_URI: postgrestDbURL,
+          // Derived from schema.pg_schema (or schema.api_schemas), a hardcoded "public" here meant
+          // a non-default pg_schema pushed correctly and then answered PGRST106 on every request.
+          // Native dev has no masking extension either, so a schema with field rules is served from
+          // `api` here too: the case an "is the database external" rule would have got wrong.
+          PGRST_DB_SCHEMA: apiSchemaList(
+            config,
+            // The installed archive decides: one downloaded before the masking library was bundled
+            // has no extension, so its field rules are enforced by views instead.
+            fieldMaskingTierFromProject(cwd, config, nativeMaskLibraryPresent(pgBinDir)),
+          ),
+          // Parity with self-host, which has always set this. Unqualified names in column defaults
+          // (`uuid_generate_v4()`) resolve here, and with a non-public pg_schema the request schema
+          // alone does not reach them.
+          PGRST_DB_EXTRA_SEARCH_PATH: "public,extensions",
           PGRST_DB_ANON_ROLE: "anon",
           PGRST_SERVER_PORT: postgrestPort,
           PGRST_SERVER_HOST: "127.0.0.1",
@@ -547,7 +596,7 @@ ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON SEQUENCES TO authenticate
         links,
         anonKey,
         serviceRoleKey,
-        hints: [`Postgres ${dbURL}`, `JWT secret: ${LOCAL_JWT_SECRET}`],
+        hints: [`Postgres ${dbURL}`, `JWT secret: #${secretFingerprint(LOCAL_JWT_SECRET)} (in .env)`],
       })
 
       // ── Shutdown handler ──────────────────────────────────────────────────
@@ -595,9 +644,9 @@ ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON SEQUENCES TO authenticate
 // Schema push (engine subprocess)
 // ---------------------------------------------------------------------------
 
-// Last successfully-pushed AST JSON — used to skip no-op re-fires.
+// Last successfully-pushed AST JSON, used to skip no-op re-fires.
 let _lastPushedAst: string | null = null
-// AST that failed on its last attempt — always retried even if content is unchanged.
+// AST that failed on its last attempt, always retried even if content is unchanged.
 let _lastFailedAst: string | null = null
 
 async function runSchemaPush(
@@ -621,7 +670,7 @@ async function runSchemaPush(
     ast = filtered
     if (adapted.length > 0) {
       console.warn(
-        `[supatype] ⚠  ${adapted.length} field(s) replaced with JSONB — required extensions not available:\n` +
+        `[supatype] ⚠  ${adapted.length} field(s) replaced with JSONB, required extensions not available:\n` +
         adapted.map((s: string) => `    ${s}`).join("\n"),
       )
     }
@@ -695,7 +744,7 @@ async function runSchemaPush(
     { cwd, stdio: "pipe", encoding: "utf8" },
   )
   if (genResult.status !== 0) {
-    console.warn("[supatype] Manifest generation failed — server routing may be stale.")
+    console.warn("[supatype] Manifest generation failed, server routing may be stale.")
   }
 
   // Generate admin config (for Studio). Engine writes to stdout.
@@ -840,7 +889,7 @@ async function extractPostgresArchive(
 }
 
 // ---------------------------------------------------------------------------
-// PostgREST resolver — downloads from GitHub releases if not cached
+// PostgREST resolver: downloads from GitHub releases if not cached
 // ---------------------------------------------------------------------------
 
 const POSTGREST_DEFAULT_VERSION = "12.2.3"
@@ -981,12 +1030,12 @@ function repairWindowsPostgrestRuntime(cacheDir: string, archivePath: string, bi
 }
 
 // ---------------------------------------------------------------------------
-// Local-dev JWT generator (no external dep — pure crypto)
+// Local-dev JWT generator (no external dep, pure crypto)
 // ---------------------------------------------------------------------------
 
 
 // ---------------------------------------------------------------------------
-// AST adaptation — replace extension-dependent fields with JSONB fallbacks
+// AST adaptation: replace extension-dependent fields with JSONB fallbacks
 // ---------------------------------------------------------------------------
 
 interface AstField { kind: string; required?: boolean; [k: string]: unknown }

package/src/commands/doctor.ts

@@ -1,10 +1,12 @@
 import type { Command } from "commander"
 import { loadConfig, loadSchemaAst } from "../config.js"
 import { info, plain } from "../ui/messages.js"
-import { schemaPathFromProject } from "../project-config.js"
+import { hooksPathFromProject, schemaPathFromProject, serviceRoleRoutes } from "../project-config.js"
 import { resolveTarget, targetSchemaDoctor, schemaPgSchema } from "../resolve-target.js"
 import { loadProjectLink } from "../link.js"
 import { resolveHostEngineDatabaseUrl } from "../dev-compose.js"
+import { hooksReport, type HooksReport } from "../model-hooks.js"
+import { checkServiceRoleRoutes, type ServiceRoleProblems } from "../service-role-check.js"
 
 interface DoctorItem {
   kind: string
@@ -20,12 +22,15 @@ interface DoctorReport {
   unmanagedDrift: DoctorItem[]
 }
 
-function printSection(title: string, items: DoctorItem[]): void {
+/** Exported for tests: the label form is easy to get subtly wrong per item kind. */
+export function printSection(title: string, items: DoctorItem[]): void {
   if (items.length === 0) return
   plain(`\n${title} (${items.length}):\n`)
   for (const item of items) {
     const fields = item.fields.length > 0 ? ` (${item.fields.join(", ")})` : ""
-    plain(`  • ${item.table}.${item.name}${fields}`)
+    // A table's `name` *is* its table, so the usual `table.name` form renders "widget.widget".
+    const label = item.table === item.name ? item.name : `${item.table}.${item.name}`
+    plain(`  • ${label}${fields}`)
     plain(`    ${item.message}`)
   }
 }
@@ -82,6 +87,9 @@ export function registerDoctor(program: Command): void {
         })) as DoctorReport
       }
 
+      printHooks(hooksReport(cwd, hooksPathFromProject(config, cwd), ast))
+      printServiceRoleGrants(checkServiceRoleRoutes(config, cwd), serviceRoleRoutes(config))
+
       printSection("Missing (in AST, not in DB)", report.missing ?? [])
       printSection("Stale managed (stamped, not in AST)", report.staleManaged ?? [])
       printSection("Unmanaged drift (manual decision)", report.unmanagedDrift ?? [])
@@ -101,3 +109,61 @@ export function registerDoctor(program: Command): void {
       }
     })
 }
+
+/**
+ * Whether declared hooks can actually run.
+ *
+ * Worth its own section because every failure here is silent: a hook whose function is missing, or a
+ * stack with functions switched off, produces no error anywhere, the write just succeeds
+ * unvalidated. Drift you cannot see is the thing doctor exists for.
+ */
+export function printHooks(report: HooksReport): void {
+  if (report.declared.length === 0) return
+
+  plain(`\nHooks (${report.declared.length}):\n`)
+  for (const hook of report.declared) {
+    const broken = report.missing.some(
+      (m) => m.model === hook.model && m.event === hook.event,
+    )
+    plain(`  ${broken ? "✗" : "•"} ${hook.model}.${hook.event} → ${hook.function}`)
+  }
+
+  if (report.missing.length > 0) {
+    plain("\n  Those marked ✗ name a function that does not exist, so they never fire.")
+    plain("  Create it with: supatype hooks new <name>")
+  }
+  if (report.functionsDisabled) {
+    plain("\n  functions_enabled is false in .supatype/manifest.json, every hook is inert.")
+    plain("  Regenerate the stack config with: supatype self-host compose")
+  }
+  if (report.mapMissing) {
+    plain("\n  .supatype/manifest.json carries no hook map, so the server has nothing to call.")
+    plain("  Run: supatype push")
+  }
+}
+
+/**
+ * Report which functions may see the service-role key, and which grants do nothing.
+ *
+ * Worth printing even when everything resolves: this is the list of functions that can read and write
+ * past every access rule in the schema, and "which ones are those again?" should be answerable without
+ * opening the config.
+ */
+export function printServiceRoleGrants(
+  problems: ServiceRoleProblems,
+  declared: readonly string[],
+): void {
+  if (declared.length === 0) return
+
+  plain(`\nService-role grants (${declared.length}):\n`)
+  const broken = new Set(problems.missing)
+  for (const name of declared) {
+    plain(`  ${broken.has(name) ? "✗" : "•"} ${name}`)
+  }
+
+  if (broken.size > 0) {
+    plain("\n  Those marked ✗ match no function, so they grant nothing, the function reads no key.")
+  }
+  for (const warning of problems.warnings) plain(warning)
+  plain("\n  These functions bypass every access rule in the schema. Anything not listed cannot.")
+}

package/src/commands/engine.ts

@@ -1,6 +1,6 @@
 /**
  * Engine management commands:
- *   supatype engine status  — check if the engine container is reachable
+ *   supatype engine status: check if the engine container is reachable
  */
 
 import type { Command } from "commander"

package/src/commands/functions.ts

@@ -16,6 +16,7 @@ import { ensureBinary } from "../ensure-binary.js"
 import {
   functionsPathCandidatesFromProject,
   preferredFunctionsPathFromProject,
+  serviceRoleRoutes,
 } from "../project-config.js"
 import {
   discoverTsFunctionsInDir,
@@ -24,6 +25,7 @@ import {
 import { loadProjectLink } from "../link.js"
 import { resolveTarget } from "../resolve-target.js"
 import { targetFetch } from "../target-client.js"
+import { ensureFunctionsDenoTypes } from "../functions-deno-types.js"
 import { error, info, plain } from "../ui/messages.js"
 import { nextSteps } from "../ui/next-steps.js"
 
@@ -136,22 +138,23 @@ function scaffoldFunction(cwd: string, name: string): void {
 
   mkdirSync(fnDir, { recursive: true })
 
-  const indexContent = `// ${name} — Supatype Edge Function
+  const indexContent = `// ${name}, Supatype Edge Function
 // Docs: https://supatype.com/docs/edge-functions
 
 export default async function handler(req: Request): Promise<Response> {
-  const { method, url } = req
+  const { method } = req
+  const url = Deno.env.get("SUPATYPE_URL")
 
   // Example: read request body for POST requests
   if (method === "POST") {
     const body = await req.json()
-    return new Response(JSON.stringify({ message: "Hello from ${name}!", received: body }), {
+    return new Response(JSON.stringify({ message: "Hello from ${name}!", received: body, url }), {
       status: 200,
       headers: { "Content-Type": "application/json" },
     })
   }
 
-  return new Response(JSON.stringify({ message: "Hello from ${name}!" }), {
+  return new Response(JSON.stringify({ message: "Hello from ${name}!", url }), {
     status: 200,
     headers: { "Content-Type": "application/json" },
   })
@@ -181,13 +184,27 @@ export default async function handler(req: Request): Promise<Response> {
     )
   }
 
+  const denoTypes = ensureFunctionsDenoTypes(cwd, functionsDir)
+
   const functionsDirLabel = relativeFunctionsDir(cwd, functionsDir)
   info(`Created function: ${functionsDirLabel}/${name}/index.ts`)
-  nextSteps("Next steps:", [
+  if (denoTypes.wroteDenoDts) {
+    info(`Added Deno IDE types: ${functionsDirLabel}/deno.d.ts`)
+  }
+  if (denoTypes.wroteTsconfig) {
+    info(`Added functions tsconfig: ${functionsDirLabel}/tsconfig.json`)
+  }
+  if (denoTypes.rootExclude === "updated") {
+    info('Updated root tsconfig.json to exclude "functions"')
+  }
+
+  const steps = [
     "Local dev:    npx supatype functions serve",
     `Invoke:       npx supatype functions invoke ${name}`,
     "Deploy:       npx supatype functions deploy",
-  ])
+    ...denoTypes.hints,
+  ]
+  nextSteps("Next steps:", steps)
 }
 
 // ─── Discover functions ──────────────────────────────────────────────────────
@@ -240,7 +257,7 @@ function discoverFunctions(cwd: string): DiscoveredFunction[] {
     const stat = statSync(fullPath)
 
     if (stat.isDirectory()) {
-      // Directory function — look for index.ts
+      // Directory function: look for index.ts
       const indexPath = join(fullPath, "index.ts")
       if (existsSync(indexPath)) {
         fns.push({ name: entry, entrypoint: indexPath, absPath: fullPath })
@@ -352,7 +369,7 @@ async function deploy(cwd: string, opts: { only?: string; env?: string; dryRun?:
   }
 
   if (opts.dryRun) {
-    plain("Dry run — the following functions would be deployed:\n")
+    plain("Dry run: the following functions would be deployed:\n")
     for (const fn of fns) {
       plain(`  ${fn.name}  →  ${relative(cwd, fn.entrypoint)}`)
     }
@@ -422,6 +439,9 @@ async function deployViaTarget(
               source,
               entrypoint: `${fn.name}/index.ts`,
             }],
+            // Sent every deploy, and replaced wholesale by the platform: the config file is the whole
+            // truth, so a name removed from it must stop being entitled to the service-role key.
+            serviceRole: serviceRoleRoutesFor(cwd),
           },
           token: target.token!,
           orgId: target.orgId,
@@ -479,6 +499,9 @@ async function deployCloud(cwd: string, fns: DiscoveredFunction[], env?: string)
             source,
             entrypoint: `${fn.name}/index.ts`,
           }],
+          // Same grants as the target path: both reach the same endpoint, and a project deployed one
+          // way must not end up with a different credential surface than the other.
+          serviceRole: serviceRoleRoutesFor(cwd),
         }),
         signal: AbortSignal.timeout(60_000),
       })
@@ -500,13 +523,27 @@ async function deployCloud(cwd: string, fns: DiscoveredFunction[], env?: string)
   info(`Invoke: https://${linked.ref}.supatype.dev/functions/v1/<name>`)
 }
 
+/**
+ * The project's `functions.serviceRole` list, or undefined when the config cannot be read.
+ *
+ * Undefined rather than `[]`: the platform replaces the stored list wholesale when the field is present,
+ * so sending an empty array because a config failed to load would revoke every grant the project has.
+ */
+export function serviceRoleRoutesFor(cwd: string): string[] | undefined {
+  try {
+    return serviceRoleRoutes(loadConfig(cwd))
+  } catch {
+    return undefined
+  }
+}
+
 function readFunctionSource(fn: DiscoveredFunction): string {
   const stat = statSync(fn.absPath)
   if (stat.isFile()) {
     return readFileSync(fn.absPath, "utf8")
   }
 
-  // Directory function — read all .ts files
+  // Directory function: read all .ts files
   const files: Record<string, string> = {}
   const entries = readdirSync(fn.absPath, { recursive: true }) as string[]
   for (const entry of entries) {
@@ -570,7 +607,7 @@ async function listFunctions(cwd: string): Promise<void> {
     plain(`  ${"─".repeat(28)} ${"─".repeat(24)} ${"─".repeat(20)} ${"─".repeat(12)}`)
 
     for (const fn of data) {
-      const deployed = fn.deployedAt ? new Date(fn.deployedAt).toLocaleString() : "—"
+      const deployed = fn.deployedAt ? new Date(fn.deployedAt).toLocaleString() : "-"
       plain(
         `  ${fn.name.padEnd(28)} ${deployed.padEnd(24)} ${String(fn.invocations24h ?? 0).padEnd(20)} ${fn.avgDurationMs ?? 0}ms`,
       )

package/src/commands/generate.ts

@@ -2,9 +2,10 @@ import type { Command } from "commander"
 import { mkdirSync, writeFileSync } from "node:fs"
 import { resolve, dirname } from "node:path"
 import { loadConfig, loadSchemaAst } from "../config.js"
-import { schemaPathFromProject } from "../project-config.js"
+import { hooksPathFromProject, schemaPathFromProject } from "../project-config.js"
 import { ensureEngine, engineRequest } from "../engine-client.js"
 import { generateClientAugmentation } from "../augmentation-generator.js"
+import { writeHooksModule } from "../model-hooks.js"
 import { error, info } from "../ui/messages.js"
 
 export function registerGenerate(program: Command): void {
@@ -41,5 +42,8 @@ export function registerGenerate(program: Command): void {
       mkdirSync(dirname(augmentationOutPath), { recursive: true })
       writeFileSync(augmentationOutPath, augmentationCode, "utf8")
       info(`Client augmentation written to ${outputClientPath}`)
+
+      const hooksPath = writeHooksModule(cwd, hooksPathFromProject(config, cwd), ast)
+      if (hooksPath !== null) info(`Hook handler types written to ${hooksPath}`)
     })
 }

package/src/commands/hooks.ts

@@ -0,0 +1,138 @@
+/**
+ * `supatype hooks`: scaffold and inspect model hooks.
+ *
+ * Separate from `supatype functions` because the two are different things wearing the same runtime.
+ * A function is a **public endpoint**: anyone holding the anon key can invoke it. A hook is
+ * **procedural**: only the API server calls it, around a write, and the gateway refuses the route
+ * from outside. Keeping them in separate directories is what makes that boundary structural instead
+ * of a list somebody has to maintain.
+ */
+import type { Command } from "commander"
+import { existsSync, mkdirSync, writeFileSync } from "node:fs"
+import { join, relative } from "node:path"
+import { loadConfig, loadSchemaAst } from "../config.js"
+import { hooksPathFromProject, schemaPathFromProject } from "../project-config.js"
+import { declaredHooks, hooksReport } from "../model-hooks.js"
+import { error, info, plain } from "../ui/messages.js"
+
+export function registerHooks(program: Command): void {
+  const hooksCmd = program
+    .command("hooks")
+    .description("Manage model hooks (procedural handlers the API runs around a write)")
+
+  hooksCmd
+    .command("new <name>")
+    .description("Scaffold a hook handler")
+    .action((name: string) => {
+      scaffoldHook(process.cwd(), name)
+    })
+
+  hooksCmd
+    .command("list")
+    .description("Show the hooks the schema declares and whether each one can run")
+    .action(() => {
+      const cwd = process.cwd()
+      const config = loadConfig(cwd)
+      const ast = loadSchemaAst(schemaPathFromProject(config, cwd), cwd)
+      const report = hooksReport(cwd, hooksPathFromProject(config, cwd), ast)
+
+      if (report.declared.length === 0) {
+        info("No model declares a hook.")
+        return
+      }
+      for (const hook of report.declared) {
+        const broken = report.missing.some((m) => m.model === hook.model && m.event === hook.event)
+        plain(`  ${broken ? "✗" : "•"} ${hook.model}.${hook.event} → ${hook.function}`)
+      }
+      if (report.missing.length > 0) {
+        plain("\n  ✗ names a handler that does not exist, so that hook never fires.")
+      }
+    })
+}
+
+function scaffoldHook(cwd: string, name: string): void {
+  const config = loadConfig(cwd)
+  const hooksDir = hooksPathFromProject(config, cwd)
+  const dir = join(hooksDir, name)
+
+  if (existsSync(dir)) {
+    error(`Hook "${name}" already exists at ${relative(cwd, dir)}`)
+    process.exit(1)
+  }
+
+  const ast = loadSchemaAst(schemaPathFromProject(config, cwd), cwd)
+  const declared = declaredHooks(ast).filter((hook) => hook.function === name)
+
+  mkdirSync(dir, { recursive: true })
+  writeFileSync(join(dir, "index.ts"), handlerTemplate(name, declared), "utf8")
+
+  info(`Created hook: ${relative(cwd, join(dir, "index.ts"))}`)
+  if (declared.length === 0) {
+    // Scaffolding a handler nothing calls is easy to do and impossible to notice, since a hook that
+    // is never referenced simply never runs.
+    plain("")
+    plain("  No model references it yet. Add it to a model's meta:")
+    plain(`    hooks: { beforeChange: "${name}" }`)
+    plain("  then run `supatype push` to generate its types and register it.")
+  } else {
+    plain("")
+    for (const hook of declared) {
+      plain(`  Wired to ${hook.model}.${hook.event}`)
+    }
+  }
+}
+
+/**
+ * The scaffold deliberately imports from `../_supatype/hooks.ts`, which `push` generates.
+ *
+ * Before the first push that file does not exist, so the handler will not compile, which is the
+ * honest state: the types come from the schema, and a handler typed against a model that has not been
+ * pushed is a handler typed against a guess.
+ */
+function handlerTemplate(name: string, declared: { model: string; event: string }[]): string {
+  const event = declared[0]?.event ?? "beforeChange"
+  const model = declared[0]?.model ?? "YourModel"
+
+  if (event.startsWith("after")) {
+    return `// ${name}: model hook (${event})
+//
+// Runs after the write has succeeded. It cannot change or undo it: a rejection here would be a
+// rejection of something that already happened. Failures are logged, not surfaced to the caller.
+
+import { hook, type AfterChange } from "../_supatype/hooks.ts"
+
+const handler: AfterChange<"your_table"> = async (ctx) => {
+  console.log(\`\${ctx.table} \${ctx.operation} by \${ctx.user?.sub ?? "anon"}\`)
+}
+
+export default hook(handler)
+`
+  }
+
+  return `// ${name}: model hook (${event}) for ${model}
+//
+// Runs before the write reaches Postgres, so it can reject it or rewrite the body.
+//
+// Not a security boundary: hooks fire for writes through the API, and direct SQL, seeds and anything
+// holding the service role bypass them. Invariants belong in the model's access rules or a CHECK.
+
+import { hook, type BeforeChange } from "../_supatype/hooks.ts"
+
+const handler: BeforeChange<"your_table"> = async (ctx) => {
+  if (ctx.operation === "insert") {
+    // \`ctx.rows\` is the submitted rows, typed from the model.
+    return { rows: ctx.rows }
+  }
+
+  // \`ctx.patch\` is the submitted partial; \`ctx.previous()\` reads the rows about to change.
+  // Those come back as stored, unmasked, so do not echo them into a rejection message.
+  return {}
+
+  // Reject with a message the caller sees, and a status of your choosing:
+  //   return { reject: "A post needs a title" }
+  //   return { reject: { message: "Already exists", status: 409, code: "duplicate" } }
+}
+
+export default hook(handler)
+`
+}