@supatype/cli 0.1.0 → 0.1.1

package/src/dev-session-lock.ts

@@ -0,0 +1,101 @@
+/**
+ * Tracks an active `supatype dev` session so we can recover when the CLI exits
+ * without graceful shutdown (terminal closed, kill signal, etc.).
+ */
+
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs"
+import { join, resolve } from "node:path"
+import { spawnSync } from "node:child_process"
+import * as p from "@clack/prompts"
+import { runDockerCompose } from "./self-host-compose.js"
+import { isInteractive } from "./ui/interactive.js"
+import { warn } from "./ui/messages.js"
+
+const LOCK_VERSION = 1 as const
+
+export interface DevSessionLock {
+  version: typeof LOCK_VERSION
+  composeProject: string
+  projectRef: string
+  composePath: string
+  kongPort: number
+  startedAt: string
+}
+
+export function devSessionLockPath(cwd: string): string {
+  return resolve(cwd, ".supatype/dev-session.json")
+}
+
+export function readDevSessionLock(cwd: string): DevSessionLock | null {
+  const path = devSessionLockPath(cwd)
+  if (!existsSync(path)) return null
+  try {
+    const data = JSON.parse(readFileSync(path, "utf8")) as DevSessionLock
+    if (data.version !== LOCK_VERSION) return null
+    return data
+  } catch {
+    return null
+  }
+}
+
+export function writeDevSessionLock(cwd: string, lock: Omit<DevSessionLock, "version">): void {
+  const dir = join(cwd, ".supatype")
+  mkdirSync(dir, { recursive: true })
+  const payload: DevSessionLock = { version: LOCK_VERSION, ...lock }
+  writeFileSync(devSessionLockPath(cwd), `${JSON.stringify(payload, null, 2)}\n`, "utf8")
+}
+
+export function clearDevSessionLock(cwd: string): void {
+  const path = devSessionLockPath(cwd)
+  if (existsSync(path)) unlinkSync(path)
+}
+
+export function composeStackHasContainers(composeProject: string): boolean {
+  const result = spawnSync(
+    "docker",
+    ["ps", "-a", "--filter", `label=com.docker.compose.project=${composeProject}`, "--format", "{{.Names}}"],
+    { encoding: "utf8", shell: process.platform === "win32" },
+  )
+  return Boolean(result.stdout?.trim())
+}
+
+/**
+ * When a previous dev session did not shut down cleanly, offer to stop its stack
+ * before starting a new one.
+ */
+export async function recoverStaleDevSession(cwd: string): Promise<void> {
+  const lock = readDevSessionLock(cwd)
+  if (!lock) return
+  if (!composeStackHasContainers(lock.composeProject)) {
+    clearDevSessionLock(cwd)
+    return
+  }
+
+  const message =
+    `Previous dev session for "${lock.projectRef}" may not have shut down cleanly ` +
+    `(stack "${lock.composeProject}" is still running).`
+
+  if (!isInteractive()) {
+    warn(message)
+    warn(`Stop it manually: docker compose -p ${lock.composeProject} down`)
+    return
+  }
+
+  const stop = await p.confirm({
+    message: `${message}\n\nStop the orphaned stack before starting?`,
+    initialValue: true,
+  })
+
+  if (p.isCancel(stop) || !stop) {
+    warn(`Leaving "${lock.composeProject}" running.`)
+    return
+  }
+
+  const status = runDockerCompose(lock.composePath, ["down"], cwd, lock.composeProject, { quiet: true })
+  if (status === 0) {
+    clearDevSessionLock(cwd)
+    p.log.success(`Stopped orphaned stack "${lock.composeProject}".`)
+  } else {
+    warn(`Could not stop "${lock.composeProject}" (exit ${status}).`)
+  }
+}

package/src/dev-shutdown.ts

@@ -1,24 +1,86 @@
 /**
- * Graceful shutdown for `supatype dev` — single path from SIGINT and TUI Ctrl+C.
+ * Graceful shutdown for `supatype dev` — SIGINT, TUI Ctrl+C, terminal close,
+ * and a synchronous compose-down fallback on process exit.
  */
 
+import { existsSync } from "node:fs"
 import { endDevSession } from "./dev-session.js"
+import { clearDevSessionLock } from "./dev-session-lock.js"
+import { runDockerCompose } from "./self-host-compose.js"
+
+export interface DevComposeShutdownFallback {
+  cwd: string
+  composePath: string
+  composeProject: string
+}
 
 let shutdownWork: (() => Promise<void>) | null = null
