@supatype/cli 0.1.6 → 0.1.7

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)
+`
+}

package/src/commands/init.ts

@@ -2,6 +2,7 @@ import type { Command } from "commander"
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
 import { resolve, join, basename } from "node:path"
 import { spawnSync } from "node:child_process"
+import { randomBytes } from "node:crypto"
 import { p, runClackFlow } from "../ui/clack.js"
 import { ensureNotCancelled } from "../ui/prompts.js"
 import { generateAndWriteKeys } from "./keys.js"
@@ -13,6 +14,7 @@ import {
   ensureComponentBinaries,
   reportComponentBinaryFailures,
 } from "../ensure-component-binaries.js"
+import { ensureFunctionsDenoTypes } from "../functions-deno-types.js"
 import { mergeSupatypePackageJson } from "../init-package-json.js"
 import { cliPackageVersion } from "../cli-package-version.js"
 import {
@@ -792,6 +794,12 @@ function scaffoldHelloFunction(
   if (!existsSync(join(dir, "functions/.env.local"))) {
     write("functions/.env.local", functionsEnvLocalTemplate())
   }
+  const denoTypes = ensureFunctionsDenoTypes(dir, join(dir, "functions"))
+  if (denoTypes.wroteDenoDts) file("created", "functions/deno.d.ts")
+  if (denoTypes.wroteTsconfig) file("created", "functions/tsconfig.json")
+  if (denoTypes.rootExclude === "updated") {
+    file("updated", 'tsconfig.json (exclude "functions")')
+  }
 }
 
 // ─── Templates ───────────────────────────────────────────────────────────────
@@ -1182,13 +1190,28 @@ export type SiteSettings = Model<{
 
 function envTemplate(opts: ScaffoldOptions): string {
   const sections: string[] = []
-  sections.push(`DATABASE_URL=postgresql://supatype_admin:postgres@localhost:5432/${opts.projectName}
-POSTGRES_USER=supatype_admin
-POSTGRES_PASSWORD=postgres
-POSTGRES_DB=${opts.projectName}`)
+  // Generated, not constant. These reach a server: the previous defaults meant a self-host
+  // deployment ran with a password of `postgres` and a JWT secret published in this repo —
+  // and anyone holding that secret can mint a token naming any Postgres role. Safe to generate
+  // only because `supatype dev` no longer overwrites them on every run (see local-secrets.ts).
+  const postgresPassword = randomBytes(24).toString("base64url")
 
-  sections.push(`# JWT — run \`supatype keys\` to generate ANON_KEY and SERVICE_ROLE_KEY
-JWT_SECRET=super-secret-jwt-token-change-in-production
+  sections.push(`DATABASE_URL=postgresql://supatype_admin:${postgresPassword}@localhost:5432/${opts.projectName}
+POSTGRES_USER=supatype_admin
+POSTGRES_PASSWORD=${postgresPassword}
+POSTGRES_DB=${opts.projectName}
+
+# PostgREST's own database credential. It connects as \`authenticator\`, a role that holds no
+# privileges and can only switch to anon/authenticated/service_role — so a request whose JWT
+# names any other role is refused by Postgres rather than honoured.
+#
+# Deliberately NOT the same as POSTGRES_PASSWORD: that one is yours, for direct SQL access, and
+# rotating it should never take the REST API down with it.
+AUTHENTICATOR_PASSWORD=${randomBytes(24).toString("base64url")}`)
+
+  sections.push(`# JWT — ANON_KEY and SERVICE_ROLE_KEY are derived from this secret.
+# Changing it invalidates every issued token; re-run \`supatype keys\` afterwards.
+JWT_SECRET=${randomBytes(48).toString("base64url")}
 ANON_KEY=
 SERVICE_ROLE_KEY=`)
 
