forge-workflow 0.0.4 → 0.0.5

package/lib/setup.js

@@ -1,192 +1,192 @@
-const fs = require('node:fs');
-const path = require('node:path');
-
-/**
- * Save setup state to .forge/setup-state.json
- * @param {string} projectPath - Path to the project root
- * @param {Object} state - Setup state object
- * @param {string} state.version - Forge version
- * @param {string[]} state.completed_steps - List of completed steps
- * @param {string[]} state.pending_steps - List of pending steps
- * @param {string} [state.last_run] - ISO timestamp of last run
- * @returns {Promise<void>}
- */
-async function saveSetupState(projectPath, state) {
-  const forgeDir = path.join(projectPath, '.forge');
-  const setupStatePath = path.join(forgeDir, 'setup-state.json');
-
-  // Ensure .forge directory exists
-  await fs.promises.mkdir(forgeDir, { recursive: true });
-
-  // Add last_run timestamp if not provided
-  if (!state.last_run) {
-    state.last_run = new Date().toISOString();
-  }
-
-  // Write state as JSON
-  await fs.promises.writeFile(setupStatePath, JSON.stringify(state, null, 2), 'utf-8');
-}
-
-/**
- * Load setup state from .forge/setup-state.json
- * @param {string} projectPath - Path to the project root
- * @returns {Promise<Object|null>} Setup state object, or null if not found or invalid
- */
-async function loadSetupState(projectPath) {
-  const setupStatePath = path.join(projectPath, '.forge', 'setup-state.json');
-
-  try {
-    const content = await fs.promises.readFile(setupStatePath, 'utf-8');
-    return JSON.parse(content);
-  } catch (_error) {
-    // File doesn't exist or invalid JSON
-    return null;
-  }
-}
-
-/**
- * Check if setup is complete (no pending steps)
- * @param {string} projectPath - Path to the project root
- * @returns {Promise<boolean>} True if setup complete, false otherwise
- */
-async function isSetupComplete(projectPath) {
-  const state = await loadSetupState(projectPath);
-
-  if (!state) {
-    return false;
-  }
-
-  // Setup is complete if pending_steps is empty
-  return state.pending_steps.length === 0;
-}
-
-/**
- * Get the next pending step
- * @param {string} projectPath - Path to the project root
- * @returns {Promise<string|null>} Next step name, or null if none
- */
-async function getNextStep(projectPath) {
-  const state = await loadSetupState(projectPath);
-
-  if (!state || !state.pending_steps || state.pending_steps.length === 0) {
-    return null;
-  }
-
-  // Return first pending step
-  return state.pending_steps[0];
-}
-
-/**
- * Mark a step as complete (move from pending to completed)
- * @param {string} projectPath - Path to the project root
- * @param {string} stepName - Name of the step to mark complete
- * @returns {Promise<void>}
- */
-async function markStepComplete(projectPath, stepName) {
-  let state = await loadSetupState(projectPath);
-
-  // If no state exists, create initial state
-  if (!state) {
-    state = {
-      version: '1.6.0',
-      completed_steps: [],
-      pending_steps: []
-    };
-  }
-
-  // Remove from pending_steps if present
-  state.pending_steps = state.pending_steps.filter(step => step !== stepName);
-
-  // Add to completed_steps if not already there
-  if (!state.completed_steps.includes(stepName)) {
-    state.completed_steps.push(stepName);
-  }
-
-  // Update last_run timestamp
-  state.last_run = new Date().toISOString();
-
-  // Save updated state
-  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,
-  scaffoldGithubBeadsSync
-};
+const fs = require('node:fs');
+const path = require('node:path');
+
+/**
+ * Save setup state to .forge/setup-state.json
+ * @param {string} projectPath - Path to the project root
+ * @param {Object} state - Setup state object
+ * @param {string} state.version - Forge version
+ * @param {string[]} state.completed_steps - List of completed steps
+ * @param {string[]} state.pending_steps - List of pending steps
+ * @param {string} [state.last_run] - ISO timestamp of last run
+ * @returns {Promise<void>}
+ */
+async function saveSetupState(projectPath, state) {
+  const forgeDir = path.join(projectPath, '.forge');
+  const setupStatePath = path.join(forgeDir, 'setup-state.json');
+
+  // Ensure .forge directory exists
+  await fs.promises.mkdir(forgeDir, { recursive: true });
+
+  // Add last_run timestamp if not provided
+  if (!state.last_run) {
+    state.last_run = new Date().toISOString();
+  }
+
+  // Write state as JSON
+  await fs.promises.writeFile(setupStatePath, JSON.stringify(state, null, 2), 'utf-8');
+}
+
+/**
+ * Load setup state from .forge/setup-state.json
+ * @param {string} projectPath - Path to the project root
+ * @returns {Promise<Object|null>} Setup state object, or null if not found or invalid
+ */
+async function loadSetupState(projectPath) {
+  const setupStatePath = path.join(projectPath, '.forge', 'setup-state.json');
+
+  try {
+    const content = await fs.promises.readFile(setupStatePath, 'utf-8');
+    return JSON.parse(content);
+  } catch (_error) {
+    // File doesn't exist or invalid JSON
+    return null;
+  }
+}
+
+/**
+ * Check if setup is complete (no pending steps)
+ * @param {string} projectPath - Path to the project root
+ * @returns {Promise<boolean>} True if setup complete, false otherwise
+ */
+async function isSetupComplete(projectPath) {
+  const state = await loadSetupState(projectPath);
+
+  if (!state) {
+    return false;
+  }
+
+  // Setup is complete if pending_steps is empty
+  return state.pending_steps.length === 0;
+}
+
+/**
+ * Get the next pending step
+ * @param {string} projectPath - Path to the project root
+ * @returns {Promise<string|null>} Next step name, or null if none
+ */
+async function getNextStep(projectPath) {
+  const state = await loadSetupState(projectPath);
+
+  if (!state || !state.pending_steps || state.pending_steps.length === 0) {
+    return null;
+  }
+
+  // Return first pending step
+  return state.pending_steps[0];
+}
+
+/**
+ * Mark a step as complete (move from pending to completed)
+ * @param {string} projectPath - Path to the project root
+ * @param {string} stepName - Name of the step to mark complete
+ * @returns {Promise<void>}
+ */
+async function markStepComplete(projectPath, stepName) {
+  let state = await loadSetupState(projectPath);
+
+  // If no state exists, create initial state
+  if (!state) {
+    state = {
+      version: '1.6.0',
+      completed_steps: [],
+      pending_steps: []
+    };
+  }
+
+  // Remove from pending_steps if present
+  state.pending_steps = state.pending_steps.filter(step => step !== stepName);
+
+  // Add to completed_steps if not already there
+  if (!state.completed_steps.includes(stepName)) {
+    state.completed_steps.push(stepName);
+  }
+
+  // Update last_run timestamp
+  state.last_run = new Date().toISOString();
+
+  // Save updated state
+  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,
+  scaffoldGithubBeadsSync
+};

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