@supatype/cli 0.1.4 → 0.1.5

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,
@@ -236,12 +237,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 +463,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 +816,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 +897,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. */

package/src/realtime-launch.ts

@@ -0,0 +1,52 @@
+import { existsSync } from "node:fs"
+import { dirname, join, resolve } from "node:path"
+import { fileURLToPath } from "node:url"
+import { ensureBinary } from "./ensure-binary.js"
+import type { SupatypeProjectConfig } from "./project-config.js"
+
+export interface RealtimeLaunchSpec {
+  bin: string
+  args: string[]
+}
+
+const CLI_PKG_DIR = dirname(fileURLToPath(import.meta.url))
+
+/** Monorepo contributor fallback: packages/realtime/dist/index.js relative to CLI package. */
+function monorepoRealtimeEntry(): string | null {
+  const candidate = resolve(CLI_PKG_DIR, "../../realtime/dist/index.js")
+  return existsSync(candidate) ? candidate : null
+}
+
+/**
+ * Resolve how to spawn supatype-realtime for native dev.
+ * Order: overrides.realtime → CDN binary → node + monorepo dist.
+ */
+export async function resolveRealtimeLaunch(
+  config: SupatypeProjectConfig,
+  cwd: string,
+): Promise<RealtimeLaunchSpec> {
+  const override = config.overrides?.realtime?.trim()
+  if (override) {
+    const resolved = resolve(cwd, override)
+    if (!existsSync(resolved)) {
+      throw new Error(`[overrides] realtime path does not exist: ${resolved}`)
+    }
+    if (resolved.endsWith(".js") || resolved.endsWith(".mjs") || resolved.endsWith(".cjs")) {
+      return { bin: process.execPath, args: [resolved] }
+    }
+    return { bin: resolved, args: [] }
+  }
+
+  try {
+    const bin = await ensureBinary("realtime", config)
+    return { bin, args: [] }
+  } catch {
+    const entry = monorepoRealtimeEntry()
+    if (entry) {
+      return { bin: process.execPath, args: [entry] }
+    }
+    throw new Error(
+      "realtime binary not available — run `supatype update` or set overrides.realtime in supatype.config.ts",
+    )
+  }
+}

package/src/required-host-components.ts

@@ -23,7 +23,7 @@ export function requiredHostComponents(
     return ["engine"]
   }
 
-  const components: Component[] = ["engine", "server", "postgres"]
+  const components: Component[] = ["engine", "server", "postgres", "realtime"]
   const hasFunctions = functionsPathCandidatesFromProject(config, cwd).some((dir) =>
     existsSync(dir),
   )

package/src/route-manifest.ts

@@ -0,0 +1,17 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs"
+
+/** Merge fields into `.supatype/manifest.json` (creates file if missing). */
+export function patchRouteManifest(
+  manifestPath: string,
+  patch: Record<string, unknown>,
+): void {
+  let manifest: Record<string, unknown> = {}
+  if (existsSync(manifestPath)) {
+    try {
+      manifest = JSON.parse(readFileSync(manifestPath, "utf8")) as Record<string, unknown>
+    } catch {
+      manifest = {}
+    }
+  }
+  writeFileSync(manifestPath, `${JSON.stringify({ ...manifest, ...patch }, null, 2)}\n`, "utf8")
+}

package/src/schema-push-lock.ts

