getculpa 1.0.1 → 1.0.2

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>;

package/lib/repair.mjs

@@ -1,135 +1,174 @@
-// CF20-T5 — `getculpa repair`. Re-stages missing/corrupt parity files from
-// the packaged assets, regenerates install-state.json if unreadable,
-// re-fetches a missing launcher/collectord, and does none of this
-// destructively: an EXISTING docker-compose.yml (the live pin) is never
-// touched (the edcf97f invariant this task's reviewer condition names), no
-// `docker volume` command is ever issued (data is never touched), and a
-// second run changes nothing that was already healthy (idempotent).
-//
-// Reuses lib/provision.mjs's own stageParityFiles/stageLiveComposeIfAbsent
-// (exported additively for this purpose — see that file's comment) instead
-// of re-implementing file staging here.
-
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-import { spawnSync as realSpawnSync } from "node:child_process";
-import { stageLiveComposeIfAbsent, stageParityFiles, PARITY_ASSETS } from "./provision.mjs";
-import { fetchCollectord, fetchLauncher } from "./fetch.mjs";
-import { checkDockerEngineReachable, checkDockerPresent } from "./preflight.mjs";
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const packageRoot = path.join(__dirname, "..");
-
-function readJsonSafe(filePath) {
-  try {
-    return JSON.parse(readFileSync(filePath, "utf8"));
-  } catch {
-    return null;
-  }
-}
-
-function detectDockerState(dockerSpawnSync) {
-  if (!checkDockerPresent(dockerSpawnSync)) return "missing";
-  if (!checkDockerEngineReachable(dockerSpawnSync)) return "installed-not-running";
-  return "ready";
-}
-
-function vendorBinaryPath(vendorDir, name, platform) {
-  const exe = platform === "win32" ? ".exe" : "";
-  return path.join(vendorDir, `${name}${exe}`);
-}
-
-export async function repair(opts) {
-  const {
-    appDir,
-    currentVersion,
-    platform = process.platform,
-    vendorDir = path.join(packageRoot, "vendor"),
-    dockerSpawnSync = realSpawnSync,
-    fetchLauncherFn = fetchLauncher,
-    fetchCollectordFn = fetchCollectord,
-    log = console.log,
-  } = opts;
-
-  const actions = [];
-
-  if (!existsSync(appDir)) {
-    mkdirSync(appDir, { recursive: true });
-    actions.push(`created the missing app directory (${appDir})`);
-  }
-
-  // 1. Parity files — re-stage anything missing. stageParityFiles never
-  //    touches docker-compose.yml (it doesn't reference that name at all),
-  //    so this step alone already satisfies "never touch a live compose".
-  const missingBefore = PARITY_ASSETS.filter((name) => !existsSync(path.join(appDir, name)));
-  stageParityFiles(appDir);
-  for (const name of missingBefore) {
-    actions.push(`restored missing parity file: ${name}`);
-  }
-
-  // 2. Live compose — created ONLY if entirely absent; an existing one is
-  //    never overwritten (stageLiveComposeIfAbsent's own contract).
-  const composeCreated = stageLiveComposeIfAbsent(appDir);
-  if (composeCreated) {
-    actions.push("live docker-compose.yml was missing - recreated from the shipped culpa-compose.yml");
-  }
-
-  // 3. install-state.json — regenerate only when missing/corrupt. The
-  //    regenerated state is a conservative snapshot of what is actually on
-  //    disk right now: dockerState/collectorStaged are re-detected,
-  //    imagesStaged is set false (safe default — worst case is one extra
-  //    `docker compose pull` message at the next `getculpa`, never data
-  //    loss, mirroring deferredPullCatchUp's own contract in lib/start.mjs).
-  const existingState = readJsonSafe(path.join(appDir, "install-state.json"));
-  if (!existingState) {
-    const dockerState = detectDockerState(dockerSpawnSync);
-    const collectorStaged = existsSync(vendorBinaryPath(vendorDir, "culpa-collectord", platform));
-    const regenerated = {
-      packageVersion: currentVersion,
-      provisionedAt: new Date().toISOString(),
-      dockerState,
-      imagesStaged: false,
-      collectorStaged,
-      platform,
-    };
-    writeFileSync(path.join(appDir, "install-state.json"), `${JSON.stringify(regenerated, null, 2)}\n`);
-    actions.push("install-state.json was missing or unreadable - regenerated");
-  }
-
-  // 4. Launcher / collectord — re-fetch only when the vendored binary is
-  //    genuinely absent. Never re-fetches when present (idempotent, and the
-  //    task's explicit invocation-recording fact). The launcher is REQUIRED
-  //    (doctor.mjs's checkVendoredLauncher fails the same way when it's
-  //    missing) — a failed re-fetch must make repair's own result say so,
-  //    not just log and report ok:true (CF20-R review). The collector stays
-  //    optional/non-fatal: capture-off is a valid degraded state.
-  const launcherPath = vendorBinaryPath(vendorDir, "culpa-launcher", platform);
-  if (!existsSync(launcherPath)) {
-    try {
-      await fetchLauncherFn({ vendorDir });
-      actions.push("the launcher was missing - re-fetched and verified");
-    } catch (e) {
-      log(`getculpa repair: could not re-fetch the launcher (${e.message}). Run \`getculpa repair\` again once online.`);
-    }
-  }
-
-  const collectordPath = vendorBinaryPath(vendorDir, "culpa-collectord", platform);
-  if (!existsSync(collectordPath)) {
-    try {
-      await fetchCollectordFn({ vendorDir });
-      actions.push("the capture collector was missing - re-fetched and verified");
-    } catch (e) {
-      // fetchCollectord's own contract: "not published for this release yet"
-      // is an expected, non-fatal outcome (see lib/fetch.mjs) — repair must
-      // degrade the same way, never abort over an optional component.
-      log(`getculpa repair: capture collector not re-fetched (${e.message}).`);
-    }
-  }
-
-  if (actions.length === 0) log("getculpa repair: nothing to do - this install is already healthy.");
-  else for (const a of actions) log(`getculpa repair: ${a}`);
-
-  const launcherOk = existsSync(launcherPath);
-  return { ok: launcherOk, actions };
-}
+// CF20-T5 — `getculpa repair`. Re-stages missing/corrupt parity files from
+// the packaged assets, regenerates install-state.json if unreadable,
+// re-fetches a missing launcher/collectord, and does none of this
+// destructively: an EXISTING docker-compose.yml (the live pin) is never
+// touched (the edcf97f invariant this task's reviewer condition names), no
+// `docker volume` command is ever issued (data is never touched), and a
+// second run changes nothing that was already healthy (idempotent).
+//
+// Reuses lib/provision.mjs's own stageParityFiles/stageLiveComposeIfAbsent
+// (exported additively for this purpose — see that file's comment) instead
+// of re-implementing file staging here.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync as realSpawnSync } from "node:child_process";
+import {
+  collectorBinaryName,
+  parityAssetsFor,
+  stageCollectorBinary,
+  stageLiveComposeIfAbsent,
+  stageParityFiles,
+} from "./provision.mjs";
+import { fetchCollectord, fetchLauncher } from "./fetch.mjs";
+import { checkDockerEngineReachable, checkDockerPresent } from "./preflight.mjs";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const packageRoot = path.join(__dirname, "..");
+
+function readJsonSafe(filePath) {
+  try {
+    return JSON.parse(readFileSync(filePath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function detectDockerState(dockerSpawnSync) {
+  if (!checkDockerPresent(dockerSpawnSync)) return "missing";
+  if (!checkDockerEngineReachable(dockerSpawnSync)) return "installed-not-running";
+  return "ready";
+}
+
+function vendorBinaryPath(vendorDir, name, platform) {
+  const exe = platform === "win32" ? ".exe" : "";
+  return path.join(vendorDir, `${name}${exe}`);
+}
+
+export async function repair(opts) {
+  const {
+    appDir,
+    currentVersion,
+    platform = process.platform,
+    arch = process.arch,
+    vendorDir = path.join(packageRoot, "vendor"),
+    dockerSpawnSync = realSpawnSync,
+    fetchLauncherFn = fetchLauncher,
+    fetchCollectordFn = fetchCollectord,
+    log = console.log,
+  } = opts;
+
+  const actions = [];
+
+  if (!existsSync(appDir)) {
+    mkdirSync(appDir, { recursive: true });
+    actions.push(`created the missing app directory (${appDir})`);
+  }
+
+  // 1. Parity files — re-stage anything missing. stageParityFiles never
+  //    touches docker-compose.yml (it doesn't reference that name at all),
+  //    so this step alone already satisfies "never touch a live compose".
+  // T-CF28-6: platform-scoped, or repair would restore the four Windows .ps1
+  // files provisioning deliberately skips on darwin/linux — and report each
+  // one as a "restored missing parity file" action while doing it.
+  const missingBefore = parityAssetsFor(platform).filter((name) => !existsSync(path.join(appDir, name)));
+  stageParityFiles(appDir, process.env, platform);
+  for (const name of missingBefore) {
+    actions.push(`restored missing parity file: ${name}`);
+  }
+
+  // 2. Live compose — created ONLY if entirely absent; an existing one is
+  //    never overwritten (stageLiveComposeIfAbsent's own contract).
+  const composeCreated = stageLiveComposeIfAbsent(appDir);
+  if (composeCreated) {
+    actions.push("live docker-compose.yml was missing - recreated from the shipped culpa-compose.yml");
+  }
+
+  // 3. install-state.json — regenerate only when missing/corrupt. The
+  //    regenerated state is a conservative snapshot of what is actually on
+  //    disk right now: dockerState/collectorStaged are re-detected,
+  //    imagesStaged is set false (safe default — worst case is one extra
+  //    `docker compose pull` message at the next `getculpa`, never data
+  //    loss, mirroring deferredPullCatchUp's own contract in lib/start.mjs).
+  const existingState = readJsonSafe(path.join(appDir, "install-state.json"));
+  if (!existingState) {
+    const dockerState = detectDockerState(dockerSpawnSync);
+    // Review of 0e4b2e2: this derived collectorStaged from the PACKAGE
+    // vendor dir, which is not what culpa-collector.ps1:35 reads. It could
+    // therefore regenerate install-state.json saying capture was staged
+    // while the app dir held no collector at all — the same false positive
+    // T-CF29-8 removed from provision(). One invariant, both writers.
+    const collectorStaged = existsSync(path.join(appDir, collectorBinaryName(platform, arch)));
+    const regenerated = {
+      packageVersion: currentVersion,
+      provisionedAt: new Date().toISOString(),
+      dockerState,
+      imagesStaged: false,
+      collectorStaged,
+      platform,
+    };
+    writeFileSync(path.join(appDir, "install-state.json"), `${JSON.stringify(regenerated, null, 2)}\n`);
+    actions.push("install-state.json was missing or unreadable - regenerated");
+  }
+
+  // 4. Launcher / collectord — re-fetch only when the vendored binary is
+  //    genuinely absent. Never re-fetches when present (idempotent, and the
+  //    task's explicit invocation-recording fact). The launcher is REQUIRED
+  //    (doctor.mjs's checkVendoredLauncher fails the same way when it's
+  //    missing) — a failed re-fetch must make repair's own result say so,
+  //    not just log and report ok:true (CF20-R review). The collector stays
+  //    optional/non-fatal: capture-off is a valid degraded state.
+  const launcherPath = vendorBinaryPath(vendorDir, "culpa-launcher", platform);
+  if (!existsSync(launcherPath)) {
+    try {
+      await fetchLauncherFn({ vendorDir });
+      actions.push("the launcher was missing - re-fetched and verified");
+    } catch (e) {
+      log(`getculpa repair: could not re-fetch the launcher (${e.message}). Run \`getculpa repair\` again once online.`);
+    }
+  }
+
+  const collectordPath = vendorBinaryPath(vendorDir, "culpa-collectord", platform);
+  if (!existsSync(collectordPath)) {
+    try {
+      await fetchCollectordFn({ vendorDir });
+      actions.push("the capture collector was missing - re-fetched and verified");
+    } catch (e) {
+      // fetchCollectord's own contract: "not published for this release yet"
+      // is an expected, non-fatal outcome (see lib/fetch.mjs) — repair must
+      // degrade the same way, never abort over an optional component.
+      log(`getculpa repair: capture collector not re-fetched (${e.message}).`);
+    }
+  }
+
+  // Review of 0e4b2e2: re-fetching only refilled the PACKAGE vendor dir, so
+  // "re-fetched and verified" claimed a repair that left capture exactly as
+  // broken as it found it. The app-dir copy is the one that matters.
+  const appCollector = path.join(appDir, collectorBinaryName(platform, arch));
+  if (!existsSync(appCollector) && stageCollectorBinary({ appDir, vendorDir, platform, arch })) {
+    actions.push("the capture collector was missing from the app directory - staged it");
+  }
+
+  // The state file may have been regenerated BEFORE the staging above, so
+  // correct it to what is now true rather than leaving a stale answer.
+  const statePath = path.join(appDir, "install-state.json");
+  const finalState = readJsonSafe(statePath);
+  const collectorTruth = existsSync(appCollector);
+  // Review of 4e45f81: this used to correct the file and say NOTHING, so a
+  // run that really did change something reported "nothing to do - this
+  // install is already healthy". Same class of false claim the rest of this
+  // commit removes, just relocated into the action log.
+  if (finalState && finalState.collectorStaged !== collectorTruth) {
+    actions.push(
+      `install-state.json claimed capture was ${finalState.collectorStaged ? "staged" : "absent"} - corrected to match the app directory`,
+    );
+    writeFileSync(statePath, `${JSON.stringify({ ...finalState, collectorStaged: collectorTruth }, null, 2)}\n`);
+  }
+
+  if (actions.length === 0) log("getculpa repair: nothing to do - this install is already healthy.");
+  else for (const a of actions) log(`getculpa repair: ${a}`);
+
+  const launcherOk = existsSync(launcherPath);
+  return { ok: launcherOk, actions };
+}

package/lib/start.d.mts

@@ -28,6 +28,8 @@ export interface StartOptions {
   openBrowser?: (url: string) => void;
   isTTY?: boolean;
   delegateWindowsLaunch?: (appDir: string) => { ok: boolean; output?: string };
+  isInteractive?: boolean;
+  askYesNo?: (question: string) => Promise<boolean>;
 }
 
 export interface StartResult {