@supatype/cli 0.1.0 → 0.1.2

package/src/dev-shutdown.ts

@@ -1,28 +1,97 @@
 /**
- * Graceful shutdown for `supatype dev` — single path from SIGINT and TUI Ctrl+C.
+ * 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 signalsRegistered = false
+let shutdownCompleted = false
+let forceQuitRequested = false
+let hooksRegistered = false
+let ignoreSigintUntil = 0
+
+/** SIGINT/SIGTERM hooks — call as soon as `supatype dev` starts (before compose is up). */
+export function ensureDevShutdownHooks(): void {
+  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)
+  }
+}
 
 function onSignal(): void {
+  if (Date.now() < ignoreSigintUntil) return
   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>): void {
+export function registerDevShutdown(
+  work: () => Promise<void>,
+  opts?: RegisterDevShutdownOptions,
+): void {
   shutdownWork = work
-  if (signalsRegistered) return
-  signalsRegistered = true
-  process.on("SIGINT", onSignal)
-  process.on("SIGTERM", onSignal)
+  composeFallback = opts?.compose ?? null
+  shutdownCwd = opts?.cwd ?? opts?.compose?.cwd ?? null
+  ensureDevShutdownHooks()
 }
 
 /** TUI Ctrl+C — do not re-emit SIGINT (avoids double-fire on Windows raw mode). */
 export function requestDevShutdown(): void {
+  ignoreSigintUntil = Date.now() + 400
   void runDevShutdown()
 }
 
@@ -30,13 +99,33 @@ 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
+  ignoreSigintUntil = 0
+}
+
 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)
   }
