refacil-sdd-ai 5.3.1 → 5.3.3

package/bin/cli.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 'use strict';
 
@@ -441,6 +441,40 @@ function maybeInjectCodegraphSuggestion() {
   }
 }
 
+/** Throttle window for the global CodeGraph CLI upgrade check: once per 7 days. */
+const CODEGRAPH_UPGRADE_THROTTLE_MS = 7 * 24 * 60 * 60 * 1000;
+
+/**
+ * Upgrade the global codegraph CLI to the version floor when it is outdated,
+ * at most once per throttle window. Fire-and-forget (the upgrade itself runs in
+ * a detached background process). Stamps the marker BEFORE spawning so a slow or
+ * failed upgrade never retries on every session. Never throws.
+ */
+function maybeUpgradeCodegraph() {
+  try {
+    if (!codegraph.isOutdated()) return;
+    const markerDir = path.join(os.homedir(), '.refacil-sdd-ai');
+    const marker = path.join(markerDir, '.codegraph-upgrade-check');
+    let last = 0;
+    try {
+      const parsed = new Date(fs.readFileSync(marker, 'utf8').trim()).getTime();
+      if (!isNaN(parsed)) last = parsed;
+    } catch (_) {}
+    if (Date.now() - last < CODEGRAPH_UPGRADE_THROTTLE_MS) return; // checked recently
+    try {
+      fs.mkdirSync(markerDir, { recursive: true });
+      fs.writeFileSync(marker, new Date().toISOString());
+    } catch (_) {}
+    process.stdout.write(
+      `[refacil-sdd-ai] CodeGraph CLI is outdated (v${codegraph.installedVersion()} < ${codegraph.MIN_VERSION}) — ` +
+      'upgrading in background. Restart your session once it finishes.\n',
+    );
+    codegraph.upgrade({ background: true });
+  } catch (_) {
+    // Tolerant — never block session startup
+  }
+}
+
 function checkUpdate() {
   const root = resolveWorkspaceRoot();
 
@@ -596,18 +630,26 @@ function checkUpdate() {
           '[refacil-sdd-ai] CodeGraph is enabled but the CLI is not installed. ' +
           'Run /refacil:update to install and configure it.\n',
         );
-      } else if (!codegraph.isInitialized(root)) {
-        // Not indexed: start automatically in the background, no question needed
-        codegraph.init(root);
-        process.stdout.write('[refacil-sdd-ai] CodeGraph: building index in background (~30s).\n');
-      } else if (codegraph.isStale(root)) {
-        // Index exists but new commits since last init: refresh silently
-        codegraph.init(root);
-        process.stdout.write('[refacil-sdd-ai] CodeGraph: refreshing index (new commits detected).\n');
       } else {
-        // Initialized and up to date. If the timestamp file is absent (index was built
-        // externally, not through our tools), write it now so isStale() has a reference.
-        codegraph.touchTimestamp(root);
+        // Installed: keep the global CLI current. Throttled background upgrade so
+        // existing users move past the version floor without blocking session start.
+        maybeUpgradeCodegraph();
+        if (!codegraph.isInitialized(root)) {
+          // Not indexed: start automatically in the background, no question needed
+          codegraph.init(root);
+          process.stdout.write('[refacil-sdd-ai] CodeGraph: building index in background (~30s).\n');
+        } else if (!codegraph.hasAutoSync() && codegraph.isStale(root)) {
+          // Older codegraph without the daemon file watcher: new commits since
+          // last init → refresh silently ourselves. On WATCHER_VERSION and up the
+          // daemon auto-syncs + catches up on startup, so this branch is skipped
+          // to avoid a redundant double reindex.
+          codegraph.init(root);
+          process.stdout.write('[refacil-sdd-ai] CodeGraph: refreshing index (new commits detected).\n');
+        } else {
+          // Initialized and up to date. If the timestamp file is absent (index was built
+          // externally, not through our tools), write it now so isStale() has a reference.
+          codegraph.touchTimestamp(root);
+        }
       }
     }
   } catch (_) {
@@ -1371,12 +1413,20 @@ switch (command) {
       if (!codegraph.isInstalled()) {
         process.stdout.write('[refacil-sdd-ai] Installing @colbymchenry/codegraph globally...\n');
         try {
-          execSync('npm install -g @colbymchenry/codegraph', { stdio: 'inherit', timeout: 120000 });
+          execSync('npm install -g @colbymchenry/codegraph@latest', { stdio: 'inherit', timeout: 120000 });
           process.stdout.write('[refacil-sdd-ai] @colbymchenry/codegraph installed.\n');
         } catch (err) {
           process.stderr.write(`[refacil-sdd-ai] Failed to install codegraph: ${err.message}\n`);
           process.exit(1);
         }
+      } else if (codegraph.isOutdated()) {
+        // Existing global install is below the version floor — upgrade synchronously
+        // so the rest of setup runs against the new binary.
+        process.stdout.write(
+          `[refacil-sdd-ai] Upgrading @colbymchenry/codegraph (installed v${codegraph.installedVersion()} < ${codegraph.MIN_VERSION})...\n`,
+        );
+        codegraph.upgrade({ background: false });
+        process.stdout.write('[refacil-sdd-ai] @colbymchenry/codegraph upgraded.\n');
       }
       codegraph.registerMcp(selectedIDEs);
       if (!codegraph.isInitialized(projectRoot)) {

package/lib/codegraph.js

@@ -262,6 +262,138 @@ function touchTimestamp(repoPath) {
   } catch (_) {}
 }
 
+// ── Version floor + global upgrade ────────────────────────────────────────────
+
+/**
+ * Minimum codegraph CLI version we want users to run. Existing global installs
+ * below this floor are upgraded automatically (throttled) by checkUpdate, and
+ * synchronously by `codegraph setup`.
+ *
+ * 0.9.9 dropped the native better-sqlite3 build (which pulled the deprecated
+ * prebuild-install) in favour of prebuilt per-platform binaries.
+ */
+const MIN_VERSION = '0.9.9';
+
+/**
+ * Version at/above which the codegraph MCP daemon keeps the index fresh on its
+ * own across sessions, making our SessionStart stale-reindex redundant.
+ *
+ * The live file watcher (auto-sync while running) has existed since ~0.8.0, but
+ * that alone does NOT cover our case: isStale() fires on commits made WHILE the
+ * daemon/IDE was closed (a pull, a branch switch), which a live-only watcher
+ * misses. The capability that covers it is catch-up-on-connect — added in 0.9.5
+ * ("the MCP server now catches up on connect, reconciling anything that changed
+ * while it wasn't running"), shipped alongside the persistent per-project daemon.
+ * So 0.9.5 is the real floor. Below it (older installs not yet upgraded) we keep
+ * triggering `codegraph index` ourselves. See hasAutoSync.
+ */
+const WATCHER_VERSION = '0.9.5';
+
+/**
+ * Return the installed global codegraph version string (e.g. "0.9.9"), or null
+ * when codegraph is not installed or the version cannot be determined.
+ * Never throws.
+ * @returns {string|null}
+ */
+function installedVersion() {
+  try {
+    const { spawnSync } = require('child_process');
+    // shell: true is required on Windows where npm binaries are installed as .cmd files
+    const result = spawnSync('codegraph', ['--version'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 5000,
+      shell: true,
+    });
+    if (result.status !== 0 || !result.stdout) return null;
+    const match = result.stdout.trim().match(/\d+\.\d+\.\d+/);
+    return match ? match[0] : null;
+  } catch (_) {
+    return null;
+  }
+}
+
+/**
+ * Compare two dotted numeric versions. Returns true when `version` is strictly
+ * lower than `floor`. Malformed / non-numeric segments are treated as 0.
+ * Pure and total — never throws. Exported for testing.
+ * @param {string} version
+ * @param {string} floor
+ * @returns {boolean}
+ */
+function isVersionBelow(version, floor) {
+  const parse = (v) => String(v).split('.').map((n) => parseInt(n, 10) || 0);
+  const a = parse(version);
+  const b = parse(floor);
+  for (let i = 0; i < 3; i++) {
+    const x = a[i] || 0;
+    const y = b[i] || 0;
+    if (x < y) return true;
+    if (x > y) return false;
+  }
+  return false;
+}
+
+/**
+ * True when codegraph is installed but its version is below the floor.
+ * Returns false when not installed or the version cannot be parsed — callers
+ * handle the "missing" case separately, and an unknown version never triggers
+ * a disruptive upgrade.
+ * @param {string} [floor] - override the version floor (defaults to MIN_VERSION)
+ * @returns {boolean}
+ */
+function isOutdated(floor) {
+  const current = installedVersion();
+  if (!current) return false;
+  return isVersionBelow(current, floor || MIN_VERSION);
+}
+
+/**
+ * True when the installed codegraph's MCP daemon keeps the graph fresh on its
+ * own (file watcher + startup catch-up, WATCHER_VERSION and up) — in which case
+ * our SessionStart stale-reindex would just duplicate the daemon's work and
+ * should be skipped. Returns false for older versions (no watcher → keep doing
+ * the manual reindex) and when the version can't be determined (be conservative
+ * and keep the manual refresh). Never throws.
+ * @returns {boolean}
+ */
+function hasAutoSync() {
+  const current = installedVersion();
+  if (!current) return false; // unknown version → keep the manual refresh (safe)
+  return !isVersionBelow(current, WATCHER_VERSION);
+}
+
+/**
+ * Upgrade the global codegraph CLI to the latest published version.
+ * Never throws.
+ * @param {object} [opts]
+ * @param {boolean} [opts.background=true] - true: detached fire-and-forget (does not block);
+ *                                           false: synchronous with inherited stdio (used by setup).
+ */
+function upgrade(opts) {
+  const background = !opts || opts.background !== false;
+  try {
+    if (background) {
+      const { spawn } = require('child_process');
+      const child = spawn('npm install -g @colbymchenry/codegraph@latest', [], {
+        detached: true,
+        stdio: 'ignore',
+        shell: true,        // required for Windows .cmd binaries
+        windowsHide: true,  // suppress console window pop-ups on Windows
+      });
+      child.unref();
+    } else {
+      const { execSync } = require('child_process');
+      execSync('npm install -g @colbymchenry/codegraph@latest', {
+        stdio: 'inherit',
+        timeout: 120000,
+      });
+    }
+  } catch (_) {
+    // Swallow: upgrade is best-effort, must never break the caller
+  }
+}
+
 module.exports = {
   isInstalled,
   isInitialized,
@@ -270,4 +402,11 @@ module.exports = {
   touchTimestamp,
   mcpEntry,
   registerMcp,
+  MIN_VERSION,
+  WATCHER_VERSION,
+  installedVersion,
+  isVersionBelow,
+  isOutdated,
+  hasAutoSync,
+  upgrade,
 };

package/lib/spec-sync.js

@@ -98,7 +98,13 @@ function parseCriteriaBlocks(markdown) {
   };
 
   for (const line of lines) {
-    const m = line.match(/^##\s+((?:CA|CR)-\d+):\s*(.+)$/i);
+    // Tolerant heading match so archive's spec-sync never trips on cosmetic
+    // format variance the proposer/agents produce in the wild:
+    //   - heading level: h2 (## CA-01) OR h3+ (### CA-A01) — level is ignored
+    //   - criterion id: numeric (CA-01), feature-prefixed (CA-A01, CA-G01) or
+    //     suffixed (CA-12b) — any [A-Za-z0-9] run after the CA-/CR- prefix
+    // The CA-/CR- token is the real signal; the heading level and id shape are not.
+    const m = line.match(/^#{2,6}\s+((?:CA|CR)-[A-Za-z0-9]+):\s*(.+)$/i);
     if (m) {
       pushCurrent();
       current = { id: m[1].toUpperCase(), title: m[2].trim(), lines: [] };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "refacil-sdd-ai",
-  "version": "5.3.1",
+  "version": "5.3.3",
   "description": "SDD-AI: Specification-Driven Development with AI — development methodology using AI with Claude Code, Cursor, OpenCode and Codex",
   "bin": {
     "refacil-sdd-ai": "./bin/cli.js"
@@ -47,7 +47,6 @@
     "ws": "^8.18.0"
   },
   "optionalDependencies": {
-    "@clack/prompts": "^0.9.0",
-    "@colbymchenry/codegraph": "0.7.9"
+    "@clack/prompts": "^0.9.0"
   }
 }