refacil-sdd-ai 5.2.2 → 5.3.0

package/lib/compact-guidance.js

@@ -1,77 +1,122 @@
-const fs = require('fs');
-const path = require('path');
-
-const MARKER_START = '<!-- refacil-sdd-ai:compact-guidance:start -->';
-const MARKER_END = '<!-- refacil-sdd-ai:compact-guidance:end -->';
-
-function readTemplate(packageRoot) {
-  const tplPath = path.join(packageRoot, 'templates', 'compact-guidance.md');
-  return fs.readFileSync(tplPath, 'utf8').trimEnd();
-}
-
-function buildBlock(templateContent) {
-  return `${MARKER_START}\n${templateContent}\n${MARKER_END}`;
-}
-
-function syncCompactGuidance(projectRoot, packageRoot) {
-  const agentsPath = path.join(projectRoot, 'AGENTS.md');
-  if (!fs.existsSync(agentsPath)) {
-    return { status: 'skipped-no-agents-md' };
-  }
-
-  const template = readTemplate(packageRoot);
-  const block = buildBlock(template);
-  const existing = fs.readFileSync(agentsPath, 'utf8');
-
-  const startIdx = existing.indexOf(MARKER_START);
-  const endIdx = existing.indexOf(MARKER_END);
-
-  let next;
-  let action;
-
-  if (startIdx === -1 || endIdx === -1) {
-    next = existing.trimEnd() + '\n\n' + block + '\n';
-    action = 'appended';
-  } else {
-    const before = existing.substring(0, startIdx);
-    const after = existing.substring(endIdx + MARKER_END.length);
-    next = before + block + after;
-    action = 'replaced';
-  }
-
-  if (next === existing) {
-    return { status: 'unchanged' };
-  }
-
-  fs.writeFileSync(agentsPath, next);
-  return { status: action };
-}
-
-function removeCompactGuidance(projectRoot) {
-  const agentsPath = path.join(projectRoot, 'AGENTS.md');
-  if (!fs.existsSync(agentsPath)) {
-    return { status: 'skipped-no-agents-md' };
-  }
-
-  const existing = fs.readFileSync(agentsPath, 'utf8');
-  const startIdx = existing.indexOf(MARKER_START);
-  const endIdx = existing.indexOf(MARKER_END);
-
-  if (startIdx === -1 || endIdx === -1) {
-    return { status: 'not-present' };
-  }
-
-  const before = existing.substring(0, startIdx).trimEnd();
-  const after = existing.substring(endIdx + MARKER_END.length);
-  const next = (before + '\n' + after.replace(/^\s+/, '')).trimEnd() + '\n';
-
-  fs.writeFileSync(agentsPath, next);
-  return { status: 'removed' };
-}
-
-module.exports = {
-  syncCompactGuidance,
-  removeCompactGuidance,
-  MARKER_START,
-  MARKER_END,
-};
+const fs = require('fs');
+const path = require('path');
+
+const MARKER_START = '<!-- refacil-sdd-ai:compact-guidance:start -->';
+const MARKER_END = '<!-- refacil-sdd-ai:compact-guidance:end -->';
+const LEGACY_MARKER_START = '<!-- compact-guidance:start -->';
+const LEGACY_MARKER_END = '<!-- compact-guidance:end -->';
+
+/**
+ * Removes obsolete empty placeholder pair (pre-refacil-sdd-ai naming).
+ * Preserves the block if non-whitespace content exists between legacy markers.
+ */
+function stripLegacyCompactGuidanceMarkers(content) {
+  const startIdx = content.indexOf(LEGACY_MARKER_START);
+  if (startIdx === -1) return content;
+
+  const endIdx = content.indexOf(LEGACY_MARKER_END, startIdx + LEGACY_MARKER_START.length);
+  if (endIdx === -1) return content;
+
+  const inner = content.substring(startIdx + LEGACY_MARKER_START.length, endIdx);
+  if (inner.trim() !== '') return content;
+
+  const before = content.substring(0, startIdx).trimEnd();
+  const after = content.substring(endIdx + LEGACY_MARKER_END.length).replace(/^\s+/, '');
+  if (!before) return after.trimStart();
+  if (!after) return `${before}\n`;
+  return `${before}\n\n${after}`;
+}
+
+function readTemplate(packageRoot) {
+  const tplPath = path.join(packageRoot, 'templates', 'compact-guidance.md');
+  return fs.readFileSync(tplPath, 'utf8').trimEnd();
+}
+
+function buildBlock(templateContent) {
+  return `${MARKER_START}\n${templateContent}\n${MARKER_END}`;
+}
+
+/** Normalize line endings for idempotent compare (CA-02 / Windows CRLF). */
+function normalizeEol(text) {
+  return text.replace(/\r\n/g, '\n');
+}
+
+function contentUnchanged(next, raw) {
+  const a = normalizeEol(next).trimEnd() + '\n';
+  const b = normalizeEol(raw).trimEnd() + '\n';
+  return a === b;
+}
+
+function syncCompactGuidance(projectRoot, packageRoot) {
+  const agentsPath = path.join(projectRoot, 'AGENTS.md');
+  if (!fs.existsSync(agentsPath)) {
+    return { status: 'skipped-no-agents-md' };
+  }
+
+  const template = readTemplate(packageRoot);
+  const block = buildBlock(template);
+  const raw = fs.readFileSync(agentsPath, 'utf8');
+  const existing = stripLegacyCompactGuidanceMarkers(raw);
+
+  const startIdx = existing.indexOf(MARKER_START);
+  const endIdx = existing.indexOf(MARKER_END);
+
+  let next;
+  let action;
+
+  if (startIdx === -1 || endIdx === -1) {
+    next = existing.trimEnd() + '\n\n' + block + '\n';
+    action = 'appended';
+  } else {
+    const before = existing.substring(0, startIdx);
+    const after = existing.substring(endIdx + MARKER_END.length);
+    next = before + block + after;
+    action = 'replaced';
+  }
+
+  const normalized = next.trimEnd() + '\n';
+  if (contentUnchanged(normalized, raw)) {
+    return { status: 'unchanged' };
+  }
+
+  fs.writeFileSync(agentsPath, normalized);
+  return { status: action };
+}
+
+function removeCompactGuidance(projectRoot) {
+  const agentsPath = path.join(projectRoot, 'AGENTS.md');
+  if (!fs.existsSync(agentsPath)) {
+    return { status: 'skipped-no-agents-md' };
+  }
+
+  const raw = fs.readFileSync(agentsPath, 'utf8');
+  const existing = stripLegacyCompactGuidanceMarkers(raw);
+  const startIdx = existing.indexOf(MARKER_START);
+  const endIdx = existing.indexOf(MARKER_END);
+
+  if (startIdx === -1 || endIdx === -1) {
+    const legacyOnly = stripLegacyCompactGuidanceMarkers(raw);
+    if (legacyOnly !== raw) {
+      fs.writeFileSync(agentsPath, legacyOnly.trimEnd() + '\n');
+      return { status: 'legacy-removed' };
+    }
+    return { status: 'not-present' };
+  }
+
+  const before = existing.substring(0, startIdx).trimEnd();
+  const after = existing.substring(endIdx + MARKER_END.length);
+  const next = (before + '\n' + after.replace(/^\s+/, '')).trimEnd() + '\n';
+
+  fs.writeFileSync(agentsPath, next);
+  return { status: 'removed' };
+}
+
+module.exports = {
+  syncCompactGuidance,
+  removeCompactGuidance,
+  stripLegacyCompactGuidanceMarkers,
+  MARKER_START,
+  MARKER_END,
+  LEGACY_MARKER_START,
+  LEGACY_MARKER_END,
+};

