getculpa 0.0.1 → 1.0.1

package/assets/uninstall-culpa.ps1

@@ -0,0 +1,117 @@
+# Culpa uninstaller for Windows (T-087, T-IX-01).
+# Stops and removes the containers and shortcuts. Your recorded data is
+# KEPT unless you answer Y to the final question.
+# -FromUninstaller: run by the setup.exe's uninstaller - no interactive
+# prompts, data always kept (never delete data without an explicit yes).
+#
+# CR-PR5 round 2 (SAFETY ORDERING): the canonical-path check now gates EVERY
+# destructive action - docker down, the data-volume prompt, and file removal.
+# A copy of this script run from anywhere else previously could stop the real
+# `culpa` project and offer to delete culpa_pgdata, the shared data volume.
+param([switch]$FromUninstaller)
+
+$ErrorActionPreference = "SilentlyContinue"
+$AppDir = $PSScriptRoot
+# CF5-F11: the install directory is the founder's choice now, so "canonical"
+# is what SETUP RECORDED, not a hardcoded path. Inno writes InstallLocation
+# into its own uninstall key; fall back to %LOCALAPPDATA%\Culpa for installs
+# made before the directory page existed, and for the zip layout.
+# The guard itself is unchanged and still load-bearing: a stray COPY of this
+# script must never stop containers or delete files belonging to the real
+# install.
+$Recorded = (Get-ItemProperty -Path "HKCU:\Software\Microsoft\Windows\CurrentVersion\Uninstall\{B7A6F2C4-9D31-4E5A-A0C8-52C1E7D94F60}_is1" -Name InstallLocation -ErrorAction SilentlyContinue).InstallLocation
+$Canonical = if ([string]::IsNullOrWhiteSpace($Recorded)) {
+    Join-Path $env:LOCALAPPDATA "Culpa"
+} else {
+    $Recorded.TrimEnd('\')
+}
+$ComposeDst = Join-Path $AppDir "docker-compose.yml"
+
+if ($AppDir -ne $Canonical) {
+    # non-canonical copy: touch NOTHING (no docker, no volume, no files)
+    Write-Host "This copy is not the installed one - nothing was changed." -ForegroundColor Yellow
+    Write-Host "To uninstall Culpa: Windows Settings -> Installed apps -> Culpa,"
+    Write-Host "or run uninstall-culpa.ps1 in $Canonical."
+    if (-not $FromUninstaller) { Read-Host "Press Enter to close" }
+    exit 0
+}
+
+# CF19 (CodeRabbit PR#16 #289): collector shutdown runs AFTER the
+# canonical-path guard — a stray COPY of this script must not change the real
+# installation, and stopping its collector is a change. Stopping capture is
+# otherwise always safe, so it precedes the container teardown.
+$CollectorCtl = Join-Path $AppDir "culpa-collector.ps1"
+if (Test-Path $CollectorCtl) { & $CollectorCtl -Stop }
+
+Write-Host "==> Stopping Culpa"
+# CR-PR5: judge the native exit code explicitly (SilentlyContinue does NOT
+# catch it), and NEVER infer "stopped" from a missing compose file - a prior
+# failed cleanup can leave containers running. Absent file => ask docker.
+$stackStopped = $false
+# CR-PR5 r4: check docker EXPLICITLY. SilentlyContinue swallows a missing
+# executable and leaves $LASTEXITCODE at its PRIOR value - verified on
+# Windows PowerShell 5.1: after any earlier successful native command that
+# value is 0, so the old implicit test would have read "stopped" having
+# stopped nothing, and deleted files while containers ran. Fail-closed now
+# by construction, not by the accident of call ordering.
+if (-not (Get-Command docker -ErrorAction SilentlyContinue)) {
+    Write-Host "Docker was not found on PATH - cannot confirm Culpa is stopped." -ForegroundColor Yellow
+} elseif (Test-Path $ComposeDst) {
+    docker compose -f $ComposeDst -p culpa down
+    $stackStopped = ($LASTEXITCODE -eq 0)
+} else {
+    Write-Host "No compose file here - checking for running Culpa containers directly."
+    docker compose -p culpa down
+    $stackStopped = ($LASTEXITCODE -eq 0)
+}
+if (-not $stackStopped) {
+    Write-Host "Culpa did not stop cleanly - leaving files in place so you can retry:" -ForegroundColor Yellow
+    Write-Host "  docker compose -p culpa down"
+}
+
+Write-Host "==> Removing shortcuts"
+Remove-Item (Join-Path ([Environment]::GetFolderPath("Desktop")) "Culpa.lnk") -Force
+Remove-Item (Join-Path ([Environment]::GetFolderPath("Desktop")) "Culpa Dashboard.url") -Force
+Remove-Item (Join-Path ([Environment]::GetFolderPath("StartMenu")) "Programs\Culpa") -Recurse -Force
+
+if (-not $FromUninstaller) {
+    $wipe = Read-Host "Also DELETE all recorded cost data? This cannot be undone. (y/N)"
+    if ($wipe -eq "y" -or $wipe -eq "Y") {
+        docker volume rm culpa_pgdata
+        Write-Host "Data volume removed."
+    } else {
+        Write-Host "Data kept (volume culpa_pgdata). Reinstalling later will find it again."
+    }
+    if ($stackStopped) {
+        $unins = Join-Path $AppDir "unins000.exe"
+        if (Test-Path $unins) {
+            # exe install: hand off so the Windows Settings entry is cleaned too
+            Start-Process $unins "/VERYSILENT"
+        } else {
+            # T-171 script install: WE own the Settings entry, so we remove it.
+            # An exe install never reaches here - Inno owns and removes its own
+            # key, and deleting it from this side would strand the wizard with
+            # a listing it can no longer clean up.
+            Remove-Item -Path "HKCU:\Software\Microsoft\Windows\CurrentVersion\Uninstall\{B7A6F2C4-9D31-4E5A-A0C8-52C1E7D94F60}_is1" -Recurse -Force
+            Remove-Item $AppDir -Recurse -Force
+        }
+        Write-Host "Culpa removed."
+    } else {
+        Write-Host "Files kept because the stack is still running - stop it, then run this again."
+    }
+    Read-Host "Press Enter to close"
+} else {
+    # setup.exe's uninstaller removes the installed files itself; we only
+    # clean up what install-culpa.ps1 created at runtime - and ONLY when the
+    # stack actually stopped
+    # CR-PR5 round 3: SIGNAL the failure. Printing alone let Inno delete the
+    # scripts while containers were still running; culpa-setup.iss now runs
+    # this from InitializeUninstall and CANCELS the uninstall on a nonzero
+    # exit, so the files stay put and the retry is possible.
+    if (-not $stackStopped) {
+        Write-Host "Refusing to remove Culpa while its containers are running." -ForegroundColor Red
+        exit 1
+    }
+    Remove-Item $ComposeDst -Force
+    Write-Host "Data kept (volume culpa_pgdata). Reinstalling later will find it again."
+}

package/bin/culpa.js

@@ -1,11 +1,22 @@
 #!/usr/bin/env node
-// Name-claim placeholder. It prints one message and exits 0 — deliberately
-// no flags, no network, no files touched. The real CLI (culpa/cli) replaces
-// this package's contents at its own release; until then anyone who runs
-// `npx getculpa` gets an honest answer instead of a 404.
-
-console.log("Culpa — LLM spend forensics and forecasting, local-first.");
-console.log("");
-console.log("  Coming soon.");
-console.log("");
-console.log("  https://getculpa.com");
+// Thin shim: exec the vendored culpa launcher (installed by
+// scripts/install.js at postinstall), forwarding argv/stdio/exit code. The
+// launcher owns everything from here — versions/, updates, the payload.
+
+"use strict";
+
+const { spawnSync } = require("node:child_process");
+const fs = require("node:fs");
+const path = require("node:path");
+
+const exe = process.platform === "win32" ? ".exe" : "";
+const launcher = path.join(__dirname, "..", "vendor", `culpa-launcher${exe}`);
+
+if (!fs.existsSync(launcher)) {
+  console.error("culpa: the launcher is not installed (postinstall failed or was skipped).");
+  console.error("culpa: run `npm rebuild getculpa` (or reinstall) to fetch it.");
+  process.exit(1);
+}
+
+const result = spawnSync(launcher, process.argv.slice(2), { stdio: "inherit" });
+process.exit(result.status === null ? 1 : result.status);

package/bin/getculpa.js

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+// CF20-T3 — `getculpa` command router.
+//
+//   getculpa | getculpa start   -> wake the stack (CF20-T4)
+//   getculpa doctor / repair    -> diagnostics + self-heal (CF20-T5)
+//   getculpa uninstall          -> lib/uninstall.mjs
+//   getculpa --help / --version -> local, no launcher needed
+//   anything else (scan, connect, update, config, ...) -> passthrough to the
+//     vendored launcher, exactly like bin/culpa.js does today.
+
+"use strict";
+
+const { spawnSync } = require("node:child_process");
+const fs = require("node:fs");
+const path = require("node:path");
+
+const HELP = `getculpa - Culpa, LLM spend forensics and forecasting, local-first
+
+Usage:
+  getculpa                 Start (or resume) the Culpa stack
+  getculpa start           Same as above
+  getculpa stop            Stop the running stack (data is kept)
+  getculpa restart         Stop, then start
+  getculpa status          Show install/docker/stack/license status
+  getculpa doctor          Diagnose this install
+  getculpa repair          Re-stage missing/corrupt install files (no data touched)
+  getculpa uninstall       Remove Culpa (data is kept unless you confirm)
+  getculpa scan            Zero-install local scan (no Docker, no network)
+  getculpa connect         Print the topology-appropriate capture recipe
+  getculpa update          Manage CLI launcher updates
+  getculpa --help          Show this help
+  getculpa --version       Show the getculpa package version
+`;
+
+function printVersion() {
+  const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, "..", "package.json"), "utf8"));
+  console.log(pkg.version);
+}
+
+function runLauncherPassthrough(args) {
+  const exe = process.platform === "win32" ? ".exe" : "";
+  const launcher = path.join(__dirname, "..", "vendor", `culpa-launcher${exe}`);
+  if (!fs.existsSync(launcher)) {
+    console.error("getculpa: the launcher is not installed (postinstall failed or was skipped).");
+    console.error("getculpa: run `npm rebuild getculpa` (or reinstall) to fetch it.");
+    process.exit(1);
+  }
+  const result = spawnSync(launcher, args, { stdio: "inherit" });
+  process.exit(result.status === null ? 1 : result.status);
+}
+
+function currentVersion() {
+  return JSON.parse(fs.readFileSync(path.join(__dirname, "..", "package.json"), "utf8")).version;
+}
+
+function printResult(result) {
+  if (result.ok) return;
+  console.error("");
+  console.error(`Culpa couldn't start.`);
+  console.error(result.message ?? "(no further detail)");
+  if (result.recovery) console.error(result.recovery);
+}
+
+async function runStart() {
+  const { start } = await import("../lib/start.mjs");
+  const { getAppDir } = await import("../lib/paths.mjs");
+  const result = await start({ appDir: getAppDir(), currentVersion: currentVersion() });
+  if (!result.ok) {
+    printResult(result);
+    process.exit(1);
+  }
+  process.exit(0);
+}
+
+async function runStop() {
+  const { stop } = await import("../lib/stop.mjs");
+  const result = await stop();
+  process.exit(result.ok ? 0 : 1);
+}
+
+async function runRestart() {
+  const { stop } = await import("../lib/stop.mjs");
+  const { start } = await import("../lib/start.mjs");
+  const { getAppDir } = await import("../lib/paths.mjs");
+  await stop();
+  const result = await start({ appDir: getAppDir(), currentVersion: currentVersion() });
+  if (!result.ok) {
+    printResult(result);
+    process.exit(1);
+  }
+  process.exit(0);
+}
+
+async function runStatus() {
+  const { status, formatStatus } = await import("../lib/status.mjs");
+  const result = await status();
+  console.log(formatStatus(result));
+  process.exit(0);
+}
+
+async function runDoctor() {
+  const { doctor, formatDoctorReport } = await import("../lib/doctor.mjs");
+  const { getAppDir } = await import("../lib/paths.mjs");
+  const result = await doctor({ appDir: getAppDir(), currentVersion: currentVersion() });
+  console.log(formatDoctorReport(result));
+  process.exit(result.ok ? 0 : 1);
+}
+
+async function runRepair() {
+  const { repair } = await import("../lib/repair.mjs");
+  const { getAppDir } = await import("../lib/paths.mjs");
+  const result = await repair({ appDir: getAppDir(), currentVersion: currentVersion() });
+  process.exit(result.ok ? 0 : 1);
+}
+
+async function runUninstall() {
+  const { uninstall } = await import("../lib/uninstall.mjs");
+  const result = await uninstall();
+  process.exit(result.ok ? 0 : 1);
+}
+
+async function main(argv) {
+  const [cmd] = argv;
+  if (cmd === undefined || cmd === "start") return runStart();
+  if (cmd === "-h" || cmd === "--help" || cmd === "help") {
+    console.log(HELP);
+    return process.exit(0);
+  }
+  if (cmd === "-v" || cmd === "--version") {
+    printVersion();
+    return process.exit(0);
+  }
+  if (cmd === "stop") return runStop();
+  if (cmd === "restart") return runRestart();
+  if (cmd === "status") return runStatus();
+  if (cmd === "doctor") return runDoctor();
+  if (cmd === "repair") return runRepair();
+  if (cmd === "uninstall") return runUninstall();
+  // scan / connect / update / config / anything unrecognized: the launcher
+  // owns USAGE and exit-code semantics for its own surface, same as culpa.js.
+  return runLauncherPassthrough(argv);
+}
+
+main(process.argv.slice(2)).catch((e) => {
+  console.error(`getculpa: ${e.message}`);
+  process.exit(1);
+});

