@supatype/cli 0.1.0 → 0.1.2

package/src/ui/runtime/run-clack-flow.tsx

@@ -0,0 +1,52 @@
+import React, { useRef } from "react"
+import { render } from "ink"
+import { isInteractive } from "../interactive.js"
+import { createClackApi, type ClackApi } from "../clack-api.js"
+import { FlowApp } from "../flows/FlowApp.js"
+
+interface RunClackFlowRootProps {
+  run: (api: ClackApi) => Promise<unknown>
+  onComplete: (value: unknown) => void
+  onError: (err: unknown) => void
+}
+
+function RunClackFlowRoot({ run, onComplete, onError }: RunClackFlowRootProps): React.ReactElement {
+  const started = useRef(false)
+
+  return (
+    <FlowApp
+      bind={(controller) => {
+        if (started.current) return
+        started.current = true
+        void run(createClackApi(controller))
+          .then(onComplete)
+          .catch(onError)
+      }}
+    />
+  )
+}
+
+/** Mount a single Ink flow session (init wizard, standalone confirm, etc.). */
+export async function runClackFlow<T>(run: (api: ClackApi) => Promise<T>): Promise<T> {
+  if (!isInteractive()) {
+    throw new Error("Interactive Ink flow requires a TTY.")
+  }
+
+  return new Promise<T>((resolve, reject) => {
+    const instance = render(
+      <RunClackFlowRoot
+        run={run as (api: ClackApi) => Promise<unknown>}
+        onComplete={(value) => {
+          instance.unmount()
+          resolve(value as T)
+        }}
+        onError={(err) => {
+          instance.unmount()
+          reject(err)
+        }}
+      />,
+    )
+  })
+}
+
+export { CLACK_CANCEL } from "./cancel.js"

package/src/ui/theme.ts

@@ -0,0 +1,41 @@
+/**
+ * Supatype terminal design tokens — shared by Ink components and plain CI output.
+ */
+
+export const RESET = "\x1b[0m"
+export const DIM = "\x1b[2m"
+export const BOLD = "\x1b[1m"
+
+export const theme = {
+  brand: "magenta" as const,
+  brandHex: "#c084fc",
+  info: "cyan" as const,
+  warn: "yellow" as const,
+  error: "red" as const,
+  success: "green" as const,
+  dim: "gray" as const,
+  muted: "gray" as const,
+} as const
+
+/** Legacy ANSI exports used by dev-logo / dev-task-colors. */
+export const BRAND_COLOR = "\x1b[35m"
+
+export function brandStyle(text: string): string {
+  return `${BRAND_COLOR}${BOLD}${text}${RESET}`
+}
+
+export function plainInfo(message: string): string {
+  return `${theme.info === "cyan" ? "\x1b[36m" : ""}ℹ ${message}${RESET}`
+}
+
+export function plainWarn(message: string): string {
+  return `\x1b[33m⚠ ${message}${RESET}`
+}
+
+export function plainError(message: string): string {
+  return `\x1b[31m✗ ${message}${RESET}`
+}
+
+export function plainSuccess(message: string): string {
+  return `\x1b[32m✓ ${message}${RESET}`
+}

package/src/valkey-sidecar.ts

