getculpa 1.0.2 → 1.0.3

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.3 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.3
     container_name: culpa-dashboard
     environment:
       CULPA_API_BASE: http://server:4545

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/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) {

package/lib/start.mjs

@@ -415,10 +415,15 @@ async function runPosixStateMachine({ appDir, liveCompose, platform, spawnSync,
     };
   }
 
-  // No collectord build/staging exists for macOS/Linux yet (task scope) —
-  // degrade honestly rather than fail the whole launch over capture.
+  // V102 T-V102-14 (M4, D-113): the old line here said "no collector build
+  // ships for macOS/Linux yet" — verified FALSE on real hardware (the arm64
+  // collectord ships, was staged executable, install-state recorded
+  // collectorStaged: true). What IS true: the collector is not auto-started
+  // on this platform yet, while the server-side coding-tool log sweep works
+  // (proven live on the Mac: calls landed unattended, ~45 min cadence). Say
+  // exactly that — neither direction of the old overclaim.
   stagesRun.push(STAGES.START_CULPA);
-  log("getculpa: capture is OFF on this platform for now (no collector build ships for macOS/Linux yet) - everything else works normally.");
+  log("getculpa: your local coding-tool usage is captured by the built-in log sweep. The production traffic collector is not started automatically on this platform yet - everything else works normally.");
 
   stagesRun.push(STAGES.OPEN_UI);
   if (pinnedVersion) writeFileSync(path.join(appDir, "last-boot-version.txt"), `${pinnedVersion}\n`);

package/lib/uninstall.mjs

@@ -62,12 +62,36 @@ 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;
@@ -82,13 +106,28 @@ export async function uninstall(opts = {}) {
     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.");
+    // 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 {
-      console.log("Data kept (volume culpa_pgdata). Reinstalling later will find it again.");
+      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);
     }
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "getculpa",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "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": {

package/scripts/install.js

@@ -119,11 +119,15 @@ async function main() {
   // `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({
+  const { readPayloadState, stageInitialPayload, vendoredLauncherPath } = await import("../lib/bootstrap.mjs");
+  stageInitialPayload({
     launcherPath: vendoredLauncherPath(path.join(__dirname, "..")),
     env: process.env,
   });
+  // V102 T-V102-15 (M3): the summary reports what updates/state.json actually
+  // says, never the updater's exit code — "installed" was claimed on a Mac
+  // whose state read current: null while doctor FAILed the same install.
+  const payloadState = readPayloadState({ 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.
@@ -139,7 +143,7 @@ async function main() {
     dockerState,
     imagesStaged,
     collectorStaged,
-    payloadStaged,
+    payloadState,
     platform: process.platform,
     isTTY: Boolean(process.stdout.isTTY),
     env: process.env,