@supatype/cli 0.1.4 → 0.1.6

package/src/binary-cache.ts

@@ -1,7 +1,7 @@
 /**
  * Binary cache — manages supatype component binaries.
  *
- * Components: engine, server, postgres, deno.
+ * Components: engine, server, postgres, deno, realtime.
  * Cache root: ~/.supatype/cache/{component}/{version}/
  * Override path: config.overrides?.{component} (local build path).
  *
@@ -85,6 +85,7 @@ export function describeActiveOverrides(config: SupatypeProjectConfig): string[]
   add("server", o.server)
   add("postgres_dir", o.postgres_dir)
   add("deno", o.deno)
+  add("realtime", o.realtime)
   add("studio", o.studio)
   add("postgrest", o.postgrest)
   return lines
@@ -151,6 +152,7 @@ const CDN_PATHS: Record<Component, (version: string, platform: PlatformId) => st
   server:   (v, p) => `/server/v${v}/supatype-server-${p.os}-${p.arch}${p.os === "windows" ? ".exe" : ""}`,
   postgres: (v, p) => `/postgres/v${v}/supatype-pg-${postgresArchiveTag(v)}-${p.os}-${p.arch}${p.os === "windows" ? ".zip" : ".tar.gz"}`,
   deno:     (v, p) => `/deno/v${v}/deno-${p.os}-${p.arch}${p.os === "windows" ? ".exe" : ""}`,
+  realtime: (v, p) => `/realtime/v${v}/supatype-realtime-${p.os}-${p.arch}${p.os === "windows" ? ".exe" : ""}`,
 }
 
 // Checksums file path (one per version directory, covers all platform binaries).
@@ -190,6 +192,7 @@ function binaryName(component: Component, version: string, platform: PlatformId)
     case "server":   return `supatype-server-${platform.os}-${platform.arch}${win ? ".exe" : ""}`
     case "postgres": return `supatype-pg-${postgresArchiveTag(version)}-${platform.os}-${platform.arch}${win ? ".zip" : ".tar.gz"}`
     case "deno":     return `deno-${platform.os}-${platform.arch}${win ? ".exe" : ""}`
+    case "realtime": return `supatype-realtime-${platform.os}-${platform.arch}${win ? ".exe" : ""}`
   }
 }
 
@@ -630,7 +633,7 @@ async function streamToFileWithProgress(url: string, destPath: string): Promise<
 // SHA256 verification
 // ---------------------------------------------------------------------------
 
-const EXECUTABLE_COMPONENTS = new Set<Component>(["engine", "server", "deno"])
+const EXECUTABLE_COMPONENTS = new Set<Component>(["engine", "server", "deno", "realtime"])
 
 /** True when a cached file matches expected format for the current platform. */
 function cachedArtifactLooksValid(component: Component, filePath: string): boolean {
@@ -655,7 +658,7 @@ export function validateArtifactFormat(
 
 /**
  * Per-component CDN artifact shapes:
- *   engine, server, deno — native executable (ELF / Mach-O / PE)
+ *   engine, server, deno, realtime — native executable (ELF / Mach-O / PE)
  *   postgres (unix)      — .tar.gz (gzip)
  *   postgres (windows)   — .zip
  */
@@ -867,12 +870,22 @@ export async function fetchLatestVersion(component: Component): Promise<string>
   return data.version.trim()
 }
 
-/** Fetch the latest version for all components concurrently. */
-export async function fetchAllLatestVersions(): Promise<Record<Component, string>> {
+/** Fetch the latest version for all components concurrently. Missing CDN entries are omitted. */
+export async function fetchAllLatestVersions(): Promise<Partial<Record<Component, string>>> {
   const results = await Promise.all(
-    BINARY_COMPONENTS.map(async (c) => [c, await fetchLatestVersion(c)] as const),
+    BINARY_COMPONENTS.map(async (c) => {
+      try {
+        return [c, await fetchLatestVersion(c)] as const
+      } catch {
+        return [c, undefined] as const
+      }
+    }),
   )
-  return Object.fromEntries(results) as Record<Component, string>
+  const out: Partial<Record<Component, string>> = {}
+  for (const [c, v] of results) {
+    if (v) out[c] = v
+  }
+  return out
 }
 
 // ---------------------------------------------------------------------------
@@ -885,8 +898,10 @@ export async function fetchAllLatestVersions(): Promise<Record<Component, string
  * Fails gracefully when graceful=true (suitable for postinstall).
  */
 /**
- * Verify all cached binaries for the current platform (used by integration CI).
- * Throws if any cached component is missing or fails format checks.
+ * Verify cached binaries for the current platform (used by integration CI).
+ * Only checks components present in `versions` — unpublished CDN components
+ * (no latest.json yet) are skipped with a log so CI can land before first release.
+ * Throws if a pinned component is missing from cache or fails format checks.
  */
 export function verifyCachedBinaries(versions: Partial<ComponentVersions> | undefined): void {
   if (!versions) {
@@ -896,7 +911,10 @@ export function verifyCachedBinaries(versions: Partial<ComponentVersions> | unde
   for (const component of BINARY_COMPONENTS) {
     const version = versions[component]
     if (typeof version !== "string" || version.trim() === "") {
-      throw new Error(`[supatype] versions.${component} must be set`)
+      console.log(
+        `[supatype] skipping verify for ${component} (no version — CDN latest.json not published yet)`,
+      )
+      continue
     }
     const destPath = join(cachePath(component, version), binaryName(component, version, platform))
     if (!cachedArtifactLooksValid(component, destPath)) {
@@ -918,7 +936,7 @@ export async function downloadAll(
 
   for (const component of components) {
     const version = versions?.[component] ?? latest[component]
-    if (version === VERSION_PIN_LOCAL) continue
+    if (!version || version === VERSION_PIN_LOCAL) continue
     try {
       await download(component, version, platform)
     } catch (err) {

package/src/cli-standalone.ts

@@ -0,0 +1,62 @@
+/**
+ * Standalone CLI binary CDN download (self-update + curl|sh installers).
+ */
+
+import { chmodSync, existsSync, mkdirSync, writeFileSync } from "node:fs"
+import { homedir } from "node:os"
+import { join } from "node:path"
+import { currentPlatform, type PlatformId } from "./binary-cache.js"
+
+const CDN_BASE = "https://releases.supatype.com"
+
+export function cliCdnPath(version: string, platform: PlatformId): string {
+  const win = platform.os === "windows"
+  return `/cli/v${version}/supatype-cli-${platform.os}-${platform.arch}${win ? ".exe" : ""}`
+}
+
+export function cliCachePath(version: string, platform: PlatformId = currentPlatform()): string {
+  const win = platform.os === "windows"
+  const name = `supatype-cli-${platform.os}-${platform.arch}${win ? ".exe" : ""}`
+  return join(homedir(), ".supatype", "cache", "cli", version, name)
+}
+
+export async function fetchStandaloneCliLatestVersion(): Promise<string> {
+  const resp = await fetch(`${CDN_BASE}/cli/latest.json`)
+  if (!resp.ok) {
+    throw new Error(`Failed to fetch CLI latest.json: HTTP ${resp.status}`)
+  }
+  const data = await resp.json() as { version?: unknown }
+  if (typeof data.version !== "string" || data.version.trim() === "") {
+    throw new Error("Invalid cli/latest.json: missing version")
+  }
+  return data.version.trim()
+}
+
+/** Download the standalone CLI binary for the current platform. */
+export async function downloadStandaloneCli(version?: string): Promise<string> {
+  const platform = currentPlatform()
+  const resolved = version ?? await fetchStandaloneCliLatestVersion()
+  const dest = cliCachePath(resolved, platform)
+  if (existsSync(dest)) return dest
+
+  const url = `${CDN_BASE}${cliCdnPath(resolved, platform)}`
+  const resp = await fetch(url)
+  if (!resp.ok) {
+    throw new Error(`Failed to download CLI from ${url}: HTTP ${resp.status}`)
+  }
+  const buf = Buffer.from(await resp.arrayBuffer())
+  if (buf.length < 64) {
+    throw new Error("Downloaded CLI artifact is too small")
+  }
+  const head = buf.subarray(0, 5).toString("utf8").toLowerCase()
+  if (head.startsWith("<!doc") || head.startsWith("{")) {
+    throw new Error("Downloaded CLI artifact looks like an error page, not a binary")
+  }
+
+  mkdirSync(join(dest, ".."), { recursive: true })
+  writeFileSync(dest, buf)
+  if (platform.os !== "windows") {
+    chmodSync(dest, 0o755)
+  }
+  return dest
+}

package/src/commands/admin.ts

@@ -69,6 +69,16 @@ export interface EnsureFirstAdminOptions {
   compose?: { project: string; composePath: string }
 }
 
+function resolveAdminConnection(
+  cwd: string,
+  config: SupatypeProjectConfig,
+  override?: string,
+): string {
+  if (override !== undefined) return override
+  if (hasEngineOverride(config)) return hostComposeDbUrlFromEnv(cwd)
+  return readEnvValue(cwd, "DATABASE_URL", connectionString(config))
+}
+
 export function registerAdmin(program: Command): void {
   const adminCmd = program
     .command("admin")
@@ -90,7 +100,7 @@ export function registerAdmin(program: Command): void {
       }) => {
         const cwd = process.cwd()
         const config = loadConfig(cwd)
-        const connection = opts.connection ?? connectionString(config)
+        const connection = resolveAdminConnection(cwd, config, opts.connection)
 
         const email = opts.email ?? (await promptText("Admin email"))
         if (!email || !email.includes("@")) {
@@ -150,7 +160,7 @@ export function registerAdmin(program: Command): void {
       async (opts: { email: string; role: string; connection?: string }) => {
         const cwd = process.cwd()
         const config = loadConfig(cwd)
-        const connection = opts.connection ?? connectionString(config)
+        const connection = resolveAdminConnection(cwd, config, opts.connection)
 
         const pg = await importPg()
         const pool = new pg.Pool({ connectionString: connection, max: 2 })
@@ -198,7 +208,7 @@ export function registerAdmin(program: Command): void {
     .action(async (opts: { connection?: string }) => {
       const cwd = process.cwd()
       const config = loadConfig(cwd)
-      const connection = opts.connection ?? connectionString(config)
+      const connection = resolveAdminConnection(cwd, config, opts.connection)
 
       const pg = await importPg()
       const pool = new pg.Pool({ connectionString: connection, max: 2 })

package/src/commands/dev.ts

@@ -44,6 +44,9 @@ import { publishDevReady } from "../dev-ready-panel.js"
 import { probeDockerDaemon, reportDockerUnavailable } from "../docker-runtime.js"
 import { fatalError } from "../ui/fatal.js"
 import { registerDevShutdown } from "../dev-shutdown.js"
+import { patchRouteManifest } from "../route-manifest.js"
+import { resolveRealtimeLaunch } from "../realtime-launch.js"
+import { writeAppViteEnv } from "../app-vite-env.js"
 import { ensureValkeySidecar, stopValkeySidecar } from "../valkey-sidecar.js"
 import {
   initdb,
@@ -72,6 +75,7 @@ function gotrueSMTPFromEmailConfig(email: SupatypeProjectConfig["email"] | undef
 }
 
 const NATIVE_PG_PORT = 5432
+const REALTIME_PORT = "4000"
 
 function portCheckCommand(port: number): string {
   return process.platform === "win32"
@@ -316,6 +320,38 @@ ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON SEQUENCES TO authenticate
       const anonKey        = signJwt({ ...jwtBase, role: "anon" },         LOCAL_JWT_SECRET)
       const serviceRoleKey = signJwt({ ...jwtBase, role: "service_role" }, LOCAL_JWT_SECRET)
 
+      const realtimeUrl = `http://127.0.0.1:${REALTIME_PORT}`
+      patchRouteManifest(manifestPath, {
+        realtime_enabled: true,
+        realtime_url: realtimeUrl,
+      })
+
+      writeAppViteEnv(cwd, config, `http://localhost:${serverPort}`, anonKey)
+
+      let realtimeProc: ProcessManager | null = null
+      try {
+        const launch = await resolveRealtimeLaunch(config, cwd)
+        realtimeProc = new ProcessManager(launch.bin, launch.args, {
+          label: "realtime",
+          pidDir,
+          colour: "\x1b[35m",
+          env: {
+            DATABASE_URL: dbURL,
+            JWT_SECRET: LOCAL_JWT_SECRET,
+            PORT: REALTIME_PORT,
+            SLOT_NAME: "supatype_realtime",
+            PUBLICATION_NAME: "supatype_realtime_pub",
+          },
+        })
+        realtimeProc.start()
+        console.log(`[supatype] Realtime service: ${realtimeUrl}`)
+      } catch (err) {
+        console.warn(
+          `[supatype] ⚠  Realtime unavailable — WebSocket subscriptions will not work.\n` +
+            `  ${(err as Error).message}`,
+        )
+      }
+
 
       const emailProvider = config.email?.provider ?? "console"
       const gotrueMailerProvider =
@@ -344,6 +380,7 @@ ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON SEQUENCES TO authenticate
           ? { SUPATYPE_DENO_SERVE_SCRIPT: denoServeScriptAbs }
           : {}),
         SUPATYPE_URL: `http://localhost:${serverPort}`,
+        SUPATYPE_REALTIME_URL: realtimeUrl,
         SUPATYPE_ANON_KEY: anonKey,
         SUPATYPE_SERVICE_ROLE_KEY: serviceRoleKey,
         PORT: serverPort,
@@ -518,6 +555,7 @@ ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON SEQUENCES TO authenticate
         console.log("[supatype] Shutting down...")
         await Promise.all([
           serverProc.stop(),
+          realtimeProc?.stop(),
           postgrestProc?.stop(),
           studioProc?.stop(),
           appProc?.stop(),

package/src/commands/init.ts

@@ -1201,7 +1201,9 @@ SITE_URL=http://localhost:3000`)
       `# Local API gateway (Kong) — unique per project so multiple stacks can run concurrently
 SUPATYPE_KONG_PORT=${opts.kongPort}
 PUBLIC_SUPATYPE_URL=${apiUrl}
-API_EXTERNAL_URL=${apiUrl}`,
+API_EXTERNAL_URL=${apiUrl}
+VITE_SUPATYPE_URL=${apiUrl}
+VITE_SUPATYPE_ANON_KEY=`,
     )
   }
 

package/src/commands/keys.ts

@@ -70,6 +70,14 @@ export function generateAndWriteKeys(
     let content = readFileSync(envPath, "utf8")
     content = upsertEnvVar(content, "ANON_KEY", anonKey)
     content = upsertEnvVar(content, "SERVICE_ROLE_KEY", serviceKey)
+    content = upsertEnvVar(content, "VITE_SUPATYPE_ANON_KEY", anonKey)
+    content = upsertEnvVar(content, "PUBLIC_SUPATYPE_ANON_KEY", anonKey)
+    content = upsertEnvVar(content, "EXPO_PUBLIC_SUPATYPE_ANON_KEY", anonKey)
+    const apiUrl = readEnvVar(content, "PUBLIC_SUPATYPE_URL") ?? readEnvVar(content, "API_EXTERNAL_URL")
+    if (apiUrl) {
+      content = upsertEnvVar(content, "VITE_SUPATYPE_URL", apiUrl)
+      content = upsertEnvVar(content, "EXPO_PUBLIC_SUPATYPE_URL", apiUrl)
+    }
     writeFileSync(envPath, content, "utf8")
   }
 
@@ -83,6 +91,14 @@ function upsertEnvVar(content: string, key: string, value: string): string {
   return `${content}${sep}${key}=${value}\n`
 }
 
+function readEnvVar(content: string, key: string): string | undefined {
+  const re = new RegExp(`^${key}=(.*)$`, "m")
+  const match = re.exec(content)
+  if (!match?.[1]) return undefined
+  const value = match[1].trim()
+  return value.length > 0 ? value : undefined
+}
+
 export function resolveSecret(dir: string = process.cwd()): string | undefined {
   // 1. Check environment variable
   const fromEnv = process.env["JWT_SECRET"]

package/src/commands/self-update.ts

@@ -2,12 +2,14 @@
  * supatype self-update — Phase 10.6C8.
  *
  * npm-installed CLI: instruct to use `npm update -g`.
- * Standalone / future curl|sh installs: CDN-published CLI binary replacement is not wired yet.
+ * Standalone curl|sh installs: replace binary from releases.supatype.com/cli/.
  */
 
 import type { Command } from "commander"
+import { copyFileSync, renameSync } from "node:fs"
 import { sep } from "node:path"
-import { error, plain } from "../ui/messages.js"
+import { downloadStandaloneCli, fetchStandaloneCliLatestVersion } from "../cli-standalone.js"
+import { error, info, plain } from "../ui/messages.js"
 
 function looksLikeNpmOrWorkspaceCLI(): boolean {
   const main = process.argv[1] ?? ""
@@ -23,24 +25,43 @@ function looksLikeNpmOrWorkspaceCLI(): boolean {
 export function registerSelfUpdate(program: Command): void {
   program
     .command("self-update")
-    .description(
-      "Update the supatype CLI (npm: use npm update; standalone binary swap from CDN is not available yet)",
-    )
-    .action(() => {
+    .description("Update the supatype CLI (npm or standalone CDN binary)")
+    .action(async () => {
       if (looksLikeNpmOrWorkspaceCLI()) {
         plain(
           "This CLI was installed via npm (or runs from the package workspace).\n" +
             "Update with:\n\n  npm update -g @supatype/cli\n\n" +
-            "To bump engine/server/postgres/deno pinned in supatype.config.ts, use:\n\n  supatype update\n",
+            "To bump engine/server/postgres/deno/realtime pinned in supatype.config.ts, use:\n\n  supatype update\n",
         )
         return
       }
 
-      error(
-        "Standalone CLI self-update (replace binary from CDN) is not published yet.\n\n" +
-          "Install or upgrade via npm:\n  npm install -g @supatype/cli\n\n" +
-          "Component binaries (engine, server, postgres, deno):\n  supatype update\n",
-      )
-      process.exit(1)
+      const currentPath = process.argv[1]
+      if (!currentPath) {
+        error("Could not determine current CLI path.")
+        process.exit(1)
+      }
+
+      try {
+        const latest = await fetchStandaloneCliLatestVersion()
+        info(`Downloading supatype CLI v${latest}...`)
+        const downloaded = await downloadStandaloneCli(latest)
+        const backup = `${currentPath}.bak`
+        copyFileSync(currentPath, backup)
+        try {
+          renameSync(downloaded, currentPath)
+        } catch (err) {
+          copyFileSync(downloaded, currentPath)
+        }
+        info(`Updated to v${latest}.`)
+        plain("Run `supatype --version` to verify.")
+      } catch (err) {
+        error(
+          `Standalone CLI self-update failed: ${(err as Error).message}\n\n` +
+            "Install or upgrade via npm:\n  npm install -g @supatype/cli\n\n" +
+            "Component binaries (engine, server, postgres, deno, realtime):\n  supatype update\n",
+        )
+        process.exit(1)
+      }
     })
 }

package/src/commands/update.ts

@@ -59,7 +59,7 @@ export function registerUpdate(program: Command): void {
 
       const platform = currentPlatform()
 
-      const components: Component[] = ["engine", "server", "postgres", "deno"]
+      const components: Component[] = ["engine", "server", "postgres", "deno", "realtime"]
       const updates: Array<{ component: Component; from: string; to: string }> = []
 
       info("Fetching latest component versions from CDN...")
@@ -67,6 +67,14 @@ export function registerUpdate(program: Command): void {
 
       for (const component of components) {
         const latest = latestVersions[component]
+        if (!latest) {
+          if (component === "realtime") {
+            info(`Skipping ${component}: not published on CDN yet`)
+            continue
+          }
+          error(`No latest version for ${component} on CDN`)
+          continue
+        }
         const current = pinnedVersion(component, config)
         if (!current) {
           if (opts.check) {

package/src/components.ts

@@ -1,5 +1,5 @@
-/** CDN-cached binaries resolved by the CLI (`engine`, `server`, `postgres`, `deno`). */
-export const BINARY_COMPONENTS = ["engine", "server", "postgres", "deno"] as const
+/** CDN-cached binaries resolved by the CLI (`engine`, `server`, `postgres`, `deno`, `realtime`). */
+export const BINARY_COMPONENTS = ["engine", "server", "postgres", "deno", "realtime"] as const
 
 export type Component = (typeof BINARY_COMPONENTS)[number]
 

package/src/dev-compose.ts

@@ -8,6 +8,7 @@ import { dirname, join, resolve } from "node:path"
 import { spawnSync } from "node:child_process"
 import { startProxyDevApp, resolveProxyDevScript } from "./app/proxy-dev-app.js"
 import { loadSchemaAst } from "./config.js"
+import { withComposeSchemaPushLock } from "./schema-push-lock.js"
 import {
   COMPOSE_DEV_KONG_PORT,
   connectionString,
@@ -187,7 +188,9 @@ function upsertDevComposeEnv(
     SERVICE_ROLE_KEY: serviceRoleKey,
     PUBLIC_SUPATYPE_ANON_KEY: anonKey,
     VITE_SUPATYPE_ANON_KEY: anonKey,
+    EXPO_PUBLIC_SUPATYPE_ANON_KEY: anonKey,
     PUBLIC_SUPATYPE_URL: apiUrl,
+    EXPO_PUBLIC_SUPATYPE_URL: apiUrl,
     SUPATYPE_KONG_PORT: String(kongPort),
     API_EXTERNAL_URL: apiUrl,
     SITE_URL: apiUrl,
@@ -236,12 +239,69 @@ async function waitComposeHealthy(paths: SelfHostComposePaths, cwd: string, maxM
   throw new Error("Compose db service did not become healthy in time")
 }
 
+/** True when the named compose service has a running container. */
+function composeServiceIsRunning(
+  paths: SelfHostComposePaths,
+  cwd: string,
+  composeProject: string,
+  service: string,
+): boolean {
+  const envFile = join(cwd, ".env")
+  const args = ["compose", "-p", composeProject, "--project-directory", cwd, "-f", paths.composePath]
+  if (existsSync(envFile)) args.push("--env-file", envFile)
+  args.push("ps", "-q", "--status", "running", service)
+  const result = spawnSync("docker", args, { cwd, encoding: "utf8" })
+  return result.status === 0 && typeof result.stdout === "string" && result.stdout.trim() !== ""
+}
+
+/**
+ * Capture Postgres container logs before compose down destroys them.
+ * Writes `.supatype/ci-logs/db-*.log` and prints a tail for CI job logs.
+ */
+function dumpComposeDbLogs(
+  paths: SelfHostComposePaths,
+  cwd: string,
+  composeProject: string,
+  reason: string,
+): void {
+  const logDir = join(cwd, ".supatype", "ci-logs")
+  mkdirSync(logDir, { recursive: true })
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-")
+  const logPath = join(logDir, `db-${stamp}.log`)
+
+  const envFile = join(cwd, ".env")
+  const args = ["compose", "-p", composeProject, "--project-directory", cwd, "-f", paths.composePath]
+  if (existsSync(envFile)) args.push("--env-file", envFile)
+  args.push("logs", "--no-color", "--timestamps", "--tail", "800", "db")
+
+  const result = spawnSync("docker", args, {
+    cwd,
+    encoding: "utf8",
+    maxBuffer: 10 * 1024 * 1024,
+  })
+  const body = `${result.stdout ?? ""}${result.stderr ?? ""}`.trim()
+  const content = body || `(empty — docker compose logs db exit ${result.status ?? "?"})\n`
+  try {
+    writeFileSync(logPath, content)
+  } catch {
+    /* best-effort */
+  }
+
+  const lines = content.split("\n")
+  const tail = lines.slice(-200).join("\n")
+  console.error(`[supatype] Postgres logs after ${reason} (saved ${logPath}):`)
+  console.error(tail)
+}
+
 async function waitKongReady(kongPort: number, maxSec: number): Promise<void> {
   const base = `http://localhost:${kongPort}`
   for (let i = 0; i < maxSec; i++) {
     try {
-      const res = await fetch(`${base}/auth/v1/health`)
-      if (res.ok) return
+      const [auth, realtime] = await Promise.all([
+        fetch(`${base}/auth/v1/health`),
+        fetch(`${base}/realtime/v1/health`),
+      ])
+      if (auth.ok && realtime.ok) return
     } catch {
       /* retry */
     }
@@ -405,12 +465,20 @@ async function runComposeSchemaPush(
 
   console.log("[supatype] Applying schema via compose schema-engine...")
   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 = await runComposeEnginePush(paths, cwd, composeProject, config, sources)
+  const runPush = async () => {
+    let result = await runComposeEnginePush(paths, cwd, composeProject, config, sources)
+    // Windows Docker bind mounts can lag briefly after the host write.
+    if (result.status !== 0) {
+      await new Promise((r) => setTimeout(r, 250))
+      result = await runComposeEnginePush(paths, cwd, composeProject, config, sources)
+    }
+    return result
   }
+  // 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)
+    : await runPush()
   if (push.status !== 0) {
     _lastFailedAst = astJson
     const detail = filterComposeNoise(push.output) || push.output
@@ -750,23 +818,71 @@ export async function runDevCompose(cwd: string, config: SupatypeProjectConfig,
   await recoverStaleDevSession(cwd)
   await handleComposeProjectRename(cwd, config.project.name, paths)
 
-  console.log("[supatype] Bringing up Docker Compose services...")
-  const upStatus = runDockerCompose(paths.composePath, ["up", "-d"], cwd, project, {
+  console.log("[supatype] Bringing up Postgres (compose db)...")
+  const upDbStatus = runDockerCompose(paths.composePath, ["up", "-d", "db"], cwd, project, {
     quiet: true,
     brand: devBrand,
   })
-  if (upStatus !== 0) {
+  if (upDbStatus !== 0) {
     endDevSession()
-    exitComposeFailed(upStatus, "Could not start the local Compose stack.", devBrand)
+    exitComposeFailed(upDbStatus, "Could not start Postgres (compose db service).", devBrand)
   }
 
   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 new Promise((r) => setTimeout(r, 3000))
 
+  // A: apply schema before realtime (and the rest of the stack) starts decoding WAL.
   const schemaPath = schemaPathFromProject(config, cwd)
-  await runComposeSchemaPush(cwd, config, paths, schemaPath, project).catch((e: unknown) =>
-    console.error("[supatype] Initial schema push failed:", (e as Error).message),
-  )
+  {
+    const maxAttempts = 3
+    let lastErr: unknown
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      try {
+        await runComposeSchemaPush(cwd, config, paths, schemaPath, project)
+        lastErr = undefined
+        break
+      } catch (e: unknown) {
+        lastErr = e
+        console.error(
+          `[supatype] Initial schema push failed (attempt ${attempt}/${maxAttempts}):`,
+          (e as Error).message,
+        )
+        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)
+          await new Promise((r) => setTimeout(r, 3000 * attempt))
+        }
+      }
+    }
+    if (lastErr) {
+      dumpComposeDbLogs(paths, cwd, project, "initial schema push exhausted")
+      endDevSession()
+      throw new Error(
+        `Initial schema push failed after ${maxAttempts} attempts: ${(lastErr as Error).message}`,
+      )
+    }
+  }
+
+  console.log("[supatype] Bringing up Docker Compose services...")
+  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)
+  }
 
   if (localServerImage !== undefined) {
     console.log("[supatype] Recreating server with local image...")
@@ -783,6 +899,22 @@ 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(
+      paths.composePath,
+      ["up", "-d", "--force-recreate", "--no-deps", "realtime"],
+      cwd,
+      project,
+      { quiet: true, brand: devBrand },
+    )
+    if (rtStatus !== 0) {
+      endDevSession()
+      exitComposeFailed(rtStatus, "Could not recreate the realtime container.", devBrand)
+    }
+  }
+
   console.log("[supatype] Waiting for API gateway...")
   await waitKongReady(kongPort, 120)
   console.log("[supatype] Waiting for storage API...")

package/src/project-config.ts

@@ -116,6 +116,8 @@ export interface SupatypeProjectConfig {
     postgres_dir?: string
     /** Path to a local deno binary. */
     deno?: string
+    /** Path to a local supatype-realtime binary (or node entry script). */
+    realtime?: string
     /** Path to the @supatype/studio package directory (starts Vite dev server). */
     studio?: string
     /** Path to a local PostgREST binary. */