forge-workflow 0.0.3 → 0.0.5

package/lib/smart-merge.js

@@ -0,0 +1,64 @@
+'use strict';
+
+/**
+ * Smart merge for AGENTS.md - preserves USER sections, updates FORGE sections.
+ *
+ * Handles four cases:
+ * 1. No markers at all: Wrap existing content in USER markers, append FORGE section
+ * 2. USER markers but no FORGE markers: Keep USER section, insert FORGE section
+ * 3. Both markers present: Preserve USER section, update FORGE section (existing behavior)
+ * 4. Empty existing content: Return only FORGE section (no empty USER block)
+ *
+ * @param {string} existingContent - The current AGENTS.md content
+ * @param {string} newContent - The new template content containing FORGE section
+ * @returns {string} Merged content, or empty string if merge not possible
+ */
+function smartMergeAgentsMd(existingContent, newContent) {
+  // Extract FORGE section from new content (needed in all cases)
+  const forgeStartMatch = (/(<!-- FORGE:START.*?-->[\s\S]*?<!-- FORGE:END -->)/).exec(newContent);
+  const forgeSection = forgeStartMatch ? forgeStartMatch[0] : '';
+
+  // Check if existing content has markers
+  const hasUserMarkers = existingContent.includes('<!-- USER:START') && existingContent.includes('<!-- USER:END');
+
+  let userSection;
+
+  if (hasUserMarkers) {
+    // Extract existing USER section (with markers)
+    const userMatch = (/(<!-- USER:START.*?-->[\s\S]*?<!-- USER:END -->)/).exec(existingContent);
+    userSection = userMatch ? userMatch[0] : '';
+  } else if (existingContent.trim() === '') {
+    // Empty existing content: no USER block at all
+    userSection = null;
+  } else {
+    // No markers: wrap entire existing content in USER markers
+    userSection = `<!-- USER:START -->\n${existingContent.trim()}\n<!-- USER:END -->`;
+  }
+
+  // Build merged content
+  const setupInstructions = newContent.includes('<!-- FORGE:SETUP-INSTRUCTIONS')
+    ? (/(<!-- FORGE:SETUP-INSTRUCTIONS[\s\S]*?-->)/).exec(newContent)?.[0] || ''
+    : '';
+
+  let merged = '# AGENTS.md\n\n';
+
+  // Add setup instructions if this is first-time setup
+  if (setupInstructions && !existingContent.includes('FORGE:SETUP-INSTRUCTIONS')) {
+    merged += setupInstructions + '\n\n';
+  }
+
+  // Add USER section (skip if empty existing content — no empty USER block)
+  if (userSection !== null) {
+    merged += userSection + '\n\n';
+  }
+
+  // Add updated FORGE section
+  merged += forgeSection + '\n\n';
+
+  // Add footer
+  merged += `---\n\n## Improving This Workflow\n\nEvery time you give the same instruction twice, add it to this file:\n1. User-specific rules: Add to USER:START section above\n2. Forge workflow improvements: Suggest to forge maintainers\n\n**Keep this file updated as you learn about the project.**\n\n---\n\nSee \`AGENTS.md\` for complete workflow guide.\nSee \`docs/TOOLCHAIN.md\` for comprehensive tool reference.\n`;
+
+  return merged;
+}
+
+module.exports = { smartMergeAgentsMd };

package/lib/symlink-utils.js

