forge-workflow 0.0.5 → 0.0.7

package/lib/file-utils.js

@@ -0,0 +1,260 @@
+/**
+ * file-utils.js — File I/O operations extracted from bin/forge.js
+ *
+ * All functions that previously relied on the module-level `projectRoot`
+ * variable now accept it as an explicit parameter.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+/**
+ * Read a file and return its contents as a UTF-8 string.
+ * @param {string} filePath - Absolute path to the file.
+ * @returns {string|null} File contents, or null on failure.
+ */
+function readFile(filePath) {
+  try {
+    return fs.readFileSync(filePath, 'utf8');
+  } catch (err) {
+    if (process.env.DEBUG) {
+      console.warn(`  ⚠ Could not read ${filePath}: ${err.message}`);
+    }
+    return null;
+  }
+}
+
+/**
+ * Write content to a file, creating parent directories as needed.
+ * Blocks path traversal outside projectRoot.
+ * @param {string} filePath - Relative path within projectRoot.
+ * @param {string} content - Content to write.
+ * @param {string} projectRoot - Absolute path to the project root.
+ * @returns {boolean} True on success, false on failure or blocked traversal.
+ */
+function writeFile(filePath, content, projectRoot) {
+  try {
+    const fullPath = path.resolve(projectRoot, filePath);
+    const resolvedProjectRoot = path.resolve(projectRoot);
+
+    // SECURITY: Prevent path traversal
+    if (fullPath !== resolvedProjectRoot && !fullPath.startsWith(resolvedProjectRoot + path.sep)) {
+      console.error(`  ✗ Security: Write path escape blocked: ${filePath}`);
+      return false;
+    }
+
+    const dir = path.dirname(fullPath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+    fs.writeFileSync(fullPath, content, { mode: 0o644 });
+    return true;
+  } catch (err) {
+    console.error(`  ✗ Failed to write ${filePath}: ${err.message}`);
+    return false;
+  }
+}
+
+/**
+ * Ensure a directory exists under projectRoot.
+ * Blocks path traversal outside projectRoot.
+ * @param {string} dir - Relative path within projectRoot.
+ * @param {string} projectRoot - Absolute path to the project root.
+ * @returns {boolean} True on success, false on blocked traversal.
+ */
+function ensureDir(dir, projectRoot) {
+  const fullPath = path.resolve(projectRoot, dir);
+  const resolvedProjectRoot = path.resolve(projectRoot);
+
+  // SECURITY: Prevent path traversal
+  if (fullPath !== resolvedProjectRoot && !fullPath.startsWith(resolvedProjectRoot + path.sep)) {
+    console.error(`  ✗ Security: Directory path escape blocked: ${dir}`);
+    return false;
+  }
+
+  if (!fs.existsSync(fullPath)) {
+    fs.mkdirSync(fullPath, { recursive: true });
+  }
+  return true;
+}
+
+/**
+ * Creates a directory on first use and prints a one-time purpose note.
+ * @param {string} dir - Absolute path to the directory to create.
+ * @param {string} purpose - Human-readable purpose description.
+ * @returns {string|null} Purpose message if created, null if already existed.
+ */
+function ensureDirWithNote(dir, purpose) {
+  if (fs.existsSync(dir)) {
+    return null;
+  }
+  fs.mkdirSync(dir, { recursive: true });
+  const display = dir.replaceAll('\\', '/');
+  const msg = `Created ${display} for ${purpose}`;
+  console.log(`  ${msg}`);
+  return msg;
+}
+
+/**
+ * Strip YAML frontmatter from markdown content.
+ * @param {string} content - Markdown string potentially containing frontmatter.
+ * @returns {string} Content without frontmatter.
+ */
+function stripFrontmatter(content) {
+  const match = content.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n([\s\S]*)$/); // NOSONAR — RegExp.exec blocked by security hook; match() equivalent here (no g flag)
+  return match ? match[1] : content;
+}
+
+/**
+ * Read the .env.local file from projectRoot.
+ * @param {string} projectRoot - Absolute path to the project root.
+ * @returns {string} File contents, or empty string if missing.
+ */
+function readEnvFile(projectRoot) {
+  const envPath = path.join(projectRoot, '.env.local');
+  try {
+    if (fs.existsSync(envPath)) {
+      return fs.readFileSync(envPath, 'utf8');
+    }
+  } catch (err) {
+    // File read failure is acceptable - file may not exist or have permission issues
+    // Return empty string to allow caller to proceed with defaults
+    console.warn('Failed to read .env.local:', err.message);
+  }
+  return '';
+}
+
+/**
+ * Parse .env.local and return key-value pairs.
+ * @param {string} projectRoot - Absolute path to the project root.
+ * @returns {Object} Parsed key-value pairs.
+ */
+function parseEnvFile(projectRoot) {
+  const content = readEnvFile(projectRoot);
+  const lines = content.split(/\r?\n/);
+  const vars = {};
+  lines.forEach(line => {
+    const match = line.match(/^([A-Z_]+)=(.*)$/); // NOSONAR — RegExp.exec blocked by security hook; match() equivalent here (no g flag)
+    if (match) {
+      vars[match[1]] = match[2];
+    }
+  });
+  return vars;
+}
+
+/**
+ * Write or update .env.local — PRESERVES existing values by default.
+ * @param {Object} tokens - Key-value pairs to write.
+ * @param {boolean} [preserveExisting=true] - Whether to preserve existing values.
+ * @param {string} projectRoot - Absolute path to the project root.
+ * @returns {{ added: string[], preserved: string[] }} Keys added and preserved.
+ */
+function writeEnvTokens(tokens, projectRoot, preserveExisting = true) {
+  const envPath = path.join(projectRoot, '.env.local');
+  let content = readEnvFile(projectRoot);
+
+  // Parse existing content (handle both CRLF and LF line endings)
+  const lines = content.split(/\r?\n/);
+  const existingVars = {};
+  const existingKeys = new Set();
+  lines.forEach(line => {
+    const match = line.match(/^([A-Z_]+)=/); // NOSONAR — RegExp.exec blocked by security hook; match() equivalent here (no g flag)
+    if (match) {
+      existingVars[match[1]] = line;
+      existingKeys.add(match[1]);
+    }
+  });
+
+  // Track what was added vs preserved
+  let added = [];
+  let preserved = [];
+
+  // Add/update tokens - PRESERVE existing values if preserveExisting is true
+  Object.entries(tokens).forEach(([key, value]) => {
+    if (value?.trim()) {
+      if (preserveExisting && existingKeys.has(key)) {
+        // Keep existing value, don't overwrite
+        preserved.push(key);
+      } else {
+        // Add new token
+        existingVars[key] = `${key}=${value.trim()}`;
+        added.push(key);
+      }
+    }
+  });
+
+  // Rebuild file with comments
+  const outputLines = [];
+
+  // Add header if new file
+  if (!content.includes('# External Service API Keys')) {
+    outputLines.push(
+      '# External Service API Keys for Forge Workflow',
+      '# Get your keys from:',
+      '#   Parallel AI: https://platform.parallel.ai',
+      '#   Greptile: https://app.greptile.com/api',
+      '#   SonarCloud: https://sonarcloud.io/account/security',
+      ''
+    );
+  }
+
+  // Add existing content (preserve order and comments)
+  lines.forEach(line => {
+    const match = line.match(/^([A-Z_]+)=/); // NOSONAR — RegExp.exec blocked by security hook; match() equivalent here (no g flag)
+    if (match && existingVars[match[1]]) {
+      outputLines.push(existingVars[match[1]]);
+      delete existingVars[match[1]]; // Mark as added
+    } else if (line.trim()) {
+      outputLines.push(line);
+    }
+  });
+
+  // Add any new tokens not in original file
+  Object.values(existingVars).forEach(line => {
+    outputLines.push(line);
+  });
+
+  // Ensure ends with newline
+  let finalContent = outputLines.join('\n').trim() + '\n';
+
+  fs.writeFileSync(envPath, finalContent);
+
+  // OWASP A02: Set restrictive permissions on .env.local (contains API keys)
+  // On Windows, chmod is a no-op so we skip it
+  if (process.platform !== 'win32') {
+    try {
+      fs.chmodSync(envPath, 0o600);
+    } catch (_err) { // NOSONAR — chmod failure is non-fatal, file was still written
+      // chmod failure is non-fatal — file was still written successfully
+    }
+  }
+
+  // Add .env.local to .gitignore if not present
+  const gitignorePath = path.join(projectRoot, '.gitignore');
+  try {
+    let gitignore = '';
+    if (fs.existsSync(gitignorePath)) {
+      gitignore = fs.readFileSync(gitignorePath, 'utf8');
+    }
+    if (!gitignore.includes('.env.local')) {
+      fs.appendFileSync(gitignorePath, '\n# Local environment variables\n.env.local\n');
+    }
+  } catch (err) {
+    // Gitignore update is optional - failure doesn't prevent .env.local creation
+    // User can manually add .env.local to .gitignore if needed
+    console.warn('Failed to update .gitignore:', err.message);
+  }
+
+  return { added, preserved };
+}
+
+module.exports = {
+  readFile,
+  writeFile,
+  ensureDir,
+  ensureDirWithNote,
+  stripFrontmatter,
+  readEnvFile,
+  parseEnvFile,
+  writeEnvTokens,
+};

