@supatype/cli 0.1.0-alpha.9 → 0.1.1

package/src/dev-shutdown.ts

@@ -0,0 +1,147 @@
+/**
+ * Graceful shutdown for `supatype dev` — SIGINT, TUI Ctrl+C, terminal close,
+ * and a synchronous compose-down fallback on process exit.
+ */
+
+import { existsSync } from "node:fs"
+import { endDevSession } from "./dev-session.js"
+import { clearDevSessionLock } from "./dev-session-lock.js"
+import { runDockerCompose } from "./self-host-compose.js"
+
+export interface DevComposeShutdownFallback {
+  cwd: string
+  composePath: string
+  composeProject: string
+}
+
+let shutdownWork: (() => Promise<void>) | null = null
+let composeFallback: DevComposeShutdownFallback | null = null
+let shutdownCwd: string | null = null
+let shuttingDown = false
+let shutdownCompleted = false
+let forceQuitRequested = false
+let hooksRegistered = false
+
+function onSignal(): void {
+  void runDevShutdown()
+}
+
+function onStdinClose(): void {
+  if (!process.stdin.isTTY) return
+  void runDevShutdown()
+}
+
+function syncComposeDownFallback(): void {
+  if (shutdownCompleted || !composeFallback) return
+  try {
+    runDockerCompose(
+      composeFallback.composePath,
+      ["down"],
+      composeFallback.cwd,
+      composeFallback.composeProject,
+      { quiet: true },
+    )
+  } catch {
+    // best-effort — process is exiting
+  }
+  if (shutdownCwd) clearDevSessionLock(shutdownCwd)
+}
+
+function onProcessExit(): void {
+  syncComposeDownFallback()
+}
+
+export interface RegisterDevShutdownOptions {
+  /** Sync `docker compose down` when async teardown cannot finish (terminal close, kill). */
+  compose?: DevComposeShutdownFallback
+  /** Project root — clears `.supatype/dev-session.json` after shutdown. */
+  cwd?: string
+}
+
+/** Register async teardown (stop children, compose down, etc.). Call once per dev session. */
+export function registerDevShutdown(
+  work: () => Promise<void>,
+  opts?: RegisterDevShutdownOptions,
+): void {
+  shutdownWork = work
+  composeFallback = opts?.compose ?? null
+  shutdownCwd = opts?.cwd ?? opts?.compose?.cwd ?? null
+
+  if (hooksRegistered) return
+  hooksRegistered = true
+
+  process.on("SIGINT", onSignal)
+  process.on("SIGTERM", onSignal)
+  if (process.platform === "win32") {
+    process.on("SIGBREAK", onSignal)
+  }
+  process.on("exit", onProcessExit)
+
+  if (process.stdin.isTTY) {
+    process.stdin.on("end", onStdinClose)
+    process.stdin.on("close", onStdinClose)
+  }
+}
+
+/** TUI Ctrl+C — do not re-emit SIGINT (avoids double-fire on Windows raw mode). */
+export function requestDevShutdown(): void {
+  void runDevShutdown()
+}
+
+export function isDevShuttingDown(): boolean {
+  return shuttingDown
+}
+
+/** @internal Tests — reset module state between cases. */
+export function resetDevShutdownForTests(): void {
+  shutdownWork = null
+  composeFallback = null
+  shutdownCwd = null
+  shuttingDown = false
+  shutdownCompleted = false
+  forceQuitRequested = false
+  hooksRegistered = false
+}
+
+async function runDevShutdown(): Promise<void> {
+  if (shuttingDown) {
+    if (!forceQuitRequested) {
+      forceQuitRequested = true
+      process.stderr.write(
+        "\n[supatype] Still shutting down (stopping Docker)… press Ctrl+C again to force quit.\n",
+      )
+      return
+    }
+    try {
+      endDevSession()
+    } catch {
+      // best-effort terminal restore
+    }
+    process.stderr.write("\n[supatype] Forced quit — Docker containers may still be running.\n")
+    process.stdout.write("\n")
+    process.exit(130)
+  }
+  shuttingDown = true
+
+  try {
+    endDevSession()
+    process.stdout.write("\n")
+    await shutdownWork?.()
+    shutdownCompleted = true
+    if (shutdownCwd) clearDevSessionLock(shutdownCwd)
+    process.exit(0)
+  } catch (err) {
+    process.stderr.write(`[supatype] Shutdown failed: ${(err as Error).message}\n`)
+    process.stderr.write(
+      "[supatype] Docker containers may still be running — try: supatype self-host compose down\n",
+    )
+    syncComposeDownFallback()
+    shutdownCompleted = true
+    process.exit(1)
+  }
+}
+
+/** Whether a compose fallback was registered (tests). */
+export function hasComposeShutdownFallback(): boolean {
+  return composeFallback !== null && existsSync(composeFallback.composePath)
+}

