@supatype/cli 0.1.0-alpha.9 → 0.1.0

package/src/dev-compose.ts

@@ -10,6 +10,7 @@ import { startProxyDevApp } from "./app/proxy-dev-app.js"
 import { loadSchemaAst } from "./config.js"
 import {
   COMPOSE_DEV_KONG_PORT,
+  connectionString,
   projectRootFromConfig,
   resolveRuntimeProvider,
   schemaPathFromProject,
@@ -17,17 +18,47 @@ import {
 } 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 {
+  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"
 
 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
 }
@@ -71,6 +102,78 @@ function hostComposeDbUrl(cwd: string): string {
   return `postgresql://${user}:${pass}@127.0.0.1:${port}/${db}?sslmode=disable`
 }
 
+/**
+ * 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)
+}
+
+/**
+ * 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)
+}
+
+/**
+ * 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> {
   const envPath = join(cwd, ".env")
   if (existsSync(envPath)) {
@@ -82,10 +185,14 @@ async function resolveKongPort(cwd: string): Promise<number> {
   return port
 }
 
-function upsertEnvFile(cwd: string, updates: Record<string, string>): void {
+function upsertEnvFile(
+  cwd: string,
+  updates: Record<string, string>,
+  removeKeys: readonly string[] = [],
+): void {
   const envPath = join(cwd, ".env")
   const existing = existsSync(envPath) ? readFileSync(envPath, "utf8") : ""
-  const keys = new Set(Object.keys(updates))
+  const keys = new Set([...Object.keys(updates), ...removeKeys])
   const kept = existing
     .split("\n")
     .filter((line) => {
@@ -96,15 +203,17 @@ function upsertEnvFile(cwd: string, updates: Record<string, string>): void {
   writeFileSync(envPath, `${merged.join("\n").trimEnd()}\n`, "utf8")
 }
 
-/** Keep compose + Studio + Astro on the same freshly signed dev JWTs every `dev` / `push`. */
+/** 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 {
   const apiUrl = `http://localhost:${kongPort}`
+  const imagePins = composeDockerImageEnv(config)
   const updates: Record<string, string> = {
     POSTGRES_USER: "supatype_admin",
     POSTGRES_PASSWORD: "postgres",
@@ -118,11 +227,15 @@ function ensureDevComposeEnv(
     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)
 }
 
 async function waitComposeHealthy(paths: SelfHostComposePaths, cwd: string, maxMs: number, composeProject: string): Promise<void> {
@@ -158,8 +271,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 +330,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 +369,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 +389,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 +469,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 +641,35 @@ 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)
+
   console.log("[supatype] Schema pushed.")
 }
 
@@ -365,13 +689,20 @@ 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 })
+  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)
@@ -384,6 +715,18 @@ export async function runDevCompose(cwd: string, config: SupatypeProjectConfig,
   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",
+  })
+
+  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 +766,82 @@ 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}.`)
+    }
+  })
 
   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.")
+  }
+}