great-cto 2.78.0 → 2.79.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.78.0",
+  "version": "2.79.0",
   "author": {
     "name": "Great CTO",
     "url": "https://github.com/avelikiy/great_cto"

package/board/packages/board/lib/alerts.mjs

@@ -6,7 +6,7 @@ import {
   loadSubscriptions,
   removeSubscription,
 } from '../push-adapter.mjs';
-import { GREAT_CTO_DIR, PUSH_SUBS_FILE, VAPID_KEYS_FILE, VAPID_SUBJECT } from './config.mjs';
+import { GREAT_CTO_DIR, PUSH_SUBS_FILE, VAPID_KEYS_FILE, VAPID_SUBJECT, BUILD_VERSION } from './config.mjs';
 import { _reportRepublishDedupeSet } from './state.mjs';
 import { listProjects, readProjectMd } from './projects.mjs';
 import { addNotification } from './notifications.mjs';
@@ -16,6 +16,7 @@ import { getTasks } from './beads.mjs';
 import { readVerdicts } from './verdicts.mjs';
 import { isFailure } from './fleet.mjs';
 import { getShareState, toggleShare } from './share.mjs';
+import { checkForRelease, buildUpdatePayload } from './update-alert.mjs';
 import { log } from './log.mjs';
 
 // ── Email alerts (Resend) ─────────────────────────────────────────────────
@@ -134,6 +135,7 @@ async function firePushAlert(eventName, dedupeKey, payload) {
 function startAlertCron() {
   const FIVE_MIN = 5 * 60 * 1000;
   const ONE_HOUR = 60 * 60 * 1000;
+  const ONE_DAY = 24 * 60 * 60 * 1000;
 
   // incident.p0: open P0 task with recent activity (last 24h).
   // Older P0s are existing backlog — surfacing them via email is spam.
@@ -408,7 +410,26 @@ function startAlertCron() {
     } catch (e) { log.warn('cron report.daily failed:', e.message); }
   }, FIVE_MIN);
 
-  log.info('Alert cron started: gate.stale (5min), sla.escalate (5min), connector.health (5min), cost.threshold (1h), digest.daily (Mon–Fri 08:00), digest.weekly (Fri 09:00), report.daily (09:00)');
+  // update.available: daily check for a newer great-cto npm release.
+  // Dedupe key embeds the latest version string (see update-alert.mjs), so a
+  // given release notifies exactly once no matter how many daily ticks pass
+  // while it remains latest — a fresh key is only minted when npm publishes
+  // a newer version. Fails silent offline; skipped entirely when
+  // GREAT_CTO_NO_UPDATE_CHECK=1 (checkForRelease honors the env var itself).
+  setInterval(() => {
+    checkForRelease({
+      currentVersion: BUILD_VERSION,
+      isFired: (dedupeKey) => Boolean(readAlertsFired()[dedupeKey]),
+      notify: (current, latest, dedupeKey) => {
+        const payload = buildUpdatePayload(current, latest);
+        fireEmailAlert('update.available', dedupeKey, payload);
+        addNotification('update.available', payload);
+        firePushAlert('update.available', dedupeKey, payload);
+      },
+    }).catch(e => log.warn('cron update.available failed:', e.message));
+  }, ONE_DAY);
+
+  log.info('Alert cron started: gate.stale (5min), sla.escalate (5min), connector.health (5min), cost.threshold (1h), digest.daily (Mon–Fri 08:00), digest.weekly (Fri 09:00), report.daily (09:00), update.available (24h)');
 }
 
 export { readAlertsFired, writeAlertsFired, fireEmailAlert, firePushAlert, startAlertCron };

package/board/packages/board/lib/update-alert.mjs

