great-cto 2.79.0 → 2.80.0

package/board/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "great_cto",
   "id": "great_cto",
   "description": "Engineering process for solo founders and teams up to 50 engineers. Agents do architecture, code review, QA, and security. You make two decisions per feature.",
-  "version": "2.79.0",
+  "version": "2.80.0",
   "author": {
     "name": "Great CTO",
     "url": "https://github.com/avelikiy/great_cto"

package/dist/main.js

@@ -55,6 +55,7 @@ function parseArgs(argv) {
         useLlm: false,
         noLlm: false,
         host: null,
+        upgradeSelf: false,
         positional: [],
     };
     const rest = [];
@@ -120,6 +121,8 @@ function parseArgs(argv) {
             args.command = "report";
         else if (a === "upgrade")
             args.command = "upgrade";
+        else if (a === "--self")
+            args.upgradeSelf = true;
         else if (a === "task") {
             args.command = "task";
             args.taskArgs = argv.slice(i + 1);
@@ -356,6 +359,7 @@ ${bold("Usage:")}
   npx great-cto adapt [--dry-run]
   npx great-cto serve [--port 3142]
   npx great-cto upgrade [superpowers|beads]  Re-clone companions to latest tag + re-apply overlays
+  npx great-cto upgrade --self                Upgrade the great-cto CLI itself, in place
   npx great-cto help
   npx great-cto version
 
@@ -386,6 +390,7 @@ ${bold("Upgrade:")}
   great-cto upgrade              Upgrade superpowers + beads to latest, re-apply critic overlays
   great-cto upgrade superpowers  Upgrade superpowers only
   great-cto upgrade beads        Upgrade beads only
+  great-cto upgrade --self       Upgrade the great-cto CLI itself (also: upgrade self)
   ${dim("(Safe to run any time — idempotent if already on latest)")}
 
 ${bold("CI gate:")}
@@ -999,12 +1004,36 @@ function installPrePushHook(projectDir) {
         // Best-effort: hook failure must never block init
     }
 }
-async function runUpgrade(rawArgv) {
+async function runSelfUpgrade() {
+    const { performSelfUpgrade, resolveRunningBinaryPath } = await import("./self-upgrade.js");
+    const currentVersion = getCliVersion();
+    const binaryPath = resolveRunningBinaryPath();
+    log(`${bold("great-cto upgrade --self")} — current version ${cyan(currentVersion)}`);
+    log(dim(`  running binary: ${binaryPath}`));
+    log("");
+    const result = performSelfUpgrade({ currentVersion, binaryPath });
+    if (result.manager === "npx") {
+        log(result.message);
+        return 0;
+    }
+    if (result.exitCode !== 0) {
+        error(result.message);
+        return result.exitCode;
+    }
+    success(result.message);
+    return 0;
+}
+async function runUpgrade(rawArgv, args) {
+    // `upgrade --self` / `upgrade self` — upgrade the CLI itself, not companion plugins.
+    const upgradeIdx = rawArgv.indexOf("upgrade");
+    const firstArgAfterUpgrade = upgradeIdx >= 0 ? rawArgv[upgradeIdx + 1] : undefined;
+    if (args.upgradeSelf || firstArgAfterUpgrade === "self") {
+        return runSelfUpgrade();
+    }
     const { upgradePlugin, upgradeAll } = await import("./upgrade.js");
     const { COMPANION_PLUGINS } = await import("./companion.js");
     // Optional positional: great-cto upgrade [plugin-name]
-    const upgradeIdx = rawArgv.indexOf("upgrade");
-    const pluginArg = upgradeIdx >= 0 ? rawArgv[upgradeIdx + 1] : undefined;
+    const pluginArg = firstArgAfterUpgrade;
     const targetPlugin = pluginArg && !pluginArg.startsWith("--") ? pluginArg : undefined;
     let results;
     if (targetPlugin) {
@@ -1048,12 +1077,16 @@ async function main() {
             });
         }
         catch { /* telemetry never affects the exit */ }
-        // Update hint — printed after the command's own output, never blocks on
-        // network (reads a local cache; spawns a detached refresh if stale).
-        // Excluded automatically for mcp/worker/task via PROTOCOL_SENSITIVE_COMMANDS
-        // inside checkForUpdate — worker/task don't even route through finish().
+        // Update hint / prompt — printed after the command's own output, never
+        // blocks on network (reads a local cache; spawns a detached refresh if
+        // stale). May await a single Y/n keystroke for up to 15s, but ONLY when
+        // a newer version is already cached, stderr+stdin are TTYs, and this
+        // version hasn't been prompted before (see shouldPrompt() in
+        // update-check.ts). Excluded automatically for mcp/worker/task via
+        // PROTOCOL_SENSITIVE_COMMANDS inside checkForUpdate — worker/task don't
+        // even route through finish().
         try {
-            checkForUpdate({ currentVersion: getCliVersion(), command: args.command });
+            await checkForUpdate({ currentVersion: getCliVersion(), command: args.command });
         }
         catch { /* update hint never affects the exit */ }
         process.exit(code);
@@ -1189,7 +1222,7 @@ async function main() {
     }
     if (args.command === "upgrade") {
         try {
-            const code = await runUpgrade(rawArgv);
+            const code = await runUpgrade(rawArgv, args);
             await finish(code);
         }
         catch (e) {

package/dist/self-upgrade.js

@@ -0,0 +1,156 @@
+/**
+ * self-upgrade.ts — `great-cto upgrade --self` (and `great-cto upgrade self`).
+ *
+ * Upgrades the great-cto CLI itself, in place, by detecting HOW the running
+ * binary was installed and running the matching package-manager command.
+ *
+ * Detection is driven entirely by the resolved (symlinks-followed) path to
+ * the currently-running binary — never by "which npm is on PATH" or similar,
+ * because a machine can have multiple package managers and multiple install
+ * prefixes at once (e.g. a Volta-style toolchain manager alongside a plain
+ * nvm-style Node version manager). The whole point of resolving from
+ * process.argv[1] is to upgrade the exact binary that is actually running,
+ * not just "some" great-cto install found elsewhere on the machine.
+ *
+ * Detection is a pure function (binaryPath: string -> Plan) so it's fully
+ * unit-testable without spawning any process or touching the filesystem.
+ */
+import { realpathSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { sep } from "node:path";
+/**
+ * Pure function: given the resolved path to the running binary, decide which
+ * package manager "owns" it and what command would upgrade it in place.
+ *
+ * Resolution order (first match wins):
+ *   1. npx / npm exec cache            -> no-op (npx always runs latest already)
+ *   2. Volta shim/install directory    -> `volta install great-cto@latest`
+ *   3. pnpm global install directory   -> `pnpm add -g great-cto@latest`
+ *   4. anything else (plain npm/nvm)   -> `npm install -g great-cto@latest --prefix <prefix>`
+ *
+ * `pathSep` is injectable purely so tests can exercise POSIX-style paths
+ * deterministically regardless of the host OS running the test.
+ */
+export function detectInstall(binaryPath, pathSep = sep) {
+    const normalized = binaryPath.split("\\").join("/");
+    // 1. npx / npm exec cache — npx always fetches+runs the latest version on
+    //    every invocation, so there is nothing to "upgrade": the next `npx
+    //    great-cto` already gets the newest release. Installing here would be
+    //    a no-op at best and would litter the npx cache at worst.
+    if (normalized.includes("/_npx/") || normalized.includes("/.npm/_npx/") || /\/\.npm\/[^/]*_cacache/.test(normalized)) {
+        return { manager: "npx", prefix: null, command: null };
+    }
+    // 2. Volta — toolchain manager that shims global installs under ~/.volta
+    //    (real-world installs use the dotfile form ".volta"; match both so the
+    //    detector works against the actual directory Volta creates).
+    if (normalized.includes("/volta/") || normalized.includes("/.volta/")) {
+        return { manager: "volta", prefix: null, command: ["volta", "install", "great-cto@latest"] };
+    }
+    // 3. pnpm — global installs live under a pnpm-managed store/bin directory
+    //    (real-world installs use the dotfile form ".pnpm"/".local/share/pnpm";
+    //    match both bare and dotfile forms for the same reason as Volta above).
+    if (normalized.includes("/pnpm/") || normalized.includes("/.pnpm/")) {
+        return { manager: "pnpm", prefix: null, command: ["pnpm", "add", "-g", "great-cto@latest"] };
+    }
+    // 4. Plain npm (including nvm-style per-version prefixes, and custom
+    //    prefixes like a dotfile-managed toolchain directory). Derive the
+    //    global prefix from the binary path: a global npm bin shim always
+    //    lives at "<prefix>/bin/<name>", so the prefix is the parent of the
+    //    "bin" directory. For nvm-style layouts (~/.nvm/versions/node/vX.Y.Z/bin/great-cto)
+    //    that parent *is* the version's own prefix, which is exactly right —
+    //    npm install -g scoped with --prefix installs into that same version's
+    //    global node_modules, so the binary that's running gets upgraded, not
+    //    some other prefix on the machine.
+    const prefix = derivePrefixFromBinPath(normalized, pathSep);
+    if (prefix) {
+        return { manager: "npm", prefix, command: ["npm", "install", "-g", "great-cto@latest", "--prefix", prefix] };
+    }
+    // Derivation failed (e.g. binary isn't inside a "bin" dir at all) — fall
+    // back to a plain global install and let npm pick whatever prefix is
+    // currently configured (npm config get prefix / NPM_CONFIG_PREFIX).
+    return { manager: "npm", prefix: null, command: ["npm", "install", "-g", "great-cto@latest"] };
+}
+/** …/bin/great-cto -> prefix is the directory above "bin". Returns null if no "bin" segment is found. */
+function derivePrefixFromBinPath(normalizedPath, _pathSep) {
+    const parts = normalizedPath.split("/").filter((p) => p !== "");
+    const binIdx = parts.lastIndexOf("bin");
+    if (binIdx <= 0)
+        return null; // no "bin" dir, or "bin" is the root itself
+    const prefixParts = parts.slice(0, binIdx);
+    const isAbsolute = normalizedPath.startsWith("/");
+    return (isAbsolute ? "/" : "") + prefixParts.join("/");
+}
+/**
+ * Resolve the real (symlinks-followed) path to the currently-running binary.
+ * Exported so callers/tests can compute it once and pass it through.
+ */
+export function resolveRunningBinaryPath(argv1 = process.argv[1] ?? "") {
+    try {
+        return realpathSync(argv1);
+    }
+    catch {
+        return argv1;
+    }
+}
+/**
+ * Perform the actual self-upgrade: run the install command synchronously
+ * with inherited stdio, then verify by spawning the SAME binary path with
+ * --version.
+ *
+ * Never throws — all failure modes are captured in the returned result so
+ * callers can decide the process exit code themselves.
+ */
+export function performSelfUpgrade(opts) {
+    const binaryPath = opts.binaryPath ?? resolveRunningBinaryPath();
+    const spawnFn = opts.spawnFn ?? spawnSync;
+    const plan = detectInstall(binaryPath);
+    if (plan.manager === "npx" || plan.command === null) {
+        return {
+            exitCode: 0,
+            manager: "npx",
+            prefix: null,
+            oldVersion: opts.currentVersion,
+            newVersion: opts.currentVersion,
+            message: "running via npx — npx always fetches the latest release on every run, nothing to upgrade.",
+        };
+    }
+    const [cmd, ...cmdArgs] = plan.command;
+    const installRun = spawnFn(cmd, cmdArgs, { stdio: "inherit" });
+    if (installRun.error) {
+        return {
+            exitCode: 1,
+            manager: plan.manager,
+            prefix: plan.prefix,
+            oldVersion: opts.currentVersion,
+            newVersion: null,
+            message: `self-upgrade failed: could not run '${plan.command.join(" ")}' — ${installRun.error.message}`,
+        };
+    }
+    const installExitCode = installRun.status ?? 1;
+    if (installExitCode !== 0) {
+        return {
+            exitCode: installExitCode,
+            manager: plan.manager,
+            prefix: plan.prefix,
+            oldVersion: opts.currentVersion,
+            newVersion: null,
+            message: `self-upgrade failed: '${plan.command.join(" ")}' exited with code ${installExitCode}`,
+        };
+    }
+    // Verify: spawn the SAME binary path with --version and report old -> new.
+    const verifyRun = spawnFn(process.execPath, [binaryPath, "--version"], { encoding: "utf8" });
+    const newVersion = verifyRun.status === 0 ? (verifyRun.stdout ?? "").trim() || null : null;
+    const prefixNote = plan.prefix ? ` (prefix: ${plan.prefix})` : "";
+    return {
+        exitCode: 0,
+        manager: plan.manager,
+        prefix: plan.prefix,
+        oldVersion: opts.currentVersion,
+        newVersion,
+        message: newVersion
+            ? `upgraded via ${plan.manager}${prefixNote}: ${opts.currentVersion} → ${newVersion}`
+            : `install via ${plan.manager}${prefixNote} succeeded, but could not verify the new version (--version check failed)`,
+    };
+}
+// Re-export for callers that only need the prefix-derivation logic directly.
+export { derivePrefixFromBinPath as _derivePrefixFromBinPath };

package/dist/update-check.js

@@ -22,8 +22,18 @@
 //
 // Opt-out: GREAT_CTO_NO_UPDATE_CHECK=1 (checked by both the foreground read
 // and the background refresh entry point).
+//
+// Interactive prompt: when a newer version is found AND both stderr and
+// stdin are TTYs AND the check isn't suppressed AND this specific version
+// hasn't been prompted for before, checkForUpdate() asks `Update to X? [Y/n]`
+// on stderr with a 15s timeout (node:readline). "Yes" runs the same
+// self-upgrade code path as `great-cto upgrade --self`, in-process. Either
+// way the chosen (or timed-out) version is recorded in the cache file's
+// `promptedFor` field so a given release is prompted for AT MOST ONCE —
+// every later run falls back to the one-line hint.
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -31,6 +41,7 @@ import { semverDescending } from "./semver.js";
 export const REGISTRY_DIST_TAGS_URL = "https://registry.npmjs.org/-/package/great-cto/dist-tags";
 export const CACHE_FRESH_MS = 24 * 60 * 60 * 1000; // 24h
 export const PACKAGE_NAME = "great-cto";
+export const PROMPT_TIMEOUT_MS = 15_000;
 /** Commands where stdout/stderr are machine-parsed — never print a hint, never spawn a check. */
 export const PROTOCOL_SENSITIVE_COMMANDS = new Set([
     "mcp", // stdio JSON-RPC protocol — any stray byte on stdout/stderr breaks the client
@@ -58,6 +69,30 @@ export function isSuppressed(opts = {}) {
         return true;
     return false;
 }
+/**
+ * Pure function: should the interactive `Update to X? [Y/n]` prompt fire?
+ *
+ * All of the following must hold:
+ *   - not suppressed (isSuppressed() — reuses the same CI/opt-out/protocol/TTY rules)
+ *   - stdin is ALSO a TTY (isSuppressed only checks stderr; a prompt needs to
+ *     read a keystroke, so a piped/redirected stdin must never block on it)
+ *   - a newer version is actually available
+ *   - this exact `latest` version hasn't already been prompted for
+ *     (cache.promptedFor === latest means "already asked, at most once per release")
+ */
+export function shouldPrompt(opts) {
+    if (isSuppressed({ env: opts.env, command: opts.command, stderrIsTTY: opts.stderrIsTTY }))
+        return false;
+    if (opts.stdinIsTTY !== true)
+        return false;
+    if (!opts.cache)
+        return false;
+    if (!isNewerVersion(opts.currentVersion, opts.cache.latest))
+        return false;
+    if (opts.cache.promptedFor === opts.cache.latest)
+        return false;
+    return true;
+}
 /** Pure function: read + parse cache JSON. Returns null on any error (missing/corrupt). */
 export function readCache(readFileFn = (p) => readFileSync(p, "utf8"), path = cachePath()) {
     try {
@@ -65,12 +100,33 @@ export function readCache(readFileFn = (p) => readFileSync(p, "utf8"), path = ca
         const parsed = JSON.parse(raw);
         if (typeof parsed.checkedAt !== "string" || typeof parsed.latest !== "string")
             return null;
-        return { checkedAt: parsed.checkedAt, latest: parsed.latest };
+        const cache = { checkedAt: parsed.checkedAt, latest: parsed.latest };
+        if (typeof parsed.promptedFor === "string")
+            cache.promptedFor = parsed.promptedFor;
+        return cache;
     }
     catch {
         return null;
     }
 }
+/**
+ * Pure function: write `promptedFor` into the cache file, preserving the
+ * other fields. Best-effort — swallows write errors (a failed write just
+ * means the prompt might fire again next run, which is safe, not silent
+ * data loss).
+ */
+export function recordPromptedFor(version, readFileFn = (p) => readFileSync(p, "utf8"), writeFileFn = writeFileSync, path = cachePath()) {
+    try {
+        const existing = readCache(readFileFn, path);
+        const cache = existing
+            ? { ...existing, promptedFor: version }
+            : { checkedAt: new Date().toISOString(), latest: version, promptedFor: version };
+        writeFileFn(path, JSON.stringify(cache, null, 2) + "\n");
+    }
+    catch {
+        /* best-effort — never break the CLI over a cache write failure */
+    }
+}
 /** Pure function: is a cache entry still fresh (<24h old)? */
 export function isCacheFresh(cache, now = Date.now(), freshMs = CACHE_FRESH_MS) {
     if (!cache)
@@ -93,28 +149,85 @@ export function formatHint(current, latest, styler = {
     dim: (s) => s,
     bold: (s) => s,
 }) {
-    return `${styler.dim("update available:")} ${styler.dim(current)} ${styler.dim("→")} ${styler.bold(styler.cyan(latest))}  ${styler.dim(`run ${styler.cyan("npm i -g great-cto")} to upgrade`)}`;
+    return `${styler.dim("update available:")} ${styler.dim(current)} ${styler.dim("→")} ${styler.bold(styler.cyan(latest))}  ${styler.dim(`run ${styler.cyan("great-cto upgrade --self")} to upgrade`)}`;
+}
+/**
+ * Ask `question` on stderr and read one line of input from stdin via
+ * node:readline, with a hard timeout. Resolves `true` for an empty/"y"/"Y"
+ * answer, `false` for anything else INCLUDING a timeout or "n". Never
+ * rejects. Only called when both stderr and stdin are already confirmed
+ * TTYs (see shouldPrompt), so this never blocks a piped/CI invocation.
+ *
+ * `input`/`output` are injectable (defaulting to the real process streams)
+ * so tests can exercise real readline behavior — including the timeout —
+ * against isolated streams instead of monkey-patching process.stdin.
+ */
+export function promptYesNo(question, timeoutMs = PROMPT_TIMEOUT_MS, input = process.stdin, output = process.stderr) {
+    return new Promise((resolve) => {
+        const rl = createInterface({ input, output, terminal: false });
+        let settled = false;
+        const finish = (answer) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            rl.close();
+            resolve(answer);
+        };
+        // Intentionally NOT unref'd: this timer is the only thing standing
+        // between "user is deciding" and "give up and fall back to the hint" —
+        // it must keep the event loop alive for up to timeoutMs so the prompt
+        // reliably resolves (and, on success, so recordPromptedFor()/finish()
+        // in main.ts still run). It is always cleared on any resolution path
+        // (answer or timeout), so it never actually blocks exit beyond that.
+        const timer = setTimeout(() => finish(false), timeoutMs);
+        try {
+            rl.question(question, (answer) => {
+                const normalized = answer.trim().toLowerCase();
+                finish(normalized === "" || normalized === "y" || normalized === "yes");
+            });
+        }
+        catch {
+            finish(false);
+        }
+    });
 }
 /**
  * Foreground entry point. Call once per CLI invocation, after the command's
- * normal output has been printed. Never throws, never awaits network I/O.
+ * normal output has been printed. Never throws.
  *
  * - If suppressed: no-op.
- * - If cache is fresh: print hint (if newer) synchronously, no spawn.
+ * - If cache is fresh:
+ *     - if a newer version exists and shouldPrompt() says yes, show the
+ *       interactive `Update to X? [Y/n]` prompt (15s timeout) and, on yes,
+ *       run the self-upgrade in-process before returning.
+ *     - otherwise, print the one-line hint (if newer) exactly as before.
  * - If cache is missing/stale: spawn a detached background refresh and
- *   return immediately (no hint this run — the cache isn't warm yet).
+ *   return immediately (no hint/prompt this run — the cache isn't warm yet).
+ *
+ * Only the prompt path awaits anything (stdin, up to 15s); every other path
+ * returns synchronously-fast, matching the original never-block guarantee.
  */
-export function checkForUpdate(opts) {
+export async function checkForUpdate(opts) {
     try {
         const env = opts.env ?? process.env;
         const stderrIsTTY = opts.stderrIsTTY ?? Boolean(process.stderr.isTTY);
+        const stdinIsTTY = opts.stdinIsTTY ?? Boolean(process.stdin.isTTY);
         if (isSuppressed({ env, command: opts.command, stderrIsTTY }))
             return;
         const cache = readCache();
         if (isCacheFresh(cache, opts.now)) {
-            if (cache && isNewerVersion(opts.currentVersion, cache.latest)) {
-                printHint(opts.currentVersion, cache.latest);
+            if (!cache || !isNewerVersion(opts.currentVersion, cache.latest))
+                return;
+            if (shouldPrompt({ currentVersion: opts.currentVersion, cache, env, command: opts.command, stderrIsTTY, stdinIsTTY })) {
+                const accepted = await promptYesNo(`Update to ${cache.latest}? [Y/n] `);
+                recordPromptedFor(cache.latest);
+                if (accepted) {
+                    await runSelfUpgradeInProcess(opts.currentVersion);
+                }
+                return;
             }
+            printHint(opts.currentVersion, cache.latest);
             return;
         }
         spawnBackgroundCheck();
@@ -123,6 +236,23 @@ export function checkForUpdate(opts) {
         // Fail-silent — an update hint must never break or slow down a real command.
     }
 }
+/**
+ * Run the same self-upgrade code path as `great-cto upgrade --self`,
+ * in-process, after the user accepted the interactive prompt. Isolated into
+ * its own function (rather than importing self-upgrade.ts at module scope)
+ * so update-check.ts's own unit tests never need to touch child_process.
+ */
+async function runSelfUpgradeInProcess(currentVersion) {
+    try {
+        const { performSelfUpgrade, resolveRunningBinaryPath } = await import("./self-upgrade.js");
+        const binaryPath = resolveRunningBinaryPath();
+        const result = performSelfUpgrade({ currentVersion, binaryPath });
+        process.stderr.write((result.exitCode === 0 ? result.message : `error: ${result.message}`) + "\n");
+    }
+    catch {
+        /* fail-silent — an accepted prompt must never crash the command that triggered it */
+    }
+}
 function printHint(current, latest) {
     try {
         // Local, minimal color helpers mirroring ui.ts's NO_COLOR-aware wrap(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "great-cto",
-  "version": "2.79.0",
+  "version": "2.80.0",
   "description": "One command install for the great_cto Claude Code plugin. Auto-detects your stack, picks the right archetype, bootstraps PROJECT.md.",
   "keywords": [
     "claude-code",