getculpa 1.0.7 → 1.0.10

package/lib/uninstall.d.mts

@@ -1,17 +1,20 @@
-export interface UninstallOptions {
-  appDir?: string;
-  platform?: string;
-  spawnSync?: (cmd: string, args?: string[], opts?: unknown) => { status: number | null };
-  homedir?: string;
-  createInterface?: (opts: { input: NodeJS.ReadStream; output: NodeJS.WriteStream }) => {
-    question: (prompt: string, cb: (answer: string) => void) => void;
-    close: () => void;
-  };
-  isTTY?: boolean;
-}
-
-export interface UninstallResult {
-  ok: boolean;
-}
-
-export function uninstall(opts?: UninstallOptions): Promise<UninstallResult>;
+export interface UninstallOptions {
+  appDir?: string;
+  platform?: string;
+  spawnSync?: (cmd: string, args?: string[], opts?: unknown) => { status: number | null };
+  homedir?: string;
+  createInterface?: (opts: { input: NodeJS.ReadStream; output: NodeJS.WriteStream }) => {
+    question: (prompt: string, cb: (answer: string) => void) => void;
+    close: () => void;
+  };
+  isTTY?: boolean;
+  /** Set by the npm `preuninstall` hook: suppress the "npm uninstall -g getculpa"
+   *  next-step hint (we are already inside that command). D-126 / v1.0.9. */
+  fromNpmHook?: boolean;
+}
+
+export interface UninstallResult {
+  ok: boolean;
+}
+
+export function uninstall(opts?: UninstallOptions): Promise<UninstallResult>;

package/lib/uninstall.mjs