package/lib/forge-context.js

@@ -0,0 +1,42 @@
+'use strict';
+
+/**
+ * ForgeContext — Mutable state container for the Forge CLI.
+ *
+ * Replaces the module-level globals in bin/forge.js with a single
+ * injectable object, making state explicit and testable.
+ *
+ * Mirrors the globals: projectRoot, FORCE_MODE, VERBOSE_MODE,
+ * NON_INTERACTIVE, SYMLINK_ONLY, SYNC_ENABLED, actionLog,
+ * PKG_MANAGER, and packageDir.
+ *
+ * @module forge-context
+ */
+
+class ForgeContext { // NOSONAR — constructor-only class is intentional: serves as typed state container, methods will be added as CLI evolves
+  /**
+   * @param {object} [options]
+   * @param {string}   [options.projectRoot]    - Project root directory
+   * @param {boolean}  [options.forceMode]      - Force overwrite (--force)
+   * @param {boolean}  [options.verboseMode]    - Verbose output (--verbose)
+   * @param {boolean}  [options.nonInteractive] - Skip prompts (--quick / --yes)
+   * @param {boolean}  [options.symlinkOnly]    - Fail instead of copy fallback (--symlink)
+   * @param {boolean}  [options.syncEnabled]    - Scaffold Beads GitHub sync (--sync)
+   * @param {string}   [options.pkgManager]     - Detected package manager
+   * @param {Array}    [options.actionLog]      - Incremental setup action log
+   * @param {string}   [options.packageDir]     - Forge package directory
+   */
+  constructor(options = {}) {
+    this.projectRoot = options.projectRoot || process.cwd();
+    this.forceMode = options.forceMode || false;
+    this.verboseMode = options.verboseMode || false;
+    this.nonInteractive = options.nonInteractive || false;
+    this.symlinkOnly = options.symlinkOnly || false;
+    this.syncEnabled = options.syncEnabled || false;
+    this.pkgManager = options.pkgManager || 'npm';
+    this.actionLog = options.actionLog || [];
+    this.packageDir = options.packageDir || '';
+  }
+}
+
+module.exports = { ForgeContext };

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/frontmatter.js

