forge-workflow 0.0.3 → 0.0.4

package/lib/detect-agent.js

@@ -0,0 +1,191 @@
+/**
+ * Agent Auto-Detection Module
+ *
+ * 4-layer detection strategy:
+ *   Layer 1: AI_AGENT env var (universal standard)
+ *   Layer 2: Agent-specific env vars (high confidence)
+ *   Layer 3: VSCode path parsing (medium confidence)
+ *   Layer 4: Config file signatures (medium-low confidence)
+ *
+ * @module detect-agent
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+/**
+ * Layer 2 mapping: env var → agent name.
+ * Order matters — first match wins within this layer.
+ * Each entry: [envVarName, agentName]
+ * @type {Array<[string, string]>}
+ */
+const AGENT_ENV_VARS = [
+  // Forge-supported agents only (7 agents)
+  // Claude Code (with cowork sub-check handled separately)
+  ['CLAUDECODE', 'claude'],
+  ['CLAUDE_CODE', 'claude'],
+  // Cursor
+  ['CURSOR_TRACE_ID', 'cursor'],
+  ['CURSOR_AGENT', 'cursor'],
+  // Codex (OpenAI)
+  ['CODEX_SANDBOX', 'codex'],
+  ['CODEX_CI', 'codex'],
+  ['CODEX_THREAD_ID', 'codex'],
+  // OpenCode
+  ['OPENCODE_CLIENT', 'opencode'],
+  // GitHub Copilot
+  ['COPILOT_MODEL', 'github-copilot'],
+  ['COPILOT_ALLOW_ALL', 'github-copilot'],
+  ['COPILOT_GITHUB_TOKEN', 'github-copilot'],
+  // Cline, Roo Code, Kilocode — no env vars (VSCode extensions, config-file-only)
+];
+
+/**
+ * Layer 4 mapping: config file/dir paths → agent name.
+ * Paths are relative to project root.
+ * @type {Array<[string, string]>}
+ */
+const CONFIG_SIGNATURES = [
+  // Forge-supported agents only (7 agents)
+  [path.join('.claude', 'settings.json'), 'claude'],
+  ['.cursorrules', 'cursor'],
+  [path.join('.cursor', 'rules'), 'cursor'],
+  ['.clinerules', 'cline'],
+  ['.cline', 'cline'],
+  [path.join('.roo', 'rules'), 'roo-code'],
+  ['.roo', 'roo-code'],
+  ['.kilocode', 'kilocode'],
+  ['codex.md', 'codex'],
+  ['.codex', 'codex'],
+  [path.join('.opencode', 'commands'), 'opencode'],
+  ['.opencode', 'opencode'],
+  [path.join('.github', 'copilot-instructions.md'), 'github-copilot'],
+];
+
+/**
+ * Detect the actively running AI agent from environment signals.
+ *
+ * Covers layers 1-3 of the 4-layer detection strategy:
+ *   1. AI_AGENT env var (universal, highest priority)
+ *   2. Agent-specific env vars (high confidence)
+ *   3. VSCode path parsing (medium confidence)
+ * Layer 4 (config file signatures) is in detectConfiguredAgents().
+ *
+ * @param {Record<string, string>} [env=process.env] - Environment variables
+ * @returns {{ name: string, source: 'env'|'path', confidence: 'high'|'medium' } | null}
+ */
+function detectActiveAgent(env = process.env) {
+  // Layer 1: AI_AGENT universal env var
+  if (env.AI_AGENT) {
+    return { name: env.AI_AGENT, source: 'env', confidence: 'high' };
+  }
+
+  // Layer 2: Agent-specific env vars
+  // Special sub-check: Claude Code cowork mode
+  if ((env.CLAUDECODE || env.CLAUDE_CODE) && env.CLAUDE_CODE_IS_COWORK) {
+    return { name: 'cowork', source: 'env', confidence: 'high' };
+  }
+
+  for (const [varName, agentName] of AGENT_ENV_VARS) {
+    if (env[varName]) {
+      return { name: agentName, source: 'env', confidence: 'high' };
+    }
+  }
+
+  // Layer 3: VSCode path parsing
+  const pathResult = _detectFromVSCodePaths(env);
+  if (pathResult && pathResult.agent) {
+    return { name: pathResult.agent, source: 'path', confidence: 'medium' };
+  }
+
+  return null;
+}
+
+/**
+ * Parse VSCode-related env vars for editor/agent identification.
+ *
+ * @param {Record<string, string>} env - Environment variables
+ * @returns {{ agent: string|null, editor: string|null } | null}
+ * @private
+ */
+function _detectFromVSCodePaths(env) {
+  const pathsToCheck = [
+    env.VSCODE_CODE_CACHE_PATH,
+    env.VSCODE_NLS_CONFIG,
+  ].filter(Boolean);
+
+  if (pathsToCheck.length === 0) return null;
+
+  const combined = pathsToCheck.join(' ').toLowerCase();
+
+  // Only detect Forge-supported agents via VSCode paths
+  if (combined.includes('cursor')) {
+    return { agent: 'cursor', editor: 'cursor' };
+  }
+
+  // Generic VSCode (or unsupported VSCode forks) — not a specific agent
+  if (combined.includes('code')) {
+    return { agent: null, editor: 'vscode' };
+  }
+
+  return null;
+}
+
+/**
+ * Detect all agents with config files present in the project root (Layer 4).
+ *
+ * @param {string} projectRoot - Absolute path to project root
+ * @returns {string[]} Array of unique agent names detected from config files
+ */
+function detectConfiguredAgents(projectRoot) {
+  const detected = new Set();
+
+  for (const [relativePath, agentName] of CONFIG_SIGNATURES) {
+    const fullPath = path.join(projectRoot, relativePath);
+    try {
+      if (fs.existsSync(fullPath)) {
+        detected.add(agentName);
+      }
+    } catch (_err) {
+      // Permission error or other fs issue — skip silently
+    }
+  }
+
+  return [...detected];
+}
+
+/**
+ * Full environment detection combining all 4 layers.
+ *
+ * @param {string} projectRoot - Absolute path to project root
+ * @param {Record<string, string>} [env=process.env] - Environment variables
+ * @returns {{
+ *   activeAgent: string|null,
+ *   activeAgentSource: 'env'|'path'|null,
+ *   confidence: 'high'|'medium'|null,
+ *   configuredAgents: string[],
+ *   editor: string|null
+ * }}
+ */
+function detectEnvironment(projectRoot, env = process.env) {
+  const active = detectActiveAgent(env);
+  const configuredAgents = detectConfiguredAgents(projectRoot);
+
+  // Get editor from VSCode paths (_detectFromVSCodePaths is cheap and deterministic)
+  const vscodePaths = _detectFromVSCodePaths(env);
+  const editor = vscodePaths ? vscodePaths.editor : null;
+
+  return {
+    activeAgent: active ? active.name : null,
+    activeAgentSource: active ? active.source : null,
+    confidence: active ? active.confidence : null,
+    configuredAgents,
+    editor,
+  };
+}
+
+module.exports = {
+  detectActiveAgent,
+  detectConfiguredAgents,
+  detectEnvironment,
+};