@@ -0,0 +1,107 @@
+// Release notification — daily check for a newer great-cto npm release,
+// surfaced through the board's existing notification + push-alert pipeline.
+//
+// Design mirrors the CLI's update-check.ts (same registry endpoint, same
+// zero-dependency approach) but fires through addNotification()/firePushAlert()
+// instead of a stderr hint, since the board is a long-running server, not a
+// one-shot CLI invocation.
+//
+// Registry endpoint: https://registry.npmjs.org/-/package/great-cto/dist-tags
+//   Verified with curl to return only `{"latest":"x.y.z"}`.
+//
+// Dedupe: alerts-fired.json (existing mechanism in alerts.mjs) is keyed by
+// dedupeKey; the key here embeds the latest version string so each new
+// release notifies exactly once, no matter how many daily ticks pass while
+// that version remains the latest.
+//
+// Opt-out: GREAT_CTO_NO_UPDATE_CHECK=1 (same env var as the CLI hint).
+
+const REGISTRY_DIST_TAGS_URL = 'https://registry.npmjs.org/-/package/great-cto/dist-tags';
+const FETCH_TIMEOUT_MS = 3000;
+
+/** Pure function: parse "x.y.z" into a 3-tuple of ints (missing/garbage segments -> 0). */
+function parseSemver(v) {
+  return String(v || '').split('.').map(n => parseInt(n, 10) || 0);
+}
+
+/** Pure function: true when `latest` is strictly newer than `current` (semver order). */
+function isNewerVersion(current, latest) {
+  if (!current || !latest || current === 'unknown') return false;
+  const a = parseSemver(latest);
+  const b = parseSemver(current);
+  for (let i = 0; i < 3; i++) {
+    const d = (a[i] ?? 0) - (b[i] ?? 0);
+    if (d !== 0) return d > 0;
+  }
+  return false;
+}
+
+/** Pure function: the dedupe key for a given latest version — one notification per new release, ever. */
+function updateDedupeKey(latest) {
+  return `update.available:${latest}`;
+}
+
+/** Pure function: build the notification payload for a given current/latest pair. */
+function buildUpdatePayload(current, latest) {
+  return {
+    title: `great_cto v${latest} released (you run v${current})`,
+    body: `A new great-cto release is available. Upgrade with: npx great-cto upgrade`,
+    level: 'info',
+    project: 'great_cto',
+    link: 'https://github.com/avelikiy/great_cto/releases',
+    action: 'View release',
+    kv: { current, latest },
+  };
+}
+
+/** Fetch {latest} from the npm registry. Returns null on any error/timeout/offline — fail-silent by design. */
+async function fetchLatestVersion(fetchFn = fetch) {
+  try {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), FETCH_TIMEOUT_MS);
+    try {
+      const res = await fetchFn(REGISTRY_DIST_TAGS_URL, { signal: ctrl.signal });
+      if (!res.ok) return null;
+      const body = await res.json();
+      return typeof body?.latest === 'string' ? body.latest : null;
+    } finally {
+      clearTimeout(timer);
+    }
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Run one update check. Injectable deps for testing — no real network calls
+ * or fs/notification side effects when `fetchFn`/`isFired`/`notify` are stubs.
+ *
+ * @param {object} opts
+ * @param {string} opts.currentVersion   BUILD_VERSION from lib/config.mjs
+ * @param {(url: string, init?: object) => Promise<Response>} [opts.fetchFn]
+ * @param {(dedupeKey: string) => boolean} [opts.isFired]   dedupe lookup (alerts-fired.json)
+ * @param {(current: string, latest: string, dedupeKey: string) => void} [opts.notify]
+ *   called once when a newer, undelivered version is found
+ * @returns {Promise<{checked: boolean, latest: string|null, notified: boolean}>}
+ */
+async function checkForRelease({ currentVersion, fetchFn = fetch, isFired = () => false, notify = () => {} }) {
+  if (process.env.GREAT_CTO_NO_UPDATE_CHECK === '1') {
+    return { checked: false, latest: null, notified: false };
+  }
+  const latest = await fetchLatestVersion(fetchFn);
+  if (!latest) return { checked: true, latest: null, notified: false };
+  if (!isNewerVersion(currentVersion, latest)) return { checked: true, latest, notified: false };
+  const dedupeKey = updateDedupeKey(latest);
+  if (isFired(dedupeKey)) return { checked: true, latest, notified: false };
+  notify(currentVersion, latest, dedupeKey);
+  return { checked: true, latest, notified: true };
+}
+
+export {
+  REGISTRY_DIST_TAGS_URL,
+  isNewerVersion,
+  updateDedupeKey,
+  buildUpdatePayload,
+  fetchLatestVersion,
+  checkForRelease,
+};

package/dist/main.js

@@ -21,6 +21,7 @@ import { bootstrap } from "./bootstrap.js";
 import { compileFlow } from "./flow.js";
 import { shouldUseLlmFallback, suggestArchetypeFromLlm } from "./llm-fallback.js";
 import { sendUsagePing, sendInstallPing, telemetrySubcommand, isTelemetryEnabled, computeAnonId } from "./telemetry.js";