package/lib/assets.d.mts

@@ -0,0 +1,2 @@
+export const ASSET_MANIFEST: Record<string, string>;
+export function resolveAssetPath(name: string): string;

package/lib/assets.mjs

@@ -0,0 +1,36 @@
+// CF20-T3 — resolves the canonical shared install assets. Packed installs
+// read from assets/ (staged by scripts/prepack.js at `npm pack`/publish
+// time). Dev/test runs (no pack step) fall back to the repo-relative
+// canonical paths, so nothing here is ever forked — there is exactly one
+// source of truth for each file, and assets/ is a generated copy of it.
+
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const packageRoot = path.join(__dirname, "..");
+// packaging/npm-getculpa/lib -> packaging/npm-getculpa -> packaging -> repo root
+const repoRoot = path.join(packageRoot, "..", "..");
+
+// name -> repo-relative canonical source (dev/test fallback only)
+export const ASSET_MANIFEST = {
+  "culpa-compose.yml": path.join(repoRoot, "installers", "culpa-compose.yml"),
+  "install-culpa.ps1": path.join(repoRoot, "installers", "windows", "install-culpa.ps1"),
+  "launch-culpa.ps1": path.join(repoRoot, "installers", "windows", "launch-culpa.ps1"),
+  "uninstall-culpa.ps1": path.join(repoRoot, "installers", "windows", "uninstall-culpa.ps1"),
+  "culpa-collector.ps1": path.join(repoRoot, "installers", "windows", "culpa-collector.ps1"),
+  "register.mjs": path.join(repoRoot, "collector", "node", "register.mjs"),
+};
+
+export function resolveAssetPath(name) {
+  const fallback = ASSET_MANIFEST[name];
+  if (!fallback) throw new Error(`unknown shared install asset: ${name}`);
+
+  const packed = path.join(packageRoot, "assets", name);
+  if (existsSync(packed)) return packed;
+  if (existsSync(fallback)) return fallback;
+  throw new Error(
+    `asset '${name}' not found in packed assets/ (${packed}) or the repo-relative fallback (${fallback})`,
+  );
+}