package/lib/detect-worktree.js

@@ -0,0 +1,47 @@
+'use strict';
+
+const { execFileSync } = require('child_process');
+const path = require('path');
+
+/**
+ * Detect if the current directory is inside a git worktree.
+ * Uses git rev-parse --git-dir vs --git-common-dir — they differ in worktrees.
+ *
+ * @param {string} [cwd=process.cwd()] - Directory to check
+ * @returns {{ inWorktree: boolean, branch?: string, mainWorktree?: string }}
+ */
+function detectWorktree(cwd = process.cwd()) {
+  try {
+    const gitDir = execFileSync('git', ['rev-parse', '--git-dir'], {
+      encoding: 'utf8', cwd, stdio: ['pipe', 'pipe', 'pipe']
+    }).trim();
+
+    const gitCommonDir = execFileSync('git', ['rev-parse', '--git-common-dir'], {
+      encoding: 'utf8', cwd, stdio: ['pipe', 'pipe', 'pipe']
+    }).trim();
+
+    // Resolve to absolute paths for reliable comparison
+    const absGitDir = path.resolve(cwd, gitDir);
+    const absCommonDir = path.resolve(cwd, gitCommonDir);
+
+    // In a worktree, git-dir is like .git/worktrees/<name>
+    // while git-common-dir is the main .git directory
+    if (absGitDir !== absCommonDir) {
+      const branch = execFileSync('git', ['branch', '--show-current'], {
+        encoding: 'utf8', cwd, stdio: ['pipe', 'pipe', 'pipe']
+      }).trim();
+
+      // Main worktree is one level above the common .git dir
+      const mainWorktree = path.resolve(absCommonDir, '..');
+
+      return { inWorktree: true, branch, mainWorktree };
+    }
+
+    return { inWorktree: false };
+  } catch (_err) {
+    // Not in a git repo or git not available
+    return { inWorktree: false };
+  }
+}
+
+module.exports = { detectWorktree };