package/lib/config.js

@@ -4,6 +4,9 @@ const fs = require('fs');
 const path = require('path');
 const os = require('os');
 
+const CODEGRAPH_MODES = ['enabled', 'per-repo', 'disabled'];
+const DEFAULT_CODEGRAPH_MODE = 'enabled';
+
 const DEFAULT_PROTECTED_BRANCHES = ['master', 'main', 'develop', 'dev', 'testing', 'qa'];
 const DEFAULT_BASE_BRANCH = 'develop';
 const SUPPORTED_LANGUAGES = ['english', 'spanish'];
@@ -236,14 +239,38 @@ function loadBranchConfigWithSources(projectRoot) {
     artifactLanguageSource = 'default';
   }
 
+  // --- codegraphMode ---
+  let codegraphMode = null;
+  let codegraphModeSource = 'default';
+
+  if (projectCfg !== null) {
+    const val = extractCodegraphMode(projectCfg, 'project');
+    if (val !== null) {
+      codegraphMode = val;
+      codegraphModeSource = 'project';
+    }
+  }
+
+  if (codegraphMode === null && globalCfg !== null) {
+    const val = extractCodegraphMode(globalCfg, 'global');
+    if (val !== null) {
+      codegraphMode = val;
+      codegraphModeSource = 'global';
+    }
+  }
+
+  // codegraphMode has no default — null means "no preference yet" (suggestion not yet answered)
+
   return {
     protectedBranches,
     baseBranch,
     artifactLanguage,
+    codegraphMode,
     sources: {
       protectedBranches: protectedBranchesSource,
       baseBranch: baseBranchSource,
       artifactLanguage: artifactLanguageSource,
+      codegraphMode: codegraphModeSource,
     },
   };
 }
