getculpa 1.0.2 → 1.0.4

package/README.md

@@ -1,8 +1,7 @@
 # getculpa
 
-`packaging/npm-getculpa` supersedes the `installers/npm@0.0.1` name-claim
-placeholder (that package's contents are frozen; this one is the real
-package published as `getculpa` on npm).
+**Culpa — LLM spend forensics and forecasting, local-first.** See where the
+money went, across models, features and users, on your own machine.
 
 **`npm i -g getculpa` provisions the full Culpa install — the same files,
 shortcuts, and registration the Windows installer lays down — and starts

package/assets/culpa-compose.yml

@@ -5,7 +5,7 @@
 # name is used when present, which is how these pins were verified before
 # publication.
 #
-# ── RELEASE STATE: v1.0.2 PUBLISHED AND SIGNED (2026-08-17) ─────────
+# ── RELEASE STATE: v1.0.4 PUBLISHED AND SIGNED (2026-08-20) ─────────
 # The line above is REWRITTEN BY installers/publish.sh at real-publish time —
 # this file has shipped a hand-edited, wrong publication claim twice, so the
 # claim is now mechanical, never prose. While it reads NOT PUBLISHED, the pins
@@ -26,7 +26,7 @@
 #   cosign verify \
 #     --certificate-identity 'info@myaigi.ai' \
 #     --certificate-oidc-issuer 'https://github.com/login/oauth' \
-#     ghcr.io/myaigidev/culpa-server:v1.0.2
+#     ghcr.io/myaigidev/culpa-server:v1.0.3
 # Repeat for culpa-dashboard. Both must report VERIFIED.
 #
 # If a pull fails with an authentication or "denied" error rather than a
@@ -55,7 +55,7 @@ services:
     restart: unless-stopped
 
   server:
-    image: ghcr.io/myaigidev/culpa-server:v1.0.2
+    image: ghcr.io/myaigidev/culpa-server:v1.0.3
     container_name: culpa-server
     environment:
       DATABASE_URL: postgres://culpa:culpa@db:5432/culpa
@@ -127,7 +127,7 @@ services:
     # black-surface palette — no server, migration or API change, so the server
     # above deliberately stays at v0.11.0 rather than being re-tagged for a
     # release it has no diff in (D-072: never rebuild a tag that already exists).
-    image: ghcr.io/myaigidev/culpa-dashboard:v1.0.2
+    image: ghcr.io/myaigidev/culpa-dashboard:v1.0.4
     container_name: culpa-dashboard
     environment:
       CULPA_API_BASE: http://server:4545

package/assets/culpa-relay-fly.toml

@@ -0,0 +1,70 @@
+# Culpa Relay — Fly.io deploy (T-C7, D-048; Rust binary since T-157/D8-11:
+# the image carries ONE compiled binary, nothing readable).
+# The relay is PUBLIC BY DESIGN: serverless and multi-cloud backends push to a
+# URL + token, so this app has [http_service] with force_https — the exact
+# OPPOSITE of the private-only companion (deploy/companion/fly.toml). Security
+# is the required bearer tokens: the relay refuses to boot without BOTH (the
+# write token appends, the read token reads — never crossed), and every
+# endpoint except /health demands one.
+#
+# The relay is DB-less: its only state is the object mailbox on the volume
+# below. Your LOCAL Culpa pulls that feed (live tail + catch-up) and is
+# the only place pricing/normalization ever happen.
+#
+# Deploy (from the REPO ROOT; the build context is native/relay):
+#   flyctl launch --config deploy/relay/fly.toml --no-deploy
+#   flyctl volumes create culpa_relay_data --app culpa-relay --region <same-as-backend>
+#   flyctl secrets set --app culpa-relay CULPA_INGEST_TOKEN=$(openssl rand -hex 32)
+#   flyctl secrets set --app culpa-relay CULPA_READ_TOKEN=$(openssl rand -hex 32)
+#   flyctl deploy --config deploy/relay/fly.toml
+#
+# Then wire the two sides (see docs/relay-deploy-runbook.md):
+#   backend:      CULPA_BASE_URL=https://culpa-relay.fly.dev  CULPA_INGEST_TOKEN=<the write token>
+#   local Culpa:  relay config url=https://culpa-relay.fly.dev, token=<the read token>
+
+app = "culpa-relay"            # rename per install
+primary_region = "jnb"         # put this in the SAME region as your backend
+
+[build]
+  # resolved relative to this file; run flyctl from the repo root so the
+  # build context carries native/relay/ (same footgun as the license server)
+  dockerfile = "../../native/relay/Dockerfile"
+
+[env]
+  RELAY_PORT = "4747"
+  RELAY_DATA_DIR = "/data"
+  # CULPA_INGEST_TOKEN + CULPA_READ_TOKEN arrive via `flyctl secrets set` —
+  # NEVER in this file. The relay exits at boot if either is missing or they
+  # are equal (it never runs open or role-collapsed).
+
+[http_service]
+  internal_port = 4747
+  force_https = true
+  # ALWAYS-ON is the point: the relay accumulates the log while your laptop is
+  # off. Never let the platform stop the machine.
+  auto_stop_machines = "off"
+  auto_start_machines = true
+  min_machines_running = 1
+
+[[http_service.checks]]
+  interval = "30s"
+  timeout = "5s"
+  grace_period = "10s"
+  method = "GET"
+  path = "/health"
+
+[mounts]
+  # the object mailbox lives here — losing this volume loses any entries your
+  # local Culpa has not pulled yet
+  #
+  # ⚠ SINGLE MACHINE ONLY (CodeRabbit full review): Fly volumes are one-per-
+  # machine and never replicated, so `fly scale count 2` gives each machine its
+  # OWN /data and silently FORKS the mailbox — the puller would only see
+  # whichever fork the edge routes it to. fly.toml cannot cap machine count;
+  # never scale this app past 1 (check with `fly scale show -a <app>`), or move
+  # the mailbox to shared storage first.
+  source = "culpa_relay_data"
+  destination = "/data"
+
+[[vm]]
+  size = "shared-cpu-1x"       # the relay only appends and serves a file

