@supatype/cli 0.1.0-alpha.9 → 0.1.1

package/src/dev-compose.ts

@@ -2,7 +2,7 @@
  * `supatype dev` when `provider: docker` — full self-host Compose stack (Kong gateway).
  */
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
+import { existsSync, mkdirSync, writeFileSync } from "node:fs"
 import { homedir } from "node:os"
 import { dirname, join, resolve } from "node:path"
 import { spawnSync } from "node:child_process"
@@ -10,24 +10,59 @@ import { startProxyDevApp } from "./app/proxy-dev-app.js"
 import { loadSchemaAst } from "./config.js"
 import {
   COMPOSE_DEV_KONG_PORT,
+  connectionString,
   projectRootFromConfig,
   resolveRuntimeProvider,
   schemaPathFromProject,
   type SupatypeProjectConfig,
 } from "./project-config.js"
 import { signJwt } from "./jwt.js"
-import { isPortInUse } from "./postgres-ctl.js"
-import { composeProjectName, runDockerCompose, writeSelfHostCompose, type SelfHostComposePaths } from "./self-host-compose.js"
+import { ensureDevDbPort, ensureKongPort } from "./dev-ports.js"
+import { handleComposeProjectRename } from "./compose-rename.js"
+import { recoverStaleDevSession, writeDevSessionLock } from "./dev-session-lock.js"
+import { readEnvValue, upsertEnvFile } from "./env-file.js"
+import {
+  COMPOSE_PINNED_IMAGE_ENV_KEYS,
+  composeDockerImageEnv,
+  composeProjectName,
+  exitComposeFailed,
+  runDockerCompose,
+  schemaEngineImageForPush,
+  writeSelfHostCompose,
+  type SelfHostComposePaths,
+} from "./self-host-compose.js"
+import type { DockerBrandOptions } from "./docker-runtime.js"
 import { hasEngineOverride } from "./binary-cache.js"
 import { startStudioViteDevServer } from "./studio-dev-server.js"
-import { ensureEngine, engineRequest } from "./engine-client.js"
+import { ensureEngine, engineRequest, type DiffResult } from "./engine-client.js"
+import { writeSchemaSourcePushArtifacts, type SchemaSourcePushArtifacts } from "./schema-sources.js"
+import { endDevSession } from "./dev-session.js"
+import { writeLocalEnvironment } from "./link.js"
+import { registerDevShutdown } from "./dev-shutdown.js"
+import {
+  filterComposeNoise,
+  formatEnginePushMessage,
+  parseEngineJsonOutput,
+  parseEnginePushOutput,
+} from "./engine-push-output.js"
 import { withAdminRoles } from "./studio-admin-roles.js"
+import { restoreSystemRelationTargets } from "./restore-system-relation-targets.js"
+import { provisionBucketsFromAst } from "./storage-provision.js"
+import type { ExtractedSchemaAstV2 } from "./schema-ast-v2.js"
+import { ensureFirstAdminUserForProject } from "./commands/admin.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)
+  const removeImageKeys = COMPOSE_PINNED_IMAGE_ENV_KEYS.filter((key) => !(key in imagePins))
+  upsertEnvFile(cwd, imagePins, removeImageKeys)
+}
+
 export interface DevComposeOptions {
   watch: boolean
 }
