getculpa 0.0.1 → 1.0.2

package/lib/install-summary.mjs

@@ -0,0 +1,144 @@
+// T-CF28-5 (postinstall output) + T-CF28-7 (the install-time half of the
+// Docker ask) — the lines postinstall prints when it finishes.
+//
+// Extracted from scripts/install.js's main() as a PURE function. The words
+// are the product here: the shipped 1.0.1 printed "Culpa installed
+// successfully." on a fresh Mac with no Docker, where nothing could actually
+// start. That line lived inline in a CommonJS script with no export, so no
+// test could assert it. It is a line-builder now so the claims it makes are
+// checked by tests/npm-core-install-summary.test.ts.
+//
+// TWO RULES THIS FILE EXISTS TO ENFORCE:
+//
+// 1. Never claim "ready" unless it IS ready. The founder's ruled headline is
+//    "Culpa is installed and ready." with `ready` in green — printed when
+//    Docker is genuinely usable. When Docker is missing or stopped, the
+//    headline drops to "Culpa is installed." and the Docker requirement is
+//    stated plainly. Printing the ruled line unconditionally would repeat the
+//    exact defect that created T-CF28-7.
+//
+// 2. Say what each platform will really do. postinstall CANNOT prompt
+//    (scripts/install.js:13-15 — npm installs run headless and a stdin read
+//    would hang), so this file only DETECTS and TELLS; the asking happens at
+//    first `getculpa`. win32 already ships that flow
+//    (installers/windows/launch-culpa.ps1:179-234); darwin gains it in
+//    lib/start.mjs; linux stays guidance-only, because installing a system
+//    package without explicit consent is out of bounds (the same rule
+//    lib/docker.mjs:73-79 already follows for starting the engine).
+
+import { green } from "./tty.mjs";
+
+const DOCKER_DESKTOP_URL = "https://www.docker.com/products/docker-desktop/";
+const DOCKER_ENGINE_DOCS_URL = "https://docs.docker.com/engine/install/";
+
+function headline(classification, version, previousVersion, dockerReady, colour) {
+  switch (classification) {
+    case "upgrade":
+      return `Culpa updated: ${previousVersion} -> ${version} (staged; applies at next \`getculpa\`).`;
+    case "downgrade-package":
+      return `Culpa ${previousVersion} is already installed; this package (${version}) is older and was not applied.`;
+    case "same-version":
+    case "repair":
+      return "Culpa installation repaired.";
+    default:
+      // "fresh" — the only case the founder's ruled wording describes.
+      return dockerReady ? `Culpa is installed and ${green("ready", colour)}.` : "Culpa is installed.";
+  }
+}
+
+function inventory(appDir, imagesStaged, collectorStaged, payloadStaged) {
+  return [
+    `  Location:  ${appDir}`,
+    // T-CF28-4b: the CLI payload is the program `getculpa` actually runs. When
+    // it is missing the install is not usable at all, so this row names the
+    // one command that finishes the job rather than leaving a dead first run.
+    `  Culpa CLI: ${payloadStaged ? "installed" : "deferred - run `getculpa update` to finish"}`,
+    `  Images:    ${imagesStaged ? "staged" : "deferred to first run"}`,
+    `  Capture:   ${collectorStaged ? "collector installed" : "off (collector not installed)"}`,
+  ];
+}
+
+// Docker is MISSING. Each platform gets only what is true for it.
+function dockerMissingLines(platform) {
+  const lines = [
+    "Culpa needs Docker to run: its database and services run in containers.",
+    "Docker was not found on this machine.",
+  ];
+  if (platform === "darwin") {
+    lines.push(
+      "  Install it with:  brew install --cask docker",
+      "    Homebrew asks for your password, and you must open Docker once from",
+      "    Applications before Culpa can start - it is not a one-click install.",
+      `  Or download it:   ${DOCKER_DESKTOP_URL}`,
+      "Culpa will offer to do this for you the first time you run `getculpa`.",
+    );
+  } else if (platform === "win32") {
+    lines.push(
+      "Culpa will offer to install Docker for you the first time you run `getculpa`.",
+      `  Or download it:   ${DOCKER_DESKTOP_URL}`,
+    );
+  } else {
+    lines.push(
+      `  Install Docker Engine:  ${DOCKER_ENGINE_DOCS_URL}`,
+      "Culpa will not install system packages for you - install it yourself, then",
+      "run `getculpa`.",
+    );
+  }
+  return lines;
+}
+
+// Docker is PRESENT but the engine is stopped. Starting it is something Culpa
+// really does do on darwin (lib/docker.mjs:69-72, `open -a Docker`) and win32
+// (installers/windows/launch-culpa.ps1:236-244) — but never on linux.
+function dockerStoppedLines(platform) {
+  const lines = ["Docker is installed but its engine is not running."];
+  if (platform === "linux") {
+    lines.push("  Start it yourself, for example:  sudo systemctl start docker");
+  } else {
+    lines.push("  Culpa will start it for you when you run `getculpa`.");
+  }
+  return lines;
+}
+
+export function buildInstallSummary(opts) {
+  const {
+    classification,
+    version,
+    previousVersion = null,
+    appDir,
+    dockerState,
+    imagesStaged = false,
+    collectorStaged = false,
+    // T-CF28-4b. Fail-CLOSED, matching imagesStaged/collectorStaged above: a
+    // caller that cannot say whether the payload is there has no evidence for
+    // "ready", and this function exists precisely to stop readiness being
+    // claimed without evidence. scripts/install.js always passes the real value.
+    payloadStaged = false,
+    platform = process.platform,
+    isTTY = false,
+    env = {},
+  } = opts;
+
+  const dockerReady = dockerState === "ready";
+  // "ready" means the next command will work. A missing CLI payload breaks
+  // that just as completely as a missing Docker, so it gates the word too.
+  const ready = dockerReady && payloadStaged;
+  const colour = { isTTY, env };
+  const lines = [headline(classification, version, previousVersion, ready, colour)];
+
+  // A refused downgrade staged nothing — an inventory there would describe a
+  // state this run did not produce (lib/provision.mjs:175-183).
+  if (classification !== "downgrade-package") {
+    lines.push(...inventory(appDir, imagesStaged, collectorStaged, payloadStaged));
+  }
+
+  if (!dockerReady) {
+    lines.push("");
+    lines.push(...(dockerState === "missing" ? dockerMissingLines(platform) : dockerStoppedLines(platform)));
+  }
+
+  lines.push("");
+  lines.push(ready ? "Run:" : "Then run:");
+  lines.push("  getculpa");
+  return lines;
+}