package/lib/file-hash.js

@@ -0,0 +1,26 @@
+const crypto = require('crypto');
+const fs = require('fs');
+
+/**
+ * Compute SHA-256 hex digest of a string.
+ * @param {string} content
+ * @returns {string} 64-char lowercase hex hash
+ */
+function contentHash(content) {
+  return crypto.createHash('sha256').update(content).digest('hex');
+}
+
+/**
+ * Check whether an existing file's content matches the given string.
+ * Returns false if the file does not exist.
+ * @param {string} filePath
+ * @param {string} newContent
+ * @returns {boolean}
+ */
+function fileMatchesContent(filePath, newContent) {
+  if (!fs.existsSync(filePath)) return false;
+  const existing = fs.readFileSync(filePath, 'utf8');
+  return contentHash(existing) === contentHash(newContent);
+}
+
+module.exports = { contentHash, fileMatchesContent };

package/lib/setup-action-log.js

@@ -0,0 +1,139 @@
+/**
+ * Centralized action log for setup operations.
+ *
+ * Collects file-level actions (created, skipped, merged, etc.) during
+ * `forge setup` so the CLI can display a structured summary at the end.
+ *
+ * @module setup-action-log
+ */
+
+/** Map of directory prefixes to human-readable agent names. */
+const AGENT_PREFIXES = {
+  '.claude/': 'Claude Code',
+  '.cursor/': 'Cursor',
+  '.windsurf/': 'Windsurf',
+  '.cline/': 'Cline',
+  '.codex/': 'Codex',
+  '.opencode/': 'OpenCode',
+  '.kilocode/': 'Kilocode',
+  '.roo/': 'Roo Code',
+  '.github/prompts/': 'GitHub Copilot'
+};
+
+/**
+ * Detect the agent name from a file path.
+ *
+ * @param {string} filePath - Relative file path (e.g. `.claude/settings.json`)
+ * @returns {string} Agent name or `'General'` if no agent prefix matches
+ */
+function detectAgent(filePath) {
+  const normalized = filePath.replace(/\\/g, '/');
+  for (const [prefix, name] of Object.entries(AGENT_PREFIXES)) {
+    if (normalized.startsWith(prefix)) {
+      return name;
+    }
+  }
+  return 'General';
+}
+
+/**
+ * Strip the agent directory prefix from a file path.
+ *
+ * @param {string} filePath - Relative file path
+ * @returns {string} Path with the leading agent directory removed
+ */
+function stripAgentPrefix(filePath) {
+  const normalized = filePath.replace(/\\/g, '/');
+  for (const prefix of Object.keys(AGENT_PREFIXES)) {
+    if (normalized.startsWith(prefix)) {
+      return normalized.slice(prefix.length);
+    }
+  }
+  return normalized;
+}
+
+class SetupActionLog {
+  constructor() {
+    /** @type {Array<{file: string, action: string, detail: string|null}>} */
+    this.actions = [];
+  }
+
+  /**
+   * Record a setup action.
+   *
+   * @param {string} file   - Relative file path that was acted on
+   * @param {string} action - One of: created, skipped, merged, conflict, removed, force-created
+   * @param {string|null} [detail=null] - Optional human-readable detail
+   */
+  add(file, action, detail = null) {
+    this.actions.push({ file, action, detail });
+  }
+
+  /**
+   * Get counts grouped by action type.
+   *
+   * @returns {Record<string, number>} e.g. `{ created: 4, skipped: 2 }`
+   */
+  getSummary() {
+    const counts = {};
+    for (const { action } of this.actions) {
+      counts[action] = (counts[action] || 0) + 1;
+    }
+    return counts;
+  }
+
+  /**
+   * Get the full ordered list of actions.
+   *
+   * @returns {Array<{file: string, action: string, detail: string|null}>}
+   */
+  getVerbose() {
+    return this.actions;
+  }
+
+  /**
+   * Group files by detected agent name.
+   *
+   * Each agent key maps to an object whose keys are action types and whose
+   * values are arrays of file paths (with the agent prefix stripped).
+   *
+   * @returns {Record<string, Record<string, string[]>>}
+   */
+  getAgentSummary() {
+    const agents = {};
+    for (const { file, action } of this.actions) {
+      const agent = detectAgent(file);
+      const stripped = stripAgentPrefix(file);
+
+      if (!agents[agent]) {
+        agents[agent] = {};
+      }
+      if (!agents[agent][action]) {
+        agents[agent][action] = [];
+      }
+      agents[agent][action].push(stripped);
+    }
+    return agents;
+  }
+
+  /**
+   * Filter actions by type.
+   *
+   * @param {string} action - The action type to filter on
+   * @returns {Array<{file: string, action: string, detail: string|null}>}
+   */
+  getByAction(action) {
+    return this.actions.filter(a => a.action === action);
+  }
+
+  /**
+   * Total number of recorded actions.
+   *
+   * @returns {number}
+   */
+  get length() {
+    return this.actions.length;
+  }
+}
+
+module.exports = { SetupActionLog };

