@supatype/cli 0.1.12 → 0.2.0

package/src/model-hooks.ts

@@ -164,16 +164,127 @@ export function manifestHooks(ast: unknown): Record<string, Record<string, Manif
   return out
 }
 
+
+/** One declared per-field validator. `event` is the field it checks, so reporting reads uniformly. */
+export interface DeclaredValidator {
+  model: string
+  field: string
+  function: string
+}
+
+/** Every per-field validator declared across the schema, in a stable order for reporting. */
+export function declaredValidators(ast: unknown): DeclaredValidator[] {
+  const models = (ast as { models?: unknown[] })?.models
+  if (!Array.isArray(models)) return []
+
+  const out: DeclaredValidator[] = []
+  for (const model of models) {
+    const shaped = model as {
+      name?: string
+      annotations?: { platform?: { validate?: Record<string, unknown> } }
+    }
+    const validators = shaped.annotations?.platform?.validate
+    if (typeof validators !== "object" || validators === null) continue
+
+    for (const [field, value] of Object.entries(validators)) {
+      const fn = (value as { function?: unknown })?.function
+      if (typeof fn === "string" && fn.length > 0) {
+        out.push({ model: shaped.name ?? "?", field, function: fn })
+      }
+    }
+  }
+  return out.sort((a, b) => `${a.model}.${a.field}`.localeCompare(`${b.model}.${b.field}`))
+}
+
+/**
+ * The validator map for `.supatype/manifest.json`, keyed by **table** then **column**.
+ *
+ * `onUnavailable` is written explicitly as `reject` rather than left to the server's default. The
+ * server does default that way, but its policy matches exact event names, and a validator that
+ * silently accepted a value because a new event name was missing from a switch is precisely the
+ * failure found when that path was built. Saying it here means neither side has to be right alone.
+ */
+export function manifestValidators(ast: unknown): Record<string, Record<string, ManifestHookEntry>> {
+  const models = (ast as { models?: unknown[] })?.models
+  if (!Array.isArray(models)) return {}
+
+  const out: Record<string, Record<string, ManifestHookEntry>> = {}
+  for (const model of models) {
+    const shaped = model as {
+      annotations?: {
+        db?: { tableName?: string }
+        platform?: { validate?: Record<string, { function?: string; timeout?: number }> }
+      }
+    }
+    const table = shaped.annotations?.db?.tableName
+    const validators = shaped.annotations?.platform?.validate
+    if (typeof table !== "string" || table.length === 0) continue
+    if (typeof validators !== "object" || validators === null) continue
+
+    const entries: Record<string, ManifestHookEntry> = {}
+    for (const [field, value] of Object.entries(validators)) {
+      const fn = value?.function
+      if (typeof fn !== "string" || fn.length === 0) continue
+      entries[field] = {
+        function: fn,
+        timeout: typeof value.timeout === "number" ? value.timeout : DEFAULT_HOOK_TIMEOUT_MS,
+        onUnavailable: "reject",
+      }
+    }
+    if (Object.keys(entries).length > 0) out[table] = entries
+  }
+  return out
+}
+
+/**
+ * Validators naming a function that does not exist, as lines for a push failure.
+ *
+ * Shares `availableFunctions` with the hook check, so "what counts as a function" cannot come to
+ * mean two things.
+ */
+export function validateModelValidators(
+  ast: unknown,
+  functionsDir: string,
+  cwd: string,
+): string[] {
+  const validators = declaredValidators(ast)
+  if (validators.length === 0) return []
+
+  const available = availableFunctions(functionsDir)
+  const known = new Set(available)
+  const missing = validators.filter((entry) => !known.has(entry.function))
+  if (missing.length === 0) return []
+
+  const where = relative(cwd, functionsDir) || functionsDir
+  const lines = missing.map(
+    (entry) =>
+      `  ${entry.model}.${entry.field} → "${entry.function}" (no ${where}/${entry.function}/index.ts)`,
+  )
+  lines.push("")
+  lines.push(
+    available.length > 0
+      ? `Functions found in ${where}: ${available.join(", ")}`
+      : `No functions found in ${where}. Create one with: supatype hooks new <name>`,
+  )
+  return lines
+}
+
 /** Well below the 10s edge-function ceiling, so a hung hook fails fast instead of holding a slot. */
 export const DEFAULT_HOOK_TIMEOUT_MS = 2000
 
 /**
- * Merge the hook map into an existing `.supatype/manifest.json`.
+ * Merge the hook and validator maps into an existing `.supatype/manifest.json`.
+ *
+ * Both keys are written here rather than in two functions, because they fail together and for the
+ * same reason: each is a map the server reads to decide what to call around a write, and a manifest
+ * carrying a stale one calls the wrong thing or nothing at all. A validator that is never called is
+ * the worse half of that: the schema says the field is checked, and no error appears anywhere,
+ * because the write simply succeeds.
  *
  * **Only updates a manifest that is already there.** Creating one from scratch here would be a
  * hazard: `functions_enabled` is a plain bool on the server's side, so a manifest carrying only
  * hooks would read as functions *disabled*, the exact defect this repo fixed a commit ago, arriving
- * by a different door. The compose path owns creation; this owns one key.
+ * by a different door. The compose path owns creation; this owns two keys.
  *
  * Returns true when the file was rewritten.
  */
