getculpa 1.0.9 → 1.1.0

package/bin/culpa.js

@@ -1,22 +1,22 @@
-#!/usr/bin/env node
-// Thin shim: exec the vendored culpa launcher (installed by
-// scripts/install.js at postinstall), forwarding argv/stdio/exit code. The
-// launcher owns everything from here — versions/, updates, the payload.
-
-"use strict";
-
-const { spawnSync } = require("node:child_process");
-const fs = require("node:fs");
-const path = require("node:path");
-
-const exe = process.platform === "win32" ? ".exe" : "";
-const launcher = path.join(__dirname, "..", "vendor", `culpa-launcher${exe}`);
-
-if (!fs.existsSync(launcher)) {
-  console.error("culpa: the launcher is not installed (postinstall failed or was skipped).");
-  console.error("culpa: run `npm rebuild getculpa` (or reinstall) to fetch it.");
-  process.exit(1);
-}
-
-const result = spawnSync(launcher, process.argv.slice(2), { stdio: "inherit" });
-process.exit(result.status === null ? 1 : result.status);
+#!/usr/bin/env node
+// Thin shim: exec the vendored culpa launcher (installed by
+// scripts/install.js at postinstall), forwarding argv/stdio/exit code. The
+// launcher owns everything from here — versions/, updates, the payload.
+
+"use strict";
+
+const { spawnSync } = require("node:child_process");
+const fs = require("node:fs");
+const path = require("node:path");
+
+const exe = process.platform === "win32" ? ".exe" : "";
+const launcher = path.join(__dirname, "..", "vendor", `culpa-launcher${exe}`);
+
+if (!fs.existsSync(launcher)) {
+  console.error("culpa: the launcher is not installed (postinstall failed or was skipped).");
+  console.error("culpa: run `npm rebuild getculpa` (or reinstall) to fetch it.");
+  process.exit(1);
+}
+
+const result = spawnSync(launcher, process.argv.slice(2), { stdio: "inherit" });
+process.exit(result.status === null ? 1 : result.status);

package/bin/getculpa.js