@@ -1,138 +1,158 @@
-// CF20-T3 — `getculpa uninstall`. win32 delegates to the same
-// uninstall-culpa.ps1 the Windows installer ships (canonical-path guard,
-// collector stop, compose down, pgdata prompt all live there already).
-// macOS/Linux implement the same net effect once: compose down, remove the
-// shortcut equivalents this core lays down, prompt for pgdata removal
-// (TTY only — never destructive without an interactive terminal), then
-// point at `npm uninstall -g getculpa` to remove the CLI itself.
-
-import { spawnSync as realSpawnSync } from "node:child_process";
-import { existsSync, rmSync } from "node:fs";
-import os from "node:os";
-import path from "node:path";
-import readline from "node:readline";
-import { getAppDir } from "./paths.mjs";
-
-function delegateWindowsUninstall(appDir, spawnSync) {
-  const script = path.join(appDir, "uninstall-culpa.ps1");
-  const result = spawnSync("powershell.exe", ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", script], {
-    stdio: "inherit",
-  });
-  // uninstall-culpa.ps1 stops the capture collector itself before stopping
-  // the stack (CF19 CodeRabbit PR#16 #289) — non-fatally, with no exit-code
-  // gate on that one step, so a collector-stop hiccup alone never fails this
-  // delegate. This return value IS the delegate's true overall outcome
-  // (stack stop + everything else the script does), inherited straight to
-  // the console via stdio:"inherit" either way.
-  return result.status === 0;
-}
-
-// CF20-R: guard the case where there is nothing to bring down (a fresh app
-// dir, or one already fully torn down) — running `docker compose -f
-// <nonexistent file> ... down` would just fail loudly for no real reason.
-// A genuine compose-down failure (the file exists, the command ran, and
-// docker refused) DOES surface as a failure — see the caller.
-function composeDown(appDir, spawnSync) {
-  const compose = path.join(appDir, "docker-compose.yml");
-  if (!existsSync(compose)) {
-    console.log("getculpa: no docker-compose.yml found - nothing to stop.");
-    return true;
-  }
-  const result = spawnSync("docker", ["compose", "-f", compose, "-p", "culpa", "down"], { stdio: "inherit" });
-  if (result.status !== 0) {
-    console.error("getculpa: `docker compose down` did not complete cleanly - see the output above.");
-  }
-  return result.status === 0;
-}
-
-// The only shortcut this core lays down outside the app dir on macOS is the
-// Desktop .webloc (installers/macos/install-culpa.command:132-142); Linux
-// ships no shortcut convention yet, so there is nothing else to remove.
-function removeShortcutEquivalents(homedir) {
-  rmSync(path.join(homedir, "Desktop", "Culpa Dashboard.webloc"), { force: true });
-}
-
-// Never destructive without a real interactive terminal — a non-TTY caller
-// (CI, a script, npm's own postinstall/preuninstall hooks) always gets NO.
-// isTTY is injectable (same pattern as lib/start.mjs's maybeOpenBrowser)
-// rather than read from the live process.stdin.isTTY directly, so tests
-// assert the safe default deliberately instead of relying on vitest's own
-// stdin happening to be non-TTY.
-async function promptPgdataRemoval(createInterface, isTTY) {
-  if (!isTTY) return false;
-  const rl = createInterface({ input: process.stdin, output: process.stdout });
-  const answer = await new Promise((resolve) => {
-    // V102 T-V102-16 (D-113): EOF (Ctrl-D, or a stdin that ends mid-prompt)
-    // fires `close` and NEVER invokes question()'s callback — this promise
-    // used to hang forever at the one prompt guarding DELETION of the cost
-    // database. An unanswered question is a NO, exactly like tty.mjs.
-    // Optional-call: older injected fakes without `once` keep working.
-    rl.once?.("close", () => resolve(""));
-    rl.question("Also DELETE all recorded cost data? This cannot be undone. (y/N) ", resolve);
-  });
-  rl.close();
-  return answer.trim().toLowerCase() === "y";
-}
-
-// V102 T-V102-16 (M11/W2, D-113): macOS uninstall exited 0 leaving ~7.3 MB
-// (launcher, collector, compose, register.mjs) silently behind — the Windows
-// ps1 removes the app dir and is "the more complete of the two" (W2). Remove
-// the dir ONLY when it is provably a Culpa install dir (install-state.json,
-// which every install writes); a mistargeted CULPA_APP_DIR is kept and said.
-// Truthful beats a surprise rm -rf in both directions.
-function removeAppDir(appDir) {
-  if (!existsSync(appDir)) return;
-  if (existsSync(path.join(appDir, "install-state.json"))) {
-    rmSync(appDir, { recursive: true, force: true });
-    console.log(`Removed: ${appDir} (launcher, collector, compose and capture shims).`);
-    return;
-  }
-  console.log(
-    `Kept: ${appDir} - no install-state.json found there, so it is not provably a Culpa install directory. Remove it yourself if you are sure.`,
-  );
-}
-
-export async function uninstall(opts = {}) {
-  const appDir = opts.appDir ?? getAppDir();
-  const platform = opts.platform ?? process.platform;
-  const spawnSync = opts.spawnSync ?? realSpawnSync;
-  const homedir = opts.homedir ?? os.homedir();
-  const createInterface = opts.createInterface ?? readline.createInterface;
-  const isTTY = opts.isTTY ?? process.stdin.isTTY;
-
-  let ok;
-  if (platform === "win32") {
-    ok = delegateWindowsUninstall(appDir, spawnSync);
-    if (!ok) console.error("getculpa: uninstall did not complete cleanly - see the output above.");
-  } else {
-    ok = composeDown(appDir, spawnSync);
-    // Review-4 IMPORTANT + CodeRabbit PR#19 [7] (Major): a FAILED stop skips
-    // EVERY destructive step — the ps1's $stackStopped gate, whose comment
-    // records the prior real incident (CR-PR5 round 3). Not even the pgdata
-    // PROMPT is offered: after a partial teardown the volume can be
-    // unreferenced, so a user confirming deletion here could lose the cost
-    // database while being told the stack is still running. Nothing is
-    // removed; the one honest instruction is to stop the stack and rerun.
-    if (!ok) {
-      console.log(
-        `Files kept: ${appDir} - the stack is still running (\`docker compose down\` failed above). Nothing was removed. Stop the stack, then run this again.`,
-      );
-    } else {
-      removeShortcutEquivalents(homedir);
-      const wipe = await promptPgdataRemoval(createInterface, isTTY);
-      if (wipe) {
-        spawnSync("docker", ["volume", "rm", "culpa_pgdata"], { stdio: "inherit" });
-        console.log("Data volume removed.");
-      } else {
-        console.log("Data kept (volume culpa_pgdata). Reinstalling later will find it again.");
-      }
-      // M11/W2: after the data decision, remove the app dir itself (ps1 parity)
-      removeAppDir(appDir);
-    }
-  }
-
-  console.log("");
-  console.log("To finish removing the Culpa CLI: npm uninstall -g getculpa");
-
-  return { ok };
-}
+// CF20-T3 — `getculpa uninstall`. win32 delegates to the same
+// uninstall-culpa.ps1 the Windows installer ships (canonical-path guard,
+// collector stop, compose down, pgdata prompt all live there already).
+// macOS/Linux implement the same net effect once: compose down, remove the
+// shortcut equivalents this core lays down, prompt for pgdata removal
+// (TTY only — never destructive without an interactive terminal), then
+// point at `npm uninstall -g getculpa` to remove the CLI itself.
+
+import { spawnSync as realSpawnSync } from "node:child_process";
+import { existsSync, rmSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import readline from "node:readline";
+import { getAppDir } from "./paths.mjs";
+
+function delegateWindowsUninstall(appDir, spawnSync, isTTY) {
+  const script = path.join(appDir, "uninstall-culpa.ps1");
+  // D-126: a non-interactive caller (the npm `preuninstall` hook, or any non-TTY
+  // run) MUST pass -Unattended so uninstall-culpa.ps1 skips every Read-Host — it
+  // would otherwise PROMPT to delete the cost database and BLOCK on "Press Enter"
+  // inside a silent `npm uninstall -g`. -Unattended still does the full
+  // self-teardown (remove the app dir + the script-install Add/Remove key), which
+  // -FromUninstaller (Inno's mode) deliberately does not. powershell's own
+  // -NonInteractive is added as a fail-fast: any stray prompt errors, never hangs.
+  const nonInteractive = !isTTY;
+  const args = ["-NoProfile"];
+  if (nonInteractive) args.push("-NonInteractive");
+  args.push("-ExecutionPolicy", "Bypass", "-File", script);
+  if (nonInteractive) args.push("-Unattended");
+  const result = spawnSync("powershell.exe", args, {
+    stdio: "inherit",
+  });
+  // uninstall-culpa.ps1 stops the capture collector itself before stopping
+  // the stack (CF19 CodeRabbit PR#16 #289) — non-fatally, with no exit-code
+  // gate on that one step, so a collector-stop hiccup alone never fails this
+  // delegate. This return value IS the delegate's true overall outcome
+  // (stack stop + everything else the script does), inherited straight to
+  // the console via stdio:"inherit" either way.
+  return result.status === 0;
+}
+
+// CF20-R: guard the case where there is nothing to bring down (a fresh app
+// dir, or one already fully torn down) — running `docker compose -f
+// <nonexistent file> ... down` would just fail loudly for no real reason.
+// A genuine compose-down failure (the file exists, the command ran, and
+// docker refused) DOES surface as a failure — see the caller.
+function composeDown(appDir, spawnSync) {
+  const compose = path.join(appDir, "docker-compose.yml");
+  if (!existsSync(compose)) {
+    console.log("getculpa: no docker-compose.yml found - nothing to stop.");
+    return true;
+  }
+  const result = spawnSync("docker", ["compose", "-f", compose, "-p", "culpa", "down"], { stdio: "inherit" });
+  if (result.status !== 0) {
+    console.error("getculpa: `docker compose down` did not complete cleanly - see the output above.");
+  }
+  return result.status === 0;
+}
+
+// The only shortcut this core lays down outside the app dir on macOS is the
+// Desktop .webloc (installers/macos/install-culpa.command:132-142); Linux
+// ships no shortcut convention yet, so there is nothing else to remove.
+function removeShortcutEquivalents(homedir) {
+  rmSync(path.join(homedir, "Desktop", "Culpa Dashboard.webloc"), { force: true });
+}
+
+// Never destructive without a real interactive terminal — a non-TTY caller
+// (CI, a script, npm's own postinstall/preuninstall hooks) always gets NO.
+// isTTY is injectable (same pattern as lib/start.mjs's maybeOpenBrowser)
+// rather than read from the live process.stdin.isTTY directly, so tests
+// assert the safe default deliberately instead of relying on vitest's own
+// stdin happening to be non-TTY.
+async function promptPgdataRemoval(createInterface, isTTY) {
+  if (!isTTY) return false;
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  const answer = await new Promise((resolve) => {
+    // V102 T-V102-16 (D-113): EOF (Ctrl-D, or a stdin that ends mid-prompt)
+    // fires `close` and NEVER invokes question()'s callback — this promise
+    // used to hang forever at the one prompt guarding DELETION of the cost
+    // database. An unanswered question is a NO, exactly like tty.mjs.
+    // Optional-call: older injected fakes without `once` keep working.
+    rl.once?.("close", () => resolve(""));
+    rl.question("Also DELETE all recorded cost data? This cannot be undone. (y/N) ", resolve);
+  });
+  rl.close();
+  return answer.trim().toLowerCase() === "y";
+}
+
+// V102 T-V102-16 (M11/W2, D-113): macOS uninstall exited 0 leaving ~7.3 MB
+// (launcher, collector, compose, register.mjs) silently behind — the Windows
+// ps1 removes the app dir and is "the more complete of the two" (W2). Remove
+// the dir ONLY when it is provably a Culpa install dir (install-state.json,
+// which every install writes); a mistargeted CULPA_APP_DIR is kept and said.
+// Truthful beats a surprise rm -rf in both directions.
+function removeAppDir(appDir) {
+  if (!existsSync(appDir)) return;
+  if (existsSync(path.join(appDir, "install-state.json"))) {
+    rmSync(appDir, { recursive: true, force: true });
+    console.log(`Removed: ${appDir} (launcher, collector, compose and capture shims).`);
+    return;
+  }
+  console.log(
+    `Kept: ${appDir} - no install-state.json found there, so it is not provably a Culpa install directory. Remove it yourself if you are sure.`,
+  );
+}
+
+export async function uninstall(opts = {}) {
+  const appDir = opts.appDir ?? getAppDir();
+  const platform = opts.platform ?? process.platform;
+  const spawnSync = opts.spawnSync ?? realSpawnSync;
+  const homedir = opts.homedir ?? os.homedir();
+  const createInterface = opts.createInterface ?? readline.createInterface;
+  const isTTY = opts.isTTY ?? process.stdin.isTTY;
+  // D-126 / v1.0.9: set by the npm `preuninstall` hook (scripts/preuninstall.js).
+  // When true we are ALREADY inside `npm uninstall -g getculpa`, so the trailing
+  // "To finish removing the Culpa CLI: npm uninstall -g getculpa" hint below is
+  // wrong/confusing — the hook owns the closing "what's left behind" summary.
+  // Teardown behaviour is otherwise identical.
+  const fromNpmHook = opts.fromNpmHook ?? false;
+
+  let ok;
+  if (platform === "win32") {
+    ok = delegateWindowsUninstall(appDir, spawnSync, isTTY);
+    if (!ok) console.error("getculpa: uninstall did not complete cleanly - see the output above.");
+  } else {
+    ok = composeDown(appDir, spawnSync);
+    // Review-4 IMPORTANT + CodeRabbit PR#19 [7] (Major): a FAILED stop skips
+    // EVERY destructive step — the ps1's $stackStopped gate, whose comment
+    // records the prior real incident (CR-PR5 round 3). Not even the pgdata
+    // PROMPT is offered: after a partial teardown the volume can be
+    // unreferenced, so a user confirming deletion here could lose the cost
+    // database while being told the stack is still running. Nothing is
+    // removed; the one honest instruction is to stop the stack and rerun.
+    if (!ok) {
+      console.log(
+        `Files kept: ${appDir} - the stack is still running (\`docker compose down\` failed above). Nothing was removed. Stop the stack, then run this again.`,
+      );
+    } else {
+      removeShortcutEquivalents(homedir);
+      const wipe = await promptPgdataRemoval(createInterface, isTTY);
+      if (wipe) {
+        spawnSync("docker", ["volume", "rm", "culpa_pgdata"], { stdio: "inherit" });
+        console.log("Data volume removed.");
+      } else {
+        console.log("Data kept (volume culpa_pgdata). Reinstalling later will find it again.");
+      }
+      // M11/W2: after the data decision, remove the app dir itself (ps1 parity)
+      removeAppDir(appDir);
+    }
+  }
+
+  if (!fromNpmHook) {
+    console.log("");
+    console.log("To finish removing the Culpa CLI: npm uninstall -g getculpa");
+  }
+
+  return { ok };
+}

package/package.json

@@ -1,25 +1,26 @@
-{
-  "name": "getculpa",
-  "version": "1.0.7",
-  "description": "Culpa CLI: `npm i -g getculpa` provisions the full Culpa install (Windows-installer parity) and leaves it dormant. `getculpa` wakes the stack.",
-  "license": "SEE LICENSE IN LICENSE",
-  "bin": {
-    "getculpa": "bin/getculpa.js",
-    "culpa": "bin/culpa.js"
-  },
-  "scripts": {
-    "postinstall": "node scripts/install.js",
-    "prepack": "node scripts/prepack.js"
-  },
-  "files": [
-    "bin/",
-    "lib/",
-    "scripts/",
-    "assets/",
-    "README.md",
-    "LICENSE"
-  ],
-  "engines": {
-    "node": ">=20"
-  }
-}
+{
+  "name": "getculpa",
+  "version": "1.0.10",
+  "description": "Culpa CLI: `npm i -g getculpa` provisions the full Culpa install (Windows-installer parity) and leaves it dormant. `getculpa` wakes the stack.",
+  "license": "SEE LICENSE IN LICENSE",
+  "bin": {
+    "getculpa": "bin/getculpa.js",
+    "culpa": "bin/culpa.js"
+  },
+  "scripts": {
+    "postinstall": "node scripts/install.js",
+    "preuninstall": "node scripts/preuninstall.js",
+    "prepack": "node scripts/prepack.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "scripts/",
+    "assets/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  }
+}

package/scripts/preuninstall.js

@@ -0,0 +1,82 @@
+// v1.0.9 (findings: ~/Downloads/10-uninstall-findings.md) — npm `preuninstall`
+// hook so `npm uninstall -g getculpa` actually DEPROVISIONS instead of leaving a
+// running stack, ~400MB of images and the stored credentials behind (the P1
+// findings: the CLI that could clean up was the very thing being deleted).
+//
+// npm runs this NON-INTERACTIVELY (no TTY), so it drives the same teardown as
+// `getculpa uninstall` in its safe, data-preserving default: stop the stack +
+// remove the `culpa` network, the Desktop shortcut and the app dir (which also
+// clears the stale install-state.json — findings P3). It NEVER deletes the data
+// volumes: a silent hook must not destroy the cost database or the stored
+// licence. It then prints exactly what is left behind, with the one-line removal
+// command (the findings' suggested fix).
+//
+// A nonzero exit does NOT stop `npm uninstall -g` (verified: node 20.19.6 /
+// npm 11.x, D-126), so the Windows Inno "cancel-on-nonzero" control cannot be
+// replicated here. The honest ceiling npm allows is a loud warning on a failed
+// stop; we give it and still exit 0 (a nonzero exit only adds "npm error" noise
+// while npm removes the package anyway).
+
+"use strict";
+
+// Dependency-injected so the summary / stop-failure messaging is unit-testable in
+// isolation (a fake `uninstall`, captured log/err) — mirrors the injection style
+// of tests/npm-core-uninstall.test.ts. The npm entry (bottom) wires the real deps.
+async function runPreuninstall(deps = {}) {
+  const importUninstall = deps.importUninstall ?? (() => import("../lib/uninstall.mjs"));
+  const log = deps.log ?? console.log;
+  const err = deps.err ?? console.error;
+
+  const { uninstall } = await importUninstall();
+
+  log("");
+  log("getculpa: uninstalling — stopping the Culpa stack and removing install files...");
+
+  let ok = false;
+  try {
+    ({ ok } = await uninstall({ isTTY: false, fromNpmHook: true }));
+  } catch (e) {
+    // A teardown error must never crash the hook or abort the package removal.
+    err(`getculpa: preuninstall teardown hit an error: ${(e && e.message) || e}`);
+    ok = false;
+  }
+
+  if (!ok) {
+    // "Refuse to leave a running stack silently" — the ceiling npm allows (D-126):
+    // npm removes getculpa regardless, so warn loudly with the manual command.
+    err("");
+    err("getculpa: WARNING — the Culpa stack may still be RUNNING (its stop did not complete cleanly).");
+    err("getculpa: getculpa is about to be removed, so stop the stack yourself with:");
+    err("    docker compose -p culpa down");
+    err("");
+    return { ok: false };
+  }
+
+  // Data + credentials are KEPT on purpose (never deleted by a silent hook).
+  // culpa_pgdata holds the recorded cost data AND the stored licence key + sync
+  // secret (culpa/api/claim_client.ts stores them in the SQL settings table);
+  // culpa_data holds the machine secret. No host-side licence file exists (D-126).
+  log("");
+  log("getculpa: Culpa's containers and network are stopped and the install files are removed.");
+  log("Two data volumes were KEPT on purpose (reinstalling later reuses them):");
+  log("  - culpa_pgdata : your recorded cost data AND your stored licence key + sync secret");
+  log("  - culpa_data   : the machine secret");
+  log("To remove them too (this DELETES your recorded data and stored licence, and cannot be undone):");
+  log("    docker volume rm culpa_pgdata culpa_data");
+  log("");
+  return { ok: true };
+}
+
+module.exports = { runPreuninstall };
+
+// Always exit 0: a failed teardown is surfaced as a loud warning above, not as a
+// nonzero exit (which npm ignores for uninstall while still removing the package).
+if (require.main === module) {
+  runPreuninstall().then(
+    () => process.exit(0),
+    (e) => {
+      console.error(`getculpa: preuninstall hook error (uninstall still proceeds): ${(e && e.message) || e}`);
+      process.exit(0);
+    },
+  );
+}