getculpa 1.0.9 → 1.1.0

package/lib/bootstrap.mjs

@@ -1,97 +1,163 @@
-// T-CF28-4b — stage the CLI payload during `npm i -g getculpa`.
-//
-// THE DEFECT. A fresh install fetched the LAUNCHER (lib/fetch.mjs) but never
-// the PAYLOAD the launcher runs. `state.json` was left with `current: null`,
-// so the very first `getculpa` reached
-// native/culpa-launcher/src/main.rs:79-88, found nothing to exec, and printed
-// the no-payload message. The Mac tester had to work out `getculpa update` for
-// themselves and then run a SECOND command before anything happened. An
-// install that leaves nothing runnable is not an install.
-//
-// WHY THIS IS NOT AN UNCONSENTED UPDATE. `culpa update` is an explicit,
-// user-initiated verb and is not consent-gated: consent gates the BACKGROUND
-// check (`cli.rs:421-452`, `run_background_check` `cli.rs:316-318`). The user
-// ran `npm i -g getculpa`; downloading the program they just asked to install
-// is completing that install. The auto-update consent model is untouched, and
-// nothing here records a preference on the user's behalf.
-//
-// WHY IT SHELLS OUT RATHER THAN DOWNLOADING. The launcher already owns a
-// verified path: manifest fetch, sha256 verification, self-test, atomic
-// promotion. A second downloader in Node would be a second trust boundary to
-// audit and keep in step. This calls the one that already exists.
-//
-// EVERY FAILURE IS SOFT. Offline, a stalled mirror, a missing binary — none of
-// them fail the install. They leave the payload deferred, exactly as before
-// this module existed, and lib/install-summary.mjs says so and names the
-// command. The install never claims more than it did.
-
-import { spawnSync as realSpawnSync } from "node:child_process";
-import { existsSync, readFileSync } from "node:fs";
-import path from "node:path";
-import { getAppDir } from "./paths.mjs";
-
-// A real payload is tens of MB over a network Culpa does not control. Long
-// enough not to abort a slow-but-working download; short enough that a hung
-// mirror degrades to a clear deferred message instead of hanging `npm install`
-// indefinitely, which is the failure mode that matters — npm gives no progress
-// output of its own here.
-export const PAYLOAD_STAGE_TIMEOUT_MS = 10 * 60 * 1000;
-
-// Where lib/fetch.mjs puts the launcher (see stageStubLauncher in
-// scripts/install.js for the same naming: `culpa-launcher` + platform suffix).
-export function vendoredLauncherPath(packageRoot, platform = process.platform) {
-  const exe = platform === "win32" ? ".exe" : "";
-  const candidate = path.join(packageRoot, "vendor", `culpa-launcher${exe}`);
-  return existsSync(candidate) ? candidate : null;
-}
-
-/** V102 T-V102-15 (M3, D-113): what the launcher's updates/state.json
- *  actually says — EVIDENCE for the install summary, never the updater's
- *  exit code (which claimed "Culpa CLI: installed" on a Mac whose state read
- *  current: null while doctor FAILed the same install).
- *  "installed": current is set. "staged": pending only — activates at the
- *  next `getculpa`. "missing": neither, no file, or unreadable.
- *  NB (review-3): getAppDir honours CULPA_APP_DIR but not CULPA_HOME — the
- *  known-open T-CF28-3c asymmetry (see paths.mjs:17-27 and open-loops
- *  §T-CF28-3c). A CULPA_HOME-only relocation therefore reads the default
- *  location and reports "missing" — underselling, never a false claim. */
-export function readPayloadState(opts = {}) {
-  const { env = process.env } = opts;
-  try {
-    const raw = readFileSync(path.join(getAppDir({ env }), "updates", "state.json"), "utf8");
-    const state = JSON.parse(raw);
-    if (typeof state.current === "string" && state.current.length > 0) return "installed";
-    if (typeof state.pending === "string" && state.pending.length > 0) return "staged";
-    return "missing";
-  } catch {
-    return "missing"; // absent or corrupt: no evidence, no claim
-  }
-}
-
-export function stageInitialPayload(opts) {
-  const { launcherPath, spawnSync = realSpawnSync, log = console.log, env = process.env } = opts;
-
-  // No launcher means the fetch above already failed and said so; there is
-  // nothing to invoke and nothing further worth reporting here.
-  if (!launcherPath) return { staged: false, reason: "no-launcher" };
-
-  log("getculpa: downloading the Culpa CLI (this is the program `getculpa` runs).");
-  const result = spawnSync(launcherPath, ["update"], {
-    stdio: "inherit",
-    timeout: PAYLOAD_STAGE_TIMEOUT_MS,
-    // Inherit the install's own environment so CULPA_HOME / CULPA_APP_DIR
-    // resolve to the SAME root scripts/install.js provisioned into (D-108
-    // unified that chain across the launcher and the Node CLI).
-    env,
-  });
-
-  if (result.error) {
-    log(`getculpa: could not download the Culpa CLI (${result.error.message}) - run \`getculpa update\` to finish.`);
-    return { staged: false, reason: "spawn-failed" };
-  }
-  if (result.status !== 0) {
-    log("getculpa: could not download the Culpa CLI - run `getculpa update` to finish.");
-    return { staged: false, reason: "update-failed" };
-  }
-  return { staged: true, reason: "staged" };
-}
+// T-CF28-4b — stage the CLI payload during `npm i -g getculpa`.
+//
+// THE DEFECT. A fresh install fetched the LAUNCHER (lib/fetch.mjs) but never
+// the PAYLOAD the launcher runs. `state.json` was left with `current: null`,
+// so the very first `getculpa` reached
+// native/culpa-launcher/src/main.rs:79-88, found nothing to exec, and printed
+// the no-payload message. The Mac tester had to work out `getculpa update` for
+// themselves and then run a SECOND command before anything happened. An
+// install that leaves nothing runnable is not an install.
+//
+// WHY THIS IS NOT AN UNCONSENTED UPDATE. `culpa update` is an explicit,
+// user-initiated verb and is not consent-gated: consent gates the BACKGROUND
+// check (`cli.rs:421-452`, `run_background_check` `cli.rs:316-318`). The user
+// ran `npm i -g getculpa`; downloading the program they just asked to install
+// is completing that install. The auto-update consent model is untouched, and
+// nothing here records a preference on the user's behalf.
+//
+// WHY IT SHELLS OUT RATHER THAN DOWNLOADING. The launcher already owns a
+// verified path: manifest fetch, sha256 verification, self-test, atomic
+// promotion. A second downloader in Node would be a second trust boundary to
+// audit and keep in step. This calls the one that already exists.
+//
+// EVERY FAILURE IS SOFT. Offline, a stalled mirror, a missing binary — none of
+// them fail the install. They leave the payload deferred, exactly as before
+// this module existed, and lib/install-summary.mjs says so and names the
+// command. The install never claims more than it did.
+
+import { spawnSync as realSpawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { getAppDir } from "./paths.mjs";
+import { compareVersions } from "./preflight.mjs";
+
+// A real payload is tens of MB over a network Culpa does not control. Long
+// enough not to abort a slow-but-working download; short enough that a hung
+// mirror degrades to a clear deferred message instead of hanging `npm install`
+// indefinitely, which is the failure mode that matters — npm gives no progress
+// output of its own here.
+export const PAYLOAD_STAGE_TIMEOUT_MS = 10 * 60 * 1000;
+
+// Where lib/fetch.mjs puts the launcher (see stageStubLauncher in
+// scripts/install.js for the same naming: `culpa-launcher` + platform suffix).
+export function vendoredLauncherPath(packageRoot, platform = process.platform) {
+  const exe = platform === "win32" ? ".exe" : "";
+  const candidate = path.join(packageRoot, "vendor", `culpa-launcher${exe}`);
+  return existsSync(candidate) ? candidate : null;
+}
+
+/** V102 T-V102-15 (M3, D-113): what the launcher's updates/state.json
+ *  actually says — EVIDENCE for the install summary, never the updater's
+ *  exit code (which claimed "Culpa CLI: installed" on a Mac whose state read
+ *  current: null while doctor FAILed the same install).
+ *  "installed": current is set. "staged": pending only — activates at the
+ *  next `getculpa`. "missing": neither, no file, or unreadable.
+ *  NB (review-3): getAppDir honours CULPA_APP_DIR but not CULPA_HOME — the
+ *  known-open T-CF28-3c asymmetry (see paths.mjs:17-27 and open-loops
+ *  §T-CF28-3c). A CULPA_HOME-only relocation therefore reads the default
+ *  location and reports "missing" — underselling, never a false claim. */
+export function readPayloadState(opts = {}) {
+  return readPayloadDetail(opts).state;
+}
+
+/** T-V1010-1 (ISS-V1010-1): the state AND the versions it was read from.
+ *  With `expectedVersion` (the npm package's own version) the answer is
+ *  VERSION-AWARE — a fresh `npm i -g getculpa@1.0.10` on a machine whose
+ *  versions/ held 1.0.4 used to read "installed" because `current` was merely
+ *  non-null, and the summary said so while the one download had failed.
+ *    "installed": current is at, or AHEAD of, expected (the launcher only ever
+ *                 moves forward — cli.rs run_manual_update — so ahead is never
+ *                 a downgrade and never "behind");
+ *    "staged":    pending is at or ahead of expected (activates at launch);
+ *    "behind":    something is present but the newest of current/pending is
+ *                 older than expected — the download did not arrive;
+ *    "missing":   nothing present, or no/corrupt file.
+ *  Without `expectedVersion` the three-state answer is unchanged (callers that
+ *  do not know the package version). Unparsable version strings compare as
+ *  equal (compareVersions fail-open, the launch-culpa.ps1 convention). */
+export function readPayloadDetail(opts = {}) {
+  const { env = process.env, expectedVersion } = opts;
+  let current = null;
+  let pending = null;
+  try {
+    const raw = readFileSync(path.join(getAppDir({ env }), "updates", "state.json"), "utf8");
+    const state = JSON.parse(raw);
+    if (typeof state.current === "string" && state.current.length > 0) current = state.current;
+    if (typeof state.pending === "string" && state.pending.length > 0) pending = state.pending;
+  } catch {
+    return { state: "missing", current: null, pending: null }; // absent or corrupt: no evidence, no claim
+  }
+  if (current === null && pending === null) return { state: "missing", current, pending };
+  if (typeof expectedVersion !== "string" || expectedVersion.length === 0) {
+    return { state: current !== null ? "installed" : "staged", current, pending };
+  }
+  if (current !== null && compareVersions(current, expectedVersion) >= 0) return { state: "installed", current, pending };
+  if (pending !== null && compareVersions(pending, expectedVersion) >= 0) return { state: "staged", current, pending };
+  return { state: "behind", current, pending };
+}
+
+export function stageInitialPayload(opts) {
+  const {
+    launcherPath,
+    spawnSync = realSpawnSync,
+    log = console.log,
+    env = process.env,
+    // T-V1010-1: the npm package's own version. When given, the result is
+    // judged by what updates/state.json says AFTERWARDS, not by the exit code,
+    // and a download that did not bring this version is retried ONCE (the
+    // 1.0.10 install's single run failed as "offline" on an online machine).
+    // When omitted the function behaves exactly as before: one spawn, the
+    // exit code decides.
+    expectedVersion,
+    readDetail = readPayloadDetail,
+  } = opts;
+
+  // No launcher means the fetch above already failed and said so; there is
+  // nothing to invoke and nothing further worth reporting here.
+  if (!launcherPath) return { staged: false, reason: "no-launcher" };
+
+  const runUpdate = () =>
+    spawnSync(launcherPath, ["update"], {
+      stdio: "inherit",
+      timeout: PAYLOAD_STAGE_TIMEOUT_MS,
+      // Inherit the install's own environment so CULPA_HOME / CULPA_APP_DIR
+      // resolve to the SAME root scripts/install.js provisioned into (D-108
+      // unified that chain across the launcher and the Node CLI).
+      env,
+    });
+
+  log("getculpa: downloading the Culpa CLI (this is the program `getculpa` runs).");
+  const result = runUpdate();
+
+  const versionAware = typeof expectedVersion === "string" && expectedVersion.length > 0;
+  if (!versionAware) {
+    if (result.error) {
+      log(`getculpa: could not download the Culpa CLI (${result.error.message}) - run \`getculpa update\` to finish.`);
+      return { staged: false, reason: "spawn-failed" };
+    }
+    if (result.status !== 0) {
+      log("getculpa: could not download the Culpa CLI - run `getculpa update` to finish.");
+      return { staged: false, reason: "update-failed" };
+    }
+    return { staged: true, reason: "staged" };
+  }
+
+  const arrived = (d) => d.state === "installed" || d.state === "staged";
+  let detail = readDetail({ env, expectedVersion });
+  if (!arrived(detail)) {
+    // One more try: a transient transport failure is classed "offline" by the
+    // launcher and a second attempt seconds later routinely succeeds. Bounded
+    // the same way; still soft. Known gap: a first run killed by the timeout
+    // can leave the launcher's own update lock in place, in which case this
+    // retry is a no-op — the summary still reports the real state.
+    log(`getculpa: the Culpa CLI v${expectedVersion} did not arrive - trying the download once more.`);
+    const again = runUpdate();
+    detail = readDetail({ env, expectedVersion });
+    if (!arrived(detail)) {
+      const why = again.error ? ` (${again.error.message})` : "";
+      log(`getculpa: could not download the Culpa CLI v${expectedVersion}${why} - run \`getculpa\` (it downloads it) or \`getculpa update\` to finish.`);
+      return { staged: false, reason: again.error ? "spawn-failed" : "update-failed", detail };
+    }
+  }
+  return { staged: true, reason: "staged", detail };
+}

package/lib/dispatch.d.mts

@@ -1,12 +1,12 @@
-export type DispatchDecision =
-  | { kind: "help"; verb: string | null }
-  | { kind: "refuse-uninstall" }
-  | { kind: "confirm-uninstall" }
-  | { kind: "run-uninstall" }
-  | { kind: "dispatch" };
-
-export const LOCAL_VERBS: string[];
-
-export function verbHelp(verb: string): string;
-
-export function decideDispatch(argv: string[], opts?: { isTTY?: boolean }): DispatchDecision;
+export type DispatchDecision =
+  | { kind: "help"; verb: string | null }
+  | { kind: "refuse-uninstall" }
+  | { kind: "confirm-uninstall" }
+  | { kind: "run-uninstall" }
+  | { kind: "dispatch" };
+
+export const LOCAL_VERBS: string[];
+
+export function verbHelp(verb: string): string;
+
+export function decideDispatch(argv: string[], opts?: { isTTY?: boolean }): DispatchDecision;

package/lib/dispatch.mjs

@@ -1,59 +1,66 @@
-// V102 T-V102-04 (M8/P0-2, D-113) — dispatch decisions for bin/getculpa.js.
-//
-// Executed on real hardware: `getculpa uninstall --help` stopped and removed
-// all three containers and the network, because the router recognised a help
-// flag only as argv[0] and dispatched on argv[0] without reading argv[1].
-// `stop`, `restart` and `repair` shared the shape. The rule now: for every
-// verb THIS bin routes locally, a help flag anywhere in argv decides HELP
-// before anything is imported or spawned. Passthrough verbs (scan, connect,
-// update, config, …) keep their argv untouched — the vendored launcher owns
-// their help and exit-code semantics.
-//
-// Pure decisions, no side effects: the bin acts on the returned kind, and the
-// facts in tests/npm-cli-dispatch.test.ts assert the decisions directly.
-
-const HELP_FLAGS = new Set(["-h", "--help", "help"]);
-
-/** Every verb bin/getculpa.js routes locally (everything else passes through). */
-export const LOCAL_VERBS = ["start", "stop", "restart", "status", "doctor", "repair", "uninstall"];
-const LOCAL = new Set(LOCAL_VERBS);
-
-const VERB_HELP = {
-  start: "Start (or resume) the Culpa stack. Data is kept.",
-  stop: "Stop the running stack. Containers stop, nothing is removed, all data is kept. Start again with `getculpa`.",
-  restart: "Stop, then start the stack. No data is touched.",
-  status: "Show install/docker/stack/license status. Read-only.",
-  doctor: "Diagnose this install. Read-only.",
-  repair: "Re-stage missing or corrupt install files. No data touched.",
-  uninstall:
-    "Stop and REMOVE Culpa's containers and network. Asks for confirmation first; pass --yes to consent from a script (a non-interactive run without --yes refuses). Recorded cost data is kept unless you separately confirm deleting it.",
-};
-
-/** One verb's help block, prefixed with its usage line. */
-export function verbHelp(verb) {
-  const text = VERB_HELP[verb] ?? "No help recorded for this verb.";
-  return `Usage: getculpa ${verb}\n\n  ${text}\n`;
-}
-
-/**
- * Decide what argv means BEFORE any dispatch. Returns one of:
- *   { kind: "help", verb: string | null }  print help (general when verb null)
- *   { kind: "refuse-uninstall" }           non-interactive, no --yes: refuse
- *   { kind: "confirm-uninstall" }          interactive: ask, then uninstall
- *   { kind: "run-uninstall" }              consent given via --yes/-y
- *   { kind: "dispatch" }                   fall through to the existing router
- */
-export function decideDispatch(argv, { isTTY = false } = {}) {
-  const [cmd] = argv;
-  if (cmd === undefined) return { kind: "dispatch" };
-  if (HELP_FLAGS.has(cmd)) return { kind: "help", verb: null };
-  if (LOCAL.has(cmd) && argv.slice(1).some((a) => HELP_FLAGS.has(a))) {
-    return { kind: "help", verb: cmd };
-  }
-  if (cmd === "uninstall") {
-    if (argv.includes("--yes") || argv.includes("-y")) return { kind: "run-uninstall" };
-    if (!isTTY) return { kind: "refuse-uninstall" };
-    return { kind: "confirm-uninstall" };
-  }
-  return { kind: "dispatch" };
-}
+// V102 T-V102-04 (M8/P0-2, D-113) — dispatch decisions for bin/getculpa.js.
+//
+// Executed on real hardware: `getculpa uninstall --help` stopped and removed
+// all three containers and the network, because the router recognised a help
+// flag only as argv[0] and dispatched on argv[0] without reading argv[1].
+// `stop`, `restart` and `repair` shared the shape. The rule now: for every
+// verb THIS bin routes locally, a help flag anywhere in argv decides HELP
+// before anything is imported or spawned. Passthrough verbs (scan, connect,
+// update, config, …) keep their argv untouched — the vendored launcher owns
+// their help and exit-code semantics.
+//
+// Pure decisions, no side effects: the bin acts on the returned kind, and the
+// facts in tests/npm-cli-dispatch.test.ts assert the decisions directly.
+
+const HELP_FLAGS = new Set(["-h", "--help", "help"]);
+
+/** Every verb bin/getculpa.js routes locally (everything else passes through). */
+export const LOCAL_VERBS = ["start", "stop", "restart", "status", "doctor", "repair", "uninstall"];
+const LOCAL = new Set(LOCAL_VERBS);
+
+const VERB_HELP = {
+  start: "Start (or resume) the Culpa stack. Data is kept.",
+  stop: "Stop the running stack. Containers stop, nothing is removed, all data is kept. Start again with `getculpa`.",
+  restart: "Stop, then start the stack. No data is touched.",
+  status: "Show install/docker/stack/license status. Read-only.",
+  doctor: "Diagnose this install. Read-only.",
+  repair: "Re-stage missing or corrupt install files. No data touched.",
+  uninstall:
+    "Stop and REMOVE Culpa's containers and network. Asks for confirmation first; pass --yes to consent from a script (a non-interactive run without --yes refuses). Recorded cost data is kept unless you separately confirm deleting it.",
+};
+
+/** T-182.8 (ISS-MAC-11): the environment for a passthrough spawn — the
+ *  vendored launcher and the culpa CLI spell their usage in the invoked name
+ *  when CULPA_ARGV0 says `getculpa` (an allowlist on their side). Pure. */
+export function passthroughEnv(base) {
+  return { ...base, CULPA_ARGV0: "getculpa" };
+}
+
+/** One verb's help block, prefixed with its usage line. */
+export function verbHelp(verb) {
+  const text = VERB_HELP[verb] ?? "No help recorded for this verb.";
+  return `Usage: getculpa ${verb}\n\n  ${text}\n`;
+}
+
+/**
+ * Decide what argv means BEFORE any dispatch. Returns one of:
+ *   { kind: "help", verb: string | null }  print help (general when verb null)
+ *   { kind: "refuse-uninstall" }           non-interactive, no --yes: refuse
+ *   { kind: "confirm-uninstall" }          interactive: ask, then uninstall
+ *   { kind: "run-uninstall" }              consent given via --yes/-y
+ *   { kind: "dispatch" }                   fall through to the existing router
+ */
+export function decideDispatch(argv, { isTTY = false } = {}) {
+  const [cmd] = argv;
+  if (cmd === undefined) return { kind: "dispatch" };
+  if (HELP_FLAGS.has(cmd)) return { kind: "help", verb: null };
+  if (LOCAL.has(cmd) && argv.slice(1).some((a) => HELP_FLAGS.has(a))) {
+    return { kind: "help", verb: cmd };
+  }
+  if (cmd === "uninstall") {
+    if (argv.includes("--yes") || argv.includes("-y")) return { kind: "run-uninstall" };
+    if (!isTTY) return { kind: "refuse-uninstall" };
+    return { kind: "confirm-uninstall" };
+  }
+  return { kind: "dispatch" };
+}

package/lib/docker.d.mts

@@ -1,76 +1,76 @@
-export type SpawnSyncLike = (
-  cmd: string,
-  args?: string[],
-  opts?: unknown,
-) => { status: number | null; stdout?: string; stderr?: string };
-
-export const PROBE_TIMEOUT_MS: number;
-
-export function pollUntil(
-  probe: () => boolean | Promise<boolean>,
-  opts: { maxWaitMs: number; intervalMs: number; sleepFn?: (ms: number) => Promise<void> },
-): Promise<boolean>;
-
-export function checkDockerEngineReachable(spawnSync?: SpawnSyncLike): boolean;
-
-export function waitForDockerEngine(opts?: {
-  spawnSync?: SpawnSyncLike;
-  maxWaitMs?: number;
-  intervalMs?: number;
-  sleepFn?: (ms: number) => Promise<void>;
-}): Promise<boolean>;
-
-export type DarwinDockerInstallOutcome = "installed" | "no-brew" | `failed:${string}`;
-
-export function installDockerDarwin(spawnSync?: SpawnSyncLike): DarwinDockerInstallOutcome;
-
-export function startEngineIfPossible(
-  platform: string,
-  spawnSync?: SpawnSyncLike,
-  log?: (msg: string) => void,
-): { attempted: boolean; ok: boolean };
-
-export function isProjectRunning(spawnSync?: SpawnSyncLike): boolean;
-
-export type FetchLike = typeof fetch;
-
-export function probeHealth(url: string, opts?: { fetchFn?: FetchLike }): Promise<boolean>;
-
-export function waitForHealth(
-  url: string,
-  opts?: { maxWaitMs?: number; intervalMs?: number; sleepFn?: (ms: number) => Promise<void>; fetchFn?: FetchLike },
-): Promise<boolean>;
-
-export function dbContainerExists(spawnSync?: SpawnSyncLike): boolean;
-
-export function waitForPgReady(opts?: {
-  spawnSync?: SpawnSyncLike;
-  maxWaitMs?: number;
-  intervalMs?: number;
-  sleepFn?: (ms: number) => Promise<void>;
-}): Promise<boolean>;
-
-export function resolveBackupBaseline(recorded: string | null | undefined, spawnSync?: SpawnSyncLike): string;
-
-export function isBackupNeeded(
-  dbExists: boolean,
-  pinnedVersion: string | null | undefined,
-  baseline: string | null | undefined,
-): boolean;
-
-export function preMigrationBackup(opts: {
-  backupDir: string;
-  tag: string;
-  spawnSync?: SpawnSyncLike;
-  now?: Date;
-}): string;
-
-export interface PortOwner {
-  pid: number;
-  name: string;
-}
-
-export function findPortOwner(
-  port: number,
-  opts?: { platform?: string; spawnSync?: SpawnSyncLike },
-): PortOwner | null;
+export type SpawnSyncLike = (
+  cmd: string,
+  args?: string[],
+  opts?: unknown,
+) => { status: number | null; stdout?: string; stderr?: string };
+
+export const PROBE_TIMEOUT_MS: number;
+
+export function pollUntil(
+  probe: () => boolean | Promise<boolean>,
+  opts: { maxWaitMs: number; intervalMs: number; sleepFn?: (ms: number) => Promise<void> },
+): Promise<boolean>;
+
+export function checkDockerEngineReachable(spawnSync?: SpawnSyncLike): boolean;
+
+export function waitForDockerEngine(opts?: {
+  spawnSync?: SpawnSyncLike;
+  maxWaitMs?: number;
+  intervalMs?: number;
+  sleepFn?: (ms: number) => Promise<void>;
+}): Promise<boolean>;
+
+export type DarwinDockerInstallOutcome = "installed" | "no-brew" | `failed:${string}`;
+
+export function installDockerDarwin(spawnSync?: SpawnSyncLike): DarwinDockerInstallOutcome;
+
+export function startEngineIfPossible(
+  platform: string,
+  spawnSync?: SpawnSyncLike,
+  log?: (msg: string) => void,
+): { attempted: boolean; ok: boolean };
+
+export function isProjectRunning(spawnSync?: SpawnSyncLike): boolean;
+
+export type FetchLike = typeof fetch;
+
+export function probeHealth(url: string, opts?: { fetchFn?: FetchLike }): Promise<boolean>;
+
+export function waitForHealth(
+  url: string,
+  opts?: { maxWaitMs?: number; intervalMs?: number; sleepFn?: (ms: number) => Promise<void>; fetchFn?: FetchLike },
+): Promise<boolean>;
+
+export function dbContainerExists(spawnSync?: SpawnSyncLike): boolean;
+
+export function waitForPgReady(opts?: {
+  spawnSync?: SpawnSyncLike;
+  maxWaitMs?: number;
+  intervalMs?: number;
+  sleepFn?: (ms: number) => Promise<void>;
+}): Promise<boolean>;
+
+export function resolveBackupBaseline(recorded: string | null | undefined, spawnSync?: SpawnSyncLike): string;
+
+export function isBackupNeeded(
+  dbExists: boolean,
+  pinnedVersion: string | null | undefined,
+  baseline: string | null | undefined,
+): boolean;
+
+export function preMigrationBackup(opts: {
+  backupDir: string;
+  tag: string;
+  spawnSync?: SpawnSyncLike;
+  now?: Date;
+}): string;
+
+export interface PortOwner {
+  pid: number;
+  name: string;
+}
+
+export function findPortOwner(
+  port: number,
+  opts?: { platform?: string; spawnSync?: SpawnSyncLike },
+): PortOwner | null;