getculpa 0.0.1 → 1.0.2

package/lib/provision.mjs

@@ -0,0 +1,318 @@
+// CF20-T3 — the defer-start provisioner. Lays down everything the Windows
+// installer lays down; starts nothing (compose up, collector start, and a
+// browser open are all launch-time work — CF20-T4).
+//
+// Docker interaction (presence, engine reachability, image pull) and the
+// win32 installer delegation both take injectable dependencies, defaulting
+// to the real ones. Tests MUST override them: this module runs on the
+// founder's own dev machine, and the real win32 delegate writes to the real
+// Desktop, Start Menu and HKCU — never acceptable as a side effect of a test
+// run. Docker-command recording (for the "nothing started" fact) happens
+// through the injected dockerSpawnSync rather than a PATH shim, for the same
+// reason install-culpa.ps1 injects -Probe into Test-DockerInstalled: an
+// explicit dependency is more reliable than relying on OS PATH resolution
+// rules for a fake executable.
+
+import { spawnSync as realSpawnSync } from "node:child_process";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { checkDockerEngineReachable, checkDockerPresent, classifyUpgrade, isIncomingComposeOlder } from "./preflight.mjs";
+import { resolveAssetPath } from "./assets.mjs";
+import { canonicalAppDir } from "./paths.mjs";
+
+// T-CF29-8: where lib/fetch.mjs stages the vendored binaries. Same derivation
+// lib/repair.mjs already uses, so the two agree on one vendor directory.
+const packageRoot = path.join(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+// The full parity file-set (Windows inventory: culpa-setup.iss:43-54, minus
+// the collectord binary, which lib/fetch.mjs stages separately by triple).
+// This is the WINDOWS inventory and stays the canonical full list — use
+// parityAssetsFor(platform) to get what a given platform should actually
+// receive.
+export const PARITY_ASSETS = [
+  "culpa-compose.yml",
+  "install-culpa.ps1",
+  "launch-culpa.ps1",
+  "uninstall-culpa.ps1",
+  "culpa-collector.ps1",
+  "register.mjs",
+];
+
+// T-CF28-6 — four of the six are PowerShell scripts that only win32 can run:
+// lib/start.mjs delegates to launch-culpa.ps1 only when platform === "win32"
+// (start.mjs:457), lib/uninstall.mjs only delegates to uninstall-culpa.ps1 on
+// win32 (uninstall.mjs:80-82), and install-culpa.ps1/culpa-collector.ps1 are
+// invoked by the Windows installer path alone. Staging them on darwin/linux
+// put four inert files in the user's app dir and made `getculpa doctor` grade
+// them as part of a healthy install.
+export const WINDOWS_ONLY_ASSETS = Object.freeze([
+  "install-culpa.ps1",
+  "launch-culpa.ps1",
+  "uninstall-culpa.ps1",
+  "culpa-collector.ps1",
+]);
+
+// The single source of truth for "which parity files belong on this platform".
+// provision(), repair() and doctor() ALL read it — if any one of them used the
+// flat list instead, repair would restore what provision skipped, or doctor
+// would fail an install for a file that is correctly absent.
+export function parityAssetsFor(platform = process.platform) {
+  if (platform === "win32") return PARITY_ASSETS;
+  return PARITY_ASSETS.filter((name) => !WINDOWS_ONLY_ASSETS.includes(name));
+}
+
+// CF20-T6 — protects the SHIPPED culpa-compose.yml the same way
+// stageLiveComposeIfAbsent already protects the live one, mirroring
+// launch-culpa.ps1's QW-1 one-direction rule: an older incoming pin must
+// never silently overwrite a newer one already staged (the
+// downgrade-package case — npm delivered an older getculpa than what is
+// already here). CULPA_ALLOW_DOWNGRADE=1 is the same escape hatch T4's
+// start.mjs already honors for QW-3 at launch time.
+function stageShippedCompose(appDir, env) {
+  const src = resolveAssetPath("culpa-compose.yml");
+  const dest = path.join(appDir, "culpa-compose.yml");
+  const allowDowngrade = env.CULPA_ALLOW_DOWNGRADE === "1";
+  if (existsSync(dest) && !allowDowngrade) {
+    const incoming = readFileSync(src, "utf8");
+    const staged = readFileSync(dest, "utf8");
+    if (isIncomingComposeOlder(incoming, staged)) {
+      console.warn(
+        "getculpa: the incoming package's culpa-compose.yml pin is older than the one already staged - skipped (set CULPA_ALLOW_DOWNGRADE=1 to override).",
+      );
+      return;
+    }
+  }
+  copyFileSync(src, dest);
+}
+
+// CF20-T5 (repair): exported so lib/repair.mjs can re-stage the parity
+// file-set and (only-if-absent) the live compose without duplicating this
+// logic — same reason the task instructions call out reuse over a second
+// copy. Purely additive: behavior and call sites inside this file are
+// unchanged.
+export function stageParityFiles(appDir, env = process.env, platform = process.platform) {
+  mkdirSync(appDir, { recursive: true });
+  stageShippedCompose(appDir, env);
+  for (const name of parityAssetsFor(platform)) {
+    if (name === "culpa-compose.yml") continue;
+    copyFileSync(resolveAssetPath(name), path.join(appDir, name));
+  }
+}
+
+// The live compose is staged ONLY when absent. An existing live compose
+// belongs to launch-time's QW-1 sync (launch-culpa.ps1) — provisioning must
+// never re-pin a running install out from under it.
+export function stageLiveComposeIfAbsent(appDir) {
+  const live = path.join(appDir, "docker-compose.yml");
+  if (existsSync(live)) return false;
+  copyFileSync(path.join(appDir, "culpa-compose.yml"), live);
+  return true;
+}
+
+// T-CF29-8 — the name culpa-collector.ps1:35 reads from the app dir, and the
+// same name culpa-setup.iss:52 installs there. NOT the Rust target triple
+// lib/fetch.mjs uses for the release asset (x86_64-pc-windows-msvc): this is
+// the Node-style platform-arch pair.
+export function collectorBinaryName(platform = process.platform, arch = process.arch) {
+  const exe = platform === "win32" ? ".exe" : "";
+  return `culpa-collectord-${platform}-${arch}${exe}`;
+}
+
+// T-CF29-8 — capture was silently OFF on every Windows npm install:
+// "culpa-collectord-win32-x64.exe not present in this package - skipping
+// capture setup". lib/fetch.mjs stages the binary into the PACKAGE's vendor/
+// as culpa-collectord.exe, the .ps1 reads it from the APP DIR under the
+// triple-suffixed name, and nothing bridged the two. The Windows installer
+// path has always put it in the app dir, so this is the npm path catching up
+// to installer parity, not a new convention.
+//
+// Returns whether the binary is really there afterwards — never a hopeful
+// echo of the caller's collectorFetched flag, because "capture is on" is
+// exactly the kind of claim that must be backed by a file on disk.
+export function stageCollectorBinary({ appDir, vendorDir, platform, arch }) {
+  const exe = platform === "win32" ? ".exe" : "";
+  const src = path.join(vendorDir, `culpa-collectord${exe}`);
+  if (!existsSync(src)) return false;
+  const dest = path.join(appDir, collectorBinaryName(platform, arch));
+  try {
+    copyFileSync(src, dest);
+  } catch (e) {
+    console.warn(`getculpa: capture collector could not be staged (${e.message}) - capture OFF, everything else works.`);
+    return false;
+  }
+  return existsSync(dest);
+}
+
+function detectDockerState(dockerSpawnSync) {
+  if (!checkDockerPresent(dockerSpawnSync)) return "missing";
+  if (!checkDockerEngineReachable(dockerSpawnSync)) return "installed-not-running";
+  return "ready";
+}
+
+// Staging only — `pull`, never `up`. This is the defer invariant's other
+// half: even with a reachable engine, provisioning must not start anything.
+function stageImages(appDir, dockerSpawnSync) {
+  const shipped = path.join(appDir, "culpa-compose.yml");
+  const result = dockerSpawnSync("docker", ["compose", "-f", shipped, "-p", "culpa", "pull"], {
+    encoding: "utf8",
+  });
+  return result.status === 0;
+}
+
+// Real win32 delegate: -DeferStart -NonInteractive is what makes this safe
+// to run unattended from postinstall (no dialogs, no engine start, no
+// compose up, no browser) while still producing the same shortcuts + HKCU
+// registration the Windows installer produces.
+function defaultDelegateWindowsInstaller(appDir) {
+  const script = path.join(appDir, "install-culpa.ps1");
+  const result = realSpawnSync(
+    "powershell.exe",
+    ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", script, "-DeferStart", "-NonInteractive"],
+    { stdio: "inherit" },
+  );
+  return result.status === 0;
+}
+
+function writeState(appDir, state) {
+  writeFileSync(path.join(appDir, "install-state.json"), `${JSON.stringify(state, null, 2)}\n`);
+}
+
+function readExistingState(appDir) {
+  try {
+    return JSON.parse(readFileSync(path.join(appDir, "install-state.json"), "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+// CF20-T6 — the honest, human-facing line for each classifyUpgrade outcome.
+// "upgrade" is explicit that the new version is STAGED, not running yet —
+// it applies at the next `getculpa` (start.mjs's QW-1-equivalent sync + T4's
+// launch orchestration), never here. Postinstall stays silent about
+// migrations by design: those are QW-4's job at that next `getculpa`, not
+// this one.
+function describeClassification(classification, previousVersion, currentVersion) {
+  switch (classification) {
+    case "fresh":
+      return `getculpa: installing Culpa ${currentVersion}.`;
+    case "upgrade":
+      return `getculpa: upgrading Culpa ${previousVersion} -> ${currentVersion} (staged; applies at next \`getculpa\`).`;
+    case "same-version":
+      return `getculpa: repairing the existing Culpa ${currentVersion} installation (same version reinstalled).`;
+    case "downgrade-package":
+      return (
+        `getculpa: this package (${currentVersion}) is older than the installed Culpa ${previousVersion} - ` +
+        "refusing to downgrade (set CULPA_ALLOW_DOWNGRADE=1 to override)."
+      );
+    case "repair":
+    default:
+      return "getculpa: repairing the existing Culpa installation.";
+  }
+}
+
+export async function provision(opts) {
+  const {
+    appDir,
+    currentVersion,
+    collectorFetched = false,
+    platform = process.platform,
+    arch = process.arch,
+    vendorDir = path.join(packageRoot, "vendor"),
+    dockerSpawnSync = realSpawnSync,
+    delegateWindowsInstaller = defaultDelegateWindowsInstaller,
+    env = process.env,
+  } = opts;
+
+  // Classify + capture the pre-existing state BEFORE anything below mutates
+  // appDir — both read the install-state.json / live compose that staging
+  // is about to overwrite.
+  const { classification, previousVersion } = classifyUpgrade({ appDir, currentVersion });
+  console.log(describeClassification(classification, previousVersion, currentVersion));
+  const existingState = readExistingState(appDir);
+
+  // CF20-R: a REFUSED downgrade (classification === "downgrade-package",
+  // CULPA_ALLOW_DOWNGRADE not set) used to still restage every OTHER parity
+  // file (the ps1 scripts, register.mjs) with the older package's copies —
+  // only culpa-compose.yml was protected (stageShippedCompose's own guard).
+  // That left a mixed-version app dir: a newer compose pin beside older
+  // scripts. Skip the WHOLE parity re-stage in this case instead, so the app
+  // dir stays wholly at the newer version; dir/state handling below is
+  // unaffected.
+  const allowDowngrade = env.CULPA_ALLOW_DOWNGRADE === "1";
+  const refusedDowngrade = classification === "downgrade-package" && !allowDowngrade;
+  if (refusedDowngrade) {
+    console.warn(
+      `getculpa: this package is older than the installed Culpa ${previousVersion} - skipping the parity file re-stage entirely (compose, scripts, register.mjs) to avoid a mixed-version app dir (set CULPA_ALLOW_DOWNGRADE=1 to override).`,
+    );
+  } else {
+    stageParityFiles(appDir, env, platform);
+  }
+  stageLiveComposeIfAbsent(appDir);
+
+  // T-CF29-8: only attempt it when the fetch reported success; the result is
+  // what gets recorded, not the intent.
+  const collectorStaged = collectorFetched && stageCollectorBinary({ appDir, vendorDir, platform, arch });
+  if (collectorFetched && !collectorStaged) {
+    console.warn(
+      "getculpa: the capture collector was downloaded but could not be placed in the app directory - capture OFF, everything else works.",
+    );
+  }
+
+  const dockerState = detectDockerState(dockerSpawnSync);
+  let imagesStaged = false;
+  if (dockerState === "ready") {
+    imagesStaged = stageImages(appDir, dockerSpawnSync);
+    if (!imagesStaged) {
+      console.warn("getculpa: image staging failed - images will be pulled at first `getculpa`.");
+    }
+  } else {
+    const why = dockerState === "missing" ? "Docker was not found" : "Docker is not running";
+    console.warn(`getculpa: ${why} - image staging deferred to first \`getculpa\`.`);
+  }
+
+  if (platform === "win32") {
+    // CF20-R: the Windows delegate registers the ONE fixed, per-machine HKCU
+    // uninstall key (install-culpa.ps1 / culpa-setup.iss's AppId). A second
+    // app dir on the same machine (CULPA_APP_DIR pointed somewhere
+    // non-default) must never overwrite that shared key — the gate's
+    // historical incident class. Only delegate when this appDir IS the
+    // canonical one (CULPA_APP_DIR's override stripped); otherwise skip
+    // registration and say so, once, honestly.
+    if (appDir === canonicalAppDir({ platform, env })) {
+      const ok = delegateWindowsInstaller(appDir);
+      if (!ok) {
+        console.warn("getculpa: Windows shortcut/registry setup did not complete cleanly - shortcuts may be missing.");
+      }
+    } else {
+      console.log("getculpa: non-canonical app dir: shortcuts/registry registration skipped.");
+    }
+  }
+
+  // T6 review (Important): a REFUSED downgrade must not record the rejected,
+  // older currentVersion as installed — the protected artifacts still carry
+  // the newer version, and this field is the ground truth the next run's
+  // classification reads. Persist the true installed version instead.
+  const recordedPackageVersion =
+    classification === "downgrade-package" && previousVersion ? previousVersion : currentVersion;
+  writeState(appDir, {
+    packageVersion: recordedPackageVersion,
+    previousVersion,
+    classification,
+    // provisionedAt is the FIRST install's timestamp, preserved across every
+    // subsequent provision() run; updatedAt is this run's.
+    provisionedAt: existingState?.provisionedAt ?? new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+    dockerState,
+    imagesStaged,
+    collectorStaged,
+    platform,
+  });
+
+  // T-CF28-5/7: the Docker and staging facts were already computed above and
+  // written to install-state.json, but the caller that has to REPORT them
+  // (scripts/install.js) could not see them — which is how a Docker-less
+  // install still printed "Culpa installed successfully." Returning them
+  // changes no behavior here; it just stops postinstall from having to guess.
+  return { classification, previousVersion, dockerState, imagesStaged, collectorStaged };
+}

package/lib/repair.d.mts

@@ -0,0 +1,21 @@
+import type { SpawnSyncLike } from "./docker.d.mts";
+import type { FetchResult } from "./fetch.d.mts";
+
+export interface RepairOptions {
+  appDir: string;
+  currentVersion: string;
+  platform?: string;
+  arch?: string;
+  vendorDir?: string;
+  dockerSpawnSync?: SpawnSyncLike;
+  fetchLauncherFn?: (opts?: { vendorDir?: string }) => Promise<FetchResult>;
+  fetchCollectordFn?: (opts?: { vendorDir?: string }) => Promise<FetchResult>;
+  log?: (msg: string) => void;
+}
+
+export interface RepairResult {
+  ok: boolean;
+  actions: string[];
+}
+
+export function repair(opts: RepairOptions): Promise<RepairResult>;

package/lib/repair.mjs

@@ -0,0 +1,174 @@
+// 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 {
+  collectorBinaryName,
+  parityAssetsFor,
+  stageCollectorBinary,
+  stageLiveComposeIfAbsent,
+  stageParityFiles,
+} 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,
+    arch = process.arch,
+    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".
+  // T-CF28-6: platform-scoped, or repair would restore the four Windows .ps1
+  // files provisioning deliberately skips on darwin/linux — and report each
+  // one as a "restored missing parity file" action while doing it.
+  const missingBefore = parityAssetsFor(platform).filter((name) => !existsSync(path.join(appDir, name)));
+  stageParityFiles(appDir, process.env, platform);
+  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);
+    // Review of 0e4b2e2: this derived collectorStaged from the PACKAGE
+    // vendor dir, which is not what culpa-collector.ps1:35 reads. It could
+    // therefore regenerate install-state.json saying capture was staged
+    // while the app dir held no collector at all — the same false positive
+    // T-CF29-8 removed from provision(). One invariant, both writers.
+    const collectorStaged = existsSync(path.join(appDir, collectorBinaryName(platform, arch)));
+    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}).`);
+    }
+  }
+
+  // Review of 0e4b2e2: re-fetching only refilled the PACKAGE vendor dir, so
+  // "re-fetched and verified" claimed a repair that left capture exactly as
+  // broken as it found it. The app-dir copy is the one that matters.
+  const appCollector = path.join(appDir, collectorBinaryName(platform, arch));
+  if (!existsSync(appCollector) && stageCollectorBinary({ appDir, vendorDir, platform, arch })) {
+    actions.push("the capture collector was missing from the app directory - staged it");
+  }
+
+  // The state file may have been regenerated BEFORE the staging above, so
+  // correct it to what is now true rather than leaving a stale answer.
+  const statePath = path.join(appDir, "install-state.json");
+  const finalState = readJsonSafe(statePath);
+  const collectorTruth = existsSync(appCollector);
+  // Review of 4e45f81: this used to correct the file and say NOTHING, so a
+  // run that really did change something reported "nothing to do - this
+  // install is already healthy". Same class of false claim the rest of this
+  // commit removes, just relocated into the action log.
+  if (finalState && finalState.collectorStaged !== collectorTruth) {
+    actions.push(
+      `install-state.json claimed capture was ${finalState.collectorStaged ? "staged" : "absent"} - corrected to match the app directory`,
+    );
+    writeFileSync(statePath, `${JSON.stringify({ ...finalState, collectorStaged: collectorTruth }, null, 2)}\n`);
+  }
+
+  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,44 @@
+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 };
+  isInteractive?: boolean;
+  askYesNo?: (question: string) => Promise<boolean>;
+}
+
+export interface StartResult {
+  ok: boolean;
+  stage: string;
+  message?: string;
+  recovery?: string;
+  alreadyRunning?: boolean;
+  stagesRun: string[];
+}
+
+export function start(opts: StartOptions): Promise<StartResult>;