forge-workflow 0.0.5 → 0.0.6

package/lib/freshness-token.js

@@ -0,0 +1,148 @@
+/**
+ * Freshness Token — Validate/Ship stage freshness state
+ *
+ * Tracks whether `main` has moved forward since /validate ran,
+ * so /ship can warn if validation results are stale.
+ *
+ * Token file: `<projectRoot>/.forge-freshness` (ephemeral, gitignored)
+ *
+ * @module freshness-token
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+const TOKEN_FILENAME = '.forge-freshness';
+
+/**
+ * Get the current git branch name.
+ * @param {string} projectRoot - Absolute path to the project root.
+ * @returns {string} Current branch name.
+ */
+function getCurrentBranch(projectRoot) {
+  // Safe: execFileSync with array args prevents injection (OWASP A03). PATH is OS-controlled.
+  return execFileSync('git', ['-C', projectRoot, 'rev-parse', '--abbrev-ref', 'HEAD'], {
+    encoding: 'utf8'
+  }).trim();
+}
+
+/**
+ * Detect the default branch (main, master, develop, trunk).
+ * @param {string} projectRoot - Absolute path to the project root.
+ * @returns {string} Default branch name.
+ */
+function getDefaultBranch(projectRoot) {
+  try {
+    // Safe: execFileSync with array args prevents injection (OWASP A03). PATH is OS-controlled.
+    return execFileSync('git', ['-C', projectRoot, 'rev-parse', '--abbrev-ref', 'origin/HEAD'], {
+      encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe']
+    }).trim().replace('origin/', '');
+  } catch (_e) { /* intentional: origin/HEAD not set, probe common branch names */ // NOSONAR S2486
+    for (const name of ['main', 'master', 'develop', 'trunk']) {
+      try {
+        // Safe: execFileSync with array args prevents injection (OWASP A03). PATH is OS-controlled.
+        execFileSync('git', ['-C', projectRoot, 'rev-parse', '--verify', name], { stdio: 'pipe' });
+        return name;
+      } catch (_e2) { /* intentional: branch doesn't exist, try next name */ } // NOSONAR S2486
+    }
+    return 'main';
+  }
+}
+
+/**
+ * Get the merge-base commit between HEAD and the default branch.
+ * @param {string} projectRoot - Absolute path to the project root.
+ * @returns {string} The merge-base commit SHA.
+ * @throws {Error} If git merge-base fails (no common ancestor, detached HEAD, etc.)
+ */
+function getMergeBase(projectRoot) {
+  const base = getDefaultBranch(projectRoot);
+  try {
+    // Safe: execFileSync with array args prevents injection (OWASP A03). PATH is OS-controlled.
+    return execFileSync('git', ['-C', projectRoot, 'merge-base', 'HEAD', base], {
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe']
+    }).trim();
+  } catch (err) {
+    throw new Error(
+      `Failed to compute merge-base for HEAD and ${base} in "${projectRoot}": ${err.message}`
+    );
+  }
+}
+
+/**
+ * Write a freshness token to `<projectRoot>/.forge-freshness`.
+ *
+ * Records the current branch, base commit (merge-base HEAD main),
+ * and a timestamp so /ship can detect if validation is stale.
+ *
+ * @param {string} projectRoot - Absolute path to the project root.
+ * @returns {{ timestamp: number, branch: string, baseCommit: string }} The written token.
+ * @throws {Error} If git merge-base fails (no common ancestor, detached HEAD, etc.)
+ */
+function writeFreshnessToken(projectRoot) {
+  const branch = getCurrentBranch(projectRoot);
+  const baseCommit = getMergeBase(projectRoot);
+
+  const token = {
+    timestamp: Date.now(),
+    branch,
+    baseCommit
+  };
+
+  const tokenPath = path.join(projectRoot, TOKEN_FILENAME);
+  fs.writeFileSync(tokenPath, JSON.stringify(token, null, 2), 'utf8');
+
+  return token;
+}
+
+/**
+ * Read and parse the freshness token from `<projectRoot>/.forge-freshness`.
+ *
+ * @param {string} projectRoot - Absolute path to the project root.
+ * @returns {{ timestamp: number, branch: string, baseCommit: string } | null}
+ *   The token object, or null if the file is missing or corrupted.
+ */
+function readFreshnessToken(projectRoot) {
+  const tokenPath = path.join(projectRoot, TOKEN_FILENAME);
+
+  try {
+    const content = fs.readFileSync(tokenPath, 'utf8');
+    return JSON.parse(content);
+  } catch (_err) { /* intentional: missing file (ENOENT), corrupted JSON, or empty file — return null */ // NOSONAR S2486
+    return null;
+  }
+}
+
+/**
+ * Check if a freshness token is stale.
+ *
+ * A token is stale when:
+ * - It is null (missing or corrupted)
+ * - The current merge-base differs from the token's baseCommit
+ *   (meaning main has moved forward since validation)
+ * - git merge-base fails (can't verify freshness)
+ *
+ * @param {{ timestamp: number, branch: string, baseCommit: string } | null} token
+ * @param {string} projectRoot - Absolute path to the project root.
+ * @returns {boolean} True if validation results are stale and should be re-run.
+ */
+function isStale(token, projectRoot) {
+  if (token === null) {
+    return true;
+  }
+
+  try {
+    const currentBase = getMergeBase(projectRoot);
+    return currentBase !== token.baseCommit;
+  } catch (_err) { /* intentional: merge-base failed, treat as stale since freshness can't be verified */ // NOSONAR S2486
+    return true;
+  }
+}
+
+module.exports = {
+  writeFreshnessToken,
+  readFreshnessToken,
+  isStale
+};

