@supatype/cli 0.1.0 → 0.1.1

package/src/commands/init.ts

@@ -52,6 +52,8 @@ export interface ScaffoldOptions {
   projectName: string
   /** Local development runtime (docker recommended). */
   provider: "docker" | "native"
+  /** Host Kong port when provider is docker (unique per project). */
+  kongPort?: number
   productionTarget: ProductionTarget
   domain?: string
   /** ACME contact email for Let's Encrypt HTTPS (self-host + domain). */
@@ -64,6 +66,9 @@ export interface ScaffoldOptions {
   /** Object storage when deployed to production. */
   storageProduction: "local" | "s3"
   helloFunction: boolean
+  /** When set, written to .env for first dev/push to create the admin panel user. */
+  adminEmail?: string
+  adminPassword?: string
 }
 
 type StorageProvider = ScaffoldOptions["storageLocal"]
@@ -126,6 +131,9 @@ interface InitCliOptions {
   defaults?: boolean
   install: boolean
   keys: boolean
+  adminEmail?: string
+  adminPassword?: string
+  admin?: boolean
 }
 
 export function registerInit(program: Command): void {
@@ -140,6 +148,9 @@ export function registerInit(program: Command): void {
     .option("-y, --defaults", "Skip all prompts and use sensible defaults")
     .option("--no-install", "Do not run the package manager install step")
     .option("--no-keys", "Do not generate ANON_KEY / SERVICE_ROLE_KEY")
+    .option("--admin-email <email>", "First admin panel user email (written to .env)")
+    .option("--admin-password <password>", "First admin panel user password (written to .env)")
+    .option("--no-admin", "Do not configure a first admin user")
     .action(async (name: string | undefined, opts: InitCliOptions) => {
       const dir = name ? resolve(process.cwd(), name) : process.cwd()
 
@@ -164,6 +175,23 @@ export function registerInit(program: Command): void {
           install: true,
           generateKeys: true,
         }
+        if (result.provider === "docker") {
+          const { findNextFreePort } = await import("../dev-ports.js")
+          const { COMPOSE_DEV_KONG_PORT } = await import("../project-config.js")
+          result.kongPort = await findNextFreePort(COMPOSE_DEV_KONG_PORT)
+        }
+        if (!opts.admin && opts.adminEmail && opts.adminPassword) {
+          result.adminEmail = opts.adminEmail
+          result.adminPassword = opts.adminPassword
+        }
+      }
+
+      if (opts.admin === false) {
+        delete result.adminEmail
+        delete result.adminPassword
+      } else if (opts.adminEmail && opts.adminPassword) {
+        result.adminEmail = opts.adminEmail
+        result.adminPassword = opts.adminPassword
       }
 
       // CLI flags override wizard / default action choices.
@@ -262,6 +290,12 @@ async function runWizard(
     }),
   )
 
+  let kongPort: number | undefined
+  if (provider === "docker") {
+    const { promptKongPortChoice } = await import("../dev-ports.js")
+    kongPort = await promptKongPortChoice()
+  }
+
   const schemaPath = ensureNotCancelled(
     await p.text({
       message: "Where should your schema live?",
@@ -322,11 +356,43 @@ async function runWizard(
     }),
   )
 
+  let adminEmail: string | undefined
+  let adminPassword: string | undefined
+  const createAdmin = ensureNotCancelled(
+    await p.confirm({
+      message: "Create an admin user for /admin?",
+      initialValue: true,
+    }),
+  )
+  if (createAdmin) {
+    adminEmail =
+      ensureNotCancelled(
+        await p.text({
+          message: "Admin email",
+          placeholder: "you@example.com",
+          defaultValue: "",
+        }),
+      ).trim() || undefined
+    if (adminEmail) {
+      adminPassword =
+        ensureNotCancelled(
+          await p.text({
+            message: "Admin password (min 8 chars)",
+            defaultValue: "",
+          }),
+        ).trim() || undefined
+      if (adminPassword && adminPassword.length < 8) {
+        adminPassword = undefined
+      }
+    }
+  }
+
   p.outro("Setting up your project...")
 
   return {
     projectName,
     provider,
+    ...(kongPort !== undefined ? { kongPort } : {}),
     productionTarget,
     ...(domain !== undefined ? { domain } : {}),
     ...(tlsEmail !== undefined ? { tlsEmail } : {}),
@@ -339,6 +405,7 @@ async function runWizard(
     packageManager,
     install,
     generateKeys,
+    ...(adminEmail && adminPassword ? { adminEmail, adminPassword } : {}),
   }
 }
 
@@ -910,9 +977,27 @@ SERVICE_ROLE_KEY=`)
   sections.push(`# Site URL (used by GoTrue for email redirects)
 SITE_URL=http://localhost:3000`)
 
+  if (opts.provider === "docker" && opts.kongPort !== undefined) {
+    const apiUrl = `http://localhost:${opts.kongPort}`
+    sections.push(
+      `# Local API gateway (Kong) — unique per project so multiple stacks can run concurrently
+SUPATYPE_KONG_PORT=${opts.kongPort}
+PUBLIC_SUPATYPE_URL=${apiUrl}
+API_EXTERNAL_URL=${apiUrl}`,
+    )
+  }
+
   sections.push(emailEnvSection(opts.email, opts.projectName))
   sections.push(storageEnvSections(opts.storageLocal, opts.storageProduction))
 
+  if (opts.adminEmail && opts.adminPassword) {
+    sections.push(
+      `# First admin for /admin — consumed on first supatype dev or push (password removed after use)
+SUPATYPE_ADMIN_EMAIL=${opts.adminEmail}
+SUPATYPE_ADMIN_PASSWORD=${opts.adminPassword}`,
+    )
+  }
+
   sections.push(
     `# Self-host compose uses the same DATABASE_URL when Postgres is published on localhost:5432`,
   )
@@ -1106,8 +1191,15 @@ function printNextSteps(args: {
   if (name) steps.push(`cd ${name}`)
   if (!installed) steps.push(`${result.packageManager} install`)
   if (!keysGenerated) steps.push("supatype keys")
-  steps.push("supatype dev          # Docker Compose stack (Kong :18473)")
+  const kongHint =
+    result.provider === "docker" && result.kongPort !== undefined
+      ? `supatype dev          # Docker Compose stack (Kong :${result.kongPort})`
+      : "supatype dev          # Docker Compose stack (Kong :18473)"
+  steps.push(kongHint)
   steps.push("supatype push         # apply schema + generate types")
+  if (result.adminEmail) {
+    steps.push("                      # first admin user is created on dev or push")
+  }
   if (result.helloFunction) {
     steps.push("supatype functions serve   # run edge functions locally")
   }

package/src/commands/push.ts

@@ -8,7 +8,7 @@ import { printDiffOperations, printDiffWarnings } from "../diff-output.js"
 import { signJwt } from "../jwt.js"
 import { provisionBucketsFromAst } from "../storage-provision.js"
 import type { ExtractedSchemaAstV2 } from "../schema-ast-v2.js"
-import { promptFirstAdminUser } from "./admin.js"
+import { ensureFirstAdminUser } from "./admin.js"
 import { withAdminRoles } from "../studio-admin-roles.js"
 import { restoreSystemRelationTargets } from "../restore-system-relation-targets.js"
 import type { SupatypeProjectConfig } from "../project-config.js"
@@ -145,8 +145,8 @@ async function pushViaTarget(
 
   if (target.mode === "direct" || target.mode === "local") {
     await writeLocalAdminConfig(ast, config)
-    if (ops.length > 0 && target.databaseUrl) {
-      await promptFirstAdminUser(target.databaseUrl)
+    if (target.databaseUrl) {
+      await ensureFirstAdminUser(target.databaseUrl, { cwd })
     }
     await generateTypesLocal(ast, config)
     await provisionLocalStorage(ast, config)

package/src/compose-rename.ts

@@ -0,0 +1,76 @@
+/**
+ * Detect and clean up Docker Compose state when `project.name` changes.
+ */
+
+import { existsSync, readFileSync } from "node:fs"
+import { join } from "node:path"
+import * as p from "@clack/prompts"
+import { loadLocalEnvironment } from "./link.js"
+import { composeStackHasContainers } from "./dev-session-lock.js"
+import { composeProjectName, runDockerCompose, type SelfHostComposePaths } from "./self-host-compose.js"
+import { isInteractive } from "./ui/interactive.js"
+import { warn } from "./ui/messages.js"
+
+/**
+ * When `project.name` changes, the compose project slug changes too (`supatype-{name}`).
+ * Offer to stop containers from the previous slug so volumes/ports do not linger.
+ */
+export async function handleComposeProjectRename(
+  cwd: string,
+  currentProjectName: string,
+  paths: SelfHostComposePaths,
+): Promise<void> {
+  const local = loadLocalEnvironment(cwd)
+  const previousRef = local?.projectRef?.trim()
+  if (!previousRef || previousRef === currentProjectName) return
+
+  const previousCompose = composeProjectName(previousRef)
+  const currentCompose = composeProjectName(currentProjectName)
+  if (previousCompose === currentCompose) return
+  if (!composeStackHasContainers(previousCompose)) return
+
+  const message =
+    `Project renamed from "${previousRef}" to "${currentProjectName}".\n` +
+    `Docker stack "${previousCompose}" may still be running.`
+
+  if (!isInteractive()) {
+    warn(message)
+    warn(`Stop it manually: docker compose -p ${previousCompose} down`)
+    return
+  }
+
+  const stopOld = await p.confirm({
+    message: `${message}\n\nStop the old Docker stack now?`,
+    initialValue: true,
+  })
+
+  if (p.isCancel(stopOld) || !stopOld) {
+    warn(`Leaving "${previousCompose}" running. Stop it with: docker compose -p ${previousCompose} down`)
+    return
+  }
+
+  const status = runDockerCompose(paths.composePath, ["down"], cwd, previousCompose, { quiet: true })
+  if (status === 0) {
+    p.log.success(`Stopped old stack "${previousCompose}".`)
+    warnIfHardcodedComposeScripts(cwd, previousCompose)
+  } else {
+    warn(`Could not stop "${previousCompose}" (exit ${status}). Try: docker compose -p ${previousCompose} down`)
+  }
+}
+
+function warnIfHardcodedComposeScripts(cwd: string, oldComposeProject: string): void {
+  const pkgPath = join(cwd, "package.json")
+  if (!existsSync(pkgPath)) return
+  try {
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf8")) as { scripts?: Record<string, string> }
+    const scripts = Object.values(pkg.scripts ?? {}).join("\n")
+    if (scripts.includes(`-p ${oldComposeProject}`)) {
+      warn(
+        `package.json scripts still reference compose project "${oldComposeProject}". ` +
+          "Update them if you renamed project.name in supatype.config.ts.",
+      )
+    }
+  } catch {
+    // ignore invalid package.json
+  }
+}

package/src/dev-compose.ts

@@ -2,7 +2,7 @@
  * `supatype dev` when `provider: docker` — full self-host Compose stack (Kong gateway).
  */
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
+import { existsSync, mkdirSync, writeFileSync } from "node:fs"
 import { homedir } from "node:os"
 import { dirname, join, resolve } from "node:path"
 import { spawnSync } from "node:child_process"
@@ -17,7 +17,10 @@ import {
   type SupatypeProjectConfig,
 } from "./project-config.js"
 import { signJwt } from "./jwt.js"
-import { isPortInUse } from "./postgres-ctl.js"
+import { ensureDevDbPort, ensureKongPort } from "./dev-ports.js"
+import { handleComposeProjectRename } from "./compose-rename.js"
+import { recoverStaleDevSession, writeDevSessionLock } from "./dev-session-lock.js"
+import { readEnvValue, upsertEnvFile } from "./env-file.js"
 import {
   COMPOSE_PINNED_IMAGE_ENV_KEYS,
   composeDockerImageEnv,
@@ -46,6 +49,7 @@ import { withAdminRoles } from "./studio-admin-roles.js"
 import { restoreSystemRelationTargets } from "./restore-system-relation-targets.js"
 import { provisionBucketsFromAst } from "./storage-provision.js"
 import type { ExtractedSchemaAstV2 } from "./schema-ast-v2.js"
+import { ensureFirstAdminUserForProject } from "./commands/admin.js"
 
 const LOCAL_JWT_SECRET = "super-secret-jwt-token-with-at-least-32-characters-long"
 
@@ -70,30 +74,12 @@ export function composeDbUrl(): string {
 
 /**
  * Resolve the host Kong port for this project. Persisted in `.env` as
- * SUPATYPE_KONG_PORT so re-runs are stable; on first run it picks the default
- * (18473) or the next free port, so multiple projects can run concurrently.
+ * SUPATYPE_KONG_PORT; prompts when the configured port is already taken.
  */
 async function resolveDevDbPort(cwd: string): Promise<number> {
-  const envPath = join(cwd, ".env")
-  if (existsSync(envPath)) {
-    const m = readFileSync(envPath, "utf8").match(/^SUPATYPE_DEV_DB_PORT=(\d+)/m)
-    if (m && m[1]) return Number(m[1])
-  }
-  let port = COMPOSE_DEV_DB_PORT
-  while (await isPortInUse(port)) port++
-  return port
+  return ensureDevDbPort(cwd)
 }
 
-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
-}
-
-/** Postgres DSN for compose db when published to the host (local engine push). */
 function hostComposeDbUrl(cwd: string): string {
   const port = readEnvValue(cwd, "SUPATYPE_DEV_DB_PORT", String(COMPOSE_DEV_DB_PORT))
   const user = readEnvValue(cwd, "POSTGRES_USER", "supatype_admin")
@@ -175,36 +161,10 @@ export async function resolveHostEngineDatabaseUrl(
 }
 
 async function resolveKongPort(cwd: string): Promise<number> {
-  const envPath = join(cwd, ".env")
-  if (existsSync(envPath)) {
-    const m = readFileSync(envPath, "utf8").match(/^SUPATYPE_KONG_PORT=(\d+)/m)
-    if (m && m[1]) return Number(m[1])
-  }
-  let port = COMPOSE_DEV_KONG_PORT
-  while (await isPortInUse(port)) port++
-  return port
+  return ensureKongPort(cwd, { context: "dev" })
 }
 
-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")
-}
-
-/** Keep compose + Studio on the same freshly signed dev JWTs; sync optional image pins from config. */
-function ensureDevComposeEnv(
+function upsertDevComposeEnv(
   cwd: string,
   config: SupatypeProjectConfig,
   anonKey: string,
@@ -222,6 +182,7 @@ function ensureDevComposeEnv(
     ANON_KEY: anonKey,
     SERVICE_ROLE_KEY: serviceRoleKey,
     PUBLIC_SUPATYPE_ANON_KEY: anonKey,
+    VITE_SUPATYPE_ANON_KEY: anonKey,
     PUBLIC_SUPATYPE_URL: apiUrl,
     SUPATYPE_KONG_PORT: String(kongPort),
     API_EXTERNAL_URL: apiUrl,
@@ -238,6 +199,18 @@ function ensureDevComposeEnv(
   upsertEnvFile(cwd, updates, removeImageKeys)
 }
 
+/** Keep compose + Studio on the same freshly signed dev JWTs; sync optional image pins from config. */
+function ensureDevComposeEnv(
+  cwd: string,
+  config: SupatypeProjectConfig,
+  anonKey: string,
+  serviceRoleKey: string,
+  kongPort: number,
+  devDbPort?: number,
+): void {
+  upsertDevComposeEnv(cwd, config, anonKey, serviceRoleKey, kongPort, devDbPort)
+}
+
 async function waitComposeHealthy(paths: SelfHostComposePaths, cwd: string, maxMs: number, composeProject: string): Promise<void> {
   const composeDir = dirname(paths.composePath)
   const envFile = join(cwd, ".env")
@@ -670,6 +643,10 @@ export async function pushSchemaDocker(cwd: string, config: SupatypeProjectConfi
   await waitKongReady(kongPort, 120)
   await provisionDockerStorageBuckets(ast, kongPort, serviceRoleKey)
 
+  await ensureFirstAdminUserForProject(cwd, config, {
+    compose: { project, composePath: paths.composePath },
+  })
+
   console.log("[supatype] Schema pushed.")
 }
 
@@ -693,6 +670,8 @@ export async function runDevCompose(cwd: string, config: SupatypeProjectConfig,
 
   console.log(`[supatype] provider: docker — starting self-host Compose stack (project ${project}, gateway :${kongPort})...`)
   const paths = writeSelfHostCompose(cwd, config, { devLocal: true })
+  await recoverStaleDevSession(cwd)
+  await handleComposeProjectRename(cwd, config.project.name, paths)
   const devBrand = { intro: "Local development" }
 
   const upStatus = runDockerCompose(paths.composePath, ["up", "-d"], cwd, project, {
@@ -712,6 +691,10 @@ export async function runDevCompose(cwd: string, config: SupatypeProjectConfig,
     console.error("[supatype] Initial schema push failed:", (e as Error).message),
   )
 
+  await ensureFirstAdminUserForProject(cwd, config, {
+    compose: { project, composePath: paths.composePath },
+  })
+
   console.log("[supatype] Waiting for API gateway...")
   await waitKongReady(kongPort, 120)
 
@@ -724,6 +707,14 @@ export async function runDevCompose(cwd: string, config: SupatypeProjectConfig,
     provider: "docker",
   })
 
+  writeDevSessionLock(cwd, {
+    composeProject: project,
+    projectRef: config.project.name,
+    composePath: paths.composePath,
+    kongPort,
+    startedAt: new Date().toISOString(),
+  })
+
   const ast = loadSchemaAst(schemaPath, cwd)
   await provisionDockerStorageBuckets(ast, kongPort, serviceRoleKey)
 
@@ -785,6 +776,9 @@ export async function runDevCompose(cwd: string, config: SupatypeProjectConfig,
     } else {
       console.warn(`[supatype] Compose down exited with status ${downStatus}.`)
     }
+  }, {
+    cwd,
+    compose: { cwd, composePath: paths.composePath, composeProject: project },
   })
 
   if (opts.watch) {

package/src/dev-ports.ts

@@ -0,0 +1,212 @@
+/**
+ * Kong / Postgres host port resolution for local Docker dev.
+ * Persists SUPATYPE_KONG_PORT in `.env` so re-runs are stable, but re-checks
+ * availability so multiple projects and port collisions are surfaced clearly.
+ */
+
+import * as p from "@clack/prompts"
+import { COMPOSE_DEV_KONG_PORT } from "./project-config.js"
+import { isPortInUse } from "./postgres-ctl.js"
+import { readEnvInt, upsertEnvFile } from "./env-file.js"
+import { isInteractive } from "./ui/interactive.js"
+import { fatalError } from "./ui/fatal.js"
+
+const MIN_PORT = 1024
+const MAX_PORT = 65535
+
+export function isValidHostPort(port: number): boolean {
+  return Number.isInteger(port) && port >= MIN_PORT && port <= MAX_PORT
+}
+
+export function parseHostPortInput(raw: string): number | null {
+  const port = Number(raw.trim())
+  return isValidHostPort(port) ? port : null
+}
+
+/** Next free TCP port on 127.0.0.1 starting at `start`. */
+export async function findNextFreePort(start: number): Promise<number> {
+  let port = Math.max(MIN_PORT, start)
+  while (port <= MAX_PORT && (await isPortInUse(port))) port++
+  if (port > MAX_PORT) {
+    throw new Error(`No free local port found in range ${start}–${MAX_PORT}.`)
+  }
+  return port
+}
+
+export function readPersistedKongPort(cwd: string): number | null {
+  return readEnvInt(cwd, "SUPATYPE_KONG_PORT")
+}
+
+function persistKongPort(cwd: string, port: number): void {
+  const apiUrl = `http://localhost:${port}`
+  upsertEnvFile(cwd, {
+    SUPATYPE_KONG_PORT: String(port),
+    PUBLIC_SUPATYPE_URL: apiUrl,
+    API_EXTERNAL_URL: apiUrl,
+    SITE_URL: apiUrl,
+  })
+}
+
+async function promptPortConflict(
+  cwd: string,
+  blockedPort: number,
+  reason: "in_use" | "init",
+): Promise<number> {
+  const port = await promptPortConflictWithoutPersist(blockedPort, reason)
+  persistKongPort(cwd, port)
+  return port
+}
+
+export interface EnsureKongPortOptions {
+  /** When false, fail fast instead of prompting (CI / scripts). */
+  interactive?: boolean
+  /** init wizard — slightly different copy */
+  context?: "dev" | "init"
+}
+
+/**
+ * Resolve the Kong host port for this project directory.
+ * - Uses `.env` when set and available.
+ * - Prompts (or errors) when the configured port is taken.
+ * - Auto-picks the next free port on first run when unset.
+ */
+export async function ensureKongPort(
+  cwd: string,
+  opts: EnsureKongPortOptions = {},
+): Promise<number> {
+  const interactive = opts.interactive ?? isInteractive()
+  const context = opts.context ?? "dev"
+  const persisted = readPersistedKongPort(cwd)
+
+  if (persisted !== null) {
+    if (!(await isPortInUse(persisted))) return persisted
+
+    if (!interactive) {
+      fatalError(`Port ${persisted} is already in use (SUPATYPE_KONG_PORT in .env).`, [
+        "Stop the other service or set a different SUPATYPE_KONG_PORT.",
+        "Run `supatype dev` in a terminal to pick a new port interactively.",
+      ])
+    }
+
+    return promptPortConflict(cwd, persisted, "in_use")
+  }
+
+  const preferred = COMPOSE_DEV_KONG_PORT
+  const port =
+    (await isPortInUse(preferred))
+      ? interactive && context === "init"
+        ? await promptPortConflict(cwd, preferred, "init")
+        : await findNextFreePort(preferred)
+      : preferred
+
+  return port
+}
+
+/** Wizard / init — pick a Kong port without writing `.env` (scaffold writes it). */
+export async function promptKongPortChoice(): Promise<number> {
+  const freeDefault = (await isPortInUse(COMPOSE_DEV_KONG_PORT))
+    ? await findNextFreePort(COMPOSE_DEV_KONG_PORT)
+    : COMPOSE_DEV_KONG_PORT
+
+  const value = await p.text({
+    message: "Local API gateway port (Kong)",
+    defaultValue: String(freeDefault),
+    placeholder: String(COMPOSE_DEV_KONG_PORT),
+    validate: (raw) => {
+      const port = parseHostPortInput(raw ?? "")
+      if (!port) return `Enter a port between ${MIN_PORT} and ${MAX_PORT}.`
+      return undefined
+    },
+  })
+
+  if (p.isCancel(value)) {
+    p.cancel("Cancelled.")
+    process.exit(0)
+  }
+
+  const port = parseHostPortInput(value)!
+  if (await isPortInUse(port)) {
+    return promptPortConflictWithoutPersist(port, "init")
+  }
+  return port
+}
+
+async function promptPortConflictWithoutPersist(
+  blockedPort: number,
+  reason: "in_use" | "init",
+): Promise<number> {
+  const suggested = await findNextFreePort(blockedPort + 1)
+  const headline =
+    reason === "init"
+      ? `Port ${blockedPort} is already in use on this machine.`
+      : `Port ${blockedPort} is in use — another Supatype project or service may already be bound to it.`
+
+  const choice = await p.select<"suggested" | "custom" | "cancel">({
+    message: headline,
+    options: [
+      {
+        value: "suggested",
+        label: `Use ${suggested} instead`,
+        hint: "next available port",
+      },
+      { value: "custom", label: "Enter a different port" },
+      { value: "cancel", label: "Cancel" },
+    ],
+  })
+
+  if (p.isCancel(choice) || choice === "cancel") {
+    p.cancel("Cancelled.")
+    process.exit(0)
+  }
+
+  if (choice === "suggested") return suggested
+
+  const custom = await p.text({
+    message: "Local API gateway port (Kong)",
+    defaultValue: String(suggested),
+    validate: (value) => {
+      const port = parseHostPortInput(value ?? "")
+      if (!port) return `Enter a port between ${MIN_PORT} and ${MAX_PORT}.`
+      return undefined
+    },
+  })
+
+  if (p.isCancel(custom)) {
+    p.cancel("Cancelled.")
+    process.exit(0)
+  }
+
+  const port = parseHostPortInput(custom)
+  if (!port) {
+    p.cancel("Invalid port.")
+    process.exit(1)
+  }
+
+  if (await isPortInUse(port)) {
+    fatalError(`Port ${port} is still in use.`, [
+      "Pick another port or stop the service using it.",
+      "Check Docker Desktop for other Supatype stacks.",
+    ])
+  }
+
+  return port
+}
+
+const COMPOSE_DEV_DB_PORT = 54329
+
+export async function ensureDevDbPort(cwd: string): Promise<number> {
+  const persisted = readEnvInt(cwd, "SUPATYPE_DEV_DB_PORT")
+  if (persisted !== null) {
+    if (!(await isPortInUse(persisted))) return persisted
+    const next = await findNextFreePort(persisted + 1)
+    upsertEnvFile(cwd, {
+      SUPATYPE_DEV_DB_PORT: String(next),
+      DATABASE_URL: `postgresql://supatype_admin:postgres@localhost:${next}/supatype?sslmode=disable`,
+    })
+    return next
+  }
+
+  let port = COMPOSE_DEV_DB_PORT
+  while (await isPortInUse(port)) port++
+  return port
+}