+let composeFallback: DevComposeShutdownFallback | null = null
+let shutdownCwd: string | null = null
 let shuttingDown = false
-let signalsRegistered = false
+let shutdownCompleted = false
+let forceQuitRequested = false
+let hooksRegistered = false
 
 function onSignal(): void {
   void runDevShutdown()
 }
 
+function onStdinClose(): void {
+  if (!process.stdin.isTTY) return
+  void runDevShutdown()
+}
+
+function syncComposeDownFallback(): void {
+  if (shutdownCompleted || !composeFallback) return
+  try {
+    runDockerCompose(
+      composeFallback.composePath,
+      ["down"],
+      composeFallback.cwd,
+      composeFallback.composeProject,
+      { quiet: true },
+    )
+  } catch {
+    // best-effort — process is exiting
+  }
+  if (shutdownCwd) clearDevSessionLock(shutdownCwd)
+}
+
+function onProcessExit(): void {
+  syncComposeDownFallback()
+}
+
+export interface RegisterDevShutdownOptions {
+  /** Sync `docker compose down` when async teardown cannot finish (terminal close, kill). */
+  compose?: DevComposeShutdownFallback
+  /** Project root — clears `.supatype/dev-session.json` after shutdown. */
+  cwd?: string
+}
+
 /** Register async teardown (stop children, compose down, etc.). Call once per dev session. */
-export function registerDevShutdown(work: () => Promise<void>): void {
+export function registerDevShutdown(
+  work: () => Promise<void>,
+  opts?: RegisterDevShutdownOptions,
+): void {
   shutdownWork = work
-  if (signalsRegistered) return
-  signalsRegistered = true
+  composeFallback = opts?.compose ?? null
+  shutdownCwd = opts?.cwd ?? opts?.compose?.cwd ?? null
+
+  if (hooksRegistered) return
+  hooksRegistered = true
+
   process.on("SIGINT", onSignal)
   process.on("SIGTERM", onSignal)
+  if (process.platform === "win32") {
+    process.on("SIGBREAK", onSignal)
+  }
+  process.on("exit", onProcessExit)
+
+  if (process.stdin.isTTY) {
+    process.stdin.on("end", onStdinClose)
+    process.stdin.on("close", onStdinClose)
+  }
 }
 
 /** TUI Ctrl+C — do not re-emit SIGINT (avoids double-fire on Windows raw mode). */
@@ -30,13 +92,32 @@ export function isDevShuttingDown(): boolean {
   return shuttingDown
 }
 
+/** @internal Tests — reset module state between cases. */
+export function resetDevShutdownForTests(): void {
+  shutdownWork = null
+  composeFallback = null
+  shutdownCwd = null
+  shuttingDown = false
+  shutdownCompleted = false
+  forceQuitRequested = false
+  hooksRegistered = false
+}
+
 async function runDevShutdown(): Promise<void> {
   if (shuttingDown) {
+    if (!forceQuitRequested) {
+      forceQuitRequested = true
+      process.stderr.write(
+        "\n[supatype] Still shutting down (stopping Docker)… press Ctrl+C again to force quit.\n",
+      )
+      return
+    }
     try {
       endDevSession()
     } catch {
       // best-effort terminal restore
     }
+    process.stderr.write("\n[supatype] Forced quit — Docker containers may still be running.\n")
     process.stdout.write("\n")
     process.exit(130)
   }
@@ -46,9 +127,21 @@ async function runDevShutdown(): Promise<void> {
     endDevSession()
     process.stdout.write("\n")
     await shutdownWork?.()
+    shutdownCompleted = true
+    if (shutdownCwd) clearDevSessionLock(shutdownCwd)
     process.exit(0)
   } catch (err) {
     process.stderr.write(`[supatype] Shutdown failed: ${(err as Error).message}\n`)
+    process.stderr.write(
+      "[supatype] Docker containers may still be running — try: supatype self-host compose down\n",
+    )
+    syncComposeDownFallback()
+    shutdownCompleted = true
     process.exit(1)
   }
 }
+
+/** Whether a compose fallback was registered (tests). */
+export function hasComposeShutdownFallback(): boolean {
+  return composeFallback !== null && existsSync(composeFallback.composePath)
+}

package/src/env-file.ts

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

package/src/self-host-compose.ts

@@ -593,7 +593,8 @@ export function runDockerCompose(
   const env: NodeJS.ProcessEnv = options?.quiet
     ? { ...process.env, COMPOSE_PROGRESS: "quiet" }
     : process.env
-  const result = spawnSync("docker", composeArgs, { stdio: "inherit", cwd: projectRoot, env })
+  const stdio = options?.quiet ? "pipe" : "inherit"
+  const result = spawnSync("docker", composeArgs, { stdio, cwd: projectRoot, env })
   return result.status ?? 1
 }
 

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/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)
+  })
+})

