forge-workflow 0.0.4 → 0.0.6

package/lib/beads-sync-scaffold.js

@@ -0,0 +1,260 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+/**
+ * Detect the default branch of the repository.
+ *
+ * Strategy (in order):
+ *   1. `git symbolic-ref refs/remotes/origin/HEAD` -> parse branch name
+ *   2. `git remote show origin` -> parse "HEAD branch:" line
+ *   3. Fall back to `'main'`
+ *
+ * @param {string} projectRoot - Absolute path to the project root.
+ * @param {object} [options] - Options object.
+ * @param {Function} [options._exec] - Injected execFileSync for testing.
+ * @returns {string} The default branch name.
+ */
+function detectDefaultBranch(projectRoot, options = {}) {
+  const exec = options._exec || execFileSync;
+
+  // Strategy 1: symbolic-ref
+  try {
+    const out = exec('git', ['symbolic-ref', 'refs/remotes/origin/HEAD'], {
+      cwd: projectRoot,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    const ref = out.toString().trim();
+    // refs/remotes/origin/main -> main
+    const parts = ref.split('/');
+    if (parts.length > 0) {
+      return parts[parts.length - 1];
+    }
+  } catch (_e) {
+    // Expected: symbolic-ref fails when origin/HEAD is not set — fall through to strategy 2
+  }
+
+  // Strategy 2: remote show origin
+  try {
+    const out = exec('git', ['remote', 'show', 'origin'], {
+      cwd: projectRoot,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    const text = out.toString();
+    const match = text.match(/HEAD branch:\s*(.+)/);
+    if (match) {
+      return match[1].trim();
+    }
+  } catch (_e) {
+    // Expected: 'git remote show origin' fails when no remote is configured — fall through to fallback
+  }
+
+  // Strategy 3: fallback
+  return 'main';
+}
+
+/**
+ * Detect the installed Beads version.
+ *
+ * Strategy (in order):
+ *   1. `bd --version` -> parse version string (e.g. "beads version 0.52.0" -> "0.52.0")
+ *   2. Fall back to known-good default `'0.49.1'`
+ *
+ * @param {object} [options] - Options object.
+ * @param {Function} [options._exec] - Injected execFileSync for testing.
+ * @returns {string} The Beads version string.
+ */
+function detectBeadsVersion(options = {}) {
+  const exec = options._exec || execFileSync;
+
+  try {
+    const out = exec('bd', ['--version'], {
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    const text = out.toString().trim();
+    // "beads version 0.52.0" -> "0.52.0"
+    const match = text.match(/(\d{1,4}\.\d{1,4}\.\d{1,4})/);
+    if (match) {
+      return match[1];
+    }
+  } catch (_e) {
+    // Expected: 'bd --version' fails when bd CLI is not installed — fall through to default version
+  }
+
+  return '0.49.1';
+}
+
+/**
+ * Template workflow YAML files by replacing the default branch and Beads version.
+ *
+ * Templates only forge-created workflow files by replacing the default branch
+ * and Beads version. Skips user-owned workflows to avoid overwriting legitimate
+ * branch targets.
+ *
+ * @param {string} workflowDir - Absolute path to the directory containing YAML files.
+ * @param {string} branch - The default branch name to substitute.
+ * @param {string} beadsVersion - The Beads version to substitute.
+ * @param {string[]} [createdFiles=[]] - List of file paths created by scaffoldBeadsSync. Only these are templated.
+ */
+function templateWorkflows(workflowDir, branch, beadsVersion, createdFiles = []) {
+  if (!fs.existsSync(workflowDir)) return;
+
+  const targetNames = new Set(createdFiles.map(f => path.basename(f)));
+
+  const entries = fs.readdirSync(workflowDir);
+
+  for (const entry of entries) {
+    // Only template forge-created files; skip user-owned workflows
+    if (targetNames.size > 0 && !targetNames.has(entry)) continue;
+
+    const ext = path.extname(entry).toLowerCase();
+    if (ext !== '.yml' && ext !== '.yaml') {
+      continue;
+    }
+
+    const filePath = path.join(workflowDir, entry);
+    const stat = fs.statSync(filePath);
+    if (!stat.isFile()) {
+      continue;
+    }
+
+    const original = fs.readFileSync(filePath, 'utf8');
+    let content = original;
+    content = content.replaceAll(
+      /branches:\s*\[master\]/g,
+      `branches: [${branch}]`
+    );
+    content = content.replaceAll(
+      /BD_VERSION="0\.49\.1"/g,
+      `BD_VERSION="${beadsVersion}"`
+    );
+    // Only write if content actually changed
+    if (content !== original) {
+      fs.writeFileSync(filePath, content);
+    }
+  }
+}
+
+/**
+ * @typedef {Object} ScaffoldResult
+ * @property {string[]} filesCreated - Relative paths of files written (new or overwritten)
+ * @property {string[]} filesSkipped - Relative paths of files that already existed and were preserved
+ */
+
+/**
+ * Copy a single file from src to dest, creating parent directories as needed.
+ *
+ * @param {string} src - Absolute source path
+ * @param {string} dest - Absolute destination path
+ * @returns {void}
+ */
+function copyFileWithDirs(src, dest) {
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.copyFileSync(src, dest);
+}
+
+/**
+ * Scaffold Beads sync workflows and scripts to the user's project.
+ *
+ * Copies workflow templates, sync modules, config, and mapping stub into
+ * the project's `.github/` tree from the forge package source.
+ *
+ * @param {string} projectRoot - Absolute path to the user's project root
+ * @param {string} packageDir - Absolute path to the forge package install location
+ * @param {Object} [_options={}] - Reserved for future options
+ * @returns {ScaffoldResult}
+ */
+function scaffoldBeadsSync(projectRoot, packageDir, _options = {}) {
+  /** @type {string[]} */
+  const filesCreated = [];
+  /** @type {string[]} */
+  const filesSkipped = [];
+
+  const githubDir = path.join(projectRoot, '.github');
+
+  // --- Step a: Copy workflow templates ---
+  const workflowNames = ['github-to-beads.yml', 'beads-to-github.yml'];
+  const srcWorkflowsDir = path.join(packageDir, '.github', 'workflows');
+
+  for (const name of workflowNames) {
+    const src = path.join(srcWorkflowsDir, name);
+    const relPath = `.github/workflows/${name}`;
+    const dest = path.join(projectRoot, '.github', 'workflows', name);
+
+    if (!fs.existsSync(src)) continue;
+    if (fs.existsSync(dest)) {
+      filesSkipped.push(relPath);
+    } else {
+      copyFileWithDirs(src, dest);
+      filesCreated.push(relPath);
+    }
+  }
+
+  // --- Step b: Copy sync modules ---
+  const srcSyncDir = path.join(packageDir, 'scripts', 'github-beads-sync');
+  const destSyncDir = path.join(githubDir, 'scripts', 'beads-sync');
+
+  if (fs.existsSync(srcSyncDir)) {
+    const entries = fs.readdirSync(srcSyncDir);
+    for (const entry of entries) {
+      const srcFile = path.join(srcSyncDir, entry);
+      const stat = fs.statSync(srcFile);
+      if (stat.isFile()) {
+        const relPath = `.github/scripts/beads-sync/${entry}`;
+        const dest = path.join(destSyncDir, entry);
+        if (fs.existsSync(dest)) {
+          filesSkipped.push(relPath);
+        } else {
+          copyFileWithDirs(srcFile, dest);
+          filesCreated.push(relPath);
+        }
+      }
+    }
+  }
+
+  // --- Step c: Create beads-sync-config.json ---
+  const configRelPath = '.github/beads-sync-config.json';
+  const configDest = path.join(githubDir, 'beads-sync-config.json');
+  const srcConfig = path.join(packageDir, 'scripts', 'github-beads-sync.config.json');
+
+  if (fs.existsSync(configDest)) {
+    filesSkipped.push(configRelPath);
+  } else if (fs.existsSync(srcConfig)) {
+    copyFileWithDirs(srcConfig, configDest);
+    filesCreated.push(configRelPath);
+  } else {
+    // Create a sensible default config
+    const defaultConfig = {
+      defaultType: 'task',
+      defaultPriority: 2,
+      mapAssignee: true,
+      publicRepoGate: 'none'
+    };
+    fs.mkdirSync(path.dirname(configDest), { recursive: true });
+    fs.writeFileSync(configDest, JSON.stringify(defaultConfig, null, 2) + '\n');
+    filesCreated.push(configRelPath);
+  }
+
+  // --- Step d: Create beads-mapping.json if not exists ---
+  const mappingRelPath = '.github/beads-mapping.json';
+  const mappingDest = path.join(githubDir, 'beads-mapping.json');
+
+  if (fs.existsSync(mappingDest)) {
+    filesSkipped.push(mappingRelPath);
+  } else {
+    fs.mkdirSync(path.dirname(mappingDest), { recursive: true });
+    fs.writeFileSync(mappingDest, '{}');
+    filesCreated.push(mappingRelPath);
+  }
+
+  return { filesCreated, filesSkipped };
+}
+
+module.exports = {
+  detectDefaultBranch,
+  detectBeadsVersion,
+  templateWorkflows,
+  scaffoldBeadsSync,
+};

package/lib/commands/_registry.js

@@ -0,0 +1,134 @@
+/**
+ * Command Registry — Auto-Discovery
+ *
+ * Scans a commands directory for .js files, validates each exports
+ * { name, description, handler }, and builds a routing Map.
+ *
+ * Follows the same fs.readdirSync() pattern as lib/plugin-manager.js.
+ *
+ * @module _registry
+ */
+
+const { existsSync, readdirSync } = require('node:fs');
+const path = require('node:path');
+
+/**
+ * @typedef {Object} CommandModule
+ * @property {string} name - Command name used for routing
+ * @property {string} description - Human-readable description
+ * @property {function(Array, Object, string): Promise<*>} handler - Async command handler
+ * @property {string} [usage] - Usage string (optional)
+ * @property {Object<string, string>} [flags] - Flag descriptions (optional)
+ */
+
+/**
+ * Validate that a module exports the required command interface.
+ *
+ * @param {*} mod - The required module
+ * @returns {{ valid: boolean, reason?: string }}
+ */
+function validateCommand(mod) {
+  if (!mod || typeof mod !== 'object') {
+    return { valid: false, reason: 'module does not export an object' };
+  }
+  if (typeof mod.name !== 'string' || !mod.name) {
+    return { valid: false, reason: 'missing or invalid "name" export' };
+  }
+  if (typeof mod.description !== 'string' || !mod.description) {
+    return { valid: false, reason: 'missing or invalid "description" export' };
+  }
+  if (typeof mod.handler !== 'function') {
+    return { valid: false, reason: 'missing or invalid "handler" export' };
+  }
+  return { valid: true };
+}
+
+/**
+ * Load and discover command modules from a directory.
+ *
+ * Scans `commandsDir` for `.js` files (excluding files starting with `_`),
+ * validates each module exports `{ name, description, handler }`, and builds
+ * a routing Map keyed by command name.
+ *
+ * Malformed modules are skipped with a `console.warn` — other commands
+ * continue loading. Duplicate command names warn and skip the later file.
+ *
+ * @param {string} commandsDir - Absolute path to the commands directory
+ * @returns {{ commands: Map<string, CommandModule>, getHelp: () => string }}
+ */
+function loadCommands(commandsDir) {
+  /** @type {Map<string, CommandModule>} */
+  const commands = new Map();
+
+  if (!commandsDir || !existsSync(commandsDir)) {
+    return {
+      commands,
+      getHelp: () => buildHelp(commands),
+    };
+  }
+
+  const files = readdirSync(commandsDir)
+    .filter(f => f.endsWith('.js') && !f.startsWith('_'))
+    .sort(); // deterministic order — first file wins on duplicates
+
+  for (const file of files) {
+    const filePath = path.join(commandsDir, file);
+
+    let mod;
+    try {
+      mod = require(filePath);
+    } catch (_err) {
+      console.warn(`[registry] Skipping ${file}: failed to load — ${_err.message}`);
+      continue;
+    }
+
+    const validation = validateCommand(mod);
+    if (!validation.valid) {
+      console.warn(`[registry] Skipping ${file}: ${validation.reason}`);
+      continue;
+    }
+
+    if (commands.has(mod.name)) {
+      console.warn(
+        `[registry] Skipping ${file}: duplicate command name "${mod.name}"`
+      );
+      continue;
+    }
+
+    commands.set(mod.name, mod);
+  }
+
+  return {
+    commands,
+    getHelp: () => buildHelp(commands),
+  };
+}
+
+/**
+ * Build a formatted help string from discovered commands.
+ *
+ * @param {Map<string, CommandModule>} commands
+ * @returns {string}
+ */
+function buildHelp(commands) {
+  if (commands.size === 0) {
+    return 'No commands available.';
+  }
+
+  const lines = ['Available commands:', ''];
+
+  // Find the longest name for alignment
+  let maxLen = 0;
+  for (const name of commands.keys()) {
+    if (name.length > maxLen) maxLen = name.length;
+  }
+
+  for (const [name, cmd] of commands) {
+    const padding = ' '.repeat(maxLen - name.length + 2);
+    lines.push(`  ${name}${padding}${cmd.description}`);
+  }
+
+  return lines.join('\n');
+}
+
+module.exports = { loadCommands, validateCommand };

package/lib/commands/clean.js

@@ -0,0 +1,181 @@
+'use strict';
+
+const { execFileSync } = require('node:child_process');
+const fs = require('node:fs');
+const path = require('node:path');
+const { stopDolt } = require('./worktree');
+
+/**
+ * Forge Clean Command
+ * Remove worktrees for merged branches, stopping Dolt servers first.
+ * Uses execFileSync (not execSync) to prevent command injection (OWASP A03).
+ *
+ * @module commands/clean
+ */
+
+/**
+ * Detect the default branch (main, master, develop, trunk).
+ * Tries origin/HEAD first, then probes common names.
+ * @param {Function} runFile - execFileSync-compatible function
+ * @returns {string} Default branch name
+ */
+function getDefaultBranch(runFile) {
+  try {
+    return runFile('git', ['rev-parse', '--abbrev-ref', 'origin/HEAD'], { stdio: 'pipe' })
+      .toString().trim().replace('origin/', '');
+  } catch (_e) { /* intentional: origin/HEAD not set, probe common names */ // NOSONAR S2486
+    for (const name of ['main', 'master', 'develop', 'trunk']) {
+      try {
+        runFile('git', ['rev-parse', '--verify', name], { stdio: 'pipe' });
+        return name;
+      } catch (_e2) { /* intentional: try next branch name */ } // NOSONAR S2486
+    }
+    return 'main';
+  }
+}
+
+/**
+ * Parse `git worktree list --porcelain` output into a map of path -> branch.
+ * @param {string} output - Raw porcelain output
+ * @returns {Map<string, string>} Map of worktree path -> branch name
+ */
+function parseWorktreeList(output) {
+  const map = new Map();
+  const blocks = output.split('\n\n');
+  for (const block of blocks) {
+    const lines = block.trim().split('\n');
+    let wtPath = null;
+    let branch = null;
+    for (const line of lines) {
+      if (line.startsWith('worktree ')) {
+        wtPath = line.slice('worktree '.length);
+      }
+      if (line.startsWith('branch ')) {
+        // branch refs/heads/feat/foo -> feat/foo
+        branch = line.slice('branch refs/heads/'.length);
+      }
+    }
+    if (wtPath && branch) {
+      map.set(wtPath, branch);
+    }
+  }
+  return map;
+}
+
+/**
+ * Clean a single worktree directory if its branch is merged.
+ * @param {string} dir - Directory name within .worktrees/
+ * @param {Map<string, string>} worktreeMap - Path-to-branch mapping
+ * @param {string[]} mergedBranches - List of merged branch names
+ * @param {string} worktreesDir - Absolute path to .worktrees/
+ * @param {boolean} dryRun - If true, skip actual removal
+ * @param {Function} runFile - execFileSync-compatible function
+ * @param {object} fsApi - fs module (for DI)
+ * @returns {Promise<boolean>} True if the worktree was cleaned (or would be in dry-run)
+ */
+async function cleanWorktree(dir, worktreeMap, mergedBranches, worktreesDir, dryRun, runFile, fsApi) {
+  const wtPath = path.resolve(worktreesDir, dir);
+  const branch = worktreeMap.get(wtPath);
+
+  if (branch && mergedBranches.includes(branch)) {
+    if (!dryRun) {
+      const stopResult = stopDolt(wtPath, { _exec: runFile, _fs: fsApi });
+      if (stopResult.stopped) {
+        await new Promise(r => setTimeout(r, 500));
+      }
+      try {
+        runFile('git', ['worktree', 'remove', wtPath], { stdio: 'pipe' });
+      } catch (_removeErr) { /* intentional: worktree has uncommitted changes, skip */ // NOSONAR S2486
+        return false;
+      }
+    }
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Main handler for the clean command.
+ * @param {string[]} _args - Positional arguments (unused)
+ * @param {object} flags - CLI flags
+ * @param {string} projectRoot - Project root path
+ * @param {object} [opts] - Options for dependency injection
+ * @param {Function} [opts._exec] - Override for execFileSync (testing)
+ * @param {object} [opts._fs] - Override for fs module (testing)
+ * @returns {Promise<{ success: boolean, cleaned: number, active: number, dryRun: boolean }>}
+ */
+async function handler(_args, flags, projectRoot, opts = {}) {
+  const runFile = opts._exec || execFileSync;
+  const fsApi = opts._fs || fs;
+  const dryRun = !!(flags['--dry-run'] || flags.dryRun);
+
+  const worktreesDir = path.resolve(projectRoot, '.worktrees');
+
+  // If .worktrees/ doesn't exist, nothing to clean
+  if (!fsApi.existsSync(worktreesDir)) {
+    return { success: true, cleaned: 0, active: 0, dryRun };
+  }
+
+  // 1. List dirs in .worktrees/
+  const entries = fsApi.readdirSync(worktreesDir, { withFileTypes: true });
+  const dirs = entries.filter(e => e.isDirectory()).map(e => e.name);
+
+  if (dirs.length === 0) {
+    return { success: true, cleaned: 0, active: 0, dryRun };
+  }
+
+  // 2. Detect default branch, then get merged branches
+  const defaultBranch = getDefaultBranch(runFile);
+  let mergedBranches;
+  try {
+    const mergedOutput = runFile('git', ['branch', '--merged', defaultBranch], { stdio: 'pipe' });
+    mergedBranches = mergedOutput
+      .toString()
+      .split('\n')
+      .map(b => b.trim().replace(/^\*\s*/, ''))
+      .filter(b => b.length > 0);
+  } catch (_e) { /* intentional: fallback to empty list */ // NOSONAR S2486
+    mergedBranches = [];
+  }
+
+  // 3. Get worktree -> branch mapping from git
+  let worktreeMap;
+  try {
+    const listOutput = runFile('git', ['worktree', 'list', '--porcelain'], { stdio: 'pipe' });
+    worktreeMap = parseWorktreeList(listOutput.toString());
+  } catch (_e) { /* intentional: fallback to empty map */ // NOSONAR S2486
+    worktreeMap = new Map();
+  }
+
+  // 4. For each worktree dir, check if its branch is merged
+  let cleaned = 0;
+  let active = 0;
+
+  for (const dir of dirs) {
+    const wasCleaned = await cleanWorktree(dir, worktreeMap, mergedBranches, worktreesDir, dryRun, runFile, fsApi);
+    if (wasCleaned) {
+      cleaned++;
+    } else {
+      active++;
+    }
+  }
+
+  // Prune stale worktree refs to prevent bare repo state
+  if (!dryRun && cleaned > 0) {
+    try {
+      runFile('git', ['worktree', 'prune'], { stdio: 'pipe' });
+    } catch (_e) { /* intentional: prune is best-effort cleanup */ } // NOSONAR S2486
+  }
+
+  return { success: true, cleaned, active, dryRun };
+}
+
+module.exports = {
+  name: 'clean',
+  description: 'Remove worktrees for merged branches (stops Dolt servers)',
+  usage: 'forge clean [--dry-run]',
+  flags: {
+    '--dry-run': 'Show what would be cleaned without removing',
+  },
+  handler,
+};