package/bin/getculpa.js

@@ -121,21 +121,49 @@ async function runUninstall() {
 
 async function main(argv) {
   const [cmd] = argv;
-  if (cmd === undefined || cmd === "start") return runStart();
-  if (cmd === "-h" || cmd === "--help" || cmd === "help") {
-    console.log(HELP);
-    return process.exit(0);
-  }
   if (cmd === "-v" || cmd === "--version") {
     printVersion();
     return process.exit(0);
   }
+  // V102 T-V102-04 (M8, D-113): `getculpa uninstall --help` once EXECUTED the
+  // uninstall — the help flag was only recognised as argv[0]. All help and
+  // uninstall-consent decisions now happen here, BEFORE anything is imported
+  // or spawned. Passthrough verbs fall through untouched (the launcher owns
+  // their help).
+  const { decideDispatch, verbHelp } = await import("../lib/dispatch.mjs");
+  const decision = decideDispatch(argv, {
+    isTTY: process.stdin.isTTY === true && process.stdout.isTTY === true,
+  });
+  if (decision.kind === "help") {
+    console.log(decision.verb === null ? HELP : verbHelp(decision.verb));
+    return process.exit(0);
+  }
+  if (decision.kind === "refuse-uninstall") {
+    console.error(
+      "getculpa: uninstall removes Culpa's containers and network. Run it from a terminal to confirm interactively, or pass --yes to consent from a script. Nothing was changed.",
+    );
+    return process.exit(1);
+  }
+  if (decision.kind === "confirm-uninstall") {
+    const { askYesNo } = await import("../lib/tty.mjs");
+    const consented = await askYesNo(
+      "This stops and removes Culpa's containers and network (recorded cost data is kept unless you separately confirm deleting it). Continue? (y/N) ",
+      { isInteractive: true },
+    );
+    if (!consented) {
+      console.log("getculpa: uninstall cancelled. Nothing was changed.");
+      return process.exit(0);
+    }
+    return runUninstall();
+  }
+  if (decision.kind === "run-uninstall") return runUninstall();
+  if (cmd === undefined || cmd === "start") return runStart();
   if (cmd === "stop") return runStop();
   if (cmd === "restart") return runRestart();
   if (cmd === "status") return runStatus();
   if (cmd === "doctor") return runDoctor();
   if (cmd === "repair") return runRepair();
-  if (cmd === "uninstall") return runUninstall();
+  // `uninstall` never reaches here — every argv shape is decided above.
   // scan / connect / update / config / anything unrecognized: the launcher
   // owns USAGE and exit-code semantics for its own surface, same as culpa.js.
   return runLauncherPassthrough(argv);

package/lib/assets.mjs

@@ -1,36 +1,39 @@
-// CF20-T3 — resolves the canonical shared install assets. Packed installs
-// read from assets/ (staged by scripts/prepack.js at `npm pack`/publish
-// time). Dev/test runs (no pack step) fall back to the repo-relative
-// canonical paths, so nothing here is ever forked — there is exactly one
-// source of truth for each file, and assets/ is a generated copy of it.
-
-import { existsSync } from "node:fs";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const packageRoot = path.join(__dirname, "..");
-// packaging/npm-getculpa/lib -> packaging/npm-getculpa -> packaging -> repo root
-const repoRoot = path.join(packageRoot, "..", "..");
-
-// name -> repo-relative canonical source (dev/test fallback only)
-export const ASSET_MANIFEST = {
-  "culpa-compose.yml": path.join(repoRoot, "installers", "culpa-compose.yml"),
-  "install-culpa.ps1": path.join(repoRoot, "installers", "windows", "install-culpa.ps1"),
-  "launch-culpa.ps1": path.join(repoRoot, "installers", "windows", "launch-culpa.ps1"),
-  "uninstall-culpa.ps1": path.join(repoRoot, "installers", "windows", "uninstall-culpa.ps1"),
-  "culpa-collector.ps1": path.join(repoRoot, "installers", "windows", "culpa-collector.ps1"),
-  "register.mjs": path.join(repoRoot, "collector", "node", "register.mjs"),
-};
-
-export function resolveAssetPath(name) {
-  const fallback = ASSET_MANIFEST[name];
-  if (!fallback) throw new Error(`unknown shared install asset: ${name}`);
-
-  const packed = path.join(packageRoot, "assets", name);
-  if (existsSync(packed)) return packed;
-  if (existsSync(fallback)) return fallback;
-  throw new Error(
-    `asset '${name}' not found in packed assets/ (${packed}) or the repo-relative fallback (${fallback})`,
-  );
-}
+// CF20-T3 — resolves the canonical shared install assets. Packed installs
+// read from assets/ (staged by scripts/prepack.js at `npm pack`/publish
+// time). Dev/test runs (no pack step) fall back to the repo-relative
+// canonical paths, so nothing here is ever forked — there is exactly one
+// source of truth for each file, and assets/ is a generated copy of it.
+
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const packageRoot = path.join(__dirname, "..");
+// packaging/npm-getculpa/lib -> packaging/npm-getculpa -> packaging -> repo root
+const repoRoot = path.join(packageRoot, "..", "..");
+
+// name -> repo-relative canonical source (dev/test fallback only)
+export const ASSET_MANIFEST = {
+  "culpa-compose.yml": path.join(repoRoot, "installers", "culpa-compose.yml"),
+  "install-culpa.ps1": path.join(repoRoot, "installers", "windows", "install-culpa.ps1"),
+  "launch-culpa.ps1": path.join(repoRoot, "installers", "windows", "launch-culpa.ps1"),
+  "uninstall-culpa.ps1": path.join(repoRoot, "installers", "windows", "uninstall-culpa.ps1"),
+  "culpa-collector.ps1": path.join(repoRoot, "installers", "windows", "culpa-collector.ps1"),
+  "register.mjs": path.join(repoRoot, "collector", "node", "register.mjs"),
+  // ISS-V103-9: staged under an explicit name; the canonical basename
+  // (fly.toml) would read as the customer's own app config.
+  "culpa-relay-fly.toml": path.join(repoRoot, "deploy", "relay", "fly.toml"),
+};
+
+export function resolveAssetPath(name) {
+  const fallback = ASSET_MANIFEST[name];
+  if (!fallback) throw new Error(`unknown shared install asset: ${name}`);
+
+  const packed = path.join(packageRoot, "assets", name);
+  if (existsSync(packed)) return packed;
+  if (existsSync(fallback)) return fallback;
+  throw new Error(
+    `asset '${name}' not found in packed assets/ (${packed}) or the repo-relative fallback (${fallback})`,
+  );
+}

package/lib/bootstrap.d.mts

@@ -23,3 +23,7 @@ export interface StageInitialPayloadResult {
 }
 
 export function stageInitialPayload(opts: StageInitialPayloadOptions): StageInitialPayloadResult;
+
+export type PayloadState = "installed" | "staged" | "missing";
+
+export function readPayloadState(opts?: { env?: Record<string, string | undefined> }): PayloadState;

package/lib/bootstrap.mjs

@@ -26,8 +26,9 @@
 // command. The install never claims more than it did.
 
 import { spawnSync as realSpawnSync } from "node:child_process";
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
+import { getAppDir } from "./paths.mjs";
 
 // A real payload is tens of MB over a network Culpa does not control. Long
 // enough not to abort a slow-but-working download; short enough that a hung
@@ -44,6 +45,29 @@ export function vendoredLauncherPath(packageRoot, platform = process.platform) {
   return existsSync(candidate) ? candidate : null;
 }
 
+/** V102 T-V102-15 (M3, D-113): what the launcher's updates/state.json
+ *  actually says — EVIDENCE for the install summary, never the updater's
+ *  exit code (which claimed "Culpa CLI: installed" on a Mac whose state read
+ *  current: null while doctor FAILed the same install).
+ *  "installed": current is set. "staged": pending only — activates at the
+ *  next `getculpa`. "missing": neither, no file, or unreadable.
+ *  NB (review-3): getAppDir honours CULPA_APP_DIR but not CULPA_HOME — the
+ *  known-open T-CF28-3c asymmetry (see paths.mjs:17-27 and open-loops
+ *  §T-CF28-3c). A CULPA_HOME-only relocation therefore reads the default
+ *  location and reports "missing" — underselling, never a false claim. */
+export function readPayloadState(opts = {}) {
+  const { env = process.env } = opts;
+  try {
+    const raw = readFileSync(path.join(getAppDir({ env }), "updates", "state.json"), "utf8");
+    const state = JSON.parse(raw);
+    if (typeof state.current === "string" && state.current.length > 0) return "installed";
+    if (typeof state.pending === "string" && state.pending.length > 0) return "staged";
+    return "missing";
+  } catch {
+    return "missing"; // absent or corrupt: no evidence, no claim
+  }
+}
+
 export function stageInitialPayload(opts) {
   const { launcherPath, spawnSync = realSpawnSync, log = console.log, env = process.env } = opts;
 

package/lib/dispatch.d.mts

@@ -0,0 +1,12 @@
+export type DispatchDecision =
+  | { kind: "help"; verb: string | null }
+  | { kind: "refuse-uninstall" }
+  | { kind: "confirm-uninstall" }
+  | { kind: "run-uninstall" }
+  | { kind: "dispatch" };
+
+export const LOCAL_VERBS: string[];
+
+export function verbHelp(verb: string): string;
+
+export function decideDispatch(argv: string[], opts?: { isTTY?: boolean }): DispatchDecision;

package/lib/dispatch.mjs

@@ -0,0 +1,59 @@
+// V102 T-V102-04 (M8/P0-2, D-113) — dispatch decisions for bin/getculpa.js.
+//
+// Executed on real hardware: `getculpa uninstall --help` stopped and removed
+// all three containers and the network, because the router recognised a help
+// flag only as argv[0] and dispatched on argv[0] without reading argv[1].
+// `stop`, `restart` and `repair` shared the shape. The rule now: for every
+// verb THIS bin routes locally, a help flag anywhere in argv decides HELP
+// before anything is imported or spawned. Passthrough verbs (scan, connect,
+// update, config, …) keep their argv untouched — the vendored launcher owns
+// their help and exit-code semantics.
+//
+// Pure decisions, no side effects: the bin acts on the returned kind, and the
+// facts in tests/npm-cli-dispatch.test.ts assert the decisions directly.
+
+const HELP_FLAGS = new Set(["-h", "--help", "help"]);
+
+/** Every verb bin/getculpa.js routes locally (everything else passes through). */
+export const LOCAL_VERBS = ["start", "stop", "restart", "status", "doctor", "repair", "uninstall"];
+const LOCAL = new Set(LOCAL_VERBS);
+
+const VERB_HELP = {
+  start: "Start (or resume) the Culpa stack. Data is kept.",
+  stop: "Stop the running stack. Containers stop, nothing is removed, all data is kept. Start again with `getculpa`.",
+  restart: "Stop, then start the stack. No data is touched.",
+  status: "Show install/docker/stack/license status. Read-only.",
+  doctor: "Diagnose this install. Read-only.",
+  repair: "Re-stage missing or corrupt install files. No data touched.",
+  uninstall:
+    "Stop and REMOVE Culpa's containers and network. Asks for confirmation first; pass --yes to consent from a script (a non-interactive run without --yes refuses). Recorded cost data is kept unless you separately confirm deleting it.",
+};
+
+/** One verb's help block, prefixed with its usage line. */
+export function verbHelp(verb) {
+  const text = VERB_HELP[verb] ?? "No help recorded for this verb.";
+  return `Usage: getculpa ${verb}\n\n  ${text}\n`;
+}
+
+/**
+ * Decide what argv means BEFORE any dispatch. Returns one of:
+ *   { kind: "help", verb: string | null }  print help (general when verb null)
+ *   { kind: "refuse-uninstall" }           non-interactive, no --yes: refuse
+ *   { kind: "confirm-uninstall" }          interactive: ask, then uninstall
+ *   { kind: "run-uninstall" }              consent given via --yes/-y
+ *   { kind: "dispatch" }                   fall through to the existing router
+ */
+export function decideDispatch(argv, { isTTY = false } = {}) {
+  const [cmd] = argv;
+  if (cmd === undefined) return { kind: "dispatch" };
+  if (HELP_FLAGS.has(cmd)) return { kind: "help", verb: null };
+  if (LOCAL.has(cmd) && argv.slice(1).some((a) => HELP_FLAGS.has(a))) {
+    return { kind: "help", verb: cmd };
+  }
+  if (cmd === "uninstall") {
+    if (argv.includes("--yes") || argv.includes("-y")) return { kind: "run-uninstall" };
+    if (!isTTY) return { kind: "refuse-uninstall" };
+    return { kind: "confirm-uninstall" };
+  }
+  return { kind: "dispatch" };
+}

package/lib/doctor.mjs

@@ -244,9 +244,24 @@ async function checkHealth(fetchFn, running) {
 }
 
 function scanLicenseKeyPresence(env, appDir) {
-  if (env.CULPA_LICENSE_KEY) return true;
+  // CodeRabbit PR#19 [6]: "   " is truthy — trim before believing the env
+  if ((env.CULPA_LICENSE_KEY ?? "").trim() !== "") return true;
   const compose = readTextSafe(path.join(appDir, "docker-compose.yml"));
-  return /CULPA_LICENSE_KEY/.test(compose);
+  // V102 T-V102-15 (M6/W3, D-113): the old bare /CULPA_LICENSE_KEY/ regex
+  // matched a COMMENT line in the shipped compose, so doctor reported
+  // "[OK] present (redacted)" with no key set — on real hardware, both
+  // platforms, while `status` said "License: unknown" beside it. Only an
+  // uncommented env ENTRY carrying a non-empty value counts.
+  return compose.split(/\r?\n/).some((line) => {
+    const t = line.trim();
+    if (t.startsWith("#")) return false;
+    const m = /^-?\s*["']?CULPA_LICENSE_KEY["']?\s*[:=]\s*(.+)$/.exec(t);
+    if (m === null) return false;
+    // PR#19 [6]: "KEY: # configured elsewhere" is YAML for an EMPTY value
+    // plus a trailing comment — never a configured key
+    const value = m[1].trim().replace(/^["']|["']$/g, "").trim();
+    return value.length > 0 && !value.startsWith("#");
+  });
 }
 
 // Extracts ONLY configured/state/plan — even if the (possibly stubbed, in

package/lib/install-summary.d.mts

@@ -9,7 +9,7 @@ export interface InstallSummaryOptions {
   dockerState: DockerState;
   imagesStaged?: boolean;
   collectorStaged?: boolean;
-  payloadStaged?: boolean;
+  payloadState?: "installed" | "staged" | "missing";
   platform?: string;
   isTTY?: boolean;
   env?: Record<string, string | undefined>;

package/lib/install-summary.mjs

@@ -46,13 +46,23 @@ function headline(classification, version, previousVersion, dockerReady, colour)
   }
 }
 
-function inventory(appDir, imagesStaged, collectorStaged, payloadStaged) {
+// 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: ${payloadStaged ? "installed" : "deferred - run `getculpa update` to finish"}`,
+    `  Culpa CLI: ${PAYLOAD_ROW[payloadState] ?? PAYLOAD_ROW.missing}`,
     `  Images:    ${imagesStaged ? "staged" : "deferred to first run"}`,
     `  Capture:   ${collectorStaged ? "collector installed" : "off (collector not installed)"}`,
   ];
@@ -109,27 +119,29 @@ export function buildInstallSummary(opts) {
     dockerState,
     imagesStaged = false,
     collectorStaged = false,
-    // T-CF28-4b. 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 always passes the real value.
-    payloadStaged = 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
+  // "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.
-  const ready = dockerReady && payloadStaged;
+  // "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, payloadStaged));
+    lines.push(...inventory(appDir, imagesStaged, collectorStaged, payloadState));
   }
 
   if (!dockerReady) {