getculpa 0.0.1 → 1.0.2

package/lib/start.mjs

@@ -0,0 +1,479 @@
+// CF20-T4 — `getculpa` / `getculpa start`: wakes the dormant stack.
+//
+// Windows: Node runs the platform-agnostic pre-checks (installed? docker
+// present? already running? ports free?) then DELEGATES everything else —
+// Docker-engine ensure/authorize/start+poll, QW-1/3/4 guards, `compose up`,
+// collector restart, health wait, registry sync, browser open — to the
+// STAGED launch-culpa.ps1 (installers/windows/launch-culpa.ps1, copied into
+// the app dir by provision.mjs's PARITY_ASSETS). That script is the
+// semantics source (see the task's own instruction); this module must never
+// re-implement or diverge from what it does. In particular,
+// launch-culpa.ps1:179-234 ALSO owns "Docker isn't installed" (its own
+// WPF authorize-then-winget-install flow) — so CHECK_DOCKER is
+// informational-only on win32, never a hard gate: failing fast here would
+// skip that flow and regress existing UX for a founder on a fresh machine.
+//
+// macOS/Linux: no launch-culpa.ps1 exists there, so this module implements
+// the SAME state machine directly, reusing lib/docker.mjs's helpers and
+// lib/preflight.mjs's version-parsing (the same functions QW-1/3 use, so
+// the two guard implementations can never disagree about what "a pin" is).
+// CHECK_DOCKER IS a hard gate there: there is no interactive installer flow
+// on these platforms in this task's scope (linux especially — no
+// `systemctl start docker` without explicit consent, per the task's hard
+// rules), so a missing/unreachable engine fails fast with one recovery step.
+
+import { spawnSync as realSpawnSync } from "node:child_process";
+import { copyFileSync, existsSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import {
+  checkDockerEngineReachable,
+  dbContainerExists,
+  findPortOwner,
+  isBackupNeeded,
+  isProjectRunning,
+  preMigrationBackup,
+  probeHealth,
+  resolveBackupBaseline,
+  installDockerDarwin,
+  startEngineIfPossible,
+  waitForDockerEngine,
+  waitForHealth,
+  waitForPgReady,
+} from "./docker.mjs";
+import { checkDockerPresent, compareVersions, parsePinnedServerVersion } from "./preflight.mjs";
+import { askYesNo as realAskYesNo } from "./tty.mjs";
+
+export const STAGES = Object.freeze({
+  CHECK_INSTALLATION: "CHECK_INSTALLATION",
+  CHECK_DOCKER: "CHECK_DOCKER",
+  IDEMPOTENCY_CHECK: "IDEMPOTENCY_CHECK",
+  PORT_CHECK: "PORT_CHECK",
+  START_DOCKER_IF_REQUIRED: "START_DOCKER_IF_REQUIRED",
+  WAIT_FOR_DOCKER: "WAIT_FOR_DOCKER",
+  PREPARE_RUNTIME: "PREPARE_RUNTIME",
+  START_CULPA_DEPENDENCIES: "START_CULPA_DEPENDENCIES",
+  RUN_REQUIRED_MIGRATIONS: "RUN_REQUIRED_MIGRATIONS",
+  HEALTH_CHECK: "HEALTH_CHECK",
+  START_CULPA: "START_CULPA",
+  OPEN_UI: "OPEN_UI",
+});
+
+const DASHBOARD_URL = "http://127.0.0.1:3000";
+const DASHBOARD_URL_FRIENDLY = "http://localhost:3000";
+const PORTS_TO_CHECK = [3000, 4545];
+
+function fail(stage, message, recovery) {
+  return { ok: false, stage, message, recovery };
+}
+
+function readInstallState(appDir) {
+  try {
+    return JSON.parse(readFileSync(path.join(appDir, "install-state.json"), "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function writeInstallState(appDir, state) {
+  writeFileSync(path.join(appDir, "install-state.json"), `${JSON.stringify(state, null, 2)}\n`);
+}
+
+// PREPARE_RUNTIME's deferred-pull half (both platforms). DECISION (documented
+// per task instructions): `docker compose up` DOES auto-pull any image
+// missing locally by default (pull_policy: missing), so skipping this call
+// entirely would still work correctly — the reason to keep it is the
+// MESSAGE, not correctness. provision.mjs stages images with `docker compose
+// pull` when the engine is reachable at npm-install time; when it wasn't,
+// install-state.json is left with imagesStaged:false and the pull is caught
+// up HERE, on the first `getculpa`, labelled honestly, so a first-run
+// multi-GB pull is never silently absorbed into `compose up`'s own output or
+// (on win32) into launch-culpa.ps1's health-wait window. Pulls the SHIPPED
+// compose (culpa-compose.yml), matching provision.mjs's own stageImages() —
+// on an upgrade this pre-pulls the version that is about to become live via
+// QW-1, rather than the (possibly stale) currently-live pin.
+function deferredPullCatchUp({ appDir, spawnSync, log, warn }) {
+  const state = readInstallState(appDir);
+  if (state?.imagesStaged === true) return;
+  const shipped = path.join(appDir, "culpa-compose.yml");
+  if (!existsSync(shipped)) return;
+  log("==> Pulling Culpa's container images (first run - this can take a few minutes)");
+  const r = spawnSync("docker", ["compose", "-f", shipped, "-p", "culpa", "pull"], { stdio: "inherit" });
+  if (r.status !== 0) {
+    warn("getculpa: image pull did not complete cleanly - `docker compose up` will retry it.");
+    return;
+  }
+  if (state) writeInstallState(appDir, { ...state, imagesStaged: true });
+}
+
+// Ported from Test-BackwardPin (launch-culpa.ps1:97-103) byte-for-byte:
+// a malformed pin against a well-formed known baseline fails CLOSED (refuse);
+// both-unparsable and no-baseline stay permissive.
+function isBackwardPin(pinnedVersion, lastBootVersion) {
+  if (!pinnedVersion || !pinnedVersion.trim()) return false;
+  if (!lastBootVersion || !lastBootVersion.trim()) return false;
+  const rx = /^v?(\d+)\.(\d+)\.(\d+)/;
+  if (!rx.test(pinnedVersion) && rx.test(lastBootVersion)) return true;
+  return compareVersions(pinnedVersion, lastBootVersion) === -1;
+}
+
+// QW-1/3/4, ported from launch-culpa.ps1:257-316. Returns { pinnedVersion }
+// to continue, or a fail() result to abort BEFORE anything else is started —
+// same fail-closed contract as the .ps1. non-win32 only (win32 delegates
+// these three guards to the .ps1 itself).
+async function runVersionGuards({ appDir, liveCompose, spawnSync, env, log, warn, sleepFn }) {
+  const shippedPath = path.join(appDir, "culpa-compose.yml");
+  if (existsSync(shippedPath)) {
+    const shippedVer = parsePinnedServerVersion(readFileSync(shippedPath, "utf8"));
+    const liveVer = parsePinnedServerVersion(readFileSync(liveCompose, "utf8"));
+    if (shippedVer && liveVer && compareVersions(shippedVer, liveVer) === 1) {
+      copyFileSync(shippedPath, liveCompose);
+      log("==> Upgrade detected: live compose re-pinned from the shipped culpa-compose.yml");
+    }
+  }
+
+  const pinnedVersion = parsePinnedServerVersion(readFileSync(liveCompose, "utf8"));
+  const lastBootFile = path.join(appDir, "last-boot-version.txt");
+  const lastBootVersion = existsSync(lastBootFile) ? readFileSync(lastBootFile, "utf8").trim() : "";
+
+  if (isBackwardPin(pinnedVersion, lastBootVersion)) {
+    if (env.CULPA_ALLOW_DOWNGRADE === "1") {
+      warn(
+        `WARNING: CULPA_ALLOW_DOWNGRADE=1 - launching an OLDER server (${pinnedVersion}) against a database last used by ${lastBootVersion}.`,
+      );
+    } else {
+      return fail(
+        STAGES.PREPARE_RUNTIME,
+        "Culpa couldn't complete the database upgrade.",
+        `The compose file pins culpa-server ${pinnedVersion}, but this machine last ran ${lastBootVersion}. Restore the ${lastBootVersion} pin, or set CULPA_ALLOW_DOWNGRADE=1 only after restoring a matching database backup, then run \`getculpa\` again.`,
+      );
+    }
+  }
+
+  const dbExists = dbContainerExists(spawnSync);
+  const baseline = resolveBackupBaseline(lastBootVersion, spawnSync);
+  if (!isBackupNeeded(dbExists, pinnedVersion, baseline)) return { pinnedVersion };
+
+  if (env.CULPA_SKIP_BACKUP === "1") {
+    warn(`WARNING: CULPA_SKIP_BACKUP=1 - upgrading ${baseline || "unknown"} -> ${pinnedVersion} WITHOUT a database backup.`);
+    return { pinnedVersion };
+  }
+
+  log(`==> Version change (${baseline || "unknown"} -> ${pinnedVersion}): backing up the database first`);
+  const up = spawnSync("docker", ["compose", "-f", liveCompose, "-p", "culpa", "up", "-d", "db"]);
+  if (up.status !== 0) {
+    return fail(
+      STAGES.PREPARE_RUNTIME,
+      "Culpa couldn't reach its local database.",
+      "Could not start the database container to take the pre-upgrade backup. Check `docker logs culpa-db`, then run `getculpa` again.",
+    );
+  }
+  const pgReady = await waitForPgReady({ spawnSync, sleepFn });
+  if (!pgReady) {
+    return fail(
+      STAGES.PREPARE_RUNTIME,
+      "Culpa couldn't reach its local database.",
+      "The database did not become ready within 60s, so the pre-upgrade backup could not be taken. Nothing was upgraded. Run `getculpa` again.",
+    );
+  }
+  try {
+    const dump = preMigrationBackup({ backupDir: path.join(appDir, "backups"), tag: baseline || "unknown", spawnSync });
+    log(`==> Backup verified: ${dump}`);
+  } catch (e) {
+    return fail(
+      STAGES.PREPARE_RUNTIME,
+      "Culpa couldn't complete the database upgrade.",
+      `Pre-upgrade backup failed (${e.message}). Nothing was upgraded. Set CULPA_SKIP_BACKUP=1 to launch without a backup (not recommended), then run \`getculpa\` again.`,
+    );
+  }
+  return { pinnedVersion };
+}
+
+// T-CF28-7 — "The install fails to ask for docker and other dependencies. IT
+// MUST ASK AND INSTALL THESE" (founder). This is the ASK half; the DETECT half
+// runs at npm-install time (lib/install-summary.mjs), because postinstall
+// cannot prompt (scripts/install.js:13-15).
+//
+// Reached only when Docker is genuinely absent on a non-win32 platform. Every
+// branch ends in a fail() — even a SUCCESSFUL install, because Docker Desktop
+// still needs one manual launch before its engine answers. That mirrors
+// launch-culpa.ps1:233, which likewise stops after installing rather than
+// pretending the stack is coming up.
+const DOCKER_DESKTOP_URL = "https://www.docker.com/products/docker-desktop/";
+const DOCKER_ENGINE_DOCS_URL = "https://docs.docker.com/engine/install/";
+const DOCKER_MISSING = "Culpa couldn't start: Docker is not installed.";
+
+// The consent text IS the disclosure. It names the exact command, that a
+// password will be asked for, and that a manual first launch is still
+// required — so nobody agrees to a "one-click install" that isn't one.
+const DARWIN_CONSENT_QUESTION =
+  "Culpa needs Docker to run, and it was not found on this machine.\n" +
+  "Install it now with `brew install --cask docker`?\n" +
+  "  Homebrew will ask for your password, and afterwards you must open Docker once\n" +
+  "  from Applications - this cannot be a fully hands-off install.\n" +
+  "  Nothing is downloaded unless you answer yes.\n" +
+  "Install Docker now? (y/N) ";
+
+async function offerDockerInstall({ platform, spawnSync, log, askYesNo, isInteractive }) {
+  // linux: installing a system package without explicit consent is out of
+  // bounds — the same rule startEngineIfPossible already follows for merely
+  // STARTING the engine (docker.mjs:73-79). Guidance only, and no prompt: a
+  // yes here could not be honoured anyway.
+  if (platform !== "darwin") {
+    return fail(
+      STAGES.CHECK_DOCKER,
+      DOCKER_MISSING,
+      `Culpa runs its database and services in containers. Install Docker Engine (${DOCKER_ENGINE_DOCS_URL}), then run \`getculpa\` again. Culpa will not install system packages for you.`,
+    );
+  }
+
+  if (!isInteractive) {
+    return fail(
+      STAGES.CHECK_DOCKER,
+      DOCKER_MISSING,
+      `Culpa runs its database and services in containers. Install it with \`brew install --cask docker\` (or download it from ${DOCKER_DESKTOP_URL}), open Docker once, then run \`getculpa\` again.`,
+    );
+  }
+
+  if (!(await askYesNo(DARWIN_CONSENT_QUESTION))) {
+    return fail(
+      STAGES.CHECK_DOCKER,
+      DOCKER_MISSING,
+      `The Docker install was not authorized, so nothing was installed and nothing was changed. Install it yourself with \`brew install --cask docker\` or from ${DOCKER_DESKTOP_URL}, then run \`getculpa\` again.`,
+    );
+  }
+
+  log("==> Installing Docker Desktop with Homebrew (brew install --cask docker)");
+  const outcome = installDockerDarwin(spawnSync);
+
+  if (outcome === "no-brew") {
+    return fail(
+      STAGES.CHECK_DOCKER,
+      DOCKER_MISSING,
+      `Homebrew is not available, so Docker could not be installed automatically. Nothing was changed. Download Docker Desktop from ${DOCKER_DESKTOP_URL}, open it once, then run \`getculpa\` again.`,
+    );
+  }
+  if (outcome !== "installed") {
+    const code = outcome.replace(/^failed:/, "");
+    return fail(
+      STAGES.CHECK_DOCKER,
+      DOCKER_MISSING,
+      `Homebrew could not install Docker (exit code ${code}). Nothing else was changed. Install Docker Desktop from ${DOCKER_DESKTOP_URL}, open it once, then run \`getculpa\` again.`,
+    );
+  }
+  return fail(
+    STAGES.CHECK_DOCKER,
+    "Docker was installed. Culpa has not started yet.",
+    "Open Docker once from Applications and wait for it to finish starting, then run `getculpa` again.",
+  );
+}
+
+function maybeOpenBrowser({ env, isTTY, openBrowser }) {
+  if (!isTTY) return;
+  if (env.CULPA_NO_BROWSER) return;
+  openBrowser(DASHBOARD_URL_FRIENDLY);
+}
+
+function defaultOpenBrowser(url) {
+  if (process.platform === "darwin") return void realSpawnSync("open", [url]);
+  if (process.platform === "linux") return void realSpawnSync("xdg-open", [url]);
+  realSpawnSync("cmd.exe", ["/c", "start", "", url]);
+}
+
+// Real win32 delegate: no flags — the launched script is the one the
+// Windows installer's own shortcut runs, unmodified. Captures output (rather
+// than pure stdio:"inherit") so mapWindowsFailure() can name the failing
+// layer on a non-zero exit; the captured text is still echoed to the caller.
+function defaultDelegateWindowsLaunch(appDir) {
+  const script = path.join(appDir, "launch-culpa.ps1");
+  const result = realSpawnSync("powershell.exe", ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", script], {
+    encoding: "utf8",
+  });
+  if (result.stdout) process.stdout.write(result.stdout);
+  if (result.stderr) process.stderr.write(result.stderr);
+  return { ok: result.status === 0, output: `${result.stdout ?? ""}\n${result.stderr ?? ""}` };
+}
+
+// Best-effort text match against launch-culpa.ps1's own Fail() messages
+// (verbatim strings at :223/227/231/243/251/276/301/308/313/323/340) so a
+// win32 failure still gets ONE of the canonical layer-naming messages
+// instead of a raw non-zero exit code. Order matters — first match wins.
+const WINDOWS_FAILURE_MAP = [
+  [/docker desktop|winget|docker.*not (running|found)/i, "Culpa couldn't start Docker.", "Start Docker Desktop yourself, wait for the whale icon to settle, then run `getculpa` again."],
+  [/pre-upgrade backup|pg_dump|OLDER server|pinned server/i, "Culpa couldn't complete the database upgrade.", "See the output above for the exact reason, then run `getculpa` again (set CULPA_SKIP_BACKUP=1 or CULPA_ALLOW_DOWNGRADE=1 only if you understand the risk)."],
+  [/dashboard did not answer/i, "Culpa's dashboard didn't come up in time.", "Run `docker logs culpa-dashboard` to see why, then run `getculpa` again."],
+  [/could not start the culpa services/i, "Culpa couldn't start its services.", "See the output above for the exact Docker error, then run `getculpa` again."],
+];
+
+function mapWindowsFailure(output) {
+  for (const [re, message, recovery] of WINDOWS_FAILURE_MAP) {
+    if (re.test(output)) return { stage: STAGES.START_CULPA_DEPENDENCIES, message, recovery };
+  }
+  return {
+    stage: STAGES.START_CULPA_DEPENDENCIES,
+    message: "Culpa couldn't start.",
+    recovery: "See the output above for details, then run `getculpa` again (or `getculpa status` for diagnostics).",
+  };
+}
+
+async function runIdempotencyCheck({ spawnSync, fetchFn, log, env, isTTY, openBrowser }) {
+  const running = isProjectRunning(spawnSync);
+  const healthy = running && (await probeHealth(DASHBOARD_URL, { fetchFn }));
+  if (!healthy) return { running };
+  log(`Culpa is already running - ${DASHBOARD_URL_FRIENDLY}`);
+  maybeOpenBrowser({ env, isTTY, openBrowser });
+  return { running, alreadyHealthy: true };
+}
+
+function checkPortConflicts({ running, platform, spawnSync }) {
+  if (running) return null; // our own project may legitimately hold these ports
+  for (const port of PORTS_TO_CHECK) {
+    const owner = findPortOwner(port, { platform, spawnSync });
+    if (owner) {
+      return fail(
+        STAGES.PORT_CHECK,
+        `Culpa couldn't start because port ${port} is already in use by ${owner.name} (pid ${owner.pid}).`,
+        `Stop ${owner.name} yourself (Culpa will never do this for you), then run \`getculpa\` again.`,
+      );
+    }
+  }
+  return null;
+}
+
+async function runWindowsDelegate({ appDir, spawnSync, log, warn, delegateWindowsLaunch, stagesRun }) {
+  stagesRun.push(STAGES.PREPARE_RUNTIME);
+  deferredPullCatchUp({ appDir, spawnSync, log, warn });
+
+  stagesRun.push(
+    STAGES.START_CULPA_DEPENDENCIES,
+    STAGES.RUN_REQUIRED_MIGRATIONS,
+    STAGES.HEALTH_CHECK,
+    STAGES.START_CULPA,
+    STAGES.OPEN_UI,
+  );
+  log("==> Delegating to launch-culpa.ps1 (Docker ensure, compose up, collector, health wait, browser)");
+  const result = delegateWindowsLaunch(appDir);
+  if (!result.ok) {
+    const mapped = mapWindowsFailure(result.output ?? "");
+    return { ok: false, stage: mapped.stage, message: mapped.message, recovery: mapped.recovery, stagesRun };
+  }
+  return { ok: true, stage: STAGES.OPEN_UI, stagesRun };
+}
+
+async function runPosixStateMachine({ appDir, liveCompose, platform, spawnSync, fetchFn, sleepFn, env, log, warn, openBrowser, isTTY, stagesRun }) {
+  stagesRun.push(STAGES.START_DOCKER_IF_REQUIRED);
+  let engineReady = checkDockerEngineReachable(spawnSync);
+  if (!engineReady) {
+    startEngineIfPossible(platform, spawnSync, log);
+    stagesRun.push(STAGES.WAIT_FOR_DOCKER);
+    engineReady = await waitForDockerEngine({ spawnSync, sleepFn });
+    if (!engineReady) {
+      return {
+        ...fail(
+          STAGES.WAIT_FOR_DOCKER,
+          "Culpa couldn't start Docker.",
+          "Start Docker (or Docker Desktop) yourself, wait for it to finish starting, then run `getculpa` again.",
+        ),
+        stagesRun,
+      };
+    }
+  } else {
+    stagesRun.push(STAGES.WAIT_FOR_DOCKER);
+  }
+
+  stagesRun.push(STAGES.PREPARE_RUNTIME);
+  deferredPullCatchUp({ appDir, spawnSync, log, warn });
+  const guardResult = await runVersionGuards({ appDir, liveCompose, spawnSync, env, log, warn, sleepFn });
+  if (guardResult.ok === false) return { ...guardResult, stagesRun };
+  const { pinnedVersion } = guardResult;
+
+  stagesRun.push(STAGES.START_CULPA_DEPENDENCIES);
+  const up = spawnSync("docker", ["compose", "-f", liveCompose, "-p", "culpa", "up", "-d"], { stdio: "inherit" });
+  if (up.status !== 0) {
+    return {
+      ...fail(STAGES.START_CULPA_DEPENDENCIES, "Culpa couldn't start its services.", "Docker's own error is above. Fix it, then run `getculpa` again."),
+      stagesRun,
+    };
+  }
+
+  // RUN_REQUIRED_MIGRATIONS is compose-internal: the culpa-server image's
+  // container CMD runs culpa-migrate BEFORE the server binary starts (no
+  // compose override) — verified in native/culpa-api/src/main.rs:5-10. There
+  // is nothing for Node to invoke; HEALTH_CHECK below is the real signal
+  // that migrations finished, since the server never answers until they do.
+  stagesRun.push(STAGES.RUN_REQUIRED_MIGRATIONS);
+
+  stagesRun.push(STAGES.HEALTH_CHECK);
+  const healthy = await waitForHealth(DASHBOARD_URL, { sleepFn, fetchFn });
+  if (!healthy) {
+    return {
+      ...fail(
+        STAGES.HEALTH_CHECK,
+        "Culpa's dashboard didn't come up in time.",
+        "Run `docker logs culpa-dashboard` (or `getculpa status`) to see why, then run `getculpa` again.",
+      ),
+      stagesRun,
+    };
+  }
+
+  // No collectord build/staging exists for macOS/Linux yet (task scope) —
+  // degrade honestly rather than fail the whole launch over capture.
+  stagesRun.push(STAGES.START_CULPA);
+  log("getculpa: capture is OFF on this platform for now (no collector build ships for macOS/Linux yet) - everything else works normally.");
+
+  stagesRun.push(STAGES.OPEN_UI);
+  if (pinnedVersion) writeFileSync(path.join(appDir, "last-boot-version.txt"), `${pinnedVersion}\n`);
+  maybeOpenBrowser({ env, isTTY, openBrowser });
+
+  return { ok: true, stage: STAGES.OPEN_UI, stagesRun };
+}
+
+export async function start(opts) {
+  const {
+    appDir,
+    platform = process.platform,
+    spawnSync = realSpawnSync,
+    fetchFn,
+    sleepFn,
+    env = process.env,
+    log = console.log,
+    warn = console.warn,
+    openBrowser = defaultOpenBrowser,
+    isTTY = process.stdout.isTTY,
+    delegateWindowsLaunch = defaultDelegateWindowsLaunch,
+    // T-CF28-7: consent needs BOTH ends of the terminal — stdin to read the
+    // answer, stdout for the question. isTTY above is stdout-only (it gates
+    // the browser open), so it cannot stand in for this.
+    isInteractive = Boolean(process.stdin.isTTY && process.stdout.isTTY),
+    askYesNo = (question) => realAskYesNo(question, { isInteractive }),
+  } = opts;
+
+  const stagesRun = [STAGES.CHECK_INSTALLATION];
+  const liveCompose = path.join(appDir, "docker-compose.yml");
+  if (!existsSync(appDir) || !existsSync(liveCompose)) {
+    return { ...fail(STAGES.CHECK_INSTALLATION, "Culpa is not installed.", "Run `npm i -g getculpa` (or reinstall it) first."), stagesRun };
+  }
+
+  stagesRun.push(STAGES.CHECK_DOCKER);
+  if (platform !== "win32" && !checkDockerPresent(spawnSync)) {
+    // T-CF28-7: was a dead end with a bare URL. Still a hard gate — nothing
+    // below can work without Docker — but on darwin it now offers to install
+    // it first. win32 is deliberately excluded (see this file's header):
+    // launch-culpa.ps1:179-234 owns that flow and must not be short-circuited.
+    return { ...(await offerDockerInstall({ platform, spawnSync, log, askYesNo, isInteractive })), stagesRun };
+  }
+
+  stagesRun.push(STAGES.IDEMPOTENCY_CHECK);
+  const idempotency = await runIdempotencyCheck({ spawnSync, fetchFn, log, env, isTTY, openBrowser });
+  if (idempotency.alreadyHealthy) {
+    return { ok: true, stage: STAGES.IDEMPOTENCY_CHECK, alreadyRunning: true, stagesRun };
+  }
+
+  stagesRun.push(STAGES.PORT_CHECK);
+  const portConflict = checkPortConflicts({ running: idempotency.running, platform, spawnSync });
+  if (portConflict) return { ...portConflict, stagesRun };
+
+  if (platform === "win32") {
+    return runWindowsDelegate({ appDir, spawnSync, log, warn, delegateWindowsLaunch, stagesRun });
+  }
+  return runPosixStateMachine({ appDir, liveCompose, platform, spawnSync, fetchFn, sleepFn, env, log, warn, openBrowser, isTTY, stagesRun });
+}

package/lib/status.d.mts

@@ -0,0 +1,23 @@
+import type { SpawnSyncLike, FetchLike } from "./docker.d.mts";
+
+export interface StatusOptions {
+  appDir?: string;
+  platform?: string;
+  spawnSync?: SpawnSyncLike;
+  fetchFn?: FetchLike;
+}
+
+export interface StatusResult {
+  installed: boolean;
+  packageVersion: string | null;
+  platform: string;
+  dockerPresent: boolean;
+  dockerReachable: boolean;
+  running: boolean;
+  dashboardHealthy: boolean;
+  serverHealthy: boolean;
+  licenseConfigured: boolean | null;
+}
+
+export function status(opts?: StatusOptions): Promise<StatusResult>;
+export function formatStatus(s: StatusResult): string;

package/lib/status.mjs

@@ -0,0 +1,74 @@
+// CF20-T4 — `getculpa status`. Every probe degrades to a known-unknown
+// value on failure; this command must never throw, and must never touch a
+// live process (detection only — starting/stopping is start.mjs/stop.mjs's
+// job). License presence is surfaced as the `configured` BOOLEAN ONLY, and
+// ONLY when the server already answered 200 — never key material, never
+// speculative against a stopped stack (native/culpa-api/src/server.rs:1695-1711).
+
+import { spawnSync as realSpawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { checkDockerEngineReachable, isProjectRunning, probeHealth } from "./docker.mjs";
+import { checkDockerPresent } from "./preflight.mjs";
+import { getAppDir } from "./paths.mjs";
+
+function readInstallState(appDir) {
+  try {
+    return JSON.parse(readFileSync(path.join(appDir, "install-state.json"), "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+async function probeServerEntitlement(fetchFn) {
+  try {
+    const res = await fetchFn("http://127.0.0.1:4545/internal/entitlement", { signal: AbortSignal.timeout(3_000) });
+    if (res.status !== 200) return { serverHealthy: false, licenseConfigured: null };
+    const body = await res.json();
+    const configured = typeof body?.configured === "boolean" ? body.configured : null;
+    return { serverHealthy: true, licenseConfigured: configured };
+  } catch {
+    return { serverHealthy: false, licenseConfigured: null };
+  }
+}
+
+export async function status(opts = {}) {
+  const appDir = opts.appDir ?? getAppDir();
+  const platform = opts.platform ?? process.platform;
+  const spawnSync = opts.spawnSync ?? realSpawnSync;
+  const fetchFn = opts.fetchFn ?? fetch;
+
+  const installed = existsSync(path.join(appDir, "docker-compose.yml"));
+  const state = installed ? readInstallState(appDir) : null;
+  const dockerPresent = checkDockerPresent(spawnSync);
+  const dockerReachable = dockerPresent && checkDockerEngineReachable(spawnSync);
+  const running = dockerReachable && isProjectRunning(spawnSync);
+
+  const dashboardHealthy = running ? await probeHealth("http://127.0.0.1:3000", { fetchFn }) : false;
+  const { serverHealthy, licenseConfigured } = running
+    ? await probeServerEntitlement(fetchFn)
+    : { serverHealthy: false, licenseConfigured: null };
+
+  return {
+    installed,
+    packageVersion: state?.packageVersion ?? null,
+    platform,
+    dockerPresent,
+    dockerReachable,
+    running,
+    dashboardHealthy,
+    serverHealthy,
+    licenseConfigured,
+  };
+}
+
+export function formatStatus(s) {
+  const line = (label, value) => `${label.padEnd(18)} ${value}`;
+  return [
+    line("Installed:", s.installed ? `yes (v${s.packageVersion ?? "unknown"})` : "no"),
+    line("Docker:", !s.dockerPresent ? "not found" : s.dockerReachable ? "running" : "installed, not running"),
+    line("Culpa stack:", s.running ? "running" : "stopped"),
+    line("Dashboard:", s.dashboardHealthy ? "healthy (http://localhost:3000)" : "not responding"),
+    line("License:", s.licenseConfigured === null ? "unknown" : s.licenseConfigured ? "configured" : "not configured"),
+  ].join("\n");
+}

package/lib/stop.d.mts

@@ -0,0 +1,15 @@
+import type { SpawnSyncLike } from "./docker.d.mts";
+
+export interface StopOptions {
+  appDir?: string;
+  platform?: string;
+  spawnSync?: SpawnSyncLike;
+  log?: (msg: string) => void;
+}
+
+export interface StopResult {
+  ok: boolean;
+  stopped: boolean;
+}
+
+export function stop(opts?: StopOptions): Promise<StopResult>;

package/lib/stop.mjs

@@ -0,0 +1,46 @@
+// CF20-T4 — `getculpa stop`.
+//
+// DECISION (see task report): uses `docker compose stop`, NOT `down`.
+// uninstall-culpa.ps1:60/65 uses `down` because uninstall is a full teardown
+// (containers + the compose network removed; named volumes are kept — no
+// `-v` flag there either). `stop` is a distinct, resumable verb: a founder
+// pausing Culpa should get a fast `getculpa` back — Compose's own paired
+// verb for `stop` is `start`/`up`, not a recreate — without losing the
+// container-level state `down` discards. The collector is a host process
+// (win32 only, D-082 — it binds 127.0.0.1 outside Docker) so it is always
+// stopped explicitly first, exactly as uninstall-culpa.ps1:43-44 does.
+
+import { spawnSync as realSpawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { getAppDir } from "./paths.mjs";
+
+export async function stop(opts = {}) {
+  const appDir = opts.appDir ?? getAppDir();
+  const platform = opts.platform ?? process.platform;
+  const spawnSync = opts.spawnSync ?? realSpawnSync;
+  const log = opts.log ?? console.log;
+
+  if (platform === "win32") {
+    const collectorCtl = path.join(appDir, "culpa-collector.ps1");
+    if (existsSync(collectorCtl)) {
+      spawnSync("powershell.exe", ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", collectorCtl, "-Stop"], {
+        stdio: "inherit",
+      });
+    }
+  }
+
+  const compose = path.join(appDir, "docker-compose.yml");
+  if (!existsSync(compose)) {
+    log("Culpa is not installed here - nothing to stop.");
+    return { ok: true, stopped: false };
+  }
+
+  const result = spawnSync("docker", ["compose", "-f", compose, "-p", "culpa", "stop"], { stdio: "inherit" });
+  if (result.status !== 0) {
+    log("getculpa: Culpa did not stop cleanly - see the output above.");
+    return { ok: false, stopped: false };
+  }
+  log("Culpa stopped.");
+  return { ok: true, stopped: true };
+}

package/lib/tty.d.mts

@@ -0,0 +1,18 @@
+export interface ColourOptions {
+  isTTY?: boolean;
+  env?: Record<string, string | undefined>;
+}
+
+export function colourEnabled(opts?: ColourOptions): boolean;
+export function green(text: string, opts?: ColourOptions): string;
+
+export interface AskYesNoOptions {
+  isInteractive?: boolean;
+  createInterface?: (opts: { input: unknown; output: unknown }) => {
+    question: (q: string, cb: (answer: string) => void) => void;
+    once: (event: string, cb: () => void) => void;
+    close: () => void;
+  };
+}
+
+export function askYesNo(question: string, opts?: AskYesNoOptions): Promise<boolean>;