@@ -39,30 +74,12 @@ export function composeDbUrl(): string {
 
 /**
  * Resolve the host Kong port for this project. Persisted in `.env` as
- * SUPATYPE_KONG_PORT so re-runs are stable; on first run it picks the default
- * (18473) or the next free port, so multiple projects can run concurrently.
+ * SUPATYPE_KONG_PORT; prompts when the configured port is already taken.
  */
 async function resolveDevDbPort(cwd: string): Promise<number> {
-  const envPath = join(cwd, ".env")
-  if (existsSync(envPath)) {
-    const m = readFileSync(envPath, "utf8").match(/^SUPATYPE_DEV_DB_PORT=(\d+)/m)
-    if (m && m[1]) return Number(m[1])
-  }
-  let port = COMPOSE_DEV_DB_PORT
-  while (await isPortInUse(port)) port++
-  return port
-}
-
-function readEnvValue(cwd: string, key: string, fallback: string): string {
-  const envPath = join(cwd, ".env")
-  if (existsSync(envPath)) {
-    const m = readFileSync(envPath, "utf8").match(new RegExp(`^${key}=(.+)$`, "m"))
-    if (m?.[1]) return m[1].trim()
-  }
-  return fallback
+  return ensureDevDbPort(cwd)
 }
 
-/** Postgres DSN for compose db when published to the host (local engine push). */
 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")
@@ -71,40 +88,92 @@ function hostComposeDbUrl(cwd: string): string {
   return `postgresql://${user}:${pass}@127.0.0.1:${port}/${db}?sslmode=disable`
 }
 
-async function resolveKongPort(cwd: string): Promise<number> {
-  const envPath = join(cwd, ".env")
-  if (existsSync(envPath)) {
-    const m = readFileSync(envPath, "utf8").match(/^SUPATYPE_KONG_PORT=(\d+)/m)
-    if (m && m[1]) return Number(m[1])
-  }
-  let port = COMPOSE_DEV_KONG_PORT
-  while (await isPortInUse(port)) port++
-  return port
+/**
+ * When `provider: docker` and `overrides.engine` is set, ensure Postgres is published
+ * on the host (SUPATYPE_DEV_DB_PORT) so the local engine binary can connect.
+ */
+export async function ensureDockerDbPublishedForHostEngine(
+  cwd: string,
+  config: SupatypeProjectConfig,
+  brand?: DockerBrandOptions,
+): Promise<void> {
+  if (resolveRuntimeProvider(config) !== "docker") {
+    throw new Error("ensureDockerDbPublishedForHostEngine requires provider: docker")
+  }
+  if (!hasEngineOverride(config)) {
+    throw new Error(
+      "Docker Postgres is not published to the host without overrides.engine. " +
+        "Set overrides.engine in supatype.local.config.ts or pass --connection.",
+    )
+  }
+
+  const project = composeProjectName(config.project.name)
+  const kongPort = await resolveKongPort(cwd)
+  const devDbPort = await resolveDevDbPort(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)
+  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)
 }
 
-function upsertEnvFile(cwd: string, updates: Record<string, string>): void {
-  const envPath = join(cwd, ".env")
-  const existing = existsSync(envPath) ? readFileSync(envPath, "utf8") : ""
-  const keys = new Set(Object.keys(updates))
-  const kept = existing
-    .split("\n")
-    .filter((line) => {
-      const key = line.split("=")[0]?.trim()
-      return key && line.includes("=") && !keys.has(key)
-    })
-  const merged = [...kept, ...Object.entries(updates).map(([key, value]) => `${key}=${value}`)]
-  writeFileSync(envPath, `${merged.join("\n").trimEnd()}\n`, "utf8")
+/**
+ * True when CLI should publish local Compose Postgres for the host-side engine
+ * (local dev with overrides.engine). False for remote DB URLs via config or --connection.
+ */
+export function usesLocalDockerEngineDb(
+  config: SupatypeProjectConfig,
+  explicitConnection?: string,
+): boolean {
+  if (explicitConnection?.trim()) return false
+  if (config.connection?.trim()) return false
+  return resolveRuntimeProvider(config) === "docker" && hasEngineOverride(config)
 }
 
-/** Keep compose + Studio + Astro on the same freshly signed dev JWTs every `dev` / `push`. */
-function ensureDevComposeEnv(
+/**
+ * Resolve a Postgres URL reachable from the host-side engine binary.
+ * Local docker + overrides.engine → SUPATYPE_DEV_DB_PORT on localhost.
+ * Remote self-host → set `connection` in config or pass `--connection`.
+ */
+export async function resolveHostEngineDatabaseUrl(
+  cwd: string,
+  config: SupatypeProjectConfig,
+  explicit?: string,
+): Promise<string> {
+  if (explicit?.trim()) return explicit
+  if (config.connection?.trim()) return config.connection
+  if (usesLocalDockerEngineDb(config)) {
+    await ensureDockerDbPublishedForHostEngine(cwd, config)
+    return hostComposeDbUrl(cwd)
+  }
+  return connectionString(config)
+}
+
+async function resolveKongPort(cwd: string): Promise<number> {
+  return ensureKongPort(cwd, { context: "dev" })
+}
+
+function upsertDevComposeEnv(
   cwd: string,
+  config: SupatypeProjectConfig,
   anonKey: string,
   serviceRoleKey: string,
   kongPort: number,
   devDbPort?: number,
 ): void {
   const apiUrl = `http://localhost:${kongPort}`
+  const imagePins = composeDockerImageEnv(config)
   const updates: Record<string, string> = {
     POSTGRES_USER: "supatype_admin",
     POSTGRES_PASSWORD: "postgres",
@@ -113,16 +182,33 @@ function ensureDevComposeEnv(
     ANON_KEY: anonKey,
     SERVICE_ROLE_KEY: serviceRoleKey,
     PUBLIC_SUPATYPE_ANON_KEY: anonKey,
+    VITE_SUPATYPE_ANON_KEY: anonKey,
     PUBLIC_SUPATYPE_URL: apiUrl,
     SUPATYPE_KONG_PORT: String(kongPort),
     API_EXTERNAL_URL: apiUrl,
     SITE_URL: apiUrl,
     GOTRUE_MAILER_AUTOCONFIRM: "true",
+    ...imagePins,
   }
   if (devDbPort !== undefined) {
     updates.SUPATYPE_DEV_DB_PORT = String(devDbPort)
+    updates.DATABASE_URL =
+      `postgresql://supatype_admin:postgres@localhost:${devDbPort}/supatype?sslmode=disable`
   }
-  upsertEnvFile(cwd, updates)
+  const removeImageKeys = COMPOSE_PINNED_IMAGE_ENV_KEYS.filter((key) => !(key in imagePins))
+  upsertEnvFile(cwd, updates, removeImageKeys)
+}
+
+/** Keep compose + Studio on the same freshly signed dev JWTs; sync optional image pins from config. */
+function ensureDevComposeEnv(
+  cwd: string,
+  config: SupatypeProjectConfig,
+  anonKey: string,
+  serviceRoleKey: string,
+  kongPort: number,
+  devDbPort?: number,
+): void {
+  upsertDevComposeEnv(cwd, config, anonKey, serviceRoleKey, kongPort, devDbPort)
 }
 
 async function waitComposeHealthy(paths: SelfHostComposePaths, cwd: string, maxMs: number, composeProject: string): Promise<void> {
@@ -158,8 +244,18 @@ async function waitKongReady(kongPort: number, maxSec: number): Promise<void> {
   throw new Error(`Kong gateway at ${base} did not become ready within ${maxSec}s`)
 }
 
+async function provisionDockerStorageBuckets(
+  ast: ExtractedSchemaAstV2,
+  kongPort: number,
+  serviceRoleKey: string,
+): Promise<void> {
+  await provisionBucketsFromAst(ast, `http://localhost:${kongPort}/storage/v1`, serviceRoleKey)
+}
+
 let _lastPushedAst: string | null = null
 let _lastFailedAst: string | null = null
+let _composePushInFlight = false
+let _composePushQueued = false
 
 /**
  * Regenerate admin-config + TypeScript types from the AST using the **host** engine.
@@ -207,6 +303,7 @@ async function refreshSchemaArtifacts(
 
   try {
     const admin = withAdminRoles(await engineRequest<unknown>("/admin", { ast }), config)
+    restoreSystemRelationTargets(admin, ast)
     writeFileSync(adminConfigPath, `${JSON.stringify(admin, null, 2)}\n`)
     console.log("[supatype] Admin config written to .supatype/admin-config.json")
   } catch (err) {
@@ -245,12 +342,19 @@ async function runComposeSchemaPush(
     console.log("[supatype] Applying schema via local engine (overrides.engine)...")
     await ensureEngine()
     const pgSchema = config.schema?.pg_schema ?? "public"
+    const sources = writeSchemaSourcePushArtifacts(cwd)
     try {
       await engineRequest("/push", {
         ast,
         database_url: hostComposeDbUrl(cwd),
         schema: pgSchema,
         force: true,
+        ...(sources
+          ? {
+              schema_sources_gz_base64: sources.payload.dataBase64,
+              schema_sources_manifest: sources.payload.manifest,
+            }
+          : {}),
       })
     } catch (err) {
       _lastFailedAst = astJson
@@ -258,34 +362,66 @@ async function runComposeSchemaPush(
     }
     _lastPushedAst = astJson
     _lastFailedAst = null
+    if (astHasSystemAuthRelation(ast)) {
+      grantAuthSchemaAccess(paths, cwd, composeProject)
+    }
     console.log("[supatype] Schema applied.")
     return
   }
 
   console.log("[supatype] Applying schema via compose schema-engine...")
-  let push = runComposeEnginePush(paths, cwd, composeProject)
+  const sources = writeSchemaSourcePushArtifacts(cwd)
+  let push = await runComposeEnginePush(paths, cwd, composeProject, config, sources)
   // Windows Docker bind mounts can lag briefly after the host write.
   if (push.status !== 0) {
     await new Promise((r) => setTimeout(r, 250))
-    push = runComposeEnginePush(paths, cwd, composeProject)
+    push = await runComposeEnginePush(paths, cwd, composeProject, config, sources)
   }
   if (push.status !== 0) {
     _lastFailedAst = astJson
-    throw new Error(push.output || `Engine schema push failed (exit ${push.status})`)
+    const detail = filterComposeNoise(push.output) || push.output
+    throw new Error(detail || `Engine schema push failed (exit ${push.status})`)
   }
   _lastPushedAst = astJson
   _lastFailedAst = null
 
-  console.log("[supatype] Schema applied.")
+  if (astHasSystemAuthRelation(ast)) {
+    grantAuthSchemaAccess(paths, cwd, composeProject)
+  }
+}
+
+/** Serialize watch-triggered pushes so docker output cannot interleave. */
+async function runComposeSchemaPushQueued(
+  cwd: string,
+  config: SupatypeProjectConfig,
+  paths: SelfHostComposePaths,
+  schemaPath: string,
+  composeProject: string,
+): Promise<void> {
+  if (_composePushInFlight) {
+    _composePushQueued = true
+    return
+  }
+  _composePushInFlight = true
+  try {
+    do {
+      _composePushQueued = false
+      await runComposeSchemaPush(cwd, config, paths, schemaPath, composeProject)
+    } while (_composePushQueued)
+  } finally {
+    _composePushInFlight = false
+  }
 }
 
-function runComposeEnginePush(
+async function runComposeEnginePush(
   paths: SelfHostComposePaths,
   cwd: string,
   composeProject: string,
-): { status: number; output: string } {
+  config: SupatypeProjectConfig,
+  sources?: SchemaSourcePushArtifacts | null,
+): Promise<{ status: number; output: string }> {
   const envFile = resolve(cwd, ".env")
-  const composeArgs = ["compose"]
+  const composeArgs = ["compose", "--progress", "quiet"]
   if (composeProject) composeArgs.push("-p", composeProject)
   composeArgs.push("--project-directory", cwd)
   composeArgs.push("-f", paths.composePath)
@@ -306,16 +442,159 @@ function runComposeEnginePush(
     "--force",
     "--non-interactive",
   )
+  if (sources) {
+    composeArgs.push(
+      "--schema-sources-gz",
+      sources.dockerGzPath,
+      "--schema-sources-manifest",
+      sources.dockerManifestPath,
+    )
+  }
+  const pushEnv: NodeJS.ProcessEnv = {
+    ...process.env,
+    COMPOSE_PROGRESS: "quiet",
+  }
+  const engineImage = await schemaEngineImageForPush(config)
+  if (engineImage) {
+    pushEnv.SUPATYPE_ENGINE_IMAGE = engineImage
+  }
   const result = spawnSync("docker", composeArgs, {
     cwd,
     encoding: "utf8",
     maxBuffer: 10 * 1024 * 1024,
+    env: pushEnv,
   })
   const output = `${result.stdout ?? ""}${result.stderr ?? ""}`.trim()
-  if (output.length > 0) {
-    console.error(output)
+  const exitStatus = result.status ?? 1
+  const pushResult = parseEnginePushOutput(output)
+
+  if (exitStatus === 0) {
+    if (pushResult) {
+      console.log(`[supatype] ${formatEnginePushMessage(pushResult)}`)
+    } else {
+      console.log("[supatype] Schema applied.")
+    }
   }
-  return { status: result.status ?? 1, output }
+
+  return { status: exitStatus, output }
+}
+
+async function runComposeEngineDiff(
+  paths: SelfHostComposePaths,
+  cwd: string,
+  composeProject: string,
+  config: SupatypeProjectConfig,
+  pgSchema: string,
+): Promise<{ status: number; output: string; diff: DiffResult | null }> {
+  const envFile = resolve(cwd, ".env")
+  const composeArgs = ["compose", "--progress", "quiet"]
+  if (composeProject) composeArgs.push("-p", composeProject)
+  composeArgs.push("--project-directory", cwd)
+  composeArgs.push("-f", paths.composePath)
+  if (existsSync(envFile)) {
+    composeArgs.push("--env-file", envFile)
+  }
+  composeArgs.push(
+    "--profile",
+    "tools",
+    "run",
+    "--rm",
+    "schema-engine",
+    "diff",
+    "-i",
+    "/project/.supatype/schema.ast.json",
+    "--database-url",
+    composeDbUrl(),
+    "--schema",
+    pgSchema,
+  )
+  const diffEnv: NodeJS.ProcessEnv = {
+    ...process.env,
+    COMPOSE_PROGRESS: "quiet",
+  }
+  const engineImage = await schemaEngineImageForPush(config)
+  if (engineImage) {
+    diffEnv.SUPATYPE_ENGINE_IMAGE = engineImage
+  }
+  const result = spawnSync("docker", composeArgs, {
+    cwd,
+    encoding: "utf8",
+    maxBuffer: 10 * 1024 * 1024,
+    env: diffEnv,
+  })
+  const output = `${result.stdout ?? ""}${result.stderr ?? ""}`.trim()
+  const exitStatus = result.status ?? 1
+  const diff = parseEngineJsonOutput<DiffResult>(output)
+
+  return { status: exitStatus, output, diff }
+}
+
+/**
+ * `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
+ * through the local engine binary.
+ */
+export async function diffSchemaDocker(cwd: string, config: SupatypeProjectConfig): Promise<DiffResult> {
+  if (resolveRuntimeProvider(config) !== "docker") {
+    throw new Error("diffSchemaDocker requires provider: docker")
+  }
+  const project = composeProjectName(config.project.name)
+  const pgSchema = config.schema?.pg_schema ?? "public"
+
+  if (hasEngineOverride(config)) {
+    const brand = { intro: "Schema diff" }
+    await ensureDockerDbPublishedForHostEngine(cwd, config, brand)
+    const schemaPath = schemaPathFromProject(config, cwd)
+    const ast = loadSchemaAst(schemaPath, cwd)
+    await ensureEngine()
+    return engineRequest<DiffResult>("/diff", {
+      ast,
+      database_url: hostComposeDbUrl(cwd),
+      schema: pgSchema,
+    })
+  }
+
+  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)
+  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)
+
+  const schemaPath = schemaPathFromProject(config, cwd)
+  const ast = loadSchemaAst(schemaPath, cwd)
+
+  const supatypeDir = join(cwd, ".supatype")
+  mkdirSync(supatypeDir, { recursive: true })
+  const astPath = join(supatypeDir, "schema.ast.json")
+  writeFileSync(astPath, JSON.stringify(ast))
+
+  let result = await runComposeEngineDiff(paths, cwd, project, config, pgSchema)
+  // Windows Docker bind mounts can lag briefly after the host write.
+  if (result.status !== 0) {
+    await new Promise((r) => setTimeout(r, 250))
+    result = await runComposeEngineDiff(paths, cwd, project, config, pgSchema)
+  }
+  if (result.status !== 0) {
+    const detail = filterComposeNoise(result.output) || result.output
+    throw new Error(detail || `Engine schema diff failed (exit ${result.status})`)
+  }
+  if (!result.diff) {
+    throw new Error("Engine diff returned no result")
+  }
+  return result.diff
 }
 
 /**
@@ -335,17 +614,39 @@ export async function pushSchemaDocker(cwd: string, config: SupatypeProjectConfi
   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)
-  ensureDevComposeEnv(cwd, anonKey, serviceRoleKey, kongPort, devDbPort)
+  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)
-  if (up !== 0) process.exit(up)
+  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)
 
   const schemaPath = schemaPathFromProject(config, cwd)
+  const ast = loadSchemaAst(schemaPath, cwd)
   await runComposeSchemaPush(cwd, config, paths, schemaPath, project)
+
+  const upGateway = runDockerCompose(paths.composePath, ["up", "-d"], cwd, project, {
+    quiet: true,
+    brand: pushBrand,
+  })
+  if (upGateway !== 0) {
+    exitComposeFailed(upGateway, "Could not start the Compose gateway stack.", pushBrand)
+  }
+  await waitKongReady(kongPort, 120)
+  await provisionDockerStorageBuckets(ast, kongPort, serviceRoleKey)
+
+  await ensureFirstAdminUserForProject(cwd, config, {
+    compose: { project, composePath: paths.composePath },
+  })
+
   console.log("[supatype] Schema pushed.")
 }
 
@@ -365,13 +666,22 @@ export async function runDevCompose(cwd: string, config: SupatypeProjectConfig,
   const anonKey = signJwt({ ...jwtBase, role: "anon" }, LOCAL_JWT_SECRET)
   const serviceRoleKey = signJwt({ ...jwtBase, role: "service_role" }, LOCAL_JWT_SECRET)
 
-  ensureDevComposeEnv(cwd, anonKey, serviceRoleKey, kongPort, devDbPort)
+  ensureDevComposeEnv(cwd, config, anonKey, serviceRoleKey, kongPort, devDbPort)
 
   console.log(`[supatype] provider: docker — starting self-host Compose stack (project ${project}, gateway :${kongPort})...`)
   const paths = writeSelfHostCompose(cwd, config, { devLocal: true })
+  await recoverStaleDevSession(cwd)
+  await handleComposeProjectRename(cwd, config.project.name, paths)
+  const devBrand = { intro: "Local development" }
 
-  const upStatus = runDockerCompose(paths.composePath, ["up", "-d"], cwd, project)
-  if (upStatus !== 0) process.exit(upStatus)
+  const upStatus = runDockerCompose(paths.composePath, ["up", "-d"], cwd, project, {
+    quiet: true,
+    brand: devBrand,
+  })
+  if (upStatus !== 0) {
+    endDevSession()
+    exitComposeFailed(upStatus, "Could not start the local Compose stack.", devBrand)
+  }
 
   console.log("[supatype] Waiting for Postgres (compose)...")
   await waitComposeHealthy(paths, cwd, 180_000, project)
@@ -381,9 +691,33 @@ export async function runDevCompose(cwd: string, config: SupatypeProjectConfig,
     console.error("[supatype] Initial schema push failed:", (e as Error).message),
   )
 
+  await ensureFirstAdminUserForProject(cwd, config, {
+    compose: { project, composePath: paths.composePath },
+  })
+
   console.log("[supatype] Waiting for API gateway...")
   await waitKongReady(kongPort, 120)
 
+  writeLocalEnvironment(cwd, {
+    target: "local",
+    apiUrl: `http://localhost:${kongPort}`,
+    databaseUrl: hasEngineOverride(config) ? hostComposeDbUrl(cwd) : composeDbUrl(),
+    projectRef: config.project.name,
+    kongPort,
+    provider: "docker",
+  })
+
+  writeDevSessionLock(cwd, {
+    composeProject: project,
+    projectRef: config.project.name,
+    composePath: paths.composePath,
+    kongPort,
+    startedAt: new Date().toISOString(),
+  })
+
+  const ast = loadSchemaAst(schemaPath, cwd)
+  await provisionDockerStorageBuckets(ast, kongPort, serviceRoleKey)
+
   const pidDir = join(homedir(), ".supatype", "projects", config.project.name, "pid")
   mkdirSync(pidDir, { recursive: true })
 
@@ -423,33 +757,85 @@ export async function runDevCompose(cwd: string, config: SupatypeProjectConfig,
 
   const appProc = startProxyDevApp(cwd, config, pidDir)
 
-  const cleanup = async () => {
-    console.log("\n[supatype] Shutting down compose...")
+  let schemaWatcher: import("node:fs").FSWatcher | null = null
+  let debounceTimer: ReturnType<typeof setTimeout> | null = null
+
+  registerDevShutdown(async () => {
+    schemaWatcher?.close()
+    schemaWatcher = null
+    if (debounceTimer) {
+      clearTimeout(debounceTimer)
+      debounceTimer = null
+    }
+    console.log("[supatype] Shutting down compose...")
     await studioProc?.stop()
     await appProc?.stop()
-    runDockerCompose(paths.composePath, ["down"], cwd, project)
-    process.exit(0)
-  }
-  process.once("SIGINT", () => void cleanup())
-  process.once("SIGTERM", () => void cleanup())
+    const downStatus = runDockerCompose(paths.composePath, ["down"], cwd, project, { quiet: true })
+    if (downStatus === 0) {
+      console.log("[supatype] Compose stack stopped.")
+    } else {
+      console.warn(`[supatype] Compose down exited with status ${downStatus}.`)
+    }
+  }, {
+    cwd,
+    compose: { cwd, composePath: paths.composePath, composeProject: project },
+  })
 
   if (opts.watch) {
     const schemaDir = join(projectRootFromConfig(config, cwd), config.schema?.path ?? "schema/index.ts", "..")
     console.log(`[supatype] Watching ${schemaDir} for changes...`)
     const { watch } = await import("node:fs")
-    let debounceTimer: ReturnType<typeof setTimeout> | null = null
-    watch(schemaDir, { recursive: true }, (_eventType, filename) => {
+    schemaWatcher = watch(schemaDir, { recursive: true }, (_eventType, filename) => {
       if (!filename?.endsWith(".ts")) return
       if (debounceTimer) clearTimeout(debounceTimer)
       debounceTimer = setTimeout(() => {
         debounceTimer = null
         console.log(`\n[supatype] Change detected in ${filename}, pushing schema...`)
-        runComposeSchemaPush(cwd, config, paths, schemaPath, project).catch((e: unknown) =>
-          console.error("[supatype] Schema push failed:", (e as Error).message),
-        )
+        runComposeSchemaPushQueued(cwd, config, paths, schemaPath, project)
+          .then(async () => {
+            const updatedAst = loadSchemaAst(schemaPath, cwd)
+            await provisionDockerStorageBuckets(updatedAst, kongPort, serviceRoleKey)
+          })
+          .catch((e: unknown) =>
+            console.error("[supatype] Schema push failed:", (e as Error).message),
+          )
       }, 300)
     })
   }
 
   await new Promise<never>(() => undefined)
 }
+
+function astHasSystemAuthRelation(ast: unknown): boolean {
+  const obj = ast as { models?: Array<{ fields?: Record<string, { kind?: string; target?: string }> }> }
+  if (!obj?.models) return false
+  for (const model of obj.models) {
+    if (!model.fields) continue
+    for (const field of Object.values(model.fields)) {
+      if (field.kind === "relation" && field.target === "supatype:user") return true
+    }
+  }
+  return false
+}
+
+function grantAuthSchemaAccess(
+  paths: SelfHostComposePaths,
+  cwd: string,
+  composeProject: string,
+): void {
+  const composeDir = dirname(paths.composePath)
+  const baseArgs = [
+    "compose", "-p", composeProject,
+    "-f", paths.composePath,
+  ]
+  const sql = "GRANT USAGE ON SCHEMA auth TO service_role; GRANT SELECT ON auth.users TO service_role;"
+  const result = spawnSync(
+    "docker",
+    [...baseArgs, "exec", "-T", "-e", "PGPASSWORD=postgres", "db",
+     "psql", "-U", "supatype_admin", "-d", "supatype", "-c", sql],
+    { 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.")
+  }
+}