@@ -0,0 +1,126 @@
+/**
+ * Lightweight Valkey container for native `supatype dev` (REST response cache).
+ */
+
+import { spawnSync } from "node:child_process"
+import { createConnection } from "node:net"
+
+const DEFAULT_HOST = "127.0.0.1"
+const DEFAULT_PORT = 6379
+const IMAGE = "valkey/valkey:8-alpine"
+
+function containerName(projectName: string): string {
+  const safe = projectName.replace(/[^a-zA-Z0-9_-]/g, "-").slice(0, 48)
+  return `supatype-valkey-dev-${safe}`
+}
+
+function dockerAvailable(): boolean {
+  const r = spawnSync("docker", ["info"], { stdio: "ignore" })
+  return r.status === 0
+}
+
+function isAddrReachable(host: string, port: number, timeoutMs = 800): boolean {
+  try {
+    const r = spawnSync(
+      process.execPath,
+      [
+        "-e",
+        `const n=require('net');const s=n.createConnection({host:${JSON.stringify(host)},port:${port}});` +
+          `s.on('connect',()=>{s.end();process.exit(0)});s.on('error',()=>process.exit(1));` +
+          `setTimeout(()=>process.exit(1),${timeoutMs})`,
+      ],
+      { stdio: "ignore" },
+    )
+    return r.status === 0
+  } catch {
+    return false
+  }
+}
+
+function sleepMs(ms: number): void {
+  const end = Date.now() + ms
+  while (Date.now() < end) {
+    /* spin */
+  }
+}
+
+export interface ValkeySidecarResult {
+  addr: string
+  containerName: string | null
+  started: boolean
+}
+
+/**
+ * Ensure Valkey is reachable at 127.0.0.1:6379 for native dev.
+ * Starts a named Docker container when Docker is available and nothing is listening.
+ */
+export function ensureValkeySidecar(projectName: string): ValkeySidecarResult {
+  const envAddr = process.env["SUPATYPE_VALKEY_ADDR"]?.trim()
+  if (envAddr) {
+    return { addr: envAddr, containerName: null, started: false }
+  }
+
+  const addr = `${DEFAULT_HOST}:${DEFAULT_PORT}`
+
+  if (isAddrReachable(DEFAULT_HOST, DEFAULT_PORT)) {
+    return { addr, containerName: null, started: false }
+  }
+
+  if (!dockerAvailable()) {
+    console.warn(
+      "[supatype] ⚠  Valkey not available (Docker not running). " +
+        "REST server cache (`cache({ server: true })`) will bypass until Valkey is reachable.",
+    )
+    return { addr: "", containerName: null, started: false }
+  }
+
+  const name = containerName(projectName)
+  spawnSync("docker", ["rm", "-f", name], { stdio: "ignore" })
+
+  const run = spawnSync(
+    "docker",
+    ["run", "-d", "--name", name, "-p", `${DEFAULT_PORT}:6379`, IMAGE],
+    { encoding: "utf8" },
+  )
+
+  if (run.status !== 0) {
+    const detail = (run.stderr || run.stdout || "").trim()
+    console.warn(
+      `[supatype] ⚠  Could not start Valkey sidecar: ${detail || `exit ${run.status}`}\n` +
+        "  REST server cache will bypass until Valkey is available.",
+    )
+    return { addr: "", containerName: null, started: false }
+  }
+
+  for (let i = 0; i < 30; i++) {
+    if (isAddrReachable(DEFAULT_HOST, DEFAULT_PORT)) {
+      console.log(`[supatype] Valkey sidecar running (${addr})`)
+      return { addr, containerName: name, started: true }
+    }
+    sleepMs(100)
+  }
+
+  console.warn("[supatype] ⚠  Valkey sidecar started but not reachable yet — cache may bypass initially.")
+  return { addr, containerName: name, started: true }
+}
+
+export function stopValkeySidecar(containerName: string | null): void {
+  if (!containerName) return
+  spawnSync("docker", ["rm", "-f", containerName], { stdio: "ignore" })
+}
+
+/** @internal Test helper — probe without subprocess. */
+export function probeTcp(host: string, port: number): Promise<boolean> {
+  return new Promise((resolve) => {
+    const s = createConnection({ host, port })
+    s.once("connect", () => {
+      s.destroy()
+      resolve(true)
+    })
+    s.once("error", () => resolve(false))
+    setTimeout(() => {
+      s.destroy()
+      resolve(false)
+    }, 800)
+  })
+}

