getculpa 0.0.1 → 1.0.2

package/assets/uninstall-culpa.ps1

@@ -0,0 +1,227 @@
+# 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.
+# T-CF29-2 params:
+#   -Force                      proceed from THIS directory even when the
+#                               canonical check disagrees (explicit opt-in;
+#                               never automatic)
+#   -RecordedInstallLocation    inject what the registry would return, so the
+#                               resolution can be tested without touching HKCU
+#                               (same -Probe precedent as install-culpa.ps1)
+#   -CanonicalOverrideForTest   inject the fallback directory, for the same reason
+#   -PrintPlanOnly              resolve, print the decision as JSON, exit 0
+#                               BEFORE any destructive action
+param(
+    [switch]$FromUninstaller,
+    [switch]$Force,
+    [string]$RecordedInstallLocation,
+    [string]$CanonicalOverrideForTest,
+    [switch]$PrintPlanOnly
+)
+
+$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.
+#
+# T-CF29-2: a recorded value that POINTS AT A DELETED DIRECTORY used to be
+# trusted anyway, so the guard below could never match and Culpa became
+# impossible to uninstall. That is not hypothetical — the CF20 npm gate
+# overwrote this shared value with a scratch dir which was then removed.
+# A path that does not exist cannot be shadowing a real install, so it is
+# ignored in favour of the default. Everything else about the guard stands.
+# T-CF29-2: the guard compared raw strings, so two spellings of the SAME
+# directory read as different installs — an 8.3 short path (C:\Users\ZOLANI~1)
+# versus its long form, a trailing backslash, or different casing. Each of
+# those turns the uninstaller into the same dead end a stale registry value
+# does. Resolve-Path returns the canonical long form for a path that exists;
+# a path that does not exist falls back to a trimmed, lowercased comparison.
+function Normalize-Dir {
+    param([string]$Path)
+    if ([string]::IsNullOrWhiteSpace($Path)) { return "" }
+    $trimmed = $Path.TrimEnd('\', '/')
+    # GetFullPath expands an 8.3 short component (ZOLANI~1) to its long form;
+    # Resolve-Path does NOT (verified on this machine), so it cannot be relied
+    # on for that. Both are best-effort: a path that cannot be expanded falls
+    # through to the trimmed, lowercased comparison.
+    try { $trimmed = [System.IO.Path]::GetFullPath($trimmed).TrimEnd('\', '/') } catch { }
+    return $trimmed.ToLowerInvariant()
+}
+
+function Resolve-CanonicalDir {
+    param(
+        [string]$Recorded,
+        [string]$Default,
+        [scriptblock]$PathExists = { param($p) Test-Path -LiteralPath $p }
+    )
+    if ([string]::IsNullOrWhiteSpace($Recorded)) {
+        return [PSCustomObject]@{ Dir = $Default; Source = "default" }
+    }
+    $trimmed = $Recorded.TrimEnd('\')
+    if (-not (& $PathExists $trimmed)) {
+        return [PSCustomObject]@{ Dir = $Default; Source = "stale-registry" }
+    }
+    return [PSCustomObject]@{ Dir = $trimmed; Source = "registry" }
+}
+
+# SAFETY (review of 8da2b2e, CRITICAL): -RecordedInstallLocation and
+# -CanonicalOverrideForTest are ordinary parameters on the SHIPPED script, so
+# they are reachable through exactly the `-File` invocation surface Inno and
+# the shortcuts use. As first written they fed the canonical decision directly,
+# which let a stray copy pass -CanonicalOverrideForTest <its own dir> and reach
+# `docker compose -p culpa down` and the culpa_pgdata prompt with NO -Force and
+# none of the -Force warnings. Proven by probe: wouldProceed:true, forced:false.
+# That is the precise scenario CR-PR5 round 2 exists to prevent, and the
+# -Probe precedent cited above does not excuse it: that one is a parameter of
+# an INTERNAL FUNCTION, reachable only by dot-sourcing, never a top-level flag.
+#
+# They are therefore honoured ONLY under -PrintPlanOnly, which cannot touch
+# docker, the data volume, the registry or any file. In a run that could do
+# something destructive they are ignored outright, so the canonical decision
+# always comes from the real registry or the real default.
+$InjectionRequested = $PSBoundParameters.ContainsKey('RecordedInstallLocation') -or
+                      -not [string]::IsNullOrWhiteSpace($CanonicalOverrideForTest)
+$InjectionHonoured = $InjectionRequested -and $PrintPlanOnly.IsPresent
+
+if ($InjectionHonoured -and $PSBoundParameters.ContainsKey('RecordedInstallLocation')) {
+    $Recorded = $RecordedInstallLocation
+} else {
+    $Recorded = (Get-ItemProperty -Path "HKCU:\Software\Microsoft\Windows\CurrentVersion\Uninstall\{B7A6F2C4-9D31-4E5A-A0C8-52C1E7D94F60}_is1" -Name InstallLocation -ErrorAction SilentlyContinue).InstallLocation
+}
+$DefaultDir = if (-not $InjectionHonoured -or [string]::IsNullOrWhiteSpace($CanonicalOverrideForTest)) {
+    Join-Path $env:LOCALAPPDATA "Culpa"
+} else {
+    $CanonicalOverrideForTest.TrimEnd('\')
+}
+$Resolved = Resolve-CanonicalDir -Recorded $Recorded -Default $DefaultDir
+$Canonical = $Resolved.Dir
+$ComposeDst = Join-Path $AppDir "docker-compose.yml"
+
+$Matches_ = ((Normalize-Dir $AppDir) -eq (Normalize-Dir $Canonical))
+$WouldProceed = ($Matches_ -or $Force.IsPresent)
+
+if ($PrintPlanOnly) {
+    [PSCustomObject]@{
+        appDir          = $AppDir
+        canonical       = $Canonical
+        canonicalSource = $Resolved.Source
+        wouldProceed    = $WouldProceed
+        forced          = ($Force.IsPresent -and -not $Matches_)
+        # so plan output can never be mistaken for a real registry read
+        injected        = $InjectionHonoured
+    } | ConvertTo-Json -Compress
+    exit 0
+}
+
+if (-not $WouldProceed) {
+    # 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 ($Resolved.Source -eq "stale-registry") {
+        Write-Host "(The recorded install location no longer exists, so the default was used.)"
+    }
+    # T-CF29-2: never leave the user with no way out. If the canonical
+    # directory is wrong or gone, this is the escape hatch — explicit, so it
+    # can never fire by accident on a stray copy.
+    Write-Host "If Culpa really is installed HERE, re-run with -Force:" -ForegroundColor Yellow
+    Write-Host "  powershell -ExecutionPolicy Bypass -File `"$AppDir\uninstall-culpa.ps1`" -Force"
+    if (-not $FromUninstaller) { Read-Host "Press Enter to close" }
+    exit 0
+}
+
+if ($Force.IsPresent -and -not $Matches_) {
+    Write-Host "-Force: uninstalling from $AppDir even though the recorded location is $Canonical." -ForegroundColor Yellow
+}
+
+# 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/bootstrap.d.mts

@@ -0,0 +1,25 @@
+// Unlike docker.d.mts's SpawnSyncLike, this one carries `error`: a spawn that
+// never ran (missing binary, timeout kill) reports it there, not via status.
+export type LauncherSpawnSync = (
+  cmd: string,
+  args?: string[],
+  opts?: Record<string, unknown>,
+) => { status: number | null; error?: Error };
+
+export const PAYLOAD_STAGE_TIMEOUT_MS: number;
+
+export function vendoredLauncherPath(packageRoot: string, platform?: string): string | null;
+
+export interface StageInitialPayloadOptions {
+  launcherPath: string | null;
+  spawnSync?: LauncherSpawnSync;
+  log?: (msg: string) => void;
+  env?: Record<string, string | undefined>;
+}
+
+export interface StageInitialPayloadResult {
+  staged: boolean;
+  reason: "no-launcher" | "spawn-failed" | "update-failed" | "staged";
+}
+
+export function stageInitialPayload(opts: StageInitialPayloadOptions): StageInitialPayloadResult;

package/lib/bootstrap.mjs

@@ -0,0 +1,73 @@
+// 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 } from "node:fs";
+import path from "node:path";
+
+// 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;
+}
+
+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" };
+}

package/lib/docker.d.mts

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