package/lib/paths.d.mts

@@ -0,0 +1,9 @@
+export interface GetAppDirOptions {
+  env?: Record<string, string | undefined>;
+  platform?: string;
+  homedir?: string;
+}
+
+export function getAppDir(opts?: GetAppDirOptions): string;
+
+export function canonicalAppDir(opts?: GetAppDirOptions): string;

package/lib/paths.mjs

@@ -0,0 +1,61 @@
+// CF20-T3 — per-OS app dir resolution (Windows-installer parity).
+//
+// Real conventions, verified against the installers themselves:
+//   win32:  %LOCALAPPDATA%\Culpa      (installers/windows/install-culpa.ps1:19)
+//   darwin: ~/Library/Application Support/Culpa (installers/macos/install-culpa.command:7)
+//   linux:  ~/.local/share/culpa, honoring XDG_DATA_HOME (no shipped Linux
+//           installer yet — this is the XDG-spec default for that base path)
+//
+// path.win32 / path.posix are used explicitly (never the ambient `path`)
+// so the SAME function returns the correct separator for a simulated
+// platform on any host OS — this is what makes it testable on a Windows
+// dev machine without lying about macOS/Linux output.
+
+import os from "node:os";
+import path from "node:path";
+
+// CULPA_APP_DIR is a test-only escape hatch (task spec: "for tests only").
+// It is still readable in production because there is no safe way to tell
+// "a test set this" from "an operator set this" from inside the module, and
+// refusing a real operator's override would be a worse failure mode than
+// honoring it.
+//
+// D-108 (cli-v1.0.2): the vendored Rust launcher honors CULPA_APP_DIR too —
+// as a fallback when its own CULPA_HOME is unset (native/culpa-launcher/
+// src/home.rs). So relocating with this variable moves BOTH halves: the
+// stack/licence state this module resolves AND the launcher's
+// versions/updates state. Keep the two sides in step if either changes.
+export function getAppDir(opts = {}) {
+  const env = opts.env ?? process.env;
+  const platform = opts.platform ?? process.platform;
+  const homedir = opts.homedir ?? os.homedir();
+
+  if (env.CULPA_APP_DIR) return env.CULPA_APP_DIR;
+
+  if (platform === "win32") {
+    const base = env.LOCALAPPDATA || path.win32.join(homedir, "AppData", "Local");
+    return path.win32.join(base, "Culpa");
+  }
+  if (platform === "darwin") {
+    return path.posix.join(homedir, "Library", "Application Support", "Culpa");
+  }
+  // linux and other POSIX platforms
+  const xdgDataHome = env.XDG_DATA_HOME || path.posix.join(homedir, ".local", "share");
+  return path.posix.join(xdgDataHome, "culpa");
+}
+
+// CF20-R — the ONE fixed HKCU uninstall key (installers/windows/
+// install-culpa.ps1's Add/Remove Programs registration, culpa-setup.iss's
+// AppId) is per-MACHINE, not per-app-dir. A second app dir on the same
+// Windows machine (CULPA_APP_DIR pointed somewhere non-default) must never
+// register/overwrite that shared key — the gate's historical incident class.
+// canonicalAppDir answers "what would getAppDir() return if CULPA_APP_DIR
+// were NOT set" — the override is stripped, everything else (platform,
+// homedir, LOCALAPPDATA/XDG_DATA_HOME) still applies — so a caller can tell
+// whether the app dir it was actually given is the canonical, registry-owning
+// one.
+export function canonicalAppDir(opts = {}) {
+  const env = { ...(opts.env ?? process.env) };
+  delete env.CULPA_APP_DIR;
+  return getAppDir({ ...opts, env });
+}