package/src/dev-task-colors.ts

@@ -0,0 +1,47 @@
+/**
+ * ANSI colours for `supatype dev` TUI task list and log panes.
+ */
+
+import { BOLD, DIM, RESET } from "./ui/brand.js"
+
+export { RESET, DIM, BOLD }
+
+/** Purple for orchestrator logs, green for Vite/app, etc. */
+export function taskColor(taskId: string): string {
+  switch (taskId) {
+    case "stack":
+      return "\x1b[35m"
+    case "app":
+      return "\x1b[32m"
+    case "studio":
+      return "\x1b[96m"
+    case "server":
+      return "\x1b[32m"
+    case "postgrest":
+      return "\x1b[36m"
+    default:
+      return "\x1b[37m"
+  }
+}
+
+export function levelColor(line: string): string | null {
+  if (line.startsWith("✗ ")) return "\x1b[31m"
+  if (line.startsWith("⚠ ")) return "\x1b[33m"
+  return null
+}
+
+/** Drop redundant prefix — task pane is already labelled supatype. */
+export function normalizeStackLogLine(line: string): string {
+  return line.replace(/^\[supatype\]\s*/, "")
+}
+
+export function colorizeLogLine(taskId: string, line: string): string {
+  const level = levelColor(line)
+  const base = level ?? taskColor(taskId)
+  return `${base}${line}${RESET}`
+}
+
+export function colorizeTaskLabel(taskId: string, label: string, focused: boolean): string {
+  const style = focused ? BOLD + taskColor(taskId) : taskColor(taskId)
+  return `${style}${label}${RESET}`
+}

package/src/dev-tui.ts