@@ -260,14 +287,123 @@ function loadBranchConfig(projectRoot) {
   return { protectedBranches, baseBranch, artifactLanguage };
 }
 
+/**
+ * Validate `codegraphMode` from a parsed config object.
+ * Valid values: 'enabled' | 'per-repo' | 'disabled'. Default: 'enabled'.
+ * Returns the value if valid, or null + emits a warning if invalid.
+ * @param {object} cfg  — parsed YAML object
+ * @param {string} src  — source label for the warning ('project' | 'global')
+ * @returns {string|null}
+ */
+function extractCodegraphMode(cfg, src) {
+  if (!('codegraphMode' in cfg)) return null;
+  const val = cfg.codegraphMode;
+  if (typeof val !== 'string' || val.trim() === '') {
+    process.stderr.write(
+      `[refacil-sdd-ai] warning: codegraphMode in ${src} config must be a non-empty string — ignoring.\n`,
+    );
+    return null;
+  }
+  const trimmed = val.trim();
+  if (!CODEGRAPH_MODES.includes(trimmed)) {
+    process.stderr.write(
+      `[refacil-sdd-ai] warning: codegraphMode "${trimmed}" in ${src} config is not a valid value (${CODEGRAPH_MODES.join(', ')}) — ignoring.\n`,
+    );
+    return null;
+  }
+  return trimmed;
+}
+
+/**
+ * Read CodeGraph suggestion UI state from a parsed config object.
+ * Keys read: codegraph-suggest-shown (boolean), codegraph-suggest-snooze (ISO date string).
+ * Returns { shown: bool|null, snoozeUntil: string|null }.
+ * Never warns — these are internal state keys that may simply be absent.
+ * @param {object} cfg  — parsed YAML object
+ * @param {string} _src — source label (unused, kept for API consistency)
+ * @returns {{ shown: boolean|null, snoozeUntil: string|null }}
+ */
+function extractCodegraphSuggestState(cfg, _src) {
+  let shown = null;
+  let snoozeUntil = null;
+
+  if ('codegraph-suggest-shown' in cfg) {
+    const raw = cfg['codegraph-suggest-shown'];
+    if (raw === 'true' || raw === true) shown = true;
+    else if (raw === 'false' || raw === false) shown = false;
+  }
+
+  if ('codegraph-suggest-snooze' in cfg) {
+    const raw = cfg['codegraph-suggest-snooze'];
+    if (typeof raw === 'string' && raw.trim() !== '') {
+      snoozeUntil = raw.trim();
+    }
+  }
+
+  return { shown, snoozeUntil };
+}
+
+/**
+ * Write (set or update) a single flat key:value pair in a YAML config file.
+ * Uses the same minimal YAML format as the existing parser — only flat key:value scalars.
+ * If the key already exists, its line is replaced in-place (preserving other lines).
+ * If the key does not exist, it is appended.
+ * Creates the file and parent directories if they do not exist.
+ * Never throws — all errors are swallowed silently.
+ *
+ * @param {string} key      — config key (e.g. 'codegraphMode')
+ * @param {string} value    — scalar string value to set
+ * @param {string} homeDir  — path to the user home directory (e.g. os.homedir())
+ */
+function writeConfigValue(key, value, homeDir) {
+  try {
+    const globalConfigPath = path.join(homeDir || os.homedir(), '.refacil-sdd-ai', 'config.yaml');
+    fs.mkdirSync(path.dirname(globalConfigPath), { recursive: true });
+
+    let lines = [];
+    if (fs.existsSync(globalConfigPath)) {
+      lines = fs.readFileSync(globalConfigPath, 'utf8').split('\n');
+    }
+
+    // Determine if key already exists (match "key:" or "key: value" at line start)
+    const keyPattern = new RegExp(`^${key.replace(/[-]/g, '\\$&')}:`);
+    let found = false;
+    const updated = lines.map((line) => {
+      if (keyPattern.test(line)) {
+        found = true;
+        return `${key}: ${value}`;
+      }
+      return line;
+    });
+
+    if (!found) {
+      // Remove trailing empty line before appending to avoid double blank lines
+      while (updated.length > 0 && updated[updated.length - 1].trim() === '') {
+        updated.pop();
+      }
+      updated.push(`${key}: ${value}`);
+      updated.push('');
+    }
+
+    fs.writeFileSync(globalConfigPath, updated.join('\n'));
+  } catch (_) {
+    // Silently swallow — config writes must never break caller flow
+  }
+}
+
 module.exports = {
   parseYaml,
   readConfigFile,
   loadBranchConfig,
   loadBranchConfigWithSources,
   extractArtifactLanguage,
+  extractCodegraphMode,
+  extractCodegraphSuggestState,
+  writeConfigValue,
   DEFAULT_PROTECTED_BRANCHES,
   DEFAULT_BASE_BRANCH,
   SUPPORTED_LANGUAGES,
   DEFAULT_ARTIFACT_LANGUAGE,
+  CODEGRAPH_MODES,
+  DEFAULT_CODEGRAPH_MODE,
 };

