refacil-sdd-ai 5.2.2 → 5.3.0

package/lib/codegraph-telemetry.js

@@ -0,0 +1,135 @@
+'use strict';
+
+/**
+ * CodeGraph telemetry — analogous to lib/compact/telemetry.js.
+ *
+ * Logs events to ~/.refacil-sdd-ai/codegraph.log (JSONL).
+ * Uses the same try/catch-silent pattern and ensureDir() approach
+ * as compact telemetry. Never throws to the caller.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const HOME_DIR = path.join(os.homedir(), '.refacil-sdd-ai');
+const LOG_PATH = path.join(HOME_DIR, 'codegraph.log');
+
+function ensureDir() {
+  try {
+    fs.mkdirSync(HOME_DIR, { recursive: true });
+  } catch (_) {}
+}
+
+/**
+ * Log a CodeGraph usage event.
+ * @param {string} skillId             — e.g. 'investigator' | 'proposer' | 'debugger'
+ * @param {boolean} hasGraph           — whether .codegraph/ was present in the repo
+ * @param {number}  toolCallsCount     — number of CodeGraph tool calls made this session
+ * @param {number}  estimatedTokensSaved — estimated tokens saved vs reading files directly
+ */
+function logEvent(skillId, hasGraph, toolCallsCount, estimatedTokensSaved) {
+  try {
+    ensureDir();
+    const line =
+      JSON.stringify({
+        ts: new Date().toISOString(),
+        skillId: skillId || 'unknown',
+        hasGraph: Boolean(hasGraph),
+        toolCallsCount: toolCallsCount || 0,
+        estimatedTokensSaved: estimatedTokensSaved || 0,
+      }) + '\n';
+    fs.appendFileSync(LOG_PATH, line);
+  } catch (_) {
+    // Telemetry must never break the caller
+  }
+}
+
+/**
+ * Read all log entries as an array of parsed objects.
+ * Returns [] if the log file does not exist or cannot be read.
+ * @returns {object[]}
+ */
+function readLog() {
+  try {
+    const content = fs.readFileSync(LOG_PATH, 'utf8');
+    return content
+      .split('\n')
+      .filter(Boolean)
+      .map((line) => {
+        try {
+          return JSON.parse(line);
+        } catch (_) {
+          return null;
+        }
+      })
+      .filter(Boolean);
+  } catch (_) {
+    return [];
+  }
+}
+
+/**
+ * Compute stats grouped by skillId, comparing with-graph vs without-graph.
+ * @returns {{
+ *   bySkill: Record<string, { withGraph: { events: number, toolCalls: number, tokensSaved: number }, withoutGraph: { events: number } }>,
+ *   totalEvents: number,
+ *   totalTokensSaved: number,
+ *   totalToolCalls: number
+ * }}
+ */
+function stats() {
+  const entries = readLog();
+  const bySkill = {};
+  let totalEvents = 0;
+  let totalTokensSaved = 0;
+  let totalToolCalls = 0;
+
+  for (const e of entries) {
+    const skillId = e.skillId || 'unknown';
+    if (!bySkill[skillId]) {
+      bySkill[skillId] = {
+        withGraph: { events: 0, toolCalls: 0, tokensSaved: 0 },
+        withoutGraph: { events: 0 },
+      };
+    }
+
+    if (e.hasGraph) {
+      bySkill[skillId].withGraph.events++;
+      bySkill[skillId].withGraph.toolCalls += e.toolCallsCount || 0;
+      bySkill[skillId].withGraph.tokensSaved += e.estimatedTokensSaved || 0;
+      totalToolCalls += e.toolCallsCount || 0;
+      totalTokensSaved += e.estimatedTokensSaved || 0;
+    } else {
+      bySkill[skillId].withoutGraph.events++;
+    }
+
+    totalEvents++;
+  }
+
+  return {
+    bySkill,
+    totalEvents,
+    totalTokensSaved,
+    totalToolCalls,
+  };
+}
+
+/**
+ * Delete the log file.
+ * Silent on errors (file may not exist).
+ */
+function clearLog() {
+  try {
+    fs.unlinkSync(LOG_PATH);
+  } catch (_) {}
+}
+
+module.exports = {
+  HOME_DIR,
+  LOG_PATH,
+  logEvent,
+  readLog,
+  stats,
+  clearLog,
+};