@@ -0,0 +1,232 @@
+/**
+ * Interactive terminal UI for `supatype dev` — task list + focused log pane.
+ */
+
+import { stripAnsi } from "./dev-log-filter.js"
+import type { DevLogBus } from "./dev-log-bus.js"
+import {
+  colorizeLogLine,
+  colorizeTaskLabel,
+  DIM,
+  RESET,
+  taskColor,
+} from "./dev-task-colors.js"
+import {
+  colorLogoLines,
+  layoutLogoBlock,
+  logoRowCount,
+  pickLogoLines,
+} from "./dev-logo.js"
+import { requestDevShutdown } from "./dev-shutdown.js"
+
+const ENTER_ALT_SCREEN = "\x1b[?1049h"
+const LEAVE_ALT_SCREEN = "\x1b[?1049l"
+const HIDE_CURSOR = "\x1b[?25l"
+const SHOW_CURSOR = "\x1b[?25h"
+const CLEAR_SCREEN = "\x1b[2J\x1b[H"
+
+const TASK_COL_WIDTH = 22
+const MIN_WIDTH = 60
+const MIN_HEIGHT = 14
+
+export class DevTui {
+  private active = false
+  private scrollFromBottom = 0
+  private renderPending = false
+  private unsubscribeBus: (() => void) | null = null
+  private readonly onResize = (): void => this.scheduleRender()
+  private readonly onData = (chunk: Buffer): void => this.handleInput(chunk)
+
+  constructor(private readonly bus: DevLogBus) {}
+
+  start(): void {
+    if (this.active) return
+    this.active = true
+    this.scrollFromBottom = 0
+
+    if (process.stdin.isTTY) {
+      process.stdin.setRawMode(true)
+      process.stdin.resume()
+      process.stdin.on("data", this.onData)
+    }
+    process.stdout.on("resize", this.onResize)
+
+    process.stdout.write(ENTER_ALT_SCREEN + HIDE_CURSOR)
+    this.unsubscribeBus = this.bus.onUpdate(() => this.scheduleRender())
+    this.scheduleRender()
+  }
+
+  stop(): void {
+    if (!this.active) return
+    this.active = false
+
+    this.unsubscribeBus?.()
+    this.unsubscribeBus = null
+
+    process.stdout.off("resize", this.onResize)
+    if (process.stdin.isTTY) {
+      process.stdin.off("data", this.onData)
+      process.stdin.setRawMode(false)
+      process.stdin.pause()
+    }
+
+    process.stdout.write(SHOW_CURSOR + LEAVE_ALT_SCREEN)
+  }
+
+  private scheduleRender(): void {
+    if (!this.active || this.renderPending) return
+    this.renderPending = true
+    setImmediate(() => {
+      this.renderPending = false
+      if (this.active) this.render()
+    })
+  }
+
+  private handleInput(chunk: Buffer): void {
+    const key = chunk.toString()
+
+    if (key === "\x03") {
+      requestDevShutdown()
+      return
+    }
+
+    switch (key) {
+      case "j":
+      case "\x1b[B":
+        this.bus.focusNext()
+        this.scrollFromBottom = 0
+        break
+      case "k":
+      case "\x1b[A":
+        this.bus.focusPrevious()
+        this.scrollFromBottom = 0
+        break
+      case "u":
+        this.scrollFromBottom = Math.min(
+          this.scrollFromBottom + 3,
+          this.maxScroll(this.bus.getFocusedTaskId()),
+        )
+        break
+      case "d":
+        this.scrollFromBottom = Math.max(this.scrollFromBottom - 3, 0)
+        break
+      case "g":
+        this.scrollFromBottom = this.maxScroll(this.bus.getFocusedTaskId())
+        break
+      case "G":
+        this.scrollFromBottom = 0
+        break
+      default:
+        return
+    }
+    this.scheduleRender()
+  }
+
+  private maxScroll(taskId: string): number {
+    const task = this.bus.getTask(taskId)
+    if (!task) return 0
+    const logHeight = this.splitPaneHeight()
+    return Math.max(0, task.lines.length - logHeight)
+  }
+
+  private chromeRowCount(): number {
+    // logo + separator + keybind hint + footer
+    return logoRowCount() + 3
+  }
+
+  private splitPaneHeight(): number {
+    const rows = Math.max(MIN_HEIGHT, process.stdout.rows ?? 24)
+    return Math.max(4, rows - this.chromeRowCount())
+  }
+
+  private render(): void {
+    const cols = Math.max(MIN_WIDTH, process.stdout.columns ?? 80)
+    const logWidth = cols - TASK_COL_WIDTH - 1
+    const logHeight = this.splitPaneHeight()
+
+    const lines: string[] = []
+
+    const logoPlain = layoutLogoBlock(pickLogoLines())
+    for (const colored of colorLogoLines(logoPlain)) {
+      lines.push(formatLogoRow(colored, cols))
+    }
+
+    lines.push(`${DIM}${"─".repeat(cols)}${RESET}`)
+    lines.push(
+      `${DIM}${truncate(
+        " ↑/k ↓/j task  u/d scroll  g/G top/bottom  Ctrl+C quit",
+        cols,
+      )}${RESET}`,
+    )
+
+    const taskIds = this.bus.getTaskOrder()
+    const focusedId = this.bus.getFocusedTaskId()
+
+    for (let row = 0; row < logHeight; row++) {
+      let left = " ".repeat(TASK_COL_WIDTH)
+      const taskId = taskIds[row]
+      if (taskId) {
+        const task = this.bus.getTask(taskId)
+        if (task) {
+          const marker = taskId === focusedId ? "▶" : " "
+          const unread = task.unread ? " •" : "  "
+          const label = truncate(`${marker} ${task.title}${unread}`, TASK_COL_WIDTH - 1)
+          left = padVisible(
+            colorizeTaskLabel(taskId, label, taskId === focusedId),
+            TASK_COL_WIDTH,
+          )
+        }
+      }
+
+      const logLine = this.logLineAt(focusedId, row, logHeight, logWidth)
+      lines.push(left + `${DIM}│${RESET}` + logLine)
+    }
+
+    const focusedTitle = this.bus.getTask(focusedId)?.title ?? focusedId
+    lines.push(`${DIM} focused:${RESET} ${colorizeTaskLabel(focusedId, focusedTitle, true)}`)
+
+    process.stdout.write(CLEAR_SCREEN + lines.join("\n"))
+  }
+
+  private logLineAt(taskId: string, row: number, logHeight: number, width: number): string {
+    const task = this.bus.getTask(taskId)
+    if (!task || task.lines.length === 0) {
+      return " ".repeat(width)
+    }
+
+    const total = task.lines.length
+    const end = total - this.scrollFromBottom
+    const start = Math.max(0, end - logHeight)
+    const index = start + row
+    if (index >= end || index >= total) {
+      return " ".repeat(width)
+    }
+
+    const raw = stripAnsi(task.lines[index] ?? "")
+    const clipped = truncate(raw, width)
+    return padVisible(colorizeLogLine(taskId, clipped), width)
+  }
+}
+
+function truncate(text: string, width: number): string {
+  if (width <= 0) return ""
+  if (text.length <= width) return text
+  if (width <= 1) return text.slice(0, width)
+  return `${text.slice(0, width - 1)}…`
+}
+
+/** Pad to visible width (ignores ANSI sequences already stripped from input). */
+function padVisible(text: string, width: number): string {
+  const visible = stripAnsi(text)
+  if (visible.length >= width) return text
+  return text + " ".repeat(width - visible.length)
+}
+
+function formatLogoRow(colored: string, cols: number): string {
+  const plain = stripAnsi(colored)
+  if (plain.length <= cols) {
+    return plain.length < cols ? `${colored}${" ".repeat(cols - plain.length)}` : colored
+  }
+  const purple = taskColor("stack")
+  return `${purple}\x1b[1m${plain.slice(0, cols)}${RESET}`
+}

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