package/lib/setup-summary-renderer.js

@@ -0,0 +1,106 @@
+/**
+ * Renders a clean summary from SetupActionLog data.
+ *
+ * Default mode: 3-line concise output.
+ * Verbose mode: file-by-file detail grouped by agent.
+ *
+ * @module setup-summary-renderer
+ */
+
+/**
+ * Capitalize the first letter of a string.
+ *
+ * @param {string} str
+ * @returns {string}
+ */
+function capitalize(str) {
+  if (!str) return str;
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}
+
+/**
+ * Render setup summary as a string.
+ *
+ * @param {import('./setup-action-log').SetupActionLog} actionLog - The populated action log
+ * @param {string[]} agentNames - List of configured agent slugs (e.g. ['claude', 'cursor'])
+ * @param {boolean} verbose - Whether to show file-by-file detail
+ * @returns {string} The formatted summary output
+ */
+function renderSetupSummary(actionLog, agentNames, verbose) {
+  if (verbose) {
+    return renderVerbose(actionLog, agentNames);
+  }
+  return renderDefault(actionLog, agentNames);
+}
+
+/**
+ * Render the default 3-line concise summary.
+ *
+ * @param {import('./setup-action-log').SetupActionLog} actionLog
+ * @param {string[]} agentNames
+ * @returns {string}
+ */
+function renderDefault(actionLog, agentNames) {
+  const agentCount = agentNames.length;
+  const agentLabel = agentCount === 1 ? '1 agent' : `${agentCount} agents`;
+  const agentList = agentNames.length > 0 ? ` (${agentNames.join(', ')})` : '';
+
+  const summary = actionLog.getSummary();
+
+  // Build counts line — only include non-zero actions
+  const displayOrder = ['created', 'skipped', 'merged', 'force-created', 'updated', 'conflict', 'removed'];
+  const parts = [];
+  for (const action of displayOrder) {
+    if (summary[action] && summary[action] > 0) {
+      parts.push(`${capitalize(action)}: ${summary[action]} ${summary[action] === 1 ? 'file' : 'files'}`);
+    }
+  }
+  // Include any actions not in displayOrder
+  for (const [action, count] of Object.entries(summary)) {
+    if (!displayOrder.includes(action) && count > 0) {
+      parts.push(`${capitalize(action)}: ${count} ${count === 1 ? 'file' : 'files'}`);
+    }
+  }
+
+  const lines = [];
+  lines.push(`Forge setup complete — ${agentLabel} configured${agentList}`);
+
+  if (parts.length > 0) {
+    lines.push(`  ${parts.join(' | ')}`);
+  } else {
+    lines.push('  0 files changed');
+  }
+
+  lines.push('  Run forge setup --verbose to see all files');
+
+  return lines.join('\n');
+}
+
+/**
+ * Render verbose file-by-file output grouped by agent.
+ *
+ * @param {import('./setup-action-log').SetupActionLog} actionLog
+ * @param {string[]} _agentNames - Not used in verbose (agents come from log data)
+ * @returns {string}
+ */
+function renderVerbose(actionLog, _agentNames) {
+  const agentSummary = actionLog.getAgentSummary();
+  const lines = [];
+
+  for (const [agent, actions] of Object.entries(agentSummary)) {
+    for (const [action, files] of Object.entries(actions)) {
+      const fileCount = files.length;
+      const fileLabel = fileCount === 1 ? '1 file' : `${fileCount} files`;
+      const fileList = files.join(', ');
+      lines.push(`${agent}: ${fileList} (${fileLabel}) [${action}]`);
+    }
+  }
+
+  if (lines.length === 0) {
+    return 'No file operations recorded.';
+  }
+
+  return lines.join('\n');
+}
+
+module.exports = { renderSetupSummary };

