@supatype/cli 0.1.13 → 0.2.0

package/src/compose-services.ts

@@ -0,0 +1,174 @@
+/**
+ * What the local stack is actually running, asked of Docker rather than guessed.
+ *
+ * `status` and `logs` each used to carry a hardcoded list of container names.
+ * Both lists were wrong: they named containers the compose file does not create
+ * (`supatype-postgres`, `supatype-kong`), omitted every service it does create
+ * (`server`, `storage`, `functions-worker`, `schema-engine`, `valkey`), and used
+ * a naming scheme the compose file never applies, since it sets no
+ * `container_name` and Docker therefore names containers
+ * `<project>-<service>-<n>`.
+ *
+ * A list of services in the source is a list that goes stale the next time the
+ * stack changes shape. `docker compose ps` cannot.
+ */
+import { spawnSync } from "node:child_process"
+import { existsSync } from "node:fs"
+import { loadConfig } from "./config.js"
+import { composeProjectName, selfHostComposePaths } from "./self-host-compose.js"
+
+/** Where the local stack's compose file is, and what project name it runs under. */
+export interface ComposeContext {
+  composePath: string
+  projectRoot: string
+  projectName: string
+}
+
+/** One service in the local stack. */
+export interface ComposeService {
+  /** The compose service name, which is what `logs --service` takes. */
+  service: string
+  /** The container Docker created for it, if any. */
+  container: string
+  /** Docker's own word: running, exited, created, restarting, and so on. */
+  state: string
+  /** Published ports, as Docker reports them. */
+  ports: string
+  /** How long it has been up, as Docker reports it. */
+  status: string
+}
+
+/**
+ * composeContext locates the generated compose file for this project.
+ *
+ * Returns undefined when the stack has never been generated, which is the
+ * ordinary case in a project that only uses `supatype dev`.
+ */
+export function composeContext(cwd: string): ComposeContext | undefined {
+  const paths = selfHostComposePaths(cwd)
+  if (!existsSync(paths.composePath)) return undefined
+
+  let projectName = "supatype"
+  try {
+    const config = loadConfig(cwd)
+    if (config) projectName = composeProjectName(config.project.name)
+  } catch {
+    // A project whose config will not load can still have a running stack, and
+    // reporting on it is more useful than refusing to.
+  }
+  return { composePath: paths.composePath, projectRoot: cwd, projectName }
+}
+
+/**
+ * composeServices asks Docker what the stack is running.
+ *
+ * `--all` so a stopped service is reported as stopped rather than vanishing,
+ * which is the question `supatype status` is usually asked.
+ */
+export function composeServices(ctx: ComposeContext): ComposeService[] {
+  const result = spawnSync("docker", [...composeArgs(ctx), "ps", "--all", "--format", "json"], {
+    encoding: "utf8",
+    timeout: 15_000,
+  })
+  if (result.status !== 0 || !result.stdout) return []
+  return parseComposePs(result.stdout)
+}
+
+/**
+ * parseComposePs reads `docker compose ps --format json`.
+ *
+ * Compose v2 emits one JSON object per line; some versions emit a single JSON
+ * array instead. Both are accepted, because which one you get depends on the
+ * Docker version the developer happens to have.
+ */
+export function parseComposePs(stdout: string): ComposeService[] {
+  const trimmed = stdout.trim()
+  if (trimmed === "") return []
+
+  const rows: unknown[] = []
+  if (trimmed.startsWith("[")) {
+    try {
+      const parsed: unknown = JSON.parse(trimmed)
+      if (Array.isArray(parsed)) rows.push(...parsed)
+    } catch {
+      return []
+    }
+  } else {
+    for (const line of trimmed.split("\n")) {
+      if (line.trim() === "") continue
+      try {
+        rows.push(JSON.parse(line))
+      } catch {
+        // A line that is not JSON is progress noise, not a service.
+      }
+    }
+  }
+
+  const services: ComposeService[] = []
+  for (const row of rows) {
+    if (typeof row !== "object" || row === null) continue
+    const record = row as Record<string, unknown>
+    const service = typeof record["Service"] === "string" ? record["Service"] : ""
+    if (service === "") continue
+    services.push({
+      service,
+      container: typeof record["Name"] === "string" ? record["Name"] : "",
+      state: typeof record["State"] === "string" ? record["State"] : "unknown",
+      ports: typeof record["Publishers"] === "string" ? record["Publishers"] : formatPorts(record["Publishers"]),
+      status: typeof record["Status"] === "string" ? record["Status"] : "",
+    })
+  }
+  services.sort((a, b) => a.service.localeCompare(b.service))
+  return services
+}
+
+/**
+ * formatPorts renders the structured Publishers array Compose emits, keeping
+ * only the ports actually reachable from the host.
+ */
+function formatPorts(publishers: unknown): string {
+  if (!Array.isArray(publishers)) return ""
+  const published: string[] = []
+  for (const entry of publishers) {
+    if (typeof entry !== "object" || entry === null) continue
+    const record = entry as Record<string, unknown>
+    const host = record["PublishedPort"]
+    const target = record["TargetPort"]
+    if (typeof host === "number" && host > 0 && typeof target === "number") {
+      published.push(`${host}->${target}`)
+    }
+  }
+  return [...new Set(published)].join(", ")
+}
+
+/**
+ * composeArgs is the invocation prefix every compose call needs.
+ *
+ * The compose file lives under `.supatype/self-host/`, so the project directory
+ * has to be given explicitly: without it Compose resolves relative build
+ * contexts and env files against the file's own directory rather than the
+ * project root.
+ */
+export function composeArgs(ctx: ComposeContext): string[] {
+  return ["compose", "-p", ctx.projectName, "--project-directory", ctx.projectRoot, "-f", ctx.composePath]
+}
+
+/**
+ * composeServiceNames lists the services the compose file defines.
+ *
+ * This is what `logs --service` should be validated against, not the running
+ * containers: a service that failed to start is exactly the one whose logs you
+ * want, and it has no container.
+ */
+export function composeServiceNames(ctx: ComposeContext): string[] {
+  const result = spawnSync("docker", [...composeArgs(ctx), "config", "--services"], {
+    encoding: "utf8",
+    timeout: 15_000,
+  })
+  if (result.status !== 0 || !result.stdout) return []
+  return result.stdout
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => line !== "")
+    .sort()
+}