@@ -0,0 +1,81 @@
+/**
+ * Symlink utilities for Forge setup.
+ *
+ * Creates CLAUDE.md (or other agent link files) as a symlink to AGENTS.md,
+ * with an automatic fallback to copy when symlinks are not available
+ * (e.g., Windows without admin privileges).
+ *
+ * @module symlink-utils
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+/**
+ * Header comment prepended to copies when symlink creation fails.
+ * Alerts users that the file is a copy and how to create a proper symlink.
+ */
+const HEADER_COMMENT =
+  '<!-- This file is a copy of AGENTS.md. Keep in sync manually or use: bunx forge setup --symlink -->';
+
+/**
+ * Create a symlink from `linkPath` pointing to `target`.
+ * If symlink creation fails (e.g., EPERM on Windows without admin),
+ * falls back to a file copy with a header comment — unless `symlinkOnly`
+ * is true, in which case it reports the error and returns ''.
+ *
+ * @param {string} target   - Absolute path to the source file (e.g., AGENTS.md)
+ * @param {string} linkPath - Absolute path for the symlink/copy (e.g., CLAUDE.md)
+ * @param {Object} [options={}] - Options
+ * @param {boolean} [options.symlinkOnly=false] - When true, skip copy fallback (--symlink flag)
+ * @returns {'linked'|'copied'|''} Result indicator
+ */
+function createSymlinkOrCopy(target, linkPath, options = {}) {
+  try {
+    // Ensure target exists
+    if (!fs.existsSync(target)) {
+      console.error(`  ✗ Source file does not exist: ${target}`);
+      return '';
+    }
+
+    // Remove existing file/symlink at linkPath
+    if (fs.existsSync(linkPath)) {
+      const stat = fs.lstatSync(linkPath);
+      if (stat.isDirectory()) {
+        console.warn(
+          `  ⚠ Skipped ${linkPath} (a directory exists at this path). Remove it manually and re-run setup.`
+        );
+        return '';
+      }
+      fs.unlinkSync(linkPath);
+    }
+
+    // Ensure parent directory exists
+    const linkDir = path.dirname(linkPath);
+    if (!fs.existsSync(linkDir)) {
+      fs.mkdirSync(linkDir, { recursive: true });
+    }
+
+    // Attempt symlink (relative path for portability)
+    try {
+      const relPath = path.relative(linkDir, target);
+      fs.symlinkSync(relPath, linkPath);
+      return 'linked';
+    } catch (_symlinkErr) {
+      // Expected: symlink creation fails with EPERM on Windows without admin privileges — fall back to copy
+      if (options.symlinkOnly) {
+        console.warn(`  ⚠ Symlink failed for ${linkPath} (--symlink requires symlink support)`);
+        return '';
+      }
+      // Fall back to copy with header
+      const content = fs.readFileSync(target, 'utf-8');
+      fs.writeFileSync(linkPath, HEADER_COMMENT + '\n' + content, 'utf-8');
+      return 'copied';
+    }
+  } catch (err) {
+    console.error(`  ✗ Failed to link/copy ${target} -> ${linkPath}: ${err.message}`);
+    return '';
+  }
+}
+
+module.exports = { createSymlinkOrCopy, HEADER_COMMENT };

package/lib/workflow-profiles.js