package/tests/admin-ensure.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from "vitest"
+import {
+  ADMIN_EMAIL_ENV,
+  ADMIN_PASSWORD_ENV,
+  clearAdminSeedPassword,
+  hashPasswordForAuth,
+} from "../src/commands/admin.js"
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+import { tmpdir } from "node:os"
+import { scaffold, defaultScaffoldOptions } from "../src/commands/init.js"
+
+describe("hashPasswordForAuth", () => {
+  it("produces a bcrypt hash", async () => {
+    const hash = await hashPasswordForAuth("test-password-123")
+    expect(hash.startsWith("$2")).toBe(true)
+  })
+})
+
+describe("clearAdminSeedPassword", () => {
+  it("removes SUPATYPE_ADMIN_PASSWORD from .env", () => {
+    const dir = join(tmpdir(), `supatype-admin-seed-${Date.now()}`)
+    mkdirSync(dir, { recursive: true })
+    writeFileSync(
+      join(dir, ".env"),
+      `${ADMIN_EMAIL_ENV}=admin@example.com\n${ADMIN_PASSWORD_ENV}=secret123\nJWT_SECRET=x\n`,
+      "utf8",
+    )
+    try {
+      clearAdminSeedPassword(dir)
+      const content = readFileSync(join(dir, ".env"), "utf8")
+      expect(content).toContain(`${ADMIN_EMAIL_ENV}=admin@example.com`)
+      expect(content).not.toContain(ADMIN_PASSWORD_ENV)
+      expect(content).toContain("JWT_SECRET=x")
+    } finally {
+      rmSync(dir, { recursive: true, force: true })
+    }
+  })
+})
+
+describe("init admin seed in .env", () => {
+  it("writes SUPATYPE_ADMIN_* when scaffold options include credentials", () => {
+    const dir = join(tmpdir(), `supatype-init-admin-${Date.now()}`)
+    mkdirSync(dir, { recursive: true })
+    try {
+      scaffold(dir, {
+        ...defaultScaffoldOptions("seeded-app"),
+        adminEmail: "admin@example.com",
+        adminPassword: "password123",
+      })
+      const env = readFileSync(join(dir, ".env"), "utf8")
+      expect(env).toContain("SUPATYPE_ADMIN_EMAIL=admin@example.com")
+      expect(env).toContain("SUPATYPE_ADMIN_PASSWORD=password123")
+      expect(existsSync(join(dir, ".env"))).toBe(true)
+    } finally {
+      rmSync(dir, { recursive: true, force: true })
+    }
+  })
+})

package/tests/binary-cache-cloud-overrides.test.ts

