@supatype/cli 0.1.0-alpha.10

package/src/docker-postgres.ts

@@ -0,0 +1,295 @@
+/**
+ * docker-postgres — manage a supatype/postgres Docker container for local dev.
+ *
+ * Used by `supatype dev` when database.provider = "docker".
+ * The container is named supatype-{projectName} and persists data in a
+ * named Docker volume (supatype-{projectName}-data) across restarts.
+ */
+
+import { spawnSync } from "node:child_process"
+
+export interface DockerPgOptions {
+  /** Docker image to run. Defaults to supatype/postgres:latest. */
+  image: string
+  /** Project name — used to derive the container and volume names. */
+  projectName: string
+  /** Host port to bind to container's 5432. */
+  port: number
+  /** Superuser password (dev only). Defaults to "postgres". */
+  password?: string
+}
+
+const PG_USER = "supatype_admin"
+/** Must match `dockerPgStart` default `POSTGRES_PASSWORD`. */
+const DEFAULT_DEV_PASSWORD = "postgres"
+
+function dockerPgPsql(
+  name: string,
+  db: string,
+  sql: string,
+  password = DEFAULT_DEV_PASSWORD,
+) {
+  return spawnSync(
+    "docker",
+    [
+      "exec",
+      "-e", `PGPASSWORD=${password}`,
+      name,
+      "psql", "--no-password", "-U", PG_USER, "-d", db, "-tAc", sql,
+    ],
+    { encoding: "utf8", stdio: "pipe" },
+  )
+}
+
+/** Derived container name for a project. */
+export function containerName(projectName: string): string {
+  return `supatype-${projectName}`
+}
+
+/**
+ * Start the supatype/postgres Docker container.
+ * Removes any stopped container with the same name before starting.
+ * Throws if `docker run` exits non-zero.
+ */
+export function dockerPgStart(opts: DockerPgOptions): void {
+  const { image, projectName, port, password = "postgres" } = opts
+  const name = containerName(projectName)
+  const volume = `${name}-data`
+
+  // Remove any stopped container from a previous session.
+  spawnSync("docker", ["rm", "-f", name], { encoding: "utf8" })
+
+  const result = spawnSync(
+    "docker",
+    [
+      "run", "-d",
+      "--name", name,
+      "-e", `POSTGRES_USER=${PG_USER}`,
+      "-e", `POSTGRES_PASSWORD=${password}`,
+      "-e", `POSTGRES_DB=${projectName}`,
+      "-p", `${port}:5432`,
+      "-v", `${volume}:/var/lib/postgresql/data`,
+      image,
+    ],
+    { encoding: "utf8", stdio: "pipe" },
+  )
+
+  if (result.status !== 0) {
+    const detail = (result.stderr ?? result.stdout ?? "").trim()
+    throw new Error(
+      `Failed to start Docker container "${name}".\n` +
+        (detail ? `  docker: ${detail}\n` : "") +
+        `  Is Docker running?  docker info`,
+    )
+  }
+}
+
+/**
+ * Stop the container (fast — does not remove it or the data volume).
+ * Safe to call even if the container is not running.
+ */
+export function dockerPgStop(projectName: string): void {
+  spawnSync("docker", ["stop", containerName(projectName)], { encoding: "utf8" })
+}
+
+function dockerPgLogsTail(name: string, tail = 120): string {
+  const logs = spawnSync(
+    "docker",
+    ["logs", "--tail", String(tail), name],
+    { encoding: "utf8" },
+  )
+  return `${logs.stdout ?? ""}${logs.stderr ?? ""}`
+}
+
+function dockerPgHealthStatus(name: string): string | undefined {
+  const inspect = spawnSync(
+    "docker",
+    ["inspect", "-f", "{{if .State.Health}}{{.State.Health.Status}}{{end}}", name],
+    { encoding: "utf8", stdio: "pipe" },
+  )
+  if (inspect.status !== 0) return undefined
+  const status = inspect.stdout?.trim()
+  return status === "" ? undefined : status
+}
+
+/** True when the final post-init Postgres process is accepting connections. */
+export function dockerPgPostInitServing(logs: string): boolean {
+  const ready = "database system is ready to accept connections"
+  const lastReady = logs.lastIndexOf(ready)
+  if (lastReady === -1) return false
+
+  const initDone = logs.lastIndexOf("PostgreSQL init process complete")
+  if (initDone === -1) {
+    // Reused data volume — this run did not re-run entrypoint init.
+    return true
+  }
+  return initDone < lastReady
+}
+
+function migrateStillRunning(logs: string): boolean {
+  return /99-supatype-migrate\.sh: running .+\.sql/.test(logs)
+}
+
+function psqlTruthy(stdout: string | undefined): boolean {
+  const v = (stdout ?? "").replace(/\r/g, "").trim().toLowerCase()
+  return v === "t" || v === "true"
+}
+
+const ANON_ROLE_SQL = "SELECT EXISTS (SELECT FROM pg_roles WHERE rolname = 'anon')"
+
+function dockerPgHasAnonRole(
+  name: string,
+  projectName: string,
+  password = DEFAULT_DEV_PASSWORD,
+): boolean {
+  for (const db of [projectName, "postgres"]) {
+    const result = dockerPgPsql(name, db, ANON_ROLE_SQL, password)
+    if (result.status === 0 && psqlTruthy(result.stdout)) return true
+  }
+  return false
+}
+
+function dockerPgExecReady(name: string): boolean {
+  const ready = spawnSync(
+    "docker",
+    ["exec", name, "pg_isready", "-U", PG_USER, "-q"],
+    { encoding: "utf8", stdio: "pipe" },
+  )
+  return ready.status === 0
+}
+
+/**
+ * Poll until Postgres accepts connections and the image entrypoint init has
+ * finished (anon/authenticated/service_role come from supatype-postgres
+ * migrations/db/init-scripts/00000000000000-initial-schema.sql via migrate.sh).
+ */
+export async function dockerPgWaitReady(
+  projectName: string,
+  timeoutMs = 180_000,
+  password = DEFAULT_DEV_PASSWORD,
+): Promise<void> {
+  const name = containerName(projectName)
+  const deadline = Date.now() + timeoutMs
+  let servingWithoutAnonMs = 0
+  let lastPsqlDetail = ""
+
+  while (Date.now() < deadline) {
+    const health = dockerPgHealthStatus(name)
+    const logs = dockerPgLogsTail(name)
+    const serving =
+      health === "healthy" ||
+      dockerPgPostInitServing(logs) ||
+      dockerPgExecReady(name)
+
+    if (serving && !migrateStillRunning(logs)) {
+      if (dockerPgHasAnonRole(name, projectName, password)) return
+
+      const probe = dockerPgPsql(name, projectName, ANON_ROLE_SQL, password)
+      lastPsqlDetail = [
+        probe.status !== 0 ? `psql exit ${probe.status}` : "",
+        probe.stderr?.trim(),
+        probe.stdout?.trim() ? `stdout=${probe.stdout.trim()}` : "",
+      ]
+        .filter(Boolean)
+        .join("; ")
+
+      const reusedVolume =
+        logs.includes("database system is ready to accept connections") &&
+        !logs.includes("PostgreSQL init process complete")
+
+      if (reusedVolume) {
+        servingWithoutAnonMs += 500
+        if (servingWithoutAnonMs >= 5_000) throw staleVolumeError(name)
+      } else {
+        servingWithoutAnonMs = 0
+      }
+    } else {
+      servingWithoutAnonMs = 0
+    }
+
+    await sleep(500)
+  }
+
+  const logs = dockerPgLogsTail(name, 80)
+  throw new Error(
+    `Docker Postgres "${name}" did not finish image init within ${timeoutMs}ms.\n` +
+      "  API roles (anon, authenticated, service_role) are created by the supatype/postgres\n" +
+      "  entrypoint (99-supatype-migrate.sh), not by the CLI.\n" +
+      "  If you upgraded the image, remove the stale volume:\n" +
+      `    docker volume rm ${name}-data\n` +
+      (lastPsqlDetail ? `  Last anon probe: ${lastPsqlDetail}\n` : "") +
+      (logs ? `  logs (tail):\n${indent(logs)}\n` : ""),
+  )
+}
+
+function staleVolumeError(name: string): Error {
+  return new Error(
+    `Docker Postgres "${name}" is up but API roles are missing.\n` +
+      "  The data volume was initialised without supatype/postgres migrations (stale or wrong image).\n" +
+      "  Remove the volume so first-boot 99-supatype-migrate.sh runs again:\n" +
+      `    docker volume rm ${name}-data`,
+  )
+}
+
+/** Connection string for the Docker container (local dev credentials). */
+export function dockerDbUrl(projectName: string, port: number, password = DEFAULT_DEV_PASSWORD): string {
+  // Host → published port. sqlx/libpq "prefer" can mis-handle SSL on some hosts (e.g. Docker Desktop on Windows).
+  return `postgres://${PG_USER}:${password}@127.0.0.1:${port}/${projectName}?sslmode=disable`
+}
+
+/**
+ * DB URL for processes sharing the Postgres container network namespace
+ * (supatype-server migrate in a one-shot container). Uses loopback inside the
+ * container where pg_hba grants trust — avoids host-published-port SCRAM/SSL issues.
+ */
+export function dockerPgLoopbackDbUrl(projectName: string, password = DEFAULT_DEV_PASSWORD): string {
+  return `postgres://${PG_USER}:${password}@127.0.0.1:5432/${projectName}?sslmode=disable`
+}
+
+/**
+ * Published Hub tag for local dev when CDN server version is not on Docker Hub yet.
+ * Keep in sync with tests/integration/scripts/compose-smoke.sh.
+ */
+export const DEFAULT_SERVER_DOCKER_IMAGE = "supatype/server:latest"
+
+/**
+ * Run `supatype-server migrate` on the Postgres container network (loopback trust).
+ * Used on Windows + database.provider docker — host-published :5432 breaks libpq TLS there.
+ */
+export function runGotrueMigrationsViaDocker(
+  pgContainerName: string,
+  serverImage: string,
+  migrateEnv: Record<string, string>,
+): void {
+  const envArgs = Object.entries(migrateEnv).flatMap(([k, v]) => ["-e", `${k}=${v}`])
+  const result = spawnSync(
+    "docker",
+    [
+      "run", "--rm",
+      "--network", `container:${pgContainerName}`,
+      ...envArgs,
+      serverImage,
+      "migrate",
+    ],
+    { encoding: "utf8", stdio: "pipe" },
+  )
+  if (result.status !== 0) {
+    const detail = (result.stderr ?? result.stdout ?? "").trim()
+    throw new Error(
+      `GoTrue migrations failed in Docker (exit ${result.status ?? "unknown"})` +
+        (detail ? `:\n${detail}` : ""),
+    )
+  }
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+function indent(s: string): string {
+  return s
+    .trimEnd()
+    .split("\n")
+    .map((l) => `    ${l}`)
+    .join("\n")
+}

package/src/engine-client.ts

@@ -0,0 +1,236 @@
+/**
+ * engine-client.ts — subprocess-based engine invocation.
+ *
+ * Replaces the former HTTP-based engine client (Docker container API).
+ * All callers use the same interface; only the transport changed.
+ *
+ * The engine binary reads a request JSON file passed via --request-file and
+ * writes a response JSON to stdout.
+ */
+
+import { spawnSync } from "node:child_process"
+import { mkdirSync, writeFileSync, unlinkSync, existsSync, readdirSync } from "node:fs"
+import { tmpdir, homedir } from "node:os"
+import { join } from "node:path"
+import { loadConfig } from "./config.js"
+import { resolveBinary, currentPlatform, cachePath } from "./binary-cache.js"
+
+// ---------------------------------------------------------------------------
+// Types (kept for backward compatibility with existing callers)
+// ---------------------------------------------------------------------------
+
+export interface Operation {
+  kind: "create_table" | "alter_table" | "drop_table" | "create_index" | "drop_index" |
+        "create_policy" | "drop_policy" | "add_column" | "drop_column" | "alter_column" |
+        "recreate_column"
+  type?: string
+  description?: string
+  risk?: "safe" | "warn" | "danger" | "cautious" | "destructive"
+  warning?: string
+  sql?: string
+}
+
+export interface DiffResult {
+  operations: Operation[]
+  warnings?: string[]
+  summary?: string
+}
+
+export interface IntrospectResult {
+  models: Array<{
+    name: string
+    table: string
+    columns: Array<{
+      name: string
+      type: string
+      nullable: boolean
+      default?: string
+      primaryKey?: boolean
+      unique?: boolean
+      references?: { table: string; column: string }
+    }>
+  }>
+}
+
+export interface EngineResult<T = unknown> {
+  ok: boolean
+  data: T
+  message?: string
+  error?: string
+}
+
+export class EngineError extends Error {
+  constructor(
+    message: string,
+    public readonly endpoint: string,
+    public readonly exitCode: number | null,
+  ) {
+    super(message)
+    this.name = "EngineError"
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Engine binary resolution
+// ---------------------------------------------------------------------------
+
+let _engineBin: string | null = null
+
+async function getEngineBin(): Promise<string> {
+  if (_engineBin) return _engineBin
+
+  const cwd = process.cwd()
+
+  try {
+    const config = loadConfig(cwd)
+    _engineBin = await resolveBinary("engine", config)
+    return _engineBin
+  } catch {
+    // No valid project config — fall through to default cache path.
+  }
+
+  // No config found — scan the cache for any available engine binary.
+  const platform = currentPlatform()
+  const engineCacheDir = join(homedir(), ".supatype", "cache", "engine")
+  try {
+    const cachedVersions = readdirSync(engineCacheDir).sort()
+    for (const version of cachedVersions.reverse()) {
+      const bin = join(cachePath("engine", version), `supatype-engine-${platform.os}-${platform.arch}`)
+      if (existsSync(bin)) {
+        _engineBin = bin
+        return _engineBin
+      }
+    }
+  } catch { /* cache dir doesn't exist */ }
+
+  throw new Error(
+    "Engine binary not found. Run: supatype update",
+  )
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/** Verify the engine binary is accessible. Throws if not found. */
+export async function ensureEngine(): Promise<void> {
+  await getEngineBin()
+}
+
+/** Check if the engine can be invoked. Returns true/false. */
+export async function engineHealth(): Promise<boolean> {
+  try {
+    const bin = await getEngineBin()
+    const result = spawnSync(bin, ["--version"], { encoding: "utf8" })
+    return result.status === 0
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Invoke the engine and return a typed result.
+ *
+ * The endpoint maps to a subcommand:
+ *   /diff        → engine diff
+ *   /push        → engine push
+ *   /generate    → engine generate
+ *   /migrations  → engine migrations
+ *   /introspect  → engine introspect
+ *   /validate    → engine validate
+ *   /admin       → engine admin (admin-config JSON on stdout)
+ */
+export async function engineRequest<T = unknown>(
+  endpoint: string,
+  body: Record<string, unknown>,
+): Promise<T> {
+  const bin = await getEngineBin()
+
+  // Write request to a temp file.
+  // For CLI-mode endpoints the engine reads the input file as a raw SchemaAst,
+  // so we extract the `ast` field when present, otherwise write the full body.
+  const tmpDir = join(tmpdir(), "supatype-engine")
+  mkdirSync(tmpDir, { recursive: true })
+  const reqFile = join(tmpDir, `req-${Date.now()}.json`)
+  const inputPayload = body["ast"] !== undefined ? body["ast"] : body
+  writeFileSync(reqFile, JSON.stringify(inputPayload))
+
+  const args = endpointToArgs(endpoint, body, reqFile)
+
+  const result = spawnSync(bin, args, {
+    encoding: "utf8",
+    cwd: process.cwd(),
+  })
+
+  // Clean up temp file.
+  try { unlinkSync(reqFile) } catch { /* ignore */ }
+
+  if (result.status !== 0) {
+    const stderr = result.stderr?.trim() || "(no output)"
+    throw new EngineError(
+      `Engine ${endpoint} failed (exit ${result.status}): ${stderr}`,
+      endpoint,
+      result.status,
+    )
+  }
+
+  if (!result.stdout?.trim()) {
+    // Some subcommands print nothing on success.
+    return {} as T
+  }
+
+  try {
+    return JSON.parse(result.stdout) as T
+  } catch {
+    // Non-JSON stdout — return as message.
+    return { message: result.stdout.trim() } as T
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Endpoint → CLI args mapping
+// ---------------------------------------------------------------------------
+
+function endpointToArgs(
+  endpoint: string,
+  body: Record<string, unknown>,
+  reqFile: string,
+): string[] {
+  const dbUrl = (body["database_url"] as string | undefined) ?? ""
+  const schema = (body["schema"] as string | undefined) ?? "public"
+  const force = body["force"] ? ["--force"] : []
+  const nonInteractive =
+    body["non_interactive"] === true || body["force"] === true ? ["--non-interactive"] : []
+
+  switch (endpoint) {
+    case "/diff":
+      return ["diff", "--input", reqFile, "--database-url", dbUrl, "--schema", schema]
+
+    case "/push":
+      return ["push", "--input", reqFile, "--database-url", dbUrl, "--schema", schema, ...force, ...nonInteractive]
+
+    case "/parse":
+      return ["parse", "--input", reqFile]
+
+    case "/generate": {
+      const lang = (body["lang"] as string | undefined) ?? "typescript"
+      return ["generate", "--input", reqFile, "--lang", lang]
+    }
+
+    case "/introspect":
+      return ["introspect", "--database-url", dbUrl, "--schema", schema]
+
+    case "/validate":
+      return ["validate", "--input", reqFile]
+
+    case "/admin":
+      return ["admin", "--input", reqFile]
+
+    default:
+      if (endpoint.startsWith("/migrations")) {
+        const action = (body["action"] as string | undefined) ?? "list"
+        return ["migrations", action, "--database-url", dbUrl]
+      }
+      return [endpoint.replace(/^\//, ""), "--input", reqFile]
+  }
+}

package/src/engine-push-output.ts

@@ -0,0 +1,71 @@
+/**
+ * Parse and format schema-engine push output (compose subprocess or HTTP).
+ */
+
+export interface EnginePushResult {
+  status?: string
+  operations?: number
+  admin_refreshed?: boolean
+  message?: string
+}
+
+/** Extract the engine JSON object from mixed docker compose stdout/stderr. */
+export function parseEnginePushOutput(output: string): EnginePushResult | null {
+  const trimmed = output.trim()
+  if (!trimmed) return null
+
+  for (const line of trimmed.split(/\r?\n/)) {
+    const candidate = line.trim()
+    if (!candidate.startsWith("{") || !candidate.endsWith("}")) continue
+    try {
+      return JSON.parse(candidate) as EnginePushResult
+    } catch {
+      /* try next line */
+    }
+  }
+
+  if (trimmed.startsWith("{")) {
+    try {
+      return JSON.parse(trimmed) as EnginePushResult
+    } catch {
+      return null
+    }
+  }
+
+  return null
+}
+
+/** Human-readable one-liner for successful push (matches `supatype push` tone). */
+export function formatEnginePushMessage(result: EnginePushResult): string {
+  if (result.status === "up_to_date") {
+    if (result.admin_refreshed) {
+      return "Schema up to date — Studio metadata synced."
+    }
+    return "Schema up to date."
+  }
+
+  const ops = result.operations
+  if (typeof ops === "number" && ops > 0) {
+    return `Applied ${ops} operation(s).`
+  }
+
+  return result.message?.trim() || "Schema applied."
+}
+
+const COMPOSE_PROGRESS_LINE =
+  /^Container\s+.+\s+(Running|Waiting|Healthy|Created|Starting|Started|Exited|Stopped)\s*$/i
+
+/** Drop docker compose progress noise; keep engine JSON and real errors. */
+export function filterComposeNoise(output: string): string {
+  return output
+    .split(/\r?\n/)
+    .map((line) => line.trimEnd())
+    .filter((line) => {
+      const t = line.trim()
+      if (!t) return false
+      if (COMPOSE_PROGRESS_LINE.test(t)) return false
+      return true
+    })
+    .join("\n")
+    .trim()
+}

package/src/ensure-binary.ts

@@ -0,0 +1,28 @@
+/**
+ * Resolve component binaries, downloading from the CDN when not cached.
+ */
+
+import {
+  resolveBinary,
+  download,
+  currentPlatform,
+  resolveVersionFor,
+  type Component,
+} from "./binary-cache.js"
+import type { SupatypeProjectConfig } from "./project-config.js"
+
+export async function ensureBinary(
+  component: Component,
+  config: SupatypeProjectConfig,
+): Promise<string> {
+  try {
+    return await resolveBinary(component, config)
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err)
+    if (!message.includes("not found in cache")) {
+      throw err
+    }
+  }
+
+  return download(component, await resolveVersionFor(component, config), currentPlatform())
+}