package/lib/codegraph.js

@@ -0,0 +1,273 @@
+'use strict';
+
+/**
+ * CodeGraph abstraction layer.
+ *
+ * Wraps @colbymchenry/codegraph as an optional dependency.
+ * Never throws to the caller — all errors are swallowed silently.
+ *
+ * IDE support matrix (MCP registration):
+ *   - Claude Code  : ~/.claude/settings.json          → mcpServers.codegraph
+ *   - Cursor       : ~/.cursor/mcp.json                → mcpServers.codegraph
+ *   - OpenCode     : <globalOpenCodeDir>/opencode.jsonc → mcp.codegraph
+ *   - Codex        : ~/.codex/config.toml              → mcp_servers.codegraph
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+/**
+ * Check whether @colbymchenry/codegraph is installed in the current Node.js resolution chain.
+ * @returns {boolean}
+ */
+function isInstalled() {
+  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,
+    });
+    return result.status === 0;
+  } catch (_) {
+    return false;
+  }
+}
+
+/**
+ * Check whether the given repo path has already been indexed by CodeGraph.
+ * A repo is considered indexed when a `.codegraph/` directory exists at its root.
+ * @param {string} repoPath - absolute path to the project root
+ * @returns {boolean}
+ */
+function isInitialized(repoPath) {
+  try {
+    return fs.existsSync(path.join(repoPath, '.codegraph'));
+  } catch (_) {
+    return false;
+  }
+}
+
+/** Timestamp file written inside .codegraph/ each time we trigger init. */
+const LAST_INIT_FILE = '.codegraph/.refacil-last-init';
+
+/**
+ * Spawn a background CodeGraph indexing process for the given repo.
+ * Uses the global `codegraph` CLI binary (shell: true for Windows .cmd support).
+ * Also writes a timestamp so isStale() can compare against git history.
+ * Fire-and-forget — returns immediately. Never throws.
+ * @param {string} repoPath - absolute path to the project root
+ */
+function init(repoPath) {
+  try {
+    const { spawn } = require('child_process');
+    // `codegraph init` creates .codegraph/ (structure only, 0 nodes).
+    // `codegraph index` builds the actual graph (must run after init).
+    // For first-time: chain both commands so the graph is built in one shot.
+    // For re-index:   only `codegraph index` (structure already exists).
+    const cgDir = path.join(repoPath, '.codegraph');
+    const isFirstTime = !fs.existsSync(cgDir);
+    // Use shell chaining (&&) so the second command only runs if the first succeeds.
+    const cmd = isFirstTime ? 'codegraph init && codegraph index' : 'codegraph index';
+    const child = spawn(cmd, [], {
+      detached: true,
+      stdio: 'ignore',
+      shell: true,        // required for && chaining and Windows .cmd binaries
+      windowsHide: true,  // suppress console window pop-ups on Windows
+      cwd: repoPath,
+    });
+    child.unref();
+    // Update the timestamp on re-index (.codegraph/ exists). For first-time,
+    // the directory does not exist yet so we skip — isStale() falls back to mtime.
+    if (!isFirstTime) {
+      fs.writeFileSync(path.join(cgDir, '.refacil-last-init'), new Date().toISOString());
+    }
+  } catch (_) {
+    // Swallow: CodeGraph not installed, spawn failed, or fs write failed
+  }
+}
+
+/**
+ * Return true when there are git commits newer than the last time we triggered
+ * `codegraph init` for this repo. Always returns false when git is unavailable,
+ * the repo has no commits, or any error occurs — never blocks, never throws.
+ * @param {string} repoPath - absolute path to the project root
+ * @returns {boolean}
+ */
+function isStale(repoPath) {
+  try {
+    // Determine the reference date: prefer our timestamp file, fall back to .codegraph/ mtime
+    let refDate;
+    const lastInitPath = path.join(repoPath, LAST_INIT_FILE);
+    if (fs.existsSync(lastInitPath)) {
+      const parsed = new Date(fs.readFileSync(lastInitPath, 'utf8').trim());
+      if (!isNaN(parsed.getTime())) refDate = parsed;
+    }
+    if (!refDate) {
+      const cgDir = path.join(repoPath, '.codegraph');
+      if (!fs.existsSync(cgDir)) return false;
+      refDate = fs.statSync(cgDir).mtime;
+    }
+
+    // Check for git commits after refDate — gracefully skip if no git
+    const { spawnSync } = require('child_process');
+    const result = spawnSync(
+      'git', ['-C', repoPath, 'log', '--oneline', `--after=${refDate.toISOString()}`, '-1'],
+      { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 3000 },
+    );
+    if (result.status !== 0 || result.error) return false; // no git or git error
+    return result.stdout.trim().length > 0;
+  } catch (_) {
+    return false;
+  }
+}
+
+/**
+ * Return the MCP tool hint string for the agent system prompt.
+ * All four IDEs support MCP, so this returns a non-null value for all of them
+ * when CodeGraph is installed.
+ * Returns null when CodeGraph is not installed or any error occurs.
+ *
+ * @param {string} ide - 'claude' | 'cursor' | 'opencode' | 'codex'
+ * @returns {string|null}
+ */
+function mcpEntry(ide) {
+  try {
+    if (!ide) return null;
+    if (!isInstalled()) return null;
+    return (
+      'CodeGraph MCP tools available: ' +
+      'codegraph_search, codegraph_callers, codegraph_callees, codegraph_context, codegraph_impact. ' +
+      'Use these BEFORE Grep or Read for symbol and call-graph queries when .codegraph/ is present.'
+    );
+  } catch (_) {
+    return null;
+  }
+}
+
+// ── MCP server registration ───────────────────────────────────────────────────
+
+const CODEGRAPH_MCP_KEY = 'codegraph';
+
+function _upsertMcpEntry(filePath, entry) {
+  let config = {};
+  try {
+    const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) config = parsed;
+  } catch (_) {}
+  if (!config.mcpServers) config.mcpServers = {};
+  if (config.mcpServers[CODEGRAPH_MCP_KEY]) return; // already registered — idempotent
+  config.mcpServers[CODEGRAPH_MCP_KEY] = entry;
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, JSON.stringify(config, null, 2) + '\n', 'utf8');
+}
+
+function _registerClaudeMcp(homeDir) {
+  const dir = path.join(homeDir, '.claude');
+  if (!fs.existsSync(dir)) return;
+  _upsertMcpEntry(path.join(dir, 'settings.json'), {
+    command: 'codegraph',
+    args: ['serve', '--mcp', '--path', '.'],
+  });
+}
+
+function _registerCursorMcp(homeDir) {
+  const dir = path.join(homeDir, '.cursor');
+  if (!fs.existsSync(dir)) return;
+  _upsertMcpEntry(path.join(dir, 'mcp.json'), {
+    type: 'stdio',
+    command: 'codegraph',
+    args: ['serve', '--mcp', '--path', '${workspaceFolder}'],
+  });
+}
+
+function _registerOpenCodeMcp(homeDir) {
+  const { globalOpenCodeDir } = require('./global-paths');
+  const openCodeDir = globalOpenCodeDir(homeDir);
+  fs.mkdirSync(openCodeDir, { recursive: true });
+  const configPath = path.join(openCodeDir, 'opencode.jsonc');
+  let config = { $schema: 'https://opencode.ai/config.json' };
+  try {
+    const raw = fs.readFileSync(configPath, 'utf8').replace(/\/\/[^\n]*/g, '');
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === 'object') config = parsed;
+  } catch (_) {}
+  if (!config.mcp) config.mcp = {};
+  if (config.mcp[CODEGRAPH_MCP_KEY]) return;
+  config.mcp[CODEGRAPH_MCP_KEY] = { type: 'local', command: ['codegraph', 'serve', '--mcp'], enabled: true };
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n', 'utf8');
+}
+
+function _registerCodexMcp(homeDir) {
+  const codexDir = path.join(homeDir, '.codex');
+  if (!fs.existsSync(codexDir)) return;
+  const configPath = path.join(codexDir, 'config.toml');
+  const smolToml = require('smol-toml');
+  let config = {};
+  try {
+    config = smolToml.parse(fs.readFileSync(configPath, 'utf8'));
+  } catch (_) {}
+  if (!config.mcp_servers) config.mcp_servers = {};
+  if (config.mcp_servers[CODEGRAPH_MCP_KEY]) return;
+  config.mcp_servers[CODEGRAPH_MCP_KEY] = { command: 'codegraph', args: ['serve', '--mcp'] };
+  fs.writeFileSync(configPath, smolToml.stringify(config), 'utf8');
+}
+
+/**
+ * Register the CodeGraph MCP server entry in each selected IDE's config file.
+ * Idempotent — no-ops if the entry already exists or the IDE dir is absent. Never throws.
+ *
+ * Accepts both dot-prefixed (.claude) and plain (claude) IDE names — both formats are normalized.
+ *
+ * IDE → file:
+ *   claude   → ~/.claude/settings.json           (mcpServers.codegraph)
+ *   cursor   → ~/.cursor/mcp.json                (mcpServers.codegraph)
+ *   opencode → <globalOpenCodeDir>/opencode.jsonc  (mcp.codegraph)
+ *   codex    → ~/.codex/config.toml              (mcp_servers.codegraph)
+ *
+ * @param {string[]} selectedIDEs - e.g. ['.claude','.cursor'] or ['claude','cursor']
+ * @param {string} [homeDir] - injectable for testing
+ */
+function registerMcp(selectedIDEs, homeDir) {
+  const resolvedHome = homeDir || os.homedir();
+  const ides = Array.isArray(selectedIDEs) ? selectedIDEs : [];
+  for (const ide of ides) {
+    try {
+      const name = ide.startsWith('.') ? ide.slice(1) : ide;
+      if (name === 'claude') _registerClaudeMcp(resolvedHome);
+      else if (name === 'cursor') _registerCursorMcp(resolvedHome);
+      else if (name === 'opencode') _registerOpenCodeMcp(resolvedHome);
+      else if (name === 'codex') _registerCodexMcp(resolvedHome);
+    } catch (_) {}
+  }
+}
+
+/**
+ * Write the .refacil-last-init timestamp into an existing .codegraph/ directory.
+ * No-op when .codegraph/ does not exist. Used by checkUpdate to stamp indexes
+ * that were built externally (not through our setup/init commands).
+ * @param {string} repoPath
+ */
+function touchTimestamp(repoPath) {
+  try {
+    const cgDir = path.join(repoPath, '.codegraph');
+    if (!fs.existsSync(cgDir)) return;
+    const tsFile = path.join(cgDir, '.refacil-last-init');
+    if (!fs.existsSync(tsFile)) {
+      fs.writeFileSync(tsFile, new Date().toISOString());
+    }
+  } catch (_) {}
+}
+
+module.exports = {
+  isInstalled,
+  isInitialized,
+  isStale,
+  init,
+  touchTimestamp,
+  mcpEntry,
+  registerMcp,
+};