@@ -1,197 +1,197 @@
-/**
- * Workflow Profiles
- *
- * Implements hybrid approach: 4 user-facing types (Feature/Fix/Refactor/Chore)
- * map to 6 internal profiles (Critical/Standard/Simple/Hotfix/Docs/Refactor)
- * with keyword-based auto-escalation.
- */
-
-/**
- * Internal workflow profiles aligned with AGENTS.md specification
- */
-const PROFILES = {
-  critical: {
-    name: 'Critical (Maximum Rigor)',
-    stages: ['/status', '/plan', '/dev', '/validate', '/ship', '/review', '/premerge', '/verify'],
-    tdd: 'strict',
-    research: 'required',
-    description: 'Security, auth, payments, data integrity, breaking changes',
-    keywords: ['auth', 'security', 'payment', 'crypto', 'password', 'token', 'session', 'data-migration', 'breaking']
-  },
-
-  standard: {
-    name: 'Standard (Full Workflow)',
-    stages: ['/status', '/plan', '/dev', '/validate', '/ship', '/review', '/premerge'],
-    tdd: 'required',
-    research: 'optional',
-    description: 'Most features and non-critical enhancements'
-  },
-
-  simple: {
-    name: 'Simple (Streamlined)',
-    stages: ['/dev', '/validate', '/ship', '/premerge'],
-    tdd: 'recommended',
-    research: 'skip',
-    description: 'UI tweaks, small improvements, minor fixes'
-  },
-
-  hotfix: {
-    name: 'Hotfix (Emergency)',
-    stages: ['/dev', '/validate', '/ship'],
-    tdd: 'required',  // Must reproduce bug
-    research: 'skip',
-    description: 'Production bugs, urgent fixes',
-    keywords: ['urgent', 'production', 'emergency', 'hotfix', 'critical']
-  },
-
-  docs: {
-    name: 'Docs (Documentation Only)',
-    stages: ['/verify', '/ship', '/premerge'],
-    tdd: 'no',
-    research: 'no',
-    description: 'Documentation updates, README changes'
-  },
-
-  refactor: {
-    name: 'Refactor (Behavior-Preserving)',
-    stages: ['/plan', '/dev', '/validate', '/ship', '/premerge'],
-    tdd: 'strict',  // Must preserve behavior
-    research: 'optional',
-    description: 'Code cleanup, optimization, behavior-preserving improvements'
-  }
-};
-
-/**
- * Generic keyword detection helper (DRY utility)
- * @param {string} text - Text to analyze
- * @param {string[]} keywords - Keywords to search for
- * @returns {boolean} - True if any keyword found
- */
-function containsKeywords(text, keywords) {
-  if (!text || typeof text !== 'string') return false;
-  const lowerText = text.toLowerCase();
-  return keywords.some(keyword => lowerText.includes(keyword));
-}
-
-/**
- * Detects if text contains critical keywords (auth, security, payment, etc.)
- * @param {string} text - Text to analyze (branch name, commit message, etc.)
- * @returns {boolean} - True if critical keywords found
- */
-function containsCriticalKeywords(text) {
-  const keywords = ['auth', 'security', 'payment', 'crypto', 'password', 'token', 'session', 'migration', 'breaking'];
-  return containsKeywords(text, keywords);
-}
-
-/**
- * Detects if text contains hotfix keywords (urgent, production, emergency, etc.)
- * @param {string} text - Text to analyze (branch name, commit message, etc.)
- * @returns {boolean} - True if hotfix keywords found
- */
-function containsHotfixKeywords(text) {
-  const keywords = ['urgent', 'production', 'emergency', 'hotfix', 'critical'];
-  return containsKeywords(text, keywords);
-}
-
-/**
- * Detects user-facing work type from context (4 simple types)
- * @param {Object} context - Detection context
- * @param {string} context.branch - Git branch name
- * @returns {string} - User type: 'feature' | 'fix' | 'refactor' | 'chore'
- */
-function getUserType(context) {
-  const branch = context.branch || '';
-  const branchLower = branch.toLowerCase();
-
-  // Detect from branch prefix
-  if (branchLower.startsWith('feat/')) return 'feature';
-  if (branchLower.startsWith('fix/')) return 'fix';
-  if (branchLower.startsWith('hotfix/')) return 'fix';
-  if (branchLower.startsWith('refactor/')) return 'refactor';
-  if (branchLower.startsWith('docs/')) return 'chore';
-  if (branchLower.startsWith('chore/')) return 'chore';
-
-  // Default: feature (safest - full workflow)
-  return 'feature';
-}
-
-/**
- * Maps user type to internal profile with keyword-based escalation (6 granular profiles)
- * @param {string} userType - User-facing type: 'feature' | 'fix' | 'refactor' | 'chore'
- * @param {Object} context - Detection context
- * @param {string[]} context.keywords - Keywords from branch/commit
- * @param {string[]} context.files - Modified files
- * @returns {string} - Internal profile: 'critical' | 'standard' | 'simple' | 'hotfix' | 'docs' | 'refactor'
- */
-function getInternalProfile(userType, context) {
-  const keywords = context.keywords || [];
-  const files = context.files || [];
-
-  // Combine all keywords into a single string for analysis
-  const keywordText = keywords.join(' ');
-
-  switch (userType) {
-    case 'feature':
-      // Auto-escalate to Critical if security-sensitive
-      return containsCriticalKeywords(keywordText) ? 'critical' : 'standard';
-
-    case 'fix':
-      // Auto-escalate to Hotfix if urgent/production
-      return containsHotfixKeywords(keywordText) ? 'hotfix' : 'simple';
-
-    case 'refactor':
-      // 1:1 mapping
-      return 'refactor';
-
-    case 'chore':
-      // Docs if only markdown files, otherwise Simple
-      if (files.length > 0 && files.every(f => f.endsWith('.md'))) {
-        return 'docs';
-      }
-      return 'simple';
-
-    default:
-      return 'standard';
-  }
-}
-
-/**
- * Main detection function - detects work type and selects appropriate profile
- * @param {Object} context - Detection context
- * @param {string} context.manualProfile - Manual profile override (optional)
- * @param {string} context.branch - Git branch name
- * @param {string[]} context.keywords - Keywords from branch/commit
- * @param {string[]} context.files - Modified files
- * @returns {Object} - { userType, profile, source }
- */
-function detectWorkType(context) {
-  // Priority 1: Manual override (power users)
-  if (context.manualProfile) {
-    return {
-      userType: null,
-      profile: context.manualProfile,
-      source: 'manual'
-    };
-  }
-
-  // Priority 2: Detect simple user type (4 options)
-  const userType = getUserType(context);
-
-  // Priority 3: Auto-select granular internal profile (6 options)
-  const profile = getInternalProfile(userType, context);
-
-  return {
-    userType,
-    profile,
-    source: 'auto'
-  };
-}
-
-module.exports = {
-  PROFILES,
-  containsCriticalKeywords,
-  containsHotfixKeywords,
-  getUserType,
-  getInternalProfile,
-  detectWorkType
-};
+/**
+ * Workflow Profiles
+ *
+ * Implements hybrid approach: 4 user-facing types (Feature/Fix/Refactor/Chore)
+ * map to 6 internal profiles (Critical/Standard/Simple/Hotfix/Docs/Refactor)
+ * with keyword-based auto-escalation.
+ */
+
+/**
+ * Internal workflow profiles aligned with AGENTS.md specification
+ */
+const PROFILES = {
+  critical: {
+    name: 'Critical (Maximum Rigor)',
+    stages: ['/status', '/plan', '/dev', '/validate', '/ship', '/review', '/premerge', '/verify'],
+    tdd: 'strict',
+    research: 'required',
+    description: 'Security, auth, payments, data integrity, breaking changes',
+    keywords: ['auth', 'security', 'payment', 'crypto', 'password', 'token', 'session', 'data-migration', 'breaking']
+  },
+
+  standard: {
+    name: 'Standard (Full Workflow)',
+    stages: ['/status', '/plan', '/dev', '/validate', '/ship', '/review', '/premerge'],
+    tdd: 'required',
+    research: 'optional',
+    description: 'Most features and non-critical enhancements'
+  },
+
+  simple: {
+    name: 'Simple (Streamlined)',
+    stages: ['/dev', '/validate', '/ship', '/premerge'],
+    tdd: 'recommended',
+    research: 'skip',
+    description: 'UI tweaks, small improvements, minor fixes'
+  },
+
+  hotfix: {
+    name: 'Hotfix (Emergency)',
+    stages: ['/dev', '/validate', '/ship'],
+    tdd: 'required',  // Must reproduce bug
+    research: 'skip',
+    description: 'Production bugs, urgent fixes',
+    keywords: ['urgent', 'production', 'emergency', 'hotfix', 'critical']
+  },
+
+  docs: {
+    name: 'Docs (Documentation Only)',
+    stages: ['/verify', '/ship', '/premerge'],
+    tdd: 'no',
+    research: 'no',
+    description: 'Documentation updates, README changes'
+  },
+
+  refactor: {
+    name: 'Refactor (Behavior-Preserving)',
+    stages: ['/plan', '/dev', '/validate', '/ship', '/premerge'],
+    tdd: 'strict',  // Must preserve behavior
+    research: 'optional',
+    description: 'Code cleanup, optimization, behavior-preserving improvements'
+  }
+};
+
+/**
+ * Generic keyword detection helper (DRY utility)
+ * @param {string} text - Text to analyze
+ * @param {string[]} keywords - Keywords to search for
+ * @returns {boolean} - True if any keyword found
+ */
+function containsKeywords(text, keywords) {
+  if (!text || typeof text !== 'string') return false;
+  const lowerText = text.toLowerCase();
+  return keywords.some(keyword => lowerText.includes(keyword));
+}
+
+/**
+ * Detects if text contains critical keywords (auth, security, payment, etc.)
+ * @param {string} text - Text to analyze (branch name, commit message, etc.)
+ * @returns {boolean} - True if critical keywords found
+ */
+function containsCriticalKeywords(text) {
+  const keywords = ['auth', 'security', 'payment', 'crypto', 'password', 'token', 'session', 'migration', 'breaking'];
+  return containsKeywords(text, keywords);
+}
+
+/**
+ * Detects if text contains hotfix keywords (urgent, production, emergency, etc.)
+ * @param {string} text - Text to analyze (branch name, commit message, etc.)
+ * @returns {boolean} - True if hotfix keywords found
+ */
+function containsHotfixKeywords(text) {
+  const keywords = ['urgent', 'production', 'emergency', 'hotfix', 'critical'];
+  return containsKeywords(text, keywords);
+}
+
+/**
+ * Detects user-facing work type from context (4 simple types)
+ * @param {Object} context - Detection context
+ * @param {string} context.branch - Git branch name
+ * @returns {string} - User type: 'feature' | 'fix' | 'refactor' | 'chore'
+ */
+function getUserType(context) {
+  const branch = context.branch || '';
+  const branchLower = branch.toLowerCase();
+
+  // Detect from branch prefix
+  if (branchLower.startsWith('feat/')) return 'feature';
+  if (branchLower.startsWith('fix/')) return 'fix';
+  if (branchLower.startsWith('hotfix/')) return 'fix';
+  if (branchLower.startsWith('refactor/')) return 'refactor';
+  if (branchLower.startsWith('docs/')) return 'chore';
+  if (branchLower.startsWith('chore/')) return 'chore';
+
+  // Default: feature (safest - full workflow)
+  return 'feature';
+}
+
+/**
+ * Maps user type to internal profile with keyword-based escalation (6 granular profiles)
+ * @param {string} userType - User-facing type: 'feature' | 'fix' | 'refactor' | 'chore'
+ * @param {Object} context - Detection context
+ * @param {string[]} context.keywords - Keywords from branch/commit
+ * @param {string[]} context.files - Modified files
+ * @returns {string} - Internal profile: 'critical' | 'standard' | 'simple' | 'hotfix' | 'docs' | 'refactor'
+ */
+function getInternalProfile(userType, context) {
+  const keywords = context.keywords || [];
+  const files = context.files || [];
+
+  // Combine all keywords into a single string for analysis
+  const keywordText = keywords.join(' ');
+
+  switch (userType) {
+    case 'feature':
+      // Auto-escalate to Critical if security-sensitive
+      return containsCriticalKeywords(keywordText) ? 'critical' : 'standard';
+
+    case 'fix':
+      // Auto-escalate to Hotfix if urgent/production
+      return containsHotfixKeywords(keywordText) ? 'hotfix' : 'simple';
+
+    case 'refactor':
+      // 1:1 mapping
+      return 'refactor';
+
+    case 'chore':
+      // Docs if only markdown files, otherwise Simple
+      if (files.length > 0 && files.every(f => f.endsWith('.md'))) {
+        return 'docs';
+      }
+      return 'simple';
+
+    default:
+      return 'standard';
+  }
+}
+
+/**
+ * Main detection function - detects work type and selects appropriate profile
+ * @param {Object} context - Detection context
+ * @param {string} context.manualProfile - Manual profile override (optional)
+ * @param {string} context.branch - Git branch name
+ * @param {string[]} context.keywords - Keywords from branch/commit
+ * @param {string[]} context.files - Modified files
+ * @returns {Object} - { userType, profile, source }
+ */
+function detectWorkType(context) {
+  // Priority 1: Manual override (power users)
+  if (context.manualProfile) {
+    return {
+      userType: null,
+      profile: context.manualProfile,
+      source: 'manual'
+    };
+  }
+
+  // Priority 2: Detect simple user type (4 options)
+  const userType = getUserType(context);
+
+  // Priority 3: Auto-select granular internal profile (6 options)
+  const profile = getInternalProfile(userType, context);
+
+  return {
+    userType,
+    profile,
+    source: 'auto'
+  };
+}
+
+module.exports = {
+  PROFILES,
+  containsCriticalKeywords,
+  containsHotfixKeywords,
+  getUserType,
+  getInternalProfile,
+  detectWorkType
+};