package/lib/greptile-match.js

@@ -0,0 +1,80 @@
+'use strict';
+
+const { execFileSync } = require('node:child_process');
+
+/**
+ * Match unresolved review threads to recent commits that touched the same files.
+ *
+ * For each thread, runs `git log --oneline --follow -- <file>` to find
+ * recent commits. If a commit exists, the thread is considered resolved
+ * (the file was modified after the review comment).
+ *
+ * Uses execFileSync (not exec) to prevent shell injection (OWASP A03).
+ *
+ * @param {Array<{file: string, line: number}>} threads - Review threads with file paths
+ * @param {string} projectRoot - Absolute path to the project root (used with git -C)
+ * @param {object} [opts] - Options
+ * @param {Function} [opts._exec] - Injected exec function for testing (defaults to execFileSync)
+ * @param {string} [opts.sinceCommit] - Merge-base SHA to restrict log to PR commits only
+ * @returns {Array<{file: string, line: number, resolved: boolean, sha?: string, reason?: string}>}
+ */
+function matchThreadsToCommits(threads, projectRoot, opts = {}) {
+  if (!threads || threads.length === 0) {
+    return [];
+  }
+
+  const exec = opts._exec || ((cmd, args) => {
+    return execFileSync(cmd, args, { encoding: 'utf8' });
+  });
+
+  // Determine commit range — restrict to PR commits when sinceCommit provided
+  let sinceCommit = opts.sinceCommit;
+  if (!sinceCommit) {
+    try {
+      sinceCommit = exec('git', ['-C', projectRoot, 'merge-base', 'HEAD', 'main']).trim();
+    } catch (_e) { // NOSONAR S2486
+      /* intentional: main branch not found, try master instead */
+      try {
+        sinceCommit = exec('git', ['-C', projectRoot, 'merge-base', 'HEAD', 'master']).trim();
+      } catch (_e2) { /* intentional: no merge-base available, fall back to unbounded log */ // NOSONAR S2486
+        sinceCommit = null;
+      }
+    }
+  }
+
+  return threads.map((thread) => {
+    const { file, line } = thread;
+
+    try {
+      const logArgs = [
+        '-C', projectRoot,
+        'log',
+        '--oneline',
+        '--follow',
+      ];
+      if (sinceCommit) {
+        logArgs.push(`${sinceCommit}..HEAD`);
+      }
+      logArgs.push('--', file);
+
+      const output = exec('git', logArgs);
+
+      const trimmed = (output || '').trim();
+
+      if (!trimmed) {
+        return { file, line, resolved: false, reason: 'no matching commit' };
+      }
+
+      // git log --oneline format: "<sha> <message>"
+      // Take the first (most recent) line
+      const firstLine = trimmed.split('\n')[0];
+      const sha = firstLine.split(' ')[0];
+
+      return { file, line, resolved: true, sha };
+    } catch (_err) { /* intentional: git log failed (file missing or git unavailable), mark unresolved */ // NOSONAR S2486
+      return { file, line, resolved: false, reason: 'no matching commit' };
+    }
+  });
+}
+
+module.exports = { matchThreadsToCommits };

