getculpa 0.0.1 → 1.0.2

package/lib/tty.mjs

@@ -0,0 +1,58 @@
+// T-CF28-5 / T-CF28-7 — terminal helpers: colour, and the yes/no consent
+// prompt. Both are gated on there actually being a human attached.
+//
+// The founder's ruling for the postinstall message is "Culpa is installed and
+// ready." with "ready" in GREEN. Colour is emitted ONLY when the destination
+// is a real terminal and NO_COLOR is unset: `npm i -g` output is routinely
+// piped, redirected to a log, or captured by CI, and a raw ANSI escape there
+// is visible garbage in the one place a human later reads to find out what
+// went wrong. Plain text is the fallback, never a degraded message.
+//
+// isTTY and env are parameters rather than reads of the live process, for the
+// same reason lib/start.mjs:360 and lib/uninstall.mjs:77 inject theirs: a test
+// asserts both branches deliberately instead of depending on how the runner
+// happens to be attached.
+//
+// NO_COLOR follows the https://no-color.org convention: any value, including
+// an empty string, disables colour. Only an ABSENT variable allows it.
+
+// String.fromCharCode(27) rather than a literal escape: this file is edited by
+// tools that have silently converted the six-character sequence into a raw
+// control byte, which is invisible in review and breaks on the next edit.
+const ESC = String.fromCharCode(27);
+const GREEN = `${ESC}[32m`;
+const DEFAULT_FG = `${ESC}[39m`;
+
+export function colourEnabled({ isTTY, env = {} } = {}) {
+  if (!isTTY) return false;
+  return env.NO_COLOR === undefined;
+}
+
+export function green(text, opts = {}) {
+  if (!colourEnabled(opts)) return text;
+  return `${GREEN}${text}${DEFAULT_FG}`;
+}
+
+// T-CF28-7 — explicit consent before Culpa installs anything on the user's
+// machine. Same safety posture as lib/uninstall.mjs:61-69: a non-interactive
+// caller is never prompted and always gets NO, so a scripted or CI run can
+// neither hang on a stdin read nor have an install decided for it by default.
+// The caller supplies the whole question, including the "(y/N)" — the wording
+// of what is about to happen is part of the consent, not decoration.
+export async function askYesNo(question, opts = {}) {
+  const { isInteractive = false, createInterface } = opts;
+  if (!isInteractive) return false;
+  const { createInterface: realCreateInterface } = await import("node:readline");
+  const rl = (createInterface ?? realCreateInterface)({ input: process.stdin, output: process.stdout });
+  const answer = await new Promise((resolve) => {
+    // EOF (Ctrl-D, or a stdin that ends mid-prompt) fires `close` and NEVER
+    // invokes question()'s callback. Without this listener the promise stays
+    // pending and `getculpa` hangs forever at the consent prompt with no
+    // error and no way out. An unanswered question is a NO, exactly as the
+    // non-interactive path above already decides.
+    rl.once("close", () => resolve(""));
+    rl.question(question, resolve);
+  });
+  rl.close();
+  return answer.trim().toLowerCase() === "y";
+}

package/lib/uninstall.d.mts

@@ -0,0 +1,17 @@
+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>;

package/lib/uninstall.mjs

@@ -0,0 +1,99 @@
+// 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) => {
+    rl.question("Also DELETE all recorded cost data? This cannot be undone. (y/N) ", resolve);
+  });
+  rl.close();
+  return answer.trim().toLowerCase() === "y";
+}
+
+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);
+    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.");
+    }
+  }
+
+  console.log("");
+  console.log("To finish removing the Culpa CLI: npm uninstall -g getculpa");
+
+  return { ok };
+}

package/package.json

@@ -1,36 +1,25 @@
 {
   "name": "getculpa",
-  "version": "0.0.1",
-  "description": "Culpa — LLM spend forensics and forecasting, local-first. Placeholder: the CLI is coming soon.",
+  "version": "1.0.2",
+  "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"
   },
-  "main": "index.js",
-  "type": "commonjs",
+  "scripts": {
+    "postinstall": "node scripts/install.js",
+    "prepack": "node scripts/prepack.js"
+  },
   "files": [
-    "bin/culpa.js",
-    "index.js",
-    "README.md"
-  ],
-  "keywords": [
-    "llm",
-    "cost",
-    "spend",
-    "forecasting",
-    "openai",
-    "anthropic",
-    "observability"
+    "bin/",
+    "lib/",
+    "scripts/",
+    "assets/",
+    "README.md",
+    "LICENSE"
   ],
-  "homepage": "https://getculpa.com",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/MyaigiDev/culpa.git"
-  },
-  "license": "UNLICENSED",
   "engines": {
     "node": ">=20"
-  },
-  "publishConfig": {
-    "access": "public"
   }
 }

package/scripts/install.js

