forge-workflow 0.0.9 → 0.1.0-beta.2

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'
 };
 
 /**

package/lib/setup.js

@@ -1,5 +1,6 @@
 const fs = require('node:fs');
 const path = require('node:path');
+const { cleanupDeprecatedSyncFiles } = require('./deprecated-sync-cleanup');
 
 /**
  * Save setup state to .forge/setup-state.json
@@ -110,76 +111,36 @@ async function markStepComplete(projectPath, stepName) {
 }
 
 /**
- * Scaffold GitHub-Beads sync files into a target project.
- * Copies workflow, config, and mapping template — never overwrites existing files.
+ * Remove generated GitHub-Beads sync scaffold from existing installs.
+ *
+ * @param {string} projectPath - Target project root
+ * @returns {Promise<{removed: string[], skipped: string[]}>}
+ */
+async function cleanupDeprecatedGithubBeadsSync(projectPath, options = {}) {
+  return cleanupDeprecatedSyncFiles(projectPath, options);
+}
+
+/**
+ * Deprecated compatibility shim for the removed GitHub-Beads sync scaffold.
+ *
+ * Performs cleanup of generated legacy sync artifacts only. User-owned files
+ * at matching paths are preserved unless their content matches known generated
+ * templates.
  *
  * @param {string} projectPath - Target project root
  * @param {string} pkgDir - Forge package directory (source of template files)
- * @returns {Promise<{created: string[], skipped: string[]}>}
+ * @returns {Promise<{created: string[], skipped: string[], removed: string[], deprecated: boolean, message: string}>}
  */
 async function scaffoldGithubBeadsSync(projectPath, pkgDir) {
-  const created = [];
-  const skipped = [];
-
-  // Sync script modules that workflows depend on at runtime
-  const syncScripts = [
-    'config.mjs', 'mapping.mjs', 'comment.mjs', 'github-api.mjs',
-    'sanitize.mjs', 'run-bd.mjs', 'label-mapper.mjs', 'index.mjs',
-    'reverse-sync.mjs', 'reverse-sync-cli.mjs',
-  ];
-
-  const files = [
-    // Phase 1: GitHub → Beads
-    {
-      src: path.join(pkgDir, '.github', 'workflows', 'github-to-beads.yml'),
-      dest: path.join('.github', 'workflows', 'github-to-beads.yml'),
-    },
-    // Phase 2: Beads → GitHub
-    {
-      src: path.join(pkgDir, '.github', 'workflows', 'beads-to-github.yml'),
-      dest: path.join('.github', 'workflows', 'beads-to-github.yml'),
-    },
-    {
-      src: path.join(pkgDir, 'scripts', 'github-beads-sync.config.json'),
-      dest: path.join('scripts', 'github-beads-sync.config.json'),
-    },
-    {
-      src: null, // generated in-place (empty mapping template)
-      dest: path.join('.github', 'beads-mapping.json'),
-      content: '{}',
-    },
-    // Sync script modules
-    ...syncScripts.map((name) => ({
-      src: path.join(pkgDir, 'scripts', 'github-beads-sync', name),
-      dest: path.join('scripts', 'github-beads-sync', name),
-    })),
-  ];
-
-  for (const file of files) {
-    const destPath = path.join(projectPath, file.dest);
-
-    // Never overwrite existing files — preserve user customizations
-    if (fs.existsSync(destPath)) {
-      skipped.push(file.dest);
-      continue;
-    }
-
-    // Ensure parent directory exists
-    const destDir = path.dirname(destPath);
-    await fs.promises.mkdir(destDir, { recursive: true });
-
-    if (file.src) {
-      // Copy from template
-      await fs.promises.copyFile(file.src, destPath);
-    } else {
-      // Write generated content
-      await fs.promises.writeFile(destPath, file.content, 'utf-8');
-    }
-
-    created.push(file.dest);
-  }
-
-  return { created, skipped };
+  const cleanup = await cleanupDeprecatedGithubBeadsSync(projectPath, { packageDir: pkgDir });
+
+  return {
+    created: [],
+    skipped: [],
+    removed: cleanup.removed,
+    deprecated: true,
+    message: 'GitHub-Beads sync scaffolding is deprecated; future GitHub issue sync must use Forge Kernel/server authority.'
+  };
 }
 
 module.exports = {
@@ -188,5 +149,6 @@ module.exports = {
   isSetupComplete,
   getNextStep,
   markStepComplete,
+  cleanupDeprecatedGithubBeadsSync,
   scaffoldGithubBeadsSync
 };

package/lib/shell-utils.js

@@ -5,10 +5,62 @@
  */
 
 const { execFileSync, spawnSync } = require('node:child_process');
+const path = require('node:path');
+
+// Extensions Windows can spawn directly via CreateProcess. Anything else that
+// `where.exe` returns — the extensionless POSIX shim (`npm`) or the batch shim
+// (`npm.cmd`) — cannot be handed to execFileSync: the former is a bash script
+// (spawnSync ENOENT, kernel issue 9997d516) and patched Node refuses .cmd/.bat
+// without shell:true (CVE-2024-27980).
+const WINDOWS_DIRECT_SPAWN_EXTS = new Set(['.exe', '.com']);
+
+// Conservative allowlist for tokens executed through cmd.exe. Blocks every cmd
+// metacharacter (& | < > ^ % ! " ' ` ( ) ; and whitespace) so shell execution
+// cannot be turned into injection even if a caller ever passes dynamic input.
+const SAFE_SHELL_TOKEN = /^[A-Za-z0-9@_+=:,./\\-]+$/;
+
+/**
+ * Throw when any token is unsafe to pass through cmd.exe.
+ * @param {string} command - The command name
+ * @param {string[]} args - Command arguments
+ */
+function assertShellSafeTokens(command, args) {
+  for (const token of [command, ...args]) {
+    if (typeof token !== 'string' || !SAFE_SHELL_TOKEN.test(token)) {
+      throw new Error(
+        `Refusing to run "${command}" via shell: unsafe token ${JSON.stringify(token)}`
+      );
+    }
+  }
+}
+
+/**
+ * Decide how to spawn a command on Windows from `where.exe` candidates.
+ * Prefers a directly spawnable .exe/.com — including when the caller already
+ * passed an absolute .exe/.com path (which `where.exe` may not re-enumerate);
+ * otherwise runs the BARE command name through cmd.exe (shell:true), which
+ * resolves npm.cmd/npx.cmd/lefthook.cmd via PATH/PATHEXT — so paths with spaces
+ * never hit shell parsing or the shell-safe token allowlist.
+ *
+ * @param {string} command - Original command name or absolute path
+ * @param {string[]} candidates - Resolved paths from `where.exe`, best first
+ * @returns {{ file: string, shell: boolean }}
+ */
+function resolveWindowsSpawnSpec(command, candidates) {
+  const direct = [command, ...candidates].find(
+    (candidate) => WINDOWS_DIRECT_SPAWN_EXTS.has(path.extname(candidate).toLowerCase())
+  );
+  if (direct) {
+    return { file: direct, shell: false };
+  }
+  return { file: command, shell: true };
+}
 
 /**
  * Securely execute a command with PATH validation.
  * Mitigates SonarCloud S4036: Ensures executables are from trusted locations.
+ * On Windows, handles npm/npx/lefthook-style cmd shims that cannot be spawned
+ * directly (see resolveWindowsSpawnSpec).
  * @param {string} command - The command to execute
  * @param {string[]} [args=[]] - Command arguments
  * @param {object} [options={}] - execFileSync options
@@ -18,16 +70,16 @@ function secureExecFileSync(command, args = [], options = {}) {
   const {
     _execFileSync = execFileSync,
     _spawnSync = spawnSync,
+    _platform = process.platform,
     ...execOptions
   } = options;
 
-  let resolvedPath = null;
+  const isWindows = _platform === 'win32';
+  const pathResolver = isWindows ? 'where.exe' : 'which';
 
+  let candidates = [];
   try {
     // Resolve command's full path to validate it's in a trusted location
-    const isWindows = process.platform === 'win32';
-    const pathResolver = isWindows ? 'where.exe' : 'which';
-
     const result = _spawnSync(pathResolver, [command], {
       encoding: 'utf8',
       stdio: ['ignore', 'pipe', 'ignore']
@@ -35,14 +87,32 @@ function secureExecFileSync(command, args = [], options = {}) {
 
     if (result.status === 0 && result.stdout) {
       // Handle both CRLF (Windows) and LF (Unix) line endings
-      resolvedPath = result.stdout.trim().split(/\r?\n/)[0].trim();
+      candidates = result.stdout
+        .trim()
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean);
     }
   } catch (_err) { // NOSONAR - S2486: Intentionally ignored; falls back to direct command execution below
   }
 
+  if (isWindows) {
+    const spec = resolveWindowsSpawnSpec(command, candidates);
+    if (spec.shell) {
+      assertShellSafeTokens(command, args);
+      // Node 22 (DEP0190) deprecates passing an args array together with shell:true.
+      // assertShellSafeTokens has already guaranteed every token is free of shell
+      // metacharacters, so fold them into a single command line and pass no args array —
+      // identical execution through cmd.exe (npm.cmd/npx.cmd shims), no deprecation warning.
+      const commandLine = [command, ...args].join(' ');
+      return _execFileSync(commandLine, [], { ...execOptions, shell: true });
+    }
+    return _execFileSync(spec.file, args, execOptions);
+  }
+
   // Fall back only when resolution failed. If execution of the resolved binary
   // throws, propagate that error instead of retrying with the unresolved name.
-  return _execFileSync(resolvedPath || command, args, execOptions);
+  return _execFileSync(candidates[0] || command, args, execOptions);
 }
 
 module.exports = {