@@ -0,0 +1,131 @@
+/**
+ * Advisory lock held while compose schema push runs so realtime can skip WAL
+ * decoding without stopping the realtime process (self-host safe).
+ *
+ * Must stay in sync with:
+ *   - packages/realtime/src/schema-push-lock.ts
+ *   - supatype-schema-engine (pg_advisory_xact_lock on the same keys)
+ */
+
+import { existsSync } from "node:fs"
+import { resolve } from "node:path"
+import { spawn, spawnSync, type ChildProcess } from "node:child_process"
+import type { SelfHostComposePaths } from "./self-host-compose.js"
+import { readEnvValue } from "./env-file.js"
+
+export const SCHEMA_PUSH_LOCK_CLASSID = 872014
+export const SCHEMA_PUSH_LOCK_OBJID = 1
+
+function composeBaseArgs(
+  paths: SelfHostComposePaths,
+  cwd: string,
+  composeProject: string,
+): string[] {
+  const envFile = resolve(cwd, ".env")
+  const args = ["compose", "-p", composeProject, "--project-directory", cwd, "-f", paths.composePath]
+  if (existsSync(envFile)) args.push("--env-file", envFile)
+  return args
+}
+
+function dbExecArgs(
+  paths: SelfHostComposePaths,
+  cwd: string,
+  composeProject: string,
+  psqlArgs: string[],
+): string[] {
+  const pass = readEnvValue(cwd, "POSTGRES_PASSWORD", "postgres")
+  const user = readEnvValue(cwd, "POSTGRES_USER", "supatype_admin")
+  const db = readEnvValue(cwd, "POSTGRES_DB", "supatype")
+  return [
+    ...composeBaseArgs(paths, cwd, composeProject),
+    "exec",
+    "-T",
+    "-e",
+    `PGPASSWORD=${pass}`,
+    "db",
+    "psql",
+    "-U",
+    user,
+    "-d",
+    db,
+    "-v",
+    "ON_ERROR_STOP=1",
+    ...psqlArgs,
+  ]
+}
+
+function schemaPushLockIsHeld(
+  paths: SelfHostComposePaths,
+  cwd: string,
+  composeProject: string,
+): boolean {
+  const args = dbExecArgs(paths, cwd, composeProject, [
+    "-tAc",
+    `SELECT EXISTS (
+       SELECT 1 FROM pg_locks
+       WHERE locktype = 'advisory'
+         AND classid = ${SCHEMA_PUSH_LOCK_CLASSID}
+         AND objid = ${SCHEMA_PUSH_LOCK_OBJID}
+         AND granted
+     )`,
+  ])
+  const result = spawnSync("docker", args, { cwd, encoding: "utf8" })
+  return result.status === 0 && result.stdout.trim() === "t"
+}
+
+/**
+ * Hold a session advisory lock for the duration of `fn` via a background
+ * `psql` inside the compose db container. Killing the holder releases the lock.
+ */
+export async function withComposeSchemaPushLock<T>(
+  paths: SelfHostComposePaths,
+  cwd: string,
+  composeProject: string,
+  fn: () => Promise<T>,
+): Promise<T> {
+  const holdSql =
+    `SELECT pg_advisory_lock(${SCHEMA_PUSH_LOCK_CLASSID}, ${SCHEMA_PUSH_LOCK_OBJID});` +
+    ` SELECT pg_sleep(86400);`
+  const args = dbExecArgs(paths, cwd, composeProject, ["-c", holdSql])
+
+  let stderrBuf = ""
+  const holder: ChildProcess = spawn("docker", args, {
+    cwd,
+    stdio: ["ignore", "pipe", "pipe"],
+  })
+  holder.stderr?.on("data", (chunk: Buffer) => {
+    stderrBuf += chunk.toString()
+  })
+
+  const deadline = Date.now() + 30_000
+  while (Date.now() < deadline) {
+    if (holder.exitCode !== null) {
+      const err = stderrBuf.trim() || "lock holder exited"
+      throw new Error(`[supatype] Failed to acquire schema-push advisory lock: ${err}`)
+    }
+    if (schemaPushLockIsHeld(paths, cwd, composeProject)) break
+    await new Promise((r) => setTimeout(r, 200))
+  }
+  if (!schemaPushLockIsHeld(paths, cwd, composeProject)) {
+    holder.kill("SIGTERM")
+    throw new Error("[supatype] Timed out waiting for schema-push advisory lock")
+  }
+
+  try {
+    return await fn()
+  } finally {
+    if (holder.exitCode === null) {
+      holder.kill("SIGTERM")
+      await new Promise<void>((resolveDone) => {
+        const t = setTimeout(() => {
+          holder.kill("SIGKILL")
+          resolveDone()
+        }, 3000)
+        holder.once("exit", () => {
+          clearTimeout(t)
+          resolveDone()
+        })
+      })
+    }
+  }
+}

package/src/self-host-compose.ts

@@ -383,6 +383,20 @@ ${dbPorts}    volumes:
       db:
         condition: service_healthy
 
+  realtime:
+    image: \${SUPATYPE_REALTIME_IMAGE:-supatype/realtime:latest}
+    expose:
+      - "4000"
+    environment:
+      PORT: "4000"
+      DATABASE_URL: "postgresql://\${POSTGRES_USER:-supatype_admin}:\${POSTGRES_PASSWORD:-postgres}@db:5432/\${POSTGRES_DB:-supatype}"
+      JWT_SECRET: \${JWT_SECRET:-super-secret-jwt-token-change-in-production}
+      SLOT_NAME: supatype_realtime
+      PUBLICATION_NAME: supatype_realtime_pub
+    depends_on:
+      db:
+        condition: service_healthy
+
   control-plane:
     image: \${SUPATYPE_CONTROL_PLANE_IMAGE:-supatype/control-plane:latest}
     expose:
@@ -423,6 +437,7 @@ ${serverPorts}    volumes:
       SUPATYPE_SQL_DATABASE_URL: "postgresql://\${POSTGRES_USER:-supatype_admin}:\${POSTGRES_PASSWORD:-postgres}@db:5432/\${POSTGRES_DB:-supatype}"
       SUPATYPE_DENO_FUNCTIONS_DIR: /project/functions
       SUPATYPE_FUNCTIONS_WORKER_URL: http://functions-worker:8001
+      SUPATYPE_REALTIME_URL: http://realtime:4000
       SUPATYPE_CONTROL_PLANE_URL: http://control-plane:8080
       SUPATYPE_VALKEY_ADDR: valkey:6379
 ${appEnv}
@@ -452,6 +467,8 @@ ${devLocal ? "      STUDIO_OPEN_DEV: \"1\"\n" : ""}
         condition: service_started
       functions-worker:
         condition: service_started
+      realtime:
+        condition: service_started
       control-plane:
         condition: service_started
 
@@ -502,6 +519,7 @@ function ensureComposeManifest(cwd: string): void {
     postgrest_url: "http://postgrest:3000",
     storage_url: "http://storage:5000",
     realtime_enabled: true,
+    realtime_url: "http://realtime:4000",
     functions_enabled: false,
   }
   writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, "utf8")