@supatype/cli 0.1.1 → 0.1.3

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/init-project-detect.ts

@@ -0,0 +1,99 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs"
+import { join } from "node:path"
+
+const VITE_CONFIG_NAMES = [
+  "vite.config.ts",
+  "vite.config.js",
+  "vite.config.mjs",
+  "vite.config.cjs",
+] as const
+
+const SUPATYPE_CONFIG_NAMES = [
+  "supatype.config.ts",
+  "supatype.config.js",
+  "supatype.config.mjs",
+] as const
+
+export interface DetectedProjectSetup {
+  /** Directory has files other than `.git`. */
+  hasExistingFiles: boolean
+  hasSupatypeConfig: boolean
+  hasVite: boolean
+  hasViteConfig: boolean
+  viteDevUrl: string
+  staticDir: string
+  /** Human-readable bullets for the init wizard. */
+  summaryLines: string[]
+}
+
+function hasPackageVite(cwd: string): boolean {
+  const pkgPath = join(cwd, "package.json")
+  if (!existsSync(pkgPath)) return false
+  try {
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf8")) as {
+      dependencies?: Record<string, string>
+      devDependencies?: Record<string, string>
+    }
+    return Boolean(pkg.devDependencies?.["vite"] ?? pkg.dependencies?.["vite"])
+  } catch {
+    return false
+  }
+}
+
+function readVitePort(cwd: string): number {
+  for (const name of VITE_CONFIG_NAMES) {
+    const path = join(cwd, name)
+    if (!existsSync(path)) continue
+    const src = readFileSync(path, "utf8")
+    const portMatch = src.match(/port:\s*(\d+)/)
+    if (portMatch?.[1]) {
+      const port = Number.parseInt(portMatch[1], 10)
+      if (Number.isInteger(port) && port > 0) return port
+    }
+  }
+  return 5173
+}
+
+function detectStaticDir(cwd: string): string {
+  if (existsSync(join(cwd, "dist", "index.html"))) return "./dist"
+  if (existsSync(join(cwd, "public", "index.html"))) return "./public"
+  if (existsSync(join(cwd, "dist"))) return "./dist"
+  if (existsSync(join(cwd, "public"))) return "./public"
+  return "./public"
+}
+
+/** Inspect `cwd` before init prompts — Vite, static dir, existing Supatype config. */
+export function detectProjectSetup(cwd: string): DetectedProjectSetup {
+  let entries: string[] = []
+  try {
+    entries = readdirSync(cwd).filter((entry) => entry !== ".git")
+  } catch {
+    entries = []
+  }
+
+  const hasExistingFiles = entries.length > 0
+  const hasViteConfig = VITE_CONFIG_NAMES.some((name) => existsSync(join(cwd, name)))
+  const hasVite = hasViteConfig || hasPackageVite(cwd)
+  const viteDevUrl = `http://127.0.0.1:${readVitePort(cwd)}`
+  const staticDir = detectStaticDir(cwd)
+  const hasSupatypeConfig = SUPATYPE_CONFIG_NAMES.some((name) => existsSync(join(cwd, name)))
+
+  const summaryLines: string[] = []
+  if (hasSupatypeConfig) summaryLines.push("supatype.config already present")
+  if (hasViteConfig) summaryLines.push(`Vite config found (${viteDevUrl})`)
+  else if (hasVite) summaryLines.push(`Vite dependency in package.json (${viteDevUrl})`)
+  if (existsSync(join(cwd, staticDir.replace(/^\.\//, "")))) {
+    summaryLines.push(`static assets in ${staticDir}`)
+  }
+  if (existsSync(join(cwd, "package.json"))) summaryLines.push("package.json present")
+
+  return {
+    hasExistingFiles,
+    hasSupatypeConfig,
+    hasVite,
+    hasViteConfig,
+    viteDevUrl,
+    staticDir,
+    summaryLines,
+  }
+}

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

package/src/rest-cache-admin.ts

@@ -0,0 +1,135 @@
+/**
+ * Admin REST cache API client for CLI commands.
+ */
+
+import { readEnvValue } from "./env-file.js"
+import { resolveProjectApiUrl } from "./resolve-api-url.js"
+
+export interface RestCacheEntrySummary {
+  key: string
+  table?: string
+  scope?: string
+  method?: string
+  path?: string
+  raw_query?: string
+  ttl_seconds: number
+  size_bytes: number
+  cached_at?: string
+}
+
+export interface RestCacheListResponse {
+  entries: RestCacheEntrySummary[]
+  cursor: string
+}
+
+export interface RestCacheDetail extends RestCacheEntrySummary {
+  status_code: number
+  content_type?: string
+  body_preview?: string
+  body_json?: unknown
+}
+
+function serviceRoleKey(cwd: string): string {
+  const key =
+    readEnvValue(cwd, "SUPATYPE_SERVICE_ROLE_KEY", "").trim() ||
+    readEnvValue(cwd, "SERVICE_ROLE_KEY", "").trim()
+  if (!key) {
+    throw new Error("SERVICE_ROLE_KEY not found in .env — run supatype dev or supatype keys")
+  }
+  return key.trim()
+}
+
+function adminHeaders(cwd: string): Record<string, string> {
+  const key = serviceRoleKey(cwd)
+  return {
+    Authorization: `Bearer ${key}`,
+    apikey: key,
+    "Content-Type": "application/json",
+  }
+}
+
+function formatCacheApiError(
+  operation: string,
+  status: number,
+  body: string,
+  baseUrl: string,
+): string {
+  const trimmed = body.trim()
+  if (status === 404) {
+    return (
+      `${operation} failed (404): ${trimmed || "not found"}\n` +
+      `  API: ${baseUrl}/admin/v1/cache\n` +
+      "  Start the stack with `supatype dev`, or check SUPATYPE_URL / PUBLIC_SUPATYPE_URL in .env."
+    )
+  }
+  if (status === 403 && trimmed.includes("rest_cache_not_available")) {
+    return "REST server cache is not available on this plan or deployment."
+  }
+  if (status === 503 && trimmed.includes("valkey")) {
+    return "Valkey is not configured — server-side REST cache requires Valkey (supatype dev with docker)."
+  }
+  return `${operation} failed (${status}): ${trimmed || "(empty body)"}`
+}
+
+function normalizeListResponse(data: RestCacheListResponse): RestCacheListResponse {
+  return {
+    entries: data.entries ?? [],
+    cursor: data.cursor ?? "0",
+  }
+}
+
+export async function listRestCacheEntries(
+  cwd: string,
+  opts?: { table?: string | undefined; cursor?: string | undefined; limit?: number | undefined },
+): Promise<RestCacheListResponse> {
+  const baseUrl = resolveProjectApiUrl(cwd)
+  const params = new URLSearchParams()
+  if (opts?.table) params.set("table", opts.table)
+  if (opts?.cursor) params.set("cursor", opts.cursor)
+  if (opts?.limit !== undefined) params.set("limit", String(opts.limit))
+  const qs = params.toString()
+  const url = `${baseUrl}/admin/v1/cache${qs ? `?${qs}` : ""}`
+  const res = await fetch(url, { headers: adminHeaders(cwd) })
+  if (!res.ok) {
+    const body = await res.text()
+    throw new Error(formatCacheApiError("list cache", res.status, body, baseUrl))
+  }
+  const data = (await res.json()) as RestCacheListResponse
+  return normalizeListResponse(data)
+}
+
+export async function getRestCacheEntry(cwd: string, key: string): Promise<RestCacheDetail> {
+  const baseUrl = resolveProjectApiUrl(cwd)
+  const enc = Buffer.from(key, "utf8").toString("base64url")
+  const url = `${baseUrl}/admin/v1/cache/entries/${encodeURIComponent(enc)}`
+  const res = await fetch(url, { headers: adminHeaders(cwd) })
+  if (!res.ok) {
+    const body = await res.text()
+    throw new Error(formatCacheApiError("get cache entry", res.status, body, baseUrl))
+  }
+  return res.json() as Promise<RestCacheDetail>
+}
+
+export async function deleteRestCacheEntry(cwd: string, key: string): Promise<void> {
+  const baseUrl = resolveProjectApiUrl(cwd)
+  const enc = Buffer.from(key, "utf8").toString("base64url")
+  const url = `${baseUrl}/admin/v1/cache/entries/${encodeURIComponent(enc)}`
+  const res = await fetch(url, { method: "DELETE", headers: adminHeaders(cwd) })
+  if (!res.ok) {
+    const body = await res.text()
+    throw new Error(formatCacheApiError("delete cache entry", res.status, body, baseUrl))
+  }
+}
+
+export async function flushRestCache(cwd: string, table?: string): Promise<void> {
+  const baseUrl = resolveProjectApiUrl(cwd)
+  const params = new URLSearchParams()
+  if (table) params.set("table", table)
+  const qs = params.toString()
+  const url = `${baseUrl}/admin/v1/cache${qs ? `?${qs}` : ""}`
+  const res = await fetch(url, { method: "DELETE", headers: adminHeaders(cwd) })
+  if (!res.ok) {
+    const body = await res.text()
+    throw new Error(formatCacheApiError("flush cache", res.status, body, baseUrl))
+  }
+}

package/src/scripts/postinstall.ts

@@ -1,57 +1,20 @@
 /**
- * Postinstall script — downloads component binaries on first install.
+ * Postinstall script — @supatype/cli global/project install.
  *
- * Components: supatype-engine, supatype-server, supatype-pg (Postgres), deno.
- * Binaries are cached in ~/.supatype/cache/{component}/{version}/.
- *
- * Failures are non-fatal: an installation message is printed and the user
- * can run `supatype update` manually to retry.
+ * Host binaries (engine, server, postgres, deno) are downloaded on demand:
+ * - native provider: first supatype dev / supatype update
+ * - docker provider: Compose images on first supatype dev
  */
 
-import { download, currentPlatform, fetchAllLatestVersions, type Component } from "../binary-cache.js"
-
 async function main() {
-  const platform = currentPlatform()
-
-  let versions: Record<Component, string>
-  try {
-    console.log("[supatype] Fetching latest component versions...")
-    versions = await fetchAllLatestVersions()
-  } catch (err) {
-    console.error(`[supatype] Failed to fetch latest versions: ${(err as Error).message}`)
-    console.error("[supatype] Run 'supatype update' to download component binaries.")
-    return
-  }
-
-  console.log(`[supatype] Downloading component binaries for ${platform.os}/${platform.arch}...`)
-
-  const components = Object.entries(versions) as [Component, string][]
-
-  let anyFailed = false
-  for (const [component, version] of components) {
-    try {
-      await download(component, version, platform)
-    } catch (err) {
-      console.error(`[supatype] Failed to download ${component} v${version}: ${(err as Error).message}`)
-      anyFailed = true
-    }
-  }
-
-  if (anyFailed) {
-    // npm hides postinstall output unless --foreground-scripts, so don't rely on
-    // this being seen: the CLI re-attempts the download (with retry) on first use.
-    console.error(
-      "[supatype] Some component binaries failed to download. " +
-        "They will be re-downloaded automatically on first use; " +
-        "run 'supatype update' to retry now.",
-    )
-  } else {
-    console.log("[supatype] All component binaries downloaded successfully.")
-  }
+  console.log(
+    "[supatype] CLI installed. " +
+      "Runtime components download automatically on first use " +
+      "(supatype dev or supatype update).",
+  )
 }
 
 main().catch((err) => {
-  // Non-fatal — postinstall failures should not break npm install.
   console.error("[supatype] Postinstall failed:", err)
   process.exit(0)
 })

package/src/self-host-compose.ts

@@ -292,9 +292,7 @@ ${studioService}
     ? `      - "80:8000"
       - "443:8443"`
     : `      - "\${SUPATYPE_KONG_PORT:-18473}:8000"`
-  const kongTlsDependsOn = tlsEnabled ? "\n      - valkey" : ""
-  const valkeyBlock = tlsEnabled
-    ? `
+  const valkeyBlock = `
   valkey:
     image: \${SUPATYPE_VALKEY_IMAGE:-valkey/valkey:8-alpine}
     command: ["valkey-server", "--appendonly", "yes"]
@@ -303,23 +301,18 @@ ${studioService}
     volumes:
       - valkey-data:/data
 `
-    : ""
+  const kongValkeyDepends = "\n      - valkey"
   const tlsHintComment = tlsEnabled
     ? ""
     : `  # HTTPS is off. To enable automatic TLS (Let's Encrypt) for production, set in supatype.config.ts:
   #   server: { mode: "standalone", domain: "your.domain", tls: { email: "you@example.com" } }
   # then re-run \`supatype self-host compose up -d\`. Kong publishes :80/:443 and provisions certs automatically.
 `
-  const volumesBlock = tlsEnabled
-    ? `volumes:
+  const volumesBlock = `volumes:
   db-data:
   minio-data:
   valkey-data:
 `
-    : `volumes:
-  db-data:
-  minio-data:
-`
 
   return `# Generated by supatype self-host compose
 # Kong → supatype-server (unified gateway) → internal PostgREST / storage / etc.
@@ -431,6 +424,7 @@ ${serverPorts}    volumes:
       SUPATYPE_DENO_FUNCTIONS_DIR: /project/functions
       SUPATYPE_FUNCTIONS_WORKER_URL: http://functions-worker:8001
       SUPATYPE_CONTROL_PLANE_URL: http://control-plane:8080
+      SUPATYPE_VALKEY_ADDR: valkey:6379
 ${appEnv}
       GOTRUE_API_HOST: 0.0.0.0
       GOTRUE_API_PORT: 9999
@@ -450,6 +444,8 @@ ${devLocal ? "      STUDIO_OPEN_DEV: \"1\"\n" : ""}
     depends_on:
       db:
         condition: service_healthy
+      valkey:
+        condition: service_started
       postgrest:
         condition: service_started
       storage:
@@ -492,7 +488,7 @@ ${kongTlsEnv}    volumes:
     ports:
 ${kongPorts}
     depends_on:
-${kongDependsOn}${kongTlsDependsOn}
+${kongDependsOn}${kongValkeyDepends}
 
 ${volumesBlock}`
 }
@@ -594,7 +590,21 @@ export function runDockerCompose(
     ? { ...process.env, COMPOSE_PROGRESS: "quiet" }
     : process.env
   const stdio = options?.quiet ? "pipe" : "inherit"
-  const result = spawnSync("docker", composeArgs, { stdio, cwd: projectRoot, env })
+  const result = spawnSync("docker", composeArgs, {
+    stdio,
+    cwd: projectRoot,
+    env,
+    ...(options?.quiet ? { encoding: "utf8" as const } : {}),
+  })
+  if (options?.quiet && result.status !== 0) {
+    const detail = [result.stderr, result.stdout]
+      .filter((s): s is string => typeof s === "string" && s.trim() !== "")
+      .join("\n")
+      .trim()
+    if (detail) {
+      console.error(`[supatype] docker compose: ${detail}`)
+    }
+  }
   return result.status ?? 1
 }
 

package/src/studio-dev-server.ts

@@ -2,7 +2,8 @@ import { existsSync } from "node:fs"
 import { join, resolve } from "node:path"
 import { ProcessManager } from "./process-manager.js"
 
-const STUDIO_PORT = 3002
+/** Vite dev server port when `overrides.studio` is set. */
+export const STUDIO_DEV_PORT = 3002
 
 export interface StudioDevServerOptions {
   cwd: string
@@ -15,8 +16,8 @@ export interface StudioDevServerOptions {
    */
   proxyTarget: string
   /**
-   * Public Supatype URL the browser uses. Compose dev: Kong on the host.
-   * Native dev: Vite dev server (same origin as Studio).
+   * Browser API base URL. Must match the Vite dev origin (`http://localhost:3002`)
+   * so fetches hit the Vite proxy (SUPATYPE_PROXY_TARGET) and avoid CORS.
    */
   viteSupatypeUrl: string
   /** Vite `base` — `/studio/` when behind Kong at `/studio/`; `/` for native dev on :3002. */
@@ -35,7 +36,7 @@ export function startStudioViteDevServer(opts: StudioDevServerOptions): ProcessM
   const basePath = opts.basePath ?? "/"
   return new ProcessManager(
     process.execPath,
-    [viteJs, "--port", String(STUDIO_PORT), "--strictPort", "--host"],
+    [viteJs, "--port", String(STUDIO_DEV_PORT), "--strictPort", "--host"],
     {
       label: "studio",
       pidDir: opts.pidDir,

package/src/ui/README.md

@@ -1,17 +1,21 @@
 # CLI terminal UI (`packages/cli/src/ui/`)
 
-Shared output layer for `supatype` commands (not `supatype dev` TUI).
+Shared Ink-based design system for the Supatype CLI.
 
 | Module | Use for |
 |--------|---------|
-| `messages.ts` | `info` / `warn` / `error` (Clack log in TTY; `[supatype]` in CI), `file`, `step`, `plain` |
-| `fatal.ts` | `fatalError`, `reportCliFatal` — branded fatals + global catch helper |
-| `confirm.ts` | Yes/no prompts (Clack in TTY; respects `--yes` / non-TTY) |
-| `progress.ts` | `withSpinner` for long async work |
-| `prompts.ts` | Logo, Clack wizard helpers, `promptText` |
+| `theme.ts` | Brand + semantic colours (Ink + plain ANSI) |
+| `messages.ts` | `info` / `warn` / `error` / `success`, `file`, `step`, `plain` |
+| `fatal.ts` | `fatalError`, `reportCliFatal` |
+| `confirm.ts` | Yes/no prompts (Ink overlay in dev, Ink flow in TTY) |
+| `progress.ts` | `withSpinner` + `runCommandChrome` for one-shot commands |
+| `runtime/command-chrome.ts` | Ink shell (logo, logs, spinner) — applied globally via `wrapProgramActionsWithChrome` in `cli.ts` |
+| `prompts.ts` | Logo, `promptText`, `promptPassword`, `ensureNotCancelled` |
+| `clack.ts` | Clack-compatible `p.*` API + `runClackFlow()` for wizards |
+| `flows/` | Ink flow shell + prompt fields |
+| `dev/DevDashboard.tsx` | `supatype dev` task list + log pane + prompt overlay |
 | `next-steps.ts` | Bulleted follow-up commands |
-| `brand.ts` | ANSI colours + logo styling (shared with dev TUI) |
 
-**`supatype dev`** keeps its own alt-screen TUI (`dev-tui.ts`). Do not route dev logs through Clack.
+**Convention:** interactive wizards use `runClackFlow(async (p) => …)` (`init`, `link`, `add domain`); one-shot commands get branded chrome automatically in `cli.ts` via `wrapProgramActionsWithChrome`. **`supatype dev`** keeps a persistent Ink dashboard (excluded from auto-wrap).
 
-**Convention:** interactive multi-step flows use Clack (`init`, `add`, `link`); one-shot commands use `info` + optional `withSpinner`.
+**Plain profile:** when `!isInteractive()` (CI, pipes), helpers fall back to `[supatype]`-prefixed lines.