package/lib/docker.d.mts

@@ -0,0 +1,72 @@
+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 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;

package/lib/docker.mjs

@@ -0,0 +1,251 @@
+// CF20-T4 — docker engine + running-stack + guard helpers shared by
+// lib/start.mjs, lib/stop.mjs and lib/status.mjs. Every docker-touching
+// function takes an injectable spawnSync (default: the real one) — the same
+// pattern lib/preflight.mjs and lib/provision.mjs already use, and for the
+// same reason: an explicit dependency is more reliable to stub in a test
+// than a PATH shim (see tests/npm-core-provision.test.ts's header comment).
+// NOTHING in this file touches a real container, port, or filesystem
+// location outside a caller-supplied path — bounded polls only, no sleeps
+// beyond the poll interval, and every poll's interval/budget is injectable
+// so a test never actually waits.
+
+import { spawnSync as realSpawnSync } from "node:child_process";
+import { mkdirSync, statSync } from "node:fs";
+import path from "node:path";
+
+const PROJECT_LABEL = "com.docker.compose.project=culpa";
+
+// CF20-R: every docker CLI probe below is a `docker info`/`ps`/`inspect`-class
+// call that normally returns in well under a second. Without a timeout, a
+// hung docker CLI (Desktop mid-restart, a stuck named pipe, an orphaned
+// process holding the socket) stalls npm install / `getculpa doctor`
+// forever. 15s is generous headroom above any healthy probe's real latency
+// while still being short enough that an install or doctor run visibly
+// degrades instead of hanging. NOT applied to preMigrationBackup's pg_dump /
+// docker cp calls below — those are genuinely long-running for a real
+// database and a 15s cap would abort a legitimate backup, not just a hang;
+// the bounded WAIT loops (waitForDockerEngine/waitForHealth/waitForPgReady)
+// keep their own maxWaitMs/intervalMs budgets unchanged — this constant only
+// bounds each individual spawnSync call inside them.
+export const PROBE_TIMEOUT_MS = 15_000;
+
+function realSleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// Bounded poll: calls `probe()` up to `Math.ceil(maxWaitMs / intervalMs)`
+// times, sleeping `intervalMs` BETWEEN attempts only (never after the last
+// one) — mirrors launch-culpa.ps1's `for ($i = 0; $i -lt N; $i++)` loops
+// (2s x 60 = 120s for the engine/dashboard, 2s x 30 = 60s for pg_isready).
+export async function pollUntil(probe, { maxWaitMs, intervalMs, sleepFn = realSleep }) {
+  const attempts = Math.max(1, Math.ceil(maxWaitMs / intervalMs));
+  for (let i = 0; i < attempts; i++) {
+    if (await probe()) return true;
+    if (i < attempts - 1) await sleepFn(intervalMs);
+  }
+  return false;
+}
+
+// --- engine reachability + start -------------------------------------------
+
+export function checkDockerEngineReachable(spawnSync = realSpawnSync) {
+  const r = spawnSync("docker", ["info", "--format", "ok"], { timeout: PROBE_TIMEOUT_MS });
+  return r.status === 0;
+}
+
+// 120s / 2s — identical budget to launch-culpa.ps1:246-251.
+export async function waitForDockerEngine(opts = {}) {
+  const { spawnSync = realSpawnSync, maxWaitMs = 120_000, intervalMs = 2_000, sleepFn } = opts;
+  return pollUntil(() => checkDockerEngineReachable(spawnSync), { maxWaitMs, intervalMs, sleepFn });
+}
+
+// darwin: mirrors installers/macos/install-culpa.command's `open -a Docker`.
+// linux: starting a system service without explicit consent is out of
+// bounds for this task (no systemctl) — this reports the two common
+// commands and returns unattempted; the caller's WAIT_FOR_DOCKER stage then
+// times out with the standard "couldn't start Docker" message, same as if
+// the founder had ignored the launch-culpa.ps1 prompt.
+export function startEngineIfPossible(platform, spawnSync = realSpawnSync, log = console.log) {
+  if (platform === "darwin") {
+    const r = spawnSync("open", ["-a", "Docker"]);
+    return { attempted: true, ok: r.status === 0 };
+  }
+  if (platform === "linux") {
+    log("getculpa: Docker's engine is not running. Start it yourself, for example:");
+    log("  sudo systemctl start docker      (systemd hosts)");
+    log("  or start Docker Desktop from your applications menu,");
+    log("then run `getculpa` again.");
+    return { attempted: false, ok: false };
+  }
+  return { attempted: false, ok: false };
+}
+
+// --- IDEMPOTENCY (spec sec 23) ----------------------------------------------
+//
+// `docker ps` (RUNNING containers only — a `docker compose stop`ped stack
+// must read as "not running" so a later `getculpa` recreates it) filtered by
+// the compose project label. Docker Compose stamps
+// com.docker.compose.project=<project name> on every container it creates,
+// independent of which compose file path was used to create it — this is
+// why the check needs no `-f` and cannot be fooled by a QW-1 re-pin between
+// checks. `docker compose -p culpa ps` was considered and rejected: current
+// Docker Compose still needs a compose file (-f, or a matching working
+// directory) to resolve service definitions for `ps`, which would
+// re-introduce a path dependency this check does not need — raw `docker ps`
+// with a label filter answers "is culpa's project running" without one.
+export function isProjectRunning(spawnSync = realSpawnSync) {
+  const r = spawnSync("docker", ["ps", "--filter", `label=${PROJECT_LABEL}`, "--format", "{{.ID}}"], {
+    encoding: "utf8",
+    timeout: PROBE_TIMEOUT_MS,
+  });
+  if (r.status !== 0) return false;
+  return (r.stdout ?? "").trim().length > 0;
+}
+
+// --- HTTP health -------------------------------------------------------------
+
+export async function probeHealth(url, { fetchFn = fetch } = {}) {
+  try {
+    const res = await fetchFn(url, { signal: AbortSignal.timeout(3_000) });
+    return res.status === 200;
+  } catch {
+    return false;
+  }
+}
+
+// 120s / 2s — identical budget to launch-culpa.ps1:331-340.
+export async function waitForHealth(url, opts = {}) {
+  const { maxWaitMs = 120_000, intervalMs = 2_000, sleepFn, fetchFn } = opts;
+  return pollUntil(() => probeHealth(url, { fetchFn }), { maxWaitMs, intervalMs, sleepFn });
+}
+
+// --- QW-4 port: pg_isready + pg_dump backup, ported from
+// launch-culpa.ps1:284-316 (Invoke-PreMigrationBackup / the pg_isready
+// loop). Same fail-closed contract: no verified dump, no launch. -------------
+
+export function dbContainerExists(spawnSync = realSpawnSync) {
+  const r = spawnSync("docker", ["ps", "-a", "--format", "{{.Names}}"], {
+    encoding: "utf8",
+    timeout: PROBE_TIMEOUT_MS,
+  });
+  if (r.status !== 0) return false;
+  return /culpa-db/.test(r.stdout ?? "");
+}
+
+// 60s / 2s — identical budget to launch-culpa.ps1:303-307. PROBE_TIMEOUT_MS
+// bounds each individual `pg_isready` call inside the poll; it does not
+// change the poll's own maxWaitMs/intervalMs budget.
+export async function waitForPgReady(opts = {}) {
+  const { spawnSync = realSpawnSync, maxWaitMs = 60_000, intervalMs = 2_000, sleepFn } = opts;
+  return pollUntil(
+    () =>
+      spawnSync("docker", ["exec", "culpa-db", "pg_isready", "-U", "culpa"], { timeout: PROBE_TIMEOUT_MS }).status ===
+      0,
+    { maxWaitMs, intervalMs, sleepFn },
+  );
+}
+
+export function resolveBackupBaseline(recorded, spawnSync = realSpawnSync) {
+  if (recorded && recorded.trim()) return recorded.trim();
+  const r = spawnSync("docker", ["inspect", "culpa-server", "--format", "{{.Config.Image}}"], {
+    encoding: "utf8",
+    timeout: PROBE_TIMEOUT_MS,
+  });
+  const image = (r.stdout ?? "").trim();
+  const m = /:(v[0-9][^:\s]*)$/.exec(image);
+  return m ? m[1] : "";
+}
+
+// Ported verbatim from Test-BackupNeeded (launch-culpa.ps1:160-165): data
+// present + an UNKNOWN baseline means BACK UP, never skip; only a baseline
+// that is known AND equal to the pin skips the backup.
+export function isBackupNeeded(dbExists, pinnedVersion, baseline) {
+  if (!dbExists) return false;
+  if (!baseline || !baseline.trim()) return true;
+  if (!pinnedVersion || !pinnedVersion.trim()) return true;
+  return pinnedVersion !== baseline;
+}
+
+function formatStamp(d) {
+  const p = (n) => String(n).padStart(2, "0");
+  return `${d.getFullYear()}${p(d.getMonth() + 1)}${p(d.getDate())}-${p(d.getHours())}${p(d.getMinutes())}${p(d.getSeconds())}`;
+}
+
+// Throws on any failure (fail-closed); returns the verified dump path on
+// success. Same three checks as the .ps1: dump exit code, copy exit code,
+// and a >=1024-byte size floor on the copied file.
+export function preMigrationBackup(opts) {
+  const { backupDir, tag, spawnSync = realSpawnSync, now = new Date() } = opts;
+  mkdirSync(backupDir, { recursive: true });
+  const dest = path.join(backupDir, `pre-${tag}-${formatStamp(now)}.dump`);
+
+  const dump = spawnSync("docker", [
+    "exec",
+    "culpa-db",
+    "sh",
+    "-c",
+    "pg_dump -Fc -U culpa culpa > /tmp/culpa-pre-upgrade.dump",
+  ]);
+  if (dump.status !== 0) throw new Error("pg_dump inside culpa-db failed");
+
+  const copy = spawnSync("docker", ["cp", "culpa-db:/tmp/culpa-pre-upgrade.dump", dest]);
+  if (copy.status !== 0) throw new Error("copying the dump out of culpa-db failed");
+
+  let size = 0;
+  try {
+    size = statSync(dest).size;
+  } catch {
+    size = 0;
+  }
+  if (size < 1024) {
+    throw new Error(`the dump at '${dest}' is missing or implausibly small (${size} bytes)`);
+  }
+  return dest;
+}
+
+// --- PORT HANDLING (spec sec 24) --------------------------------------------
+//
+// Only ever called to NAME an owner — never to act on one. Returns
+// { pid, name } for the process holding `port` in LISTEN state, or null when
+// the port is free (or the lookup itself failed — a lookup failure must
+// never be reported as a conflict).
+export function findPortOwner(port, opts = {}) {
+  const { platform = process.platform, spawnSync = realSpawnSync } = opts;
+  return platform === "win32" ? findPortOwnerWin32(port, spawnSync) : findPortOwnerPosix(port, spawnSync);
+}
+
+function findPortOwnerWin32(port, spawnSync) {
+  const conn = spawnSync(
+    "powershell.exe",
+    [
+      "-NoProfile",
+      "-Command",
+      `(Get-NetTCPConnection -LocalPort ${port} -State Listen -ErrorAction SilentlyContinue | Select-Object -First 1 -ExpandProperty OwningProcess)`,
+    ],
+    { encoding: "utf8" },
+  );
+  const pidText = (conn.stdout ?? "").trim();
+  const pid = Number(pidText.split(/\s+/)[0]);
+  if (!pidText || !Number.isFinite(pid) || pid <= 0) return null;
+
+  const proc = spawnSync(
+    "powershell.exe",
+    ["-NoProfile", "-Command", `(Get-Process -Id ${pid} -ErrorAction SilentlyContinue).ProcessName`],
+    { encoding: "utf8" },
+  );
+  const name = (proc.stdout ?? "").trim() || `pid ${pid}`;
+  return { pid, name };
+}
+
+function findPortOwnerPosix(port, spawnSync) {
+  const r = spawnSync("lsof", ["-i", `:${port}`, "-sTCP:LISTEN", "-P", "-n"], { encoding: "utf8" });
+  if (r.status !== 0) return null;
+  const lines = (r.stdout ?? "").split("\n").filter((l) => l.trim().length > 0);
+  const dataLine = lines[1]; // lines[0] is the COMMAND/PID/... header
+  if (!dataLine) return null;
+  const cols = dataLine.trim().split(/\s+/);
+  const name = cols[0];
+  const pid = Number(cols[1]);
+  if (!name || !Number.isFinite(pid) || pid <= 0) return null;
+  return { pid, name };
+}