@@ -189,17 +300,34 @@ export function syncManifestHooks(cwd: string, ast: unknown): boolean {
   }
   if (typeof parsed !== "object" || parsed === null) return false
 
-  const hooks = manifestHooks(ast)
-  const next = JSON.stringify(hooks)
-  const current = JSON.stringify(parsed["hooks"] ?? {})
-  if (next === current) return false
+  const changedHooks = applyManifestMap(parsed, "hooks", manifestHooks(ast))
+  const changedValidators = applyManifestMap(parsed, "validators", manifestValidators(ast))
+  if (!changedHooks && !changedValidators) return false
+
+  writeFileSync(manifestPath, `${JSON.stringify(parsed, null, 2)}\n`, "utf8")
+  return true
+}
+
+/**
+ * Set one manifest key to `map`, or remove it when the schema declares none.
+ *
+ * Removing rather than writing `{}` matters: the server distinguishes "no map" from "an empty map"
+ * when it decides whether the manifest predates the feature, and an empty object left behind by a
+ * schema that no longer declares any is not the same statement.
+ */
+function applyManifestMap(
+  manifest: Record<string, unknown>,
+  key: string,
+  map: Record<string, Record<string, ManifestHookEntry>>,
+): boolean {
+  const next = JSON.stringify(map)
+  if (next === JSON.stringify(manifest[key] ?? {})) return false
 
-  if (Object.keys(hooks).length === 0) {
-    delete parsed["hooks"]
+  if (Object.keys(map).length === 0) {
+    delete manifest[key]
   } else {
-    parsed["hooks"] = hooks
+    manifest[key] = map
   }
-  writeFileSync(manifestPath, `${JSON.stringify(parsed, null, 2)}\n`, "utf8")
   return true
 }
 
@@ -211,6 +339,18 @@ export interface HooksReport {
   functionsDisabled: boolean
   /** True when a manifest exists but carries no hook map, so the server has nothing to call. */
   mapMissing: boolean
+  /** Field validators declared across the schema. */
+  validators: DeclaredValidator[]
+  /**
+   * Validators whose function directory is missing.
+   *
+   * Reported apart from `missing` because the consequence is different and worth saying plainly: a
+   * missing hook is a lifecycle step that will not run, a missing validator is a field written
+   * unchecked.
+   */
+  validatorsMissing: DeclaredValidator[]
+  /** True when validators are declared and the manifest carries no validator map. */
+  validatorMapMissing: boolean
 }
 
 /**
@@ -225,15 +365,18 @@ export interface HooksReport {
  */
 export function hooksReport(cwd: string, functionsDir: string, ast: unknown): HooksReport {
   const declared = declaredHooks(ast)
+  const validators = declaredValidators(ast)
   const manifestPath = join(cwd, ".supatype", "manifest.json")
 
   let functionsDisabled = false
   let mapMissing = false
-  if (declared.length > 0 && existsSync(manifestPath)) {
+  let validatorMapMissing = false
+  if ((declared.length > 0 || validators.length > 0) && existsSync(manifestPath)) {
     try {
       const parsed = JSON.parse(readFileSync(manifestPath, "utf8")) as Record<string, unknown>
       functionsDisabled = parsed["functions_enabled"] === false
-      mapMissing = parsed["hooks"] === undefined
+      mapMissing = declared.length > 0 && parsed["hooks"] === undefined
+      validatorMapMissing = validators.length > 0 && parsed["validators"] === undefined
     } catch {
       // Unparseable: the server reports that far better than a doctor line could.
     }
@@ -256,5 +399,8 @@ export function hooksReport(cwd: string, functionsDir: string, ast: unknown): Ho
     missing: declared.filter((hook) => !known.has(hook.function)),
     functionsDisabled,
     mapMissing,
+    validators,
+    validatorsMissing: validators.filter((entry) => !known.has(entry.function)),
+    validatorMapMissing,
   }
 }

package/src/pgbouncer-userlist.ts

@@ -5,7 +5,7 @@ export function pgbouncerMd5Hash(password: string, username: string): string {
   return "md5" + createHash("md5").update(password + username).digest("hex")
 }
 
-/** Two roles used by local compose: superuser pools (GoTrue, engine) and PostgREST. */
+/** Two roles used by local compose: superuser pools (auth, engine) and PostgREST. */
 export function pgbouncerUserlistContent(pgPassword: string): string {
   return `# PgBouncer md5 userlist, matches supatype-cloud transaction pool (auth_type = md5).
 # Regenerated by supatype dev --local / init from POSTGRES_PASSWORD.

package/src/postgres-ctl.ts

@@ -168,23 +168,63 @@ export async function waitReady(opts: PgOptions, timeoutMs = 10_000): Promise<vo
 // ---------------------------------------------------------------------------
 
 /**
- * Returns true if a TCP listener is already bound to port on 127.0.0.1.
+ * Can this port be bound, on the addresses that matter?
+ *
+ *   - `0.0.0.0` is what Docker publishes on and what compose has to bind.
+ *   - `127.0.0.1` catches a listener bound to loopback only, which a wildcard bind can be allowed
+ *     to sit alongside on some platforms.
  */
-export async function isPortInUse(port: number): Promise<boolean> {
+async function bindFails(port: number, host: string): Promise<boolean> {
   const { createServer } = await import("node:net")
   return new Promise((resolve) => {
     const server = createServer()
     server.once("error", (err: NodeJS.ErrnoException) => {
-      // EADDRINUSE: something is listening. EACCES, Windows excluded/reserved port range.
+      // EADDRINUSE: something is listening. EACCES: Windows excluded/reserved port range.
       resolve(err.code === "EADDRINUSE" || err.code === "EACCES")
     })
     server.once("listening", () => {
       server.close(() => resolve(false))
     })
-    server.listen(port, "127.0.0.1")
+    server.listen(port, host)
   })
 }
 
+/**
+ * Is something answering on this port?
+ *
+ * Binding is not enough on its own. Docker Desktop publishes through a proxy that does not hold a
+ * bind a normal socket can see, so `bindFails` succeeds while nginx on that port answers HTTP 200.
+ * Measured on Windows: bind says free, curl says 200. `supatype dev` believed the bind, handed the
+ * port to compose, and compose failed with "Bind for 0.0.0.0:5432 failed: port is already
+ * allocated". Connecting is what notices.
+ */
+async function connectSucceeds(port: number, timeoutMs = 400): Promise<boolean> {
+  const { connect } = await import("node:net")
+  return new Promise((resolve) => {
+    const socket = connect({ port, host: "127.0.0.1" })
+    const done = (answer: boolean): void => {
+      socket.destroy()
+      resolve(answer)
+    }
+    socket.setTimeout(timeoutMs)
+    socket.once("connect", () => done(true))
+    socket.once("timeout", () => done(false))
+    socket.once("error", () => done(false))
+  })
+}
+
+/**
+ * True when the port cannot be used for a new listener.
+ *
+ * Either signal is enough. Reporting a port busy when it is usable costs an increment in
+ * `findNextFreePort`; reporting it free when it is not costs a failed `docker compose up`, which is
+ * the failure this exists to prevent.
+ */
+export async function isPortInUse(port: number): Promise<boolean> {
+  if (await connectSucceeds(port)) return true
+  return (await bindFails(port, "0.0.0.0")) || (await bindFails(port, "127.0.0.1"))
+}
+
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------

package/src/project-config.ts

@@ -157,13 +157,13 @@ export interface SupatypeProjectConfig {
     /**
      * Email delivery provider.
      * "console" = log to stdout (default for dev)
-     * "smtp"    = SMTP (set `smtp` below and/or GOTRUE_SMTP_* in `.env`)
+     * "smtp"    = SMTP (set `smtp` below and/or SUPATYPE_SMTP_* in `.env`)
      * "resend"  = Resend API (requires RESEND_API_KEY, RESEND_FROM)
      * "ses"     = AWS SES v2 (ambient credentials, requires SES_FROM)
      */
     provider: "console" | "smtp" | "resend" | "ses"
     /**
-     * SMTP settings for provider=smtp (merged into process env as GOTRUE_SMTP_*).
+     * SMTP settings for provider=smtp (merged into process env as SUPATYPE_SMTP_*).
      * Omitted keys can still be set via `.env` / shell.
      */
     smtp?: {
@@ -181,9 +181,9 @@ export interface SupatypeProjectConfig {
     /** From address for SES (provider=ses, or set SES_FROM env var). */
     ses_from?: string
     /**
-     * When true, `supatype dev` enables the GoTrue send-email HTTP hook pointing at this
+     * When true, `supatype dev` enables the send-email HTTP hook pointing at this
      * server's POST `/internal/v0hooks/send-email` (signed delivery, dev-only secret).
-     * Override `GOTRUE_HOOK_SEND_EMAIL_*` in `.env` if needed.
+     * Override `SUPATYPE_HOOK_SEND_EMAIL_*` in `.env` if needed.
      */
     send_email_hook?: boolean
     /**

package/src/resolve-target.ts

@@ -44,7 +44,7 @@ export interface DeployTarget {
   apiBaseUrl: string
   apiPrefix: "/api/v1" | "/platform/v1"
   token?: string | undefined
-  /** Cloud GoTrue refresh token (mode === "cloud" only). */
+  /** Cloud auth refresh token (mode === "cloud" only). */
   refreshToken?: string | undefined
   orgId?: string | undefined
   link: ProjectLink | null

package/src/schema-ast-v2.ts

@@ -3,8 +3,80 @@
  * Parsers build {@link ParsedField}; only `emitField` / `emitModel` / `emitSchema` produce JSON.
  */
 
+import type { FieldValidation } from "@supatype/types"
+
+// Re-exported so consumers of these AST types need no second import for the one field that is
+// declared elsewhere: the bound contract lives beside the modifiers that compile into it.
+export type { FieldValidation }
+
 export const AST_VERSION = 2 as const
 
+/**
+ * Every field kind the extractor can produce. **The registry, not a list.**
+ *
+ * A kind used to exist the moment someone wrote `scalar("newThing")` in the extractor's type switch,
+ * with nothing anywhere enumerating the set. That is how nine kinds came to accept a declared bound
+ * and silently enforce nothing: no code and no test could ask "what are all the kinds", so each was
+ * handled wherever someone happened to look.
+ *
+ * Naming a kind here is now the only way to create one, because {@link scalar} takes a `FieldKind`.
+ * Anything keyed by `Record<FieldKind, T>` is then exhaustive by the compiler rather than by
+ * somebody remembering: `BOUNDS_BY_KIND` in `field-bounds.ts` is the first such consumer, so adding
+ * a kind here fails the build until it is classified there.
+ */
+export const FIELD_KINDS = [
+  // Text-shaped
+  "text",
+  "email",
+  "url",
+  "slug",
+  "color",
+  "xml",
+  "ip",
+  "cidr",
+  "macaddr",
+  "tsQuery",
+  "tsVector",
+  "richText",
+  "bytes",
+  // Numeric
+  "integer",
+  "smallInt",
+  "bigInt",
+  "float",
+  "serial",
+  "bigSerial",
+  "decimal",
+  "money",
+  // Temporal
+  "datetime",
+  "timestamp",
+  "date",
+  "interval",
+  // Collections and structured values
+  "array",
+  "blocks",
+  "json",
+  "button",
+  "enum",
+  // Fixed-shape scalars
+  "boolean",
+  "uuid",
+  // Storage, spatial, plugin
+  "image",
+  "file",
+  "geo",
+  "vector",
+  "relation",
+  "custom",
+  // Composites, expanded into real columns before they reach a table
+  "timestamps",
+  "publishable",
+  "softDelete",
+] as const
+
+export type FieldKind = (typeof FIELD_KINDS)[number]
+
 export type DefaultAst =
   | { kind: "value"; value: string | number | boolean | null }
   | { kind: "now" }
@@ -49,6 +121,15 @@ export interface KernelFieldFacts {
   dimensions?: number
   blocks?: BlockDefinitionAst[]
   check?: string
+  validation?: FieldValidation
+  /**
+   * `JSON<T[]>` rather than `JSON<{...}>`, read from the declared type argument.
+   *
+   * Persisted because a model constraint naming this column with `ItemCount<>` has to resolve the
+   * same measure the field's own `MaxItems` would, and by then the type node is long gone. The
+   * engine never reads it: it receives the measure already resolved.
+   */
+  jsonArray?: boolean
   precision?: number
   scale?: number
   references?: string
@@ -64,7 +145,7 @@ export interface KernelFieldFacts {
 
 /** Internal parse result: not serialized. */
 export interface ParsedField {
-  kind: string
+  kind: FieldKind
   kernel: KernelFieldFacts
   db: DbFieldAnnotations
   platform: PlatformFieldAnnotations
@@ -87,8 +168,12 @@ export interface ModelAstV2 {
   fields: Record<string, FieldAstV2>
   options: Record<string, unknown>
   annotations: {
-    db: { tableName: string; indexes: unknown[] }
-    platform: { access: Record<string, unknown>; hooks?: Record<string, unknown> }
+    db: { tableName: string; indexes: unknown[]; constraints?: unknown[] }
+    platform: {
+      access: Record<string, unknown>
+      hooks?: Record<string, unknown>
+      validate?: Record<string, unknown>
+    }
   }
 }
 
@@ -110,7 +195,7 @@ export interface ExtractedSchemaAstV2 {
   defaultLocale?: string
 }
 
-const DEFAULT_DB_BY_KIND: Record<string, Partial<DbFieldAnnotations>> = {
+const DEFAULT_DB_BY_KIND: Partial<Record<FieldKind, Partial<DbFieldAnnotations>>> = {
   text: { pgType: "TEXT" },
   richText: { pgType: "JSONB" },
   integer: { pgType: "INTEGER" },
@@ -147,7 +232,7 @@ const DEFAULT_DB_BY_KIND: Record<string, Partial<DbFieldAnnotations>> = {
   blocks: { pgType: "JSONB" },
 }
 
-const DEFAULT_PLATFORM_BY_KIND: Record<string, Partial<PlatformFieldAnnotations>> = {
+const DEFAULT_PLATFORM_BY_KIND: Partial<Record<FieldKind, Partial<PlatformFieldAnnotations>>> = {
   richText: { editor: "rich" },
 }
 
@@ -165,9 +250,15 @@ function stripUndefined<T extends Record<string, unknown>>(obj: T): Partial<T> {
   return out as Partial<T>
 }
 
-/** Start a parsed field with kind defaults for db/platform namespaces. */
+/**
+ * Start a parsed field with kind defaults for db/platform namespaces.
+ *
+ * Takes a plain `string` rather than a `FieldKind` because it is also called with a kind read back
+ * off the wire, where the value came from JSON and carries no compile-time guarantee. The optional
+ * lookup plus the fallback is what makes an unrecognised one safe.
+ */
 export function defaultPgTypeForKind(kind: string): string {
-  return DEFAULT_DB_BY_KIND[kind]?.pgType ?? "TEXT"
+  return DEFAULT_DB_BY_KIND[kind as FieldKind]?.pgType ?? "TEXT"
 }
 
 /** Flat wire shape for fields nested inside `blocks` definitions (engine FieldAst serde). */
@@ -195,6 +286,7 @@ export function emitBlockNestedField(field: FieldAstV2): FieldAstV2 {
   if (field.srid !== undefined) wire.srid = field.srid
   if (field.dimensions !== undefined) wire.dimensions = field.dimensions
   if (field.check !== undefined) wire.check = field.check
+  if (field.validation !== undefined) wire.validation = field.validation
   if (field.precision !== undefined) wire.precision = field.precision
   if (field.scale !== undefined) wire.scale = field.scale
   if (field.sources !== undefined) wire.sources = field.sources
@@ -207,7 +299,7 @@ export function emitBlockNestedField(field: FieldAstV2): FieldAstV2 {
 }
 
 export function scalar(
-  kind: string,
+  kind: FieldKind,
   extra?: {
     kernel?: Partial<KernelFieldFacts>
     db?: Partial<DbFieldAnnotations>
@@ -267,6 +359,8 @@ export function emitField(parsed: ParsedField): FieldAstV2 {
     }))
   }
   if (kernel.check !== undefined) wire.check = kernel.check
+  if (kernel.validation !== undefined) wire.validation = kernel.validation
+  if (kernel.jsonArray === true) wire.jsonArray = true
   if (kernel.precision !== undefined) wire.precision = kernel.precision
   if (kernel.scale !== undefined) wire.scale = kernel.scale
   if (kernel.references !== undefined) wire.references = kernel.references
@@ -295,16 +389,26 @@ export function emitModel(
   access: Record<string, unknown>,
   indexes: unknown[] = [],
   hooks: Record<string, unknown> = {},
+  constraints: unknown[] = [],
+  validators: Record<string, unknown> = {},
 ): ModelAstV2 {
   return {
     name,
     fields,
     options,
     annotations: {
-      db: { tableName, indexes },
+      // Constraints sit in `db` beside `indexes`: both are things Postgres holds, unlike `access`
+      // and `hooks`, which the API layer enforces.
+      db: { tableName, indexes, ...(constraints.length > 0 && { constraints }) },
       // Hooks sit in `platform` beside `access`: they are an API-layer concern, not a column one,
       // supatype-server reads them, Postgres never sees them.
-      platform: { access, ...(Object.keys(hooks).length > 0 && { hooks }) },
+      // Validators sit in `platform` beside `hooks`: both are enforced by the API layer on the
+      // write path, and neither is something Postgres knows about.
+      platform: {
+        access,
+        ...(Object.keys(hooks).length > 0 && { hooks }),
+        ...(Object.keys(validators).length > 0 && { validate: validators }),
+      },
     },
   }
 }

package/src/self-host-compose.ts

@@ -297,11 +297,11 @@ export function renderSelfHostCompose(
   const kongMount = kongMountPath(cwd)
   const external = usesExternalDatabase(config)
   const ownerUrl = ownerDatabaseUrl(config)
-  // GoTrue's driver wants the `postgres://` spelling; an external URL is used as given.
-  const gotrueUrl = external ? ownerUrl : ownerDatabaseUrl(config, "postgres")
+  // the auth driver wants the `postgres://` spelling; an external URL is used as given.
+  const authUrl = external ? ownerUrl : ownerDatabaseUrl(config, "postgres")
   // An external URL may already carry query parameters (`?sslmode=require` is common on managed
   // providers), and appending a second `?` produces a DSN that fails to parse.
-  const gotrueSearchPathSeparator = externalDatabaseUrl(config)?.includes("?") ? "&" : "?"
+  const authSearchPathSeparator = externalDatabaseUrl(config)?.includes("?") ? "&" : "?"
   const postgrestUrl = postgrestDatabaseUrl(config)
   const devLocal = options?.devLocal === true
   const tlsEnabled = selfHostTlsEnabled(config, devLocal)
@@ -546,6 +546,14 @@ ${realtimeBlock}
 ${dbDependency}
   server:
     image: \${SUPATYPE_SERVER_IMAGE:-\${SUPATYPE_AUTH_IMAGE:-supatype/server:latest}}
+    # The server runs its migrations at boot on a connection of their own,
+    # and that path does not wait out a database that is still in recovery:
+    # it exits. Waiting for db to report healthy is not enough, because
+    # Postgres says healthy before it will accept these connections, and
+    # on a slow host the gap is wide enough to lose it for good. Bounded
+    # rather than unlimited, so a real misconfiguration still stops and
+    # stays visible instead of hiding in a crash loop.
+    restart: on-failure:5
 ${serverPorts}    volumes:
       - ${projectMount}:/project:ro
     working_dir: /project
@@ -567,20 +575,35 @@ ${realtimeServerEnv}
       SUPATYPE_CONTROL_PLANE_URL: http://control-plane:8080
       SUPATYPE_VALKEY_ADDR: valkey:6379
 ${appEnv}
-      GOTRUE_API_HOST: 0.0.0.0
-      GOTRUE_API_PORT: 9999
-      API_EXTERNAL_URL: \${API_EXTERNAL_URL:-${externalUrlFallback}}
-      GOTRUE_API_EXTERNAL_URL: \${API_EXTERNAL_URL:-${externalUrlFallback}}
-      GOTRUE_DB_DRIVER: postgres
-      GOTRUE_DB_DATABASE_URL: "${gotrueUrl}${gotrueSearchPathSeparator}search_path=auth"
-      GOTRUE_SITE_URL: \${SITE_URL:-${siteUrlFallback}}
-      GOTRUE_JWT_SECRET: \${JWT_SECRET:?JWT_SECRET is missing from .env}
-      GOTRUE_JWT_EXP: 3600
-      GOTRUE_JWT_AUD: authenticated
-      GOTRUE_JWT_DEFAULT_GROUP_NAME: authenticated
-      GOTRUE_JWT_ADMIN_ROLES: service_role,supatype_admin
-      GOTRUE_MAILER_AUTOCONFIRM: \${GOTRUE_MAILER_AUTOCONFIRM:-true}
-      GOTRUE_DISABLE_SIGNUP: \${DISABLE_SIGNUP:-false}
+      SUPATYPE_API_HOST: 0.0.0.0
+      SUPATYPE_API_PORT: 9999
+      SUPATYPE_API_EXTERNAL_URL: \${API_EXTERNAL_URL:-${externalUrlFallback}}
+      SUPATYPE_DB_DRIVER: postgres
+      SUPATYPE_DB_DATABASE_URL: "${authUrl}${authSearchPathSeparator}search_path=auth"
+      SUPATYPE_SITE_URL: \${SITE_URL:-${siteUrlFallback}}
+      SUPATYPE_JWT_SECRET: \${JWT_SECRET:?JWT_SECRET is missing from .env}
+      SUPATYPE_JWT_EXP: 3600
+      SUPATYPE_JWT_AUD: authenticated
+      SUPATYPE_JWT_DEFAULT_GROUP_NAME: authenticated
+      SUPATYPE_JWT_ADMIN_ROLES: service_role,supatype_admin
+      SUPATYPE_MAILER_AUTOCONFIRM: \${SUPATYPE_MAILER_AUTOCONFIRM:-true}
+      # email.provider and email.smtp are config, and nothing used to carry
+      # them here: with no provider and no SMTP host the auth service falls
+      # through to its noop client, so every message was dropped in silence and
+      # a project asking for smtp got the same nothing as one asking for console.
+      # The name really is MAILER_MAILER: the field is Mailer.MailerProvider.
+      SUPATYPE_MAILER_MAILER_PROVIDER: \${SUPATYPE_MAILER_MAILER_PROVIDER:-console}
+      SUPATYPE_SMTP_HOST: \${SUPATYPE_SMTP_HOST:-}
+      # 587, not empty: this one is an int on the server, and compose
+      # substitutes an unset variable as "", which fails to parse and takes
+      # the whole service down on boot. 587 is the server's own default, so
+      # leaving it unset now behaves exactly as it would with no value at all.
+      SUPATYPE_SMTP_PORT: \${SUPATYPE_SMTP_PORT:-587}
+      SUPATYPE_SMTP_USER: \${SUPATYPE_SMTP_USER:-}
+      SUPATYPE_SMTP_PASS: \${SUPATYPE_SMTP_PASS:-}
+      SUPATYPE_SMTP_ADMIN_EMAIL: \${SUPATYPE_SMTP_ADMIN_EMAIL:-}
+      SUPATYPE_SMTP_SENDER_NAME: \${SUPATYPE_SMTP_SENDER_NAME:-}
+      SUPATYPE_DISABLE_SIGNUP: \${DISABLE_SIGNUP:-false}
 ${devLocal ? "      STUDIO_OPEN_DEV: \"1\"\n" : ""}
     depends_on:
 ${dbDependencyClause}      valkey:
@@ -697,7 +720,7 @@ function ensureProjectFunctionsDir(cwd: string, config: SupatypeProjectConfig):
  *
  * The CLI resolves the URL from config; Compose substitutes `.env` at up-time. If the two disagree,
  * `push` migrates one database while the services serve another, which reads as data loss and
- * isn't. It also makes the generated GoTrue DSN wrong, since whether to append `search_path` with
+ * isn't. It also makes the generated auth DSN wrong, since whether to append `search_path` with
  * `?` or `&` is decided from the config URL's query string.
  */
 function assertExternalUrlMatchesEnv(cwd: string, config: SupatypeProjectConfig): void {

package/src/studio-dev-server.ts

@@ -9,7 +9,14 @@ export interface StudioDevServerOptions {
   cwd: string
   studioOverride: string
   pidDir: string
-  serviceRoleKey: string
+  /**
+   * The anon key, and only the anon key. Studio in the browser is an untrusted
+   * client: privileged calls go through /studio/proxy, which holds the service
+   * role key server-side and applies membership, role permissions and the audit
+   * trail. Studio refuses a service role key handed to the browser and says so
+   * loudly, which is what this used to trigger on every dev start.
+   */
+  anonKey: string
   /**
    * Where Vite proxies API requests (Kong gateway port for compose dev, or
    * supatype-server port for native `supatype dev`).
@@ -45,8 +52,7 @@ export function startStudioViteDevServer(opts: StudioDevServerOptions): ProcessM
       env: {
         VITE_SUPATYPE_URL: opts.viteSupatypeUrl,
         SUPATYPE_PROXY_TARGET: opts.proxyTarget,
-        VITE_SUPATYPE_ANON_KEY: opts.serviceRoleKey,
-        VITE_SUPATYPE_SERVICE_ROLE_KEY: opts.serviceRoleKey,
+        VITE_SUPATYPE_ANON_KEY: opts.anonKey,
         VITE_BASE_PATH: basePath,
       },
     },