@@ -0,0 +1,154 @@
+// AU-011 / CF20-T3 — npm postinstall for `getculpa`.
+//
+// This provisions the FULL Culpa install (Windows-installer parity) and
+// starts NOTHING: no `docker compose up`, no collector start, no browser.
+// "npm installation leaves Culpa fully installed but dormant." `getculpa`
+// (bin/getculpa.js) is what wakes it — that orchestration is CF20-T4, not
+// this file.
+//
+// Order: preflight (fail-closed on an unsupported platform) -> fetch the CLI
+// launcher (fail-closed: the same trust model as before, see lib/fetch.mjs)
+// -> fetch the capture collector (best-effort: absence degrades capture,
+// never aborts the install) -> provision (stage files, best-effort image
+// pull, win32 shortcuts/registry). Non-interactive by construction: nothing
+// here reads stdin or opens a dialog. Terminates on its own — no daemons,
+// no background children.
+
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const pkg = require("../package.json");
+
+// TEST SEAM (CF20-T7, scripts/cf20-npm-gate.mjs ONLY) — never set this for a
+// real install. When CULPA_GATE_SKIP_FETCH=1, the launcher/collector network
+// fetch below is replaced with an inert local stub so the gate can prove the
+// npm install route offline/deterministically (this machine's GitHub Releases
+// may not carry 0.12.0 assets yet, and the gate must never depend on that).
+// The stub is obviously fake (it errors if ever executed) and is written the
+// same way lib/fetch.mjs writes a real launcher (mkdir + write to vendor/),
+// so downstream commands that only check for the launcher's PRESENCE (e.g.
+// `getculpa doctor`) see the same shape a real install leaves behind. The
+// default path — this file's `else` branch below — is byte-for-byte what
+// shipped before this task: it still fetches from GitHub Releases and still
+// verifies the sha256 checksum before writing anything.
+function stageStubLauncher() {
+  const vendorDir = path.join(__dirname, "..", "vendor");
+  fs.mkdirSync(vendorDir, { recursive: true });
+  const exe = process.platform === "win32" ? ".exe" : "";
+  const dest = path.join(vendorDir, `culpa-launcher${exe}`);
+  fs.writeFileSync(
+    dest,
+    "#!/bin/sh\necho 'CULPA GATE STUB - NOT A REAL LAUNCHER (CULPA_GATE_SKIP_FETCH=1)' 1>&2\nexit 1\n",
+  );
+  if (process.platform !== "win32") fs.chmodSync(dest, 0o755);
+}
+
+async function main() {
+  const { checkPlatformSupport } = await import("../lib/preflight.mjs");
+  const { getAppDir } = await import("../lib/paths.mjs");
+  const { fetchLauncher, fetchCollectord } = await import("../lib/fetch.mjs");
+  const { provision } = await import("../lib/provision.mjs");
+
+  const platformCheck = checkPlatformSupport();
+  if (!platformCheck.supported) {
+    console.error(`getculpa: ${platformCheck.message}`);
+    process.exit(1);
+  }
+
+  const appDir = getAppDir();
+
+  let collectorFetched = false;
+  if (process.env.CULPA_GATE_SKIP_FETCH === "1") {
+    console.warn(
+      "getculpa: CULPA_GATE_SKIP_FETCH=1 - TEST SEAM ACTIVE (scripts/cf20-npm-gate.mjs only). " +
+        "Skipping the real launcher/collector fetch and staging an inert stub launcher instead. " +
+        "NEVER set this for a real install.",
+    );
+    stageStubLauncher();
+  } else {
+    // Fatal: without the launcher, `culpa scan`/`connect`/`update` have
+    // nothing to run — same posture as the pre-CF20 bootstrap.
+    await fetchLauncher();
+
+    // Best-effort: absence degrades capture only ("capture OFF, everything
+    // else works" — culpa-collector.ps1's own wording, mirrored here).
+    try {
+      await fetchCollectord();
+      collectorFetched = true;
+    } catch (e) {
+      console.warn(`getculpa: capture collector not fetched (${e.message}) - capture OFF, everything else works.`);
+    }
+  }
+
+  const provisionOpts = { appDir, currentVersion: pkg.version, collectorFetched };
+  // TEST SEAM (CF20-T7, scripts/cf20-npm-gate.mjs ONLY) — never set this for
+  // a real install. On win32, provision() always delegates to the STAGED
+  // install-culpa.ps1 for Desktop/Start Menu shortcuts and Add/Remove
+  // Programs registration (installers/windows/install-culpa.ps1's own T-171
+  // section — this is intentionally OUTSIDE what -DeferStart skips, since it
+  // is real Windows-installer parity, not launch-time work). That script
+  // writes to the HKCU registry key
+  // "Software\Microsoft\Windows\CurrentVersion\Uninstall\{B7A6F2C4-9D31-4E5A-
+  // A0C8-52C1E7D94F60}_is1" — DELIBERATELY the SAME key name the real Inno
+  // installer uses, so the two paths can never both be listed. That dedup
+  // only works when both paths target the SAME real app dir (the script
+  // finds the Inno unins000.exe there and skips re-registering); a gate that
+  // provisions to a SCRATCH app dir has no unins000.exe there and so does
+  // NOT hit the dedup skip - it silently overwrites the real Inno-managed
+  // entry with values pointing at a scratch directory the gate deletes
+  // afterward. CULPA_GATE_SKIP_WIN_DELEGATE=1 uses provision()'s own
+  // already-injectable delegateWindowsInstaller parameter (see
+  // lib/provision.mjs) to skip that call entirely - zero writes to the real
+  // Desktop, Start Menu, or registry. The default path (this variable unset)
+  // is byte-for-byte unchanged: provision() still calls the real delegate.
+  if (process.env.CULPA_GATE_SKIP_WIN_DELEGATE === "1") {
+    console.warn(
+      "getculpa: CULPA_GATE_SKIP_WIN_DELEGATE=1 - TEST SEAM ACTIVE (scripts/cf20-npm-gate.mjs only). " +
+        "Skipping the real install-culpa.ps1 delegate (shortcuts + the shared Add/Remove Programs " +
+        "registry key) so this run cannot collide with a real Windows install's registration. " +
+        "NEVER set this for a real install.",
+    );
+    provisionOpts.delegateWindowsInstaller = () => true;
+  }
+  const { classification, previousVersion, dockerState, imagesStaged, collectorStaged } =
+    await provision(provisionOpts);
+
+  // T-CF28-4b: stage the CLI payload the launcher actually runs. Without this
+  // a fresh install leaves state.json at `current: null` and the first
+  // `getculpa` dead-ends — the Mac tester's exact experience. Best-effort by
+  // construction: any failure leaves the payload deferred and the summary
+  // below names `getculpa update`, which is where we already were.
+  const { stageInitialPayload, vendoredLauncherPath } = await import("../lib/bootstrap.mjs");
+  const { staged: payloadStaged } = stageInitialPayload({
+    launcherPath: vendoredLauncherPath(path.join(__dirname, "..")),
+    env: process.env,
+  });
+
+  // CF20-T6: the completion line names what actually happened — an upgrade
+  // is STAGED only; the new version applies at the next `getculpa`, not here.
+  // T-CF28-5/7: those words now live in lib/install-summary.mjs so they are
+  // testable, and they no longer report success without saying whether Docker
+  // — which Culpa cannot run without — is actually present.
+  const { buildInstallSummary } = await import("../lib/install-summary.mjs");
+  const summary = buildInstallSummary({
+    classification,
+    version: pkg.version,
+    previousVersion,
+    appDir,
+    dockerState,
+    imagesStaged,
+    collectorStaged,
+    payloadStaged,
+    platform: process.platform,
+    isTTY: Boolean(process.stdout.isTTY),
+    env: process.env,
+  });
+  for (const line of summary) console.log(line);
+}
+
+main().catch((e) => {
+  console.error(`getculpa: install failed — ${e.message}`);
+  console.error("getculpa: nothing was installed. The Culpa CLI is unavailable until this succeeds.");
+  process.exit(1);
+});

