getculpa 1.0.1 → 1.0.2

package/lib/start.mjs

@@ -34,12 +34,14 @@ import {
   preMigrationBackup,
   probeHealth,
   resolveBackupBaseline,
+  installDockerDarwin,
   startEngineIfPossible,
   waitForDockerEngine,
   waitForHealth,
   waitForPgReady,
 } from "./docker.mjs";
 import { checkDockerPresent, compareVersions, parsePinnedServerVersion } from "./preflight.mjs";
+import { askYesNo as realAskYesNo } from "./tty.mjs";
 
 export const STAGES = Object.freeze({
   CHECK_INSTALLATION: "CHECK_INSTALLATION",
@@ -186,6 +188,85 @@ async function runVersionGuards({ appDir, liveCompose, spawnSync, env, log, warn
   return { pinnedVersion };
 }
 
+// T-CF28-7 — "The install fails to ask for docker and other dependencies. IT
+// MUST ASK AND INSTALL THESE" (founder). This is the ASK half; the DETECT half
+// runs at npm-install time (lib/install-summary.mjs), because postinstall
+// cannot prompt (scripts/install.js:13-15).
+//
+// Reached only when Docker is genuinely absent on a non-win32 platform. Every
+// branch ends in a fail() — even a SUCCESSFUL install, because Docker Desktop
+// still needs one manual launch before its engine answers. That mirrors
+// launch-culpa.ps1:233, which likewise stops after installing rather than
+// pretending the stack is coming up.
+const DOCKER_DESKTOP_URL = "https://www.docker.com/products/docker-desktop/";
+const DOCKER_ENGINE_DOCS_URL = "https://docs.docker.com/engine/install/";
+const DOCKER_MISSING = "Culpa couldn't start: Docker is not installed.";
+
+// The consent text IS the disclosure. It names the exact command, that a
+// password will be asked for, and that a manual first launch is still
+// required — so nobody agrees to a "one-click install" that isn't one.
+const DARWIN_CONSENT_QUESTION =
+  "Culpa needs Docker to run, and it was not found on this machine.\n" +
+  "Install it now with `brew install --cask docker`?\n" +
+  "  Homebrew will ask for your password, and afterwards you must open Docker once\n" +
+  "  from Applications - this cannot be a fully hands-off install.\n" +
+  "  Nothing is downloaded unless you answer yes.\n" +
+  "Install Docker now? (y/N) ";
+
+async function offerDockerInstall({ platform, spawnSync, log, askYesNo, isInteractive }) {
+  // linux: installing a system package without explicit consent is out of
+  // bounds — the same rule startEngineIfPossible already follows for merely
+  // STARTING the engine (docker.mjs:73-79). Guidance only, and no prompt: a
+  // yes here could not be honoured anyway.
+  if (platform !== "darwin") {
+    return fail(
+      STAGES.CHECK_DOCKER,
+      DOCKER_MISSING,
+      `Culpa runs its database and services in containers. Install Docker Engine (${DOCKER_ENGINE_DOCS_URL}), then run \`getculpa\` again. Culpa will not install system packages for you.`,
+    );
+  }
+
+  if (!isInteractive) {
+    return fail(
+      STAGES.CHECK_DOCKER,
+      DOCKER_MISSING,
+      `Culpa runs its database and services in containers. Install it with \`brew install --cask docker\` (or download it from ${DOCKER_DESKTOP_URL}), open Docker once, then run \`getculpa\` again.`,
+    );
+  }
+
+  if (!(await askYesNo(DARWIN_CONSENT_QUESTION))) {
+    return fail(
+      STAGES.CHECK_DOCKER,
+      DOCKER_MISSING,
+      `The Docker install was not authorized, so nothing was installed and nothing was changed. Install it yourself with \`brew install --cask docker\` or from ${DOCKER_DESKTOP_URL}, then run \`getculpa\` again.`,
+    );
+  }
+
+  log("==> Installing Docker Desktop with Homebrew (brew install --cask docker)");
+  const outcome = installDockerDarwin(spawnSync);
+
+  if (outcome === "no-brew") {
+    return fail(
+      STAGES.CHECK_DOCKER,
+      DOCKER_MISSING,
+      `Homebrew is not available, so Docker could not be installed automatically. Nothing was changed. Download Docker Desktop from ${DOCKER_DESKTOP_URL}, open it once, then run \`getculpa\` again.`,
+    );
+  }
+  if (outcome !== "installed") {
+    const code = outcome.replace(/^failed:/, "");
+    return fail(
+      STAGES.CHECK_DOCKER,
+      DOCKER_MISSING,
+      `Homebrew could not install Docker (exit code ${code}). Nothing else was changed. Install Docker Desktop from ${DOCKER_DESKTOP_URL}, open it once, then run \`getculpa\` again.`,
+    );
+  }
+  return fail(
+    STAGES.CHECK_DOCKER,
+    "Docker was installed. Culpa has not started yet.",
+    "Open Docker once from Applications and wait for it to finish starting, then run `getculpa` again.",
+  );
+}
+
 function maybeOpenBrowser({ env, isTTY, openBrowser }) {
   if (!isTTY) return;
   if (env.CULPA_NO_BROWSER) return;
@@ -359,6 +440,11 @@ export async function start(opts) {
     openBrowser = defaultOpenBrowser,
     isTTY = process.stdout.isTTY,
     delegateWindowsLaunch = defaultDelegateWindowsLaunch,
+    // T-CF28-7: consent needs BOTH ends of the terminal — stdin to read the
+    // answer, stdout for the question. isTTY above is stdout-only (it gates
+    // the browser open), so it cannot stand in for this.
+    isInteractive = Boolean(process.stdin.isTTY && process.stdout.isTTY),
+    askYesNo = (question) => realAskYesNo(question, { isInteractive }),
   } = opts;
 
   const stagesRun = [STAGES.CHECK_INSTALLATION];
@@ -369,10 +455,11 @@ export async function start(opts) {
 
   stagesRun.push(STAGES.CHECK_DOCKER);
   if (platform !== "win32" && !checkDockerPresent(spawnSync)) {
-    return {
-      ...fail(STAGES.CHECK_DOCKER, "Culpa couldn't start Docker.", "Install Docker (https://docs.docker.com/get-docker/), then run `getculpa` again."),
-      stagesRun,
-    };
+    // T-CF28-7: was a dead end with a bare URL. Still a hard gate — nothing
+    // below can work without Docker — but on darwin it now offers to install
+    // it first. win32 is deliberately excluded (see this file's header):
+    // launch-culpa.ps1:179-234 owns that flow and must not be short-circuited.
+    return { ...(await offerDockerInstall({ platform, spawnSync, log, askYesNo, isInteractive })), stagesRun };
   }
 
   stagesRun.push(STAGES.IDEMPOTENCY_CHECK);

package/lib/tty.d.mts

@@ -0,0 +1,18 @@
+export interface ColourOptions {
+  isTTY?: boolean;
+  env?: Record<string, string | undefined>;
+}
+
+export function colourEnabled(opts?: ColourOptions): boolean;
+export function green(text: string, opts?: ColourOptions): string;
+
+export interface AskYesNoOptions {
+  isInteractive?: boolean;
+  createInterface?: (opts: { input: unknown; output: unknown }) => {
+    question: (q: string, cb: (answer: string) => void) => void;
+    once: (event: string, cb: () => void) => void;
+    close: () => void;
+  };
+}
+
+export function askYesNo(question: string, opts?: AskYesNoOptions): Promise<boolean>;

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/package.json

@@ -1,24 +1,25 @@
-{
-  "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"
-  }
-}
+{
+  "name": "getculpa",
+  "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"
+  },
+  "scripts": {
+    "postinstall": "node scripts/install.js",
+    "prepack": "node scripts/prepack.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "scripts/",
+    "assets/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  }
+}

package/scripts/install.js

@@ -111,21 +111,40 @@ async function main() {
     );
     provisionOpts.delegateWindowsInstaller = () => true;
   }
-  const { classification, previousVersion } = await provision(provisionOpts);
+  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.
-  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");
+  // 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) => {