getculpa 0.0.1 → 1.0.1

package/lib/stop.d.mts

@@ -0,0 +1,15 @@
+import type { SpawnSyncLike } from "./docker.d.mts";
+
+export interface StopOptions {
+  appDir?: string;
+  platform?: string;
+  spawnSync?: SpawnSyncLike;
+  log?: (msg: string) => void;
+}
+
+export interface StopResult {
+  ok: boolean;
+  stopped: boolean;
+}
+
+export function stop(opts?: StopOptions): Promise<StopResult>;

package/lib/stop.mjs

@@ -0,0 +1,46 @@
+// CF20-T4 — `getculpa stop`.
+//
+// DECISION (see task report): uses `docker compose stop`, NOT `down`.
+// uninstall-culpa.ps1:60/65 uses `down` because uninstall is a full teardown
+// (containers + the compose network removed; named volumes are kept — no
+// `-v` flag there either). `stop` is a distinct, resumable verb: a founder
+// pausing Culpa should get a fast `getculpa` back — Compose's own paired
+// verb for `stop` is `start`/`up`, not a recreate — without losing the
+// container-level state `down` discards. The collector is a host process
+// (win32 only, D-082 — it binds 127.0.0.1 outside Docker) so it is always
+// stopped explicitly first, exactly as uninstall-culpa.ps1:43-44 does.
+
+import { spawnSync as realSpawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { getAppDir } from "./paths.mjs";
+
+export async function stop(opts = {}) {
+  const appDir = opts.appDir ?? getAppDir();
+  const platform = opts.platform ?? process.platform;
+  const spawnSync = opts.spawnSync ?? realSpawnSync;
+  const log = opts.log ?? console.log;
+
+  if (platform === "win32") {
+    const collectorCtl = path.join(appDir, "culpa-collector.ps1");
+    if (existsSync(collectorCtl)) {
+      spawnSync("powershell.exe", ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", collectorCtl, "-Stop"], {
+        stdio: "inherit",
+      });
+    }
+  }
+
+  const compose = path.join(appDir, "docker-compose.yml");
+  if (!existsSync(compose)) {
+    log("Culpa is not installed here - nothing to stop.");
+    return { ok: true, stopped: false };
+  }
+
+  const result = spawnSync("docker", ["compose", "-f", compose, "-p", "culpa", "stop"], { stdio: "inherit" });
+  if (result.status !== 0) {
+    log("getculpa: Culpa did not stop cleanly - see the output above.");
+    return { ok: false, stopped: false };
+  }
+  log("Culpa stopped.");
+  return { ok: true, stopped: true };
+}

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

package/scripts/install.js

@@ -0,0 +1,135 @@
+// 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 } = await provision(provisionOpts);
+
+  // CF20-T6: the completion line names what actually happened — an upgrade
+  // is STAGED only; the new version applies at the next `getculpa`, not here.
+  if (classification === "upgrade") {
+    console.log(`Culpa updated: ${previousVersion} -> ${pkg.version} (staged; applies at next \`getculpa\`).`);
+  } else if (classification === "downgrade-package") {
+    console.log(`Culpa ${previousVersion} is already installed; this package (${pkg.version}) is older and was not applied.`);
+  } else if (classification === "same-version" || classification === "repair") {
+    console.log("Culpa installation repaired.");
+  } else {
+    console.log("Culpa installed successfully.");
+  }
+  console.log("Run:");
+  console.log("  getculpa");
+}
+
+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 };