forge-workflow 0.0.5 → 0.0.7

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/runtime-health.js

@@ -0,0 +1,305 @@
+/**
+ * Runtime prerequisite checks for stage entry.
+ *
+ * This module centralizes the hard-stop decision for hooks, shell helpers,
+ * and toolchain prerequisites so stage commands do not have to infer readiness.
+ *
+ * @module lib/runtime-health
+ */
+
+const fs = require('node:fs');
+const { execFileSync: defaultExecFileSync } = require('node:child_process');
+
+const { checkLefthookStatus } = require('./lefthook-check');
+
+const WINDOWS_GIT_BASH_CANDIDATES = [
+  String.raw`C:\Program Files\Git\bin\bash.exe`,
+  String.raw`C:\Program Files (x86)\Git\bin\bash.exe`,
+  `${process.env.LOCALAPPDATA ?? ''}${String.raw`\Programs\Git\bin\bash.exe`}`
+].filter(Boolean);
+
+function toText(output) {
+  if (typeof output === 'string') return output;
+  if (Buffer.isBuffer(output)) return output.toString('utf8');
+  return output == null ? '' : String(output);
+}
+
+function normalizeHooksPath(value, platform = process.platform) {
+  let normalized = toText(value).trim().replaceAll('\\', '/');
+
+  while (normalized.endsWith('/')) {
+    normalized = normalized.slice(0, -1);
+  }
+
+  while (normalized.startsWith('./')) {
+    normalized = normalized.slice(2);
+  }
+
+  if (platform === 'win32') {
+    normalized = normalized.toLowerCase();
+  }
+
+  return normalized;
+}
+
+function createDiagnostic(code, subject, message, repair) {
+  return {
+    code,
+    subject,
+    severity: 'hard-stop',
+    message,
+    ...(repair ? { repair } : {})
+  };
+}
+
+function isUsableWindowsShellCandidate(candidate, options = {}) {
+  if (typeof options._canExecute === 'function') {
+    try {
+      return Boolean(options._canExecute(candidate));
+    } catch {
+      return false;
+    }
+  }
+
+  try {
+    defaultExecFileSync(candidate, ['--version'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore']
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function checkHookInstallation(projectRoot, options = {}) {
+  const exec = options._exec || defaultExecFileSync;
+  const platform = options.platform || process.platform;
+  const expectedRelativeHooksPath = normalizeHooksPath('.lefthook/hooks', platform);
+  const expectedAbsoluteHooksPath = normalizeHooksPath(`${projectRoot}/${expectedRelativeHooksPath}`, platform);
+
+  try {
+    const output = exec('git', ['config', '--get', 'core.hooksPath'], {
+      cwd: projectRoot,
+      encoding: 'utf8'
+    });
+
+    const hooksPath = normalizeHooksPath(output, platform);
+    const active = hooksPath === expectedRelativeHooksPath || hooksPath === expectedAbsoluteHooksPath;
+
+    return {
+      active,
+      state: active ? 'active' : 'inactive',
+      hooksPath: hooksPath || null,
+      message: active ? '' : 'Git hooks are not pointed at .lefthook/hooks.'
+    };
+  } catch {
+    return {
+      active: false,
+      state: 'unverified',
+      hooksPath: null,
+      message: 'Git hooks could not be verified.'
+    };
+  }
+}
+
+function checkCommandAvailability(command, projectRoot, options = {}) {
+  const exec = options._exec || defaultExecFileSync;
+
+  try {
+    const output = exec(command, ['--version'], {
+      cwd: projectRoot,
+      encoding: 'utf8'
+    });
+
+    return {
+      available: true,
+      state: 'available',
+      command,
+      output: toText(output).trim(),
+      message: ''
+    };
+  } catch (err) {
+    return {
+      available: false,
+      state: 'missing',
+      command,
+      output: '',
+      message: err?.message ?? `${command} is unavailable`
+    };
+  }
+}
+
+function resolveShellRuntime(options = {}) {
+  const platform = options.platform || process.platform;
+
+  if (platform !== 'win32') {
+    return {
+      available: true,
+      state: 'available',
+      platform,
+      policy: 'system-shell',
+      command: options.command || 'sh',
+      message: ''
+    };
+  }
+
+  const candidates = Object.hasOwn(options, 'candidates')
+    ? options.candidates
+    : WINDOWS_GIT_BASH_CANDIDATES;
+
+  const exists = options._exists || fs.existsSync;
+  if (Array.isArray(candidates)) {
+    let unusableCandidate = null;
+
+    for (const candidate of candidates) {
+      if (!candidate || !exists(candidate)) {
+        continue;
+      }
+
+      if (isUsableWindowsShellCandidate(candidate, options)) {
+        return {
+          available: true,
+          state: 'available',
+          platform,
+          policy: 'git-bash',
+          command: candidate,
+          message: ''
+        };
+      }
+
+      unusableCandidate = candidate;
+    }
+
+    if (unusableCandidate) {
+      return {
+        available: false,
+        state: 'unusable',
+        platform,
+        policy: 'git-bash',
+        command: unusableCandidate,
+        message: 'Git Bash candidate exists but is not executable.'
+      };
+    }
+  }
+
+  return {
+    available: false,
+    state: 'missing',
+    platform,
+    policy: 'git-bash',
+    command: null,
+    message: 'Git Bash is required on Windows for helper-backed flows.'
+  };
+}
+
+function normalizeShellRuntime(shellRuntime, platform, options = {}) {
+  if (shellRuntime && typeof shellRuntime === 'object') {
+    const state = shellRuntime.state || (shellRuntime.available ? 'available' : 'missing');
+    return {
+      available: Boolean(shellRuntime.available),
+      state,
+      platform,
+      policy: shellRuntime.policy || (platform === 'win32' ? 'git-bash' : 'system-shell'),
+      command: shellRuntime.command || null,
+      message: shellRuntime.message || ''
+    };
+  }
+
+  return resolveShellRuntime({ ...options, platform });
+}
+
+function normalizeProjectRoot(projectRoot) {
+  return typeof projectRoot === 'string' && projectRoot.trim()
+    ? projectRoot
+    : process.cwd();
+}
+
+function checkRuntimeHealth(projectRoot, options = {}) {
+  const platform = options.platform || process.platform;
+  const root = normalizeProjectRoot(projectRoot);
+
+  const lefthook = checkLefthookStatus(root);
+  const hooks = checkHookInstallation(root, options);
+  const bd = checkCommandAvailability('bd', root, options);
+  const gh = checkCommandAvailability('gh', root, options);
+  const jq = checkCommandAvailability('jq', root, options);
+  const shell = normalizeShellRuntime(options.shellRuntime, platform, options);
+
+  const diagnostics = [];
+
+  if (lefthook.state !== 'installed') {
+    diagnostics.push(createDiagnostic(
+      'LEFTHOOK_MISSING',
+      'lefthook',
+      lefthook.message || 'lefthook is required for hook installation.',
+      'bun add -D lefthook && bun install'
+    ));
+  }
+
+  if (!hooks.active) {
+    diagnostics.push(createDiagnostic(
+      'HOOKS_NOT_ACTIVE',
+      'git-hooks',
+      hooks.message || 'Git hooks are not installed.',
+      'bunx lefthook install'
+    ));
+  }
+
+  if (!bd.available) {
+    diagnostics.push(createDiagnostic(
+      'BD_MISSING',
+      'bd',
+      'bd is required for stage-entry workflow checks.'
+    ));
+  }
+
+  if (!gh.available) {
+    diagnostics.push(createDiagnostic(
+      'GH_MISSING',
+      'gh',
+      'gh is required for stage-entry workflow checks.'
+    ));
+  }
+
+  if (!jq.available) {
+    diagnostics.push(createDiagnostic(
+      'JQ_MISSING',
+      'jq',
+      'jq is required for stage-entry workflow checks.'
+    ));
+  }
+
+  if (platform === 'win32' && !shell.available) {
+    diagnostics.push(createDiagnostic(
+      'SHELL_RUNTIME_MISSING',
+      'shell-runtime',
+      shell.message || 'Git Bash is required on Windows for helper-backed flows.'
+    ));
+  }
+
+  const healthy = diagnostics.length === 0;
+
+  return {
+    healthy,
+    ready: healthy,
+    hardStop: !healthy,
+    diagnostics,
+    checks: {
+      projectRoot: root,
+      lefthook,
+      hooks,
+      bd,
+      gh,
+      jq,
+      shell
+    }
+  };
+}
+
+module.exports = {
+  checkRuntimeHealth,
+  checkHookInstallation,
+  checkCommandAvailability,
+  resolveShellRuntime
+};

package/lib/shell-utils.js

@@ -0,0 +1,50 @@
+/**
+ * Shell execution utility wrappers
+ * Extracted from bin/forge.js for reuse and testability
+ * @module lib/shell-utils
+ */
+
+const { execFileSync, spawnSync } = require('node:child_process');
+
+/**
+ * Securely execute a command with PATH validation.
+ * Mitigates SonarCloud S4036: Ensures executables are from trusted locations.
+ * @param {string} command - The command to execute
+ * @param {string[]} [args=[]] - Command arguments
+ * @param {object} [options={}] - execFileSync options
+ * @returns {Buffer|string} Command output
+ */
+function secureExecFileSync(command, args = [], options = {}) {
+  const {
+    _execFileSync = execFileSync,
+    _spawnSync = spawnSync,
+    ...execOptions
+  } = options;
+
+  let resolvedPath = null;
+
+  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']
+    });
+
+    if (result.status === 0 && result.stdout) {
+      // Handle both CRLF (Windows) and LF (Unix) line endings
+      resolvedPath = result.stdout.trim().split(/\r?\n/)[0].trim();
+    }
+  } catch (_err) { // NOSONAR - S2486: Intentionally ignored; falls back to direct command execution below
+  }
+
+  // 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);
+}
+
+module.exports = {
+  secureExecFileSync
+};