@supatype/cli 0.1.0-alpha.10 → 0.1.0-alpha.11

package/src/commands/status.ts

@@ -1,9 +1,13 @@
 /**
- * supatype status — show current state of local dev services.
+ * supatype status — show linked target or local dev stack state.
  */
 import type { Command } from "commander"
 import { spawnSync } from "node:child_process"
+import { existsSync } from "node:fs"
+import { resolve } from "node:path"
 import { LOCAL_KONG_HOST_PORT, localKongBaseUrl } from "../local-gateway.js"
+import { loadLocalEnvironment, loadProjectLink } from "../link.js"
+import { resolveTarget, targetStatus } from "../resolve-target.js"
 
 interface ServiceStatus {
   name: string
@@ -16,42 +20,105 @@ interface ServiceStatus {
 export function registerStatus(program: Command): void {
   program
     .command("status")
-    .description("Show current state of local dev services")
-    .action(() => {
-      const services: ServiceStatus[] = [
-        { name: "Postgres", container: "supatype-postgres", port: 5432 },
-        { name: "PostgREST", container: "supatype-postgrest", port: 3000 },
-        { name: "GoTrue", container: "supatype-gotrue", port: 9999 },
-        { name: "Kong", container: "supatype-kong", port: LOCAL_KONG_HOST_PORT },
-        { name: "MinIO", container: "supatype-minio", port: 9000 },
-        { name: "Realtime", container: "supatype-realtime", port: 4000 },
-        { name: "Studio", container: "supatype-studio", port: 3100 },
-      ].map((svc) => {
-        const status = getContainerStatus(svc.container)
-        const uptime = getContainerUptime(svc.container)
-        return { ...svc, status, ...(uptime !== undefined && { uptime }) }
-      })
-
-      console.log("Supatype Local Development Stack\n")
-
-      const maxName = Math.max(...services.map((s) => s.name.length))
-      for (const svc of services) {
-        const icon = svc.status === "running" ? "●" : svc.status === "stopped" ? "○" : "✕"
-        const status = svc.status.padEnd(8)
-        const port = svc.port ? `:${svc.port}` : ""
-        const uptime = svc.uptime ? ` (${svc.uptime})` : ""
-        console.log(`  ${icon} ${svc.name.padEnd(maxName)}  ${status}  ${port}${uptime}`)
+    .description("Show linked target status or local dev services")
+    .option("--env <name>", "Target environment when linked")
+    .action(async (opts: { env?: string }) => {
+      const cwd = process.cwd()
+      const link = loadProjectLink(cwd)
+      const localEnv = loadLocalEnvironment(cwd)
+
+      if (link || localEnv) {
+        try {
+          const target = resolveTarget(cwd, { env: opts.env })
+          if (target.mode !== "direct") {
+            await printLinkedStatus(target)
+            return
+          }
+        } catch (err) {
+          console.error((err as Error).message)
+          process.exitCode = 1
+          return
+        }
       }
 
-      const running = services.filter((s) => s.status === "running")
-      console.log(`\n${running.length}/${services.length} services running`)
+      printLocalStackStatus(cwd)
+    })
+}
+
+async function printLinkedStatus(target: ReturnType<typeof resolveTarget>): Promise<void> {
+  console.log(`Target: ${target.mode} (${target.environment})`)
+  console.log(`Project: ${target.projectRef}`)
+  console.log(`API: ${target.apiBaseUrl}${target.apiPrefix}\n`)
 
-      if (running.length > 0) {
-        console.log(`\nAPI URL:    ${localKongBaseUrl()}`)
-        console.log(`Studio:     http://localhost:3100`)
-        console.log(`Database:   postgresql://supatype_admin:postgres@localhost:5432/postgres`)
+  try {
+    const data = (await targetStatus(target)) as Record<string, unknown>
+    if (data.functions && Array.isArray(data.functions)) {
+      console.log(`Functions (${data.functions.length}):`)
+      for (const fn of data.functions as Array<{ name?: string } | string>) {
+        const name = typeof fn === "string" ? fn : fn.name
+        if (name) console.log(`  • ${name}`)
       }
-    })
+      console.log()
+    }
+    if (data.deploymentId) {
+      console.log(`Active deployment: ${data.deploymentId}`)
+    }
+    if (data.controlPlane) {
+      console.log(`Control plane: ${data.controlPlane}`)
+    }
+  } catch (err) {
+    console.warn(`Could not fetch remote status: ${(err as Error).message}`)
+  }
+}
+
+function printLocalStackStatus(cwd: string): void {
+  const localEnv = loadLocalEnvironment(cwd)
+  const kongPort = localEnv?.kongPort ?? LOCAL_KONG_HOST_PORT
+
+  const services: ServiceStatus[] = [
+    { name: "Postgres", container: "supatype-postgres", port: 5432 },
+    { name: "PostgREST", container: "supatype-postgrest", port: 3000 },
+    { name: "GoTrue", container: "supatype-gotrue", port: 9999 },
+    { name: "Kong", container: "supatype-kong", port: kongPort },
+    { name: "Control plane", container: "supatype-control-plane" },
+    { name: "MinIO", container: "supatype-minio", port: 9000 },
+    { name: "Realtime", container: "supatype-realtime", port: 4000 },
+    { name: "Studio", container: "supatype-studio", port: 3100 },
+  ].map((svc) => {
+    const status = getContainerStatus(svc.container)
+    const uptime = getContainerUptime(svc.container)
+    return { ...svc, status, ...(uptime !== undefined && { uptime }) }
+  })
+
+  console.log("Supatype Local Development Stack\n")
+
+  const maxName = Math.max(...services.map((s) => s.name.length))
+  for (const svc of services) {
+    const icon = svc.status === "running" ? "●" : svc.status === "stopped" ? "○" : "✕"
+    const status = svc.status.padEnd(8)
+    const port = svc.port ? `:${svc.port}` : ""
+    const uptime = svc.uptime ? ` (${svc.uptime})` : ""
+    console.log(`  ${icon} ${svc.name.padEnd(maxName)}  ${status}  ${port}${uptime}`)
+  }
+
+  const running = services.filter((s) => s.status === "running")
+  console.log(`\n${running.length}/${services.length} services running`)
+
+  if (running.length > 0) {
+    const apiUrl = localEnv?.apiUrl ?? localKongBaseUrl()
+    console.log(`\nAPI URL:    ${apiUrl}`)
+    console.log(`Studio:     http://localhost:3100`)
+    if (localEnv?.databaseUrl) {
+      console.log(`Database:   ${localEnv.databaseUrl}`)
+    } else {
+      console.log(`Database:   postgresql://supatype_admin:postgres@localhost:5432/postgres`)
+    }
+  }
+
+  if (existsSync(resolve(cwd, ".supatype/environment.json"))) {
+    console.log("\nLocal environment file: .supatype/environment.json")
+    console.log("Link remote ops: supatype link --url <api> --token $SERVICE_ROLE_KEY")
+  }
 }
 
 function getContainerStatus(name: string): "running" | "stopped" | "error" {

package/src/commands/update.ts

@@ -8,7 +8,7 @@ import { existsSync, readFileSync, writeFileSync } from "node:fs"
 import { basename, resolve } from "node:path"
 import { loadConfig } from "../config.js"
 import { resolveRuntimeProvider } from "../project-config.js"
-import { runDockerCompose, writeSelfHostCompose } from "../self-host-compose.js"
+import { runDockerCompose, writeSelfHostCompose, composePullNeedsIgnoreFailures } from "../self-host-compose.js"
 import { syncComposeImagePins } from "../dev-compose.js"
 import { download, currentPlatform, fetchAllLatestVersions, pinnedVersion, type Component } from "../binary-cache.js"
 
@@ -42,7 +42,11 @@ export function registerUpdate(program: Command): void {
         const paths = writeSelfHostCompose(cwd, config, { devLocal: true })
         syncComposeImagePins(cwd, config)
         console.log("Pulling self-host compose images...")
-        const status = runDockerCompose(paths.composePath, ["pull"], cwd)
+        const pullArgs = ["pull"]
+        if (composePullNeedsIgnoreFailures(config, cwd)) {
+          pullArgs.push("--ignore-pull-failures")
+        }
+        const status = runDockerCompose(paths.composePath, pullArgs, cwd)
         if (status !== 0) process.exit(status)
         console.log("Compose images updated.")
         return

package/src/config.ts

@@ -9,6 +9,7 @@ import {
   type SupatypeProjectConfig,
 } from "./project-config.js"
 import { extractSchemaAstFromTypes } from "./type-extractor.js"
+import type { ExtractedSchemaAstV2 } from "./schema-ast-v2.js"
 
 export type { SupatypeProjectConfig } from "./project-config.js"
 
@@ -206,7 +207,7 @@ process.stdout.write(JSON.stringify(config))
 export function loadSchemaAst(
   schemaPath: string,
   cwd: string = process.cwd(),
-): unknown {
+): ExtractedSchemaAstV2 {
   const extracted = extractSchemaAstFromTypes(schemaPath, cwd)
   if (extracted !== null) return extracted
 

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,
@@ -28,16 +29,21 @@ import {
 } from "./self-host-compose.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"
 
@@ -94,6 +100,72 @@ 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,
+): 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 })
+  if (up !== 0) process.exit(up)
+  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)) {
@@ -151,6 +223,8 @@ function ensureDevComposeEnv(
   }
   if (devDbPort !== undefined) {
     updates.SUPATYPE_DEV_DB_PORT = String(devDbPort)
+    updates.DATABASE_URL =
+      `postgresql://supatype_admin:postgres@localhost:${devDbPort}/supatype?sslmode=disable`
   }
   const removeImageKeys = COMPOSE_PINNED_IMAGE_ENV_KEYS.filter((key) => !(key in imagePins))
   upsertEnvFile(cwd, updates, removeImageKeys)
@@ -189,6 +263,14 @@ 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
@@ -279,12 +361,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
@@ -300,11 +389,12 @@ async function runComposeSchemaPush(
   }
 
   console.log("[supatype] Applying schema via compose schema-engine...")
-  let push = await runComposeEnginePush(paths, cwd, composeProject, config)
+  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)
+    push = await runComposeEnginePush(paths, cwd, composeProject, config, sources)
   }
   if (push.status !== 0) {
     _lastFailedAst = astJson
@@ -347,6 +437,7 @@ async function runComposeEnginePush(
   cwd: string,
   composeProject: string,
   config: SupatypeProjectConfig,
+  sources?: SchemaSourcePushArtifacts | null,
 ): Promise<{ status: number; output: string }> {
   const envFile = resolve(cwd, ".env")
   const composeArgs = ["compose", "--progress", "quiet"]
@@ -370,6 +461,14 @@ async 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",
@@ -399,6 +498,117 @@ async function runComposeEnginePush(
   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)) {
+    await ensureDockerDbPublishedForHostEngine(cwd, config)
+    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 up = runDockerCompose(paths.composePath, ["up", "-d", "db"], cwd, project, { quiet: true })
+  if (up !== 0) process.exit(up)
+  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
+}
+
 /**
  * `supatype push` when `provider: docker`. Uses in-compose schema-engine unless
  * `overrides.engine` is set — then Postgres is published to the host and push runs
@@ -426,7 +636,14 @@ export async function pushSchemaDocker(cwd: string, config: SupatypeProjectConfi
   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 })
+  if (upGateway !== 0) process.exit(upGateway)
+  await waitKongReady(kongPort, 120)
+  await provisionDockerStorageBuckets(ast, kongPort, serviceRoleKey)
+
   console.log("[supatype] Schema pushed.")
 }
 
@@ -468,6 +685,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 })
 
@@ -538,9 +767,14 @@ export async function runDevCompose(cwd: string, config: SupatypeProjectConfig,
       debounceTimer = setTimeout(() => {
         debounceTimer = null
         console.log(`\n[supatype] Change detected in ${filename}, pushing schema...`)
-        runComposeSchemaPushQueued(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)
     })
   }

package/src/diff-output.ts

@@ -1,4 +1,44 @@
-import type { DiffResult } from "./engine-client.js"
+import type { DiffResult, Operation } from "./engine-client.js"
+
+/** Human-readable label for a single schema operation. */
+export function formatOperation(op: Operation): string {
+  if (typeof op.description === "string" && op.description.trim().length > 0) {
+    return op.description
+  }
+
+  const kind = typeof op.type === "string" ? op.type : typeof op.kind === "string" ? op.kind : "operation"
+  const raw = op as unknown as Record<string, unknown>
+  const table = raw["table"]
+  const column = raw["column"]
+  const index = raw["index"]
+  const sql = typeof op.sql === "string" ? op.sql.trim() : ""
+
+  if (kind === "add_unique_constraint" || kind === "drop_unique_constraint") {
+    const constraint = typeof raw["constraint"] === "string" ? raw["constraint"] : null
+    if (typeof table === "string" && constraint) return `${kind} ${table}.${constraint}`
+  }
+
+  if (kind === "create_index" || kind === "drop_index" || kind === "add_index") {
+    const indexName = typeof index === "string" ? index : typeof raw["name"] === "string" ? raw["name"] : null
+    const fields = Array.isArray(raw["fields"]) ? raw["fields"].join(", ") : null
+    if (indexName && fields) return `${kind} ${table}.${indexName} (${fields})`
+    if (indexName) return `${kind} ${table}.${indexName}`
+  }
+
+  if (typeof table === "string" && typeof column === "string") {
+    return `${kind} ${table}.${column}`
+  }
+  if (typeof table === "string") {
+    return `${kind} ${table}`
+  }
+
+  if (sql) {
+    const oneLine = sql.replace(/\s+/g, " ").slice(0, 120)
+    return `${kind}: ${oneLine}${sql.length > 120 ? "…" : ""}`
+  }
+
+  return kind
+}
 
 /** Print engine diff warnings before the operation list. */
 export function printDiffWarnings(diff: DiffResult): void {
@@ -10,3 +50,41 @@ export function printDiffWarnings(diff: DiffResult): void {
   }
   console.log()
 }
+
+const RISK_SYMBOL: Record<NonNullable<DiffResult["operations"][number]["risk"]>, string> = {
+  safe: "+",
+  warn: "~",
+  cautious: "~",
+  danger: "!",
+  destructive: "!",
+}
+
+const RISK_LEGEND: Record<NonNullable<DiffResult["operations"][number]["risk"]>, string> = {
+  safe: "safe",
+  warn: "caution",
+  cautious: "caution",
+  danger: "DANGER",
+  destructive: "DANGER",
+}
+
+/** Print planned schema operations from a diff result. */
+export function printDiffOperations(diff: DiffResult): void {
+  const ops = diff.operations ?? []
+  if (ops.length === 0) {
+    console.log("No changes.")
+    return
+  }
+
+  console.log(`\n${ops.length} change(s):\n`)
+  for (const op of ops) {
+    const r = op.risk ?? "safe"
+    const label = op.warning ?? formatOperation(op)
+    console.log(`  [${RISK_SYMBOL[r]}] ${label}  (${RISK_LEGEND[r]})`)
+  }
+
+  const dangerous = ops.filter((o) => o.risk === "danger").length
+  if (dangerous > 0) {
+    console.log(`\n  ${dangerous} dangerous operation(s). Review before pushing.`)
+  }
+  console.log()
+}