package/src/config.ts

@@ -45,7 +45,7 @@ export interface SelfHostConfig {
    */
   services?: {
     db?: ServiceVersionPin
-    gotrue?: ServiceVersionPin
+    auth?: ServiceVersionPin
     postgrest?: ServiceVersionPin
     kong?: ServiceVersionPin
     caddy?: ServiceVersionPin

package/src/dev-compose.ts

@@ -144,7 +144,7 @@ export async function ensureDockerDbPublishedForHostEngine(
   }
 
   const project = composeProjectName(config.project.name)
-  const kongPort = await resolveKongPort(cwd)
+  const kongPort = await resolveKongPort(cwd, project)
   const devDbPort = await resolveDevDbPort(cwd)
 
   const now = Math.floor(Date.now() / 1000)
@@ -192,8 +192,40 @@ export async function resolveHostEngineDatabaseUrl(
   return connectionString(config)
 }
 
-async function resolveKongPort(cwd: string): Promise<number> {
-  return ensureKongPort(cwd, { context: "dev" })
+/**
+ * `email.provider` and `email.smtp` for the compose server service.
+ *
+ * The native dev path has mapped these since it existed; the compose path never
+ * did, so a project that asked for smtp got the auth service's noop client and
+ * no message at all. Console is the documented default, and it at least says
+ * that a message would have been sent.
+ */
+function composeMailerEnv(config: SupatypeProjectConfig): Record<string, string> {
+  const email = config.email
+  const out: Record<string, string> = {
+    // Mailer.MailerProvider, so the doubled word is the real name.
+    SUPATYPE_MAILER_MAILER_PROVIDER: email?.provider ?? "console",
+  }
+  const smtp = email?.smtp
+  if (email?.provider !== "smtp" || smtp === undefined) return out
+
+  if (smtp.host !== undefined && smtp.host !== "") out.SUPATYPE_SMTP_HOST = smtp.host
+  if (smtp.port !== undefined) out.SUPATYPE_SMTP_PORT = String(smtp.port)
+  if (smtp.user !== undefined && smtp.user !== "") out.SUPATYPE_SMTP_USER = smtp.user
+  if (smtp.pass !== undefined && smtp.pass !== "") out.SUPATYPE_SMTP_PASS = smtp.pass
+  if (smtp.admin_email !== undefined && smtp.admin_email !== "") {
+    out.SUPATYPE_SMTP_ADMIN_EMAIL = smtp.admin_email
+  }
+  if (smtp.sender_name !== undefined && smtp.sender_name !== "") {
+    out.SUPATYPE_SMTP_SENDER_NAME = smtp.sender_name
+  }
+  return out
+}
+
+async function resolveKongPort(cwd: string, composeProject?: string): Promise<number> {
+  // The compose project is passed so an already-running stack of *this* project counts as
+  // available rather than as a collision.
+  return ensureKongPort(cwd, { context: "dev", ...(composeProject !== undefined && { composeProject }) })
 }
 
 /**
@@ -265,7 +297,8 @@ export function upsertDevComposeEnv(
     SUPATYPE_KONG_PORT: String(kongPort),
     API_EXTERNAL_URL: apiUrl,
     SITE_URL: apiUrl,
-    GOTRUE_MAILER_AUTOCONFIRM: "true",
+    SUPATYPE_MAILER_AUTOCONFIRM: "true",
+    ...composeMailerEnv(config),
     ...imagePins,
   }
   // Never for an external database: this URL describes the `db` container, which that project does
@@ -390,21 +423,98 @@ function dumpComposeDbLogs(
   console.error(tail)
 }
 
-async function waitKongReady(kongPort: number, maxSec: number): Promise<void> {
-  const base = `http://localhost:${kongPort}`
+/**
+ * The gateway as the CLI reaches it, over IPv4.
+ *
+ * Not `localhost`. Docker publishes on `0.0.0.0`, so the IPv4 address is the one that is certainly
+ * bound, while `localhost` resolves to `::1` first on Windows and macOS. Docker Desktop does forward
+ * IPv6 through a relay, and when that relay is unhealthy it accepts the connection and then never
+ * answers, so every readiness poll hangs rather than failing.
+ *
+ * The URLs written to `.env` and printed for the operator stay on `localhost`: those are for a
+ * browser, where the name is the friendlier thing to see and the browser will fall back on its own.
+ */
+function loopbackBase(port: number): string {
+  return `http://127.0.0.1:${port}`
+}
+
+/**
+ * `fetch` with a deadline, because the built-in has none.
+ *
+ * A poll loop bounded by `maxSec` iterations is only bounded if each attempt can end. Against a
+ * socket that accepts and never responds, an un-timed `fetch` never settles, the loop never reaches
+ * its second iteration, and a wait advertised as 120 seconds runs until someone kills it. That is
+ * how `supatype push` came to hang indefinitely after reporting the schema applied.
+ */
+async function fetchWithin(url: string, ms: number, init?: RequestInit): Promise<Response> {
+  return await fetch(url, { ...init, signal: AbortSignal.timeout(ms) })
+}
+
+/**
+ * Print what the stack is doing when the gateway never comes up.
+ *
+ * A 503 through the gateway means Kong is running and something behind it is
+ * not, and until now the only thing said was that the gateway was not ready.
+ * That sends people to look at Kong, which is almost never the problem, and in
+ * CI the containers are gone by the time anything else can inspect them.
+ */
+function reportUnhealthyStack(composePath: string, cwd: string, project: string): void {
+  const capture = (args: string[]): string => {
+    const result = spawnSync("docker", ["compose", "-p", project, "--project-directory", cwd, "-f", composePath, ...args], {
+      encoding: "utf8",
+      cwd,
+    })
+    return `${result.stdout ?? ""}${result.stderr ?? ""}`.trim()
+  }
+
+  console.error("")
+  console.error("[supatype] The gateway is up but a service behind it is not. Container state:")
+  const state = capture(["ps", "-a"])
+  console.error(state === "" ? "  (no containers)" : state)
+
+  // The two the gateway health check depends on, and db because both need it.
+  for (const service of ["server", "realtime", "db"]) {
+    const logs = capture(["logs", "--no-color", "--tail", "40", service])
+    if (logs === "") continue
+    console.error("")
+    console.error(`[supatype] last 40 lines from ${service}:`)
+    console.error(logs)
+  }
+  console.error("")
+}
+
+async function waitKongReady(
+  kongPort: number,
+  maxSec: number,
+  stack?: { composePath: string; cwd: string; project: string },
+): Promise<void> {
+  const base = loopbackBase(kongPort)
+  // Remembered so the failure can name the unhealthy upstream. Blaming "the
+  // Kong gateway" sent more than one investigation after Kong when Kong was
+  // fine and a service behind it was not.
+  let lastAuth = "no response"
+  let lastRealtime = "no response"
   for (let i = 0; i < maxSec; i++) {
     try {
       const [auth, realtime] = await Promise.all([
-        fetch(`${base}/auth/v1/health`),
-        fetch(`${base}/realtime/v1/health`),
+        fetchWithin(`${base}/auth/v1/health`, 2000),
+        fetchWithin(`${base}/realtime/v1/health`, 2000),
       ])
+      lastAuth = `HTTP ${auth.status}`
+      lastRealtime = `HTTP ${realtime.status}`
       if (auth.ok && realtime.ok) return
-    } catch {
-      /* retry */
+    } catch (err) {
+      lastAuth = lastRealtime = err instanceof Error ? err.message : String(err)
     }
     await new Promise((r) => setTimeout(r, 1000))
   }
-  throw new Error(`Kong gateway at ${base} did not become ready within ${maxSec}s`)
+  if (stack !== undefined) {
+    reportUnhealthyStack(stack.composePath, stack.cwd, stack.project)
+  }
+  throw new Error(
+    `Gateway at ${base} did not become ready within ${maxSec}s ` +
+      `(auth/v1/health: ${lastAuth}, realtime/v1/health: ${lastRealtime})`,
+  )
 }
 
 /** Kong may be up while server → storage is still starting (503 or upstream errors). */
@@ -413,11 +523,11 @@ async function waitStorageApiReady(
   serviceRoleKey: string,
   maxSec: number,
 ): Promise<void> {
-  const url = `http://localhost:${kongPort}/storage/v1/bucket`
+  const url = `${loopbackBase(kongPort)}/storage/v1/bucket`
   const headers = { Authorization: `Bearer ${serviceRoleKey}` }
   for (let i = 0; i < maxSec; i++) {
     try {
-      const res = await fetch(url, { headers })
+      const res = await fetchWithin(url, 2000, { headers })
       if (res.ok) return
       const body = await res.text()
       const kongUpstreamDown = body.includes("invalid response was received from the upstream server")
@@ -440,7 +550,7 @@ async function provisionDockerStorageBuckets(
   kongPort: number,
   serviceRoleKey: string,
 ): Promise<void> {
-  await provisionBucketsFromAst(ast, `http://localhost:${kongPort}/storage/v1`, serviceRoleKey)
+  await provisionBucketsFromAst(ast, `${loopbackBase(kongPort)}/storage/v1`, serviceRoleKey)
 }
 
 let _lastPushedAst: string | null = null
@@ -767,7 +877,7 @@ export async function diffSchemaDocker(cwd: string, config: SupatypeProjectConfi
     })
   }
 
-  const kongPort = await resolveKongPort(cwd)
+  const kongPort = await resolveKongPort(cwd, project)
   const now = Math.floor(Date.now() / 1000)
   const jwtBase = { iss: "supatype", iat: now, exp: now + 315_360_000 }
   const anonKey = signJwt({ ...jwtBase, role: "anon" }, devJwtSecret(cwd))
@@ -813,7 +923,7 @@ export async function pushSchemaDocker(cwd: string, config: SupatypeProjectConfi
     throw new Error("pushSchemaDocker requires provider: docker")
   }
   const project = composeProjectName(config.project.name)
-  const kongPort = await resolveKongPort(cwd)
+  const kongPort = await resolveKongPort(cwd, project)
   // No dev db port for an external database: `ensureDevDbPort` allocates a host port for the `db`
   // container *and persists a matching DATABASE_URL*, which overwrote the operator's own URL, the
   // one the whole stack and every CLI command reads.
@@ -845,7 +955,7 @@ export async function pushSchemaDocker(cwd: string, config: SupatypeProjectConfi
   if (upGateway !== 0) {
     exitComposeFailed(upGateway, "Could not start the Compose gateway stack.", pushBrand)
   }
-  await waitKongReady(kongPort, 120)
+  await waitKongReady(kongPort, 120, { composePath: paths.composePath, cwd, project })
   await waitStorageApiReady(kongPort, serviceRoleKey, 90)
   await provisionDockerStorageBuckets(ast, kongPort, serviceRoleKey)
 
@@ -864,7 +974,7 @@ export async function runDevCompose(cwd: string, config: SupatypeProjectConfig,
   // Per-project compose name + port isolate this project from any other Supatype
   // stack on the machine (own containers, volumes, network, and gateway port).
   const project = composeProjectName(config.project.name)
-  const kongPort = await resolveKongPort(cwd)
+  const kongPort = await resolveKongPort(cwd, project)
   // No dev db port for an external database: `ensureDevDbPort` allocates a host port for the `db`
   // container *and persists a matching DATABASE_URL*, which overwrote the operator's own URL, the
   // one the whole stack and every CLI command reads.
@@ -1022,7 +1132,7 @@ export async function runDevCompose(cwd: string, config: SupatypeProjectConfig,
   }
 
   console.log("[supatype] Waiting for API gateway...")
-  await waitKongReady(kongPort, 120)
+  await waitKongReady(kongPort, 120, { composePath: paths.composePath, cwd, project })
   console.log("[supatype] Waiting for storage API...")
   await waitStorageApiReady(kongPort, serviceRoleKey, 90)
 
@@ -1062,7 +1172,7 @@ export async function runDevCompose(cwd: string, config: SupatypeProjectConfig,
       cwd,
       studioOverride,
       pidDir,
-      serviceRoleKey,
+      anonKey,
       proxyTarget: `http://localhost:${kongPort}`,
       viteSupatypeUrl: `http://localhost:${STUDIO_DEV_PORT}`,
       basePath: "/studio/",

package/src/dev-ports.ts

@@ -4,6 +4,7 @@
  * availability so multiple projects and port collisions are surfaced clearly.
  */
 
+import { spawnSync } from "node:child_process"
 import { CLACK_CANCEL, isCancel, p } from "./ui/clack.js"
 import { COMPOSE_DEV_KONG_PORT } from "./project-config.js"
 import { isPortInUse } from "./postgres-ctl.js"
@@ -14,6 +15,41 @@ import { fatalError } from "./ui/fatal.js"
 const MIN_PORT = 1024
 const MAX_PORT = 65535
 
+/**
+ * Which compose project publishes a host port, from `docker ps` output.
+ *
+ * Separated from the spawn so the decision is testable: the question "is this port held by my own
+ * stack" is the whole point of the check, and a check that can only be exercised by starting Docker
+ * is a check nobody exercises.
+ *
+ * Docker prints one line per matching container, and a container with no compose label prints an
+ * empty line. Any line naming a different project means someone else holds the port.
+ */
+export function composeProjectOwnsPort(dockerPsOutput: string, project: string): boolean {
+  const owners = dockerPsOutput
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0)
+  return owners.length > 0 && owners.every((owner) => owner === project)
+}
+
+/**
+ * True when the container publishing `port` belongs to this project's compose stack.
+ *
+ * Asks Docker rather than probing the port over HTTP. A health check would answer just as happily
+ * for a *different* project's gateway on the same port, and proceeding there would push a schema
+ * into the wrong database. Refusing is the safe answer for a stranger; only our own stack is fine.
+ */
+export function portHeldByComposeProject(port: number, project: string): boolean {
+  const result = spawnSync(
+    "docker",
+    ["ps", "--filter", `publish=${port}`, "--format", '{{.Label "com.docker.compose.project"}}'],
+    { encoding: "utf8" },
+  )
+  if (result.status !== 0 || typeof result.stdout !== "string") return false
+  return composeProjectOwnsPort(result.stdout, project)
+}
+
 export function isValidHostPort(port: number): boolean {
   return Number.isInteger(port) && port >= MIN_PORT && port <= MAX_PORT
 }
@@ -62,6 +98,11 @@ export interface EnsureKongPortOptions {
   interactive?: boolean
   /** init wizard: slightly different copy */
   context?: "dev" | "init"
+  /**
+   * Compose project for this directory. When given, a port published by that project is accepted
+   * rather than refused: that is this project's own stack, not a stranger's.
+   */
+  composeProject?: string
 }
 
 /**
@@ -81,6 +122,13 @@ export async function ensureKongPort(
   if (persisted !== null) {
     if (!(await isPortInUse(persisted))) return persisted
 
+    // Occupied by this project's own stack is not a conflict, it is the normal state after
+    // `supatype self-host compose up -d`. Refusing here made a hand-run `up -d` followed by
+    // `push` impossible, and it stopped the validation soak, which does exactly that.
+    if (opts.composeProject !== undefined && portHeldByComposeProject(persisted, opts.composeProject)) {
+      return persisted
+    }
+
     if (!interactive) {
       fatalError(`Port ${persisted} is already in use (SUPATYPE_KONG_PORT in .env).`, [
         "Stop the other service or set a different SUPATYPE_KONG_PORT.",

package/src/docker-postgres.ts

@@ -256,7 +256,7 @@ export const DEFAULT_SERVER_DOCKER_IMAGE = "supatype/server:latest"
  * Run `supatype-server migrate` on the Postgres container network (loopback trust).
  * Used on Windows + database.provider docker, host-published :5432 breaks libpq TLS there.
  */
-export function runGotrueMigrationsViaDocker(
+export function runAuthMigrationsViaDocker(
   pgContainerName: string,
   serverImage: string,
   migrateEnv: Record<string, string>,
@@ -276,7 +276,7 @@ export function runGotrueMigrationsViaDocker(
   if (result.status !== 0) {
     const detail = (result.stderr ?? result.stdout ?? "").trim()
     throw new Error(
-      `GoTrue migrations failed in Docker (exit ${result.status ?? "unknown"})` +
+      `auth migrations failed in Docker (exit ${result.status ?? "unknown"})` +
         (detail ? `:\n${detail}` : ""),
     )
   }

package/src/engine-floor.ts

@@ -0,0 +1,113 @@
+/**
+ * The engine version a schema needs, checked before the engine is asked to apply it.
+ *
+ * Field bounds and model constraints compile to CHECK constraints that call helper functions in
+ * the `_supatype` schema, and only the engine creates those helpers. A CLI that emits the call
+ * against an engine that does not create the function produces this, three times, and then gives
+ * up:
+ *
+ *     Failed to apply migration
+ *     Caused by: error returned from database:
+ *       function _supatype.richtext_text(jsonb) does not exist
+ *
+ * Which says nothing about the cause. A project on `latest` is fine; the exposed case is a pin,
+ * `versions: { engine: "0.1.9" }`, where the CLI moved and the engine did not.
+ *
+ * The check is conditional on the schema, not a flat floor: a schema that declares no bounds and
+ * no model constraints works on an older engine, and refusing it would break projects for a
+ * feature they do not use.
+ *
+ * It reads the pin rather than asking a binary for its version, because the pin is what both paths
+ * resolve from: the native provider downloads that version, and the docker provider tags the
+ * compose image with it. An unpinned project resolves to latest, which is at or above the floor by
+ * definition, so there is nothing to check.
+ */
+import type { ExtractedSchemaAstV2, ModelAstV2 } from "./schema-ast-v2.js"
+
+/** First engine release that creates the `_supatype` constraint helpers (schema-engine v0.2.0). */
+export const ENGINE_MIN_FOR_BOUNDS = "0.2.0"
+
+/**
+ * Compare two dotted versions numerically. Returns <0, 0 or >0.
+ *
+ * Pre-release suffixes are dropped before comparing, so `0.2.0-rc.1` counts as `0.2.0`. That is
+ * deliberate: a release candidate of the engine that creates the helpers does create them, and
+ * refusing it would send someone testing a pre-release down a false trail.
+ */
+export function compareVersions(a: string, b: string): number {
+  const parts = (v: string): number[] =>
+    v
+      .trim()
+      .replace(/^v/, "")
+      .split("-")[0]!
+      .split(".")
+      .map((n) => Number.parseInt(n, 10))
+      .map((n) => (Number.isNaN(n) ? 0 : n))
+  const left = parts(a)
+  const right = parts(b)
+  for (let i = 0; i < Math.max(left.length, right.length); i += 1) {
+    const diff = (left[i] ?? 0) - (right[i] ?? 0)
+    if (diff !== 0) return diff
+  }
+  return 0
+}
+
+/** Field paths in the schema that declare a bound, as `model.field`, for naming them in an error. */
+function fieldsWithBounds(models: ModelAstV2[]): string[] {
+  const found: string[] = []
+  for (const model of models) {
+    for (const [fieldName, field] of Object.entries(model.fields)) {
+      if (Object.keys(field.validation ?? {}).length > 0) found.push(`${model.name}.${fieldName}`)
+    }
+  }
+  return found
+}
+
+/** Models declaring a constraint, which compiles to a table-level CHECK. */
+function modelsWithConstraints(models: ModelAstV2[]): string[] {
+  return models
+    .filter((model) => (model.annotations.db.constraints ?? []).length > 0)
+    .map((model) => model.name)
+}
+
+/**
+ * Everything in the schema that needs {@link ENGINE_MIN_FOR_BOUNDS}, or an empty array.
+ *
+ * Exported for the error message and for tests: a check nobody can see the input of is a check
+ * that gets deleted the first time it is inconvenient.
+ */
+export function boundsRequiringHelpers(ast: ExtractedSchemaAstV2): string[] {
+  return [...fieldsWithBounds(ast.models), ...modelsWithConstraints(ast.models)]
+}
+
+/**
+ * Refuse a push whose schema needs helpers this engine does not create.
+ *
+ * Takes the pin from `versions.engine`, or undefined when unpinned. See the note above on why
+ * that is the right source rather than the binary's own `--version`.
+ */
+export function assertEngineSupportsSchema(
+  ast: ExtractedSchemaAstV2,
+  pinnedEngineVersion: string | undefined,
+): void {
+  // Unpinned resolves to latest, and `local` points at a build whose version the config does not
+  // know. Neither can be compared, and neither is the case that breaks.
+  if (pinnedEngineVersion === undefined || pinnedEngineVersion === "local") return
+  if (compareVersions(pinnedEngineVersion, ENGINE_MIN_FOR_BOUNDS) >= 0) return
+
+  const needed = boundsRequiringHelpers(ast)
+  if (needed.length === 0) return
+
+  const shown = needed.slice(0, 3).join(", ")
+  const more = needed.length > 3 ? `, and ${needed.length - 3} more` : ""
+  throw new Error(
+    `This schema declares bounds that need schema-engine ${ENGINE_MIN_FOR_BOUNDS} or newer, ` +
+      `and this project pins ${pinnedEngineVersion}.\n\n` +
+      `  Declared on: ${shown}${more}\n\n` +
+      `Bounds compile to CHECK constraints that call helpers in the _supatype schema, and only ` +
+      `engine ${ENGINE_MIN_FOR_BOUNDS}+ creates them. Applying this would fail inside Postgres ` +
+      `with "function _supatype.richtext_text(jsonb) does not exist".\n\n` +
+      `Raise or remove the pin in supatype.config.ts:\n` +
+      `  versions: { engine: "${ENGINE_MIN_FOR_BOUNDS}" }   // or omit it to track latest`,
+  )
+}

package/src/link.ts

@@ -23,7 +23,7 @@ export interface ProjectLink {
   defaultEnvironment: string
   /** Access token (cloud user JWT) or self-host SERVICE_ROLE_KEY. */
   token?: string
-  /** Cloud GoTrue refresh token, used to renew short-lived access JWTs. */
+  /** Cloud auth refresh token, used to renew short-lived access JWTs. */
   refreshToken?: string
   orgId?: string | undefined
   cloudApiUrl?: string

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.