@@ -1,175 +1,186 @@
-#!/usr/bin/env node
-// CF20-T3 — `getculpa` command router.
-//
-//   getculpa | getculpa start   -> wake the stack (CF20-T4)
-//   getculpa doctor / repair    -> diagnostics + self-heal (CF20-T5)
-//   getculpa uninstall          -> lib/uninstall.mjs
-//   getculpa --help / --version -> local, no launcher needed
-//   anything else (scan, connect, update, config, ...) -> passthrough to the
-//     vendored launcher, exactly like bin/culpa.js does today.
-
-"use strict";
-
-const { spawnSync } = require("node:child_process");
-const fs = require("node:fs");
-const path = require("node:path");
-
-const HELP = `getculpa - Culpa, LLM spend forensics and forecasting, local-first
-
-Usage:
-  getculpa                 Start (or resume) the Culpa stack
-  getculpa start           Same as above
-  getculpa stop            Stop the running stack (data is kept)
-  getculpa restart         Stop, then start
-  getculpa status          Show install/docker/stack/license status
-  getculpa doctor          Diagnose this install
-  getculpa repair          Re-stage missing/corrupt install files (no data touched)
-  getculpa uninstall       Remove Culpa (data is kept unless you confirm)
-  getculpa scan            Zero-install local scan (no Docker, no network)
-  getculpa connect         Print the topology-appropriate capture recipe
-  getculpa update          Manage CLI launcher updates
-  getculpa --help          Show this help
-  getculpa --version       Show the getculpa package version
-`;
-
-function printVersion() {
-  const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, "..", "package.json"), "utf8"));
-  console.log(pkg.version);
-}
-
-function runLauncherPassthrough(args) {
-  const exe = process.platform === "win32" ? ".exe" : "";
-  const launcher = path.join(__dirname, "..", "vendor", `culpa-launcher${exe}`);
-  if (!fs.existsSync(launcher)) {
-    console.error("getculpa: the launcher is not installed (postinstall failed or was skipped).");
-    console.error("getculpa: run `npm rebuild getculpa` (or reinstall) to fetch it.");
-    process.exit(1);
-  }
-  const result = spawnSync(launcher, args, { stdio: "inherit" });
-  process.exit(result.status === null ? 1 : result.status);
-}
-
-function currentVersion() {
-  return JSON.parse(fs.readFileSync(path.join(__dirname, "..", "package.json"), "utf8")).version;
-}
-
-function printResult(result) {
-  if (result.ok) return;
-  console.error("");
-  console.error(`Culpa couldn't start.`);
-  console.error(result.message ?? "(no further detail)");
-  if (result.recovery) console.error(result.recovery);
-}
-
-async function runStart() {
-  const { start } = await import("../lib/start.mjs");
-  const { getAppDir } = await import("../lib/paths.mjs");
-  const result = await start({ appDir: getAppDir(), currentVersion: currentVersion() });
-  if (!result.ok) {
-    printResult(result);
-    process.exit(1);
-  }
-  process.exit(0);
-}
-
-async function runStop() {
-  const { stop } = await import("../lib/stop.mjs");
-  const result = await stop();
-  process.exit(result.ok ? 0 : 1);
-}
-
-async function runRestart() {
-  const { stop } = await import("../lib/stop.mjs");
-  const { start } = await import("../lib/start.mjs");
-  const { getAppDir } = await import("../lib/paths.mjs");
-  await stop();
-  const result = await start({ appDir: getAppDir(), currentVersion: currentVersion() });
-  if (!result.ok) {
-    printResult(result);
-    process.exit(1);
-  }
-  process.exit(0);
-}
-
-async function runStatus() {
-  const { status, formatStatus } = await import("../lib/status.mjs");
-  const result = await status();
-  console.log(formatStatus(result));
-  process.exit(0);
-}
-
-async function runDoctor() {
-  const { doctor, formatDoctorReport } = await import("../lib/doctor.mjs");
-  const { getAppDir } = await import("../lib/paths.mjs");
-  const result = await doctor({ appDir: getAppDir(), currentVersion: currentVersion() });
-  console.log(formatDoctorReport(result));
-  process.exit(result.ok ? 0 : 1);
-}
-
-async function runRepair() {
-  const { repair } = await import("../lib/repair.mjs");
-  const { getAppDir } = await import("../lib/paths.mjs");
-  const result = await repair({ appDir: getAppDir(), currentVersion: currentVersion() });
-  process.exit(result.ok ? 0 : 1);
-}
-
-async function runUninstall() {
-  const { uninstall } = await import("../lib/uninstall.mjs");
-  const result = await uninstall();
-  process.exit(result.ok ? 0 : 1);
-}
-
-async function main(argv) {
-  const [cmd] = argv;
-  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();
-  // `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);
-}
-
-main(process.argv.slice(2)).catch((e) => {
-  console.error(`getculpa: ${e.message}`);
-  process.exit(1);
-});
+#!/usr/bin/env node
+// CF20-T3 — `getculpa` command router.
+//
+//   getculpa | getculpa start   -> wake the stack (CF20-T4)
+//   getculpa doctor / repair    -> diagnostics + self-heal (CF20-T5)
+//   getculpa uninstall          -> lib/uninstall.mjs
+//   getculpa --help / --version -> local, no launcher needed
+//   anything else (scan, connect, update, config, ...) -> passthrough to the
+//     vendored launcher, exactly like bin/culpa.js does today.
+
+"use strict";
+
+const { spawnSync } = require("node:child_process");
+const fs = require("node:fs");
+const path = require("node:path");
+
+const HELP = `getculpa - Culpa, LLM spend forensics and forecasting, local-first
+
+Usage:
+  getculpa                 Start (or resume) the Culpa stack
+  getculpa start           Same as above
+  getculpa stop            Stop the running stack (data is kept)
+  getculpa restart         Stop, then start
+  getculpa status          Show install/docker/stack/license status
+  getculpa doctor          Diagnose this install
+  getculpa repair          Re-stage missing/corrupt install files (no data touched)
+  getculpa uninstall       Remove Culpa (data is kept unless you confirm)
+  getculpa scan            Refresh the Culpa ledger (needs the running stack);
+                           --preview reads local logs offline: no Docker, no network
+  getculpa connect         Print the topology-appropriate capture recipe
+  getculpa update          Manage CLI launcher updates
+  getculpa <verb> --help   scan / connect / update / config: the culpa CLI's own help, under this name
+  getculpa --help          Show this help
+  getculpa --version       Show the getculpa package version
+`;
+
+function printVersion() {
+  const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, "..", "package.json"), "utf8"));
+  console.log(pkg.version);
+}
+
+function runLauncherPassthrough(args, env) {
+  const exe = process.platform === "win32" ? ".exe" : "";
+  const launcher = path.join(__dirname, "..", "vendor", `culpa-launcher${exe}`);
+  if (!fs.existsSync(launcher)) {
+    console.error("getculpa: the launcher is not installed (postinstall failed or was skipped).");
+    console.error("getculpa: run `npm rebuild getculpa` (or reinstall) to fetch it.");
+    process.exit(1);
+  }
+  // T-182.8 (ISS-MAC-11): the launcher and the CLI spell their usage in
+  // the invoked name — the environment carries it (lib/dispatch.mjs)
+  const result = spawnSync(launcher, args, { stdio: "inherit", env });
+  process.exit(result.status === null ? 1 : result.status);
+}
+
+function currentVersion() {
+  return JSON.parse(fs.readFileSync(path.join(__dirname, "..", "package.json"), "utf8")).version;
+}
+
+function printResult(result) {
+  if (result.ok) return;
+  console.error("");
+  console.error(`Culpa couldn't start.`);
+  console.error(result.message ?? "(no further detail)");
+  if (result.recovery) console.error(result.recovery);
+}
+
+// T-V1010-1 Task B: the vendored launcher, so start() can fetch the CLI
+// payload that matches this package before the stack comes up.
+async function launcherPath() {
+  const { vendoredLauncherPath } = await import("../lib/bootstrap.mjs");
+  return vendoredLauncherPath(path.join(__dirname, ".."));
+}
+
+async function runStart() {
+  const { start } = await import("../lib/start.mjs");
+  const { getAppDir } = await import("../lib/paths.mjs");
+  const result = await start({ appDir: getAppDir(), currentVersion: currentVersion(), launcherPath: await launcherPath() });
+  if (!result.ok) {
+    printResult(result);
+    process.exit(1);
+  }
+  process.exit(0);
+}
+
+async function runStop() {
+  const { stop } = await import("../lib/stop.mjs");
+  const result = await stop();
+  process.exit(result.ok ? 0 : 1);
+}
+
+async function runRestart() {
+  const { stop } = await import("../lib/stop.mjs");
+  const { start } = await import("../lib/start.mjs");
+  const { getAppDir } = await import("../lib/paths.mjs");
+  await stop();
+  const result = await start({ appDir: getAppDir(), currentVersion: currentVersion(), launcherPath: await launcherPath() });
+  if (!result.ok) {
+    printResult(result);
+    process.exit(1);
+  }
+  process.exit(0);
+}
+
+async function runStatus() {
+  const { status, formatStatus } = await import("../lib/status.mjs");
+  const result = await status();
+  console.log(formatStatus(result));
+  process.exit(0);
+}
+
+async function runDoctor() {
+  const { doctor, formatDoctorReport } = await import("../lib/doctor.mjs");
+  const { getAppDir } = await import("../lib/paths.mjs");
+  const result = await doctor({ appDir: getAppDir(), currentVersion: currentVersion() });
+  console.log(formatDoctorReport(result));
+  process.exit(result.ok ? 0 : 1);
+}
+
+async function runRepair() {
+  const { repair } = await import("../lib/repair.mjs");
+  const { getAppDir } = await import("../lib/paths.mjs");
+  const result = await repair({ appDir: getAppDir(), currentVersion: currentVersion() });
+  process.exit(result.ok ? 0 : 1);
+}
+
+async function runUninstall() {
+  const { uninstall } = await import("../lib/uninstall.mjs");
+  const result = await uninstall();
+  process.exit(result.ok ? 0 : 1);
+}
+
+async function main(argv) {
+  const [cmd] = argv;
+  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, passthroughEnv } = 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();
+  // `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, passthroughEnv(process.env));
+}
+
+main(process.argv.slice(2)).catch((e) => {
+  console.error(`getculpa: ${e.message}`);
+  process.exit(1);
+});

