@supatype/cli 0.1.13 → 0.2.0

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/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,
       },
     },

package/tests/admin-ensure.test.ts

@@ -4,8 +4,8 @@ import {
   ADMIN_PASSWORD_ENV,
   clearAdminSeedPassword,
   composePostgresPassword,
-  GOTRUE_NIL_INSTANCE_ID,
-  gotrueJwtAud,
+  SUPATYPE_NIL_INSTANCE_ID,
+  authJwtAud,
   hashPasswordForAuth,
   resolveAuthConfirmedAtColumn,
 } from "../src/commands/admin.js"
@@ -65,13 +65,13 @@ describe("composePostgresPassword", () => {
   })
 })
 
-describe("gotrueJwtAud", () => {
-  it("reads GOTRUE_JWT_AUD from .env", () => {
+describe("authJwtAud", () => {
+  it("reads SUPATYPE_JWT_AUD from .env", () => {
     const dir = join(tmpdir(), `supatype-admin-aud-${Date.now()}`)
     mkdirSync(dir, { recursive: true })
-    writeFileSync(join(dir, ".env"), "GOTRUE_JWT_AUD=custom-aud\n", "utf8")
+    writeFileSync(join(dir, ".env"), "SUPATYPE_JWT_AUD=custom-aud\n", "utf8")
     try {
-      expect(gotrueJwtAud(dir)).toBe("custom-aud")
+      expect(authJwtAud(dir)).toBe("custom-aud")
     } finally {
       rmSync(dir, { recursive: true, force: true })
     }
@@ -81,16 +81,16 @@ describe("gotrueJwtAud", () => {
     const dir = join(tmpdir(), `supatype-admin-aud-default-${Date.now()}`)
     mkdirSync(dir, { recursive: true })
     try {
-      expect(gotrueJwtAud(dir)).toBe("authenticated")
+      expect(authJwtAud(dir)).toBe("authenticated")
     } finally {
       rmSync(dir, { recursive: true, force: true })
     }
   })
 })
 
-describe("GOTRUE_NIL_INSTANCE_ID", () => {
-  it("is the nil UUID GoTrue uses for lookup", () => {
-    expect(GOTRUE_NIL_INSTANCE_ID).toBe("00000000-0000-0000-0000-000000000000")
+describe("SUPATYPE_NIL_INSTANCE_ID", () => {
+  it("is the nil UUID the auth service uses for lookup", () => {
+    expect(SUPATYPE_NIL_INSTANCE_ID).toBe("00000000-0000-0000-0000-000000000000")
   })
 })
 

package/tests/compose-parsable-defaults.test.ts

@@ -0,0 +1,60 @@
+import { describe, it, expect } from "vitest"
+import { renderSelfHostCompose } from "../src/self-host-compose.js"
+import { validateProjectConfig, type SupatypeProjectConfig } from "../src/project-config.js"
+import { DENO_RELEASE_PIN } from "../src/release-pins.js"
+
+/**
+ * Compose must not hand the server a value it cannot parse.
+ *
+ * Every variable here is substituted by compose whether or not anyone set it,
+ * and an unset one becomes the empty string. That is harmless for a host or a
+ * password and fatal for a port: the server decodes it as an int, fails on "",
+ * and exits before it binds. The whole stack then presents as "the gateway
+ * never came up", which is a long way from the cause.
+ */
+const base = {
+  project: { name: "acme" },
+  server: { mode: "dev" as const },
+  app: { mode: "none" as const },
+  database: { provider: "docker" as const },
+  versions: {
+    postgres: "17.2",
+    deno: DENO_RELEASE_PIN,
+  },
+}
+
+const config = (): SupatypeProjectConfig => validateProjectConfig(base, "supatype.config.ts")
+
+/** The `KEY: ${VAR:-default}` lines from the rendered compose file. */
+function defaultsFor(compose: string): Map<string, string> {
+  const found = new Map<string, string>()
+  for (const line of compose.split("\n")) {
+    const match = /^\s*([A-Z_]+):\s*\$\{[A-Z_]+:-(.*)\}\s*$/.exec(line)
+    if (match?.[1] !== undefined) found.set(match[1], match[2] ?? "")
+  }
+  return found
+}
+
+describe("compose defaults the server has to be able to parse", () => {
+  it("gives SMTP_PORT a number, because an unset variable becomes an empty string", () => {
+    const defaults = defaultsFor(renderSelfHostCompose(config()))
+    const port = defaults.get("SUPATYPE_SMTP_PORT")
+
+    expect(port, "SUPATYPE_SMTP_PORT is missing from the compose file").toBeDefined()
+    expect(port, "an empty default makes the server exit on boot").not.toBe("")
+    expect(Number.isInteger(Number(port))).toBe(true)
+  })
+
+  it("leaves the string-valued mailer settings empty, which the server accepts", () => {
+    const defaults = defaultsFor(renderSelfHostCompose(config()))
+    for (const key of [
+      "SUPATYPE_SMTP_HOST",
+      "SUPATYPE_SMTP_USER",
+      "SUPATYPE_SMTP_PASS",
+      "SUPATYPE_SMTP_ADMIN_EMAIL",
+      "SUPATYPE_SMTP_SENDER_NAME",
+    ]) {
+      expect(defaults.get(key), `${key} should be present`).toBeDefined()
+    }
+  })
+})

package/tests/compose-services.test.ts

@@ -0,0 +1,144 @@
+import { describe, expect, it } from "vitest"
+import { logsArgs } from "../src/commands/logs.js"
+import { composeArgs, parseComposePs } from "../src/compose-services.js"
+
+/**
+ * `supatype status` and `supatype logs` each carried a hardcoded list of container
+ * names. Both lists were wrong: they named `supatype-postgres` and `supatype-kong`,
+ * which the generated compose file does not create, and omitted `server`, `storage`,
+ * `functions-worker`, `schema-engine` and `valkey`, which it does. The file sets no
+ * `container_name`, so Docker names containers `<project>-<service>-<n>` and no
+ * guessed name could ever have matched.
+ *
+ * The fix is to ask Compose. These tests cover the parsing and argument seams, which
+ * are the parts that can be wrong without Docker present.
+ */
+
+const ctx = {
+  composePath: "/proj/.supatype/self-host/docker-compose.yml",
+  projectRoot: "/proj",
+  projectName: "supatype-demo",
+}
+
+describe("parseComposePs", () => {
+  // Compose v2 emits newline-delimited objects.
+  it("reads the NDJSON form", () => {
+    const stdout = [
+      JSON.stringify({ Service: "server", Name: "supatype-demo-server-1", State: "running", Status: "Up 2 minutes" }),
+      JSON.stringify({ Service: "db", Name: "supatype-demo-db-1", State: "exited", Status: "Exited (1)" }),
+    ].join("\n")
+
+    expect(parseComposePs(stdout)).toEqual([
+      { service: "db", container: "supatype-demo-db-1", state: "exited", ports: "", status: "Exited (1)" },
+      { service: "server", container: "supatype-demo-server-1", state: "running", ports: "", status: "Up 2 minutes" },
+    ])
+  })
+
+  // Other versions emit one array. Which you get depends on the Docker installed.
+  it("reads the array form", () => {
+    const stdout = JSON.stringify([{ Service: "studio", Name: "supatype-demo-studio-1", State: "running" }])
+    expect(parseComposePs(stdout).map((s) => s.service)).toEqual(["studio"])
+  })
+
+  it("sorts by service so the report is stable between runs", () => {
+    const stdout = ["valkey", "db", "server"].map((s) => JSON.stringify({ Service: s, State: "running" })).join("\n")
+    expect(parseComposePs(stdout).map((s) => s.service)).toEqual(["db", "server", "valkey"])
+  })
+
+  // Compose prefixes its own progress lines on some versions, and prints nothing
+  // at all when the project has never been started.
+  it("survives noise and emptiness", () => {
+    expect(parseComposePs("")).toEqual([])
+    expect(parseComposePs("   \n")).toEqual([])
+    expect(parseComposePs("[not json")).toEqual([])
+    expect(parseComposePs('pulling...\n{"Service":"db","State":"running"}')).toHaveLength(1)
+  })
+
+  // A row without a service name cannot be reported against, and a missing state
+  // must not read as running.
+  it("drops rows with no service and does not invent a state", () => {
+    const stdout = [
+      JSON.stringify({ Name: "orphan", State: "running" }),
+      JSON.stringify({ Service: "db" }),
+      "null",
+    ].join("\n")
+    const got = parseComposePs(stdout)
+    expect(got).toHaveLength(1)
+    expect(got[0]).toMatchObject({ service: "db", state: "unknown", container: "", ports: "" })
+  })
+
+  describe("ports", () => {
+    it("takes the string form as given", () => {
+      const stdout = JSON.stringify({ Service: "db", State: "running", Publishers: "0.0.0.0:5432->5432/tcp" })
+      expect(parseComposePs(stdout)[0]?.ports).toBe("0.0.0.0:5432->5432/tcp")
+    })
+
+    // Compose lists an entry per protocol and per host interface, so the same
+    // mapping arrives several times over.
+    it("renders the structured form, de-duplicated", () => {
+      const stdout = JSON.stringify({
+        Service: "db",
+        State: "running",
+        Publishers: [
+          { URL: "0.0.0.0", TargetPort: 5432, PublishedPort: 5432, Protocol: "tcp" },
+          { URL: "::", TargetPort: 5432, PublishedPort: 5432, Protocol: "tcp" },
+          { URL: "0.0.0.0", TargetPort: 9000, PublishedPort: 19000, Protocol: "tcp" },
+        ],
+      })
+      expect(parseComposePs(stdout)[0]?.ports).toBe("5432->5432, 19000->9000")
+    })
+
+    // An unpublished port is reachable only from inside the network, so reporting
+    // it would tell the developer to try an address that will refuse.
+    it("omits ports that are not published to the host", () => {
+      const stdout = JSON.stringify({
+        Service: "valkey",
+        State: "running",
+        Publishers: [{ URL: "", TargetPort: 6379, PublishedPort: 0, Protocol: "tcp" }, null, "nonsense"],
+      })
+      expect(parseComposePs(stdout)[0]?.ports).toBe("")
+    })
+  })
+})
+
+describe("composeArgs", () => {
+  // Without --project-directory, Compose resolves relative build contexts and
+  // env_file paths against .supatype/self-host/ rather than the project root.
+  it("names the project, the project directory and the file", () => {
+    expect(composeArgs(ctx)).toEqual([
+      "compose",
+      "-p",
+      "supatype-demo",
+      "--project-directory",
+      "/proj",
+      "-f",
+      "/proj/.supatype/self-host/docker-compose.yml",
+    ])
+  })
+})
+
+describe("logsArgs", () => {
+  it("tails the whole stack by default", () => {
+    expect(logsArgs(["compose"], { since: "5m", follow: true })).toEqual([
+      "compose",
+      "logs",
+      "--tail",
+      "100",
+      "--follow",
+      "--since",
+      "5m",
+    ])
+  })
+
+  // The service name is the Compose service, and it has to come last: Compose
+  // reads trailing arguments as the services to tail.
+  it("puts the service last", () => {
+    const args = logsArgs(["compose"], { service: "server", follow: false })
+    expect(args.at(-1)).toBe("server")
+    expect(args).not.toContain("--follow")
+  })
+
+  it("omits --since when there is none", () => {
+    expect(logsArgs(["compose"], {})).not.toContain("--since")
+  })
+})

package/tests/dev-ports-owner.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from "vitest"
+import { composeProjectOwnsPort } from "../src/dev-ports.js"
+
+/**
+ * The decision behind the port guard, without Docker.
+ *
+ * `supatype self-host compose up -d` followed by `supatype push` was impossible: the second
+ * command saw its own gateway on the port and refused. The fix has to accept our own stack while
+ * still refusing a stranger's, because proceeding against another project's gateway would push a
+ * schema into the wrong database.
+ */
+describe("composeProjectOwnsPort", () => {
+  it("accepts a port published by this project", () => {
+    expect(composeProjectOwnsPort("supatype-validation\n", "supatype-validation")).toBe(true)
+  })
+
+  it("refuses a port published by a different project", () => {
+    expect(composeProjectOwnsPort("someone-elses-stack\n", "supatype-validation")).toBe(false)
+  })
+
+  it("refuses when any publisher is a different project", () => {
+    const output = "supatype-validation\nsomeone-elses-stack\n"
+    expect(composeProjectOwnsPort(output, "supatype-validation")).toBe(false)
+  })
+
+  it("refuses when nothing reports a compose project", () => {
+    // A container with no compose label: something is on the port, and it is not ours.
+    expect(composeProjectOwnsPort("\n\n", "supatype-validation")).toBe(false)
+    expect(composeProjectOwnsPort("", "supatype-validation")).toBe(false)
+  })
+
+  it("tolerates the whitespace docker pads its columns with", () => {
+    expect(composeProjectOwnsPort("  supatype-validation  \n", "supatype-validation")).toBe(true)
+  })
+
+  it("does not match on a prefix", () => {
+    // `supatype-validation-2` is a different project, and a substring check would accept it.
+    expect(composeProjectOwnsPort("supatype-validation-2\n", "supatype-validation")).toBe(false)
+  })
+})

package/tests/engine-floor.test.ts

@@ -0,0 +1,102 @@
+import { describe, expect, it } from "vitest"
+import {
+  assertEngineSupportsSchema,
+  boundsRequiringHelpers,
+  compareVersions,
+  ENGINE_MIN_FOR_BOUNDS,
+} from "../src/engine-floor.js"
+import type { ExtractedSchemaAstV2, FieldAstV2, ModelAstV2 } from "../src/schema-ast-v2.js"
+
+function field(overrides: Partial<FieldAstV2> = {}): FieldAstV2 {
+  return {
+    kind: "text",
+    annotations: { db: { pgType: "TEXT" }, platform: {} },
+    ...overrides,
+  } as FieldAstV2
+}
+
+function model(name: string, fields: Record<string, FieldAstV2>, constraints?: unknown[]): ModelAstV2 {
+  return {
+    name,
+    fields,
+    options: {},
+    annotations: {
+      db: { tableName: name.toLowerCase(), indexes: [], ...(constraints && { constraints }) },
+      platform: { access: {} },
+    },
+  }
+}
+
+function schema(models: ModelAstV2[]): ExtractedSchemaAstV2 {
+  return { astVersion: 2, models } as ExtractedSchemaAstV2
+}
+
+const WITH_BOUND = schema([model("Post", { title: field({ validation: { maxLength: 80 } }) })])
+const WITHOUT_BOUND = schema([model("Post", { title: field() })])
+
+describe("compareVersions", () => {
+  it("orders by each numeric part, not lexically", () => {
+    expect(compareVersions("0.10.0", "0.9.0")).toBeGreaterThan(0)
+    expect(compareVersions("0.2.0", "0.2.0")).toBe(0)
+    expect(compareVersions("0.1.9", "0.2.0")).toBeLessThan(0)
+  })
+
+  it("ignores a leading v and a pre-release suffix", () => {
+    // A release candidate of the engine that creates the helpers does create them.
+    expect(compareVersions("v0.2.0", "0.2.0")).toBe(0)
+    expect(compareVersions("0.2.0-rc.1", "0.2.0")).toBe(0)
+  })
+})
+
+describe("boundsRequiringHelpers", () => {
+  it("names the fields that declare a bound", () => {
+    expect(boundsRequiringHelpers(WITH_BOUND)).toEqual(["Post.title"])
+  })
+
+  it("names models carrying a constraint", () => {
+    const ast = schema([model("Event", { start: field() }, [{ expr: "start < finish" }])])
+    expect(boundsRequiringHelpers(ast)).toEqual(["Event"])
+  })
+
+  it("is empty for a schema that declares neither", () => {
+    expect(boundsRequiringHelpers(WITHOUT_BOUND)).toEqual([])
+  })
+})
+
+describe("assertEngineSupportsSchema", () => {
+  it("refuses a bound schema on an engine below the floor", () => {
+    expect(() => assertEngineSupportsSchema(WITH_BOUND, "0.1.9")).toThrow(/schema-engine 0\.2\.0 or newer/)
+  })
+
+  it("names the pin and the field, so the message is actionable", () => {
+    try {
+      assertEngineSupportsSchema(WITH_BOUND, "0.1.9")
+      expect.unreachable("should have refused")
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err)
+      expect(message).toContain("pins 0.1.9")
+      expect(message).toContain("Post.title")
+      expect(message).toContain("versions: { engine:")
+    }
+  })
+
+  // The three cases where refusing would be worse than the failure it prevents: an old pin is
+  // fine without bounds, an unpinned project resolves to latest, and `local` cannot be compared.
+  it("allows an old pin when the schema declares no bounds", () => {
+    expect(() => assertEngineSupportsSchema(WITHOUT_BOUND, "0.1.9")).not.toThrow()
+  })
+
+  it("allows an unpinned project", () => {
+    expect(() => assertEngineSupportsSchema(WITH_BOUND, undefined)).not.toThrow()
+  })
+
+  it("allows a local override, whose version the config does not know", () => {
+    expect(() => assertEngineSupportsSchema(WITH_BOUND, "local")).not.toThrow()
+  })
+
+  it("allows the floor itself and anything above it", () => {
+    expect(() => assertEngineSupportsSchema(WITH_BOUND, ENGINE_MIN_FOR_BOUNDS)).not.toThrow()
+    expect(() => assertEngineSupportsSchema(WITH_BOUND, "0.3.1")).not.toThrow()
+    expect(() => assertEngineSupportsSchema(WITH_BOUND, "1.0.0")).not.toThrow()
+  })
+})

package/tests/external-database-compose.test.ts

@@ -53,7 +53,7 @@ describe("external database: compose", () => {
 
   it("points every database consumer at the one URL", () => {
     const compose = renderSelfHostCompose(external())
-    // storage, realtime, control-plane, server (SUPATYPE_SQL_DATABASE_URL), and GoTrue.
+    // storage, realtime, control-plane, server (SUPATYPE_SQL_DATABASE_URL), and auth.
     const references = compose.match(/\$\{DATABASE_URL:\?/g) ?? []
     expect(references.length).toBe(5)
   })
@@ -85,9 +85,9 @@ describe("external database: compose", () => {
     expect(compose).toContain("@db.example.com:5432/app?sslmode=require")
   })
 
-  it("appends GoTrue's search_path with the right separator", () => {
+  it("appends the auth search_path with the right separator", () => {
     // A URL that already has a query string needs `&`; a second `?` produces a DSN that fails to
-    // parse, and GoTrue would exit rather than run its auth migrations.
+    // parse, and the service would exit rather than run its auth migrations.
     expect(renderSelfHostCompose(external())).toContain('${DATABASE_URL:?DATABASE_URL is missing from .env, required by database.external}?search_path=auth"')
     expect(
       renderSelfHostCompose(