@@ -1340,16 +1363,17 @@ function helloFunctionTemplate(): string {
 
 export default async function handler(req: Request): Promise<Response> {
   const { method } = req
+  const url = Deno.env.get("SUPATYPE_URL")
 
   if (method === "POST") {
     const body = await req.json()
-    return new Response(JSON.stringify({ message: "Hello from hello!", received: body }), {
+    return new Response(JSON.stringify({ message: "Hello from hello!", received: body, url }), {
       status: 200,
       headers: { "Content-Type": "application/json" },
     })
   }
 
-  return new Response(JSON.stringify({ message: "Hello from hello!" }), {
+  return new Response(JSON.stringify({ message: "Hello from hello!", url }), {
     status: 200,
     headers: { "Content-Type": "application/json" },
   })
@@ -1435,6 +1459,16 @@ function printNextSteps(args: {
   info(`Supatype project ready${name ? ` in ${name}/` : ""}.`)
   nextSteps(setupComplete ? "Next steps:" : "Finish setup:", steps)
 
+  // Shown once, at creation. These are generated per project rather than shipped as
+  // constants, so this is the moment to say they exist and where they live — nothing prints
+  // them again, and the JWT secret is only echoed as a fingerprint from here on.
+  nextSteps("Secrets — generated for this project, kept in .env:", [
+    "POSTGRES_PASSWORD    direct SQL access as the superuser",
+    "AUTHENTICATOR_PASSWORD    PostgREST's own login; rotating the one above does not affect it",
+    "JWT_SECRET    signs ANON_KEY and SERVICE_ROLE_KEY; changing it invalidates every token",
+    "Keep .env out of version control, and use different values in production.",
+  ])
+
   if (result.app.mode === "none") {
     nextSteps("Static frontend (self-host):", [
       "supatype app add --static ./public",

package/src/commands/internal.ts

@@ -0,0 +1,23 @@
+/**
+ * Hidden internal commands (Homebrew post_install, etc.).
+ */
+
+import type { Command } from "commander"
+import { downloadAll } from "../binary-cache.js"
+import { error, info } from "../ui/messages.js"
+
+export function registerInternalCommands(program: Command): void {
+  program
+    .command("_postinstall", { hidden: true })
+    .description("Prefetch CDN component binaries after install (Homebrew post_install)")
+    .action(async () => {
+      try {
+        info("Prefetching Supatype component binaries for this platform...")
+        await downloadAll(undefined, true)
+        info("Component prefetch complete.")
+      } catch (err) {
+        error(err instanceof Error ? err.message : String(err))
+        process.exit(1)
+      }
+    })
+}

package/src/commands/link-helpers.ts

@@ -1,5 +1,6 @@
 import type { Command } from "commander"
 import { loadConfig } from "../config.js"
+import { loadCloudCredentials } from "../cloud-credentials.js"
 import {
   createCloudLink,
   createSelfHostLink,
@@ -23,7 +24,8 @@ function resolveLinkToken(opts: {
     opts.serviceRoleKey ??
     process.env["SUPATYPE_ACCESS_TOKEN"] ??
     process.env["SUPATYPE_TOKEN"] ??
-    process.env["SERVICE_ROLE_KEY"]
+    process.env["SERVICE_ROLE_KEY"] ??
+    loadCloudCredentials()?.accessToken
   )
 }
 
@@ -211,11 +213,15 @@ export async function runLinkAction(opts: {
   }
 
   if (!token) {
-    error("Authentication required. Set SUPATYPE_ACCESS_TOKEN or pass --token.")
+    error("Authentication required. Run: supatype login  (or set SUPATYPE_ACCESS_TOKEN / pass --token).")
     process.exit(1)
   }
 
   const cloudApiUrl = opts.apiUrl.replace(/\/$/, "")
+  const creds = loadCloudCredentials()
+  const refreshToken =
+    (creds?.apiUrl.replace(/\/$/, "") === cloudApiUrl ? creds.refreshToken : undefined) ??
+    existing?.refreshToken
 
   if (project) {
     const one = await targetFetch<{ slug: string; orgId: string }>(cloudApiUrl, "/api/v1", {
@@ -250,6 +256,7 @@ export async function runLinkAction(opts: {
       orgId: one.orgId,
       environments,
       existing,
+      ...(refreshToken !== undefined ? { refreshToken } : {}),
     })
     saveProjectLink(cwd, link)
     info(`Linked to cloud project: ${project}`)

package/src/commands/login.ts

@@ -0,0 +1,127 @@
+/**
+ * Cloud session login / logout for CLI control-plane auth.
+ * Self-host uses SERVICE_ROLE_KEY via `supatype link --url` — not this command.
+ */
+import type { Command } from "commander"
+import {
+  clearCloudCredentials,
+  cloudPasswordLogin,
+  loadCloudCredentials,
+  persistCloudSession,
+} from "../cloud-credentials.js"
+import { loadProjectLink, saveProjectLink } from "../link.js"
+import { isInteractive } from "../ui/interactive.js"
+import { error, info, plain } from "../ui/messages.js"
+import { ensureNotCancelled, p, printLogo, runClackFlow } from "../ui/prompts.js"
+
+function defaultApiUrl(cwd: string, flag?: string): string {
+  if (flag?.trim()) return flag.trim().replace(/\/$/, "")
+  const link = loadProjectLink(cwd)
+  if (link?.kind === "cloud" && link.cloudApiUrl) {
+    return link.cloudApiUrl.replace(/\/$/, "")
+  }
+  return (process.env["SUPATYPE_API_URL"] ?? "https://api.supatype.com").replace(/\/$/, "")
+}
+
+export function registerLogin(program: Command): void {
+  program
+    .command("login")
+    .description("Sign in to Supatype Cloud (stores refreshable session for push/deploy)")
+    .option("--api-url <url>", "Cloud control plane API URL")
+    .option("--email <email>", "Account email (non-interactive)")
+    .option("--password <password>", "Account password (prefer SUPATYPE_PASSWORD)")
+    .action(async (opts: { apiUrl?: string; email?: string; password?: string }) => {
+      const cwd = process.cwd()
+      const apiUrl = defaultApiUrl(cwd, opts.apiUrl)
+
+      let email = opts.email?.trim() ?? process.env["SUPATYPE_EMAIL"]?.trim()
+      let password =
+        opts.password ?? process.env["SUPATYPE_PASSWORD"] ?? process.env["SUPATYPE_LOGIN_PASSWORD"]
+
+      if ((!email || !password) && isInteractive()) {
+        await runClackFlow(async () => {
+          printLogo()
+          p.intro("Supatype Cloud login")
+          if (!email) {
+            email = ensureNotCancelled(
+              await p.text({
+                message: "Email",
+                placeholder: "you@example.com",
+              }),
+            ).trim()
+          }
+          if (!password) {
+            password = ensureNotCancelled(await p.password({ message: "Password" }))
+          }
+          p.outro("Signing in...")
+        })
+      }
+
+      if (!email || !password) {
+        error(
+          "Email and password required. Pass --email / --password, set SUPATYPE_EMAIL + SUPATYPE_PASSWORD, or run interactively.",
+        )
+        process.exit(1)
+      }
+
+      try {
+        const session = await cloudPasswordLogin(apiUrl, email, password)
+        persistCloudSession(cwd, {
+          apiUrl,
+          accessToken: session.accessToken,
+          ...(session.refreshToken !== undefined ? { refreshToken: session.refreshToken } : {}),
+          ...(session.email !== undefined ? { email: session.email } : { email }),
+        })
+        const link = loadProjectLink(cwd)
+        info(`Logged in to ${apiUrl}${session.email ? ` as ${session.email}` : ""}`)
+        if (link?.kind === "cloud") {
+          info(`Updated cloud session for linked project ${link.projectRef}`)
+        } else if (!session.refreshToken) {
+          plain("Warning: no refresh_token returned — session may expire in ~1h. Update control plane.")
+        } else {
+          plain("Tip: link a project with: supatype link --project <slug>")
+        }
+      } catch (err) {
+        error((err as Error).message)
+        process.exit(1)
+      }
+    })
+
+  program
+    .command("logout")
+    .description("Clear stored Supatype Cloud credentials")
+    .action(() => {
+      const cwd = process.cwd()
+      clearCloudCredentials()
+      const link = loadProjectLink(cwd)
+      if (link?.kind === "cloud") {
+        delete link.token
+        delete link.refreshToken
+        saveProjectLink(cwd, link)
+      }
+      info("Logged out of Supatype Cloud.")
+    })
+
+  program
+    .command("whoami")
+    .description("Show the current Supatype Cloud session")
+    .action(() => {
+      const creds = loadCloudCredentials()
+      const cwd = process.cwd()
+      const link = loadProjectLink(cwd)
+      if (!creds && !(link?.kind === "cloud" && link.token)) {
+        info("Not logged in. Run: supatype login")
+        return
+      }
+      if (creds) {
+        plain(`API:   ${creds.apiUrl}`)
+        if (creds.email) plain(`Email: ${creds.email}`)
+        plain(`Refresh token: ${creds.refreshToken ? "yes" : "no"}`)
+        plain(`Updated: ${creds.updatedAt}`)
+      }
+      if (link?.kind === "cloud") {
+        plain(`Linked project: ${link.projectRef}`)
+        plain(`Link has refresh token: ${link.refreshToken ? "yes" : "no"}`)
+      }
+    })
+}

package/src/commands/push.ts

@@ -1,8 +1,17 @@
 import type { Command } from "commander"
-import { mkdirSync, writeFileSync } from "node:fs"
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
 import { join } from "node:path"
 import { loadConfig, loadSchemaAst } from "../config.js"
-import { resolveRuntimeProvider, schemaPathFromProject, serverBaseUrl } from "../project-config.js"
+import { syncManifestHooks, validateModelHooks, writeHooksModule } from "../model-hooks.js"
+import { adapterEntry, readHookUpload } from "../hook-upload.js"
+import { checkServiceRoleRoutes, serviceRoleProblemLines } from "../service-role-check.js"
+import { fatalError } from "../ui/fatal.js"
+import {
+  hooksPathFromProject,
+  resolveRuntimeProvider,
+  schemaPathFromProject,
+  serverBaseUrl,
+} from "../project-config.js"
 import { ensureEngine, engineRequest, type DiffResult } from "../engine-client.js"
 import { printDiffOperations, printDiffWarnings } from "../diff-output.js"
 import { signJwt } from "../jwt.js"
@@ -20,6 +29,7 @@ import {
   type DeployTarget,
 } from "../resolve-target.js"
 import { loadProjectLink } from "../link.js"
+import { targetFetch } from "../target-client.js"
 import {
   buildSchemaSourcesPayload,
   cacheSchemaSourcesLocally,
@@ -54,6 +64,8 @@ export function registerPush(program: Command): void {
       const config = loadConfig(cwd)
       const pgSchema = schemaPgSchema(cwd)
       const ast = loadSchemaAst(schemaPathFromProject(config, cwd), cwd)
+      assertModelHooksResolve(cwd, config, ast)
+      assertServiceRoleGrantsResolve(cwd, config)
 
       const linked = loadProjectLink(cwd)
       const useDirect = opts.direct || opts.local || Boolean(opts.connection)
@@ -143,6 +155,10 @@ async function pushViaTarget(
     }
   }
 
+  if (target.mode === "cloud" || target.mode === "self-host") {
+    await deployHooksToTarget(cwd, config, target, ast)
+  }
+
   if (target.mode === "direct" || target.mode === "local") {
     await writeLocalAdminConfig(ast, config)
     if (target.databaseUrl) {
@@ -150,17 +166,86 @@ async function pushViaTarget(
     }
     await generateTypesLocal(ast, config)
     await provisionLocalStorage(ast, config)
-  } else {
-    info(`Pushed to ${target.mode} (${target.environment}).`)
+
+    // Local Studio only — a cloud/self-host push must not advertise the local
+    // gateway URL from config, which may not even be running.
+    const baseUrl = (serverBaseUrl(config) ?? "").replace(/\/$/, "")
+    if (baseUrl) {
+      plain(`\nStudio: ${baseUrl}/studio/`)
+    }
+    return
   }
 
-  const baseUrl = (serverBaseUrl(config) ?? "").replace(/\/$/, "")
-  if (baseUrl) {
-    plain(`\nStudio: ${baseUrl}/studio/`)
+  info(`Pushed to ${target.mode} (${target.environment}).`)
+  const envUrl = target.link?.environments?.[target.environment]?.apiUrl?.replace(/\/$/, "")
+  if (envUrl) {
+    plain(`\nProject API: ${envUrl}`)
   }
 }
 
+/**
+ * Upload the hooks this schema names to a managed stack.
+ *
+ * On `push` rather than `functions deploy`, because the hook *map* comes from the schema: the two have
+ * to move together, and a map naming a handler that was never uploaded turns every write to that table
+ * into a 503.
+ *
+ * The handler types are written locally as well. A project pushing to cloud still edits its hooks on
+ * this machine, and `hooks/_supatype/hooks.ts` is what makes them typed — it is generated, never
+ * committed, so a fresh clone that has only ever pushed to cloud would otherwise have no types at all.
+ */
+async function deployHooksToTarget(
+  cwd: string,
+  config: SupatypeProjectConfig,
+  target: DeployTarget,
+  ast: unknown,
+): Promise<void> {
+  const hooksDir = hooksPathFromProject(config, cwd)
+  const hooksPath = writeHooksModule(cwd, hooksDir, ast)
+  if (hooksPath !== null) info(`Hook handler types written to ${hooksPath}`)
+
+  let upload: ReturnType<typeof readHookUpload>
+  try {
+    upload = readHookUpload(cwd, hooksDir, ast)
+  } catch (err) {
+    // Refused rather than partially uploaded: the schema is already applied, so the honest thing is to
+    // say the hooks did not deploy and why, leaving the previous ones in place.
+    fatalError(err instanceof Error ? err.message : String(err))
+    return
+  }
+  if (upload === null) return
+
+  const adapter = readGeneratedAdapter(hooksDir)
+  const handlers = adapter === null ? upload.handlers : [...upload.handlers, adapter]
+
+  await withSpinner(`Deploying ${upload.handlers.length} hook(s)`, () =>
+    targetFetch(target.apiBaseUrl, target.apiPrefix, {
+      method: "POST",
+      path: `/projects/${target.projectRef}/hooks/deploy`,
+      body: { handlers, map: upload.map },
+      token: target.token!,
+      orgId: target.orgId,
+      environment: target.mode === "cloud" ? target.environment : undefined,
+    }),
+  ).then(() => info(`Deployed ${upload.handlers.length} hook(s)`))
+}
+
+/** The generated adapter, flattened to the name handlers were rewritten to import. */
+function readGeneratedAdapter(hooksDir: string): { name: string; source: string } | null {
+  const file = join(hooksDir, "_supatype", "hooks.ts")
+  if (!existsSync(file)) return null
+  return adapterEntry(readFileSync(file, "utf8"))
+}
+
 async function generateTypesLocal(ast: unknown, config: SupatypeProjectConfig): Promise<void> {
+  // Independent of `output`: a project with hooks needs its handler types whether or not it asked
+  // for client types, and the module is written next to the functions that import it.
+  const cwd = process.cwd()
+  const hooksPath = writeHooksModule(cwd, hooksPathFromProject(config, cwd), ast)
+  if (hooksPath !== null) info(`Hook handler types written to ${hooksPath}`)
+  // The server watches this file, so a changed hook takes effect without a restart.
+  if (syncManifestHooks(cwd, ast)) info("Hook map written to .supatype/manifest.json")
+
   if (!config.output?.types && !config.output?.client) return
   await withSpinner("Generating types", async () => {
     await ensureEngine()
@@ -195,3 +280,35 @@ async function writeLocalAdminConfig(ast: unknown, config: SupatypeProjectConfig
   restoreSystemRelationTargets(admin, ast)
   writeFileSync(join(dir, "admin-config.json"), `${JSON.stringify(admin, null, 2)}\n`)
 }
+
+/**
+ * Stop the push when a declared hook names a function that is not there.
+ *
+ * A hook is only enforcement if it runs. A typo'd name would extract cleanly, reach the manifest, and
+ * then never fire — so the write it was meant to validate would succeed and look fine. Cheaper to
+ * fail here, naming the directory searched.
+ */
+/**
+ * Refuse a push whose `functions.serviceRole` names a function that does not exist.
+ *
+ * The grant fails closed, which is the safe direction and the invisible one: the function reads no key
+ * at runtime, in a deploy that reported success. A warning is printed for an entry that is merely
+ * redundant, since a reader would reasonably assume the line is what does the granting.
+ */
+function assertServiceRoleGrantsResolve(cwd: string, config: SupatypeProjectConfig): void {
+  const problems = checkServiceRoleRoutes(config, cwd)
+  for (const warning of problems.warnings) plain(warning)
+  const lines = serviceRoleProblemLines(problems)
+  if (lines.length === 0) return
+  fatalError("functions.serviceRole names a function that does not exist.", lines, {
+    brand: { intro: "Push" },
+  })
+}
+
+function assertModelHooksResolve(cwd: string, config: SupatypeProjectConfig, ast: unknown): void {
+  const problems = validateModelHooks(ast, hooksPathFromProject(config, cwd), cwd)
+  if (problems.length === 0) return
+  fatalError("A model declares a hook whose function does not exist.", problems, {
+    brand: { intro: "Push" },
+  })
+}