package/lib/commands/autopilot.js

@@ -0,0 +1,120 @@
+'use strict';
+
+// Recognized IDE identifiers. Only 'cursor' gets a dedicated message path;
+// all other values (including 'unknown') fall to the generic A/B options block.
+const SUPPORTED_IDES = new Set(['cursor', 'claude-code', 'codex', 'opencode', 'unknown']);
+
+function getFlag(argv, flag, fallback) {
+  const idx = argv.indexOf(flag);
+  return idx !== -1 && argv[idx + 1] !== undefined ? argv[idx + 1] : fallback;
+}
+
+function normalizeIde(raw) {
+  if (!raw) return 'unknown';
+  const lower = raw.toLowerCase();
+  return SUPPORTED_IDES.has(lower) ? lower : 'unknown';
+}
+
+/**
+ * Shared message builder. Receives a localized strings object so both language
+ * variants (ES / EN) share the same structural logic — only the copy differs.
+ *
+ * @param {string} changeName
+ * @param {string} ide
+ * @param {{ header: string, ideLabel: string, phases: string, cursorLines: string[], genericLines: string[] }} strings
+ * @returns {string}
+ */
+function buildReadyMessage(changeName, ide, strings) {
+  const lines = [
+    strings.header,
+    `Change: ${changeName}`,
+    `${strings.ideLabel}: ${ide}`,
+    ``,
+    strings.phases,
+    ``,
+  ];
+
+  if (ide === 'cursor') {
+    lines.push(...strings.cursorLines);
+  } else {
+    lines.push(...strings.genericLines);
+  }
+
+  return lines.join('\n');
+}
+
+function buildReadyMessageEs(changeName, ide) {
+  return buildReadyMessage(changeName, ide, {
+    header: `Autopilot listo para arrancar`,
+    ideLabel: `IDE detectado`,
+    phases: `Fases: apply → test → verify → review → archive → up-code`,
+    cursorLines: [
+      `Para continuar en esta sesión, responde con una afirmación explícita:`,
+      `  go · ok · start · sí · dale · arrancar`,
+      ``,
+      `Hasta que no respondas así, no inicio el pipeline.`,
+    ],
+    genericLines: [
+      `Opciones:`,
+      `  A) Ejecutar aquí (pueden aparecer prompts de permisos durante el pipeline)`,
+      `     → responde "go" / "ok" / "start" para iniciar en esta sesión.`,
+      ``,
+      `  B) Ejecutar headless (sin interrupciones, salida visible en nueva terminal)`,
+      `     → cierra esta sesión y abre el IDE con el flag de auto-permisos adecuado,`,
+      `       luego escribe /refacil:autopilot.`,
+    ],
+  });
+}
+
+function buildReadyMessageEn(changeName, ide) {
+  return buildReadyMessage(changeName, ide, {
+    header: `Autopilot ready to start`,
+    ideLabel: `Detected IDE`,
+    phases: `Phases: apply → test → verify → review → archive → up-code`,
+    cursorLines: [
+      `To continue in this session, reply with an explicit affirmative:`,
+      `  go · ok · start · yes · dale`,
+      ``,
+      `The pipeline will not start until you reply.`,
+    ],
+    genericLines: [
+      `Options:`,
+      `  A) Run here (Bash permission prompts may appear during the pipeline)`,
+      `     → reply "go" / "ok" / "start" to begin in this session.`,
+      ``,
+      `  B) Run headless (no interruptions, output visible in a new terminal)`,
+      `     → close this session and open the IDE with the appropriate auto-permissions flag,`,
+      `       then type /refacil:autopilot.`,
+    ],
+  });
+}
+
+function handleAutopilot(sub, argv) {
+  if (sub === 'ready-message') {
+    const changeName = getFlag(argv, '--change', '');
+    const idRaw = getFlag(argv, '--ide', '');
+    const lang = getFlag(argv, '--lang', 'es');
+    const ide = normalizeIde(idRaw);
+
+    if (!changeName) {
+      process.stderr.write('  Error: --change <changeName> is required\n');
+      process.exit(1);
+    }
+
+    let message;
+    if (lang === 'en') {
+      message = buildReadyMessageEn(changeName, ide);
+    } else {
+      message = buildReadyMessageEs(changeName, ide);
+    }
+
+    process.stdout.write(message + '\n');
+  } else {
+    process.stderr.write(
+      `  Unknown autopilot subcommand: ${sub || '(none)'}. Usage: autopilot <ready-message>\n`,
+    );
+    process.exit(1);
+  }
+}
+
+module.exports = { handleAutopilot };

