@supatype/cli 0.1.6 → 0.1.9

package/src/dev-compose.ts

@@ -1,5 +1,5 @@
 /**
- * `supatype dev` when `provider: docker` — full self-host Compose stack (Kong gateway).
+ * `supatype dev` when `provider: docker`, full self-host Compose stack (Kong gateway).
  */
 
 import { existsSync, mkdirSync, writeFileSync } from "node:fs"
@@ -15,6 +15,7 @@ import {
   projectRootFromConfig,
   resolveRuntimeProvider,
   schemaPathFromProject,
+  usesExternalDatabase,
   type SupatypeProjectConfig,
 } from "./project-config.js"
 import { signJwt } from "./jwt.js"
@@ -40,6 +41,12 @@ import { ensureLocalServerDockerImage } from "./compose-local-server-image.js"
 import { ensureEngine, engineRequest, type DiffResult } from "./engine-client.js"
 import { writeSchemaSourcePushArtifacts, type SchemaSourcePushArtifacts } from "./schema-sources.js"
 import { readEnvValue, upsertEnvFile } from "./env-file.js"
+import {
+  devJwtSecret,
+  devPostgresPassword,
+  seedMissingDatabaseIdentity,
+  seedMissingLocalSecrets,
+} from "./local-secrets.js"
 import { writeLocalEnvironment } from "./link.js"
 import { registerDevShutdown } from "./dev-shutdown.js"
 import {
@@ -55,16 +62,19 @@ import type { ExtractedSchemaAstV2 } from "./schema-ast-v2.js"
 import { ensureFirstAdminUserForProject } from "./commands/admin.js"
 import { publishDevReady } from "./dev-ready-panel.js"
 
-const LOCAL_JWT_SECRET = "super-secret-jwt-token-with-at-least-32-characters-long"
-
 /** Default host port for compose Postgres when `overrides.engine` is set (devLocal). */
 const COMPOSE_DEV_DB_PORT = 54329
 
 /** Sync optional Docker image pins from config into `.env` (no JWT rotation). */
 export function syncComposeImagePins(cwd: string, config: SupatypeProjectConfig): void {
   const imagePins = composeDockerImageEnv(config)
+  // Clean up only what a previous run wrote from config. A hand-written image tag in `.env` is the
+  // documented way to run a local build, and this used to delete it on every compose run.
   const removeImageKeys = COMPOSE_PINNED_IMAGE_ENV_KEYS.filter((key) => !(key in imagePins))
-  upsertEnvFile(cwd, imagePins, removeImageKeys)
+  upsertEnvFile(cwd, imagePins, {
+    removeManaged: removeImageKeys,
+    managed: COMPOSE_PINNED_IMAGE_ENV_KEYS,
+  })
 }
 
 export interface DevComposeOptions {
@@ -72,8 +82,10 @@ export interface DevComposeOptions {
 }
 
 /** In-compose Postgres URL (SCRAM; not published to the host). */
-export function composeDbUrl(): string {
-  return "postgresql://supatype_admin:postgres@db:5432/supatype?sslmode=disable"
+export function composeDbUrl(cwd: string): string {
+  const user = readEnvValue(cwd, "POSTGRES_USER", "supatype_admin")
+  const db = readEnvValue(cwd, "POSTGRES_DB", "supatype")
+  return `postgresql://${user}:${devPostgresPassword(cwd)}@db:5432/${db}?sslmode=disable`
 }
 
 /**
@@ -84,10 +96,23 @@ async function resolveDevDbPort(cwd: string): Promise<number> {
   return ensureDevDbPort(cwd)
 }
 
+/**
+ * The database URL to hand a tool, from wherever it happens to run.
+ *
+ * The compose helpers below describe the `db` *container*, on the host at
+ * `SUPATYPE_DEV_DB_PORT`, or in-network at `db:5432`. Neither exists for a project pointed at an
+ * external database, and passing one produced "pool timed out while waiting for an open connection"
+ *- a message with nothing in it about the URL being wrong.
+ */
+function projectDatabaseUrl(cwd: string, config: SupatypeProjectConfig, inNetwork = false): string {
+  if (usesExternalDatabase(config)) return connectionString(config)
+  return inNetwork ? composeDbUrl(cwd) : hostComposeDbUrl(cwd)
+}
+
 function hostComposeDbUrl(cwd: string): string {
   const port = readEnvValue(cwd, "SUPATYPE_DEV_DB_PORT", String(COMPOSE_DEV_DB_PORT))
   const user = readEnvValue(cwd, "POSTGRES_USER", "supatype_admin")
-  const pass = readEnvValue(cwd, "POSTGRES_PASSWORD", "postgres")
+  const pass = devPostgresPassword(cwd)
   const db = readEnvValue(cwd, "POSTGRES_DB", "supatype")
   return `postgresql://${user}:${pass}@127.0.0.1:${port}/${db}?sslmode=disable`
 }
@@ -117,19 +142,12 @@ export async function ensureDockerDbPublishedForHostEngine(
 
   const now = Math.floor(Date.now() / 1000)
   const jwtBase = { iss: "supatype", iat: now, exp: now + 315_360_000 }
-  const anonKey = signJwt({ ...jwtBase, role: "anon" }, LOCAL_JWT_SECRET)
-  const serviceRoleKey = signJwt({ ...jwtBase, role: "service_role" }, LOCAL_JWT_SECRET)
+  const anonKey = signJwt({ ...jwtBase, role: "anon" }, devJwtSecret(cwd))
+  const serviceRoleKey = signJwt({ ...jwtBase, role: "service_role" }, devJwtSecret(cwd))
   ensureDevComposeEnv(cwd, config, anonKey, serviceRoleKey, kongPort, devDbPort)
 
   const paths = writeSelfHostCompose(cwd, config, { devLocal: true })
-  const up = runDockerCompose(paths.composePath, ["up", "-d", "db"], cwd, project, {
-    quiet: true,
-    ...(brand !== undefined && { brand }),
-  })
-  if (up !== 0) {
-    exitComposeFailed(up, "Could not start Postgres (compose db service).", brand)
-  }
-  await waitComposeHealthy(paths, cwd, 120_000, project)
+  await startComposeDatabase(config, paths, cwd, project, brand)
 }
 
 /**
@@ -142,6 +160,9 @@ export function usesLocalDockerEngineDb(
 ): boolean {
   if (explicitConnection?.trim()) return false
   if (config.connection?.trim()) return false
+  // An external database is already reachable and is not ours to publish. Without this the engine
+  // path tried `compose up -d db` against a compose file that deliberately has no `db` service.
+  if (usesExternalDatabase(config)) return false
   return resolveRuntimeProvider(config) === "docker" && hasEngineOverride(config)
 }
 
@@ -168,6 +189,36 @@ async function resolveKongPort(cwd: string): Promise<number> {
   return ensureKongPort(cwd, { context: "dev" })
 }
 
+/**
+ * Bring up the compose `db` service and wait for it to answer.
+ *
+ * A no-op when the project uses an external database: there is no such service, the database is
+ * already running, and its readiness is the operator's, `supatype db check` is what reports on it.
+ * Four call sites did this inline, so an external project hit `compose up -d db` against a compose
+ * file that deliberately has no `db`.
+ */
+async function startComposeDatabase(
+  config: SupatypeProjectConfig,
+  paths: SelfHostComposePaths,
+  cwd: string,
+  project: string,
+  brand: DockerBrandOptions | undefined,
+  timeoutMs = 120_000,
+  onFailure?: () => void,
+): Promise<void> {
+  if (usesExternalDatabase(config)) return
+
+  const up = runDockerCompose(paths.composePath, ["up", "-d", "db"], cwd, project, {
+    quiet: true,
+    ...(brand !== undefined && { brand }),
+  })
+  if (up !== 0) {
+    onFailure?.()
+    exitComposeFailed(up, "Could not start Postgres (compose db service).", brand)
+  }
+  await waitComposeHealthy(paths, cwd, timeoutMs, project)
+}
+
 function upsertDevComposeEnv(
   cwd: string,
   config: SupatypeProjectConfig,
@@ -179,11 +230,25 @@ function upsertDevComposeEnv(
 ): void {
   const apiUrl = `http://localhost:${kongPort}`
   const imagePins = composeDockerImageEnv(config)
+  // `POSTGRES_PASSWORD` and `JWT_SECRET` are deliberately absent.
+  //
+  // They used to be pinned here to published constants on every `dev` run, against the same
+  // `.env` a self-host deployment reads, so a project could not hold its own secrets, and one
+  // `dev` after generating them put the published values back with nothing to show it. They are
+  // now resolved from `.env` (see `local-secrets.ts`) and written by `init` alone.
+  //
+  // The keys below still have to be written, because they are *derived*: the anon and
+  // service-role tokens are signed with the effective secret, so leaving a stale pair in place
+  // would desync them from the secret that validates them.
   const updates: Record<string, string> = {
-    POSTGRES_USER: "supatype_admin",
-    POSTGRES_PASSWORD: "postgres",
-    POSTGRES_DB: "supatype",
-    JWT_SECRET: LOCAL_JWT_SECRET,
+    // The docker dev path renders the *self-host* compose file, where the secrets have no
+    // defaults: an unset value is a hard compose error rather than a service quietly starting
+    // with a published constant. This guarantees presence without overwriting: only keys
+    // genuinely absent from `.env` are filled, and with the value the project has been running
+    // with rather than a fresh one.
+    ...seedMissingLocalSecrets(cwd),
+    // Project configuration, seeded not overwritten, see seedMissingDatabaseIdentity.
+    ...seedMissingDatabaseIdentity(cwd),
     ANON_KEY: anonKey,
     SERVICE_ROLE_KEY: serviceRoleKey,
     PUBLIC_SUPATYPE_ANON_KEY: anonKey,
@@ -198,13 +263,26 @@ function upsertDevComposeEnv(
     ...imagePins,
     ...(localServerImage !== undefined && { SUPATYPE_SERVER_IMAGE: localServerImage }),
   }
-  if (devDbPort !== undefined) {
+  // Never for an external database: this URL describes the `db` container, which that project does
+  // not have. Writing it overwrote the operator's own DATABASE_URL, the value the whole stack and
+  // every CLI command reads, with a DSN pointing at a database that does not exist. Found by
+  // rehearsing a push against a real external Postgres, where the compose guard then refused to
+  // proceed because .env and the config disagreed. They disagreed because of this line.
+  if (devDbPort !== undefined && !usesExternalDatabase(config)) {
     updates.SUPATYPE_DEV_DB_PORT = String(devDbPort)
+    // User and database from the project, not hardcoded, same reason as
+    // `seedMissingDatabaseIdentity`: a project not named "supatype" had this URL pointing at a
+    // database that does not exist.
+    const dbUser = readEnvValue(cwd, "POSTGRES_USER", "supatype_admin")
+    const dbName = readEnvValue(cwd, "POSTGRES_DB", "supatype")
     updates.DATABASE_URL =
-      `postgresql://supatype_admin:postgres@localhost:${devDbPort}/supatype?sslmode=disable`
+      `postgresql://${dbUser}:${devPostgresPassword(cwd)}@localhost:${devDbPort}/${dbName}?sslmode=disable`
   }
   const removeImageKeys = COMPOSE_PINNED_IMAGE_ENV_KEYS.filter((key) => !(key in imagePins))
-  upsertEnvFile(cwd, updates, removeImageKeys)
+  upsertEnvFile(cwd, updates, {
+    removeManaged: removeImageKeys,
+    managed: COMPOSE_PINNED_IMAGE_ENV_KEYS,
+  })
 }
 
 /** Keep compose + Studio on the same freshly signed dev JWTs; sync optional image pins from config. */
@@ -280,7 +358,7 @@ function dumpComposeDbLogs(
     maxBuffer: 10 * 1024 * 1024,
   })
   const body = `${result.stdout ?? ""}${result.stderr ?? ""}`.trim()
-  const content = body || `(empty — docker compose logs db exit ${result.status ?? "?"})\n`
+  const content = body || `(empty, docker compose logs db exit ${result.status ?? "?"})\n`
   try {
     writeFileSync(logPath, content)
   } catch {
@@ -325,7 +403,7 @@ async function waitStorageApiReady(
       const body = await res.text()
       const kongUpstreamDown = body.includes("invalid response was received from the upstream server")
       if (!kongUpstreamDown && res.status !== 503) {
-        // Non-transient storage response (e.g. 401) — stop waiting.
+        // Non-transient storage response (e.g. 401), stop waiting.
         return
       }
     } catch {
@@ -334,7 +412,7 @@ async function waitStorageApiReady(
     await new Promise((r) => setTimeout(r, 1000))
   }
   console.warn(
-    `[supatype] Storage API at ${url} did not become ready within ${maxSec}s — bucket provisioning may fail.`,
+    `[supatype] Storage API at ${url} did not become ready within ${maxSec}s, bucket provisioning may fail.`,
   )
 }
 
@@ -367,7 +445,7 @@ async function refreshSchemaArtifacts(
     await ensureEngine()
   } catch (err) {
     console.warn(
-      `[supatype] Host engine unavailable — admin/types not refreshed: ${(err as Error).message}`,
+      `[supatype] Host engine unavailable, admin/types not refreshed: ${(err as Error).message}`,
     )
     return
   }
@@ -402,7 +480,7 @@ async function refreshSchemaArtifacts(
     console.log("[supatype] Admin config written to .supatype/admin-config.json")
   } catch (err) {
     console.warn(
-      `[supatype] Admin config generation failed — Studio may show stale field widgets: ${(err as Error).message}`,
+      `[supatype] Admin config generation failed, Studio may show stale field widgets: ${(err as Error).message}`,
     )
   }
 }
@@ -420,7 +498,7 @@ async function runComposeSchemaPush(
   const supatypeDir = join(cwd, ".supatype")
   mkdirSync(supatypeDir, { recursive: true })
   const astPath = join(supatypeDir, "schema.ast.json")
-  // Always materialise on disk — schema-engine reads via bind mount; skip must not omit the write.
+  // Always materialise on disk, schema-engine reads via bind mount; skip must not omit the write.
   writeFileSync(astPath, astJson)
   if (astJson === _lastPushedAst && astJson !== _lastFailedAst) return
 
@@ -428,7 +506,7 @@ async function runComposeSchemaPush(
     throw new Error(`Failed to write schema AST at ${astPath}`)
   }
 
-  // Admin + types come from the AST only (no DB) — refresh before push so Studio stays
+  // Admin + types come from the AST only (no DB), refresh before push so Studio stays
   // in sync even when migration fails (e.g. bad engine image, lossy column change).
   await refreshSchemaArtifacts(cwd, config, ast)
 
@@ -440,7 +518,7 @@ async function runComposeSchemaPush(
     try {
       await engineRequest("/push", {
         ast,
-        database_url: hostComposeDbUrl(cwd),
+        database_url: projectDatabaseUrl(cwd, config),
         schema: pgSchema,
         force: true,
         ...(sources
@@ -474,7 +552,7 @@ async function runComposeSchemaPush(
     }
     return result
   }
-  // B: only hold the advisory lock when realtime is already decoding — first-boot
+  // B: only hold the advisory lock when realtime is already decoding, first-boot
   // push (db only) must not take the lock; that path crashed under lock+DDL in CI.
   const push = composeServiceIsRunning(paths, cwd, composeProject, "realtime")
     ? await withComposeSchemaPushLock(paths, cwd, composeProject, runPush)
@@ -540,7 +618,7 @@ async function runComposeEnginePush(
     "-i",
     "/project/.supatype/schema.ast.json",
     "--database-url",
-    composeDbUrl(),
+    projectDatabaseUrl(cwd, config, true),
     "--force",
     "--non-interactive",
   )
@@ -606,7 +684,7 @@ async function runComposeEngineDiff(
     "-i",
     "/project/.supatype/schema.ast.json",
     "--database-url",
-    composeDbUrl(),
+    projectDatabaseUrl(cwd, config, true),
     "--schema",
     pgSchema,
   )
@@ -633,7 +711,7 @@ async function runComposeEngineDiff(
 
 /**
  * `supatype diff` when `provider: docker`. Uses in-compose schema-engine unless
- * `overrides.engine` is set — then Postgres is published to the host and diff runs
+ * `overrides.engine` is set: then Postgres is published to the host and diff runs
  * through the local engine binary.
  */
 export async function diffSchemaDocker(cwd: string, config: SupatypeProjectConfig): Promise<DiffResult> {
@@ -651,7 +729,7 @@ export async function diffSchemaDocker(cwd: string, config: SupatypeProjectConfi
     await ensureEngine()
     return engineRequest<DiffResult>("/diff", {
       ast,
-      database_url: hostComposeDbUrl(cwd),
+      database_url: projectDatabaseUrl(cwd, config),
       schema: pgSchema,
     })
   }
@@ -659,21 +737,14 @@ export async function diffSchemaDocker(cwd: string, config: SupatypeProjectConfi
   const kongPort = await resolveKongPort(cwd)
   const now = Math.floor(Date.now() / 1000)
   const jwtBase = { iss: "supatype", iat: now, exp: now + 315_360_000 }
-  const anonKey = signJwt({ ...jwtBase, role: "anon" }, LOCAL_JWT_SECRET)
-  const serviceRoleKey = signJwt({ ...jwtBase, role: "service_role" }, LOCAL_JWT_SECRET)
+  const anonKey = signJwt({ ...jwtBase, role: "anon" }, devJwtSecret(cwd))
+  const serviceRoleKey = signJwt({ ...jwtBase, role: "service_role" }, devJwtSecret(cwd))
   ensureDevComposeEnv(cwd, config, anonKey, serviceRoleKey, kongPort, undefined)
 
   const paths = writeSelfHostCompose(cwd, config, { devLocal: true })
   const diffBrand = { intro: "Schema diff" }
 
-  const up = runDockerCompose(paths.composePath, ["up", "-d", "db"], cwd, project, {
-    quiet: true,
-    brand: diffBrand,
-  })
-  if (up !== 0) {
-    exitComposeFailed(up, "Could not start Postgres (compose db service).", diffBrand)
-  }
-  await waitComposeHealthy(paths, cwd, 120_000, project)
+  await startComposeDatabase(config, paths, cwd, project, diffBrand)
 
   const schemaPath = schemaPathFromProject(config, cwd)
   const ast = loadSchemaAst(schemaPath, cwd)
@@ -701,7 +772,7 @@ export async function diffSchemaDocker(cwd: string, config: SupatypeProjectConfi
 
 /**
  * `supatype push` when `provider: docker`. Uses in-compose schema-engine unless
- * `overrides.engine` is set — then Postgres is published to the host and push runs
+ * `overrides.engine` is set: then Postgres is published to the host and push runs
  * through the local engine binary (AST v2, contributor builds).
  */
 export async function pushSchemaDocker(cwd: string, config: SupatypeProjectConfig): Promise<void> {
@@ -710,26 +781,25 @@ export async function pushSchemaDocker(cwd: string, config: SupatypeProjectConfi
   }
   const project = composeProjectName(config.project.name)
   const kongPort = await resolveKongPort(cwd)
-  const devDbPort = hasEngineOverride(config) ? await resolveDevDbPort(cwd) : undefined
+  // 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.
+  const devDbPort =
+    hasEngineOverride(config) && !usesExternalDatabase(config)
+      ? await resolveDevDbPort(cwd)
+      : undefined
 
   const now = Math.floor(Date.now() / 1000)
   const jwtBase = { iss: "supatype", iat: now, exp: now + 315_360_000 }
-  const anonKey = signJwt({ ...jwtBase, role: "anon" }, LOCAL_JWT_SECRET)
-  const serviceRoleKey = signJwt({ ...jwtBase, role: "service_role" }, LOCAL_JWT_SECRET)
+  const anonKey = signJwt({ ...jwtBase, role: "anon" }, devJwtSecret(cwd))
+  const serviceRoleKey = signJwt({ ...jwtBase, role: "service_role" }, devJwtSecret(cwd))
   ensureDevComposeEnv(cwd, config, anonKey, serviceRoleKey, kongPort, devDbPort)
 
   const paths = writeSelfHostCompose(cwd, config, { devLocal: true })
   const pushBrand = { intro: "Push schema" }
 
-  console.log(`[supatype] provider: docker — applying schema via compose (project ${project})...`)
-  const up = runDockerCompose(paths.composePath, ["up", "-d", "db"], cwd, project, {
-    quiet: true,
-    brand: pushBrand,
-  })
-  if (up !== 0) {
-    exitComposeFailed(up, "Could not start Postgres (compose db service).", pushBrand)
-  }
-  await waitComposeHealthy(paths, cwd, 120_000, project)
+  console.log(`[supatype] provider docker, applying schema via compose (project ${project})...`)
+  await startComposeDatabase(config, paths, cwd, project, pushBrand)
 
   const schemaPath = schemaPathFromProject(config, cwd)
   const ast = loadSchemaAst(schemaPath, cwd)
@@ -762,19 +832,25 @@ export async function runDevCompose(cwd: string, config: SupatypeProjectConfig,
   // stack on the machine (own containers, volumes, network, and gateway port).
   const project = composeProjectName(config.project.name)
   const kongPort = await resolveKongPort(cwd)
-  const devDbPort = hasEngineOverride(config) ? await resolveDevDbPort(cwd) : undefined
+  // 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.
+  const devDbPort =
+    hasEngineOverride(config) && !usesExternalDatabase(config)
+      ? await resolveDevDbPort(cwd)
+      : undefined
 
   const now = Math.floor(Date.now() / 1000)
   const jwtBase = { iss: "supatype", iat: now, exp: now + 315_360_000 }
-  const anonKey = signJwt({ ...jwtBase, role: "anon" }, LOCAL_JWT_SECRET)
-  const serviceRoleKey = signJwt({ ...jwtBase, role: "service_role" }, LOCAL_JWT_SECRET)
+  const anonKey = signJwt({ ...jwtBase, role: "anon" }, devJwtSecret(cwd))
+  const serviceRoleKey = signJwt({ ...jwtBase, role: "service_role" }, devJwtSecret(cwd))
 
   const devBrand = { intro: "Local development" }
   const localServerImage = await ensureLocalServerDockerImage(cwd, config, devBrand)
 
   ensureDevComposeEnv(cwd, config, anonKey, serviceRoleKey, kongPort, devDbPort, localServerImage)
 
-  console.log(`[supatype] provider: docker — starting self-host Compose stack (project ${project}, gateway :${kongPort})...`)
+  console.log(`[supatype] provider docker, starting self-host Compose stack (project ${project}, gateway :${kongPort})...`)
   const paths = writeSelfHostCompose(cwd, config, { devLocal: true })
   if (ensureDevApiConfig(cwd)) {
     console.log("[supatype] API config written to .supatype/api-config.json")
@@ -818,19 +894,11 @@ export async function runDevCompose(cwd: string, config: SupatypeProjectConfig,
   await recoverStaleDevSession(cwd)
   await handleComposeProjectRename(cwd, config.project.name, paths)
 
-  console.log("[supatype] Bringing up Postgres (compose db)...")
-  const upDbStatus = runDockerCompose(paths.composePath, ["up", "-d", "db"], cwd, project, {
-    quiet: true,
-    brand: devBrand,
-  })
-  if (upDbStatus !== 0) {
-    endDevSession()
-    exitComposeFailed(upDbStatus, "Could not start Postgres (compose db service).", devBrand)
+  if (!usesExternalDatabase(config)) {
+    console.log("[supatype] Bringing up Postgres (compose db)...")
   }
-
-  console.log("[supatype] Waiting for Postgres (compose)...")
-  await waitComposeHealthy(paths, cwd, 180_000, project)
-  // Settle before DDL — pg_isready can pass slightly before the instance is stable.
+  await startComposeDatabase(config, paths, cwd, project, devBrand, 180_000, endDevSession)
+  // Settle before DDL: pg_isready can pass slightly before the instance is stable.
   await new Promise((r) => setTimeout(r, 3000))
 
   // A: apply schema before realtime (and the rest of the stack) starts decoding WAL.
@@ -851,16 +919,17 @@ export async function runDevCompose(cwd: string, config: SupatypeProjectConfig,
         )
         dumpComposeDbLogs(paths, cwd, project, `schema push attempt ${attempt}/${maxAttempts}`)
         if (attempt < maxAttempts) {
-          console.log("[supatype] Resetting Postgres after failed schema push...")
-          runDockerCompose(paths.composePath, ["down", "-v"], cwd, project, {
-            quiet: true,
-            brand: devBrand,
-          })
-          runDockerCompose(paths.composePath, ["up", "-d", "db"], cwd, project, {
-            quiet: true,
-            brand: devBrand,
-          })
-          await waitComposeHealthy(paths, cwd, 120_000, project)
+          // Only for a database Supatype created. Tearing down an external one is not ours to do,
+          // and `down -v` would destroy the stack's other volumes for a failure that was never
+          // about Postgres.
+          if (!usesExternalDatabase(config)) {
+            console.log("[supatype] Resetting Postgres after failed schema push...")
+            runDockerCompose(paths.composePath, ["down", "-v"], cwd, project, {
+              quiet: true,
+              brand: devBrand,
+            })
+            await startComposeDatabase(config, paths, cwd, project, devBrand)
+          }
           await new Promise((r) => setTimeout(r, 3000 * attempt))
         }
       }
@@ -927,7 +996,7 @@ export async function runDevCompose(cwd: string, config: SupatypeProjectConfig,
   writeLocalEnvironment(cwd, {
     target: "local",
     apiUrl: `http://localhost:${kongPort}`,
-    databaseUrl: hasEngineOverride(config) ? hostComposeDbUrl(cwd) : composeDbUrl(),
+    databaseUrl: projectDatabaseUrl(cwd, config, !hasEngineOverride(config)),
     projectRef: config.project.name,
     kongPort,
     provider: "docker",
@@ -965,7 +1034,7 @@ export async function runDevCompose(cwd: string, config: SupatypeProjectConfig,
     shutdownState.studioProc = studioProc
     if (studioProc) {
       console.log(
-        `[supatype] Studio (overrides.studio) — live reload proxied at http://localhost:${kongPort}/studio/`,
+        `[supatype] Studio (overrides.studio): live reload proxied at http://localhost:${kongPort}/studio/`,
       )
     }
   }
@@ -1053,6 +1122,6 @@ function grantAuthSchemaAccess(
     { cwd: composeDir, encoding: "utf8", timeout: 10_000 },
   )
   if (result.status !== 0) {
-    console.warn("[supatype] Could not grant service_role access to auth.users — Studio relation preview may fail.")
+    console.warn("[supatype] Could not grant service_role access to auth.users, Studio relation preview may fail.")
   }
 }

package/src/dev-log-filter.ts

@@ -48,7 +48,7 @@ export function filterStackLogLine(line: string): boolean {
   return false
 }
 
-/** Drop docker noise only — keep diff tables, push status, and command output. */
+/** Drop docker noise only, keep diff tables, push status, and command output. */
 export function filterCommandLogLine(line: string): boolean {
   const t = stripAnsi(line).trim()
   if (!t) return false

package/src/dev-ports.ts

@@ -60,7 +60,7 @@ async function promptPortConflict(
 export interface EnsureKongPortOptions {
   /** When false, fail fast instead of prompting (CI / scripts). */
   interactive?: boolean
-  /** init wizard — slightly different copy */
+  /** init wizard: slightly different copy */
   context?: "dev" | "init"
 }
 
@@ -102,7 +102,7 @@ export async function ensureKongPort(
   return port
 }
 
-/** Wizard / init — pick a Kong port without writing `.env` (scaffold writes it). */
+/** Wizard / init: pick a Kong port without writing `.env` (scaffold writes it). */
 export async function promptKongPortChoice(): Promise<number> {
   const freeDefault = (await isPortInUse(COMPOSE_DEV_KONG_PORT))
     ? await findNextFreePort(COMPOSE_DEV_KONG_PORT)
@@ -139,7 +139,7 @@ async function promptPortConflictWithoutPersist(
   const headline =
     reason === "init"
       ? `Port ${blockedPort} is already in use on this machine.`
-      : `Port ${blockedPort} is in use — another Supatype project or service may already be bound to it.`
+      : `Port ${blockedPort} is in use, another Supatype project or service may already be bound to it.`
 
   const choice = await p.select<"suggested" | "custom" | "cancel">({
     message: headline,

package/src/dev-session.ts

@@ -1,5 +1,5 @@
 /**
- * `supatype dev` output session — Ink dashboard (default) or interleaved stream mode.
+ * `supatype dev` output session, Ink dashboard (default) or interleaved stream mode.
  */
 
 import { render, type Instance } from "ink"
@@ -32,7 +32,7 @@ export function beginDevSession(mode: DevUiMode): DevSession {
   return activeSession
 }
 
-/** @deprecated Ink starts in beginDevSession — kept for callers that invoke late. */
+/** @deprecated Ink starts in beginDevSession, kept for callers that invoke late. */
 export function startDevSession(): void {
   activeSession?.startInk()
 }
@@ -47,7 +47,7 @@ export function endDevSession(): void {
   activeSession = null
 }
 
-/** @deprecated Dev prompts render inside the Ink dashboard — no suspend needed. */
+/** @deprecated Dev prompts render inside the Ink dashboard, no suspend needed. */
 export function suspendDevSessionForPrompt(): void {
   prepareStdinForInteractivePrompt()
 }
@@ -58,12 +58,12 @@ export function prepareStdinForInteractivePrompt(): void {
   process.stdin.resume()
 }
 
-/** @deprecated Dev prompts render inside the Ink dashboard — no resume needed. */
+/** @deprecated Dev prompts render inside the Ink dashboard, no resume needed. */
 export function resumeDevSessionAfterPrompt(): void {
-  // no-op — prompts are Ink overlays
+  // no-op: prompts are Ink overlays
 }
 
-/** @deprecated Use Ink overlay prompts — runs fn without tearing down the dashboard. */
+/** @deprecated Use Ink overlay prompts, runs fn without tearing down the dashboard. */
 export async function withDevSessionSuspended<T>(fn: () => Promise<T>): Promise<T> {
   return fn()
 }

package/src/dev-shutdown.ts

@@ -1,5 +1,5 @@
 /**
- * Graceful shutdown for `supatype dev` — SIGINT, TUI Ctrl+C, terminal close,
+ * Graceful shutdown for `supatype dev`, SIGINT, TUI Ctrl+C, terminal close,
  * and a synchronous compose-down fallback on process exit.
  */
 
@@ -23,7 +23,7 @@ let forceQuitRequested = false
 let hooksRegistered = false
 let ignoreSigintUntil = 0
 
-/** SIGINT/SIGTERM hooks — call as soon as `supatype dev` starts (before compose is up). */
+/** SIGINT/SIGTERM hooks: call as soon as `supatype dev` starts (before compose is up). */
 export function ensureDevShutdownHooks(): void {
   if (hooksRegistered) return
   hooksRegistered = true
@@ -62,7 +62,7 @@ function syncComposeDownFallback(): void {
       { quiet: true },
     )
   } catch {
-    // best-effort — process is exiting
+    // best-effort: process is exiting
   }
   if (shutdownCwd) clearDevSessionLock(shutdownCwd)
 }
@@ -74,7 +74,7 @@ function onProcessExit(): void {
 export interface RegisterDevShutdownOptions {
   /** Sync `docker compose down` when async teardown cannot finish (terminal close, kill). */
   compose?: DevComposeShutdownFallback
-  /** Project root — clears `.supatype/dev-session.json` after shutdown. */
+  /** Project root: clears `.supatype/dev-session.json` after shutdown. */
   cwd?: string
 }
 
@@ -89,7 +89,7 @@ export function registerDevShutdown(
   ensureDevShutdownHooks()
 }
 
-/** TUI Ctrl+C — do not re-emit SIGINT (avoids double-fire on Windows raw mode). */
+/** TUI Ctrl+C: do not re-emit SIGINT (avoids double-fire on Windows raw mode). */
 export function requestDevShutdown(): void {
   ignoreSigintUntil = Date.now() + 400
   void runDevShutdown()
@@ -99,7 +99,7 @@ export function isDevShuttingDown(): boolean {
   return shuttingDown
 }
 
-/** @internal Tests — reset module state between cases. */
+/** @internal Tests: reset module state between cases. */
 export function resetDevShutdownForTests(): void {
   shutdownWork = null
   composeFallback = null
@@ -125,7 +125,7 @@ async function runDevShutdown(): Promise<void> {
     } catch {
       // best-effort terminal restore
     }
-    process.stderr.write("\n[supatype] Forced quit — Docker containers may still be running.\n")
+    process.stderr.write("\n[supatype] Forced quit: Docker containers may still be running.\n")
     process.stdout.write("\n")
     process.exit(130)
   }
@@ -145,7 +145,7 @@ async function runDevShutdown(): Promise<void> {
   } catch (err) {
     process.stderr.write(`[supatype] Shutdown failed: ${(err as Error).message}\n`)
     process.stderr.write(
-      "[supatype] Docker containers may still be running — try: supatype self-host compose down\n",
+      "[supatype] Docker containers may still be running, try: supatype self-host compose down\n",
     )
     syncComposeDownFallback()
     shutdownCompleted = true

package/src/dev-task-colors.ts

@@ -30,7 +30,7 @@ export function levelColor(line: string): string | null {
   return null
 }
 
-/** Drop redundant prefix — task pane is already labelled supatype. */
+/** Drop redundant prefix: task pane is already labelled supatype. */
 export function normalizeStackLogLine(line: string): string {
   return line.replace(/^\[supatype\]\s*/, "")
 }