forge-workflow 0.1.0-beta.4 → 0.1.0-beta.5

package/lib/symlink-utils.js

@@ -18,6 +18,40 @@ const path = require('node:path');
 const HEADER_COMMENT =
   '<!-- This file is a copy of AGENTS.md. Keep in sync manually or use: bunx forge setup --symlink -->';
 
+const SYMLINK_FALLBACK_ERRORS = new Set(['EACCES', 'ENOSYS', 'ENOTSUP', 'EOPNOTSUPP', 'EPERM']);
+
+function inspectExistingDestination(target, linkPath) {
+  let stat;
+  try {
+    stat = fs.lstatSync(linkPath);
+  } catch (err) {
+    if (err.code === 'ENOENT') return null;
+    throw err;
+  }
+
+  if (stat.isSymbolicLink()) {
+    let linkedTarget;
+    try {
+      linkedTarget = fs.readlinkSync(linkPath);
+    } catch (err) {
+      if (err.code === 'ENOENT') return null;
+      throw err;
+    }
+    if (path.resolve(path.dirname(linkPath), linkedTarget) === path.resolve(target)) {
+      return 'linked';
+    }
+  }
+  if (stat.isDirectory()) {
+    console.warn(`  Warning: Skipped ${linkPath} because it is a directory. Remove it manually and re-run setup.`);
+    return '';
+  }
+  if (stat.isFile() && fs.readFileSync(linkPath, 'utf8').trim() === '@AGENTS.md') {
+    return 'existing-import';
+  }
+  console.warn(`  Warning: Skipped ${linkPath} because an existing destination must be preserved.`);
+  return '';
+}
+
 /**
  * Create a symlink from `linkPath` pointing to `target`.
  * If symlink creation fails (e.g., EPERM on Windows without admin),
@@ -28,7 +62,7 @@ const HEADER_COMMENT =
  * @param {string} linkPath - Absolute path for the symlink/copy (e.g., CLAUDE.md)
  * @param {Object} [options={}] - Options
  * @param {boolean} [options.symlinkOnly=false] - When true, skip copy fallback (--symlink flag)
- * @returns {'linked'|'copied'|''} Result indicator
+ * @returns {'linked'|'copied'|'existing-import'|''} Result indicator
  */
 function createSymlinkOrCopy(target, linkPath, options = {}) {
   try {
@@ -38,17 +72,9 @@ function createSymlinkOrCopy(target, linkPath, options = {}) {
       return '';
     }
 
-    // Remove existing file/symlink at linkPath
-    if (fs.existsSync(linkPath)) {
-      const stat = fs.lstatSync(linkPath);
-      if (stat.isDirectory()) {
-        console.warn(
-          `  ⚠ Skipped ${linkPath} (a directory exists at this path). Remove it manually and re-run setup.`
-        );
-        return '';
-      }
-      fs.unlinkSync(linkPath);
-    }
+    // Existing agent files belong to the user. lstat also sees dangling links.
+    const existing = inspectExistingDestination(target, linkPath);
+    if (existing !== null) return existing;
 
     // Ensure parent directory exists
     const linkDir = path.dirname(linkPath);
@@ -56,22 +82,44 @@ function createSymlinkOrCopy(target, linkPath, options = {}) {
       fs.mkdirSync(linkDir, { recursive: true });
     }
 
-    // Attempt symlink (relative path for portability)
-    try {
-      const relPath = path.relative(linkDir, target);
-      fs.symlinkSync(relPath, linkPath);
-      return 'linked';
-    } catch (_symlinkErr) {
-      // Expected: symlink creation fails with EPERM on Windows without admin privileges — fall back to copy
-      if (options.symlinkOnly) {
-        console.warn(`  ⚠ Symlink failed for ${linkPath} (--symlink requires symlink support)`);
-        return '';
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+      // Attempt symlink (relative path for portability)
+      try {
+        const relPath = path.relative(linkDir, target);
+        fs.symlinkSync(relPath, linkPath);
+        return 'linked';
+      } catch (symlinkErr) {
+        if (symlinkErr.code === 'EEXIST') {
+          const racedExisting = inspectExistingDestination(target, linkPath);
+          if (racedExisting !== null) return racedExisting;
+          continue;
+        }
+        if (!SYMLINK_FALLBACK_ERRORS.has(symlinkErr.code)) {
+          throw symlinkErr;
+        }
+        if (options.symlinkOnly) {
+          console.warn(`  ⚠ Symlink failed for ${linkPath} (--symlink requires symlink support)`);
+          return '';
+        }
+        const content = fs.readFileSync(target, 'utf-8');
+        try {
+          fs.writeFileSync(linkPath, HEADER_COMMENT + '\n' + content, {
+            encoding: 'utf8',
+            flag: 'wx',
+          });
+          return 'copied';
+        } catch (copyErr) {
+          if (copyErr.code === 'EEXIST') {
+            const racedExisting = inspectExistingDestination(target, linkPath);
+            if (racedExisting !== null) return racedExisting;
+            continue;
+          }
+          throw copyErr;
+        }
       }
-      // Fall back to copy with header
-      const content = fs.readFileSync(target, 'utf-8');
-      fs.writeFileSync(linkPath, HEADER_COMMENT + '\n' + content, 'utf-8');
-      return 'copied';
     }
+    console.warn(`  ⚠ Could not create ${linkPath} after repeated conflicts; please re-run setup.`);
+    return '';
   } catch (err) {
     console.error(`  ✗ Failed to link/copy ${target} -> ${linkPath}: ${err.message}`);
     return '';

package/lib/upgrade-safety.js

@@ -8,6 +8,14 @@ const { resolvePatchIntentRecords } = require('./patch-intent');
 const { verifyForgeLock, readForgeLock } = require('./forge-lock');
 const { readConfigBackend, resolveIssueBackend } = require('./issue-backend');
 const { detectBeadsJsonlSource } = require('./beads-detect');
+const {
+  FORGE_HOOK_CONTRACT,
+  hasForgeClaudeHooks,
+  hasMultipleHardLinks,
+  HookConfigParseError,
+  renderHookConfig,
+} = require('./hook-renderer');
+const { assertNoAncestorSymlinkEscape, assertNoSymlinkEscape } = require('./protected-state-surfaces');
 
 function checkStatus(ok) {
   return ok ? 'pass' : 'fail';
@@ -55,6 +63,31 @@ function buildSelfHealCandidates(projectRoot) {
       description: 'Create missing Forge audit log file',
     });
   }
+  const claudeDir = path.join(projectRoot, '.claude');
+  if (fs.existsSync(claudeDir)) {
+    const claudeSettings = path.join(claudeDir, 'settings.json');
+    const unsafePath =
+      assertNoAncestorSymlinkEscape(projectRoot, claudeSettings) ||
+      assertNoSymlinkEscape(projectRoot, claudeSettings);
+    if (unsafePath || hasMultipleHardLinks(claudeSettings)) return candidates;
+    const existing = fs.existsSync(claudeSettings) ? fs.readFileSync(claudeSettings, 'utf8') : '';
+    try {
+      if (!hasForgeClaudeHooks(existing, FORGE_HOOK_CONTRACT)) {
+        candidates.push({
+          id: 'claude-hooks',
+          path: '.claude/settings.json',
+          description: 'Merge missing Forge-owned Claude lifecycle hooks',
+        });
+      }
+    } catch (error) {
+      if (!(error instanceof HookConfigParseError)) throw error;
+      candidates.push({
+        id: 'claude-hooks',
+        path: '.claude/settings.json',
+        description: 'Back up malformed Claude settings before hook repair',
+      });
+    }
+  }
   return candidates;
 }
 
@@ -235,6 +268,12 @@ function applySelfHeal(projectRoot, report) {
     applied.push({ path: '.forge/log.jsonl' });
   }
 
+  if (report.selfHealCandidates.some(candidate => candidate.id === 'claude-hooks')) {
+    const result = renderHookConfig({ harness: 'claude', targetRoot: projectRoot });
+    if (result.wrote) applied.push({ path: '.claude/settings.json' });
+    else if (result.backup) applied.push({ path: path.relative(projectRoot, result.backup) });
+  }
+
   return {
     refused: false,
     applied,

package/lib/using-forge.js

@@ -100,10 +100,10 @@ function applyFrontmatterLine(state, line) {
   if (state.inDescription) {
     if (/^\s+\S/.test(line)) {
       state.descParts.push(line.trim());
-    } else if (line.trim() !== '') {
-      state.inDescription = false;
+      return;
     }
-    return;
+    if (line.trim() === '') return;
+    state.inDescription = false;
   }
   // Detect the `name:` key without a regex: SonarCloud flags every /^name:.../ variant for
   // super-linear backtracking. startsWith + slice is behavior-identical — the remainder is
@@ -113,6 +113,15 @@ function applyFrontmatterLine(state, line) {
     if (value) state.name = unquote(value);
     return;
   }
+  if (line.startsWith('invocation:')) {
+    const value = line.slice('invocation:'.length).trim();
+    const quote = value[0];
+    const hasMatchingQuotes = value.length >= 2
+      && (quote === '"' || quote === "'")
+      && value.endsWith(quote);
+    state.invocation = hasMatchingQuotes ? value.slice(1, -1) : value;
+    return;
+  }
   const descMatch = /^description:\s*(.*)$/.exec(line);
   if (descMatch) {
     state.inDescription = true;
@@ -124,10 +133,14 @@ function applyFrontmatterLine(state, line) {
 /** Parse the name and (flattened) description from a SKILL.md frontmatter block. */
 function parseFrontmatter(raw) {
   const block = frontmatterBlock(raw);
-  if (block === null) return { name: null, description: '' };
-  const state = { name: null, descParts: [], inDescription: false };
+  if (block === null) return { name: null, description: '', invocation: 'model' };
+  const state = { name: null, descParts: [], inDescription: false, invocation: 'model' };
   for (const line of block.split(/\r?\n/)) applyFrontmatterLine(state, line);
-  return { name: state.name, description: state.descParts.join(' ').replace(/\s+/g, ' ').trim() };
+  return {
+    name: state.name,
+    description: state.descParts.join(' ').replace(/\s+/g, ' ').trim(),
+    invocation: state.invocation,
+  };
 }
 
 /** Read one skill dir into a `{ name, description }` catalog entry, or null when unreadable. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-workflow",
-  "version": "0.1.0-beta.4",
+  "version": "0.1.0-beta.5",
   "description": "Local runtime control plane for AI-assisted engineering workflows, gates, evidence, and all AI agents",
   "bin": {
     "forge": "bin/forge.js",
@@ -53,11 +53,11 @@
     "@eslint/js": "^10.0.1",
     "@microsoft/eslint-formatter-sarif": "^3.1.0",
     "@stryker-mutator/core": "^9.6.0",
-    "c8": "^11.0.0",
+    "c8": "^12.0.0",
     "eslint": "^10.0.2",
     "eslint-plugin-sonarjs": "^4.1.0",
     "globals": "^17.3.0",
-    "js-yaml": "^5.1.0",
+    "js-yaml": "^5.2.2",
     "lefthook": "^2.1.4",
     "typescript": "7.0.2"
   },
@@ -96,8 +96,6 @@
     ".cursor/",
     "!.cursor/node_modules/",
     "scripts/",
-    "!scripts/github-beads-sync/",
-    "!scripts/github-beads-sync.config.json",
     "!scripts/**/*.test.js",
     ".github/PLUGIN_TEMPLATE.json",
     ".forge/hooks/",
@@ -122,10 +120,11 @@
   },
   "overrides": {
     "eslint": "^10.0.2",
-    "fast-uri": "^3.1.2",
+    "fast-uri": "^3.1.4",
     "flatted": "3.4.2",
     "minimatch": "10.2.4",
-    "brace-expansion": "5.0.6",
+    "brace-expansion": "5.0.9",
+    "linkify-it": "^5.0.2",
     "lodash": "4.18.1"
   },
   "c8": {

package/scripts/doc-asserting-tests.js

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Runs (or lists) the test suites that assert on changed markdown.
+ *
+ * A markdown-only PR does not match the `paths:` filter in
+ * `.github/workflows/test.yml`, so the full matrix never runs and
+ * `required-checks-bypass.yml` reports the required "Test Suite" check green.
+ * Several suites nevertheless assert on markdown CONTENT, so such a PR merged
+ * green and then broke master for the next unrelated code PR — twice (kernel
+ * issue 63556816: the README size badge in #307/#310, and the AGENTS.md
+ * convention test after #325).
+ *
+ * This script closes that gap by running exactly the doc-asserting suites for the
+ * changed markdown. It shares `lib/doc-assertions.js` with the local push lane
+ * (`lib/commands/test.js`), so CI and local selection cannot drift apart.
+ *
+ * Usage:
+ *   node scripts/doc-asserting-tests.js [--base <ref>] [--list]
+ *
+ *   --base <ref>  Compare against <ref> (default: origin/<default-branch> or HEAD~1).
+ *   --list        Print the selected suites instead of running them.
+ */
+
+const { execFileSync, spawnSync } = require('node:child_process');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { selectDocAssertingTests } = require('../lib/doc-assertions');
+
+const REPO_ROOT = path.resolve(__dirname, '..');
+
+/** Wall-clock ceiling for the doc-asserting lane; it is a small, fast subset. */
+const LANE_TIMEOUT_MS = 5 * 60 * 1000;
+
+/**
+ * Parses the supported command-line flags.
+ *
+ * @param {string[]} argv Raw arguments (without node/script).
+ * @returns {{base: string|null, list: boolean}} Parsed options.
+ */
+function parseArgs(argv) {
+	const baseIndex = argv.indexOf('--base');
+	return {
+		base: baseIndex !== -1 ? argv[baseIndex + 1] || null : null,
+		list: argv.includes('--list'),
+	};
+}
+
+/**
+ * Resolves the ref the PR should be compared against.
+ *
+ * @param {string|null} explicitBase Base supplied with `--base`.
+ * @returns {string} A git ref usable in `git diff <ref>...HEAD`.
+ */
+function resolveBase(explicitBase) {
+	if (explicitBase) return explicitBase;
+	for (const ref of ['origin/master', 'origin/main']) {
+		try {
+			execFileSync('git', ['rev-parse', '--verify', ref], { cwd: REPO_ROOT, stdio: 'pipe', timeout: 5000 });
+			return ref;
+		} catch (_e) { /* intentional: ref not present in this checkout, try next */ } // NOSONAR S2486
+	}
+	return 'HEAD~1';
+}
+
+/**
+ * Parses `git diff --name-only` output into repository-relative paths.
+ *
+ * Split out so the parsing contract (trimmed, no blanks) is testable without a live
+ * repository: CI checks out shallow, so a test that reaches for `HEAD~1` passes locally
+ * and fails on the runner.
+ *
+ * @param {string} output Raw `git diff --name-only` stdout.
+ * @returns {string[]} Changed file paths.
+ */
+function parseChangedFiles(output) {
+	return output.split('\n').map((line) => line.trim()).filter(Boolean);
+}
+
+/**
+ * Lists repository-relative paths changed against the base ref.
+ *
+ * @param {string} base Base git ref.
+ * @returns {string[]} Changed file paths.
+ */
+function changedFilesSince(base) {
+	const output = execFileSync('git', ['diff', '--name-only', `${base}...HEAD`], {
+		cwd: REPO_ROOT,
+		encoding: 'utf8',
+		timeout: 15000,
+	});
+	return parseChangedFiles(output);
+}
+
+/**
+ * Turns a `spawnSync` result into a process exit status.
+ *
+ * A spawn that never produced a status (`error`, or killed by a signal so `status`
+ * is null) MUST report FAILURE. Reporting 0 there would re-create the bug this lane
+ * exists to remove: a required check reporting green without running the tests.
+ *
+ * @param {{status: number|null, error?: Error}} result Result of `spawnSync`.
+ * @returns {number} Exit status; non-zero whenever the run did not demonstrably pass.
+ */
+function resolveSpawnStatus(result) {
+	if (!result || result.error) return 1;
+	return result.status ?? 1;
+}
+
+function main() {
+	const { base: explicitBase, list } = parseArgs(process.argv.slice(2));
+	const base = resolveBase(explicitBase);
+
+	let changedFiles;
+	try {
+		changedFiles = changedFilesSince(base);
+	} catch (error) {
+		// Fail closed: if the change set cannot be determined we cannot prove the
+		// doc-asserting suites are unaffected.
+		console.error(`Could not compute changed files against ${base}: ${error.message}`);
+		return 1;
+	}
+
+	const suites = selectDocAssertingTests(changedFiles, REPO_ROOT, fs);
+
+	if (suites.length === 0) {
+		console.log('No changed markdown asserts on by any test suite — nothing to run.');
+		return 0;
+	}
+
+	if (list) {
+		console.log(suites.join('\n'));
+		return 0;
+	}
+
+	console.log(`Running ${suites.length} doc-asserting suite${suites.length === 1 ? '' : 's'} for changed markdown:`);
+	for (const suite of suites) console.log(`  ${suite}`);
+
+	const result = spawnSync('bun', ['test', ...suites], {
+		cwd: REPO_ROOT,
+		stdio: 'inherit',
+		timeout: LANE_TIMEOUT_MS,
+		shell: process.platform === 'win32',
+	});
+
+	if (result.error) {
+		console.error(`Failed to run doc-asserting suites: ${result.error.message}`);
+	}
+	return resolveSpawnStatus(result);
+}
+
+if (require.main === module) {
+	process.exit(main());
+}
+
+module.exports = { changedFilesSince, parseArgs, parseChangedFiles, resolveBase, resolveSpawnStatus };