@@ -98,7 +98,7 @@ describe("VERSION_PIN_LOCAL + resolveBinary", () => {
 
   it("throws when versions.engine is local without overrides.engine", async () => {
     const cfg = baseConfig()
-    cfg.versions.engine = VERSION_PIN_LOCAL
+    cfg.versions!.engine = VERSION_PIN_LOCAL
     await expect(resolveBinary("engine", cfg)).rejects.toThrow(/overrides\.engine/)
   })
 
@@ -106,7 +106,7 @@ describe("VERSION_PIN_LOCAL + resolveBinary", () => {
     const fakeBin = join(tmp, "supatype-engine-local")
     writeFileSync(fakeBin, "#")
     const cfg = baseConfig({ engine: fakeBin })
-    cfg.versions.engine = VERSION_PIN_LOCAL
+    cfg.versions!.engine = VERSION_PIN_LOCAL
     const p = await resolveBinary("engine", cfg)
     expect(p.replace(/\\/g, "/")).toContain("supatype-engine-local")
   })

package/tests/binary-download-lock.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it, beforeEach, afterEach } from "vitest"
+import { existsSync, mkdirSync, rmSync } from "node:fs"
+import { join } from "node:path"
+import { tmpdir } from "node:os"
+import {
+  tryAcquireDownloadLock,
+  releaseDownloadLock,
+  isDownloadInProgress,
+  clearDownloadLock,
+} from "../src/binary-download-lock.js"
+import { cachePath } from "../src/binary-cache.js"
+
+const VERSION = "9.9.9-test"
+
+describe("binary-download-lock", () => {
+  let dir: string
+
+  beforeEach(() => {
+    dir = cachePath("deno", VERSION)
+    if (existsSync(dir)) rmSync(dir, { recursive: true, force: true })
+    mkdirSync(dir, { recursive: true })
+  })
+
+  afterEach(() => {
+    clearDownloadLock("deno", VERSION)
+    if (existsSync(dir)) rmSync(dir, { recursive: true, force: true })
+  })
+
+  it("acquires and releases a download lock", () => {
+    expect(tryAcquireDownloadLock("deno", VERSION)).toBe(true)
+    expect(isDownloadInProgress("deno", VERSION)).toBe(true)
+    releaseDownloadLock("deno", VERSION)
+    expect(isDownloadInProgress("deno", VERSION)).toBe(false)
+  })
+
+  it("rejects a second acquire while the lock is held", () => {
+    expect(tryAcquireDownloadLock("deno", VERSION)).toBe(true)
+    expect(tryAcquireDownloadLock("deno", VERSION)).toBe(false)
+    releaseDownloadLock("deno", VERSION)
+  })
+})

package/tests/cli-help.test.ts

@@ -4,12 +4,15 @@
  */
 import { describe, it, expect } from "vitest"
 import { spawnSync } from "node:child_process"
-import { resolve, dirname } from "node:path"
+import { readFileSync } from "node:fs"
+import { resolve, dirname, join } from "node:path"
 import { fileURLToPath } from "node:url"
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 const CLI_BIN = resolve(__dirname, "../bin/supatype.js")
-const DIST_CLI = resolve(__dirname, "../dist/cli.js")
+const PACKAGE_VERSION = (
+  JSON.parse(readFileSync(join(__dirname, "../package.json"), "utf8")) as { version: string }
+).version
 
 function runCli(args: string[]): { stdout: string; stderr: string; exitCode: number } {
   const result = spawnSync(process.execPath, [CLI_BIN, ...args], {
@@ -51,10 +54,10 @@ describe("CLI binary (requires built dist/)", () => {
     }
   })
 
-  it("--version prints a semver string", () => {
+  it("--version prints package.json version", () => {
     const { stdout, exitCode } = runCli(["--version"])
     expect(exitCode).toBe(0)
-    expect(stdout.trim()).toMatch(/^\d+\.\d+\.\d+/)
+    expect(stdout.trim()).toBe(PACKAGE_VERSION)
   })
 
   it("self-update --help describes the command", () => {

package/tests/cli-package-version.test.ts

@@ -0,0 +1,15 @@
+import { describe, expect, it } from "vitest"
+import { readFileSync } from "node:fs"
+import { join, dirname } from "node:path"
+import { fileURLToPath } from "node:url"
+import { cliPackageVersion } from "../src/cli-package-version.js"
+
+const packageJson = JSON.parse(
+  readFileSync(join(dirname(fileURLToPath(import.meta.url)), "../package.json"), "utf8"),
+) as { version: string }
+
+describe("cliPackageVersion", () => {
+  it("matches packages/cli/package.json version", () => {
+    expect(cliPackageVersion()).toBe(packageJson.version)
+  })
+})

package/tests/command-chrome-coverage.test.ts

@@ -0,0 +1,149 @@
+import { Command } from "commander"
+import { describe, expect, it } from "vitest"
+import { registerInit } from "../src/commands/init.js"
+import { registerDev } from "../src/commands/dev.js"
+import { registerCache } from "../src/commands/cache.js"
+import { registerSelfUpdate } from "../src/commands/self-update.js"
+import { registerUpdate } from "../src/commands/update.js"
+import { registerPg } from "../src/commands/pg.js"
+import { registerPush } from "../src/commands/push.js"
+import { registerDiff } from "../src/commands/diff.js"
+import { registerPull } from "../src/commands/pull.js"
+import { registerDoctor } from "../src/commands/doctor.js"
+import { registerIntrospect } from "../src/commands/introspect.js"
+import { registerAdopt } from "../src/commands/adopt.js"
+import { registerGenerate } from "../src/commands/generate.js"
+import { registerMigrate } from "../src/commands/migrate.js"
+import { registerSeed } from "../src/commands/seed.js"
+import { registerKeys } from "../src/commands/keys.js"
+import { registerApp } from "../src/commands/app.js"
+import { registerAdd } from "../src/commands/add.js"
+import { registerSelfHost } from "../src/commands/self-host.js"
+import { registerCloud } from "../src/commands/cloud.js"
+import { registerEngine } from "../src/commands/engine.js"
+import { registerDb } from "../src/commands/db.js"
+import { registerDeploy } from "../src/commands/deploy.js"
+import { registerStatus } from "../src/commands/status.js"
+import { registerLogs } from "../src/commands/logs.js"
+import { registerAdmin } from "../src/commands/admin.js"
+import { registerFunctions } from "../src/commands/functions.js"
+import { registerPlugins } from "../src/commands/plugins.js"
+import { registerTypes } from "../src/commands/types.js"
+import { registerMigrateFromV1 } from "../src/commands/migrate-from-v1.js"
+import {
+  shouldExcludeCommandChrome,
+  wrapProgramActionsWithChrome,
+} from "../src/ui/runtime/command-chrome.js"
+
+type CommandWithAction = Command & {
+  parent?: Command | null
+  _actionHandler?: ((args: unknown) => unknown) | null
+}
+
+function commandPath(cmd: CommandWithAction, root: Command): string {
+  const segments: string[] = []
+  let current: CommandWithAction | null = cmd
+  while (current && current !== root) {
+    segments.unshift(current.name())
+    current = current.parent ?? null
+  }
+  return segments.join(" ")
+}
+
+function collectActionCommands(cmd: CommandWithAction, root: Command): CommandWithAction[] {
+  const out: CommandWithAction[] = []
+  if (cmd._actionHandler) out.push(cmd)
+  for (const sub of cmd.commands) {
+    out.push(...collectActionCommands(sub as CommandWithAction, root))
+  }
+  return out
+}
+
+function buildProgram(): Command {
+  const program = new Command().name("supatype")
+  registerInit(program)
+  registerDev(program)
+  registerCache(program)
+  registerSelfUpdate(program)
+  registerUpdate(program)
+  registerPg(program)
+  registerPush(program)
+  registerDiff(program)
+  registerPull(program)
+  registerDoctor(program)
+  registerIntrospect(program)
+  registerAdopt(program)
+  registerGenerate(program)
+  registerMigrate(program)
+  registerSeed(program)
+  registerKeys(program)
+  registerApp(program)
+  registerAdd(program)
+  registerSelfHost(program)
+  registerCloud(program)
+  registerEngine(program)
+  registerDb(program)
+  registerDeploy(program)
+  registerStatus(program)
+  registerLogs(program)
+  registerAdmin(program)
+  registerFunctions(program)
+  registerPlugins(program)
+  registerTypes(program)
+  registerMigrateFromV1(program)
+  wrapProgramActionsWithChrome(program)
+  return program
+}
+
+describe("CLI command chrome coverage", () => {
+  it("wraps every non-excluded leaf command", () => {
+    const program = buildProgram()
+    const root = program as CommandWithAction
+    const commands = collectActionCommands(root, program)
+
+    expect(commands.length).toBeGreaterThan(50)
+
+    const excluded: string[] = []
+    const wrapped: string[] = []
+
+    for (const cmd of commands) {
+      const path = commandPath(cmd, program)
+      const handlerBefore = cmd._actionHandler
+      // Re-wrap is idempotent only when already wrapped; detect first-wrap by path policy.
+      if (shouldExcludeCommandChrome(path)) {
+        excluded.push(path)
+        continue
+      }
+      wrapped.push(path)
+      expect(handlerBefore, `${path} should be wrapped`).toBeDefined()
+    }
+
+    expect(excluded).toEqual(
+      expect.arrayContaining([
+        "dev",
+        "init",
+        "link",
+        "add domain",
+        "logs",
+        "pg psql",
+        "functions serve",
+        "self-host compose logs",
+      ]),
+    )
+
+    expect(wrapped).toEqual(
+      expect.arrayContaining([
+        "push",
+        "diff",
+        "doctor",
+        "pull",
+        "cache list",
+        "cache rest list",
+        "deploy",
+        "deploy rollback",
+        "keys",
+        "generate",
+      ]),
+    )
+  })
+})

package/tests/command-chrome-wrap.test.ts

@@ -0,0 +1,51 @@
+import { Command } from "commander"
+import { describe, expect, it, vi } from "vitest"
+import {
+  shouldExcludeCommandChrome,
+  wrapProgramActionsWithChrome,
+} from "../src/ui/runtime/command-chrome.js"
+
+describe("shouldExcludeCommandChrome", () => {
+  it("excludes wizard and streaming commands", () => {
+    expect(shouldExcludeCommandChrome("dev")).toBe(true)
+    expect(shouldExcludeCommandChrome("init")).toBe(true)
+    expect(shouldExcludeCommandChrome("link")).toBe(true)
+    expect(shouldExcludeCommandChrome("add domain")).toBe(true)
+    expect(shouldExcludeCommandChrome("logs")).toBe(true)
+    expect(shouldExcludeCommandChrome("pg psql")).toBe(true)
+    expect(shouldExcludeCommandChrome("functions serve")).toBe(true)
+    expect(shouldExcludeCommandChrome("self-host compose logs")).toBe(true)
+  })
+
+  it("includes one-shot commands", () => {
+    expect(shouldExcludeCommandChrome("push")).toBe(false)
+    expect(shouldExcludeCommandChrome("doctor")).toBe(false)
+    expect(shouldExcludeCommandChrome("cache rest list")).toBe(false)
+    expect(shouldExcludeCommandChrome("deploy rollback")).toBe(false)
+  })
+})
+
+describe("wrapProgramActionsWithChrome", () => {
+  it("wraps leaf actions but skips excluded paths", () => {
+    const program = new Command()
+    const pushFn = vi.fn()
+    const devFn = vi.fn()
+
+    program.command("push").action(pushFn)
+    program.command("dev").action(devFn)
+
+    type CommandWithAction = Command & {
+      _actionHandler?: ((args: unknown) => unknown) | null
+    }
+
+    const pushCmd = program.commands.find((c) => c.name() === "push") as CommandWithAction
+    const devCmd = program.commands.find((c) => c.name() === "dev") as CommandWithAction
+    const pushHandlerBefore = pushCmd._actionHandler
+    const devHandlerBefore = devCmd._actionHandler
+
+    wrapProgramActionsWithChrome(program)
+
+    expect(pushCmd._actionHandler).not.toBe(pushHandlerBefore)
+    expect(devCmd._actionHandler).toBe(devHandlerBefore)
+  })
+})

package/tests/config.test.ts

@@ -176,7 +176,7 @@ describe("loadConfig()", () => {
       })}`,
     )
     const cfg = loadConfig(tmpDir)
-    expect(cfg.versions.engine).toBe("0.4.2")
+    expect(cfg.versions!.engine).toBe("0.4.2")
     expect(cfg.schema?.path).toBe("./a.ts")
   })
 })
@@ -207,7 +207,9 @@ describe("mergeProjectConfig()", () => {
       ...minimalProject("p"),
       email: { provider: "smtp", smtp: { host: "h1", port: 587, user: "u0" } },
     })
-    const merged = mergeProjectConfig(base, { email: { smtp: { host: "h2", pass: "x" } } })
+    const merged = mergeProjectConfig(base, {
+      email: { smtp: { host: "h2", pass: "x" } },
+    } as Partial<typeof base>)
     expect(merged.email?.provider).toBe("smtp")
     expect(merged.email?.smtp?.host).toBe("h2")
     expect(merged.email?.smtp?.port).toBe(587)
@@ -222,7 +224,7 @@ describe("mergeProjectConfig()", () => {
     })
     const merged = mergeProjectConfig(base, {
       email: { send_email_hook_secrets: "v1,whsec_customsecret0000000000000000" },
-    })
+    } as Partial<typeof base>)
     expect(merged.email?.send_email_hook).toBe(true)
     expect(merged.email?.send_email_hook_uri).toBe("http://old/hook")
     expect(merged.email?.send_email_hook_secrets).toBe("v1,whsec_customsecret0000000000000000")
@@ -233,7 +235,9 @@ describe("mergeProjectConfig()", () => {
       ...minimalProject("p"),
       app: { mode: "static", static_dir: "./dist", vite_dev_url: "http://127.0.0.1:1111" },
     })
-    const merged = mergeProjectConfig(base, { app: { vite_dev_url: "http://127.0.0.1:5173" } })
+    const merged = mergeProjectConfig(base, {
+      app: { vite_dev_url: "http://127.0.0.1:5173" },
+    } as Partial<typeof base>)
     expect(merged.app?.vite_dev_url).toBe("http://127.0.0.1:5173")
   })
 

package/tests/dev-ports.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it, vi, beforeEach, afterEach } from "vitest"
+import { mkdtempSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+import { tmpdir } from "node:os"
+import {
+  findNextFreePort,
+  isValidHostPort,
+  parseHostPortInput,
+  readPersistedKongPort,
+} from "../src/dev-ports.js"
+import { isPortInUse } from "../src/postgres-ctl.js"
+
+vi.mock("../src/postgres-ctl.js", () => ({
+  isPortInUse: vi.fn(),
+}))
+
+const isPortInUseMock = vi.mocked(isPortInUse)
+
+describe("dev-ports", () => {
+  beforeEach(() => {
+    isPortInUseMock.mockReset()
+  })
+
+  it("validates host ports", () => {
+    expect(isValidHostPort(18473)).toBe(true)
+    expect(isValidHostPort(80)).toBe(false)
+    expect(parseHostPortInput("18473")).toBe(18473)
+    expect(parseHostPortInput("nope")).toBeNull()
+  })
+
+  it("reads persisted Kong port from .env", () => {
+    const dir = mkdtempSync(join(tmpdir(), "supatype-ports-"))
+    writeFileSync(join(dir, ".env"), "SUPATYPE_KONG_PORT=18474\n", "utf8")
+    expect(readPersistedKongPort(dir)).toBe(18474)
+  })
+
+  it("findNextFreePort skips taken ports", async () => {
+    isPortInUseMock.mockImplementation(async (port) => port === 18473 || port === 18474)
+    await expect(findNextFreePort(18473)).resolves.toBe(18475)
+  })
+})