@@ -0,0 +1,79 @@
+'use strict';
+
+/**
+ * @module frontmatter
+ *
+ * Utility for parsing and manipulating YAML frontmatter using gray-matter.
+ *
+ * This is the canonical frontmatter library for runtime code that needs
+ * full gray-matter capabilities (e.g., commands-reset, plugin transforms).
+ *
+ * Note: scripts/sync-commands.js uses its own hand-rolled YAML parser
+ * (via the `yaml` package) because sync runs at build time and must not
+ * depend on gray-matter being installed in the target project.
+ *
+ * @example
+ *   const { parse, stringify, stripAll, keepOnly } = require('./frontmatter');
+ *   const { data, content } = parse(raw);
+ *   const rebuilt = stringify(data, content);
+ */
+
+const matter = require('gray-matter');
+
+/**
+ * Parse YAML frontmatter from a markdown string.
+ *
+ * @param {string} content - Raw file content with optional frontmatter
+ * @returns {{ data: Record<string, unknown>, content: string }}
+ */
+function parse(content) {
+  const result = matter(content);
+  return { data: result.data, content: result.content };
+}
+
+/**
+ * Build a file string from frontmatter data and body content.
+ *
+ * @param {Record<string, unknown>} data - Key-value pairs for the YAML block
+ * @param {string} content - The markdown body content
+ * @returns {string}
+ */
+function stringify(data, content) {
+  return matter.stringify(content, data);
+}
+
+/**
+ * Strip all frontmatter, returning only the body content.
+ *
+ * @param {string} content - Raw file content with optional frontmatter
+ * @returns {string} Body content without frontmatter
+ */
+function stripAll(content) {
+  const result = matter(content);
+  return result.content;
+}
+
+/**
+ * Keep only specified fields in frontmatter, strip the rest.
+ *
+ * If none of the specified fields exist, returns body only (no frontmatter).
+ *
+ * @param {string} content - Raw file content with optional frontmatter
+ * @param {string[]} fields - Field names to keep
+ * @returns {string} Rebuilt file with filtered frontmatter
+ */
+function keepOnly(content, fields) {
+  const result = matter(content);
+  const filtered = {};
+  for (const field of fields) {
+    if (Object.hasOwn(result.data, field)) {
+      filtered[field] = result.data[field];
+    }
+  }
+  if (Object.keys(filtered).length === 0) {
+    return result.content;
+  }
+  return matter.stringify(result.content, filtered);
+}
+
+module.exports = { parse, stringify, stripAll, keepOnly };

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 };