getculpa 0.0.1 → 1.0.1

package/lib/repair.mjs

@@ -0,0 +1,135 @@
+// CF20-T5 — `getculpa repair`. Re-stages missing/corrupt parity files from
+// the packaged assets, regenerates install-state.json if unreadable,
+// re-fetches a missing launcher/collectord, and does none of this
+// destructively: an EXISTING docker-compose.yml (the live pin) is never
+// touched (the edcf97f invariant this task's reviewer condition names), no
+// `docker volume` command is ever issued (data is never touched), and a
+// second run changes nothing that was already healthy (idempotent).
+//
+// Reuses lib/provision.mjs's own stageParityFiles/stageLiveComposeIfAbsent
+// (exported additively for this purpose — see that file's comment) instead
+// of re-implementing file staging here.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync as realSpawnSync } from "node:child_process";
+import { stageLiveComposeIfAbsent, stageParityFiles, PARITY_ASSETS } from "./provision.mjs";
+import { fetchCollectord, fetchLauncher } from "./fetch.mjs";
+import { checkDockerEngineReachable, checkDockerPresent } from "./preflight.mjs";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const packageRoot = path.join(__dirname, "..");
+
+function readJsonSafe(filePath) {
+  try {
+    return JSON.parse(readFileSync(filePath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function detectDockerState(dockerSpawnSync) {
+  if (!checkDockerPresent(dockerSpawnSync)) return "missing";
+  if (!checkDockerEngineReachable(dockerSpawnSync)) return "installed-not-running";
+  return "ready";
+}
+
+function vendorBinaryPath(vendorDir, name, platform) {
+  const exe = platform === "win32" ? ".exe" : "";
+  return path.join(vendorDir, `${name}${exe}`);
+}
+
+export async function repair(opts) {
+  const {
+    appDir,
+    currentVersion,
+    platform = process.platform,
+    vendorDir = path.join(packageRoot, "vendor"),
+    dockerSpawnSync = realSpawnSync,
+    fetchLauncherFn = fetchLauncher,
+    fetchCollectordFn = fetchCollectord,
+    log = console.log,
+  } = opts;
+
+  const actions = [];
+
+  if (!existsSync(appDir)) {
+    mkdirSync(appDir, { recursive: true });
+    actions.push(`created the missing app directory (${appDir})`);
+  }
+
+  // 1. Parity files — re-stage anything missing. stageParityFiles never
+  //    touches docker-compose.yml (it doesn't reference that name at all),
+  //    so this step alone already satisfies "never touch a live compose".
+  const missingBefore = PARITY_ASSETS.filter((name) => !existsSync(path.join(appDir, name)));
+  stageParityFiles(appDir);
+  for (const name of missingBefore) {
+    actions.push(`restored missing parity file: ${name}`);
+  }
+
+  // 2. Live compose — created ONLY if entirely absent; an existing one is
+  //    never overwritten (stageLiveComposeIfAbsent's own contract).
+  const composeCreated = stageLiveComposeIfAbsent(appDir);
+  if (composeCreated) {
+    actions.push("live docker-compose.yml was missing - recreated from the shipped culpa-compose.yml");
+  }
+
+  // 3. install-state.json — regenerate only when missing/corrupt. The
+  //    regenerated state is a conservative snapshot of what is actually on
+  //    disk right now: dockerState/collectorStaged are re-detected,
+  //    imagesStaged is set false (safe default — worst case is one extra
+  //    `docker compose pull` message at the next `getculpa`, never data
+  //    loss, mirroring deferredPullCatchUp's own contract in lib/start.mjs).
+  const existingState = readJsonSafe(path.join(appDir, "install-state.json"));
+  if (!existingState) {
+    const dockerState = detectDockerState(dockerSpawnSync);
+    const collectorStaged = existsSync(vendorBinaryPath(vendorDir, "culpa-collectord", platform));
+    const regenerated = {
+      packageVersion: currentVersion,
+      provisionedAt: new Date().toISOString(),
+      dockerState,
+      imagesStaged: false,
+      collectorStaged,
+      platform,
+    };
+    writeFileSync(path.join(appDir, "install-state.json"), `${JSON.stringify(regenerated, null, 2)}\n`);
+    actions.push("install-state.json was missing or unreadable - regenerated");
+  }
+
+  // 4. Launcher / collectord — re-fetch only when the vendored binary is
+  //    genuinely absent. Never re-fetches when present (idempotent, and the
+  //    task's explicit invocation-recording fact). The launcher is REQUIRED
+  //    (doctor.mjs's checkVendoredLauncher fails the same way when it's
+  //    missing) — a failed re-fetch must make repair's own result say so,
+  //    not just log and report ok:true (CF20-R review). The collector stays
+  //    optional/non-fatal: capture-off is a valid degraded state.
+  const launcherPath = vendorBinaryPath(vendorDir, "culpa-launcher", platform);
+  if (!existsSync(launcherPath)) {
+    try {
+      await fetchLauncherFn({ vendorDir });
+      actions.push("the launcher was missing - re-fetched and verified");
+    } catch (e) {
+      log(`getculpa repair: could not re-fetch the launcher (${e.message}). Run \`getculpa repair\` again once online.`);
+    }
+  }
+
+  const collectordPath = vendorBinaryPath(vendorDir, "culpa-collectord", platform);
+  if (!existsSync(collectordPath)) {
+    try {
+      await fetchCollectordFn({ vendorDir });
+      actions.push("the capture collector was missing - re-fetched and verified");
+    } catch (e) {
+      // fetchCollectord's own contract: "not published for this release yet"
+      // is an expected, non-fatal outcome (see lib/fetch.mjs) — repair must
+      // degrade the same way, never abort over an optional component.
+      log(`getculpa repair: capture collector not re-fetched (${e.message}).`);
+    }
+  }
+
+  if (actions.length === 0) log("getculpa repair: nothing to do - this install is already healthy.");
+  else for (const a of actions) log(`getculpa repair: ${a}`);
+
+  const launcherOk = existsSync(launcherPath);
+  return { ok: launcherOk, actions };
+}

package/lib/start.d.mts

@@ -0,0 +1,42 @@
+import type { SpawnSyncLike, FetchLike } from "./docker.d.mts";
+
+export const STAGES: {
+  readonly CHECK_INSTALLATION: "CHECK_INSTALLATION";
+  readonly CHECK_DOCKER: "CHECK_DOCKER";
+  readonly IDEMPOTENCY_CHECK: "IDEMPOTENCY_CHECK";
+  readonly PORT_CHECK: "PORT_CHECK";
+  readonly START_DOCKER_IF_REQUIRED: "START_DOCKER_IF_REQUIRED";
+  readonly WAIT_FOR_DOCKER: "WAIT_FOR_DOCKER";
+  readonly PREPARE_RUNTIME: "PREPARE_RUNTIME";
+  readonly START_CULPA_DEPENDENCIES: "START_CULPA_DEPENDENCIES";
+  readonly RUN_REQUIRED_MIGRATIONS: "RUN_REQUIRED_MIGRATIONS";
+  readonly HEALTH_CHECK: "HEALTH_CHECK";
+  readonly START_CULPA: "START_CULPA";
+  readonly OPEN_UI: "OPEN_UI";
+};
+
+export interface StartOptions {
+  appDir: string;
+  currentVersion?: string;
+  platform?: string;
+  spawnSync?: SpawnSyncLike;
+  fetchFn?: FetchLike;
+  sleepFn?: (ms: number) => Promise<void>;
+  env?: Record<string, string | undefined>;
+  log?: (msg: string) => void;
+  warn?: (msg: string) => void;
+  openBrowser?: (url: string) => void;
+  isTTY?: boolean;
+  delegateWindowsLaunch?: (appDir: string) => { ok: boolean; output?: string };
+}
+
+export interface StartResult {
+  ok: boolean;
+  stage: string;
+  message?: string;
+  recovery?: string;
+  alreadyRunning?: boolean;
+  stagesRun: string[];
+}
+
+export function start(opts: StartOptions): Promise<StartResult>;

package/lib/start.mjs

@@ -0,0 +1,392 @@
+// 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,
+  startEngineIfPossible,
+  waitForDockerEngine,
+  waitForHealth,
+  waitForPgReady,
+} from "./docker.mjs";
+import { checkDockerPresent, compareVersions, parsePinnedServerVersion } from "./preflight.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 };
+}
+
+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,
+  } = 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)) {
+    return {
+      ...fail(STAGES.CHECK_DOCKER, "Culpa couldn't start Docker.", "Install Docker (https://docs.docker.com/get-docker/), then run `getculpa` again."),
+      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");
+}