package/lib/setup.js

@@ -109,10 +109,84 @@ async function markStepComplete(projectPath, stepName) {
   await saveSetupState(projectPath, state);
 }
 
+/**
+ * Scaffold GitHub-Beads sync files into a target project.
+ * Copies workflow, config, and mapping template — never overwrites existing files.
+ *
+ * @param {string} projectPath - Target project root
+ * @param {string} pkgDir - Forge package directory (source of template files)
+ * @returns {Promise<{created: string[], skipped: string[]}>}
+ */
+async function scaffoldGithubBeadsSync(projectPath, pkgDir) {
+  const created = [];
+  const skipped = [];
+
+  // Sync script modules that workflows depend on at runtime
+  const syncScripts = [
+    'config.mjs', 'mapping.mjs', 'comment.mjs', 'github-api.mjs',
+    'sanitize.mjs', 'run-bd.mjs', 'label-mapper.mjs', 'index.mjs',
+    'reverse-sync.mjs', 'reverse-sync-cli.mjs',
+  ];
+
+  const files = [
+    // Phase 1: GitHub → Beads
+    {
+      src: path.join(pkgDir, '.github', 'workflows', 'github-to-beads.yml'),
+      dest: path.join('.github', 'workflows', 'github-to-beads.yml'),
+    },
+    // Phase 2: Beads → GitHub
+    {
+      src: path.join(pkgDir, '.github', 'workflows', 'beads-to-github.yml'),
+      dest: path.join('.github', 'workflows', 'beads-to-github.yml'),
+    },
+    {
+      src: path.join(pkgDir, 'scripts', 'github-beads-sync.config.json'),
+      dest: path.join('scripts', 'github-beads-sync.config.json'),
+    },
+    {
+      src: null, // generated in-place (empty mapping template)
+      dest: path.join('.github', 'beads-mapping.json'),
+      content: '{}',
+    },
+    // Sync script modules
+    ...syncScripts.map((name) => ({
+      src: path.join(pkgDir, 'scripts', 'github-beads-sync', name),
+      dest: path.join('scripts', 'github-beads-sync', name),
+    })),
+  ];
+
+  for (const file of files) {
+    const destPath = path.join(projectPath, file.dest);
+
+    // Never overwrite existing files — preserve user customizations
+    if (fs.existsSync(destPath)) {
+      skipped.push(file.dest);
+      continue;
+    }
+
+    // Ensure parent directory exists
+    const destDir = path.dirname(destPath);
+    await fs.promises.mkdir(destDir, { recursive: true });
+
+    if (file.src) {
+      // Copy from template
+      await fs.promises.copyFile(file.src, destPath);
+    } else {
+      // Write generated content
+      await fs.promises.writeFile(destPath, file.content, 'utf-8');
+    }
+
+    created.push(file.dest);
+  }
+
+  return { created, skipped };
+}
+
 module.exports = {
   saveSetupState,
   loadSetupState,
   isSetupComplete,
   getNextStep,
-  markStepComplete
+  markStepComplete,
+  scaffoldGithubBeadsSync
 };

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "forge-workflow",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "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",
-    "forge-validate": "bin/forge-validate.js"
+    "forge-preflight": "bin/forge-preflight.js"
   },
   "workspaces": [
     "packages/*"
@@ -15,9 +15,8 @@
     "test:all": "bun run test:setup && bun test",
     "test:coverage": "c8 --check-coverage bun test",
     "typecheck": "echo 'No TypeScript in project - skipping type check'",
-    "lint": "eslint .",
+    "lint": "eslint . --max-warnings 0",
     "check": "bash scripts/validate.sh",
-    "postinstall": "node ./bin/forge.js",
     "prepare": "lefthook install || echo 'Note: lefthook not installed. Git hooks disabled. Run: bun add -d lefthook'",
     "setup": "node ./bin/forge.js setup",
     "help": "node ./bin/forge.js --help",