forge-workflow 0.0.10 → 0.1.0-beta.3

package/lib/runtime-health.js

@@ -12,6 +12,8 @@ const path = require('node:path');
 const { execFileSync: defaultExecFileSync } = require('node:child_process');
 
 const { checkLefthookStatus } = require('./lefthook-check');
+const { resolveIssueBackend } = require('./issue-backend');
+const { getInstallCommand, getAddDevCommand } = require('./package-manager-remediation');
 
 const WINDOWS_GIT_BASH_CANDIDATES = [
   String.raw`C:\Program Files\Git\bin\bash.exe`,
@@ -43,11 +45,149 @@ function normalizeHooksPath(value, platform = process.platform) {
   return normalized;
 }
 
-function createDiagnostic(code, subject, message, repair) {
+function isAbsoluteForPlatform(value, platform = process.platform) {
+  const raw = toText(value).trim();
+  return platform === 'win32' ? path.win32.isAbsolute(raw) : path.posix.isAbsolute(raw);
+}
+
+function resolvesToExecutableHookCommand(line, matcher) {
+  const trimmed = line.trim();
+  if (!trimmed || trimmed.startsWith('#')) return false;
+  const firstCommand = commandName(commandTokens(trimmed)[0]);
+  if (firstCommand === 'echo' || firstCommand === 'printf') {
+    const chainIndex = trimmed.indexOf('&&');
+    return chainIndex === -1 ? false : matcher(trimmed.slice(chainIndex + 2).trim());
+  }
+  return matcher(trimmed);
+}
+
+function hasExecutableHookCommand(content, matcher) {
+  let heredocEnd = null;
+
+  for (const line of toText(content).split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (heredocEnd) {
+      if (trimmed === heredocEnd) heredocEnd = null;
+      continue;
+    }
+
+    if (resolvesToExecutableHookCommand(line, matcher)) return true;
+
+    const delimiter = heredocDelimiter(line);
+    if (delimiter) heredocEnd = delimiter;
+  }
+
+  return false;
+}
+
+function commandTokens(line) {
+  return line
+    .replace(/[;"'()]/g, ' ')
+    .split(/\s+/)
+    .filter(Boolean);
+}
+
+function commandName(token) {
+  return toText(token)
+    .replaceAll('\\', '/')
+    .split('/')
+    .pop()
+    .toLowerCase()
+    .replace(/\.(?:exe|cmd)$/, '');
+}
+
+function isWhitespace(char) {
+  return char === ' ' || char === '\t' || char === '\r' || char === '\n';
+}
+
+function isVariableNameStart(char) {
+  return (char >= 'A' && char <= 'Z') || (char >= 'a' && char <= 'z') || char === '_';
+}
+
+function isVariableNameChar(char) {
+  return isVariableNameStart(char) || (char >= '0' && char <= '9');
+}
+
+function isAssignmentToken(token) {
+  const text = toText(token);
+  const equalsIndex = text.indexOf('=');
+  if (equalsIndex <= 0 || !isVariableNameStart(text[0])) return false;
+
+  for (let index = 1; index < equalsIndex; index += 1) {
+    if (!isVariableNameChar(text[index])) return false;
+  }
+
+  return true;
+}
+
+function heredocDelimiter(line) {
+  const markerIndex = line.indexOf('<<');
+  if (markerIndex === -1 || line[markerIndex + 2] === '<') return null;
+
+  let cursor = markerIndex + 2;
+  if (line[cursor] === '-') cursor += 1;
+  while (cursor < line.length && isWhitespace(line[cursor])) cursor += 1;
+
+  const quote = line[cursor];
+  if (quote === '"' || quote === "'") {
+    cursor += 1;
+    const endQuote = line.indexOf(quote, cursor);
+    return endQuote === -1 ? line.slice(cursor).trim() || null : line.slice(cursor, endQuote) || null;
+  }
+
+  const start = cursor;
+  while (cursor < line.length && !isWhitespace(line[cursor])) cursor += 1;
+  return line.slice(start, cursor).trim() || null;
+}
+
+function isExecutingTokenPosition(tokens, index) {
+  const nonExecutingPreviousTokens = new Set(['-e', '-f', '-r', '-x', '[', 'test']);
+  const executingPreviousCommands = new Set(['bash', 'bun', 'env', 'exec', 'if', 'node', 'sh', 'then', '&&']);
+
+  let previousIndex = index - 1;
+  while (previousIndex >= 0 && isAssignmentToken(tokens[previousIndex])) {
+    previousIndex -= 1;
+  }
+
+  if (previousIndex < 0) return true;
+
+  const previous = toText(tokens[previousIndex]).toLowerCase();
+  if (nonExecutingPreviousTokens.has(previous)) return false;
+  return executingPreviousCommands.has(commandName(previous));
+}
+
+function invokesLefthook(line) {
+  return commandTokens(line).some((token) => commandName(token) === 'lefthook');
+}
+
+function invokesForgeHook(line) {
+  return commandTokens(line).some((token, index, tokens) => {
+    if (token.includes('=')) return false;
+    const normalized = token.replaceAll('\\', '/').toLowerCase();
+    if (!normalized.endsWith('.forge/hooks/check-tdd.js') && commandName(token) !== 'check-tdd.js') {
+      return false;
+    }
+
+    return isExecutingTokenPosition(tokens, index);
+  });
+}
+
+function invokesBeadsHook(line, hookName) {
+  const tokens = commandTokens(line);
+  return tokens.some((token, index) => (
+    commandName(token) === 'bd'
+    && toText(tokens[index + 1]).toLowerCase() === 'hooks'
+    && toText(tokens[index + 2]).toLowerCase() === 'run'
+    && toText(tokens[index + 3]).toLowerCase() === hookName
+    && isExecutingTokenPosition(tokens, index)
+  ));
+}
+
+function createDiagnostic(code, subject, message, repair, severity = 'hard-stop') {
   return {
     code,
     subject,
-    severity: 'hard-stop',
+    severity,
     message,
     ...(repair ? { repair } : {})
   };
@@ -76,7 +216,7 @@ function isUsableWindowsShellCandidate(candidate, options = {}) {
 function checkHookInstallation(projectRoot, options = {}) {
   const exec = options._exec || defaultExecFileSync;
   const platform = options.platform || process.platform;
-  const expectedRelativeHooksPath = normalizeHooksPath('.lefthook/hooks', platform);
+  const expectedRelativeHooksPaths = ['.lefthook/hooks', '.beads/hooks'];
   const requiredHooks = ['pre-commit', 'pre-push'];
 
   function resolveGitRoot() {
@@ -92,7 +232,10 @@ function checkHookInstallation(projectRoot, options = {}) {
   }
 
   const gitRoot = resolveGitRoot();
-  const expectedAbsoluteHooksPath = normalizeHooksPath(`${gitRoot}/${expectedRelativeHooksPath}`, platform);
+  const expectedHooksPaths = new Set(expectedRelativeHooksPaths.flatMap((hooksPath) => [
+    normalizeHooksPath(hooksPath, platform),
+    normalizeHooksPath(`${gitRoot}/${normalizeHooksPath(hooksPath, platform)}`, platform)
+  ]));
 
   function resolveGitHooksDir() {
     try {
@@ -108,17 +251,44 @@ function checkHookInstallation(projectRoot, options = {}) {
     }
   }
 
-  function fileLooksLikeActiveHook(filePath) {
+  function classifyHookFile(filePath, hookName, visited = new Set()) {
     try {
+      const normalizedFilePath = path.resolve(filePath);
+      if (visited.has(normalizedFilePath)) {
+        return { active: false, provider: 'cycle' };
+      }
+      visited.add(normalizedFilePath);
+
       const stat = fs.statSync(filePath);
       const executable = platform === 'win32'
         || (typeof options._canExecuteHook === 'function'
           ? Boolean(options._canExecuteHook(filePath, stat))
           : (stat.mode & 0o111) !== 0);
-      if (!stat.isFile() || stat.size === 0 || !executable) return false;
-      return /\blefthook\b/i.test(fs.readFileSync(filePath, 'utf8'));
+      if (!stat.isFile() || stat.size === 0 || !executable) return { active: false, provider: 'missing' };
+
+      const content = fs.readFileSync(filePath, 'utf8');
+      const runsLefthook = hasExecutableHookCommand(content, invokesLefthook);
+      const runsForgeHook = hasExecutableHookCommand(content, invokesForgeHook);
+      const runsBeadsHook = hasExecutableHookCommand(content, (line) => invokesBeadsHook(line, hookName));
+
+      if (runsLefthook) return { active: true, provider: 'lefthook' };
+      if (runsForgeHook) return { active: true, provider: 'forge' };
+
+      if (runsBeadsHook) {
+        const chainedHookPath = path.join(gitRoot, '.beads', 'hooks', hookName);
+        if (path.resolve(chainedHookPath) !== normalizedFilePath && fs.existsSync(chainedHookPath)) {
+          const chained = classifyHookFile(chainedHookPath, hookName, visited);
+          if (chained.active) {
+            return { active: true, provider: `beads->${chained.provider}` };
+          }
+        }
+
+        return { active: false, provider: 'beads-unverified' };
+      }
+
+      return { active: false, provider: 'unknown' };
     } catch {
-      return false;
+      return { active: false, provider: 'missing' };
     }
   }
 
@@ -130,11 +300,18 @@ function checkHookInstallation(projectRoot, options = {}) {
     });
 
     hooksPath = normalizeHooksPath(output, platform);
-    const active = hooksPath === expectedRelativeHooksPath || hooksPath === expectedAbsoluteHooksPath;
+    const active = expectedHooksPaths.has(hooksPath);
 
     if (active) {
-      const hooksDir = path.join(gitRoot, '.lefthook', 'hooks');
-      const missingHooks = requiredHooks.filter(hook => !fileLooksLikeActiveHook(path.join(hooksDir, hook)));
+      const rawHooksPath = toText(output).trim();
+      const hooksDir = isAbsoluteForPlatform(rawHooksPath, platform)
+        ? rawHooksPath
+        : path.resolve(gitRoot, normalizeHooksPath(rawHooksPath, platform));
+      const hookChecks = requiredHooks.map((hook) => ({
+        hook,
+        ...classifyHookFile(path.join(hooksDir, hook), hook)
+      }));
+      const missingHooks = hookChecks.filter(check => !check.active).map(check => check.hook);
       const verifiedActive = missingHooks.length === 0;
       return {
         active: verifiedActive,
@@ -142,6 +319,7 @@ function checkHookInstallation(projectRoot, options = {}) {
         verification: 'core.hooksPath',
         hooksPath: hooksPath || null,
         hooksDir,
+        providers: Object.fromEntries(hookChecks.map(check => [check.hook, check.provider])),
         missingHooks,
         message: verifiedActive
           ? ''
@@ -155,7 +333,7 @@ function checkHookInstallation(projectRoot, options = {}) {
         state: 'inactive',
         verification: 'core.hooksPath',
         hooksPath,
-        message: `Git core.hooksPath is set to "${hooksPath}", not ".lefthook/hooks".`
+        message: `Git core.hooksPath is set to "${hooksPath}", not ".lefthook/hooks" or ".beads/hooks".`
       };
     }
   } catch {
@@ -164,7 +342,11 @@ function checkHookInstallation(projectRoot, options = {}) {
 
   const hooksDir = resolveGitHooksDir();
   if (hooksDir) {
-    const missingHooks = requiredHooks.filter(hook => !fileLooksLikeActiveHook(path.join(hooksDir, hook)));
+    const hookChecks = requiredHooks.map((hook) => ({
+      hook,
+      ...classifyHookFile(path.join(hooksDir, hook), hook)
+    }));
+    const missingHooks = hookChecks.filter(check => !check.active).map(check => check.hook);
     const active = missingHooks.length === 0;
     return {
       active,
@@ -172,6 +354,7 @@ function checkHookInstallation(projectRoot, options = {}) {
       verification: 'git-path-hooks',
       hooksPath: hooksPath || null,
       hooksDir,
+      providers: Object.fromEntries(hookChecks.map(check => [check.hook, check.provider])),
       missingHooks,
       message: active
         ? ''
@@ -300,6 +483,22 @@ function normalizeProjectRoot(projectRoot) {
     : process.cwd();
 }
 
+// Resolve the active issue backend for the health gate. An already-normalized
+// `options.issueBackend` (passed by enforce-stage) wins; otherwise fall back to the
+// shared resolver (env > .forge/config.yaml > default 'kernel'). Never throws and
+// never warns from the health path.
+function resolveHealthIssueBackend(options, projectRoot) {
+  if (options.issueBackend === 'kernel' || options.issueBackend === 'beads') {
+    return options.issueBackend;
+  }
+  return resolveIssueBackend({
+    deps: options.backendDeps || {},
+    env: options.env || process.env,
+    projectRoot,
+    warn: () => {}
+  });
+}
+
 function checkRuntimeHealth(projectRoot, options = {}) {
   const platform = options.platform || process.platform;
   const root = normalizeProjectRoot(projectRoot);
@@ -311,17 +510,23 @@ function checkRuntimeHealth(projectRoot, options = {}) {
   const jq = checkCommandAvailability('jq', root, options);
   const shell = normalizeShellRuntime(options.shellRuntime, platform, options);
 
+  const issueBackend = resolveHealthIssueBackend(options, root);
+
   const diagnostics = [];
+  const advisories = [];
 
   const lefthookMissing = lefthook.state === 'missing-dependency'
     || lefthook.state === 'missing-binary';
 
   if (lefthookMissing) {
+    const lefthookRepair = lefthook.state === 'missing-binary'
+      ? getInstallCommand(root)
+      : getAddDevCommand(root, 'lefthook');
     diagnostics.push(createDiagnostic(
       'LEFTHOOK_MISSING',
       'lefthook',
       lefthook.message || 'lefthook is required for hook installation.',
-      'bun add -D lefthook && bun install'
+      lefthookRepair
     ));
   }
 
@@ -335,11 +540,25 @@ function checkRuntimeHealth(projectRoot, options = {}) {
   }
 
   if (!bd.available) {
-    diagnostics.push(createDiagnostic(
-      'BD_MISSING',
-      'bd',
-      'bd is required for stage-entry workflow checks.'
-    ));
+    if (issueBackend === 'beads') {
+      // Beads is the active issue backend, so bd is a genuine hard prerequisite.
+      diagnostics.push(createDiagnostic(
+        'BD_MISSING',
+        'bd',
+        'bd is required for stage-entry workflow checks when the beads issue backend is selected.'
+      ));
+    } else {
+      // Kernel is the default issue backend and needs no bd binary, so a missing bd
+      // must NOT hard-stop stage entry (the "no Beads install required" contract).
+      // Surface it as a non-blocking advisory instead.
+      advisories.push(createDiagnostic(
+        'BD_MISSING',
+        'bd',
+        'bd is not installed. The kernel issue backend does not require it; install bd only if you switch to the beads backend.',
+        undefined,
+        'advisory'
+      ));
+    }
   }
 
   if (!gh.available) {
@@ -373,6 +592,7 @@ function checkRuntimeHealth(projectRoot, options = {}) {
     ready: healthy,
     hardStop: !healthy,
     diagnostics,
+    advisories,
     checks: {
       projectRoot: root,
       lefthook,
@@ -380,7 +600,8 @@ function checkRuntimeHealth(projectRoot, options = {}) {
       bd,
       gh,
       jq,
-      shell
+      shell,
+      issueBackend
     }
   };
 }

package/lib/safety-config-renderer.js

@@ -0,0 +1,268 @@
+'use strict';
+
+/**
+ * Native SAFETY-surface renderer.
+ *
+ * Renders sane, non-surprising security defaults into the two safety surfaces
+ * Forge can write PROJECT-LOCALLY today:
+ *
+ *   - Claude Code : `.claude/settings.json` -> `permissions` (allow/deny/ask)
+ *   - Cursor      : `.cursorignore`         (gitignore-style AI read/index boundary)
+ *
+ * Both use read -> merge -> write (idempotent, preserves user entries). An existing
+ * `.claude/settings.json` that cannot be parsed is BACKED UP and left untouched
+ * (mirrors the MCP renderer's data-loss guard) rather than clobbering user settings.
+ *
+ * NOT rendered here (honest deferral): the Codex execution sandbox / approvals policy
+ * (`sandbox_mode` / `approval_policy`). Codex honors a project-local `.codex/config.toml`
+ * ONLY when the project is marked trusted in the GLOBAL `$CODEX_HOME/config.toml`
+ * (`projects.<path>.trust_level`). Forge cannot grant that global trust during
+ * project-local setup, so a rendered project-local sandbox policy would not take
+ * effect. It is deferred to global-scope wiring and marked `not-delivered` in the
+ * capability matrix (kernel epic 90f2f631 / #311).
+ *
+ * Defaults follow the principle: ALLOW the routine forge/dev workflow, DENY the
+ * obviously-dangerous, and let everything else fall through to the harness's normal
+ * "ask" behavior (Claude evaluates deny -> ask -> allow; unmatched tools still prompt).
+ * We intentionally do NOT set `defaultMode`, so nothing is silently auto-approved.
+ *
+ * Dependency-free beyond node builtins so it runs under `bun test` and release gates.
+ *
+ * @module safety-config-renderer
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { backupFile } = require('./mcp-config-renderer');
+
+/** Thrown when an existing settings file cannot be parsed — signals "do not overwrite". */
+class SafetyConfigParseError extends Error {
+  constructor(message, cause) {
+    super(message);
+    this.name = 'SafetyConfigParseError';
+    this.cause = cause;
+  }
+}
+
+// Safe Claude Code permission defaults. Rule syntax per Claude Code settings docs
+// (https://docs.claude.com/en/docs/claude-code/settings ,
+//  https://docs.claude.com/en/docs/claude-code/permissions):
+//   Bash(<prefix>:*)  — command-prefix match; Read(<glob>) — gitignore-style path.
+// Evaluated deny -> ask -> allow (deny always wins), so the deny Read(...) rules
+// protect secrets even though bare Read is not blanket-allowed.
+const CLAUDE_PERMISSION_DEFAULTS = Object.freeze({
+  // Routine, reversible forge/dev workflow — safe to run without a prompt.
+  allow: Object.freeze([
+    'Bash(git status:*)',
+    'Bash(git log:*)',
+    'Bash(git diff:*)',
+    'Bash(git branch:*)',
+    'Bash(git show:*)',
+    'Bash(git add:*)',
+    'Bash(git commit:*)',
+    'Bash(git stash:*)',
+    'Bash(git checkout:*)',
+    'Bash(git switch:*)',
+    'Bash(git pull:*)',
+    'Bash(git fetch:*)',
+    'Bash(git push:*)',
+    'Bash(ls:*)',
+    'Bash(cat:*)',
+    'Bash(pwd)',
+    'Bash(which:*)',
+    'Bash(mkdir:*)',
+    'Bash(cp:*)',
+    'Bash(mv:*)',
+    'Bash(bun run:*)',
+    'Bash(bun test:*)',
+    'Bash(bun install)',
+    'Bash(npm run:*)',
+    'Bash(npm test:*)',
+    'Bash(forge:*)',
+    'Bash(gh pr view:*)',
+    'Bash(gh pr list:*)',
+    'Bash(gh issue list:*)',
+  ]),
+  // Careful, rewrites-history / rewinds-state — worth a confirmation, not a hard block.
+  ask: Object.freeze([
+    'Bash(git rebase:*)',
+    'Bash(git reset:*)',
+    'Bash(git clean:*)',
+  ]),
+  // Obviously-dangerous commands + secret reads. deny wins over allow/ask.
+  deny: Object.freeze([
+    'Bash(rm -rf:*)',
+    'Bash(rm -fr:*)',
+    'Bash(git push --force:*)',
+    'Bash(git push -f:*)',
+    'Bash(git reset --hard:*)',
+    // Read/secret boundary — private keys and secret env files are never readable.
+    'Read(./.env)',
+    'Read(**/.env)',
+    'Read(**/.env.local)',
+    'Read(**/.env.*.local)',
+    'Read(**/*.pem)',
+    'Read(**/*.key)',
+    'Read(**/id_rsa)',
+    'Read(**/id_ed25519)',
+    'Read(./secrets/**)',
+    'Read(**/credentials.json)',
+  ]),
+});
+
+// Safe `.cursorignore` defaults (gitignore-style, per
+// https://cursor.com/docs/reference/ignore-file). Cursor already ignores .gitignore
+// and common lock/.env files by default; listing them here makes the secret/large-dir
+// boundary explicit and self-documenting. `.cursorignore` blocks Cursor AI features +
+// indexing (it is not a hard security boundary — terminal/MCP tools can still reach files).
+const CURSORIGNORE_DEFAULTS = Object.freeze([
+  '.env',
+  '.env.local',
+  '.env.*.local',
+  '*.pem',
+  '*.key',
+  'id_rsa',
+  'id_ed25519',
+  'secrets/',
+  'node_modules/',
+  'dist/',
+  'build/',
+  'out/',
+  'coverage/',
+  '.next/',
+  '*.log',
+]);
+
+const CURSORIGNORE_HEADER = [
+  '# ---- Forge safe defaults (managed) ----',
+  '# Keeps secrets and large/generated dirs out of Cursor AI context + index.',
+  '# Edit freely — Forge only appends missing lines and never removes yours.',
+];
+
+function unionPreserve(existing, defaults) {
+  const base = Array.isArray(existing) ? existing.filter(v => typeof v === 'string') : [];
+  const seen = new Set(base);
+  for (const rule of defaults) {
+    if (!seen.has(rule)) {
+      base.push(rule);
+      seen.add(rule);
+    }
+  }
+  return base;
+}
+
+/**
+ * Merge safe permission defaults into an existing `.claude/settings.json` string
+ * (read -> merge -> write). Preserves every other settings key and every existing
+ * allow/deny/ask entry (union, no duplicates). Idempotent.
+ * @param {string} existingText
+ * @returns {string} pretty JSON with a trailing newline
+ */
+function mergeClaudePermissions(existingText) {
+  let obj = {};
+  if (existingText && existingText.trim()) {
+    try {
+      obj = JSON.parse(existingText);
+    } catch (err) {
+      // DATA-LOSS GUARD: never silently discard a populated-but-unparseable settings
+      // file (e.g. JSONC with comments). Signal the caller to back up and skip.
+      throw new SafetyConfigParseError('existing .claude/settings.json is not valid JSON', err);
+    }
+  }
+  if (!obj || typeof obj !== 'object' || Array.isArray(obj)) obj = {};
+  const existingPerms = (obj.permissions && typeof obj.permissions === 'object' && !Array.isArray(obj.permissions))
+    ? obj.permissions
+    : {};
+  existingPerms.allow = unionPreserve(existingPerms.allow, CLAUDE_PERMISSION_DEFAULTS.allow);
+  existingPerms.ask = unionPreserve(existingPerms.ask, CLAUDE_PERMISSION_DEFAULTS.ask);
+  existingPerms.deny = unionPreserve(existingPerms.deny, CLAUDE_PERMISSION_DEFAULTS.deny);
+  obj.permissions = existingPerms;
+  return JSON.stringify(obj, null, 2) + '\n';
+}
+
+/**
+ * Merge safe ignore defaults into an existing `.cursorignore` string (read -> merge
+ * -> write). Preserves all user lines/comments verbatim and only appends default
+ * patterns that are not already present. Idempotent.
+ * @param {string} existingText
+ * @returns {string}
+ */
+function mergeCursorIgnore(existingText) {
+  const text = typeof existingText === 'string' ? existingText : '';
+  const existingPatterns = new Set(
+    text.split(/\r?\n/).map(line => line.trim()).filter(line => line && !line.startsWith('#')),
+  );
+  const missing = CURSORIGNORE_DEFAULTS.filter(pattern => !existingPatterns.has(pattern));
+  const base = text.replace(/\s+$/, '');
+  if (missing.length === 0) {
+    return base ? `${base}\n` : '';
+  }
+  const lines = [];
+  if (base) {
+    lines.push(base, '');
+  }
+  // Only add the Forge header block if it isn't already present — otherwise a later
+  // re-run (once CURSORIGNORE_DEFAULTS gains a new entry) would duplicate the header.
+  if (!text.includes(CURSORIGNORE_HEADER[0])) {
+    lines.push(...CURSORIGNORE_HEADER);
+  }
+  lines.push(...missing);
+  return lines.join('\n') + '\n';
+}
+
+/**
+ * Render safe Claude permission defaults into `.claude/settings.json`.
+ * Read -> merge -> write. An unparseable existing file is BACKED UP and left
+ * untouched (never overwritten) to avoid destroying user settings.
+ * @param {object} params
+ * @param {string} params.targetRoot - Project root.
+ * @returns {{ file: string, existed: boolean, skipped: boolean, backup?: string }}
+ */
+function renderClaudePermissions({ targetRoot }) {
+  const filePath = path.join(targetRoot, '.claude', 'settings.json');
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const existed = fs.existsSync(filePath);
+  const existing = existed ? fs.readFileSync(filePath, 'utf-8') : '';
+
+  let merged;
+  try {
+    merged = mergeClaudePermissions(existing);
+  } catch (err) {
+    if (err instanceof SafetyConfigParseError && existed) {
+      const backup = backupFile(filePath);
+      return { file: filePath, existed, skipped: true, backup };
+    }
+    throw err;
+  }
+
+  fs.writeFileSync(filePath, merged, 'utf-8');
+  return { file: filePath, existed, skipped: false };
+}
+
+/**
+ * Render safe `.cursorignore` defaults at the project root.
+ * Read -> merge -> write, preserving user lines. Line-based, so there is no
+ * parse-failure path (never destructive).
+ * @param {object} params
+ * @param {string} params.targetRoot - Project root.
+ * @returns {{ file: string, existed: boolean, skipped: boolean }}
+ */
+function renderCursorIgnore({ targetRoot }) {
+  const filePath = path.join(targetRoot, '.cursorignore');
+  const existed = fs.existsSync(filePath);
+  const existing = existed ? fs.readFileSync(filePath, 'utf-8') : '';
+  const merged = mergeCursorIgnore(existing);
+  fs.writeFileSync(filePath, merged, 'utf-8');
+  return { file: filePath, existed, skipped: false };
+}
+
+module.exports = {
+  SafetyConfigParseError,
+  CLAUDE_PERMISSION_DEFAULTS,
+  CURSORIGNORE_DEFAULTS,
+  mergeClaudePermissions,
+  mergeCursorIgnore,
+  renderClaudePermissions,
+  renderCursorIgnore,
+};

package/lib/setup-action-log.js

@@ -11,15 +11,9 @@
 const AGENT_PREFIXES = {
   '.claude/': 'Claude Code',
   '.cursor/': 'Cursor',
-  '.windsurf/': 'Windsurf',
-  '.cline/': 'Cline',
   '.codex/': 'Codex',
   '~/.codex/': 'Codex',
-  '$CODEX_HOME/': 'Codex',
-  '.opencode/': 'OpenCode',
-  '.kilocode/': 'Kilocode',
-  '.roo/': 'Roo Code',
-  '.github/prompts/': 'GitHub Copilot'
+  '$CODEX_HOME/': 'Codex'
 };
 
 /**