package/lib/global-paths.js

@@ -25,38 +25,72 @@ function globalCursorDir(homeDir) {
 }
 
 /**
- * Returns the global OpenCode user directory.
- * Production paths:
- *   Windows: %APPDATA%\opencode (falls back to ~/AppData/Roaming/opencode)
- *   macOS/Linux: ~/.config/opencode
+ * Returns legacy OpenCode config directories that may contain pre-migration artifacts.
+ * @param {string} [homeDir] - injectable for testing (default: os.homedir())
+ * @returns {string[]}
+ */
+function legacyOpenCodeDirs(homeDir) {
+  const resolvedHome = homeDir || os.homedir();
+  const dirs = [path.join(resolvedHome, '.opencode')];
+  if (process.platform === 'win32') {
+    const appData = process.env.APPDATA || path.join(resolvedHome, 'AppData', 'Roaming');
+    dirs.push(path.join(appData, 'opencode'));
+  }
+  return dirs;
+}
+
+/**
+ * Returns the global OpenCode user directory (official upstream path).
+ * Production:
+ *   - OPENCODE_CONFIG_DIR when set (absolute)
+ *   - Otherwise ~/.config/opencode on all platforms (Windows: %USERPROFILE%\.config\opencode)
  * Test injection:
- *   When appDataDir is explicitly provided, uses appDataDir\opencode (Windows-style).
- *   When only homeDir is explicitly provided (no appDataDir), uses homeDir/.opencode
- *   for cross-platform test portability.
+ *   When homeDir is explicitly provided, returns homeDir/.config/opencode.
  * @param {string} [homeDir] - injectable for testing (default: os.homedir())
- * @param {string} [appDataDir] - injectable Windows APPDATA dir for testing
  * @returns {string}
  */
