@supatype/cli 0.3.1 → 0.3.2

package/src/dev-compose.ts

@@ -2,6 +2,7 @@
  * `supatype dev` when `provider: docker`, full self-host Compose stack (Kong gateway).
  */
 
+import { writeAstDerivedOutputs } from "./type-generation.js"
 import { withPublishing } from "./model-versioning.js"
 import { existsSync, mkdirSync, writeFileSync } from "node:fs"
 import { homedir } from "node:os"
@@ -29,6 +30,10 @@ import { handleComposeProjectRename } from "./compose-rename.js"
 import { recoverStaleDevSession, writeDevSessionLock } from "./dev-session-lock.js"
 import { endDevSession, startDevSession } from "./dev-session.js"
 import { ensureDevApiConfig } from "./ensure-dev-api-config.js"
+import { cacheSeedingNotes } from "./api-config-cache.js"
+import { refreshFunctionsContext } from "./functions-context-refresh.js"
+import { DB_PORT_ENV, syncDatabaseUrlPort } from "./db-port.js"
+import { degraded } from "./strict.js"
 import {
   COMPOSE_PINNED_IMAGE_ENV_KEYS,
   composeDockerImageEnv,
@@ -374,7 +379,16 @@ async function waitComposeHealthy(paths: SelfHostComposePaths, cwd: string, maxM
   while (Date.now() < deadline) {
     const ready = spawnSync(
       "docker",
-      [...baseArgs, "exec", "-T", "db", "pg_isready", "-U", "supatype_admin"],
+      // Over TCP, deliberately, not the Unix socket.
+      //
+      // On a first run the Postgres entrypoint starts a temporary server with `listen_addresses=''`
+      // to run the init scripts, then shuts it down and starts the real one. That temporary server
+      // answers on the socket, so a socket `pg_isready` reports ready during init and the very next
+      // thing to connect meets "the database system is shutting down". It is why the initial push
+      // failed three times in a row on a clean machine while a warm one was fine.
+      //
+      // TCP is the distinction the entrypoint itself draws: the init server does not listen on it.
+      [...baseArgs, "exec", "-T", "db", "pg_isready", "-h", "127.0.0.1", "-U", "supatype_admin"],
       { cwd: composeDir, encoding: "utf8" },
     )
     if (ready.status === 0) return
@@ -594,6 +608,12 @@ async function refreshSchemaArtifacts(
   // validator silently not firing means a write the schema says is checked is accepted with a 201.
   const hooksModule = writeHooksModule(cwd, hooksPathFromProject(config, cwd), ast)
   if (hooksModule !== null) console.log(`[supatype] Hook handler types written to ${hooksModule}`)
+  // And the context module, on the same terms. `init` and `functions new` wrote it and nothing
+  // else did, so a project that already had functions when the two-argument contract landed never
+  // received one: its handlers had no `FunctionContext` to import.
+  if (refreshFunctionsContext(cwd, config)) {
+    console.log("[supatype] Function context type written to functions/_shared/context.ts")
+  }
   if (syncManifestHooks(cwd, ast)) {
     console.log("[supatype] Hook and validator maps written to .supatype/manifest.json")
   }
@@ -604,6 +624,24 @@ async function refreshSchemaArtifacts(
     console.log(`[supatype] Row cache switched ${rowCache} in .env (pg_keyspace Mode B).`)
   }
 
+  // SUPATYPE_DB_PORT moves what compose binds; DATABASE_URL is what seeds and psql use. Nothing
+  // reconciled them, so a project moved off 5432 to avoid a clash came up perfectly and then
+  // failed on `npm run seed` with ECONNREFUSED against a port nothing was listening on.
+  const dbPort = syncDatabaseUrlPort(cwd)
+  if (dbPort !== null) {
+    console.log(
+      `[supatype] DATABASE_URL port ${dbPort.from} -> ${dbPort.to} in .env, ` +
+        `to match ${DB_PORT_ENV}.`,
+    )
+  }
+
+  // The declaration is a ceiling and the allowlist is what is actually on, and only `push` ever
+  // seeded the allowlist. So a stack brought up with `supatype dev` alone had every model's
+  // `cache` block declared and nothing switched on: `.cache({ server: true })` answered BYPASS,
+  // and the only way to find out why was to open Studio and tick a box the schema had already
+  // justified.
+  for (const note of cacheSeedingNotes(cwd, ast)) console.log(`[supatype] ${note}`)
+
   try {
     await ensureEngine()
   } catch (err) {
@@ -622,15 +660,19 @@ async function refreshSchemaArtifacts(
       adminConfigPath,
     ).catch(() => false)
     if (wrote) {
-      console.warn(
-        `[supatype] Host engine unavailable (${(err as Error).message}); used the in-compose ` +
-          "engine instead.",
+      // Reported through `degraded` rather than warned: the in-compose engine writes the admin
+      // config but never reaches the type generation below, so a run that takes this path has
+      // stale generated types and says so only in a line that scrolls past. In CI that is the
+      // difference between testing the host engine path and never touching it.
+      degraded(
+        "Host engine unavailable, used the in-compose engine instead",
+        (err as Error).message,
       )
       return
     }
-    console.warn(
-      `[supatype] Host engine unavailable, admin/types not refreshed: ${(err as Error).message}
-` +
+    degraded(
+      "Host engine unavailable, admin config and types not refreshed",
+      `${(err as Error).message}\n` +
         "[supatype] Studio will report no schema until this succeeds, even though the schema is " +
         "applied. Retry with the stack up, or run `supatype push`.",
     )
@@ -660,6 +702,23 @@ async function refreshSchemaArtifacts(
     }
   }
 
+  // Needs no engine, so it is written whether or not the types step above ran or succeeded. This
+  // is what `dev` never did: a project developed entirely through `supatype dev` received neither
+  // `index.d.ts`, which is what makes `createClient` typed without a generic, nor the field kinds
+  // the client reads to keep bigInt, decimal and money columns exact.
+  try {
+    for (const message of writeAstDerivedOutputs({
+      cwd,
+      ast,
+      ...(config.output?.types !== undefined && { typesPath: config.output.types }),
+      ...(config.output?.client !== undefined && { clientPath: config.output.client }),
+    })) {
+      console.log(`[supatype] ${message}`)
+    }
+  } catch (err) {
+    console.warn(`[supatype] Generated output failed: ${(err as Error).message}`)
+  }
+
   try {
     const admin = withAdminRoles(await engineRequest<unknown>("/admin", { ast }), config)
     restoreSystemRelationTargets(admin, ast)
@@ -952,7 +1011,16 @@ export async function diffSchemaDocker(cwd: string, config: SupatypeProjectConfi
     throw new Error(detail || `Engine schema diff failed (exit ${result.status})`)
   }
   if (!result.diff) {
-    throw new Error("Engine diff returned no result")
+    // The engine exited 0 and produced nothing this could parse, which is a different failure from
+    // the engine exiting non-zero and is the harder one to act on. "Engine diff returned no result"
+    // named only the symptom, and running the same compose command by hand gave a clear error in
+    // one go, so the message was the only thing standing between the reader and the answer.
+    const output = (filterComposeNoise(result.output) || result.output || "").trim()
+    throw new Error(
+      output === ""
+        ? "The schema engine exited 0 and printed nothing. Run `supatype self-host compose run --rm schema-engine diff` to see what it does."
+        : `The schema engine exited 0 but its output could not be parsed as a diff:\n${output}`,
+    )
   }
   return result.diff
 }
@@ -1159,19 +1227,26 @@ export async function runDevCompose(cwd: string, config: SupatypeProjectConfig,
     }
   }
 
-  const pinnedRealtimeImage = readEnvValue(cwd, "SUPATYPE_REALTIME_IMAGE", "").trim()
-  if (pinnedRealtimeImage !== "") {
-    console.log("[supatype] Recreating realtime with pinned image...")
-    const rtStatus = runDockerCompose(
+  // A service whose image is pinned in `.env` is recreated once the stack is up, so a contributor
+  // can point at a build from this checkout rather than the published tag.
+  //
+  // Storage was missing from this list, which is why a storage bug survived: there was no way to
+  // run the suite against a local storage build, so every integration run tested the last release
+  // no matter what the working tree said.
+  for (const service of ["realtime", "storage"] as const) {
+    const variable = `SUPATYPE_${service.toUpperCase()}_IMAGE`
+    if (readEnvValue(cwd, variable, "").trim() === "") continue
+    console.log(`[supatype] Recreating ${service} with pinned image...`)
+    const status = runDockerCompose(
       paths.composePath,
-      ["up", "-d", "--force-recreate", "--no-deps", "realtime"],
+      ["up", "-d", "--force-recreate", "--no-deps", service],
       cwd,
       project,
       { quiet: true, brand: devBrand },
     )
-    if (rtStatus !== 0) {
+    if (status !== 0) {
       endDevSession()
-      exitComposeFailed(rtStatus, "Could not recreate the realtime container.", devBrand)
+      exitComposeFailed(status, `Could not recreate the ${service} container.`, devBrand)
     }
   }
 
@@ -1339,8 +1414,17 @@ function reconcileAuthenticatorPassword(
     },
   )
   if (result.status !== 0) {
+    // The cause, not just the consequence. This warned that REST "may answer 502" and said nothing
+    // about why, so when the supabucks e2e then failed its only API assertion with a 502, the
+    // warning twenty lines earlier read as unrelated noise. A message that predicts a failure and
+    // withholds its reason costs more than one that says nothing.
+    const detail = [result.stderr, result.error?.message]
+      .map((s) => (s ?? "").trim())
+      .filter((s) => s.length > 0)
+      .join("\n")
     console.warn(
-      "[supatype] Could not set the authenticator password; the REST API may answer 502.",
+      `[supatype] Could not set the authenticator password, so the REST API will answer 502.\n` +
+        (detail === "" ? "[supatype] docker gave no output." : detail),
     )
   }
 }
@@ -1447,6 +1531,22 @@ export async function generateViaComposeEngine(
     }
   }
 
+  // The same AST-derived files as the host path. This is the fallback used when the host engine
+  // could not be fetched, and these need no engine at all, so there is no reason for a project on
+  // this path to end up with fewer generated files than one on the other.
+  try {
+    for (const message of writeAstDerivedOutputs({
+      cwd,
+      ast,
+      ...(config.output?.types !== undefined && { typesPath: config.output.types }),
+      ...(config.output?.client !== undefined && { clientPath: config.output.client }),
+    })) {
+      console.log(`[supatype] ${message} (in-compose engine).`)
+    }
+  } catch (err) {
+    console.warn(`[supatype] Generated output failed: ${(err as Error).message}`)
+  }
+
   const adminOut = await runComposeEngineGenerator(paths, cwd, composeProject, config, ["admin"])
   if (!adminOut) return false
   const parsed = parseEngineJsonOutput<unknown>(adminOut)

package/src/functions-context-refresh.ts

@@ -0,0 +1,25 @@
+/**
+ * Keep `functions/_shared/context.ts` current on a project that already exists.
+ *
+ * The module is generated by `ensureFunctionsDenoTypes`, which `init` and `supatype functions new`
+ * call and nothing else did. So it reached new projects and new functions, and never reached a
+ * project that already had functions when the two-argument handler contract landed: those keep
+ * `(req)` handlers with no `FunctionContext` to import, while the generated file asserts
+ * "Regenerated by the CLI. Edits are overwritten."
+ *
+ * A claim about a file nothing maintains is worse than no claim, because it tells people not to
+ * edit it and not to expect it to change.
+ *
+ * Only when the project has a functions directory: writing `_shared/` into a project that has no
+ * functions would create the thing it describes out of nothing.
+ */
+import { existsSync } from "node:fs"
+import { ensureFunctionsDenoTypes } from "./functions-deno-types.js"
+import { preferredFunctionsPathFromProject, type SupatypeProjectConfig } from "./project-config.js"
+
+/** Rewrite the context module. True when this project has functions and one was written. */
+export function refreshFunctionsContext(cwd: string, config: SupatypeProjectConfig): boolean {
+  const functionsDir = preferredFunctionsPathFromProject(config, cwd)
+  if (!existsSync(functionsDir)) return false
+  return ensureFunctionsDenoTypes(cwd, functionsDir).wroteContextModule
+}

package/src/functions-deno-types.ts

@@ -83,6 +83,23 @@ declare namespace Deno {
  * directory, but `deno check` builds its own type graph and does not look at either, so a function
  * naming an ambient type fails the check the runtime itself would run. An import works in both.
  */
+/**
+ * The `_shared/README.md` both scaffolds write.
+ *
+ * One definition because there were two, identical, as string literals in `init.ts` and
+ * `functions.ts`. It lives here rather than in either because this module already owns what goes
+ * into `_shared/`, and because the next edit to this text would otherwise change it in one scaffold
+ * and not the other.
+ */
+export function sharedFunctionsReadmeSource(): string {
+  return (
+    "# Shared Code\n\n" +
+    "Files in `_shared/` are available to all functions via relative imports.\n" +
+    "This directory is not deployed as a function.\n\n" +
+    "Example: `import { sendEmail } from '../_shared/email.ts'`\n"
+  )
+}
+
 export function functionsContextModuleSource(): string {
   return `/**
  * What a function is told about the call it is serving.
@@ -94,7 +111,13 @@ export function functionsContextModuleSource(): string {
  *
  * Passing them in removes the global, so functions run concurrently.
  *
- * Regenerated by the CLI. Edits are overwritten.
+ * Rewritten by supatype init, supatype functions new, supatype push and supatype dev.
+ * Edits are overwritten.
+ *
+ * Named explicitly because "regenerated by the CLI" was true of only the first two: a project that
+ * already had functions when this contract arrived never received the module at all, so its
+ * handlers had no type to import while this line told its author the file was maintained. Say
+ * which commands, so the claim can be checked rather than believed.
  */
 export interface FunctionContext {
   /** Unique to this invocation. Every log line it writes carries the same value. */

package/src/gitignore.ts

@@ -2,12 +2,35 @@ import { existsSync, readFileSync, writeFileSync } from "node:fs"
 import { resolve } from "node:path"
 
 export const SUPATYPE_GITIGNORE_MARKER = "# Supatype, local runtime (contains secrets in link.json)"
+
+/**
+ * Every path Supatype writes that holds a secret, in one place.
+ *
+ * One list because there were two emitters, this one and `init`'s own template, and they had
+ * already drifted apart on content. Two lists of the same thing drift again, and the half that
+ * drifts is discovered by a key reaching a public repository.
+ *
+ * `.env.local` and `.env.*.local` are here because `.env` does not cover them. That pattern matches
+ * a file named exactly `.env`, while `supatype functions new` writes `functions/.env.local` with
+ * "These are NOT committed to git" at the top of it, and the worker reads
+ * `.env.<function>.local` beside that. Verified with `git check-ignore`: under `.env` alone both
+ * were tracked; with these two they are ignored at any depth, and no source file is caught.
+ */
+const SUPATYPE_IGNORED_PATHS = [
+  ".env",
+  ".env.local",
+  ".env.*.local",
+  ".supatype/",
+  "supatype.local.config.ts",
+  "supatype.local.config.js",
+  "supatype.local.config.mjs",
+] as const
+
+/** The paths above, for a scaffold that composes its own `.gitignore` around them. */
+export const SUPATYPE_GITIGNORE_PATHS: readonly string[] = SUPATYPE_IGNORED_PATHS
+
 export const SUPATYPE_GITIGNORE_BLOCK = `${SUPATYPE_GITIGNORE_MARKER}
-.env
-.supatype/
-supatype.local.config.ts
-supatype.local.config.js
-supatype.local.config.mjs
+${SUPATYPE_IGNORED_PATHS.join("\n")}
 `
 
 export function isSupatypeGitignored(cwd: string): boolean {
@@ -26,11 +49,9 @@ export function ensureSupatypeGitignore(cwd: string, opts?: { silent?: boolean }
     const next = content.endsWith("\n") ? content : `${content}\n`
     writeFileSync(gitignorePath, `${next}\n${SUPATYPE_GITIGNORE_BLOCK}`, "utf8")
   } else {
-    writeFileSync(
-      gitignorePath,
-      `.env\nnode_modules/\ndist/\n${SUPATYPE_GITIGNORE_BLOCK}`,
-      "utf8",
-    )
+    // `.env` is not repeated here: the block below already carries it, along with the
+    // `.env.local` patterns it does not cover.
+    writeFileSync(gitignorePath, `node_modules/\ndist/\n${SUPATYPE_GITIGNORE_BLOCK}`, "utf8")
   }
 
   if (!opts?.silent) {

package/src/schema-ast-v2.ts

@@ -227,6 +227,15 @@ export interface ExtractedSchemaAstV2 {
   }
 }
 
+/**
+ * The Postgres type each field kind maps to, as published in the AST.
+ *
+ * A contract, not a hint: consumers generate parsers and casts from it. `money` and `decimal` said
+ * `TEXT` here while the engine creates `NUMERIC(19,4)` and `NUMERIC`, so anyone reading this wrote
+ * code that rejected every value the column returns. The engine's own `default_pg_type` agreed
+ * with the mistake for `money`, and was already right for `decimal`, which is what made it look
+ * considered.
+ */
 const DEFAULT_DB_BY_KIND: Partial<Record<FieldKind, Partial<DbFieldAnnotations>>> = {
   text: { pgType: "TEXT" },
   richText: { pgType: "JSONB" },
@@ -244,17 +253,17 @@ const DEFAULT_DB_BY_KIND: Partial<Record<FieldKind, Partial<DbFieldAnnotations>>
   slug: { pgType: "TEXT" },
   enum: { pgType: "TEXT" },
   json: { pgType: "JSONB" },
-  decimal: { pgType: "TEXT" },
+  decimal: { pgType: "NUMERIC" },
   bytes: { pgType: "BYTEA" },
   serial: { pgType: "SERIAL" },
   bigSerial: { pgType: "BIGSERIAL" },
-  money: { pgType: "TEXT" },
-  ip: { pgType: "TEXT" },
-  cidr: { pgType: "TEXT" },
-  macaddr: { pgType: "TEXT" },
-  xml: { pgType: "TEXT" },
-  tsQuery: { pgType: "TEXT" },
-  tsVector: { pgType: "TEXT" },
+  money: { pgType: "NUMERIC(19,4)" },
+  ip: { pgType: "INET" },
+  cidr: { pgType: "CIDR" },
+  macaddr: { pgType: "MACADDR" },
+  xml: { pgType: "XML" },
+  tsQuery: { pgType: "TSQUERY" },
+  tsVector: { pgType: "TSVECTOR" },
   color: { pgType: "TEXT" },
   array: { pgType: "ARRAY" },
   image: { pgType: "JSONB" },

package/src/self-host-compose.ts

@@ -17,7 +17,8 @@ import {
 import { hasEngineOverride, hasStudioOverride, pinnedVersion, fetchLatestVersion, VERSION_PIN_LOCAL } from "./binary-cache.js"
 import { buildKongDeclarative } from "./kong-config.js"
 import { keyspaceInPostgres } from "./cache-provider.js"
-import { readEnvFile } from "./env-file.js"
+import { STUDIO_DEV_PORT } from "./studio-dev-server.js"
+import { hasEnvValue, readEnvFile } from "./env-file.js"
 import { fieldMaskingTierFromProject, type FieldMaskingTier } from "./field-masking-tier.js"
 import { projectHasVersionedModels } from "./model-versioning.js"
 
@@ -285,8 +286,16 @@ function postgrestDatabaseUrl(config: SupatypeProjectConfig): string {
   return `postgresql://authenticator:${password}@${parsed.hostname}${port}${parsed.pathname}${parsed.search}`
 }
 
-/** Host Vite dev server as seen from Kong inside Docker Compose. */
-export const COMPOSE_STUDIO_HOST_URL = "http://host.docker.internal:3002"
+/**
+ * Host Vite dev server as seen from Kong inside Docker Compose.
+ *
+ * Derived from STUDIO_DEV_PORT rather than repeating the number, because the two are one decision.
+ * Held separately they drift, and the drift is invisible: Vite binds the new port, Kong keeps
+ * proxying to the old one, and `/studio/` serves whatever else happens to be listening there. On
+ * the machine this was found, that was an unrelated Next.js app, and every Studio view failed with
+ * a missing sign-in form rather than anything naming a port.
+ */
+export const COMPOSE_STUDIO_HOST_URL = `http://host.docker.internal:${STUDIO_DEV_PORT}`
 
 /** Studio container: always Docker Hub unless SUPATYPE_STUDIO_IMAGE is set in .env. */
 function studioServiceBlock(): string {
@@ -395,7 +404,12 @@ ${studioService}
     : `      - server
       - studio
       - control-plane`
-  const publishDbToHost = !devLocal || hasEngineOverride(config)
+  // In dev the database is published only when something on the host needs to reach it, which is
+  // normally a host engine build. A project that names a port is asking for one too: without this,
+  // `SUPATYPE_DEV_DB_PORT` was honoured for the number and ignored for whether the port existed,
+  // so a seed connecting over TCP got ECONNREFUSED and nothing said why.
+  const dbPortRequested = hasEnvValue(cwd, "SUPATYPE_DEV_DB_PORT")
+  const publishDbToHost = !devLocal || hasEngineOverride(config) || dbPortRequested
   const dbPorts = publishDbToHost
     ? devLocal
       ? `    ports:
@@ -437,6 +451,15 @@ ${studioService}
     volumes:
       - storage-data:/data
       - ${SEAWEED_CONFIG_MOUNT}:/etc/seaweedfs/s3.json:ro
+    healthcheck:
+      # Any HTTP status line means the S3 endpoint is listening, which is the whole question.
+      # Success cannot be "HTTP 200": an unauthenticated GET on the root answers 403 by design,
+      # because the anonymous identity is deliberately absent from s3.json.
+      test: ["CMD-SHELL", "wget -q -S -O /dev/null http://127.0.0.1:8333 2>&1 | grep -q 'HTTP/'"]
+      interval: 3s
+      timeout: 3s
+      retries: 20
+      start_period: 5s
 ${seaweedPorts}`
   const kongTlsEnv = tlsEnabled
     ? `      KONG_PROXY_LISTEN: "0.0.0.0:8000, 0.0.0.0:8443 ssl"
@@ -491,6 +514,21 @@ ${keyspaceInPg ? "" : "  valkey-data:\n"}`
 `
   const dbDependency = external ? "" : `    depends_on:\n${dbDependencyClause}`
 
+  // Storage waits for the object store, not only the database.
+  //
+  // seaweedfs had no healthcheck and nothing depended on it, so compose started it alongside
+  // storage rather than before it. Storage would then accept a bucket creation before seaweedfs
+  // was listening, and every bucket in the schema failed with `connect ECONNREFUSED <ip>:8333`
+  // while the metadata row was written anyway. Measured on a live stack: seaweedfs started twelve
+  // minutes after storage with RestartCount 0, so it was ordered late rather than crashing.
+  //
+  // A later push succeeds, which is exactly what made it read as an intermittent mystery. It
+  // lands on the first push after a stack comes up, which is the first push a new user ever runs.
+  const storageDependency = `    depends_on:
+${dbDependencyClause}      seaweedfs:
+        condition: service_healthy
+`
+
   // Realtime, omitted entirely when the project has turned it off.
   //
   // Not started-and-disabled: the service degrades gracefully on its own (it reports the reason on
@@ -676,7 +714,7 @@ ${dbDependency}
       S3_ACCESS_KEY: ${OBJECT_STORE_ACCESS_KEY}
       S3_SECRET_KEY: ${OBJECT_STORE_SECRET_KEY}
       S3_FORCE_PATH_STYLE: "true"
-${dbDependency}
+${storageDependency}
   functions-worker:
     image: \${SUPATYPE_FUNCTIONS_WORKER_IMAGE:-supatype/functions-worker:latest}
     expose:
@@ -705,6 +743,18 @@ ${dbDependency}
       # each one able to read past every access rule in the schema.
       SUPATYPE_SERVICE_ROLE_KEY: \${SERVICE_ROLE_KEY:-}
       SUPATYPE_SERVICE_ROLE_ROUTES: "${serviceRoleRoutes(config).join(",")}"
+      # A direct database connection for functions, off unless asked for.
+      #
+      # The worker reads SUPATYPE_DB_URL and exposes it as \`ctx.dbUrl\`, and nothing here ever set
+      # it, so the field was permanently undefined on self-host and a function reaching for it got
+      # no value and no explanation.
+      #
+      # Deliberately its own variable rather than the project's DATABASE_URL. That one is the owner
+      # DSN every service already uses, and wiring it through by default would hand every function
+      # a connection that bypasses access rules, field masking and model hooks, none of which live
+      # in the database. Naming a separate variable makes it a decision: set it to the owner URL
+      # and accept that, or to a role you restricted yourself.
+      SUPATYPE_DB_URL: \${SUPATYPE_FUNCTIONS_DB_URL:-}
       STRIPE_SECRET_KEY: \${STRIPE_SECRET_KEY:-}
       STRIPE_WEBHOOK_SECRET: \${STRIPE_WEBHOOK_SECRET:-}
       SITE_URL: \${SITE_URL:-\${API_EXTERNAL_URL:-${externalUrlFallback}}}
@@ -730,6 +780,12 @@ ${realtimeBlock}
 ${dbDependency}
   server:
     image: \${SUPATYPE_SERVER_IMAGE:-\${SUPATYPE_AUTH_IMAGE:-supatype/server:latest}}
+    # host.docker.internal is a Docker Desktop name. On Linux it does not resolve unless it is
+    # mapped, so a project proxying the site or Studio to something on the host worked on macOS
+    # and Windows and failed on Linux with nothing reaching the app. host-gateway is Docker's own
+    # alias for the host, and needs 20.10, which this stack already requires.
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
     # 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
@@ -798,7 +854,7 @@ ${appEnv}
       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" : ""}
+${devLocal ? "      STUDIO_OPEN_DEV: \"${STUDIO_OPEN_DEV:-1}\"\n" : ""}
     depends_on:
 ${dbDependencyClause}${keyspaceInPg ? "" : "      valkey:\n        condition: service_started\n"}      postgrest:
         condition: service_started
@@ -819,6 +875,12 @@ ${objectStoreBlock}
     working_dir: /project
 ${dbDependency}${studioBlock}${valkeyBlock}${tlsHintComment}  kong:
     image: kong:3.6
+    # host.docker.internal is a Docker Desktop name. On Linux it does not resolve unless it is
+    # mapped, so a project proxying the site or Studio to something on the host worked on macOS
+    # and Windows and failed on Linux with nothing reaching the app. host-gateway is Docker's own
+    # alias for the host, and needs 20.10, which this stack already requires.
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
     environment:
       KONG_DATABASE: "off"
       KONG_DECLARATIVE_CONFIG: /etc/kong/kong.yml

package/src/strict.ts

@@ -0,0 +1,40 @@
+/**
+ * Strict mode: a degraded path is a failure rather than a warning.
+ *
+ * Every fallback in this CLI exists because giving up would serve a person at a terminal worse
+ * than carrying on: the in-compose engine when the CDN cannot be reached, SHA256-only verification
+ * when no key is embedded, a bucket that could not be reached from the host but works from inside
+ * the network. Each is the right default interactively.
+ *
+ * In CI the trade runs the other way. A run that limps reports success, and the thing it quietly
+ * skipped is precisely the thing nobody tests again.
+ *
+ * This is not hypothetical. On 2026-09-24 three integration jobs failed on assertions about
+ * validators and served SPAs, and the cause in all three was an engine download refused twenty
+ * lines earlier and warned about. The same fallback made a local from-zero run look like a clean
+ * pass while the host engine path was never exercised at all.
+ */
+
+/** True when the caller has asked for degraded paths to fail. */
+export function strict(): boolean {
+  return process.env["SUPATYPE_STRICT"] === "1"
+}
+
+/**
+ * Report a path that worked less well than intended.
+ *
+ * Throws under `SUPATYPE_STRICT=1`, so a CI job cannot pass over it. Warns otherwise, because
+ * interactively a working stack and a note beats an abort.
+ *
+ * `what` names the capability that degraded, not the error: the reader needs to know which feature
+ * they are now without. `detail` carries the cause.
+ */
+export function degraded(what: string, detail: string): void {
+  const message = `${what}: ${detail}`
+  if (strict()) {
+    throw new Error(
+      `${message}\nSUPATYPE_STRICT=1 is set, so a degraded path fails rather than warns.`,
+    )
+  }
+  console.warn(`[supatype] ${message}`)
+}

package/src/studio-dev-server.ts

@@ -2,8 +2,18 @@ import { existsSync } from "node:fs"
 import { join, resolve } from "node:path"
 import { ProcessManager } from "./process-manager.js"
 
-/** Vite dev server port when `overrides.studio` is set. */
-export const STUDIO_DEV_PORT = 3002
+/**
+ * Vite dev server port when `overrides.studio` is set.
+ *
+ * Overridable because it is bound with `--strictPort`, so anything else already on 3002 does not
+ * make Vite pick another port, it makes Studio fail to start and be restarted every thirty seconds
+ * for the life of the session. 3002 is an ordinary port for a local app to be sitting on, and the
+ * only signal is a Vite stack trace in among the compose output.
+ *
+ * Only the `overrides.studio` path is affected, so this is a contributor's papercut rather than a
+ * user's: an ordinary `supatype dev` serves Studio from its container.
+ */
+export const STUDIO_DEV_PORT = Number(process.env["SUPATYPE_STUDIO_DEV_PORT"]) || 3002
 
 export interface StudioDevServerOptions {
   cwd: string

package/src/type-extractor.ts

@@ -1055,7 +1055,10 @@ function parseScalarType(
         const assetOpts = parseAssetFieldOptions(typeNode.typeArguments?.[1], sourceFile)
         return attachStorageFieldMeta(
           scalar("file", {
-            db: { pgType: "TEXT" },
+            // JSONB, not TEXT. The column holds { bucket, path }, this package's own
+            // DEFAULT_DB_BY_KIND says JSONB, and the engine honours an explicit annotation, so
+            // TEXT here was one code path from a text column with a JSON object written into it.
+            db: { pgType: "JSONB" },
             kernel: { bucket, ...(assetOpts.localized && { localized: true }) },
           }),
           bucket,
@@ -1067,7 +1070,10 @@ function parseScalarType(
         const assetOpts = parseAssetFieldOptions(typeNode.typeArguments?.[1], sourceFile)
         return attachStorageFieldMeta(
           scalar("image", {
-            db: { pgType: "TEXT" },
+            // JSONB, not TEXT. The column holds { bucket, path }, this package's own
+            // DEFAULT_DB_BY_KIND says JSONB, and the engine honours an explicit annotation, so
+            // TEXT here was one code path from a text column with a JSON object written into it.
+            db: { pgType: "JSONB" },
             kernel: { bucket, ...(assetOpts.localized && { localized: true }) },
           }),
           bucket,