package/lib/preflight.d.mts

@@ -0,0 +1,39 @@
+export interface PlatformSupport {
+  supported: boolean;
+  message?: string;
+}
+
+export function checkPlatformSupport(platform?: string, arch?: string): PlatformSupport;
+
+export interface DiskSpaceResult {
+  known: boolean;
+  availableBytes: number | null;
+}
+
+export function checkDiskSpaceBestEffort(targetDir: string): DiskSpaceResult;
+
+export type SpawnSyncLike = (cmd: string, args?: string[], opts?: unknown) => { status: number | null };
+
+export function checkDockerPresent(spawnSync?: SpawnSyncLike): boolean;
+export function checkDockerEngineReachable(spawnSync?: SpawnSyncLike): boolean;
+
+export function parsePinnedServerVersion(composeText: string | null | undefined): string | null;
+export function compareVersions(a: string | null | undefined, b: string | null | undefined): -1 | 0 | 1;
+
+export type InstallKind = "fresh" | "upgrade" | "same-version" | "repair";
+
+export function classifyInstall(opts: { appDir: string; currentVersion: string }): InstallKind;
+
+export type UpgradeClassification = InstallKind | "downgrade-package";
+
+export interface UpgradeClassificationResult {
+  classification: UpgradeClassification;
+  previousVersion: string | null;
+}
+
+export function classifyUpgrade(opts: { appDir: string; currentVersion: string }): UpgradeClassificationResult;
+
+export function isIncomingComposeOlder(
+  incomingComposeText: string | null | undefined,
+  stagedComposeText: string | null | undefined,
+): boolean;

package/lib/preflight.mjs

