forge-workflow 0.0.2 → 0.0.4

package/lib/dep-guard/task-parser.js

@@ -0,0 +1,318 @@
+const fs = require('node:fs');
+const path = require('node:path');
+const { normalizeRepoPath } = require('./path-utils.js');
+
+function ensureTaskFile(taskFile) {
+	if (!taskFile || typeof taskFile !== 'string') {
+		throw new Error('Task file path is required');
+	}
+
+	const absolutePath = path.resolve(taskFile);
+	if (!fs.existsSync(absolutePath)) {
+		throw new Error(`Task file does not exist: ${absolutePath}`);
+	}
+
+	return absolutePath;
+}
+
+function parseFilesLine(value) {
+	if (!value) {
+		return [];
+	}
+
+	return value
+		.split(',')
+		.map((file) => file.replaceAll('`', '').trim())
+		.filter(Boolean);
+}
+
+function flushTask(tasks, currentTask) {
+	if (!currentTask) {
+		return;
+	}
+
+	tasks.push({
+		number: currentTask.number,
+		title: currentTask.title,
+		files: currentTask.files,
+		whatToImplement: currentTask.whatToImplement.trim(),
+		expectedOutput: currentTask.expectedOutput.trim(),
+	});
+}
+
+function isIdentifierStart(character) {
+	return /[A-Za-z_]/.test(character);
+}
+
+function isIdentifierPart(character) {
+	return /\w/.test(character);
+}
+
+function extractSymbols(text) {
+	const symbols = new Set();
+	let searchIndex = 0;
+
+	while (searchIndex < text.length) {
+		const callIndex = text.indexOf('()', searchIndex);
+		if (callIndex === -1) {
+			break;
+		}
+
+		let startIndex = callIndex - 1;
+		while (startIndex >= 0 && isIdentifierPart(text[startIndex])) {
+			startIndex -= 1;
+		}
+
+		const symbol = text.slice(startIndex + 1, callIndex);
+		if (symbol && isIdentifierStart(symbol[0])) {
+			symbols.add(symbol);
+		}
+
+		searchIndex = callIndex + 2;
+	}
+
+	for (const match of text.match(/`([^`\r\n]+)`/g) ?? []) {
+		const token = match.slice(1, -1).trim();
+		if (!token || /[/.\\\s]/.test(token)) {
+			continue;
+		}
+
+		if (/^[A-Za-z_][A-Za-z0-9_-]*$/.test(token)) {
+			symbols.add(token);
+		}
+	}
+
+	return Array.from(symbols);
+}
+
+function detectContractType(symbol, annotation = '') {
+	if (annotation === 'data-format' || annotation === 'command-contract' || annotation === 'return-shape') {
+		return annotation;
+	}
+
+	if (/Schema$|Format$/i.test(symbol)) {
+		return 'data-format';
+	}
+
+	if (/Contract$/i.test(symbol)) {
+		return 'command-contract';
+	}
+
+	if (symbol.includes('-')) {
+		return 'command-contract';
+	}
+
+	if (/Shape$/i.test(symbol)) {
+		return 'return-shape';
+	}
+
+	return 'modified';
+}
+
+function extractContractMentions(text) {
+	const mentions = new Map();
+	for (const symbol of extractSymbols(text)) {
+		mentions.set(symbol, {
+			symbol,
+			annotation: text.includes(`${symbol}()`) ? 'modified' : detectContractType(symbol),
+		});
+	}
+
+	for (const match of text.match(/\b[A-Za-z_]\w*(?:Schema|Format|Contract|Shape)\b/g) ?? []) {
+		if (mentions.has(match)) {
+			continue;
+		}
+
+		mentions.set(match, {
+			symbol: match,
+			annotation: detectContractType(match),
+		});
+	}
+
+	return Array.from(mentions.values());
+}
+
+function escapeRegExp(value) {
+	return value.replaceAll(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`);
+}
+
+function resolveRepositoryFile(repositoryRoot, filePath) {
+	if (!repositoryRoot || !filePath || path.isAbsolute(filePath)) {
+		return null;
+	}
+
+	const absoluteRoot = path.resolve(repositoryRoot);
+	const absolutePath = path.resolve(absoluteRoot, filePath);
+	const relativePath = path.relative(absoluteRoot, absolutePath);
+	if (
+		relativePath === ''
+		|| relativePath.startsWith(`..${path.sep}`)
+		|| relativePath === '..'
+		|| path.isAbsolute(relativePath)
+	) {
+		return null;
+	}
+
+	return absolutePath;
+}
+
+function fileContainsSymbol(repositoryRoot, filePath, symbol) {
+	const absolutePath = resolveRepositoryFile(repositoryRoot, filePath);
+	if (!absolutePath) {
+		return false;
+	}
+
+	if (!fs.existsSync(absolutePath)) {
+		return false;
+	}
+
+	const content = fs.readFileSync(absolutePath, 'utf8');
+	if (/^[A-Za-z_]\w*$/.test(symbol)) {
+		return new RegExp(String.raw`\b${escapeRegExp(symbol)}\b`).test(content);
+	}
+
+	return content.includes(symbol);
+}
+
+function resolveMentionFiles(task, mention, repositoryRoot) {
+	const files = task.files ?? [];
+	if (files.length === 0) {
+		return [];
+	}
+
+	if (!repositoryRoot) {
+		return files.map((file) => normalizeRepoPath(file));
+	}
+
+	const matchingFiles = files
+		.filter((file) => fileContainsSymbol(repositoryRoot, file, mention.symbol))
+		.map((file) => normalizeRepoPath(file));
+	return matchingFiles;
+}
+
+function extractTaskContracts(taskContext, options = {}) {
+	if (!taskContext || !Array.isArray(taskContext.tasks)) {
+		return [];
+	}
+
+	const contracts = new Set();
+	const repositoryRoot = options.repositoryRoot;
+
+	for (const task of taskContext.tasks) {
+		const mentions = extractContractMentions(task.whatToImplement ?? '');
+		for (const mention of mentions) {
+			for (const file of resolveMentionFiles(task, mention, repositoryRoot)) {
+				contracts.add(`${file}:${mention.symbol}(${mention.annotation})`);
+			}
+		}
+	}
+
+	return Array.from(contracts).sort((left, right) => left.localeCompare(right));
+}
+
+function isTaskHeader(line) {
+	return line.startsWith('## Task ');
+}
+
+function parseTaskHeader(line) {
+	if (!isTaskHeader(line)) {
+		return null;
+	}
+
+	const prefixLength = '## Task '.length;
+	const separatorIndex = line.indexOf(':', prefixLength);
+	if (separatorIndex === -1) {
+		return null;
+	}
+
+	const numberText = line.slice(prefixLength, separatorIndex).trim();
+	if (!numberText || Array.from(numberText).some((character) => character < '0' || character > '9')) {
+		return null;
+	}
+
+	const title = line.slice(separatorIndex + 1).trim();
+	if (!title) {
+		return null;
+	}
+
+	return {
+		number: Number(numberText),
+		title,
+	};
+}
+
+function parseTaskField(currentTask, line, currentField) {
+	if (line.startsWith('File(s):')) {
+		currentTask.files = parseFilesLine(line.slice('File(s):'.length).trim());
+		return null;
+	}
+
+	if (line.startsWith('What to implement:')) {
+		currentTask.whatToImplement = line.slice('What to implement:'.length).trim();
+		return 'whatToImplement';
+	}
+
+	if (line.startsWith('Expected output:')) {
+		currentTask.expectedOutput = line.slice('Expected output:'.length).trim();
+		return 'expectedOutput';
+	}
+
+	if (line === 'TDD steps:' || line === '---') {
+		return null;
+	}
+
+	if (currentField && line.trim()) {
+		currentTask[currentField] = `${currentTask[currentField]} ${line.trim()}`.trim();
+	}
+
+	return currentField;
+}
+
+function parseTaskFile(taskFile) {
+	const absolutePath = ensureTaskFile(taskFile);
+	const content = fs.readFileSync(absolutePath, 'utf8');
+	const lines = content.split(/\r?\n/);
+	const tasks = [];
+	let currentTask = null;
+	let currentField = null;
+
+	for (const rawLine of lines) {
+		const line = rawLine.trimEnd();
+		const taskHeader = parseTaskHeader(line);
+
+		if (taskHeader) {
+			flushTask(tasks, currentTask);
+			currentTask = {
+				number: taskHeader.number,
+				title: taskHeader.title,
+				files: [],
+				whatToImplement: '',
+				expectedOutput: '',
+			};
+			currentField = null;
+			continue;
+		}
+
+		if (!currentTask) {
+			continue;
+		}
+
+		currentField = parseTaskField(currentTask, line, currentField);
+	}
+
+	flushTask(tasks, currentTask);
+
+	return {
+		path: absolutePath,
+		taskCount: tasks.length,
+		tasks,
+	};
+}
+
+module.exports = {
+	detectContractType,
+	extractContractMentions,
+	extractSymbols,
+	extractTaskContracts,
+	parseTaskFile,
+};

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