package/scripts/prepack.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+// CF20-T3 — prepack: copy the canonical shared install assets into assets/
+// so the packed tarball is self-contained. assets/ is GENERATED — never
+// edit it directly, never fork these files; this script is its only writer.
+// lib/assets.mjs falls back to these same repo-relative sources when
+// assets/ is absent (dev/test runs that never ran `npm pack`).
+
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+const pkgRoot = path.join(__dirname, "..");
+const repoRoot = path.join(pkgRoot, "..", "..");
+const assetsDir = path.join(pkgRoot, "assets");
+
+const SOURCES = [
+  ["installers", "culpa-compose.yml"],
+  ["installers", "windows", "install-culpa.ps1"],
+  ["installers", "windows", "launch-culpa.ps1"],
+  ["installers", "windows", "uninstall-culpa.ps1"],
+  ["installers", "windows", "culpa-collector.ps1"],
+  ["collector", "node", "register.mjs"],
+];
+
+// CF20-R: clear assets/ before restaging — otherwise a canonical source file
+// that gets removed or renamed from SOURCES leaves a STALE copy behind
+// forever, and that stale file still ships in the tarball (assets/ is never
+// hand-edited, so nothing else would ever remove it).
+fs.rmSync(assetsDir, { recursive: true, force: true });
+fs.mkdirSync(assetsDir, { recursive: true });
+for (const parts of SOURCES) {
+  const src = path.join(repoRoot, ...parts);
+  if (!fs.existsSync(src)) {
+    console.error(`prepack: missing canonical source ${src}`);
+    process.exit(1);
+  }
+  const dest = path.join(assetsDir, path.basename(src));
+  fs.copyFileSync(src, dest);
+  console.log(`prepack: staged ${path.basename(src)}`);
+}

package/index.js

@@ -1,3 +0,0 @@
-// Placeholder entry point, so `require("getculpa")` resolves instead of
-// throwing MODULE_NOT_FOUND. The real API is not published yet.
-module.exports = { comingSoon: true };