getculpa 0.0.1 → 1.0.2

package/lib/doctor.mjs

@@ -0,0 +1,405 @@
+// CF20-T5 — `getculpa doctor`. Support-paste-friendly, plain text (no ANSI,
+// ever — that trivially satisfies "no ANSI when not TTY" without a second
+// TTY-conditional code path to test), sectioned diagnostics.
+//
+// Exit-code contract (spec sec 31, "doctor-on-dormant"): only STRUCTURAL
+// integrity problems (a missing parity file, an unreadable install-state.json,
+// a missing vendored launcher, or an actively-running-but-unreachable
+// database) are FAILures. Everything Docker/network/health-related degrades
+// to a WARNing — a fully-provisioned but not-yet-started ("dormant") install
+// must report ok:true. This mirrors status.mjs's own "never throws, always
+// degrades honestly" contract, extended with a pass/fail verdict.
+//
+// Every docker/http call is injectable (spawnSync/fetchFn), same pattern as
+// lib/docker.mjs, lib/start.mjs and lib/status.mjs — no PATH shim, no real
+// network, no real container.
+
+import { spawnSync as realSpawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { findPortOwner, probeHealth, PROBE_TIMEOUT_MS } from "./docker.mjs";
+import { checkDockerPresent, checkDockerEngineReachable, classifyUpgrade, parsePinnedServerVersion } from "./preflight.mjs";
+import { parityAssetsFor } from "./provision.mjs";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const packageRoot = path.join(__dirname, "..");
+
+const PORTS_TO_CHECK = [3000, 4545];
+const DASHBOARD_URL = "http://127.0.0.1:3000";
+const API_HEALTH_URL = "http://127.0.0.1:4545/health";
+const ENTITLEMENT_URL = "http://127.0.0.1:4545/internal/entitlement";
+
+function check(section, label, status, detail) {
+  return { section, label, status, detail };
+}
+
+function readJsonSafe(filePath) {
+  try {
+    return JSON.parse(readFileSync(filePath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function readTextSafe(filePath) {
+  try {
+    return readFileSync(filePath, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+// `docker ps -a --filter label=com.docker.compose.project=culpa` with a
+// tab-separated format — one call serves the "runtime/service state"
+// section AND tells the rest of doctor whether the project (and its db
+// container specifically) is running, without three separate `docker ps`
+// invocations.
+function listProjectContainers(spawnSync) {
+  const r = spawnSync(
+    "docker",
+    ["ps", "-a", "--filter", "label=com.docker.compose.project=culpa", "--format", "{{.Names}}\t{{.State}}\t{{.Status}}"],
+    { encoding: "utf8", timeout: PROBE_TIMEOUT_MS },
+  );
+  if (r.status !== 0) return [];
+  return (r.stdout ?? "")
+    .split("\n")
+    .map((l) => l.trim())
+    .filter(Boolean)
+    .map((line) => {
+      const [name, state, ...statusParts] = line.split("\t");
+      return { name: name ?? "", state: state ?? "", status: statusParts.join("\t") };
+    });
+}
+
+function getDockerServerVersion(spawnSync) {
+  const r = spawnSync("docker", ["version", "--format", "{{.Server.Version}}"], {
+    encoding: "utf8",
+    timeout: PROBE_TIMEOUT_MS,
+  });
+  if (r.status !== 0) return null;
+  return (r.stdout ?? "").trim() || null;
+}
+
+function checkVersionPlatform(currentVersion, platform, arch) {
+  return [
+    check("Version / platform", "getculpa package version", "info", currentVersion),
+    check("Version / platform", "Platform", "info", platform),
+    check("Version / platform", "Architecture", "info", arch),
+  ];
+}
+
+function checkVendoredLauncher(vendorDir, platform) {
+  const exe = platform === "win32" ? ".exe" : "";
+  const launcherPath = path.join(vendorDir, `culpa-launcher${exe}`);
+  const present = existsSync(launcherPath);
+  return check(
+    "Installation integrity",
+    "Vendored launcher",
+    present ? "ok" : "fail",
+    present ? launcherPath : `missing: ${launcherPath} (run \`npm rebuild getculpa\`, or reinstall)`,
+  );
+}
+
+function checkInstallationIntegrity(appDir, platform) {
+  const checks = [];
+  const liveComposePath = path.join(appDir, "docker-compose.yml");
+  const installed = existsSync(liveComposePath);
+
+  checks.push(check("Installation integrity", "App directory", installed ? "ok" : "info", appDir));
+
+  if (!installed) {
+    checks.push(check("Installation integrity", "Live compose", "info", "not installed - nothing to verify"));
+    return { checks, installed, state: null };
+  }
+
+  checks.push(check("Installation integrity", "Live compose", "ok", liveComposePath));
+
+  // T-CF28-6: grade only the files this platform is supposed to have. On
+  // darwin/linux the four Windows .ps1 scripts are correctly absent — listing
+  // them at all (as [OK] before, as a failure after the staging fix) reports
+  // on an install that does not exist.
+  for (const name of parityAssetsFor(platform)) {
+    const assetPath = path.join(appDir, name);
+    const present = existsSync(assetPath);
+    checks.push(
+      check(
+        "Installation integrity",
+        `Parity file: ${name}`,
+        present ? "ok" : "fail",
+        present ? assetPath : `missing: ${assetPath} (run \`getculpa repair\`)`,
+      ),
+    );
+  }
+
+  const state = readJsonSafe(path.join(appDir, "install-state.json"));
+  checks.push(
+    check(
+      "Installation integrity",
+      "install-state.json",
+      state ? "ok" : "fail",
+      state ? "readable" : "missing or unreadable (run `getculpa repair`)",
+    ),
+  );
+
+  checks.push(
+    check(
+      "Installation integrity",
+      "Capture collector",
+      state?.collectorStaged ? "ok" : "warn",
+      state?.collectorStaged ? "staged" : "not staged (capture is off on this install)",
+    ),
+  );
+
+  return { checks, installed, state };
+}
+
+function checkDocker(spawnSync) {
+  const checks = [];
+  const present = checkDockerPresent(spawnSync);
+  checks.push(
+    check("Docker", "Docker CLI", present ? "ok" : "warn", present ? "found" : "not found - install from https://docs.docker.com/get-docker/"),
+  );
+
+  const reachable = present && checkDockerEngineReachable(spawnSync);
+  checks.push(
+    check(
+      "Docker",
+      "Docker engine",
+      reachable ? "ok" : "warn",
+      reachable ? "running" : present ? "installed, but the engine is not running" : "unavailable (Docker not installed)",
+    ),
+  );
+
+  if (reachable) {
+    const version = getDockerServerVersion(spawnSync);
+    checks.push(check("Docker", "Docker version", version ? "ok" : "warn", version ?? "could not be determined"));
+  }
+
+  return { checks, reachable };
+}
+
+function checkRuntimeState(containers) {
+  if (containers.length === 0) {
+    return [check("Runtime / service state", "Containers", "info", "no containers for the culpa compose project (never started, or fully removed)")];
+  }
+  return containers.map((c) =>
+    check("Runtime / service state", c.name, c.state === "running" ? "ok" : "info", `${c.state} - ${c.status}`),
+  );
+}
+
+function checkExpectedDirectories(appDir, vendorDir) {
+  const dirs = [
+    ["App directory", appDir],
+    ["Backups directory", path.join(appDir, "backups")],
+    ["Vendor directory", vendorDir],
+  ];
+  return dirs.map(([label, dir]) => check("Expected directories", label, "info", `${existsSync(dir) ? "exists" : "missing"}: ${dir}`));
+}
+
+function checkDatabase(spawnSync, containers) {
+  const dbContainer = containers.find((c) => /culpa-db/.test(c.name));
+  if (!dbContainer || dbContainer.state !== "running") {
+    return [check("Database", "Postgres (culpa-db)", "info", "skipped - db container not running")];
+  }
+  const r = spawnSync("docker", ["exec", "culpa-db", "pg_isready", "-U", "culpa"], {
+    encoding: "utf8",
+    timeout: PROBE_TIMEOUT_MS,
+  });
+  const ready = r.status === 0;
+  return [check("Database", "Postgres (culpa-db)", ready ? "ok" : "fail", ready ? "accepting connections" : "container is running but not accepting connections")];
+}
+
+function checkMigrations(appDir) {
+  const lastBoot = readTextSafe(path.join(appDir, "last-boot-version.txt")).trim();
+  const pinned = parsePinnedServerVersion(readTextSafe(path.join(appDir, "docker-compose.yml")));
+  return [
+    check("Migrations", "Last booted server version", "info", lastBoot || "unknown (never recorded)"),
+    check("Migrations", "Live compose pinned server tag", "info", pinned ?? "unknown"),
+  ];
+}
+
+function checkPorts(spawnSync, platform, running) {
+  return PORTS_TO_CHECK.map((port) => {
+    const owner = findPortOwner(port, { platform, spawnSync });
+    if (!owner) return check("Ports", `:${port}`, "ok", "free");
+    if (running) return check("Ports", `:${port}`, "ok", `culpa-owned (${owner.name}, pid ${owner.pid})`);
+    return check("Ports", `:${port}`, "warn", `in use by ${owner.name} (pid ${owner.pid})`);
+  });
+}
+
+async function checkHealth(fetchFn, running) {
+  if (!running) {
+    return [
+      check("Culpa health", "Dashboard (:3000)", "info", "not running"),
+      check("Culpa health", "API (:4545)", "info", "not running"),
+    ];
+  }
+  const dashboardHealthy = await probeHealth(DASHBOARD_URL, { fetchFn });
+  const apiHealthy = await probeHealth(API_HEALTH_URL, { fetchFn });
+  return [
+    check("Culpa health", "Dashboard (:3000)", dashboardHealthy ? "ok" : "warn", dashboardHealthy ? "healthy" : "not responding"),
+    check("Culpa health", "API (:4545)", apiHealthy ? "ok" : "warn", apiHealthy ? "healthy" : "not responding"),
+  ];
+}
+
+function scanLicenseKeyPresence(env, appDir) {
+  if (env.CULPA_LICENSE_KEY) return true;
+  const compose = readTextSafe(path.join(appDir, "docker-compose.yml"));
+  return /CULPA_LICENSE_KEY/.test(compose);
+}
+
+// Extracts ONLY configured/state/plan — even if the (possibly stubbed, in
+// tests) response carries other fields, they are never read into the
+// report. This is the redaction boundary the F1 fact tests.
+async function checkLicense(fetchFn, running, env, appDir) {
+  const checks = [];
+  const keyPresent = scanLicenseKeyPresence(env, appDir);
+  checks.push(check("License", "CULPA_LICENSE_KEY", keyPresent ? "ok" : "info", keyPresent ? "present (redacted)" : "not set"));
+
+  if (!running) {
+    checks.push(check("License", "Entitlement", "info", "unknown (server not running)"));
+    return checks;
+  }
+  try {
+    const res = await fetchFn(ENTITLEMENT_URL, { signal: AbortSignal.timeout(3_000) });
+    if (res.status !== 200) {
+      checks.push(check("License", "Entitlement", "warn", `server did not answer (status ${res.status})`));
+      return checks;
+    }
+    const body = await res.json();
+    const configured = typeof body?.configured === "boolean" ? body.configured : null;
+    const state = typeof body?.state === "string" ? body.state : null;
+    const plan = typeof body?.plan === "string" ? body.plan : null;
+    checks.push(
+      check(
+        "License",
+        "Entitlement",
+        "ok",
+        `configured=${configured ?? "unknown"}, state=${state ?? "n/a"}, plan=${plan ?? "n/a"}`,
+      ),
+    );
+  } catch {
+    checks.push(check("License", "Entitlement", "warn", "could not reach the server"));
+  }
+  return checks;
+}
+
+// CF20-R: classifyInstall alone cannot distinguish a package DOWNGRADE
+// (this package is older than what is already staged/live) from a
+// genuinely unclear install state — both collapsed into "repair" with the
+// same "run `getculpa repair`" message, which is misleading for a
+// downgrade (it is not unclear, it was a deliberate, correct refusal).
+// classifyUpgrade already makes that distinction (provision.mjs's own
+// caller uses it) — currentVersion was already threaded all the way from
+// bin/getculpa.js into this function; the gap was this function reading it
+// through the coarser classifier.
+function checkUpdateState(appDir, currentVersion, installed) {
+  const checks = [];
+  if (!installed) {
+    checks.push(check("Update state", "Install vs shipped version", "info", "not installed - nothing to compare"));
+    return checks;
+  }
+  const { classification: kind, previousVersion } = classifyUpgrade({ appDir, currentVersion });
+  const label = {
+    "same-version": ["ok", `up to date (v${currentVersion})`],
+    upgrade: ["warn", `an update is staged - run \`getculpa\` to apply it`],
+    repair: ["warn", "install state is unclear - run `getculpa repair`"],
+    fresh: ["info", "not installed"],
+    "downgrade-package": [
+      "warn",
+      `this package (v${currentVersion}) is OLDER than the installed Culpa v${previousVersion ?? "?"} - refusing to downgrade (set CULPA_ALLOW_DOWNGRADE=1 to override)`,
+    ],
+  }[kind] ?? ["info", kind];
+  checks.push(check("Update state", "Install vs shipped version", label[0], label[1]));
+
+  const updateStatePath = path.join(appDir, "updates", "state.json");
+  const launcherState = readJsonSafe(updateStatePath);
+  // Audit (flows) finding 2: this reported "ok" whenever the JSON merely
+  // PARSED, never looking at current. So on the exact stranded install
+  // T-CF28-4b exists to prevent - no payload ever staged - doctor printed
+  // "Overall: OK" while the very next getculpa dead-ended with "no installed
+  // version found". Diagnostics that reassure you about the broken thing are
+  // worse than none.
+  const noPayload = launcherState !== null && (launcherState.current ?? null) === null;
+  checks.push(
+    check(
+      "Update state",
+      "Launcher self-update state",
+      launcherState === null ? "info" : noPayload ? "fail" : "ok",
+      launcherState === null
+        ? "unknown (no update state recorded yet)"
+        : noPayload
+          ? "no CLI payload is staged (current=null) - run `getculpa update`, then `getculpa`"
+          : `current=${launcherState.current}, pending=${launcherState.pending ?? "none"}, mode=${launcherState.mode ?? "n/a"}`,
+    ),
+  );
+  return checks;
+}
+
+export async function doctor(opts) {
+  const {
+    appDir,
+    currentVersion,
+    platform = process.platform,
+    arch = process.arch,
+    spawnSync = realSpawnSync,
+    fetchFn = fetch,
+    env = process.env,
+    vendorDir = path.join(packageRoot, "vendor"),
+  } = opts;
+
+  const checks = [];
+  checks.push(...checkVersionPlatform(currentVersion, platform, arch));
+
+  const integrity = checkInstallationIntegrity(appDir, platform);
+  checks.push(...integrity.checks);
+  checks.push(checkVendoredLauncher(vendorDir, platform));
+
+  const docker = checkDocker(spawnSync);
+  checks.push(...docker.checks);
+
+  const containers = docker.reachable ? listProjectContainers(spawnSync) : [];
+  checks.push(...checkRuntimeState(containers));
+  checks.push(...checkExpectedDirectories(appDir, vendorDir));
+  checks.push(...checkDatabase(spawnSync, containers));
+  checks.push(...checkMigrations(appDir));
+
+  const running = containers.some((c) => c.state === "running");
+  checks.push(...checkPorts(spawnSync, platform, running));
+  checks.push(...(await checkHealth(fetchFn, running)));
+  checks.push(...(await checkLicense(fetchFn, running, env, appDir)));
+  checks.push(...checkUpdateState(appDir, currentVersion, integrity.installed));
+
+  const ok = !checks.some((c) => c.status === "fail");
+  return { ok, checks };
+}
+
+export function formatDoctorReport(result) {
+  const lines = [];
+  lines.push("Culpa doctor report");
+  lines.push("====================");
+  lines.push("");
+
+  const sections = [];
+  for (const c of result.checks) {
+    let section = sections.find((s) => s.name === c.section);
+    if (!section) {
+      section = { name: c.section, items: [] };
+      sections.push(section);
+    }
+    section.items.push(c);
+  }
+
+  for (const section of sections) {
+    lines.push(`-- ${section.name} --`);
+    for (const item of section.items) {
+      lines.push(`[${item.status.toUpperCase()}] ${item.label}: ${item.detail}`);
+    }
+    lines.push("");
+  }
+
+  const failureCount = result.checks.filter((c) => c.status === "fail").length;
+  lines.push(result.ok ? "Overall: OK" : `Overall: ${failureCount} failure(s) - see above ([FAIL] lines).`);
+  return lines.join("\n");
+}

package/lib/fetch.d.mts

@@ -0,0 +1,17 @@
+export declare const ORIGIN: string;
+export function targetTriple(platform?: string, arch?: string): string;
+
+export interface FetchOptions {
+  vendorDir?: string;
+  origin?: string;
+  trustedHosts?: Set<string>;
+  allowInsecureHttp?: boolean;
+}
+
+export interface FetchResult {
+  dest: string;
+  sha256: string;
+}
+
+export function fetchLauncher(opts?: FetchOptions): Promise<FetchResult>;
+export function fetchCollectord(opts?: FetchOptions): Promise<FetchResult>;

package/lib/fetch.mjs

@@ -0,0 +1,211 @@
+// CF20-T3 — checksum-verified GitHub-release fetch, extracted from the
+// original scripts/install.js (AU-011) so it can be reused for the
+// collector binary and unit-tested against a local fixture server. Every
+// security property of the original is kept byte-for-byte:
+//   - host allowlist enforced on every redirect hop (github.com,
+//     objects.githubusercontent.com, release-assets.githubusercontent.com)
+//   - https only
+//   - bounded redirects (MAX_REDIRECTS)
+//   - size caps enforced WHILE streaming, not after buffering
+//   - write-temp + rename (never a half-written executable at the dest)
+//   - sha256 verified against the release's published checksums file before
+//     the file is ever written to its final path
+//
+// The one behavioral extension: fetchCollectord() treats "no checksum line
+// published for this asset" as an EXPECTED, non-fatal outcome (the release
+// process may ship without a collectord for a given triple yet) — everything
+// else, including a checksum MISMATCH, still fails closed exactly like the
+// launcher fetch.
+
+import crypto from "node:crypto";
+import fs 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, "..");
+
+// The ONE origin — mirrors native/culpa-launcher/src/origin.rs. Never read
+// from env or config. D-094: repointed to the public releases-only mirror
+// (MyaigiDev/culpa-releases); the source repo (myaigidev/culpa) stays
+// private.
+// Exported so tests can pin the production origin (CF21-T5 review: a revert
+// of this constant would 404 every fresh install and no injected-fixture test
+// can see it).
+export const ORIGIN = "https://github.com/MyaigiDev/culpa-releases/releases/latest/download";
+const TRUSTED_HOSTS = new Set([
+  "github.com",
+  "objects.githubusercontent.com",
+  "release-assets.githubusercontent.com",
+]);
+const MAX_REDIRECTS = 5;
+
+export function targetTriple(platform = process.platform, arch = process.arch) {
+  if (platform === "win32" && arch === "x64") return "x86_64-pc-windows-msvc";
+  if (platform === "linux" && arch === "x64") return "x86_64-unknown-linux-gnu";
+  if (platform === "darwin" && arch === "x64") return "x86_64-apple-darwin";
+  if (platform === "darwin" && arch === "arm64") return "aarch64-apple-darwin";
+  throw new Error(`unsupported platform: ${platform}/${arch}`);
+}
+
+// allowInsecureHttp defaults false and is ONLY ever set by the fixture-server
+// tests (see tests/npm-core-fetch.test.ts) — no production call site (the
+// fetchLauncher()/fetchCollectord() callers in scripts/install.js) passes
+// it, so the real https-only enforcement is unchanged.
+function assertTrustedUrl(u, trustedHosts, allowInsecureHttp) {
+  const protocolOk = u.protocol === "https:" || (allowInsecureHttp && u.protocol === "http:");
+  if (!protocolOk) throw new Error(`${u}: only https is trusted (got ${u.protocol})`);
+  if (!trustedHosts.has(u.hostname)) throw new Error(`${u}: untrusted redirect host refused (${u.hostname})`);
+}
+
+// Follows redirects manually so every hop is pinned to https + a trusted
+// host, up to MAX_REDIRECTS hops. `timeoutMs` bounds each hop individually.
+async function fetchTrusted(url, timeoutMs, trustedHosts, allowInsecureHttp) {
+  let current = new URL(url);
+  for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
+    assertTrustedUrl(current, trustedHosts, allowInsecureHttp);
+    const res = await fetch(current, { redirect: "manual", signal: AbortSignal.timeout(timeoutMs) });
+    if (res.status >= 300 && res.status < 400) {
+      const location = res.headers.get("location");
+      if (!location) throw new Error(`${current}: redirect with no Location header`);
+      current = new URL(location, current);
+      continue;
+    }
+    if (res.status === 404) {
+      const err = new Error(`GET ${current} -> 404`);
+      err.notFound = true;
+      throw err;
+    }
+    if (!res.ok) throw new Error(`GET ${current} -> ${res.status}`);
+    return res;
+  }
+  throw new Error(`${url}: too many redirects (> ${MAX_REDIRECTS})`);
+}
+
+// Enforces maxBytes WHILE STREAMING so a hostile/misconfigured response with
+// no (or a lying) Content-Length cannot be buffered past the cap before it
+// is checked.
+async function fetchBytes(url, maxBytes, timeoutMs, trustedHosts, allowInsecureHttp) {
+  const res = await fetchTrusted(url, timeoutMs, trustedHosts, allowInsecureHttp);
+  if (!res.body) throw new Error(`${url}: response has no body`);
+  const reader = res.body.getReader();
+  const chunks = [];
+  let total = 0;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    total += value.length;
+    if (total > maxBytes) {
+      await reader.cancel();
+      throw new Error(`${url}: response exceeds ${maxBytes} bytes`);
+    }
+    chunks.push(value);
+  }
+  return Buffer.concat(chunks);
+}
+
+function sha256Hex(buf) {
+  return crypto.createHash("sha256").update(buf).digest("hex");
+}
+
+// CF20-R: the checksums file is `sha256sum`'s own output — one line per
+// asset, "<sha256>  <filename>" (verified format: release-cli.yml runs
+// `sha256sum culpa-launcher-* culpa-collectord-*` on ubuntu-latest, GNU
+// coreutils' default text-mode two-space separator; tests/npm-core-fetch.test.ts's
+// fixtures construct lines the same way). `endsWith(assetName)` was a
+// substring match on the WHOLE line, not the filename field — a shorter
+// asset name that happens to be a suffix of an unrelated line (or a
+// malformed/commented line ending in the same text) could match the wrong
+// entry. Split on whitespace and compare the filename field exactly.
+function findChecksumLine(checksumsText, assetName) {
+  const line = checksumsText
+    .split("\n")
+    .map((l) => l.trim())
+    .find((l) => l.split(/\s+/)[1] === assetName);
+  if (!line) return null;
+  const expected = line.split(/\s+/)[0];
+  if (!/^[0-9a-f]{64}$/.test(expected)) throw new Error("malformed checksum line");
+  return expected;
+}
+
+function writeVerified(destDir, destName, binary) {
+  fs.mkdirSync(destDir, { recursive: true });
+  const dest = path.join(destDir, destName);
+  const tmp = `${dest}.tmp.${process.pid}`;
+  fs.writeFileSync(tmp, binary);
+  fs.renameSync(tmp, dest);
+  if (process.platform !== "win32") fs.chmodSync(dest, 0o755);
+  return dest;
+}
+
+// origin/trustedHosts/allowInsecureHttp are all injectable — this is what
+// makes the fixture-server tests possible without touching the real GitHub
+// origin or weakening production's https-only enforcement.
+async function fetchVerifiedAsset({
+  assetName,
+  destDir,
+  destName,
+  maxBytes,
+  origin = ORIGIN,
+  trustedHosts = TRUSTED_HOSTS,
+  allowInsecureHttp = false,
+}) {
+  const checksumsBuf = await fetchBytes(
+    `${origin}/culpa-launcher-checksums.txt`,
+    64 * 1024,
+    120_000,
+    trustedHosts,
+    allowInsecureHttp,
+  );
+  const expected = findChecksumLine(checksumsBuf.toString("utf8"), assetName);
+  if (!expected) {
+    const err = new Error(`no checksum published for ${assetName}`);
+    err.notFound = true;
+    throw err;
+  }
+  const binary = await fetchBytes(`${origin}/${assetName}`, maxBytes, 15 * 60_000, trustedHosts, allowInsecureHttp);
+  const actual = sha256Hex(binary);
+  if (actual !== expected) {
+    throw new Error(`checksum mismatch for ${assetName}: expected ${expected}, got ${actual}`);
+  }
+  const dest = writeVerified(destDir, destName, binary);
+  return { dest, sha256: actual };
+}
+
+export async function fetchLauncher(opts = {}) {
+  const triple = targetTriple();
+  const exe = process.platform === "win32" ? ".exe" : "";
+  const assetName = `culpa-launcher-${triple}${exe}`;
+  const vendorDir = opts.vendorDir ?? path.join(packageRoot, "vendor");
+  const result = await fetchVerifiedAsset({
+    assetName,
+    destDir: vendorDir,
+    destName: `culpa-launcher${exe}`,
+    maxBytes: 64 * 1024 * 1024,
+    origin: opts.origin,
+    trustedHosts: opts.trustedHosts,
+    allowInsecureHttp: opts.allowInsecureHttp,
+  });
+  console.log(`getculpa: installed culpa launcher (${triple}, sha256 ${result.sha256.slice(0, 12)}…)`);
+  return result;
+}
+
+// Graceful-degrade case lives here, not in the caller: "not published for
+// this release yet" is the ONE outcome that must not abort the install.
+export async function fetchCollectord(opts = {}) {
+  const triple = targetTriple();
+  const exe = process.platform === "win32" ? ".exe" : "";
+  const assetName = `culpa-collectord-${triple}${exe}`;
+  const vendorDir = opts.vendorDir ?? path.join(packageRoot, "vendor");
+  const result = await fetchVerifiedAsset({
+    assetName,
+    destDir: vendorDir,
+    destName: `culpa-collectord${exe}`,
+    maxBytes: 64 * 1024 * 1024,
+    origin: opts.origin,
+    trustedHosts: opts.trustedHosts,
+    allowInsecureHttp: opts.allowInsecureHttp,
+  });
+  console.log(`getculpa: installed capture collector (${triple}, sha256 ${result.sha256.slice(0, 12)}…)`);
+  return result;
+}

package/lib/install-summary.d.mts

@@ -0,0 +1,18 @@
+import type { UpgradeClassification } from "./preflight.d.mts";
+import type { DockerState } from "./provision.d.mts";
+
+export interface InstallSummaryOptions {
+  classification: UpgradeClassification;
+  version: string;
+  previousVersion?: string | null;
+  appDir: string;
+  dockerState: DockerState;
+  imagesStaged?: boolean;
+  collectorStaged?: boolean;
+  payloadStaged?: boolean;
+  platform?: string;
+  isTTY?: boolean;
+  env?: Record<string, string | undefined>;
+}
+
+export function buildInstallSummary(opts: InstallSummaryOptions): string[];