-function globalOpenCodeDir(homeDir, appDataDir) {
-  // When appDataDir is explicitly provided, always use appDataDir\opencode
-  if (appDataDir) {
-    return path.join(appDataDir, 'opencode');
+function globalOpenCodeDir(homeDir) {
+  const envDir = process.env.OPENCODE_CONFIG_DIR;
+  if (envDir && String(envDir).trim()) {
+    return path.resolve(envDir.trim());
   }
 
-  // When homeDir is explicitly provided (test injection without appDataDir),
-  // always use homeDir/.opencode for cross-platform test portability
   if (homeDir) {
-    return path.join(homeDir, '.opencode');
+    return path.join(homeDir, '.config', 'opencode');
   }
 
-  // Production default (no injection)
-  if (process.platform === 'win32') {
-    const appData = process.env.APPDATA || path.join(os.homedir(), 'AppData', 'Roaming');
-    return path.join(appData, 'opencode');
-  }
   return path.join(os.homedir(), '.config', 'opencode');
 }
 
+/**
+ * When OPENCODE_CONFIG_DIR is set, verify the directory exists and is writable.
+ * Emits a clear stderr message on failure. No-op when the env var is unset.
+ * @returns {boolean} true when OpenCode global installs may proceed
+ */
+function validateOpenCodeConfigDir() {
+  const envDir = process.env.OPENCODE_CONFIG_DIR;
+  if (!envDir || !String(envDir).trim()) return true;
+
+  const dir = path.resolve(envDir.trim());
+  if (!fs.existsSync(dir)) {
+    process.stderr.write(
+      `[refacil-sdd-ai] OPENCODE_CONFIG_DIR is not accessible: directory does not exist: ${dir}\n`,
+    );
+    return false;
+  }
+
+  try {
+    fs.accessSync(dir, fs.constants.W_OK);
+  } catch (err) {
+    process.stderr.write(
+      `[refacil-sdd-ai] OPENCODE_CONFIG_DIR is not writable: ${dir} (${err.message})\n`,
+    );
+    return false;
+  }
+
+  return true;
+}
+
 /**
  * Returns the global Codex CLI user directory.
  * Always ~/.codex regardless of OS.
@@ -118,6 +152,8 @@ module.exports = {
   globalClaudeDir,
   globalCursorDir,
   globalOpenCodeDir,
+  validateOpenCodeConfigDir,
+  legacyOpenCodeDirs,
   globalCodexDir,
   globalSddVersionPath,
   globalSelectedIDEsPath,

package/lib/hooks.js

@@ -54,6 +54,14 @@ function installCursorHooks(homeDir, projectRoot) {
     command: 'refacil-sdd-ai check-update',
   });
 
+  // Remove legacy workspaceOpen check-update (duplicated sessionStart → double CodeGraph index).
+  if (config.hooks.workspaceOpen) {
+    const before = config.hooks.workspaceOpen.length;
+    config.hooks.workspaceOpen = config.hooks.workspaceOpen.filter((h) => h._sdd_workspace !== true);
+    if (config.hooks.workspaceOpen.length !== before) changed = true;
+    if (config.hooks.workspaceOpen.length === 0) delete config.hooks.workspaceOpen;
+  }
+
   // compact-bash must be BEFORE check-review
   if (!config.hooks.preToolUse) config.hooks.preToolUse = [];
   if (!config.hooks.preToolUse.some((h) => h._sdd_compact === true)) {
@@ -96,7 +104,7 @@ function uninstallCursorHooks(homeDir, projectRoot) {
     try { config = JSON.parse(fs.readFileSync(hooksJsonPath, 'utf8')); } catch (_) { config = null; }
 
     if (config && config.hooks) {
-      const sddMarkers = ['_sdd', '_sdd_compact', '_sdd_review', '_sdd_notify'];
+      const sddMarkers = ['_sdd', '_sdd_workspace', '_sdd_compact', '_sdd_review', '_sdd_notify'];
       for (const event of Object.keys(config.hooks)) {
         if (!Array.isArray(config.hooks[event])) continue;
         const before = config.hooks[event].length;
@@ -249,7 +257,7 @@ function uninstallClaudeHooks(homeDir) {
 // ── Limpieza de hooks SDD en settings.json (migracion legacy) ───────────────
 
 function cleanLegacySettingsHooks(projectRoot) {
-  const sddMarkers = ['_sdd', '_sdd_compact', '_sdd_review', '_sdd_notify'];
+  const sddMarkers = ['_sdd', '_sdd_workspace', '_sdd_compact', '_sdd_review', '_sdd_notify'];
   const evts = ['SessionStart', 'PreToolUse', 'UserPromptSubmit', 'beforeSubmitPrompt', 'Stop', 'afterAgentResponse'];
 
   for (const ideDir of ['.cursor']) {
@@ -289,9 +297,17 @@ function installOpenCodePlugin(homeDir) {
 
   const srcPlugin = path.join(__dirname, 'opencode-plugin', 'index.js');
   const destPlugin = path.join(pluginsDir, 'refacil-hooks.js');
+  const srcCheckReview = path.join(__dirname, 'check-review.js');
+  const destCheckReview = path.join(pluginsDir, 'refacil-check-review.js');
+  const srcRules = path.join(__dirname, 'opencode-plugin', 'rules.js');
+  const destRules = path.join(pluginsDir, 'rules.js');
 
   try {
     fs.copyFileSync(srcPlugin, destPlugin);
+    fs.copyFileSync(srcCheckReview, destCheckReview);
+    if (fs.existsSync(srcRules)) {
+      fs.copyFileSync(srcRules, destRules);
+    }
     return true;
   } catch (err) {
     process.stderr.write(`[refacil-sdd-ai] Could not install OpenCode plugin: ${err.message}\n`);
@@ -307,9 +323,15 @@ function uninstallOpenCodePlugin(homeDir) {
   const resolvedHome = homeDir || os.homedir();
   const ocDir = globalOpenCodeDir(resolvedHome);
   const pluginPath = path.join(ocDir, 'plugins', 'refacil-hooks.js');
-  if (!fs.existsSync(pluginPath)) return false;
+  const checkReviewPath = path.join(ocDir, 'plugins', 'refacil-check-review.js');
+  const rulesPath = path.join(ocDir, 'plugins', 'rules.js');
+  if (!fs.existsSync(pluginPath) && !fs.existsSync(checkReviewPath) && !fs.existsSync(rulesPath)) {
+    return false;
+  }
   try {
-    fs.unlinkSync(pluginPath);
+    if (fs.existsSync(pluginPath)) fs.unlinkSync(pluginPath);
+    if (fs.existsSync(checkReviewPath)) fs.unlinkSync(checkReviewPath);
+    if (fs.existsSync(rulesPath)) fs.unlinkSync(rulesPath);
     return true;
   } catch (err) {
     process.stderr.write(`[refacil-sdd-ai] Could not remove OpenCode plugin: ${err.message}\n`);
@@ -326,6 +348,12 @@ function uninstallOpenCodePlugin(homeDir) {
  * @param {string} projectRoot
  */
 function removeProjectLevelHooks(projectRoot) {
+  // Safety guard: never strip hooks from the global ~/.claude/settings.json.
+  // If projectRoot is the home directory (findProjectRoot() fallback), skip entirely.
+  const resolvedRoot = require('path').resolve(projectRoot);
+  const resolvedHome = require('path').resolve(require('os').homedir());
+  if (resolvedRoot === resolvedHome) return;
+
   const sddMarkers = ['_sdd', '_sdd_compact', '_sdd_review', '_sdd_notify'];
 
   // .claude/settings.json

package/lib/ide-detection.js

@@ -6,7 +6,7 @@ const { spawnSync } = require('child_process');
  * Detects which IDEs are installed on the current system.
  * Uses `where` on Windows and `which` on macOS/Linux.
  * Error-tolerant: catches per-IDE errors silently.
- * @returns {string[]} subset of ['claude', 'cursor', 'opencode']
+ * @returns {string[]} subset of ['claude', 'cursor', 'opencode', 'codex']
  */
 function detectInstalledIDEs() {
   const candidates = [

package/lib/ignore-files.js

@@ -64,12 +64,16 @@ function syncIgnoreFile(filePath) {
   }
 
   const existing = fs.readFileSync(filePath, 'utf8');
+  // Trim each line before comparison — handles CRLF (Windows) vs LF differences
+  // so a file that differs only in line endings is treated as up-to-date (CA-05).
   const existingLines = existing.split('\n').map((l) => l.trim());
 
   const missing = BASE_ENTRIES.filter(
     (entry) => isSignificant(entry) && !existingLines.includes(entry.trim()),
   );
 
+  // No new entries needed — noop path. No additional idempotency guard is required
+  // because the initial creation path (file absent) is always correct when missing.
   if (missing.length === 0) {
     return { status: 'noop', added: 0 };
   }
@@ -94,4 +98,4 @@ function syncIgnoreFiles(projectRoot, ideDirs) {
   return result;
 }
 
-module.exports = { syncIgnoreFiles, BASE_ENTRIES };
+module.exports = { syncIgnoreFiles, syncIgnoreFile, BASE_ENTRIES };