@@ -0,0 +1,169 @@
+// CF20-T3 — preflight checks for the shared install core. Detection only:
+// nothing here starts Docker, pulls an image, or touches the app dir.
+//
+// Docker checks take an injectable spawnSync (default: the real one), the
+// same pattern install-culpa.ps1 uses for Test-DockerInstalled's -Probe —
+// so a test can stub docker's presence/engine state without a real Docker
+// install or a fragile PATH shim.
+
+import { spawnSync as realSpawnSync } from "node:child_process";
+import { existsSync, readFileSync, statfsSync } from "node:fs";
+import path from "node:path";
+import { PROBE_TIMEOUT_MS } from "./docker.mjs";
+
+const SUPPORTED_TRIPLES = new Set(["win32-x64", "linux-x64", "darwin-x64", "darwin-arm64"]);
+
+// Mirrors the launcher triples already load-bearing in scripts/install.js's
+// targetTriple() (win32/x64, linux/x64, darwin/x64, darwin/arm64).
+export function checkPlatformSupport(platform = process.platform, arch = process.arch) {
+  if (SUPPORTED_TRIPLES.has(`${platform}-${arch}`)) return { supported: true };
+  const message =
+    "Culpa currently supports Windows x64, Linux x64, and macOS (Intel or Apple Silicon). " +
+    `Detected: ${platform}/${arch}.`;
+  return { supported: false, message };
+}
+
+// Best-effort: `statfs` is unavailable or throws on some hosts/paths (e.g. a
+// directory that does not exist yet). Unknown is a valid, honestly-reported
+// outcome — this never blocks or fails the install.
+export function checkDiskSpaceBestEffort(targetDir) {
+  try {
+    const probeDir = nearestExistingAncestor(targetDir);
+    const stats = statfsSync(probeDir);
+    return { known: true, availableBytes: stats.bavail * stats.bsize };
+  } catch {
+    return { known: false, availableBytes: null };
+  }
+}
+
+function nearestExistingAncestor(startDir) {
+  let dir = startDir;
+  for (let i = 0; i < 64; i++) {
+    if (existsSync(dir)) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return dir; // reached the filesystem root
+    dir = parent;
+  }
+  return dir;
+}
+
+export function checkDockerPresent(spawnSync = realSpawnSync) {
+  // CF20-R: PROBE_TIMEOUT_MS (docker.mjs) — a hung docker CLI must not stall
+  // npm install forever.
+  const result = spawnSync("docker", ["--version"], { timeout: PROBE_TIMEOUT_MS });
+  return result.status === 0;
+}
+
+// Reachability only — never starts the engine (that is launch-time's job).
+export function checkDockerEngineReachable(spawnSync = realSpawnSync) {
+  const result = spawnSync("docker", ["info", "--format", "ok"], { timeout: PROBE_TIMEOUT_MS });
+  return result.status === 0;
+}
+
+// Same parsing target as launch-culpa.ps1's Get-PinnedServerVersion.
+export function parsePinnedServerVersion(composeText) {
+  const m = /culpa-server:([^"\s]+)/.exec(composeText ?? "");
+  return m ? m[1] : null;
+}
+
+// Same fail-open-to-"equal" semantics as launch-culpa.ps1's
+// Compare-CulpaVersions: an unparsable tag never brick the comparison, it
+// just reads as 0 (equal). -1 = a older, 1 = a newer.
+export function compareVersions(a, b) {
+  const rx = /^v?(\d+)\.(\d+)\.(\d+)/;
+  const ma = rx.exec(a ?? "");
+  const mb = rx.exec(b ?? "");
+  if (!ma || !mb) return 0;
+  for (let i = 1; i <= 3; i++) {
+    const na = Number(ma[i]);
+    const nb = Number(mb[i]);
+    if (na < nb) return -1;
+    if (na > nb) return 1;
+  }
+  return 0;
+}
+
+// Shared by classifyInstall and classifyUpgrade so the two can never read
+// "what version is already here" two different ways.
+function resolveInstalledVersionInfo(appDir) {
+  const liveComposePath = path.join(appDir, "docker-compose.yml");
+  if (!existsSync(appDir) || !existsSync(liveComposePath)) {
+    return { exists: false, installedVersion: null, state: null };
+  }
+  const statePath = path.join(appDir, "install-state.json");
+  const state = readJsonSafe(statePath);
+  const pinned = parsePinnedServerVersion(readTextSafe(liveComposePath));
+  const installedVersion = state?.packageVersion ?? pinned ?? null;
+  return { exists: true, installedVersion, state };
+}
+
+// fresh: nothing installed here yet.
+// repair: something is here (a live compose exists) but there is no state
+//   file we trust to say what version it is (e.g. a Windows-GUI-only
+//   install, or a corrupt state file) — never guess, ask for a repair.
+// upgrade / same-version: read from install-state.json's packageVersion
+//   (falling back to the live compose's pinned tag) compared against the
+//   version of the package currently running.
+export function classifyInstall({ appDir, currentVersion }) {
+  const info = resolveInstalledVersionInfo(appDir);
+  if (!info.exists) return "fresh";
+  if (!info.installedVersion || !info.state) return "repair";
+
+  const cmp = compareVersions(info.installedVersion, currentVersion);
+  if (cmp === 0) return "same-version";
+  if (cmp === -1) return "upgrade";
+  return "repair"; // installed reads NEWER than this package — never silently downgrade
+}
+
+// CF20-T6 — wires classifyInstall (T3 review Minor #4: implemented, tested,
+// ORPHANED — nothing called it) into the postinstall flow, and splits
+// classifyInstall's "repair" bucket into the two shapes postinstall must
+// message and record differently:
+//   - a genuinely unknown install (no trusted version info at all), vs.
+//   - "downgrade-package": npm delivered an OLDER getculpa than the
+//     version already staged here (a stale mirror, a pinned older version,
+//     an explicit rollback) — never silently downgrade.
+// previousVersion is best-effort (state's packageVersion first, the live
+// compose's pinned tag as fallback) and is null only for a genuinely fresh
+// install.
+export function classifyUpgrade({ appDir, currentVersion }) {
+  const classification = classifyInstall({ appDir, currentVersion });
+  const { installedVersion: previousVersion } = resolveInstalledVersionInfo(appDir);
+  if (classification === "repair" && previousVersion && compareVersions(previousVersion, currentVersion) === 1) {
+    return { classification: "downgrade-package", previousVersion };
+  }
+  return { classification, previousVersion };
+}
+
+// CF20-T6 — mirrors launch-culpa.ps1's Test-BackwardPin one-direction rule
+// (QW-1/QW-3 semantics) so the SHIPPED culpa-compose.yml can get the same
+// protection the live compose already has via provision.mjs's
+// stageLiveComposeIfAbsent: an older shipped file must never silently win
+// over a newer one already staged — the downgrade-package case. A malformed
+// incoming pin against a well-formed staged baseline fails CLOSED (treated
+// as older, the same asymmetry Test-BackwardPin uses); an absent incoming
+// or staged pin is permissive — there is no provable baseline to violate.
+export function isIncomingComposeOlder(incomingComposeText, stagedComposeText) {
+  const incoming = parsePinnedServerVersion(incomingComposeText);
+  const staged = parsePinnedServerVersion(stagedComposeText);
+  if (!incoming || !staged) return false;
+  const rx = /^v?(\d+)\.(\d+)\.(\d+)/;
+  if (!rx.test(incoming) && rx.test(staged)) return true;
+  return compareVersions(incoming, staged) === -1;
+}
+
+function readJsonSafe(filePath) {
+  try {
+    return JSON.parse(readFileSync(filePath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function readTextSafe(filePath) {
+  try {
+    return readFileSync(filePath, "utf8");
+  } catch {
+    return "";
+  }
+}

package/lib/provision.d.mts

@@ -0,0 +1,54 @@
+import type { UpgradeClassification } from "./preflight.d.mts";
+
+export const PARITY_ASSETS: string[];
+
+// T-CF28-6 — the Windows-only subset, and the platform-scoped accessor that
+// provision(), repair() and doctor() all read.
+export const WINDOWS_ONLY_ASSETS: readonly string[];
+export function parityAssetsFor(platform?: string): string[];
+
+// T-CF29-8 — the app-dir name culpa-collector.ps1 reads (Node platform-arch),
+// not the Rust target triple the release asset uses.
+export function collectorBinaryName(platform?: string, arch?: string): string;
+
+// Exported so lib/repair.mjs stages the collector to the SAME place with the
+// SAME name — the two must never disagree about where capture lives.
+export function stageCollectorBinary(opts: {
+  appDir: string;
+  vendorDir: string;
+  platform?: string;
+  arch?: string;
+}): boolean;
+
+// CF20-T5: exported for lib/repair.mjs's reuse — see provision.mjs's comment
+// on the export.
+export function stageParityFiles(
+  appDir: string,
+  env?: Record<string, string | undefined>,
+  platform?: string,
+): void;
+export function stageLiveComposeIfAbsent(appDir: string): boolean;
+
+export interface ProvisionOptions {
+  appDir: string;
+  currentVersion: string;
+  collectorFetched?: boolean;
+  platform?: string;
+  arch?: string;
+  vendorDir?: string;
+  dockerSpawnSync?: (cmd: string, args?: string[], opts?: unknown) => { status: number | null };
+  delegateWindowsInstaller?: (appDir: string) => boolean;
+  env?: Record<string, string | undefined>;
+}
+
+export type DockerState = "missing" | "installed-not-running" | "ready";
+
+export interface ProvisionResult {
+  classification: UpgradeClassification;
+  previousVersion: string | null;
+  dockerState: DockerState;
+  imagesStaged: boolean;
+  collectorStaged: boolean;
+}
+
+export function provision(opts: ProvisionOptions): Promise<ProvisionResult>;