@supatype/cli 0.1.0-alpha.9 → 0.1.0

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()
+}

package/src/docker-runtime.ts

@@ -0,0 +1,151 @@
+/**
+ * Docker daemon availability — used before `docker compose` and other docker CLI calls.
+ */
+
+import { spawnSync } from "node:child_process"
+import { platform } from "node:os"
+import { endDevSession, getActiveDevSession } from "./dev-session.js"
+import { isInteractive } from "./ui/interactive.js"
+import { error, plain } from "./ui/messages.js"
+import { clack as p, printLogo } from "./ui/prompts.js"
+
+export type DockerDaemonProbe =
+  | { ok: true }
+  | { ok: false; reason: "cli_missing" | "daemon_unavailable"; detail?: string }
+
+export type DockerBrandOptions = {
+  intro: string
+}
+
+export type DockerReportOptions = {
+  /** Logo + Clack intro before the error (e.g. `supatype dev` entry). */
+  brand?: DockerBrandOptions
+}
+
+function dockerSpawn(args: string[]) {
+  return spawnSync("docker", args, {
+    encoding: "utf8",
+    stdio: "pipe",
+    shell: process.platform === "win32",
+  })
+}
+
+/** Returns whether the Docker CLI is on PATH and the daemon accepts connections. */
+export function probeDockerDaemon(): DockerDaemonProbe {
+  const version = dockerSpawn(["version", "--format", "{{.Client.Version}}"])
+  if (version.error && "code" in version.error && version.error.code === "ENOENT") {
+    return { ok: false, reason: "cli_missing" }
+  }
+
+  const clientVersion = (version.stdout ?? "").trim()
+  const versionStderr = (version.stderr ?? "").trim()
+  const versionDetail = `${versionStderr}${version.stdout ?? ""}`.trim()
+
+  // No client version — CLI missing or broken.
+  if (!clientVersion) {
+    return {
+      ok: false,
+      reason: "cli_missing",
+      ...(versionDetail ? { detail: versionDetail } : {}),
+    }
+  }
+
+  // Client is present but daemon refused (paused/stopped). `docker info` can hang
+  // while paused on Docker Desktop — use the version stderr and skip info.
+  if (version.status !== 0 && versionStderr) {
+    return { ok: false, reason: "daemon_unavailable", detail: versionStderr }
+  }
+
+  const info = dockerSpawn(["info"])
+  if (info.status === 0) return { ok: true }
+
+  const infoDetail = `${info.stderr ?? ""}${info.stdout ?? ""}`.trim()
+  const detail = infoDetail || versionDetail
+  return { ok: false, reason: "daemon_unavailable", ...(detail ? { detail } : {}) }
+}
+
+function shouldShowDockerDetail(probe: Extract<DockerDaemonProbe, { ok: false }>): boolean {
+  if (!probe.detail) return false
+  const lower = probe.detail.toLowerCase()
+  if (probe.reason !== "daemon_unavailable") return true
+  // Skip raw daemon stderr when we already print a clearer hint.
+  return !lower.includes("paused") && !lower.includes("cannot connect")
+}
+
+function dockerUnavailableHeadline(probe: Extract<DockerDaemonProbe, { ok: false }>): string {
+  if (probe.reason === "cli_missing") {
+    return "Docker is not installed or not on your PATH."
+  }
+  return "Docker is installed but the daemon is not running."
+}
+
+function dockerUnavailableHints(probe: Extract<DockerDaemonProbe, { ok: false }>): string[] {
+  const hints: string[] = []
+
+  if (probe.reason === "cli_missing") {
+    hints.push(
+      "Install Docker Desktop (https://www.docker.com/products/docker-desktop/) or add the docker CLI to PATH.",
+    )
+  } else if (probe.detail?.toLowerCase().includes("paused")) {
+    hints.push("Unpause Docker Desktop from the whale menu or Dashboard, then try again.")
+  } else if (platform() === "win32" || platform() === "darwin") {
+    hints.push("Start Docker Desktop, then try again.")
+  } else {
+    hints.push("Start the Docker daemon (e.g. sudo systemctl start docker), then try again.")
+  }
+
+  hints.push('To develop without Docker, set provider: "native" in supatype.config.ts.')
+
+  if (shouldShowDockerDetail(probe)) {
+    const firstLine = probe.detail!.split(/\r?\n/).find((line) => line.trim().length > 0)
+    if (firstLine) hints.push(`docker: ${firstLine.trim()}`)
+  }
+
+  return hints
+}
+
+/** @deprecated Tests only — use `reportDockerUnavailable`. */
+export function formatDockerUnavailableMessage(
+  probe: Extract<DockerDaemonProbe, { ok: false }>,
+): string {
+  const lines: string[] = [dockerUnavailableHeadline(probe), ...dockerUnavailableHints(probe)]
+  return lines.join("\n")
+}
+
+/** Print Docker-unavailable guidance via the shared CLI message layer. */
+export function reportDockerUnavailable(
+  probe: Extract<DockerDaemonProbe, { ok: false }>,
+  opts?: DockerReportOptions,
+): void {
+  if (opts?.brand && isInteractive()) {
+    printLogo()
+    p.intro(opts.brand.intro)
+  }
+
+  const headline = dockerUnavailableHeadline(probe)
+  const hints = dockerUnavailableHints(probe)
+
+  error(headline)
+
+  if (isInteractive()) {
+    p.note(hints.join("\n\n"))
+    return
+  }
+
+  for (const hint of hints) {
+    plain()
+    plain(`  ${hint}`)
+  }
+}
+
+/** Exit 1 with a friendly message when Docker is not usable. */
+export function requireDockerDaemon(opts?: DockerReportOptions): void {
+  const probe = probeDockerDaemon()
+  if (probe.ok) return
+  // Dev TUI patches console — restore stderr before printing a fatal message.
+  if (getActiveDevSession()) {
+    endDevSession()
+  }
+  reportDockerUnavailable(probe, opts)
+  process.exit(1)
+}