package/lib/reset.js

@@ -0,0 +1,309 @@
+const fs = require('node:fs');
+const path = require('node:path');
+
+/**
+ * Known forge-created file patterns.
+ * Used to distinguish forge files from user-created files.
+ */
+const FORGE_COMMANDS = [
+  '.claude/commands/plan.md',
+  '.claude/commands/dev.md',
+  '.claude/commands/validate.md',
+  '.claude/commands/ship.md',
+  '.claude/commands/review.md',
+  '.claude/commands/premerge.md',
+  '.claude/commands/verify.md',
+  '.claude/commands/status.md',
+  '.claude/commands/preflight.md',
+];
+
+const FORGE_RULES = [
+  '.claude/rules/workflow.md',
+  '.claude/rules/greptile-review-process.md',
+];
+
+const FORGE_SCRIPTS = [
+  '.claude/scripts/greptile-resolve.sh',
+  '.claude/scripts/validate.sh',
+];
+
+const FORGE_WORKFLOWS = [
+  '.github/workflows/beads-to-github.yml',
+  '.github/workflows/github-to-beads.yml',
+];
+
+const FORGE_DOCS = [
+  'docs/forge/TOOLCHAIN.md',
+  'docs/forge/VALIDATION.md',
+];
+
+const FORGE_AGENT_DIRS = [
+  '.cursor',
+  '.cline',
+  '.roo',
+  '.codex',
+  '.kilocode',
+  '.opencode',
+];
+
+const FORGE_SYNC_SCRIPTS_DIR = 'scripts/github-beads-sync';
+
+/**
+ * Get categorized lists of forge-managed files in a project.
+ * Only returns files that actually exist on disk and are known forge templates.
+ * User-created files are excluded.
+ *
+ * @param {string} projectRoot - Project root directory
+ * @returns {{
+ *   config: string[],
+ *   commands: string[],
+ *   rules: string[],
+ *   scripts: string[],
+ *   docs: string[],
+ *   agentDirs: string[],
+ *   workflows: string[],
+ *   syncScripts: string[]
+ * }}
+ */
+function getForgeFiles(projectRoot) {
+  const result = {
+    config: [],
+    commands: [],
+    rules: [],
+    scripts: [],
+    docs: [],
+    agentDirs: [],
+    workflows: [],
+    syncScripts: [],
+  };
+
+  // .forge/ directory
+  if (fs.existsSync(path.join(projectRoot, '.forge'))) {
+    result.config.push('.forge');
+  }
+
+  // Known forge commands (static list)
+  for (const f of FORGE_COMMANDS) {
+    if (fs.existsSync(path.join(projectRoot, f))) {
+      result.commands.push(f);
+    }
+  }
+
+  // Dynamic discovery: scan the package's .claude/commands/ directory to find
+  // any commands that setup may have copied but aren't in the static list.
+  // Only files that exist in both the package source AND the project are included.
+  const packageCommandsDir = path.join(__dirname, '..', '.claude', 'commands');
+  try {
+    const packageEntries = fs.readdirSync(packageCommandsDir);
+    for (const entry of packageEntries) {
+      if (entry.endsWith('.md')) {
+        const relPath = `.claude/commands/${entry}`;
+        if (!result.commands.includes(relPath) &&
+            fs.existsSync(path.join(projectRoot, relPath))) {
+          result.commands.push(relPath);
+        }
+      }
+    }
+  } catch (_error) {
+    // Package commands directory read failed, skip
+  }
+
+  // Known forge rules
+  for (const f of FORGE_RULES) {
+    if (fs.existsSync(path.join(projectRoot, f))) {
+      result.rules.push(f);
+    }
+  }
+
+  // Known forge scripts
+  for (const f of FORGE_SCRIPTS) {
+    if (fs.existsSync(path.join(projectRoot, f))) {
+      result.scripts.push(f);
+    }
+  }
+
+  // Known forge docs
+  for (const f of FORGE_DOCS) {
+    if (fs.existsSync(path.join(projectRoot, f))) {
+      result.docs.push(f);
+    }
+  }
+
+  // Agent directories (only if they exist)
+  for (const dir of FORGE_AGENT_DIRS) {
+    if (fs.existsSync(path.join(projectRoot, dir))) {
+      result.agentDirs.push(dir);
+    }
+  }
+
+  // Beads workflow files
+  for (const f of FORGE_WORKFLOWS) {
+    if (fs.existsSync(path.join(projectRoot, f))) {
+      result.workflows.push(f);
+    }
+  }
+
+  // Sync scripts directory
+  const syncDir = path.join(projectRoot, FORGE_SYNC_SCRIPTS_DIR);
+  if (fs.existsSync(syncDir)) {
+    try {
+      const entries = fs.readdirSync(syncDir);
+      for (const entry of entries) {
+        const relPath = [FORGE_SYNC_SCRIPTS_DIR, entry].join('/');
+        result.syncScripts.push(relPath);
+      }
+    } catch (_error) {
+      // Directory read failed, skip
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Remove .forge/ directory only (soft reset).
+ * Requires force=true to proceed.
+ *
+ * @param {string} projectRoot - Project root directory
+ * @param {{ force?: boolean }} options
+ * @returns {{ removed: string[], preserved: string[] }}
+ */
+function resetSoft(projectRoot, { force = false } = {}) {
+  if (!force) {
+    throw new Error('Soft reset requires --force flag. This will remove .forge/ directory.');
+  }
+
+  const removed = [];
+  const preserved = [];
+
+  const forgePath = path.join(projectRoot, '.forge');
+  if (fs.existsSync(forgePath)) {
+    fs.rmSync(forgePath, { recursive: true, force: true });
+    removed.push('.forge');
+  }
+
+  // Record what was preserved
+  const inventory = getForgeFiles(projectRoot);
+  for (const f of [...inventory.commands, ...inventory.rules, ...inventory.scripts]) {
+    preserved.push(f);
+  }
+  for (const dir of inventory.agentDirs) {
+    preserved.push(dir);
+  }
+
+  return { removed, preserved };
+}
+
+/**
+ * Remove ALL forge-managed files (hard reset).
+ * Preserves user-created files not in forge template list.
+ * Requires force=true to proceed.
+ *
+ * @param {string} projectRoot - Project root directory
+ * @param {{ force?: boolean }} options
+ * @returns {{ removed: string[], preserved: string[] }}
+ */
+function resetHard(projectRoot, { force = false } = {}) {
+  if (!force) {
+    throw new Error('Hard reset requires --force flag. This will remove ALL forge files.');
+  }
+
+  const removed = [];
+  const preserved = [];
+  const inventory = getForgeFiles(projectRoot);
+
+  // Remove .forge/ directory
+  for (const dir of inventory.config) {
+    const fullPath = path.join(projectRoot, dir);
+    if (fs.existsSync(fullPath)) {
+      fs.rmSync(fullPath, { recursive: true, force: true });
+      removed.push(dir);
+    }
+  }
+
+  // Remove individual forge files
+  const allFiles = [
+    ...inventory.commands,
+    ...inventory.rules,
+    ...inventory.scripts,
+    ...inventory.docs,
+    ...inventory.workflows,
+    ...inventory.syncScripts,
+  ];
+
+  for (const f of allFiles) {
+    const fullPath = path.join(projectRoot, f);
+    if (fs.existsSync(fullPath)) {
+      fs.rmSync(fullPath, { recursive: true, force: true });
+      removed.push(f);
+    }
+  }
+
+  // Remove sync scripts directory if it still exists (empty after file removal)
+  const syncDir = path.join(projectRoot, FORGE_SYNC_SCRIPTS_DIR);
+  if (fs.existsSync(syncDir)) {
+    fs.rmSync(syncDir, { recursive: true, force: true });
+    removed.push(FORGE_SYNC_SCRIPTS_DIR);
+  }
+
+  // Remove docs/forge/ directory if empty after file removal
+  const docsForgeDir = path.join(projectRoot, 'docs', 'forge');
+  if (fs.existsSync(docsForgeDir)) {
+    try {
+      const remaining = fs.readdirSync(docsForgeDir);
+      if (remaining.length === 0) {
+        fs.rmSync(docsForgeDir, { recursive: true, force: true });
+        removed.push('docs/forge');
+      }
+    } catch (_error) {
+      // Directory read failed, skip
+    }
+  }
+
+  // Remove agent directories
+  for (const dir of inventory.agentDirs) {
+    const fullPath = path.join(projectRoot, dir);
+    if (fs.existsSync(fullPath)) {
+      fs.rmSync(fullPath, { recursive: true, force: true });
+      removed.push(dir);
+    }
+  }
+
+  return { removed, preserved };
+}
+
+/**
+ * Remove all forge files and re-run setup (reinstall).
+ * Accepts a setupFn parameter for testability.
+ *
+ * @param {string} projectRoot - Project root directory
+ * @param {{ force?: boolean, setupFn?: Function }} options
+ * @returns {Promise<{ resetResult: object, setupResult: any }>}
+ */
+async function reinstall(projectRoot, { force = false, setupFn } = {}) {
+  if (!force) {
+    throw new Error('Reinstall requires --force flag.');
+  }
+
+  const resetResult = resetHard(projectRoot, { force: true });
+
+  let setupResult = null;
+  if (setupFn) {
+    setupResult = await setupFn(projectRoot);
+  }
+
+  return { resetResult, setupResult };
+}
+
+module.exports = {
+  getForgeFiles,
+  resetSoft,
+  resetHard,
+  reinstall,
+  FORGE_COMMANDS,
+  FORGE_RULES,
+  FORGE_SCRIPTS,
+  FORGE_DOCS,
+  FORGE_WORKFLOWS,
+  FORGE_AGENT_DIRS,
+};

package/lib/task-ownership.js

@@ -0,0 +1,117 @@
+'use strict';
+
+/**
+ * Parse a task list markdown file and validate file ownership.
+ * Within each wave, no two tasks may own the same file.
+ * Cross-wave ownership is allowed (sequential execution prevents conflicts).
+ *
+ * @param {string} content - task list markdown content
+ * @returns {{ valid: boolean, violations: Array<{wave: number, task1: number, task2: number, file: string}> }}
+ */
+function validateOwnership(content) {
+  const lines = content.split('\n');
+  const violations = [];
+
+  const wavePattern = /^## Wave (\d+)/;
+  const taskPattern = /^### Task (\d+)/;
+  const ownsPattern = /\*\*OWNS\*\*:\s*(.+)/;
+
+  let currentWave = null;
+  let currentTask = null;
+  // Map: wave number -> Map of file -> first task number that owns it
+  const waveOwnership = new Map();
+
+  for (const line of lines) {
+    const parsed = parseWaveAndTask(line, wavePattern, taskPattern, currentWave, currentTask, waveOwnership);
+    if (parsed.matched) {
+      currentWave = parsed.currentWave;
+      currentTask = parsed.currentTask;
+      continue;
+    }
+
+    if (currentWave !== null && currentTask !== null) {
+      const ownedFiles = extractOwnedFiles(line, ownsPattern);
+      if (ownedFiles) {
+        checkOwnership(ownedFiles, waveOwnership.get(currentWave), currentWave, currentTask, violations);
+      }
+    }
+  }
+
+  return {
+    valid: violations.length === 0,
+    violations,
+  };
+}
+
+/**
+ * Parse a line for wave or task headers and update state accordingly.
+ * @param {string} line - Current line of markdown
+ * @param {RegExp} wavePattern - Pattern to match wave headers
+ * @param {RegExp} taskPattern - Pattern to match task headers
+ * @param {number|null} currentWave - Current wave number
+ * @param {number|null} currentTask - Current task number
+ * @param {Map} waveOwnership - Wave ownership map to initialize new waves
+ * @returns {{ matched: boolean, currentWave: number|null, currentTask: number|null }}
+ */
+function parseWaveAndTask(line, wavePattern, taskPattern, currentWave, currentTask, waveOwnership) {
+  const waveMatch = wavePattern.exec(line);
+  if (waveMatch) {
+    const wave = Number.parseInt(waveMatch[1], 10);
+    if (!waveOwnership.has(wave)) {
+      waveOwnership.set(wave, new Map());
+    }
+    return { matched: true, currentWave: wave, currentTask: null };
+  }
+
+  const taskMatch = taskPattern.exec(line);
+  if (taskMatch) {
+    return { matched: true, currentWave, currentTask: Number.parseInt(taskMatch[1], 10) };
+  }
+
+  return { matched: false, currentWave, currentTask };
+}
+
+/**
+ * Extract owned file paths from an OWNS line.
+ * @param {string} line - Current line of markdown
+ * @param {RegExp} ownsPattern - Pattern to match OWNS declarations
+ * @returns {string[]|null} Array of file paths, or null if line is not an OWNS line
+ */
+function extractOwnedFiles(line, ownsPattern) {
+  const ownsMatch = ownsPattern.exec(line);
+  if (!ownsMatch) return null;
+
+  const filesRaw = ownsMatch[1];
+  const fileMatches = filesRaw.match(/`([^`]+)`/g);
+  if (!fileMatches) return null;
+
+  return fileMatches.map((f) => f.replaceAll('`', ''));
+}
+
+/**
+ * Check for ownership violations and record them.
+ * @param {string[]} files - Files declared as owned
+ * @param {Map<string, number>} ownership - File-to-task ownership map for the current wave
+ * @param {number} currentWave - Current wave number
+ * @param {number} currentTask - Current task number
+ * @param {Array} violations - Array to push violations into
+ */
+function checkOwnership(files, ownership, currentWave, currentTask, violations) {
+  for (const file of files) {
+    if (ownership.has(file)) {
+      const firstTask = ownership.get(file);
+      if (firstTask !== currentTask) {
+        violations.push({
+          wave: currentWave,
+          task1: firstTask,
+          task2: currentTask,
+          file,
+        });
+      }
+    } else {
+      ownership.set(file, currentTask);
+    }
+  }
+}
+
+module.exports = { validateOwnership };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-workflow",
-  "version": "0.0.5",
+  "version": "0.0.6",
   "description": "7-stage TDD workflow for ALL AI coding agents (Claude, Cursor, Cline, OpenCode, Copilot, Kilo Code, Roo Code, Codex)",
   "bin": {
     "forge": "bin/forge.js",
@@ -10,7 +10,7 @@
     "packages/*"
   ],
   "scripts": {
-    "test": "bun test",
+    "test": "bun test --timeout 15000",
     "test:setup": "bash test-env/automation/setup-fixtures.sh",
     "test:all": "bun run test:setup && bun test",
     "test:coverage": "c8 --check-coverage bun test",