@keel_flow/cli 0.2.0

package/dist/up.js

@@ -0,0 +1,656 @@
+import { execSync, spawn } from "child_process";
+import { existsSync } from "fs";
+import * as nodeFs from "node:fs";
+import { createServer } from "node:net";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import pc from "picocolors";
+import { ensureEncryptionKey } from "@keel_flow/setup/server";
+import { dockerContainerStatus, listLocks, readLock, removeLock, stopDockerContainer, stopListenersOnPorts, writeLock, } from "./lifecycle.js";
+import { CLAUDE_INSTALL_HINT, probeClaudeAuth, resolveProviderKind, triggerClaudeLogin, } from "./claude-auth.js";
+// claude-bridge login preflight for `keel up`. When the default keyless provider
+// is in effect, make sure the user is signed in to their Claude subscription
+// BEFORE booting — otherwise the /chat agent boots dead at its first LLM call.
+// Never hard-blocks the workspace (verify/map/UI still work without it); it
+// auto-triggers the browser sign-in only on an interactive TTY, and otherwise
+// prints the exact recovery command. Honors --no-login / CLAUDE_CODE_OAUTH_TOKEN.
+async function claudeBridgeLoginPreflight(opts) {
+    if (resolveProviderKind() !== "claude-bridge")
+        return; // user picked a keyed provider
+    if (process.env["CLAUDE_CODE_OAUTH_TOKEN"])
+        return; // headless token already provides auth
+    const auth = probeClaudeAuth();
+    if (auth.state === "authed") {
+        process.stdout.write(pc.dim(`  Claude subscription: signed in${auth.subscriptionType ? ` (${auth.subscriptionType})` : ""}\n`));
+        return;
+    }
+    if (auth.state === "cli-missing") {
+        process.stdout.write(pc.yellow(`  ${CLAUDE_INSTALL_HINT}\n`) +
+            pc.dim("  (the workspace boots either way — the chat agent needs sign-in to answer)\n"));
+        return;
+    }
+    // logged-out
+    if (opts.skipLogin || !process.stdout.isTTY) {
+        process.stdout.write(pc.yellow("  not signed in to Claude — run `keel login` to enable the agent (or set CLAUDE_CODE_OAUTH_TOKEN)\n"));
+        return;
+    }
+    process.stdout.write(pc.cyan("  signing in to your Claude subscription (no API key needed)...\n"));
+    triggerClaudeLogin("browser");
+}
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
+// Only KEEL_TOKEN_ENCRYPTION_KEY is genuinely needed at boot — it encrypts the
+// provider secrets stored per workspace. ANTHROPIC_API_KEY is NOT a boot
+// requirement: the default interactive surface is claude-bridge (Claude
+// subscription auth, no API key) and OpenAI-compatible providers bring their own
+// key, so warning about a missing ANTHROPIC_API_KEY on every boot was a false
+// alarm that undercut the "just works" feel. A genuinely-missing Anthropic key
+// now surfaces lazily, at the point an AnthropicProvider is actually constructed.
+const REQUIRED_KEYS_AT_BOOT = ["KEEL_TOKEN_ENCRYPTION_KEY"];
+export function parseDotEnvContent(content) {
+    const result = {};
+    for (const line of content.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#"))
+            continue;
+        const eqIdx = trimmed.indexOf("=");
+        if (eqIdx < 1)
+            continue;
+        const key = trimmed.slice(0, eqIdx).trim();
+        const val = trimmed.slice(eqIdx + 1).trim();
+        if (!key)
+            continue;
+        result[key] = val;
+    }
+    return result;
+}
+export function loadDotEnv(repoRoot) {
+    const envPath = join(repoRoot, ".env");
+    if (!nodeFs.existsSync(envPath))
+        return;
+    let raw;
+    try {
+        raw = nodeFs.readFileSync(envPath, "utf8");
+    }
+    catch {
+        return;
+    }
+    const parsed = parseDotEnvContent(raw);
+    for (const [key, val] of Object.entries(parsed)) {
+        if (!(key in process.env)) {
+            process.env[key] = val;
+        }
+    }
+}
+export function warnMissingKeys() {
+    for (const key of REQUIRED_KEYS_AT_BOOT) {
+        if (!process.env[key]) {
+            process.stderr.write(pc.yellow(`  warning: ${key} is not set — some features may not work\n`));
+        }
+    }
+}
+export const DEFAULTS = {
+    API_PORT: 3001,
+    UI_PORT: 3000,
+    DB_PORT: 5432,
+    DB_USER: "keel",
+    DB_PASSWORD: "keel_local",
+    DB_NAME: "keel",
+    DOCKER_CONTAINER: "keel-postgres-up",
+    HEALTH_TIMEOUT_MS: 60_000,
+    HEALTH_POLL_INTERVAL_MS: 1_000,
+};
+// Parse user/password/database out of a Postgres connection string. Any
+// component the URL omits comes back undefined so the caller can fall back to a
+// default. Tolerates both the postgres:// and postgresql:// schemes and
+// percent-encoded credentials; on an unparseable string it returns all-empty so
+// the caller keeps its existing defaults rather than throwing.
+export function parsePgConnectionString(connectionString) {
+    try {
+        const url = new URL(connectionString);
+        const database = url.pathname.replace(/^\//, "");
+        return {
+            user: url.username ? decodeURIComponent(url.username) : undefined,
+            password: url.password ? decodeURIComponent(url.password) : undefined,
+            database: database ? decodeURIComponent(database) : undefined,
+        };
+    }
+    catch {
+        return {};
+    }
+}
+export function resolveConfig() {
+    const apiPort = parseInt(process.env["KEEL_API_PORT"] ?? String(DEFAULTS.API_PORT), 10);
+    const uiPort = parseInt(process.env["KEEL_UI_PORT"] ?? String(DEFAULTS.UI_PORT), 10);
+    const dbPort = parseInt(process.env["KEEL_DB_PORT"] ?? String(DEFAULTS.DB_PORT), 10);
+    // Default credentials used to BOTH initialize the managed container and build
+    // the connection string when no explicit URL is supplied.
+    const defaultUser = process.env["POSTGRES_USER"] ?? DEFAULTS.DB_USER;
+    const defaultPassword = process.env["POSTGRES_PASSWORD"] ?? DEFAULTS.DB_PASSWORD;
+    const defaultName = process.env["POSTGRES_DB"] ?? DEFAULTS.DB_NAME;
+    const databaseUrl = process.env["KEEL_DATABASE_URL"] ?? process.env["DATABASE_URL"] ??
+        `postgresql://${defaultUser}:${defaultPassword}@localhost:${dbPort}/${defaultName}`;
+    // Single source of truth: when an explicit DATABASE_URL/KEEL_DATABASE_URL is
+    // present, the managed Postgres container must be INITIALIZED with the same
+    // user/password/db the migration and API will later CONNECT with. Previously
+    // the container creds came from POSTGRES_* (defaulting to keel/keel_local)
+    // while the connection string came from the URL, so a custom password in the
+    // URL without a matching POSTGRES_PASSWORD initialized the container with one
+    // password and then failed auth with another (keel up: migration "role/
+    // password" failure on a fresh container). Derive the container creds from the
+    // resolved URL so the two can never diverge; the default URL parses back to
+    // the defaults, so the no-override path is unchanged.
+    const parsed = parsePgConnectionString(databaseUrl);
+    const dbUser = parsed.user ?? defaultUser;
+    const dbPassword = parsed.password ?? defaultPassword;
+    const dbName = parsed.database ?? defaultName;
+    const apiUrl = `http://localhost:${apiPort}`;
+    const uiUrl = `http://localhost:${uiPort}`;
+    return {
+        apiPort,
+        uiPort,
+        dbPort,
+        dbUser,
+        dbPassword,
+        dbName,
+        databaseUrl,
+        apiUrl,
+        uiUrl,
+        dockerContainer: process.env["KEEL_DOCKER_CONTAINER"] ?? DEFAULTS.DOCKER_CONTAINER,
+        repoRoot: process.env["KEEL_REPO_ROOT"] ?? REPO_ROOT,
+    };
+}
+export function checkWorkspacePreflight(repoRoot) {
+    const migrateScript = join(repoRoot, "apps", "api", "scripts", "migrate.mjs");
+    const workspaceDir = join(repoRoot, "apps", "workspace");
+    if (!existsSync(migrateScript) || !existsSync(workspaceDir)) {
+        process.stderr.write(pc.red(`\nkeel up — workspace preflight failed\n\n`) +
+            pc.yellow(`  keel up must run from a Keel monorepo checkout\n`) +
+            pc.yellow(`  (or set KEEL_REPO_ROOT to point at one).\n`) +
+            pc.yellow(`  This is not the same as the globally-installed subcommands.\n`) +
+            pc.dim(`\n  Expected to find:\n`) +
+            pc.dim(`    ${migrateScript}\n`) +
+            pc.dim(`    ${workspaceDir}\n`) +
+            pc.dim(`\nFix one of the above, then re-run:  keel up\n\n`));
+        process.exit(1);
+    }
+}
+export function detectDocker() {
+    try {
+        execSync("docker info --format '{{.ServerVersion}}'", { stdio: "pipe" });
+        return "running";
+    }
+    catch {
+        try {
+            execSync("docker --version", { stdio: "pipe" });
+            return "not-running";
+        }
+        catch {
+            return "unavailable";
+        }
+    }
+}
+export function hasExternalDb() {
+    return Boolean(process.env["DATABASE_URL"] ?? process.env["KEEL_DATABASE_URL"]);
+}
+export function preflightFail(reason) {
+    process.stderr.write(pc.red(`\nkeel up — database preflight failed\n\n`) +
+        reason +
+        pc.dim(`\n\nFix one of the above, then re-run:  keel up\n\n`));
+    process.exit(1);
+}
+export function checkPreflight() {
+    if (hasExternalDb())
+        return "external-db";
+    const dockerStatus = detectDocker();
+    if (dockerStatus === "running")
+        return "docker";
+    if (dockerStatus === "not-running") {
+        preflightFail(pc.yellow("Docker is installed but the daemon is not running.\n") +
+            pc.yellow("  → Start Docker Desktop (or run: sudo systemctl start docker) and retry.\n"));
+    }
+    preflightFail(pc.yellow("No database available.  Keel requires one of:\n\n") +
+        pc.cyan("  Option A — install Docker\n") +
+        pc.dim("    https://docs.docker.com/get-docker/\n\n") +
+        pc.cyan("  Option B — point to an existing Postgres+pgvector instance\n") +
+        pc.dim("    export DATABASE_URL=postgresql://user:pass@host:5432/keel\n"));
+}
+export const defaultSpawner = (cmd, args, opts) => spawn(cmd, args, { stdio: "inherit", ...opts });
+export async function startPostgres(config, spawner = defaultSpawner) {
+    const existing = (() => {
+        try {
+            const out = execSync(`docker inspect --format '{{.State.Status}}' ${config.dockerContainer}`, { stdio: "pipe" }).toString().trim();
+            return out;
+        }
+        catch {
+            return null;
+        }
+    })();
+    if (existing === "running") {
+        process.stdout.write(pc.dim(`  postgres container ${config.dockerContainer} already running\n`));
+        return;
+    }
+    if (existing === "exited" || existing === "created") {
+        process.stdout.write(pc.dim(`  restarting container ${config.dockerContainer}\n`));
+        try {
+            execSync(`docker start ${config.dockerContainer}`, { stdio: "pipe" });
+        }
+        catch (err) {
+            throw new Error(`Failed to restart container ${config.dockerContainer}: ${String(err)}\n` +
+                `Try removing it manually with: docker rm ${config.dockerContainer}`);
+        }
+        return;
+    }
+    process.stdout.write(pc.dim(`  starting pgvector container ${config.dockerContainer}\n`));
+    const proc = spawner("docker", [
+        "run",
+        "--name", config.dockerContainer,
+        "-e", `POSTGRES_USER=${config.dbUser}`,
+        "-e", `POSTGRES_PASSWORD=${config.dbPassword}`,
+        "-e", `POSTGRES_DB=${config.dbName}`,
+        "-p", `${config.dbPort}:5432`,
+        "-d",
+        "pgvector/pgvector:pg16",
+    ], { env: process.env });
+    await new Promise((resolve, reject) => {
+        proc.on("exit", (code) => {
+            if (code === 0)
+                resolve();
+            else
+                reject(new Error(`docker run exited with code ${code}`));
+        });
+        proc.on("error", reject);
+    });
+}
+export function isPortFree(port) {
+    return new Promise((resolve) => {
+        const probe = createServer();
+        probe.once("error", () => resolve(false));
+        probe.once("listening", () => probe.close(() => resolve(true)));
+        probe.listen(port, "0.0.0.0");
+    });
+}
+export async function assertPortsFree(ports) {
+    const taken = [];
+    for (const entry of ports) {
+        if (!(await isPortFree(entry.port)))
+            taken.push(entry);
+    }
+    if (taken.length === 0)
+        return;
+    const lines = taken
+        .map((entry) => `  port ${entry.port} (${entry.label}) is already in use by another process.\n` +
+        `    Find it:  lsof -nP -iTCP:${entry.port} -sTCP:LISTEN\n` +
+        `    Or pick a different port:  export ${entry.envVar}=<port>\n`)
+        .join("");
+    throw new Error(`keel up cannot start — required ports are taken:\n${lines}` +
+        `  Starting anyway would health-check a server keel up does not own.`);
+}
+export async function pollUrl(url, timeoutMs = DEFAULTS.HEALTH_TIMEOUT_MS, intervalMs = DEFAULTS.HEALTH_POLL_INTERVAL_MS, waitingLabel) {
+    const start = Date.now();
+    const deadline = start + timeoutMs;
+    let hintShown = false;
+    while (Date.now() < deadline) {
+        try {
+            const res = await fetch(url, { signal: AbortSignal.timeout(2000) });
+            if (res.ok)
+                return;
+        }
+        catch {
+        }
+        // Liveness during a long wait: a cold Next.js compile can take ~30s, and a
+        // single static "polling ..." line with no follow-up reads as a hang. After
+        // ~5s emit one reassurance — TTY only, so piped/CI output stays clean.
+        if (!hintShown && waitingLabel && process.stdout.isTTY && Date.now() - start > 5000) {
+            hintShown = true;
+            process.stdout.write(pc.dim(`  still waiting for ${waitingLabel} (first run can take ~30s)...\n`));
+        }
+        await new Promise((r) => setTimeout(r, intervalMs));
+    }
+    throw new Error(`Timed out waiting for ${url} to become healthy (${timeoutMs}ms)`);
+}
+export async function waitForPostgres(config, timeoutMs = DEFAULTS.HEALTH_TIMEOUT_MS) {
+    process.stdout.write(pc.dim("  waiting for postgres...\n"));
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        try {
+            execSync(`docker exec ${config.dockerContainer} pg_isready -U ${config.dbUser} -d ${config.dbName}`, { stdio: "pipe" });
+            return;
+        }
+        catch {
+        }
+        await new Promise((r) => setTimeout(r, 1000));
+    }
+    throw new Error(`Postgres container did not become ready within ${timeoutMs}ms`);
+}
+export function buildApiEnv(config) {
+    return {
+        ...process.env,
+        DATABASE_URL: config.databaseUrl,
+        PORT: String(config.apiPort),
+        CORS_ORIGIN: config.uiUrl,
+        KEEL_SINGLE_USER_MODE: process.env["KEEL_SINGLE_USER_MODE"] ?? "true",
+    };
+}
+export function buildUiEnv(config) {
+    return {
+        ...process.env,
+        PORT: String(config.uiPort),
+        KEEL_API_URL: config.apiUrl,
+        NEXT_PUBLIC_API_URL: config.apiUrl,
+        KEEL_SINGLE_USER_MODE: process.env["KEEL_SINGLE_USER_MODE"] ?? "true",
+    };
+}
+export async function runMigrationsViaScript(config, spawner = defaultSpawner) {
+    process.stdout.write(pc.dim("  running migrations...\n"));
+    const scriptPath = join(config.repoRoot, "apps", "api", "scripts", "migrate.mjs");
+    if (!existsSync(scriptPath)) {
+        throw new Error(`Migration script not found at ${scriptPath}`);
+    }
+    const proc = spawner("node", [scriptPath], {
+        env: { ...process.env, DATABASE_URL: config.databaseUrl },
+        cwd: join(config.repoRoot, "apps", "api"),
+    });
+    await new Promise((resolve, reject) => {
+        proc.on("exit", (code) => {
+            if (code === 0)
+                resolve();
+            else
+                reject(new Error(`Migration script exited with code ${code}`));
+        });
+        proc.on("error", reject);
+    });
+}
+export function openBrowser(url) {
+    const platform = process.platform;
+    try {
+        if (platform === "darwin")
+            execSync(`open ${url}`, { stdio: "pipe" });
+        else if (platform === "win32")
+            execSync(`start ${url}`, { stdio: "pipe" });
+        else
+            execSync(`xdg-open ${url}`, { stdio: "pipe" });
+    }
+    catch {
+    }
+}
+// The identity marker the API's /health endpoint echoes (apps/api/src/server.ts).
+// detectKeelApi requires it, so a bare {status:"ok"} from an unrelated dev server
+// on the same port is NOT mistaken for keel.
+export const KEEL_API_SERVICE = "keel-api";
+// Probe the API port and return true ONLY when a running keel API positively
+// identifies itself. Used by runUp to decide attach-vs-boot and (later) by
+// `keel status`/`keel open`. Returns false on any error, timeout, unexpected
+// status, non-JSON body, or a JSON body missing the keel-api marker — it never
+// guesses "yes". A 503 (degraded: db down but keel IS up) still counts as keel,
+// so a partially-healthy instance is recognized as ours rather than booted over.
+export async function detectKeelApi(apiUrl, timeoutMs = 2000) {
+    try {
+        const res = await fetch(`${apiUrl}/health`, { signal: AbortSignal.timeout(timeoutMs) });
+        if (!res.ok && res.status !== 503)
+            return false;
+        const body = (await res.json());
+        return body?.service === KEEL_API_SERVICE;
+    }
+    catch {
+        return false;
+    }
+}
+export function makeTeardown(services, stopContainer, apiPort) {
+    let tearingDown = false;
+    return async () => {
+        if (tearingDown)
+            return;
+        tearingDown = true;
+        process.stdout.write(pc.dim("\nshutting down...\n"));
+        // The dev servers share keel up's foreground process group, so the terminal
+        // SIGINT (Ctrl+C) already reached them; these kills are a backstop for the
+        // programmatic teardown path (a child crashing and triggering teardown).
+        services.uiProc?.kill("SIGTERM");
+        services.apiProc?.kill("SIGTERM");
+        let dockerWarning = null;
+        if (services.dockerContainer) {
+            try {
+                stopContainer(services.dockerContainer);
+            }
+            catch {
+                // Surface, don't swallow: a failed container stop means it's still
+                // running and the user needs the manual recovery command.
+                dockerWarning = `could not stop the database container — stop it with: docker stop ${services.dockerContainer}`;
+            }
+        }
+        // Remove this instance's lockfile so `keel status` doesn't report a ghost.
+        if (apiPort !== undefined)
+            removeLock(apiPort);
+        process.stdout.write((dockerWarning ? pc.yellow(`  ${dockerWarning}\n`) : "") +
+            pc.dim("stopped.\n"));
+    };
+}
+export async function runUp(opts = {}) {
+    const spawner = opts.spawner ?? defaultSpawner;
+    process.stdout.write(pc.bold("\nkeel up\n\n"));
+    loadDotEnv(process.env["KEEL_REPO_ROOT"] ?? REPO_ROOT);
+    // Zero-config secret: auto-generate + persist the token-encryption key on first
+    // run (to .keel/encryption-key, mode 0600) so the user never has to run openssl
+    // or hand-edit .env. ensureEncryptionKey returns the existing env/file key if
+    // present, else generates one. The spawned API + migrations inherit it via
+    // process.env (buildApiEnv spreads ...process.env).
+    const keyResult = ensureEncryptionKey();
+    process.env["KEEL_TOKEN_ENCRYPTION_KEY"] = keyResult.hex;
+    if (keyResult.status.warning) {
+        process.stdout.write(pc.dim(`  ${keyResult.status.warning}\n`));
+    }
+    warnMissingKeys();
+    const config = opts.config ?? resolveConfig();
+    checkWorkspacePreflight(config.repoRoot);
+    // Attach-or-fail-fast — decided BEFORE any docker/db/migration side effects,
+    // so the common re-run cases exit in milliseconds without mutating state.
+    //
+    // 1. A keel API already answering on the API port means this is a re-run of an
+    //    already-running workspace. Don't error and don't reboot anything — just
+    //    open the browser and exit cleanly. (This is the exact case that used to
+    //    boot a container, run 20 migrations, then throw a raw stack trace.)
+    if (await detectKeelApi(config.apiUrl)) {
+        process.stdout.write(pc.green("✓ keel is already running\n") +
+            pc.dim("  UI   ") + pc.cyan(config.uiUrl) + pc.dim("  ← open this\n") +
+            pc.dim(`  API  ${config.apiUrl}\n`));
+        if (!opts.skipBrowser) {
+            process.stdout.write(pc.dim("  reopening it in your browser...\n"));
+            openBrowser(config.uiUrl);
+        }
+        return;
+    }
+    // 2. No keel here, but if the ports are held by some OTHER process, stop now
+    //    with actionable guidance — before booting postgres or running migrations.
+    //    (assertPortsFree's lsof/relocate advice is correct now that we've ruled
+    //    out our own instance above.)
+    await assertPortsFree([
+        { port: config.apiPort, label: "workspace API", envVar: "KEEL_API_PORT" },
+        { port: config.uiPort, label: "workspace UI", envVar: "KEEL_UI_PORT" },
+    ]);
+    // Make sure the keyless Claude sign-in is live before we boot, so /chat works.
+    await claudeBridgeLoginPreflight({ skipLogin: opts.skipLogin ?? false });
+    const dbMode = checkPreflight();
+    const services = {
+        dockerContainer: null,
+        apiProc: null,
+        uiProc: null,
+    };
+    const teardown = makeTeardown(services, (name) => {
+        execSync(`docker stop ${name}`, { stdio: "pipe" });
+    }, config.apiPort);
+    process.on("SIGINT", () => { void teardown().then(() => process.exit(0)); });
+    process.on("SIGTERM", () => { void teardown().then(() => process.exit(0)); });
+    if (dbMode === "docker") {
+        process.stdout.write(pc.cyan("[ 1/5 ] starting postgres+pgvector\n"));
+        await startPostgres(config, spawner);
+        services.dockerContainer = config.dockerContainer;
+        await waitForPostgres(config);
+    }
+    else {
+        process.stdout.write(pc.cyan("[ 1/5 ] using external database (DATABASE_URL set)\n"));
+    }
+    process.stdout.write(pc.cyan("[ 2/5 ] running migrations\n"));
+    await runMigrationsViaScript(config, spawner);
+    process.stdout.write(pc.cyan("[ 3/5 ] starting workspace API\n"));
+    const apiEnv = buildApiEnv(config);
+    const apiProc = spawner("pnpm", ["--filter", "@keel_flow/api", "dev"], {
+        env: apiEnv,
+        cwd: config.repoRoot,
+    });
+    services.apiProc = apiProc;
+    process.stdout.write(pc.dim(`  polling ${config.apiUrl}/health\n`));
+    await pollUrl(`${config.apiUrl}/health`, DEFAULTS.HEALTH_TIMEOUT_MS, DEFAULTS.HEALTH_POLL_INTERVAL_MS, "the API");
+    process.stdout.write(pc.green(`  API ready at ${config.apiUrl}\n`));
+    process.stdout.write(pc.cyan("[ 4/5 ] starting workspace UI\n"));
+    const uiEnv = buildUiEnv(config);
+    const uiProc = spawner("pnpm", ["--filter", "@keel_flow/workspace", "dev"], {
+        env: uiEnv,
+        cwd: config.repoRoot,
+    });
+    services.uiProc = uiProc;
+    process.stdout.write(pc.dim(`  polling ${config.uiUrl}\n`));
+    await pollUrl(config.uiUrl, DEFAULTS.HEALTH_TIMEOUT_MS, DEFAULTS.HEALTH_POLL_INTERVAL_MS, "the UI to compile");
+    process.stdout.write(pc.green(`  UI ready at ${config.uiUrl}\n`));
+    process.stdout.write(pc.cyan("[ 5/5 ] opening browser\n"));
+    if (!opts.skipBrowser) {
+        openBrowser(config.uiUrl);
+    }
+    // Record this instance so `keel status`/`keel down` can find it from another
+    // terminal. Keyed by API port for multi-workspace coexistence. Informational
+    // only — `down` re-resolves the live port listeners and never trusts a PID.
+    writeLock({
+        apiPort: config.apiPort,
+        uiPort: config.uiPort,
+        apiUrl: config.apiUrl,
+        uiUrl: config.uiUrl,
+        dockerContainer: services.dockerContainer,
+        repoRoot: config.repoRoot,
+        startedAt: new Date().toISOString(),
+    });
+    process.stdout.write(pc.bold(`\n✓ keel workspace is running\n`) +
+        pc.dim(`  UI   `) + pc.cyan(config.uiUrl) + pc.dim(`  ← open this\n`) +
+        pc.dim(`  API  ${config.apiUrl}\n`) +
+        (opts.skipBrowser ? "" : pc.dim(`\n  opened in your browser automatically.\n`)) +
+        pc.dim(`  single-user mode — no sign-in required.\n`) +
+        pc.dim(`\n  Press Ctrl+C to stop`) + (process.platform === "win32" ? pc.dim(".\n\n") : pc.dim(" (or run: keel down).\n\n")));
+    await new Promise((resolve) => {
+        const exitIfDead = (name) => (code) => {
+            if (code !== null && code !== 0) {
+                process.stderr.write(pc.red(`${name} exited with code ${code}\n`));
+                void teardown().then(() => process.exit(code ?? 1));
+            }
+            else if (code !== null) {
+                process.stdout.write(pc.dim(`${name} exited cleanly\n`));
+                void teardown().then(() => resolve());
+            }
+        };
+        apiProc.on("exit", exitIfDead("API"));
+        uiProc.on("exit", exitIfDead("UI"));
+    });
+}
+// ── Lifecycle commands: status / down / open / restart ──────────────────────
+// These give keel an app-like lifecycle from any terminal, not just the one that
+// ran `keel up`. They all resolve the same config (port/container) and rely on
+// detectKeelApi's fingerprint to act on a real keel rather than a stranger.
+async function probeOk(url, timeoutMs = 2000) {
+    try {
+        const res = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) });
+        return res.ok;
+    }
+    catch {
+        return false;
+    }
+}
+export async function probeStatus(config) {
+    const [apiUp, uiUp] = await Promise.all([detectKeelApi(config.apiUrl), probeOk(config.uiUrl)]);
+    return { apiUp, uiUp, dbStatus: dockerContainerStatus(config.dockerContainer) };
+}
+function statusDot(up) {
+    return up ? pc.green("●") : pc.red("○");
+}
+// `keel status` — where is the workspace and is it up? Returns true iff both API
+// and UI answer, so the command can exit non-zero for scripting.
+export async function runStatus(opts = {}) {
+    const config = opts.config ?? resolveConfig();
+    const status = await probeStatus(config);
+    const dbUp = status.dbStatus === "running";
+    const dbLabel = status.dbStatus === "absent"
+        ? pc.dim("external / not managed")
+        : status.dbStatus === "running"
+            ? pc.green("running")
+            : pc.yellow("stopped");
+    process.stdout.write(pc.bold("\nkeel status\n\n") +
+        `  ${statusDot(status.apiUp)} API   ${pc.dim(config.apiUrl)}  ${status.apiUp ? pc.green("running") : pc.red("stopped")}\n` +
+        `  ${statusDot(status.uiUp)} UI    ${pc.dim(config.uiUrl)}  ${status.uiUp ? pc.green("running") : pc.red("stopped")}\n` +
+        `  ${statusDot(dbUp)} DB    ${pc.dim(config.dockerContainer)}  ${dbLabel}\n\n`);
+    // Surface other workspaces running on different ports (multi-instance support).
+    const others = listLocks().filter((l) => l.apiPort !== config.apiPort);
+    if (others.length > 0) {
+        process.stdout.write(pc.dim(`  other instances on: ${others.map((o) => `:${o.apiPort}`).join(", ")}  (KEEL_API_PORT=<port> keel status)\n\n`));
+    }
+    return status.apiUp && status.uiUp;
+}
+// `keel down` — stop the workspace from any terminal. Kills the process GROUP of
+// whatever currently listens on keel's API/UI ports (verified as keel via the
+// /health fingerprint), stops the managed DB container, and clears the lockfile.
+// It targets live port owners, never a recorded PID — so it cannot kill a
+// recycled PID or orphan a wrapper-forked dev server.
+export async function runDown(opts = {}) {
+    const config = opts.config ?? resolveConfig();
+    const warnings = [];
+    if (process.platform === "win32") {
+        // Process-group reaping is POSIX-only; be honest rather than silently failing.
+        process.stdout.write(pc.yellow("keel down is not supported on Windows yet.\n") +
+            pc.dim("  Stop the workspace with Ctrl+C in the terminal running keel up.\n"));
+        return { wasRunning: false, warnings: ["windows-unsupported"] };
+    }
+    const lock = readLock(config.apiPort);
+    const isKeel = await detectKeelApi(config.apiUrl);
+    if (!isKeel) {
+        if (lock) {
+            removeLock(config.apiPort);
+            process.stdout.write(pc.dim("keel was not running (cleared a stale lockfile).\n"));
+        }
+        else {
+            process.stdout.write(pc.dim("keel is not running.\n"));
+        }
+        return { wasRunning: false, warnings };
+    }
+    process.stdout.write(pc.dim("stopping keel...\n"));
+    const outcome = await stopListenersOnPorts([config.apiPort, config.uiPort]);
+    // Stop the managed DB container (named in the lockfile, else the configured
+    // default) only when it actually runs — an external DATABASE_URL has none.
+    const container = lock?.dockerContainer ?? config.dockerContainer;
+    if (container && dockerContainerStatus(container) === "running") {
+        if (!stopDockerContainer(container)) {
+            warnings.push(`could not stop the database container — stop it with: docker stop ${container}`);
+        }
+    }
+    removeLock(config.apiPort);
+    // Confirm the API port actually freed; if it still answers it may be respawning.
+    if (await detectKeelApi(config.apiUrl)) {
+        warnings.push(`the API still answers on ${config.apiUrl} — check: lsof -nP -iTCP:${config.apiPort} -sTCP:LISTEN`);
+    }
+    const reaped = outcome.killedGroups.length;
+    process.stdout.write(warnings.map((w) => pc.yellow(`  ${w}\n`)).join("") +
+        pc.green(`✓ keel stopped (${reaped} process group${reaped === 1 ? "" : "s"} reaped)\n`));
+    return { wasRunning: true, warnings };
+}
+// `keel open` — reopen the workspace in the browser, if it's running.
+export async function runOpen(opts = {}) {
+    const config = opts.config ?? resolveConfig();
+    if (await detectKeelApi(config.apiUrl)) {
+        process.stdout.write(pc.dim(`opening ${config.uiUrl}\n`));
+        openBrowser(config.uiUrl);
+        return true;
+    }
+    process.stdout.write(pc.yellow("keel isn't running — start it with: keel up\n"));
+    return false;
+}
+// `keel restart` — stop a running instance (if any), then boot fresh. runUp takes
+// over the foreground as usual.
+export async function runRestart(opts = {}) {
+    await runDown({ ...(opts.config ? { config: opts.config } : {}) });
+    await runUp(opts);
+}
+//# sourceMappingURL=up.js.map