package/src/engine-client.ts

@@ -13,21 +13,25 @@ import { mkdirSync, writeFileSync, unlinkSync, existsSync, readdirSync } from "n
 import { tmpdir, homedir } from "node:os"
 import { join } from "node:path"
 import { loadConfig } from "./config.js"
-import { resolveBinary, currentPlatform, cachePath } from "./binary-cache.js"
+import { currentPlatform, cachePath } from "./binary-cache.js"
+import { ensureBinary } from "./ensure-binary.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
+  kind?: string
   description?: string
   risk?: "safe" | "warn" | "danger" | "cautious" | "destructive"
   warning?: string
   sql?: string
+  table?: string
+  column?: string
+  constraint?: string
+  index_name?: string
+  index?: { fields?: string[]; name?: string; unique?: boolean }
 }
 
 export interface DiffResult {
@@ -83,10 +87,16 @@ async function getEngineBin(): Promise<string> {
 
   try {
     const config = loadConfig(cwd)
-    _engineBin = await resolveBinary("engine", config)
+    // Download-on-miss (with retry) so a fresh machine or a failed postinstall
+    // self-heals on first use instead of silently skipping type/admin refresh.
+    _engineBin = await ensureBinary("engine", config)
     return _engineBin
-  } catch {
-    // No valid project config — fall through to default cache path.
+  } catch (err) {
+    // A real download/verification failure must surface, not fall back to a
+    // possibly-stale cached binary from a different version.
+    const message = err instanceof Error ? err.message : String(err)
+    if (message.includes("Failed to download")) throw err
+    // Otherwise (no valid project config) fall through to default cache scan.
   }
 
   // No config found — scan the cache for any available engine binary.
@@ -146,24 +156,40 @@ export async function engineRequest<T = 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 cleanup: string[] = []
   const reqFile = join(tmpDir, `req-${Date.now()}.json`)
   const inputPayload = body["ast"] !== undefined ? body["ast"] : body
   writeFileSync(reqFile, JSON.stringify(inputPayload))
+  cleanup.push(reqFile)
+
+  let gzPath: string | undefined
+  let manifestPath: string | undefined
+  if (typeof body["schema_sources_gz_base64"] === "string") {
+    gzPath = join(tmpDir, `sources-${Date.now()}.gz`)
+    writeFileSync(gzPath, Buffer.from(body["schema_sources_gz_base64"], "base64"))
+    cleanup.push(gzPath)
+  }
+  if (body["schema_sources_manifest"] !== undefined) {
+    manifestPath = join(tmpDir, `manifest-${Date.now()}.json`)
+    writeFileSync(manifestPath, JSON.stringify(body["schema_sources_manifest"]))
+    cleanup.push(manifestPath)
+  }
 
-  const args = endpointToArgs(endpoint, body, reqFile)
+  const args = endpointToArgs(endpoint, body, reqFile, {
+    ...(gzPath !== undefined ? { gzPath } : {}),
+    ...(manifestPath !== undefined ? { manifestPath } : {}),
+  })
 
   const result = spawnSync(bin, args, {
     encoding: "utf8",
     cwd: process.cwd(),
   })
 
-  // Clean up temp file.
-  try { unlinkSync(reqFile) } catch { /* ignore */ }
+  for (const f of cleanup) {
+    try { unlinkSync(f) } catch { /* ignore */ }
+  }
 
   if (result.status !== 0) {
     const stderr = result.stderr?.trim() || "(no output)"
@@ -195,6 +221,7 @@ function endpointToArgs(
   endpoint: string,
   body: Record<string, unknown>,
   reqFile: string,
+  sources?: { gzPath?: string; manifestPath?: string },
 ): string[] {
   const dbUrl = (body["database_url"] as string | undefined) ?? ""
   const schema = (body["schema"] as string | undefined) ?? "public"
@@ -206,8 +233,26 @@ function endpointToArgs(
     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 "/push": {
+      const sourceArgs: string[] = []
+      if (sources?.gzPath) sourceArgs.push("--schema-sources-gz", sources.gzPath)
+      if (sources?.manifestPath) sourceArgs.push("--schema-sources-manifest", sources.manifestPath)
+      return [
+        "push",
+        "--input",
+        reqFile,
+        "--database-url",
+        dbUrl,
+        "--schema",
+        schema,
+        ...force,
+        ...nonInteractive,
+        ...sourceArgs,
+      ]
+    }
+
+    case "/rollback":
+      return ["rollback", "--database-url", dbUrl, "--schema", schema]
 
     case "/parse":
       return ["parse", "--input", reqFile]
@@ -220,6 +265,18 @@ function endpointToArgs(
     case "/introspect":
       return ["introspect", "--database-url", dbUrl, "--schema", schema]
 
+    case "/doctor": {
+      const strict = body["strict"] ? ["--strict"] : []
+      const noCache = body["no_cache"] ? ["--no-cache"] : []
+      return ["doctor", "--input", reqFile, "--database-url", dbUrl, "--schema", schema, ...strict, ...noCache]
+    }
+
+    case "/adopt": {
+      const yes = body["yes"] ? ["--yes"] : []
+      const noCache = body["no_cache"] ? ["--no-cache"] : []
+      return ["adopt", "--input", reqFile, "--database-url", dbUrl, "--schema", schema, ...yes, ...noCache]
+    }
+
     case "/validate":
       return ["validate", "--input", reqFile]
 
@@ -227,9 +284,16 @@ function endpointToArgs(
       return ["admin", "--input", reqFile]
 
     default:
-      if (endpoint.startsWith("/migrations")) {
+      if (endpoint === "/migrations" || endpoint.startsWith("/migrations")) {
         const action = (body["action"] as string | undefined) ?? "list"
-        return ["migrations", action, "--database-url", dbUrl]
+        if (action === "rollback") {
+          return ["rollback", "--database-url", dbUrl, "--schema", schema]
+        }
+        const name = body["name"] as string | undefined
+        if (name) {
+          return ["migrations", "--database-url", dbUrl, "--name", name]
+        }
+        return ["migrations", "--database-url", dbUrl]
       }
       return [endpoint.replace(/^\//, ""), "--input", reqFile]
   }

package/src/engine-push-output.ts

@@ -0,0 +1,75 @@
+/**
+ * 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 parseEngineJsonOutput<T>(output: string): T | 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 T
+    } catch {
+      /* try next line */
+    }
+  }
+
+  if (trimmed.startsWith("{")) {
+    try {
+      return JSON.parse(trimmed) as T
+    } catch {
+      return null
+    }
+  }
+
+  return null
+}
+
+export function parseEnginePushOutput(output: string): EnginePushResult | null {
+  return parseEngineJsonOutput<EnginePushResult>(output)
+}
+
+/** 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

@@ -6,7 +6,7 @@ import {
   resolveBinary,
   download,
   currentPlatform,
-  versionFor,
+  resolveVersionFor,
   type Component,
 } from "./binary-cache.js"
 import type { SupatypeProjectConfig } from "./project-config.js"
@@ -24,5 +24,5 @@ export async function ensureBinary(
     }
   }
 
-  return download(component, versionFor(component, config), currentPlatform())
+  return download(component, await resolveVersionFor(component, config), currentPlatform())
 }

package/src/gitignore.ts

@@ -0,0 +1,48 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs"
+import { resolve } from "node:path"
+
+export const SUPATYPE_GITIGNORE_MARKER = "# Supatype — local runtime (contains secrets in link.json)"
+export const SUPATYPE_GITIGNORE_BLOCK = `${SUPATYPE_GITIGNORE_MARKER}
+.env
+.supatype/
+supatype.local.config.ts
+supatype.local.config.js
+supatype.local.config.mjs
+`
+
+export function isSupatypeGitignored(cwd: string): boolean {
+  const gitignorePath = resolve(cwd, ".gitignore")
+  if (!existsSync(gitignorePath)) return false
+  const content = readFileSync(gitignorePath, "utf8")
+  return /\.supatype\/?(\/|\s|$)/m.test(content) || content.includes(".supatype/")
+}
+
+export function ensureSupatypeGitignore(cwd: string, opts?: { silent?: boolean }): boolean {
+  const gitignorePath = resolve(cwd, ".gitignore")
+  if (isSupatypeGitignored(cwd)) return true
+
+  if (existsSync(gitignorePath)) {
+    const content = readFileSync(gitignorePath, "utf8")
+    const next = content.endsWith("\n") ? content : `${content}\n`
+    writeFileSync(gitignorePath, `${next}\n${SUPATYPE_GITIGNORE_BLOCK}`, "utf8")
+  } else {
+    writeFileSync(
+      gitignorePath,
+      `.env\nnode_modules/\ndist/\n${SUPATYPE_GITIGNORE_BLOCK}`,
+      "utf8",
+    )
+  }
+
+  if (!opts?.silent) {
+    console.warn("Added .supatype/ to .gitignore (link.json contains secrets — never commit).")
+  }
+  return true
+}
+
+export function warnIfLinkNotGitignored(cwd: string): void {
+  if (isSupatypeGitignored(cwd)) return
+  console.warn(
+    "\n⚠  Warning: .supatype/ is not in .gitignore — link.json contains tokens and must not be committed.",
+  )
+  console.warn("   Run with link --fix-gitignore to append the Supatype block.\n")
+}

package/src/kong-config.ts

@@ -18,6 +18,11 @@ export interface KongDeclarativeOptions {
   studioServiceUrl?: string | undefined
   /** See {@link RuntimeRouteOptions.studioStripPath}. */
   studioStripPath?: boolean | undefined
+  /**
+   * When set, append a global Kong `acme` plugin (Let's Encrypt) with Redis/Valkey
+   * storage so the self-host gateway provisions and renews TLS automatically.
+   */
+  acme?: { email: string; domain: string; redisHost: string } | undefined
 }
 
 /** Escape a string for use inside YAML double quotes. */
@@ -85,9 +90,27 @@ ${route.paths.map((path) => `          - ${path}`).join("\n")}
 ${protocols}${routePlugins}${graphqlPlugins}`
   }).join("\n")
 
+  const acme = opts.acme
+  const pluginsBlock = acme
+    ? `
+plugins:
+  - name: acme
+    config:
+      account_email: ${yamlQuotedString(acme.email)}
+      tos_accepted: true
+      domains:
+        - ${yamlQuotedString(acme.domain)}
+      storage: redis
+      storage_config:
+        redis:
+          host: ${yamlQuotedString(acme.redisHost)}
+          port: 6379
+`
+    : ""
+
   return `_format_version: "3.0"
 ${consumersBlock}
 services:
 ${servicesBlock}
-`
+${pluginsBlock}`
 }