package/lib/commands/bus.js

@@ -8,6 +8,7 @@ const busClient = require('../bus/client');
 const busWatch = require('../bus/watch');
 const busPresenter = require('../bus/presenter');
 const { askHasMatchingReply } = require('../bus/askFulfillment');
+const { openInBrowser } = require('../open-browser');
 
 function parseBusArgs(argv) {
   const args = {};
@@ -155,13 +156,32 @@ async function busLeave(args, packageRoot) {
   }
 }
 
-async function busSay(args, packageRoot) {
-  const session = args.session || defaultSessionName();
-  const text = args.text;
-  if (!text) {
-    console.error('  Uso: refacil-sdd-ai bus say --text "..." [--session <s>]');
+function resolveText(args, usageHint) {
+  const hasText = args.text !== undefined;
+  const hasFromEnv = args['from-env'] !== undefined;
+  if (hasText && hasFromEnv) {
+    console.error('  Error: --text and --from-env are mutually exclusive. Use one or the other.');
+    process.exit(1);
+  }
+  if (hasFromEnv) {
+    const varName = args['from-env'];
+    const value = process.env[varName];
+    if (!value) {
+      console.error(`  Error: environment variable "${varName}" is not set or is empty.`);
+      process.exit(1);
+    }
+    return value;
+  }
+  if (!hasText) {
+    console.error(`  ${usageHint}`);
     process.exit(1);
   }
+  return args.text;
+}
+
+async function busSay(args, packageRoot) {
+  const session = args.session || defaultSessionName();
+  const text = resolveText(args, 'Uso: refacil-sdd-ai bus say --text "..." | --from-env VAR [--session <s>]');
   const { ws } = await connectOrDie(packageRoot);
   const reply = await busClient.sendAndWait(
     ws,
@@ -183,12 +203,12 @@ async function busSay(args, packageRoot) {
 async function busAsk(args, packageRoot) {
   const session = args.session || defaultSessionName();
   const to = args.to;
-  const text = args.text;
   const waitSec = args.wait ? parseInt(args.wait, 10) : 0;
-  if (!to || !text) {
-    console.error('  Uso: refacil-sdd-ai bus ask --to <name|all> --text "..." [--wait N] [--session <s>]');
+  if (!to) {
+    console.error('  Uso: refacil-sdd-ai bus ask --to <name|all> --text "..." | --from-env VAR [--wait N] [--session <s>]');
     process.exit(1);
   }
+  const text = resolveText(args, 'Uso: refacil-sdd-ai bus ask --to <name|all> --text "..." | --from-env VAR [--wait N] [--session <s>]');
   const { ws } = await connectOrDie(packageRoot);
   const ack = await busClient.sendAndWait(
     ws,
@@ -232,13 +252,9 @@ async function busAsk(args, packageRoot) {
 
 async function busReply(args, packageRoot) {
   const session = args.session || defaultSessionName();
-  const text = args.text;
   const correlationId = args.correlation || null;
   const to = args.to ? args.to.replace(/^@/, '') : null;
-  if (!text) {
-    console.error('  Uso: refacil-sdd-ai bus reply --text "..." [--to <name>] [--correlation <id>]');
-    process.exit(1);
-  }
+  const text = resolveText(args, 'Uso: refacil-sdd-ai bus reply --text "..." | --from-env VAR [--to <name>] [--correlation <id>]');
   const { ws } = await connectOrDie(packageRoot);
   const reply = await busClient.sendAndWait(
     ws,
@@ -432,29 +448,6 @@ async function busRooms(packageRoot) {
   }
 }
 
-function openInBrowser(url) {
-  const { spawn } = require('child_process');
-  const platform = process.platform;
-  let cmd;
-  let cmdArgs;
-  if (platform === 'win32') {
-    cmd = 'cmd';
-    cmdArgs = ['/c', 'start', '""', url];
-  } else if (platform === 'darwin') {
-    cmd = 'open';
-    cmdArgs = [url];
-  } else {
-    cmd = 'xdg-open';
-    cmdArgs = [url];
-  }
-  try {
-    spawn(cmd, cmdArgs, { detached: true, stdio: 'ignore', windowsHide: true }).unref();
-    return true;
-  } catch (_) {
-    return false;
-  }
-}
-
 async function busView(packageRoot) {
   try {
     const { info } = await busSpawn.ensureBroker(packageRoot);