forge-workflow 0.0.3 → 0.0.5

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