package/lib/assets.d.mts

@@ -1,2 +1,2 @@
-export const ASSET_MANIFEST: Record<string, string>;
-export function resolveAssetPath(name: string): string;
+export const ASSET_MANIFEST: Record<string, string>;
+export function resolveAssetPath(name: string): string;

package/lib/bootstrap.d.mts

@@ -1,29 +1,48 @@
-// Unlike docker.d.mts's SpawnSyncLike, this one carries `error`: a spawn that
-// never ran (missing binary, timeout kill) reports it there, not via status.
-export type LauncherSpawnSync = (
-  cmd: string,
-  args?: string[],
-  opts?: Record<string, unknown>,
-) => { status: number | null; error?: Error };
-
-export const PAYLOAD_STAGE_TIMEOUT_MS: number;
-
-export function vendoredLauncherPath(packageRoot: string, platform?: string): string | null;
-
-export interface StageInitialPayloadOptions {
-  launcherPath: string | null;
-  spawnSync?: LauncherSpawnSync;
-  log?: (msg: string) => void;
-  env?: Record<string, string | undefined>;
-}
-
-export interface StageInitialPayloadResult {
-  staged: boolean;
-  reason: "no-launcher" | "spawn-failed" | "update-failed" | "staged";
-}
-
-export function stageInitialPayload(opts: StageInitialPayloadOptions): StageInitialPayloadResult;
-
-export type PayloadState = "installed" | "staged" | "missing";
-
-export function readPayloadState(opts?: { env?: Record<string, string | undefined> }): PayloadState;
+// Unlike docker.d.mts's SpawnSyncLike, this one carries `error`: a spawn that
+// never ran (missing binary, timeout kill) reports it there, not via status.
+export type LauncherSpawnSync = (
+  cmd: string,
+  args?: string[],
+  opts?: Record<string, unknown>,
+) => { status: number | null; error?: Error };
+
+export const PAYLOAD_STAGE_TIMEOUT_MS: number;
+
+export function vendoredLauncherPath(packageRoot: string, platform?: string): string | null;
+
+export interface StageInitialPayloadOptions {
+  launcherPath: string | null;
+  spawnSync?: LauncherSpawnSync;
+  log?: (msg: string) => void;
+  env?: Record<string, string | undefined>;
+  /** T-V1010-1: the npm package's version; enables the version-aware judgement and the single retry. */
+  expectedVersion?: string;
+  readDetail?: (opts: ReadPayloadOptions) => PayloadDetail;
+}
+
+export interface StageInitialPayloadResult {
+  staged: boolean;
+  reason: "no-launcher" | "spawn-failed" | "update-failed" | "staged";
+  /** present only when expectedVersion was given */
+  detail?: PayloadDetail;
+}
+
+export function stageInitialPayload(opts: StageInitialPayloadOptions): StageInitialPayloadResult;
+
+/** "behind" (T-V1010-1) exists only when expectedVersion is known. */
+export type PayloadState = "installed" | "staged" | "behind" | "missing";
+
+export interface ReadPayloadOptions {
+  env?: Record<string, string | undefined>;
+  expectedVersion?: string;
+}
+
+export interface PayloadDetail {
+  state: PayloadState;
+  current: string | null;
+  pending: string | null;
+}
+
+export function readPayloadState(opts?: ReadPayloadOptions): PayloadState;
+
+export function readPayloadDetail(opts?: ReadPayloadOptions): PayloadDetail;