forge-workflow 0.0.4 → 0.0.6

package/lib/detect-agent.js

@@ -1,191 +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,
-};
+/**
+ * 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

@@ -1,47 +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 };
+'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/docs-command.js

@@ -0,0 +1,51 @@
+const fs = require('node:fs');
+const path = require('node:path');
+
+/**
+ * Allowlist mapping topic names to filenames in docs/.
+ * Security: Only these exact keys are accepted — prevents path traversal.
+ */
+const TOPICS = {
+  toolchain: 'TOOLCHAIN.md',
+  validation: 'VALIDATION.md',
+  setup: 'SETUP.md',
+  examples: 'EXAMPLES.md',
+  roadmap: 'ROADMAP.md',
+};
+
+/**
+ * List all available topic names.
+ * @returns {string[]}
+ */
+function listTopics() {
+  return Object.keys(TOPICS);
+}
+
+/**
+ * Get the content of a documentation topic.
+ * Uses an allowlist to prevent path traversal attacks.
+ *
+ * @param {string} topic - Topic name (must be in TOPICS allowlist)
+ * @param {string} packageDir - Forge package root directory
+ * @returns {{ content?: string, error?: string }}
+ */
+function getTopicContent(topic, packageDir) {
+  const availableList = listTopics().join(', ');
+
+  // Validate against allowlist (rejects any path traversal attempt)
+  const filename = TOPICS[topic];
+  if (!filename) {
+    return { error: `Unknown topic: "${topic}". Available topics: ${availableList}` };
+  }
+
+  const filePath = path.join(packageDir, 'docs', filename);
+
+  try {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    return { content };
+  } catch (_error) {
+    return { error: `Documentation file "${filename}" not found at ${filePath}` };
+  }
+}
+
+module.exports = { listTopics, getTopicContent, TOPICS };

package/lib/docs-copy.js

@@ -0,0 +1,50 @@
+const fs = require('node:fs');
+const path = require('node:path');
+
+/**
+ * Essential docs to copy from package's docs/ to consumer's docs/forge/
+ */
+const ESSENTIAL_DOCS = ['TOOLCHAIN.md', 'VALIDATION.md'];
+
+/**
+ * Copy essential documentation files from the Forge package to the consumer project.
+ * Creates docs/forge/ if missing. Skips files that already exist (idempotent).
+ *
+ * @param {string} projectRoot - Target project root directory
+ * @param {string} packageDir - Forge package directory (source of docs)
+ * @returns {{ created: string[], skipped: string[] }}
+ */
+function copyEssentialDocs(projectRoot, packageDir) {
+  const created = [];
+  const skipped = [];
+
+  const targetDir = path.join(projectRoot, 'docs', 'forge');
+
+  for (const docFile of ESSENTIAL_DOCS) {
+    const srcPath = path.join(packageDir, 'docs', docFile);
+    const destPath = path.join(targetDir, docFile);
+    const relPath = ['docs', 'forge', docFile].join('/');
+
+    // Skip if source doesn't exist
+    if (!fs.existsSync(srcPath)) {
+      continue;
+    }
+
+    // Skip if destination already exists (preserve user customizations)
+    if (fs.existsSync(destPath)) {
+      skipped.push(relPath);
+      continue;
+    }
+
+    // Ensure target directory exists
+    fs.mkdirSync(targetDir, { recursive: true });
+
+    // Copy file
+    fs.copyFileSync(srcPath, destPath);
+    created.push(relPath);
+  }
+
+  return { created, skipped };
+}
+
+module.exports = { copyEssentialDocs, ESSENTIAL_DOCS };

package/lib/file-hash.js

@@ -1,26 +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 };
+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 };