forge-workflow 0.0.6 → 0.0.8

package/lib/project-discovery.js

@@ -7,6 +7,7 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const { execFileSync } = require('node:child_process');
+const { normalizeAgentId } = require('./detect-agent');
 
 async function detectFramework(projectPath) {
   try {
@@ -283,12 +284,45 @@ async function detectInstalledAgents(projectPath) {
         ]
       },
       {
-        name: 'kilo',
+        name: 'cline',
         checks: [
-          // .kilo.md file
+          async () => fs.existsSync(path.join(projectPath, '.clinerules')),
           async () => {
-            const kiloMd = path.join(projectPath, '.kilo.md');
-            return fs.existsSync(kiloMd);
+            const clineDir = path.join(projectPath, '.cline');
+            return fs.existsSync(clineDir) && (await fs.promises.stat(clineDir)).isDirectory();
+          }
+        ]
+      },
+      {
+        name: 'kilocode',
+        checks: [
+          async () => {
+            const kilocodeDir = path.join(projectPath, '.kilocode');
+            return fs.existsSync(kilocodeDir) && (await fs.promises.stat(kilocodeDir)).isDirectory();
+          },
+          async () => fs.existsSync(path.join(projectPath, '.kilocode', 'workflows', 'forge-workflow.md')),
+          async () => fs.existsSync(path.join(projectPath, '.kilocode', 'rules', 'workflow.md')),
+          async () => fs.existsSync(path.join(projectPath, '.kilocode', 'skills', 'forge-workflow', 'SKILL.md'))
+        ]
+      },
+      {
+        name: 'roo',
+        checks: [
+          async () => fs.existsSync(path.join(projectPath, '.roorules')),
+          async () => {
+            const rooDir = path.join(projectPath, '.roo');
+            return fs.existsSync(rooDir) && (await fs.promises.stat(rooDir)).isDirectory();
+          },
+          async () => fs.existsSync(path.join(projectPath, '.roo', 'rules'))
+        ]
+      },
+      {
+        name: 'codex',
+        checks: [
+          async () => fs.existsSync(path.join(projectPath, 'codex.md')),
+          async () => {
+            const codexDir = path.join(projectPath, '.codex');
+            return fs.existsSync(codexDir) && (await fs.promises.stat(codexDir)).isDirectory();
           }
         ]
       },
@@ -311,7 +345,7 @@ async function detectInstalledAgents(projectPath) {
         try {
           const detected = await check();
           if (detected) {
-            detectedAgents.push(detector.name);
+            detectedAgents.push(normalizeAgentId(detector.name));
             break; // Agent detected, no need to check other patterns
           }
         } catch (_error) {

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

package/lib/ui-utils.js

@@ -0,0 +1,43 @@
+/**
+ * UI prompt and display utilities
+ * Extracted from bin/forge.js for reuse and testability
+ * @module lib/ui-utils
+ */
+
+/**
+ * Yes/No prompt helper.
+ * @param {Function} question - Async function that prompts user and returns their answer string
+ * @param {string} prompt - The prompt text to display
+ * @param {boolean} [defaultNo=true] - Whether the default answer is "no"
+ * @param {boolean} [nonInteractive=false] - If true, returns default without prompting
+ * @returns {Promise<boolean>} User's answer
+ */
+async function askYesNo(question, prompt, defaultNo = true, nonInteractive = false) {
+  // Non-interactive mode: return default without prompting
+  if (nonInteractive) {
+    const defaultValue = !defaultNo;
+    console.log(`  Non-interactive mode: ${prompt} -> ${defaultValue ? 'yes' : 'no'} (default)`);
+    return defaultValue;
+  }
+  const defaultText = defaultNo ? '[n]' : '[y]';
+  while (true) {
+    const answer = await question(`${prompt} (y/n) ${defaultText}: `);
+    const normalized = answer.trim().toLowerCase();
+
+    // Handle empty input (use default)
+    if (normalized === '') return !defaultNo;
+
+    // Accept yes variations
+    if (normalized === 'y' || normalized === 'yes') return true;
+
+    // Accept no variations
+    if (normalized === 'n' || normalized === 'no') return false;
+
+    // Invalid input - re-prompt
+    console.log('  Please enter y or n');
+  }
+}
+
+module.exports = {
+  askYesNo
+};

package/lib/validation-utils.js

@@ -0,0 +1,163 @@
+/**
+ * Input validation utilities
+ * Extracted from bin/forge.js for reuse and testability
+ * @module lib/validation-utils
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+/**
+ * Run common security checks on input.
+ * Checks for shell injection, URL encoding attacks, and non-ASCII characters.
+ * @param {string} input - Input string to validate
+ * @returns {{valid: boolean, error?: string}}
+ */
+function validateCommonSecurity(input) {
+  // Shell injection check - common shell metacharacters
+  if (/[;|&$`()<>\r\n]/.test(input)) {
+    return { valid: false, error: 'Invalid characters detected (shell metacharacters)' };
+  }
+
+  // URL encoding check - prevent encoded path traversal
+  if (/%2[eE]|%2[fF]|%5[cC]/.test(input)) {
+    return { valid: false, error: 'URL-encoded characters not allowed' };
+  }
+
+  // ASCII-only check - prevent unicode attacks
+  if (!/^[\x20-\x7E]+$/.test(input)) {
+    return { valid: false, error: 'Only ASCII printable characters allowed' };
+  }
+
+  return { valid: true }; // No security issues found
+}
+
+/**
+ * Validate user input against security patterns.
+ * Prevents shell injection, path traversal, and unicode attacks.
+ * @param {string} input - User input to validate
+ * @param {string} type - Input type: 'path', 'agent', 'hash', 'directory_path'
+ * @param {string} [projectRoot] - Project root path (required for 'path' type)
+ * @returns {{valid: boolean, error?: string}}
+ */
+function validateUserInput(input, type, projectRoot) {
+  // Common security checks first
+  const securityResult = validateCommonSecurity(input);
+  if (!securityResult.valid) return securityResult;
+
+  // Type-specific validation - delegated to helpers
+  switch (type) {
+    case 'path':
+      return validatePathInput(input, projectRoot);
+    case 'directory_path':
+      return validateDirectoryPathInput(input);
+    case 'agent':
+      return validateAgentInput(input);
+    case 'hash':
+      return validateHashInput(input);
+    default:
+      return { valid: true };
+  }
+}
+
+/**
+ * Validate 'path' type input - ensures path stays within project root.
+ * @param {string} input - Path to validate
+ * @param {string} projectRoot - Project root directory
+ * @returns {{valid: boolean, error?: string}}
+ */
+function validatePathInput(input, projectRoot) {
+  const resolved = path.resolve(projectRoot, input);
+  const resolvedRoot = path.resolve(projectRoot);
+  if (!resolved.startsWith(resolvedRoot + path.sep) && resolved !== resolvedRoot) {
+    return { valid: false, error: 'Path outside project root' };
+  }
+  return { valid: true };
+}
+
+/**
+ * Validate 'directory_path' type input - blocks system directories.
+ * @param {string} input - Directory path to validate
+ * @returns {{valid: boolean, error?: string}}
+ */
+function validateDirectoryPathInput(input) {
+  // Block null bytes
+  if (input.includes('\0')) {
+    return { valid: false, error: 'Null bytes not allowed in path' };
+  }
+
+  // Block absolute paths to sensitive system directories
+  const resolved = path.resolve(input);
+  const normalizedResolved = path.normalize(resolved).toLowerCase();
+
+  // Get platform-specific blocked paths
+  const blockedPaths = process.platform === 'win32'
+    ? [String.raw`c:\windows`, String.raw`c:\program files`, String.raw`c:\program files (x86)`]
+    : ['/etc', '/bin', '/sbin', '/boot', '/sys', '/proc', '/dev'];
+  const errorMsg = process.platform === 'win32'
+    ? 'Cannot target Windows system directories'
+    : 'Cannot target system directories';
+
+  if (blockedPaths.some(blocked => normalizedResolved.startsWith(blocked))) {
+    return { valid: false, error: errorMsg };
+  }
+
+  return { valid: true };
+}
+
+/**
+ * Validate 'agent' type input - lowercase alphanumeric with hyphens only.
+ * @param {string} input - Agent name to validate
+ * @returns {{valid: boolean, error?: string}}
+ */
+function validateAgentInput(input) {
+  if (!/^[a-z0-9-]+$/.test(input)) {
+    return { valid: false, error: 'Agent name must be lowercase alphanumeric with hyphens' };
+  }
+  return { valid: true };
+}
+
+/**
+ * Validate 'hash' type input - git commit hash (4-40 hex chars).
+ * @param {string} input - Hash to validate
+ * @returns {{valid: boolean, error?: string}}
+ */
+function validateHashInput(input) {
+  if (!/^[0-9a-f]{4,40}$/i.test(input)) {
+    return { valid: false, error: 'Invalid commit hash format (must be 4-40 hex chars)' };
+  }
+  return { valid: true };
+}
+
+/**
+ * Check write permission to a directory or file.
+ * @param {string} filePath - Path to check
+ * @returns {{writable: boolean, error?: string}}
+ */
+function _checkWritePermission(filePath) {
+  try {
+    const dir = fs.statSync(filePath).isDirectory() ? filePath : path.dirname(filePath);
+    const testFile = path.join(dir, `.forge-write-test-${Date.now()}`);
+    fs.writeFileSync(testFile, 'test');
+    fs.unlinkSync(testFile);
+    return { writable: true };
+  } catch (err) {
+    if (err.code === 'EACCES' || err.code === 'EPERM') {
+      const fix = process.platform === 'win32'
+        ? 'Run Command Prompt as Administrator'
+        : 'Try: sudo npx forge setup';
+      return { writable: false, error: `No write permission to ${filePath}. ${fix}` };
+    }
+    return { writable: false, error: err.message };
+  }
+}
+
+module.exports = {
+  validateCommonSecurity,
+  validateUserInput,
+  validatePathInput,
+  validateDirectoryPathInput,
+  validateAgentInput,
+  validateHashInput,
+  _checkWritePermission
+};