@supatype/cli 0.1.1 → 0.1.2

package/src/commands/cache.ts

@@ -1,24 +1,30 @@
 /**
- * supatype cache — list and clean cached component binaries.
+ * supatype cache — list and clean cached component binaries + REST Valkey cache.
  */
 
 import type { Command } from "commander"
 import { existsSync, readdirSync, rmSync, statSync } from "node:fs"
 import { join } from "node:path"
 import { cacheRoot, type Component } from "../binary-cache.js"
-import { info, plain } from "../ui/messages.js"
+import {
+  deleteRestCacheEntry,
+  flushRestCache,
+  getRestCacheEntry,
+  listRestCacheEntries,
+} from "../rest-cache-admin.js"
+import { error, info, plain } from "../ui/messages.js"
 
 const COMPONENTS: Component[] = ["engine", "server", "postgres", "deno"]
 
 export function registerCache(program: Command): void {
   const cache = program
     .command("cache")
-    .description("Manage cached component binaries")
+    .description("Manage cached component binaries and REST API response cache")
 
   cache
     .command("list")
     .description("List cached component binaries and their sizes")
-    .action(() => {
+    .action(async () => {
       const root = cacheRoot()
       if (!existsSync(root)) {
         info("Cache is empty.")
@@ -62,7 +68,7 @@ export function registerCache(program: Command): void {
         "  supatype cache clean engine    # remove all engine versions\n" +
         "  supatype cache clean engine 0.4.2",
     )
-    .action((component?: string, version?: string) => {
+    .action(async (component?: string, version?: string) => {
       const root = cacheRoot()
       if (!existsSync(root)) {
         info("Cache is already empty.")
@@ -91,6 +97,100 @@ export function registerCache(program: Command): void {
 
       info("Done.")
     })
+
+  const rest = cache
+    .command("rest")
+    .description("Manage REST API response cache in Valkey")
+
+  rest
+    .command("list")
+    .description("List cached REST GET entries")
+    .option("--table <name>", "Filter by table name")
+    .option("--json", "Output JSON")
+    .action(async (opts: { table?: string; json?: boolean }) => {
+      const cwd = process.cwd()
+      try {
+        const result = await listRestCacheEntries(cwd, { table: opts.table, limit: 100 })
+        if (opts.json) {
+          plain(JSON.stringify(result, null, 2))
+          return
+        }
+        if (result.entries.length === 0) {
+          info("No REST cache entries.")
+          return
+        }
+        for (const e of result.entries) {
+          plain(
+            `  ${e.table ?? "?"}  ${e.scope ?? "?"}  ttl=${e.ttl_seconds}s  ${e.size_bytes}B  ${e.key}`,
+          )
+        }
+        if (result.cursor !== "0") {
+          plain(`\n(more available — cursor ${result.cursor})`)
+        }
+      } catch (e) {
+        error(e instanceof Error ? e.message : String(e))
+        process.exitCode = 1
+      }
+    })
+
+  rest
+    .command("get <key>")
+    .description("Show one cache entry (full Valkey key)")
+    .option("--json", "Output JSON")
+    .action(async (key: string, opts: { json?: boolean }) => {
+      const cwd = process.cwd()
+      try {
+        const detail = await getRestCacheEntry(cwd, key)
+        if (opts.json) {
+          plain(JSON.stringify(detail, null, 2))
+          return
+        }
+        plain(`key:     ${detail.key}`)
+        plain(`table:   ${detail.table ?? ""}`)
+        plain(`scope:   ${detail.scope ?? ""}`)
+        plain(`ttl:     ${detail.ttl_seconds}s`)
+        plain(`status:  ${detail.status_code}`)
+        if (detail.body_preview) plain(`body:\n${detail.body_preview}`)
+      } catch (e) {
+        error(e instanceof Error ? e.message : String(e))
+        process.exitCode = 1
+      }
+    })
+
+  rest
+    .command("delete <key>")
+    .description("Delete one cache entry")
+    .action(async (key: string) => {
+      const cwd = process.cwd()
+      try {
+        await deleteRestCacheEntry(cwd, key)
+        info(`Deleted ${key}`)
+      } catch (e) {
+        error(e instanceof Error ? e.message : String(e))
+        process.exitCode = 1
+      }
+    })
+
+  rest
+    .command("flush")
+    .description("Flush REST cache entries")
+    .option("--table <name>", "Only flush one table")
+    .option("--yes", "Confirm flush")
+    .action(async (opts: { table?: string; yes?: boolean }) => {
+      if (!opts.yes) {
+        error("Pass --yes to confirm flush")
+        process.exitCode = 1
+        return
+      }
+      const cwd = process.cwd()
+      try {
+        await flushRestCache(cwd, opts.table)
+        info(opts.table ? `Flushed cache for table ${opts.table}` : "Flushed all REST cache entries")
+      } catch (e) {
+        error(e instanceof Error ? e.message : String(e))
+        process.exitCode = 1
+      }
+    })
 }
 
 function dirSize(dir: string): number {

package/src/commands/dev.ts

@@ -36,13 +36,15 @@ import {
 import { ensureBinary } from "../ensure-binary.js"
 import { startProxyDevApp } from "../app/proxy-dev-app.js"
 import { ProcessManager } from "../process-manager.js"
-import { startStudioViteDevServer } from "../studio-dev-server.js"
+import { STUDIO_DEV_PORT, startStudioViteDevServer } from "../studio-dev-server.js"
 import { restoreSystemRelationTargets } from "../restore-system-relation-targets.js"
 import { localStorageEnv } from "../local-storage.js"
 import { beginDevSession, endDevSession, resolveDevUiMode, startDevSession } from "../dev-session.js"
+import { publishDevReady } from "../dev-ready-panel.js"
 import { probeDockerDaemon, reportDockerUnavailable } from "../docker-runtime.js"
 import { fatalError } from "../ui/fatal.js"
 import { registerDevShutdown } from "../dev-shutdown.js"
+import { ensureValkeySidecar, stopValkeySidecar } from "../valkey-sidecar.js"
 import {
   initdb,
   start as pgStart,
@@ -133,7 +135,6 @@ export function registerDev(program: Command): void {
       }
 
       beginDevSession(resolveDevUiMode(opts.stream === true))
-      startDevSession()
       if (hasMeaningfulOverrides(config)) {
         console.warn("[supatype] Local binary overrides active:")
         for (const line of describeActiveOverrides(config)) {
@@ -326,9 +327,13 @@ ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON SEQUENCES TO authenticate
               ? "ses"
               : "smtp"
 
+      const valkeySidecar = ensureValkeySidecar(projectName)
+
       const serverEnv: Record<string, string> = {
         // supatype-server outer layer
         SUPATYPE_MODE: config.server.mode ?? "dev",
+        ...(valkeySidecar.addr ? { SUPATYPE_VALKEY_ADDR: valkeySidecar.addr } : {}),
+        SUPATYPE_MANAGED_PROJECT_REF: projectName,
         SUPATYPE_MANIFEST_PATH: manifestPath,
         SUPATYPE_ADMIN_CONFIG_PATH: adminConfigPath,
         SUPATYPE_POSTGREST_URL: `http://127.0.0.1:${postgrestPort}`,
@@ -471,7 +476,7 @@ ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON SEQUENCES TO authenticate
       }
 
       // ── 9d. Studio (optional) ─────────────────────────────────────────────
-      const studioPort = 3002
+      const studioPort = STUDIO_DEV_PORT
       let studioProc: ProcessManager | null = null
 
       const studioOverride = config.overrides?.studio
@@ -489,25 +494,24 @@ ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON SEQUENCES TO authenticate
 
       const appProc = startProxyDevApp(cwd, config, pidDir)
 
-      // ── Print status ──────────────────────────────────────────────────────
-      console.log(`
-[supatype] Services running:
-  Postgres         ${dbURL}
-  supatype-server  http://localhost:${serverPort}
-    REST API       http://localhost:${serverPort}/rest/v1/
-    Auth           http://localhost:${serverPort}/auth/v1/
-    Storage        http://localhost:${serverPort}/storage/v1/
-    Realtime       ws://localhost:${serverPort}/realtime/v1/${studioProc ? `\n  Studio           http://localhost:${studioPort}` : ""}
-
-  API keys (local dev only):
-    anon key       ${anonKey}
-    service_role   ${serviceRoleKey}
-
-  JWT secret: ${LOCAL_JWT_SECRET}
-
-  Press Ctrl+C to stop.
-`)
+      const links = [
+        { label: "API", url: `http://localhost:${serverPort}` },
+        { label: "REST", url: `http://localhost:${serverPort}/rest/v1/` },
+        { label: "Auth", url: `http://localhost:${serverPort}/auth/v1/` },
+        { label: "Storage", url: `http://localhost:${serverPort}/storage/v1/` },
+        { label: "Realtime", url: `ws://localhost:${serverPort}/realtime/v1/` },
+      ]
+      if (studioProc) {
+        links.push({ label: "Studio", url: `http://localhost:${studioPort}` })
+      }
 
+      publishDevReady({
+        title: "Services running",
+        links,
+        anonKey,
+        serviceRoleKey,
+        hints: [`Postgres ${dbURL}`, `JWT secret: ${LOCAL_JWT_SECRET}`],
+      })
 
       // ── Shutdown handler ──────────────────────────────────────────────────
       registerDevShutdown(async () => {
@@ -518,6 +522,7 @@ ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON SEQUENCES TO authenticate
           studioProc?.stop(),
           appProc?.stop(),
         ])
+        stopValkeySidecar(valkeySidecar.containerName)
         await stopPostgres()
       })
 

package/src/commands/init.ts

@@ -1,36 +1,25 @@
 import type { Command } from "commander"
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
-import { resolve, join, dirname, basename } from "node:path"
-import { fileURLToPath } from "node:url"
+import { resolve, join, basename } from "node:path"
 import { spawnSync } from "node:child_process"
-import * as p from "@clack/prompts"
+import { p, runClackFlow } from "../ui/clack.js"
 import { ensureNotCancelled, printLogo } from "../ui/prompts.js"
 import { generateAndWriteKeys } from "./keys.js"
 import { file, error, info, plain, warn } from "../ui/messages.js"
 import { nextSteps } from "../ui/next-steps.js"
 import { probeDockerDaemon, reportDockerUnavailable } from "../docker-runtime.js"
-
-export { scaffold }
-
-// ─── Markers used by `supatype app add / remove` (app.ts) ────────────────────
-export const APP_COMPOSE_MARKER = "  # ─── App service (run: supatype app add) ───"
-export const KONG_APP_MARKER = "  # ─── App fallback route (run: supatype app add) ───"
-
-const CLI_PACKAGE_JSON = join(
-  dirname(fileURLToPath(import.meta.url)),
-  "..",
-  "..",
-  "package.json",
-)
-
-function cliPackageVersion(): string {
-  try {
-    const pkg = JSON.parse(readFileSync(CLI_PACKAGE_JSON, "utf8")) as { version?: string }
-    return pkg.version ?? "0.1.0"
-  } catch {
-    return "0.1.0"
-  }
-}
+import { loadConfig } from "../config.js"
+import {
+  ensureComponentBinaries,
+  reportComponentBinaryFailures,
+} from "../ensure-component-binaries.js"
+import { mergeSupatypePackageJson } from "../init-package-json.js"
+import { cliPackageVersion } from "../cli-package-version.js"
+import {
+  initDependencyVersionsFallback,
+  resolveInitDependencyVersions,
+  type InitDependencyVersions,
+} from "../init-dependency-versions.js"
 
 // ─── Options model ─────────────────────────────────────────────────────────--
 
@@ -200,9 +189,23 @@ export function registerInit(program: Command): void {
 
       if (name) mkdirSync(dir, { recursive: true })
 
-      scaffold(dir, result)
+      const deps = await resolveInitDependencyVersions()
+      const runningCli = cliPackageVersion()
+      if (deps.cli !== runningCli || deps.types !== runningCli) {
+        info(
+          `Using published npm versions: @supatype/cli ^${deps.cli}, @supatype/types ^${deps.types}`,
+        )
+      }
+
+      scaffold(dir, result, deps)
+
+      const installOk = doInstall ? runInstall(dir, result.packageManager) : true
+
+      const binariesReady = installOk ? await ensureInitBinaries(dir) : false
+      if (doInstall && !installOk) {
+        warn("Skipping component binary check until dependencies install successfully.")
+      }
 
-      if (doInstall) runInstall(dir, result.packageManager)
       const keysGenerated = doKeys ? writeKeys(dir) : false
 
       warnDockerUnavailableForProvider(result.provider)
@@ -210,8 +213,9 @@ export function registerInit(program: Command): void {
       printNextSteps({
         name,
         result,
-        installed: doInstall,
+        installed: doInstall && installOk,
         keysGenerated,
+        binariesReady,
       })
     })
 }
@@ -222,6 +226,7 @@ async function runWizard(
   defaultName: string,
   defaultTarget: ProductionTarget,
 ): Promise<WizardResult> {
+  return runClackFlow(async () => {
   p.intro("Create a new Supatype project")
 
   const projectName = ensureNotCancelled(
@@ -407,6 +412,7 @@ async function runWizard(
     generateKeys,
     ...(adminEmail && adminPassword ? { adminEmail, adminPassword } : {}),
   }
+  })
 }
 
 async function promptApp(): Promise<ScaffoldAppOptions> {
@@ -485,7 +491,7 @@ function detectInvokingPackageManager(): PackageManager {
   return "npm"
 }
 
-function runInstall(dir: string, pm: PackageManager): void {
+function runInstall(dir: string, pm: PackageManager): boolean {
   info(`Installing dependencies with ${pm}...`)
   const res = spawnSync(pm, ["install"], {
     cwd: dir,
@@ -494,6 +500,29 @@ function runInstall(dir: string, pm: PackageManager): void {
   })
   if (res.status !== 0 || res.error) {
     warn(`Dependency install did not complete (run "${pm} install" manually).`)
+    return false
+  }
+  return true
+}
+
+async function ensureInitBinaries(dir: string): Promise<boolean> {
+  const previousCwd = process.cwd()
+  try {
+    process.chdir(dir)
+    const config = loadConfig(dir)
+    const result = await ensureComponentBinaries(config, dir)
+    if (!result.ok) {
+      reportComponentBinaryFailures(result.failures)
+      return false
+    }
+    return true
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err)
+    warn(`Could not verify component binaries: ${message}`)
+    warn("Run manually from your project directory: supatype update")
+    return false
+  } finally {
+    process.chdir(previousCwd)
   }
 }
 
@@ -508,7 +537,11 @@ function writeKeys(dir: string): boolean {
 
 // ─── Scaffold ──────────────────────────────────────────────────────────────--
 
-function scaffold(dir: string, optsOrName: ScaffoldOptions | string): void {
+export function scaffold(
+  dir: string,
+  optsOrName: ScaffoldOptions | string,
+  deps: InitDependencyVersions = initDependencyVersionsFallback(),
+): void {
   const opts =
     typeof optsOrName === "string" ? defaultScaffoldOptions(optsOrName) : optsOrName
   const write = (rel: string, content: string) => {
@@ -520,9 +553,17 @@ function scaffold(dir: string, optsOrName: ScaffoldOptions | string): void {
 
   const pkgPath = join(dir, "package.json")
   if (!existsSync(pkgPath)) {
-    write("package.json", packageJsonTemplate(opts, cliPackageVersion()))
+    write("package.json", packageJsonTemplate(opts, deps))
   } else {
-    file("skipped", "package.json (already exists)")
+    try {
+      const existing = JSON.parse(readFileSync(pkgPath, "utf8")) as Record<string, unknown>
+      const merged = mergeSupatypePackageJson(existing, opts, deps)
+      writeFileSync(pkgPath, `${JSON.stringify(merged, null, 2)}\n`, "utf8")
+      file("updated", "package.json (added Supatype dependencies)")
+    } catch {
+      warn("Could not merge into package.json — add @supatype/cli and @supatype/types manually.")
+      file("skipped", "package.json (invalid JSON)")
+    }
   }
 
   write("supatype.config.ts", tsConfigTemplate(opts))
@@ -565,8 +606,13 @@ function scaffoldAppAssets(
 
   if (opts.app.mode === "static") {
     const staticRel = staticDirRelative(opts.app.staticDir)
+    if (opts.app.viteDevUrl && opts.productionTarget !== "later") {
+      write("dist/index.html", holding)
+      scaffoldVite(opts, write, holding)
+      return
+    }
     write(`${staticRel}/index.html`, holding)
-    if (hasVite) scaffoldVite(opts, write, holding)
+    if (opts.app.viteDevUrl) scaffoldVite(opts, write, holding)
     return
   }
 
@@ -609,7 +655,7 @@ function scaffoldHelloFunction(
 
 // ─── Templates ───────────────────────────────────────────────────────────────
 
-function packageJsonTemplate(opts: ScaffoldOptions, cliVersion: string): string {
+function packageJsonTemplate(opts: ScaffoldOptions, deps: InitDependencyVersions): string {
   const scripts: string[] = [
     `    "dev": "supatype dev"`,
     `    "push": "supatype push"`,
@@ -633,8 +679,8 @@ function packageJsonTemplate(opts: ScaffoldOptions, cliVersion: string): string
 ${scripts.join(",\n")}
   },
   "dependencies": {
-    "@supatype/cli": "^${cliVersion}",
-    "@supatype/types": "^${cliVersion}"
+    "@supatype/cli": "^${deps.cli}",
+    "@supatype/types": "^${deps.types}"
   },
   "devDependencies": {
 ${devDeps.join(",\n")}
@@ -701,20 +747,49 @@ function localConfigTemplate(app: ScaffoldAppOptions): string {
     `const localConfig: Partial<SupatypeConfig> = {`,
     `  server: { mode: "dev" },`,
   ]
-  if (app.mode === "proxy") {
-    lines.push(`  app: {`)
-    lines.push(`    mode: "proxy",`)
-    lines.push(`    upstream: "${app.upstream ?? "http://localhost:3000"}",`)
-    lines.push(`    start: "${app.start ?? "dev"}",`)
-    if (app.viteDevUrl) lines.push(`    vite_dev_url: "${app.viteDevUrl}",`)
-    lines.push(`  },`)
+  const localApp = localDevAppConfigLines(app)
+  if (localApp.length > 0) {
+    lines.push(...localApp)
   }
   lines.push(`}`, ``, `export default localConfig`, ``)
   return lines.join("\n")
 }
 
+/** App block for supatype.local.config.ts (proxy + Vite during local dev). */
+function localDevAppConfigLines(app: ScaffoldAppOptions): string[] {
+  if (app.mode === "proxy") {
+    return [
+      `  app: {`,
+      `    mode: "proxy",`,
+      `    upstream: "${app.upstream ?? "http://localhost:3000"}",`,
+      `    start: "${app.start ?? "dev"}",`,
+      ...(app.viteDevUrl ? [`    vite_dev_url: "${app.viteDevUrl}",`] : []),
+      `  },`,
+    ]
+  }
+  if (app.viteDevUrl) {
+    return [
+      `  app: {`,
+      `    mode: "proxy",`,
+      `    upstream: "${app.viteDevUrl}",`,
+      `    start: "vite",`,
+      `    vite_dev_url: "${app.viteDevUrl}",`,
+      `  },`,
+    ]
+  }
+  return []
+}
+
 function appConfigLines(app: ScaffoldAppOptions, productionTarget: ProductionTarget): string[] {
   if (app.mode === "static") {
+    if (productionTarget !== "later" && app.viteDevUrl) {
+      return [
+        `  app: {`,
+        `    mode: "static",`,
+        `    static_dir: "./dist",  // production build output`,
+        `  },`,
+      ]
+    }
     const out = [
       `  app: {`,
       `    mode: "static",`,
@@ -774,7 +849,7 @@ function holdingPageTemplate(projectName: string): string {
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>${name} — Supatype</title>
-    <meta name="description" content="A Supatype project. Define your types — we generate your backend." />
+    <meta name="description" content="A Supatype project. Define your types — we generate your platform." />
     <link rel="preconnect" href="https://fonts.googleapis.com" />
     <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
     <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet" />
@@ -909,6 +984,8 @@ export default defineConfig({
     host: "127.0.0.1",
     port: ${port},
     strictPort: true,
+    // Docker Compose app proxy reaches the host as host.docker.internal.
+    allowedHosts: ["127.0.0.1", "localhost", "host.docker.internal"],
   },
 })
 `
@@ -1185,11 +1262,13 @@ function printNextSteps(args: {
   result: WizardResult
   installed: boolean
   keysGenerated: boolean
+  binariesReady: boolean
 }): void {
-  const { name, result, installed, keysGenerated } = args
+  const { name, result, installed, keysGenerated, binariesReady } = args
   const steps: string[] = []
   if (name) steps.push(`cd ${name}`)
   if (!installed) steps.push(`${result.packageManager} install`)
+  if (!binariesReady) steps.push("supatype update        # download component binaries")
   if (!keysGenerated) steps.push("supatype keys")
   const kongHint =
     result.provider === "docker" && result.kongPort !== undefined

package/src/commands/link-helpers.ts

@@ -12,7 +12,7 @@ import { targetFetch } from "../target-client.js"
 import { error, info, plain } from "../ui/messages.js"
 import { nextSteps } from "../ui/next-steps.js"
 import { isInteractive } from "../ui/interactive.js"
-import { ensureNotCancelled, printLogo, clack as p } from "../ui/prompts.js"
+import { ensureNotCancelled, p, runClackFlow } from "../ui/prompts.js"
 
 function resolveLinkToken(opts: {
   token?: string
@@ -145,35 +145,36 @@ export async function runLinkAction(opts: {
   let url = opts.url
 
   if (isInteractive() && !project && !url) {
-    printLogo()
-    p.intro("Link this project")
-    const targetKind = ensureNotCancelled(
-      await p.select<"cloud" | "self-host">({
-        message: "Link target",
-        options: [
-          { value: "cloud", label: "Supatype Cloud", hint: "managed project on supatype.com" },
-          { value: "self-host", label: "Self-host", hint: "your Kong gateway URL" },
-        ],
-      }),
-    )
-    if (targetKind === "cloud") {
-      project = ensureNotCancelled(
-        await p.text({
-          message: "Cloud project slug",
-          placeholder: projectRef,
-          defaultValue: projectRef,
+    await runClackFlow(async () => {
+      p.intro("Link this project")
+      const targetKind = ensureNotCancelled(
+        await p.select<"cloud" | "self-host">({
+          message: "Link target",
+          options: [
+            { value: "cloud", label: "Supatype Cloud", hint: "managed project on supatype.com" },
+            { value: "self-host", label: "Self-host", hint: "your Kong gateway URL" },
+          ],
         }),
-      ).trim()
-    } else {
-      url = ensureNotCancelled(
-        await p.text({
-          message: "Kong gateway URL",
-          placeholder: "https://api.example.com",
-          defaultValue: "http://localhost:18473",
-        }),
-      ).trim()
-    }
-    p.outro("Linking...")
+      )
+      if (targetKind === "cloud") {
+        project = ensureNotCancelled(
+          await p.text({
+            message: "Cloud project slug",
+            placeholder: projectRef,
+            defaultValue: projectRef,
+          }),
+        ).trim()
+      } else {
+        url = ensureNotCancelled(
+          await p.text({
+            message: "Kong gateway URL",
+            placeholder: "https://api.example.com",
+            defaultValue: "http://localhost:18473",
+          }),
+        ).trim()
+      }
+      p.outro("Linking...")
+    })
   }
 
   const token = resolveLinkToken(opts)

package/src/compose-local-server-image.ts

@@ -0,0 +1,68 @@
+import { existsSync } from "node:fs"
+import { dirname, isAbsolute, join, resolve } from "node:path"
+import { spawnSync } from "node:child_process"
+import { VERSION_PIN_LOCAL } from "./binary-cache.js"
+import { appendStackOutput, getActiveDevSession } from "./dev-session.js"
+import { requireDockerDaemon } from "./docker-runtime.js"
+import type { SupatypeProjectConfig } from "./project-config.js"
+
+/** Docker tag for compose dev when `versions.server` is `local`. */
+export const LOCAL_SERVER_DOCKER_IMAGE = "supatype/server:local-dev"
+
+/** Find the server repo root (directory containing `Dockerfile`) from an overrides.server binary path. */
+export function resolveServerSourceRoot(serverOverride: string, cwd: string): string | null {
+  const binaryPath = isAbsolute(serverOverride) ? serverOverride : resolve(cwd, serverOverride)
+  let dir = dirname(binaryPath)
+  for (let depth = 0; depth < 5; depth++) {
+    if (existsSync(join(dir, "Dockerfile"))) return dir
+    const parent = dirname(dir)
+    if (parent === dir) break
+    dir = parent
+  }
+  return null
+}
+
+/**
+ * When `versions.server` is `local`, build a Linux server image from the source tree
+ * next to `overrides.server` so compose dev matches the contributor's binary.
+ */
+export async function ensureLocalServerDockerImage(
+  cwd: string,
+  config: SupatypeProjectConfig,
+  brand?: { intro?: string },
+): Promise<string | undefined> {
+  if (config.versions?.server !== VERSION_PIN_LOCAL) return undefined
+
+  const override = config.overrides?.server?.trim()
+  if (!override) return undefined
+
+  const root = resolveServerSourceRoot(override, cwd)
+  if (!root) {
+    console.warn(
+      `[supatype] ⚠  versions.server is "local" but no Dockerfile found near ${override}. ` +
+        "Compose will use the default supatype/server:latest image.",
+    )
+    return undefined
+  }
+
+  requireDockerDaemon(brand?.intro ? { brand: { intro: brand.intro } } : undefined)
+  const dockerfile = join(root, "Dockerfile")
+  console.log(`[supatype] Building local server Docker image from ${root}…`)
+  const result = spawnSync(
+    "docker",
+    ["build", "--progress=plain", "-t", LOCAL_SERVER_DOCKER_IMAGE, "-f", dockerfile, root],
+    { encoding: "utf8", stdio: "pipe" },
+  )
+  const tui = getActiveDevSession()?.isTui() ?? false
+  if (!tui) {
+    appendStackOutput(result.stdout, "log")
+    appendStackOutput(result.stderr, result.status === 0 ? "log" : "error")
+  } else if (result.status !== 0) {
+    appendStackOutput(result.stderr || result.stdout || "docker build failed", "error")
+  }
+  if (result.status !== 0) {
+    throw new Error(`docker build failed for local server (exit ${result.status ?? "unknown"})`)
+  }
+  console.log(`[supatype] Local server image ready: ${LOCAL_SERVER_DOCKER_IMAGE}`)
+  return LOCAL_SERVER_DOCKER_IMAGE
+}