getculpa 1.0.1 → 1.0.3

package/lib/install-summary.mjs

@@ -0,0 +1,156 @@
+// 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.";
+  }
+}
+
+// V102 T-V102-15 (M3, D-113): the row reports the three REAL states read
+// from updates/state.json (readPayloadState), never the updater's exit code
+// — the shipped 1.0.2 printed "Culpa CLI: installed" on a Mac whose
+// state.json read current: null, while doctor FAILed the same install.
+const PAYLOAD_ROW = {
+  installed: "installed",
+  staged: "staged - activates at your next `getculpa`",
+  missing: "deferred - run `getculpa update` to finish",
+};
+
+function inventory(appDir, imagesStaged, collectorStaged, payloadState) {
+  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: ${PAYLOAD_ROW[payloadState] ?? PAYLOAD_ROW.missing}`,
+    `  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 / V102 T-V102-15. 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
+    // passes the real state read from updates/state.json (readPayloadState).
+    payloadState = "missing",
+    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.
+  // "staged" keeps it: the pending version activates at that very launch.
+  const ready = dockerReady && payloadState !== "missing";
+  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, payloadState));
+  }
+
+  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.mjs

@@ -19,6 +19,12 @@ import path from "node:path";
 // "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;

package/lib/provision.d.mts

@@ -2,9 +2,31 @@ 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>): void;
+export function stageParityFiles(
+  appDir: string,
+  env?: Record<string, string | undefined>,
+  platform?: string,
+): void;
 export function stageLiveComposeIfAbsent(appDir: string): boolean;
 
 export interface ProvisionOptions {
@@ -12,14 +34,21 @@ export interface ProvisionOptions {
   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>;

package/lib/provision.mjs

@@ -16,12 +16,20 @@
 import { spawnSync as realSpawnSync } from "node:child_process";
 import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 import { checkDockerEngineReachable, checkDockerPresent, classifyUpgrade, isIncomingComposeOlder } from "./preflight.mjs";
 import { resolveAssetPath } from "./assets.mjs";
 import { canonicalAppDir } from "./paths.mjs";
 
+// T-CF29-8: where lib/fetch.mjs stages the vendored binaries. Same derivation
+// lib/repair.mjs already uses, so the two agree on one vendor directory.
+const packageRoot = path.join(path.dirname(fileURLToPath(import.meta.url)), "..");
+
 // The full parity file-set (Windows inventory: culpa-setup.iss:43-54, minus
 // the collectord binary, which lib/fetch.mjs stages separately by triple).
+// This is the WINDOWS inventory and stays the canonical full list — use
+// parityAssetsFor(platform) to get what a given platform should actually
+// receive.
 export const PARITY_ASSETS = [
   "culpa-compose.yml",
   "install-culpa.ps1",
@@ -31,6 +39,29 @@ export const PARITY_ASSETS = [
   "register.mjs",
 ];
 
+// T-CF28-6 — four of the six are PowerShell scripts that only win32 can run:
+// lib/start.mjs delegates to launch-culpa.ps1 only when platform === "win32"
+// (start.mjs:457), lib/uninstall.mjs only delegates to uninstall-culpa.ps1 on
+// win32 (uninstall.mjs:80-82), and install-culpa.ps1/culpa-collector.ps1 are
+// invoked by the Windows installer path alone. Staging them on darwin/linux
+// put four inert files in the user's app dir and made `getculpa doctor` grade
+// them as part of a healthy install.
+export const WINDOWS_ONLY_ASSETS = Object.freeze([
+  "install-culpa.ps1",
+  "launch-culpa.ps1",
+  "uninstall-culpa.ps1",
+  "culpa-collector.ps1",
+]);
+
+// The single source of truth for "which parity files belong on this platform".
+// provision(), repair() and doctor() ALL read it — if any one of them used the
+// flat list instead, repair would restore what provision skipped, or doctor
+// would fail an install for a file that is correctly absent.
+export function parityAssetsFor(platform = process.platform) {
+  if (platform === "win32") return PARITY_ASSETS;
+  return PARITY_ASSETS.filter((name) => !WINDOWS_ONLY_ASSETS.includes(name));
+}
+
 // CF20-T6 — protects the SHIPPED culpa-compose.yml the same way
 // stageLiveComposeIfAbsent already protects the live one, mirroring
 // launch-culpa.ps1's QW-1 one-direction rule: an older incoming pin must
@@ -60,10 +91,10 @@ function stageShippedCompose(appDir, env) {
 // logic — same reason the task instructions call out reuse over a second
 // copy. Purely additive: behavior and call sites inside this file are
 // unchanged.
-export function stageParityFiles(appDir, env = process.env) {
+export function stageParityFiles(appDir, env = process.env, platform = process.platform) {
   mkdirSync(appDir, { recursive: true });
   stageShippedCompose(appDir, env);
-  for (const name of PARITY_ASSETS) {
+  for (const name of parityAssetsFor(platform)) {
     if (name === "culpa-compose.yml") continue;
     copyFileSync(resolveAssetPath(name), path.join(appDir, name));
   }
@@ -79,6 +110,40 @@ export function stageLiveComposeIfAbsent(appDir) {
   return true;
 }
 
+// T-CF29-8 — the name culpa-collector.ps1:35 reads from the app dir, and the
+// same name culpa-setup.iss:52 installs there. NOT the Rust target triple
+// lib/fetch.mjs uses for the release asset (x86_64-pc-windows-msvc): this is
+// the Node-style platform-arch pair.
+export function collectorBinaryName(platform = process.platform, arch = process.arch) {
+  const exe = platform === "win32" ? ".exe" : "";
+  return `culpa-collectord-${platform}-${arch}${exe}`;
+}
+
+// T-CF29-8 — capture was silently OFF on every Windows npm install:
+// "culpa-collectord-win32-x64.exe not present in this package - skipping
+// capture setup". lib/fetch.mjs stages the binary into the PACKAGE's vendor/
+// as culpa-collectord.exe, the .ps1 reads it from the APP DIR under the
+// triple-suffixed name, and nothing bridged the two. The Windows installer
+// path has always put it in the app dir, so this is the npm path catching up
+// to installer parity, not a new convention.
+//
+// Returns whether the binary is really there afterwards — never a hopeful
+// echo of the caller's collectorFetched flag, because "capture is on" is
+// exactly the kind of claim that must be backed by a file on disk.
+export function stageCollectorBinary({ appDir, vendorDir, platform, arch }) {
+  const exe = platform === "win32" ? ".exe" : "";
+  const src = path.join(vendorDir, `culpa-collectord${exe}`);
+  if (!existsSync(src)) return false;
+  const dest = path.join(appDir, collectorBinaryName(platform, arch));
+  try {
+    copyFileSync(src, dest);
+  } catch (e) {
+    console.warn(`getculpa: capture collector could not be staged (${e.message}) - capture OFF, everything else works.`);
+    return false;
+  }
+  return existsSync(dest);
+}
+
 function detectDockerState(dockerSpawnSync) {
   if (!checkDockerPresent(dockerSpawnSync)) return "missing";
   if (!checkDockerEngineReachable(dockerSpawnSync)) return "installed-not-running";
@@ -152,6 +217,8 @@ export async function provision(opts) {
     currentVersion,
     collectorFetched = false,
     platform = process.platform,
+    arch = process.arch,
+    vendorDir = path.join(packageRoot, "vendor"),
     dockerSpawnSync = realSpawnSync,
     delegateWindowsInstaller = defaultDelegateWindowsInstaller,
     env = process.env,
@@ -179,10 +246,19 @@ export async function provision(opts) {
       `getculpa: this package is older than the installed Culpa ${previousVersion} - skipping the parity file re-stage entirely (compose, scripts, register.mjs) to avoid a mixed-version app dir (set CULPA_ALLOW_DOWNGRADE=1 to override).`,
     );
   } else {
-    stageParityFiles(appDir, env);
+    stageParityFiles(appDir, env, platform);
   }
   stageLiveComposeIfAbsent(appDir);
 
+  // T-CF29-8: only attempt it when the fetch reported success; the result is
+  // what gets recorded, not the intent.
+  const collectorStaged = collectorFetched && stageCollectorBinary({ appDir, vendorDir, platform, arch });
+  if (collectorFetched && !collectorStaged) {
+    console.warn(
+      "getculpa: the capture collector was downloaded but could not be placed in the app directory - capture OFF, everything else works.",
+    );
+  }
+
   const dockerState = detectDockerState(dockerSpawnSync);
   let imagesStaged = false;
   if (dockerState === "ready") {
@@ -229,9 +305,14 @@ export async function provision(opts) {
     updatedAt: new Date().toISOString(),
     dockerState,
     imagesStaged,
-    collectorStaged: collectorFetched,
+    collectorStaged,
     platform,
   });
 
-  return { classification, previousVersion };
+  // T-CF28-5/7: the Docker and staging facts were already computed above and
+  // written to install-state.json, but the caller that has to REPORT them
+  // (scripts/install.js) could not see them — which is how a Docker-less
+  // install still printed "Culpa installed successfully." Returning them
+  // changes no behavior here; it just stops postinstall from having to guess.
+  return { classification, previousVersion, dockerState, imagesStaged, collectorStaged };
 }

package/lib/repair.d.mts

@@ -5,6 +5,7 @@ export interface RepairOptions {
   appDir: string;
   currentVersion: string;
   platform?: string;
+  arch?: string;
   vendorDir?: string;
   dockerSpawnSync?: SpawnSyncLike;
   fetchLauncherFn?: (opts?: { vendorDir?: string }) => Promise<FetchResult>;