package/tests/dev-session-lock.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, it, vi, beforeEach, afterEach } from "vitest"
+import { mkdtempSync, writeFileSync, existsSync, mkdirSync } from "node:fs"
+import { join } from "node:path"
+import { tmpdir } from "node:os"
+import {
+  clearDevSessionLock,
+  devSessionLockPath,
+  readDevSessionLock,
+  writeDevSessionLock,
+} from "../src/dev-session-lock.js"
+
+describe("dev-session-lock", () => {
+  let dir: string
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "supatype-lock-"))
+  })
+
+  afterEach(() => {
+    clearDevSessionLock(dir)
+  })
+
+  it("writes and reads a lock file", () => {
+    writeDevSessionLock(dir, {
+      composeProject: "supatype-demo",
+      projectRef: "demo",
+      composePath: join(dir, ".supatype/self-host/docker-compose.yml"),
+      kongPort: 18473,
+      startedAt: "2026-01-01T00:00:00.000Z",
+    })
+    expect(existsSync(devSessionLockPath(dir))).toBe(true)
+    const lock = readDevSessionLock(dir)
+    expect(lock?.composeProject).toBe("supatype-demo")
+    expect(lock?.kongPort).toBe(18473)
+  })
+
+  it("clears the lock file", () => {
+    mkdirSync(join(dir, ".supatype"), { recursive: true })
+    writeFileSync(
+      devSessionLockPath(dir),
+      JSON.stringify({
+        version: 1,
+        composeProject: "supatype-demo",
+        projectRef: "demo",
+        composePath: "x",
+        kongPort: 1,
+        startedAt: "t",
+      }),
+      "utf8",
+    )
+    clearDevSessionLock(dir)
+    expect(existsSync(devSessionLockPath(dir))).toBe(false)
+  })
+})

package/tests/dev-ui.test.ts

@@ -1,4 +1,7 @@
 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 { DevLogBus } from "../src/dev-log-bus.js"
 import { filterDevSubprocessLine, formatConsoleArgs, stripAnsi } from "../src/dev-log-filter.js"
 import { appendDevTaskLog, beginDevSession, endDevSession, resolveDevUiMode } from "../src/dev-session.js"
@@ -104,9 +107,11 @@ describe("dev-task-colors", () => {
 
 describe("dev-shutdown", () => {
   const exitSpy = vi.spyOn(process, "exit").mockImplementation((() => undefined) as typeof process.exit)
+  const stderrSpy = vi.spyOn(process.stderr, "write").mockImplementation(() => true)
 
   beforeEach(() => {
     exitSpy.mockClear()
+    stderrSpy.mockClear()
   })
 
   afterEach(() => {
@@ -125,7 +130,7 @@ describe("dev-shutdown", () => {
     expect(ran).toBe(true)
   })
 
-  it("force-exits 130 on second interrupt", async () => {
+  it("warns on second interrupt then force-exits on third", async () => {
     vi.resetModules()
     const { registerDevShutdown, requestDevShutdown } = await import("../src/dev-shutdown.js")
     registerDevShutdown(async () => {
@@ -134,6 +139,24 @@ describe("dev-shutdown", () => {
     requestDevShutdown()
     await vi.waitFor(() => expect(exitSpy).toHaveBeenCalledTimes(0))
     requestDevShutdown()
+    expect(stderrSpy).toHaveBeenCalled()
+    expect(exitSpy).toHaveBeenCalledTimes(0)
+    requestDevShutdown()
     expect(exitSpy).toHaveBeenCalledWith(130)
   })
+
+  it("registers compose fallback for sync exit cleanup", async () => {
+    vi.resetModules()
+    const { registerDevShutdown, hasComposeShutdownFallback, resetDevShutdownForTests } =
+      await import("../src/dev-shutdown.js")
+    resetDevShutdownForTests()
+    const dir = mkdtempSync(join(tmpdir(), "supatype-shutdown-"))
+    const composePath = join(dir, "docker-compose.yml")
+    writeFileSync(composePath, "services: {}\n", "utf8")
+    registerDevShutdown(async () => undefined, {
+      cwd: dir,
+      compose: { cwd: dir, composePath, composeProject: "supatype-test" },
+    })
+    expect(hasComposeShutdownFallback()).toBe(true)
+  })
 })