@@ -44,11 +133,27 @@ async function runDevShutdown(): Promise<void> {
 
   try {
     endDevSession()
-    process.stdout.write("\n")
-    await shutdownWork?.()
+    process.stderr.write("\n[supatype] Shutting down…\n")
+    if (!shutdownWork) {
+      if (shutdownCwd) clearDevSessionLock(shutdownCwd)
+      process.exit(130)
+    }
+    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

@@ -41,7 +41,26 @@ export function colorizeLogLine(taskId: string, line: string): string {
   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}`
+/** Ink colour names for React components (parallel to ANSI taskColor). */
+export function taskInkColor(taskId: string): string {
+  switch (taskId) {
+    case "stack":
+      return "magenta"
+    case "app":
+      return "green"
+    case "studio":
+      return "cyan"
+    case "server":
+      return "green"
+    case "postgrest":
+      return "blue"
+    default:
+      return "white"
+  }
+}
+
+export function logInkColor(taskId: string, line: string): string {
+  if (line.startsWith("✗ ")) return "red"
+  if (line.startsWith("⚠ ")) return "yellow"
+  return taskInkColor(taskId)
 }

package/src/docker-runtime.ts

@@ -7,7 +7,7 @@ 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"
+import { p, printLogo } from "./ui/prompts.js"
 
 export type DockerDaemonProbe =
   | { ok: true }

package/src/engine-push-output.ts

@@ -59,6 +59,10 @@ export function formatEnginePushMessage(result: EnginePushResult): string {
 const COMPOSE_PROGRESS_LINE =
   /^Container\s+.+\s+(Running|Waiting|Healthy|Created|Starting|Started|Exited|Stopped)\s*$/i
 
+export function isComposeProgressLine(line: string): boolean {
+  return COMPOSE_PROGRESS_LINE.test(line.trim())
+}
+
 /** Drop docker compose progress noise; keep engine JSON and real errors. */
 export function filterComposeNoise(output: string): string {
   return output
@@ -67,7 +71,7 @@ export function filterComposeNoise(output: string): string {
     .filter((line) => {
       const t = line.trim()
       if (!t) return false
-      if (COMPOSE_PROGRESS_LINE.test(t)) return false
+      if (isComposeProgressLine(t)) return false
       return true
     })
     .join("\n")

package/src/ensure-binary.ts

@@ -7,8 +7,10 @@ import {
   download,
   currentPlatform,
   resolveVersionFor,
+  isCachedBinaryReady,
   type Component,
 } from "./binary-cache.js"
+import { isDownloadInProgress, waitForComponentDownload } from "./binary-download-lock.js"
 import type { SupatypeProjectConfig } from "./project-config.js"
 
 export async function ensureBinary(
@@ -24,5 +26,23 @@ export async function ensureBinary(
     }
   }
 
-  return download(component, await resolveVersionFor(component, config), currentPlatform())
+  const version = await resolveVersionFor(component, config)
+  const platform = currentPlatform()
+
+  if (isDownloadInProgress(component, version)) {
+    console.log(`[supatype] Waiting for in-progress ${component} download...`)
+    const outcome = await waitForComponentDownload(
+      component,
+      version,
+      () => isCachedBinaryReady(component, version, platform),
+      (c) => {
+        console.log(`[supatype] Still waiting for ${c}...`)
+      },
+    )
+    if (outcome === "ready") {
+      return resolveBinary(component, config)
+    }
+  }
+
+  return download(component, version, platform)
 }

package/src/ensure-component-binaries.ts

@@ -0,0 +1,71 @@
+/**
+ * Ensure CDN component binaries are cached when the host CLI needs them.
+ */
+
+import { ensureBinary } from "./ensure-binary.js"
+import type { Component } from "./components.js"
+import type { SupatypeProjectConfig } from "./project-config.js"
+import {
+  describeRequiredHostComponents,
+  requiredHostComponents,
+} from "./required-host-components.js"
+import { resolveRuntimeProvider } from "./project-config.js"
+import { error, info, warn } from "./ui/messages.js"
+
+export interface ComponentBinaryFailure {
+  component: Component
+  message: string
+}
+
+export interface EnsureComponentBinariesResult {
+  ok: boolean
+  failures: ComponentBinaryFailure[]
+  skipped: boolean
+}
+
+export async function ensureComponentBinaries(
+  config: SupatypeProjectConfig,
+  cwd: string = process.cwd(),
+): Promise<EnsureComponentBinariesResult> {
+  const components = requiredHostComponents(config, cwd)
+  const provider = resolveRuntimeProvider(config)
+
+  if (components.length === 0) {
+    return { ok: true, failures: [], skipped: true }
+  }
+
+  const list = describeRequiredHostComponents(components)
+  if (provider === "docker") {
+    info(
+      `Preparing host CLI tools (${list}) — Compose still runs Postgres and the API stack.`,
+    )
+  } else {
+    info(`Preparing local runtime components (${list})…`)
+  }
+
+  const failures: ComponentBinaryFailure[] = []
+
+  for (const component of components) {
+    try {
+      await ensureBinary(component, config)
+      info(`${component} ready.`)
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err)
+      failures.push({ component, message })
+      error(`Could not prepare ${component}: ${message}`)
+    }
+  }
+
+  return { ok: failures.length === 0, failures, skipped: false }
+}
+
+export function reportComponentBinaryFailures(failures: ComponentBinaryFailure[]): void {
+  if (failures.length === 0) return
+
+  warn("Some component binaries are still missing.")
+  for (const { component, message } of failures) {
+    warn(`  ${component}: ${message}`)
+  }
+  warn("Run manually from your project directory: supatype update")
+  warn("If downloads keep failing, check your network or try again in a few minutes.")
+}

package/src/ensure-dev-api-config.ts

@@ -0,0 +1,18 @@
+import { copyFileSync, existsSync, mkdirSync } from "node:fs"
+import { dirname, join } from "node:path"
+
+const TEMPLATE_REL = join("config", "api-config.json")
+const TARGET_REL = join(".supatype", "api-config.json")
+
+/** Copy committed `config/api-config.json` when `.supatype/api-config.json` is missing. */
+export function ensureDevApiConfig(cwd: string): boolean {
+  const target = join(cwd, TARGET_REL)
+  if (existsSync(target)) return false
+
+  const template = join(cwd, TEMPLATE_REL)
+  if (!existsSync(template)) return false
+
+  mkdirSync(dirname(target), { recursive: true })
+  copyFileSync(template, target)
+  return true
+}

package/src/env-file.ts

@@ -0,0 +1,37 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+
+/** Merge key/value updates into a project `.env` without dropping unrelated lines. */
+export function upsertEnvFile(
+  cwd: string,
+  updates: Record<string, string>,
+  removeKeys: readonly string[] = [],
+): void {
+  const envPath = join(cwd, ".env")
+  const existing = existsSync(envPath) ? readFileSync(envPath, "utf8") : ""
+  const keys = new Set([...Object.keys(updates), ...removeKeys])
+  const kept = existing
+    .split("\n")
+    .filter((line) => {
+      const key = line.split("=")[0]?.trim()
+      return key && line.includes("=") && !keys.has(key)
+    })
+  const merged = [...kept, ...Object.entries(updates).map(([key, value]) => `${key}=${value}`)]
+  writeFileSync(envPath, `${merged.join("\n").trimEnd()}\n`, "utf8")
+}
+
+export function readEnvValue(cwd: string, key: string, fallback: string): string {
+  const envPath = join(cwd, ".env")
+  if (existsSync(envPath)) {
+    const m = readFileSync(envPath, "utf8").match(new RegExp(`^${key}=(.+)$`, "m"))
+    if (m?.[1]) return m[1].trim()
+  }
+  return fallback
+}
+
+export function readEnvInt(cwd: string, key: string): number | null {
+  const raw = readEnvValue(cwd, key, "")
+  if (!raw) return null
+  const port = Number(raw)
+  return Number.isInteger(port) && port > 0 && port <= 65535 ? port : null
+}

package/src/init-dependency-versions.ts

@@ -0,0 +1,69 @@
+import { cliPackageVersion } from "./cli-package-version.js"
+
+export interface InitDependencyVersions {
+  cli: string
+  types: string
+}
+
+type NpmRegistryPackage = {
+  versions?: Record<string, unknown>
+  "dist-tags"?: { latest?: string }
+}
+
+/** Fallback when the registry is unreachable (offline / tests). */
+export function initDependencyVersionsFallback(): InitDependencyVersions {
+  const version = cliPackageVersion()
+  return { cli: version, types: version }
+}
+
+async function fetchNpmPackage(name: string): Promise<NpmRegistryPackage | null> {
+  const url = `https://registry.npmjs.org/${encodeURIComponent(name)}`
+  try {
+    const resp = await fetch(url, { signal: AbortSignal.timeout(10_000) })
+    if (!resp.ok) return null
+    return (await resp.json()) as NpmRegistryPackage
+  } catch {
+    return null
+  }
+}
+
+function versionPublishedOnNpm(meta: NpmRegistryPackage | null, version: string): boolean {
+  return Boolean(meta?.versions?.[version])
+}
+
+function latestPublishedOnNpm(meta: NpmRegistryPackage | null): string | null {
+  const latest = meta?.["dist-tags"]?.latest
+  return typeof latest === "string" && latest.trim() !== "" ? latest.trim() : null
+}
+
+function resolvePackageVersion(
+  meta: NpmRegistryPackage | null,
+  preferred: string,
+): string {
+  if (versionPublishedOnNpm(meta, preferred)) return preferred
+  const latest = latestPublishedOnNpm(meta)
+  if (latest) return latest
+  return preferred
+}
+
+/**
+ * Pick @supatype/cli and @supatype/types versions that exist on npm.
+ * The running CLI may be a local dev build ahead of the registry (e.g. 0.1.3
+ * while types is only published at 0.1.1).
+ */
+export async function resolveInitDependencyVersions(): Promise<InitDependencyVersions> {
+  const runningCli = cliPackageVersion()
+  const [cliMeta, typesMeta] = await Promise.all([
+    fetchNpmPackage("@supatype/cli"),
+    fetchNpmPackage("@supatype/types"),
+  ])
+
+  if (!cliMeta && !typesMeta) {
+    return initDependencyVersionsFallback()
+  }
+
+  return {
+    cli: resolvePackageVersion(cliMeta, runningCli),
+    types: resolvePackageVersion(typesMeta, runningCli),
+  }
+}

package/src/init-package-json.ts

@@ -0,0 +1,63 @@
+import type { InitDependencyVersions } from "./init-dependency-versions.js"
+
+export interface MergePackageJsonOptions {
+  projectName: string
+  app: { viteDevUrl?: string; mode: string }
+  helloFunction: boolean
+}
+
+type PackageJson = {
+  name?: string
+  private?: boolean
+  type?: string
+  scripts?: Record<string, string>
+  dependencies?: Record<string, string>
+  devDependencies?: Record<string, string>
+}
+
+const CORE_SCRIPTS = {
+  dev: "supatype dev",
+  push: "supatype push",
+  seed: "tsx seed.ts",
+} as const
+
+/** Merge Supatype deps/scripts into an existing package.json object. */
+export function mergeSupatypePackageJson(
+  pkg: PackageJson,
+  opts: MergePackageJsonOptions,
+  deps: InitDependencyVersions,
+): PackageJson {
+  const next: PackageJson = { ...pkg }
+
+  if (!next.name) next.name = opts.projectName
+  if (next.private === undefined) next.private = true
+  if (!next.type) next.type = "module"
+
+  const scripts = { ...(next.scripts ?? {}) }
+  for (const [key, value] of Object.entries(CORE_SCRIPTS)) {
+    if (scripts[key] === undefined) scripts[key] = value
+  }
+  if (scripts.dev !== CORE_SCRIPTS.dev && scripts["supatype:dev"] === undefined) {
+    scripts["supatype:dev"] = CORE_SCRIPTS.dev
+  }
+  if (opts.app.viteDevUrl && scripts.vite === undefined) {
+    scripts.vite = "vite"
+  }
+  if (opts.helloFunction && scripts.functions === undefined) {
+    scripts.functions = "supatype functions serve"
+  }
+  next.scripts = scripts
+
+  const dependencies = { ...(next.dependencies ?? {}) }
+  if (dependencies["@supatype/cli"] === undefined) dependencies["@supatype/cli"] = `^${deps.cli}`
+  if (dependencies["@supatype/types"] === undefined) dependencies["@supatype/types"] = `^${deps.types}`
+  next.dependencies = dependencies
+
+  const devDependencies = { ...(next.devDependencies ?? {}) }
+  if (devDependencies.tsx === undefined) devDependencies.tsx = "^4.19.2"
+  if (devDependencies.typescript === undefined) devDependencies.typescript = "^5"
+  if (opts.app.viteDevUrl && devDependencies.vite === undefined) devDependencies.vite = "^6"
+  next.devDependencies = devDependencies
+
+  return next
+}

package/src/postgres-ctl.ts

@@ -148,7 +148,8 @@ export async function isPortInUse(port: number): Promise<boolean> {
   return new Promise((resolve) => {
     const server = createServer()
     server.once("error", (err: NodeJS.ErrnoException) => {
-      resolve(err.code === "EADDRINUSE")
+      // EADDRINUSE — something is listening. EACCES — Windows excluded/reserved port range.
+      resolve(err.code === "EADDRINUSE" || err.code === "EACCES")
     })
     server.once("listening", () => {
       server.close(() => resolve(false))

package/src/required-host-components.ts

@@ -0,0 +1,37 @@
+/**
+ * Which CDN-cached host binaries a project needs (native vs docker).
+ *
+ * Docker runs Postgres, API, and schema push in Compose, but the CLI still uses a
+ * host engine binary for type generation and admin-config refresh after push.
+ */
+
+import { existsSync } from "node:fs"
+import type { Component } from "./components.js"
+import {
+  functionsPathCandidatesFromProject,
+  resolveRuntimeProvider,
+  type SupatypeProjectConfig,
+} from "./project-config.js"
+
+export function requiredHostComponents(
+  config: SupatypeProjectConfig,
+  cwd: string = process.cwd(),
+): Component[] {
+  const provider = resolveRuntimeProvider(config)
+
+  if (provider === "docker") {
+    return ["engine"]
+  }
+
+  const components: Component[] = ["engine", "server", "postgres"]
+  const hasFunctions = functionsPathCandidatesFromProject(config, cwd).some((dir) =>
+    existsSync(dir),
+  )
+  if (hasFunctions) components.push("deno")
+  return components
+}
+
+export function describeRequiredHostComponents(components: readonly Component[]): string {
+  if (components.length === 0) return ""
+  return components.join(", ")
+}

package/src/resolve-api-url.ts

@@ -0,0 +1,43 @@
+/**
+ * Resolve the project API base URL (Kong gateway or direct server) for CLI HTTP calls.
+ */
+
+import { loadConfig } from "./config.js"
+import { readEnvValue } from "./env-file.js"
+import { serverBaseUrl } from "./project-config.js"
+
+const API_URL_ENV_KEYS = [
+  "SUPATYPE_URL",
+  "SUPATYPE_API_URL",
+  "PUBLIC_SUPATYPE_URL",
+  "NEXT_PUBLIC_SUPATYPE_URL",
+  "SITE_URL",
+  "API_EXTERNAL_URL",
+] as const
+
+/** Kong or server origin without a trailing slash. */
+export function resolveProjectApiUrl(cwd: string): string {
+  for (const key of API_URL_ENV_KEYS) {
+    const value = readEnvValue(cwd, key, "").trim()
+    if (value) {
+      return value.replace(/\/+$/, "")
+    }
+  }
+
+  const kongPort = readEnvValue(cwd, "SUPATYPE_KONG_PORT", "").trim()
+  if (kongPort) {
+    return `http://localhost:${kongPort}`
+  }
+
+  try {
+    const fromConfig = serverBaseUrl(loadConfig(cwd))
+    if (fromConfig) {
+      return fromConfig.replace(/\/+$/, "")
+    }
+  } catch {
+    // No supatype.config — fall through to PORT default.
+  }
+
+  const port = readEnvValue(cwd, "PORT", "54321").trim() || "54321"
+  return `http://localhost:${port}`
+}