+import { checkForUpdate } from "./update-check.js";
 import { findBoardServerPath } from "./board-path.js";
 import { readFileSync, writeFileSync, copyFileSync, chmodSync, mkdirSync, unlinkSync, existsSync as fsExistsSync } from "node:fs";
 import { dirname, join } from "node:path";
@@ -1047,6 +1048,14 @@ 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().
+        try {
+            checkForUpdate({ currentVersion: getCliVersion(), command: args.command });
+        }
+        catch { /* update hint never affects the exit */ }
         process.exit(code);
     };
     // `great-cto telemetry <on|off|status|whoami>` — inspect / toggle, never sends.

package/dist/update-check-worker.js

@@ -0,0 +1,6 @@
+// Standalone entry point for the detached background update-check process.
+// Spawned by update-check.ts (spawnBackgroundCheck) via `node dist/update-check-worker.js`.
+// Deliberately tiny: just calls refreshCache() and exits. stdio is "ignore"
+// from the parent, so nothing here should assume a console is attached.
+import { refreshCache } from "./update-check.js";
+await refreshCache();

package/dist/update-check.js

@@ -0,0 +1,193 @@
+// Update notifier — classic update-notifier pattern, zero dependency.
+//
+// Design:
+//   - Foreground NEVER waits on the network. It only reads a local cache
+//     file (~/.great_cto/update-check.json) written by a previous run.
+//   - When the cache is missing or stale (>24h), a DETACHED background
+//     process is spawned (node, stdio ignored, unref'd) that hits the npm
+//     registry and refreshes the cache for the *next* invocation to read.
+//   - This means the very first run (and the first run after 24h) never
+//     shows a hint — the hint appears one run later, once the cache is
+//     warm. That's the standard update-notifier trade-off: never block,
+//     never slow down the command the user actually asked for.
+//
+// Registry endpoint: https://registry.npmjs.org/-/package/great-cto/dist-tags
+//   Verified with curl to return only `{"latest":"x.y.z"}` — much smaller
+//   than the full package document (https://registry.npmjs.org/great-cto),
+//   which would pull the entire versions/times history.
+//
+// Privacy: read-only GET against the public npm registry, equivalent to the
+// request `npm install` already performs. No project data, no PII, nothing
+// user-specific is sent. See docs/PRIVACY.md.
+//
+// Opt-out: GREAT_CTO_NO_UPDATE_CHECK=1 (checked by both the foreground read
+// and the background refresh entry point).
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { spawn } from "node:child_process";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+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";
+/** 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
+    "worker", // long-running daemon; status is polled programmatically
+    "task", // machine-invoked task runner (spawned by worker)
+]);
+function defaultCachePath() {
+    return join(homedir(), ".great_cto", "update-check.json");
+}
+/** Resolve the cache file path — GREAT_CTO_HOME lets tests/worker isolate state, same convention as worker.ts/task-queue.ts. */
+export function cachePath() {
+    const base = process.env.GREAT_CTO_HOME || join(homedir(), ".great_cto");
+    return join(base, "update-check.json");
+}
+/** Pure function: is a suppression condition active? Fail-open to "suppressed" on any ambiguity. */
+export function isSuppressed(opts = {}) {
+    const env = opts.env ?? process.env;
+    if (env.CI != null && env.CI !== "" && env.CI !== "0" && env.CI !== "false")
+        return true;
+    if (env.GREAT_CTO_NO_UPDATE_CHECK === "1")
+        return true;
+    if (opts.command && PROTOCOL_SENSITIVE_COMMANDS.has(opts.command))
+        return true;
+    if (opts.stderrIsTTY === false)
+        return true;
+    return false;
+}
+/** Pure function: read + parse cache JSON. Returns null on any error (missing/corrupt). */
+export function readCache(readFileFn = (p) => readFileSync(p, "utf8"), path = cachePath()) {
+    try {
+        const raw = readFileFn(path);
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.checkedAt !== "string" || typeof parsed.latest !== "string")
+            return null;
+        return { checkedAt: parsed.checkedAt, latest: parsed.latest };
+    }
+    catch {
+        return null;
+    }
+}
+/** Pure function: is a cache entry still fresh (<24h old)? */
+export function isCacheFresh(cache, now = Date.now(), freshMs = CACHE_FRESH_MS) {
+    if (!cache)
+        return false;
+    const checkedAtMs = Date.parse(cache.checkedAt);
+    if (Number.isNaN(checkedAtMs))
+        return false;
+    return now - checkedAtMs < freshMs;
+}
+/** Pure function: does `latest` represent a newer version than `current`? */
+export function isNewerVersion(current, latest) {
+    if (!current || !latest || current === "unknown")
+        return false;
+    // semverDescending(a, b) < 0 means a > b (descending sort). latest > current => descending(latest, current) < 0.
+    return semverDescending(latest, current) < 0;
+}
+/** Pure function: build the one-line stderr hint text. `styler` lets callers inject color helpers (matches ui.ts). */
+export function formatHint(current, latest, styler = {
+    cyan: (s) => s,
+    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`)}`;
+}
+/**
+ * Foreground entry point. Call once per CLI invocation, after the command's
+ * normal output has been printed. Never throws, never awaits network I/O.
+ *
+ * - If suppressed: no-op.
+ * - If cache is fresh: print hint (if newer) synchronously, no spawn.
+ * - If cache is missing/stale: spawn a detached background refresh and
+ *   return immediately (no hint this run — the cache isn't warm yet).
+ */
+export function checkForUpdate(opts) {
+    try {
+        const env = opts.env ?? process.env;
+        const stderrIsTTY = opts.stderrIsTTY ?? Boolean(process.stderr.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);
+            }
+            return;
+        }
+        spawnBackgroundCheck();
+    }
+    catch {
+        // Fail-silent — an update hint must never break or slow down a real command.
+    }
+}
+function printHint(current, latest) {
+    try {
+        // Local, minimal color helpers mirroring ui.ts's NO_COLOR-aware wrap(),
+        // but gated on stderr TTY (ui.ts gates on stdout, which is the wrong
+        // stream for a hint that must print to stderr).
+        const useColor = Boolean(process.stderr.isTTY) && process.env.NO_COLOR !== "1";
+        const wrap = (code) => (s) => (useColor ? `\x1b[${code}m${s}\x1b[0m` : s);
+        const styler = { cyan: wrap("36"), dim: wrap("2"), bold: wrap("1") };
+        process.stderr.write(formatHint(current, latest, styler) + "\n");
+    }
+    catch {
+        /* fail-silent */
+    }
+}
+/** Spawn a detached, unref'd background process that refreshes the cache. Never awaited by the caller. */
+function spawnBackgroundCheck() {
+    try {
+        // Test-only escape hatch: unit tests exercise checkForUpdate()'s control
+        // flow (including "cache missing/stale -> spawn") without ever launching
+        // a real child process or touching the network. Never set in production.
+        if (process.env.GREAT_CTO_UPDATE_CHECK_NO_SPAWN === "1")
+            return;
+        const here = dirname(fileURLToPath(import.meta.url));
+        const entry = join(here, "update-check-worker.js");
+        if (!existsSync(entry))
+            return; // dist not built (e.g. running from src in dev) — skip rather than crash
+        const child = spawn(process.execPath, [entry], {
+            detached: true,
+            stdio: "ignore",
+            env: process.env,
+        });
+        child.unref();
+    }
+    catch {
+        /* fail-silent — network/update check is best-effort only */
+    }
+}
+/**
+ * Background worker body — invoked as a standalone script by
+ * update-check-worker.ts. Fetches the registry dist-tags and writes the
+ * cache. Exported so it's independently unit-testable with an injected
+ * fetcher, without needing to actually spawn a child process.
+ */
+export async function refreshCache(fetchFn = fetch, writeFileFn = writeFileSync, mkdirFn = (p) => mkdirSync(p, { recursive: true }), path = cachePath()) {
+    try {
+        const ctrl = new AbortController();
+        const timer = setTimeout(() => ctrl.abort(), 3000);
+        let latest;
+        try {
+            const res = await fetchFn(REGISTRY_DIST_TAGS_URL, { signal: ctrl.signal });
+            if (res.ok) {
+                const body = (await res.json());
+                latest = body.latest;
+            }
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (!latest)
+            return;
+        mkdirFn(dirname(path));
+        const cache = { checkedAt: new Date().toISOString(), latest };
+        writeFileFn(path, JSON.stringify(cache, null, 2) + "\n");
+    }
+    catch {
+        /* offline / registry unreachable — fail-silent, next invocation retries */
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "great-cto",
-  "version": "2.78.0",
+  "version": "2.79.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",