getculpa 0.0.1 → 1.0.2

package/lib/docker.mjs

@@ -0,0 +1,270 @@
+// 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 };
+}
+
+// T-CF28-7 — the macOS half of the ask-and-install flow Windows already
+// ships (installers/windows/launch-culpa.ps1:208-219). Called ONLY after the
+// user has explicitly agreed; this function does not ask. It reports WHICH
+// path it took rather than a bare boolean, for the same reason
+// Install-DockerDesktop does: a bare false made the .ps1's caller claim a
+// download page had been opened when the package manager was present and the
+// install had simply failed. Returns "installed" | "no-brew" | "failed:<code>".
+//
+// Homebrew is the only automatic path offered on darwin: it is the user's own
+// auditable package manager, and `--cask docker` is the official cask. There
+// is deliberately no curl-and-run fallback.
+export function installDockerDarwin(spawnSync = realSpawnSync) {
+  const brew = spawnSync("brew", ["--version"], { timeout: PROBE_TIMEOUT_MS });
+  if (brew.status !== 0) return "no-brew";
+  const result = spawnSync("brew", ["install", "--cask", "docker"], { stdio: "inherit" });
+  if (result.status === 0) return "installed";
+  return `failed:${result.status}`;
+}
+
+// --- 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 };
+}

package/lib/doctor.d.mts

@@ -0,0 +1,29 @@
+import type { SpawnSyncLike, FetchLike } from "./docker.d.mts";
+
+export type CheckStatus = "ok" | "warn" | "fail" | "info";
+
+export interface DoctorCheck {
+  section: string;
+  label: string;
+  status: CheckStatus;
+  detail: string;
+}
+
+export interface DoctorOptions {
+  appDir: string;
+  currentVersion: string;
+  platform?: string;
+  arch?: string;
+  spawnSync?: SpawnSyncLike;
+  fetchFn?: FetchLike;
+  env?: Record<string, string | undefined>;
+  vendorDir?: string;
+}
+
+export interface DoctorResult {
+  ok: boolean;
+  checks: DoctorCheck[];
+}
+
+export function doctor(opts: DoctorOptions): Promise<DoctorResult>;
+export function formatDoctorReport(result: DoctorResult): string;