forge-workflow 0.0.5 → 0.0.6

package/lib/commands/test.js

@@ -0,0 +1,207 @@
+'use strict';
+
+/**
+ * Test Command — Smart Test Runner
+ *
+ * Wraps test execution with smart defaults:
+ * - Auto-detects package manager from lockfiles
+ * - Checks Beads (Dolt) connectivity, sets BEADS_SKIP_TESTS if unavailable
+ * - Supports --affected flag to run only tests for changed files
+ *
+ * Security: Uses execFileSync for subprocess calls (OWASP A03)
+ *
+ * @module commands/test
+ */
+
+const { execFileSync: defaultExecFileSync, spawnSync: defaultSpawnSync } = require('node:child_process');
+const defaultFs = require('node:fs');
+const path = require('node:path');
+
+/** @type {Array<[string, string]>} Lockfile → package manager mapping (order matters) */
+const LOCKFILE_MAP = [
+	['bun.lockb', 'bun'],
+	['pnpm-lock.yaml', 'pnpm'],
+	['yarn.lock', 'yarn'],
+	['package-lock.json', 'npm'],
+];
+
+const DEFAULT_TIMEOUT = 120000;
+const BEADS_CHECK_TIMEOUT = 3000;
+
+/**
+ * Detect the package manager by checking which lockfile exists.
+ *
+ * @param {string} projectRoot - Absolute path to project root
+ * @param {Object} fs - Injected fs module
+ * @returns {string} Package manager command ('bun' | 'pnpm' | 'yarn' | 'npm')
+ */
+function detectPackageManager(projectRoot, fs) {
+	for (const [lockfile, manager] of LOCKFILE_MAP) {
+		if (fs.existsSync(path.join(projectRoot, lockfile))) {
+			return manager;
+		}
+	}
+	return 'npm';
+}
+
+/**
+ * Check if Beads (bd CLI) is reachable.
+ *
+ * @param {Function} execFileSync - Injected execFileSync
+ * @returns {boolean} true if bd is available
+ */
+function checkBeadsConnectivity(execFileSync) {
+	try {
+		execFileSync('bd', ['list', '--limit=1'], { timeout: BEADS_CHECK_TIMEOUT });
+		return true;
+	} catch (_e) { // NOSONAR S2486
+		/* intentional: bd not installed or unreachable */
+		return false;
+	}
+}
+
+/**
+ * Get changed files relative to main branch, mapped to test file paths.
+ *
+ * Falls back to `git diff --name-only HEAD` if merge-base fails.
+ *
+ * @param {string} _projectRoot - Project root (unused, git uses cwd)
+ * @param {Function} execFileSync - Injected execFileSync
+ * @returns {string[]} Array of test file paths (e.g. ['test/foo.test.js'])
+ */
+function getAffectedTestFiles(_projectRoot, execFileSync) {
+	let diffRef;
+
+	// Detect default branch, then try merge-base
+	let baseBranch = 'main';
+	try {
+		baseBranch = execFileSync('git', ['rev-parse', '--abbrev-ref', 'origin/HEAD'], {
+			encoding: 'utf8', timeout: 3000,
+		}).trim().replace('origin/', '');
+	} catch (_e) { // NOSONAR S2486
+		/* intentional: origin/HEAD not set, detect base branch manually */
+		for (const name of ['main', 'master']) {
+			try {
+				execFileSync('git', ['rev-parse', '--verify', name], { stdio: 'pipe', timeout: 3000 });
+				baseBranch = name;
+				break;
+			} catch (_e2) { /* intentional: branch doesn't exist, try next name */ } // NOSONAR S2486
+		}
+	}
+
+	try {
+		const mergeBase = execFileSync('git', ['merge-base', 'HEAD', baseBranch], {
+			encoding: 'utf8',
+			timeout: 5000,
+		}).trim();
+		diffRef = `${mergeBase}...HEAD`;
+	} catch (_e) { /* intentional: merge-base failed, fallback to diff against HEAD */ // NOSONAR S2486
+		diffRef = 'HEAD';
+	}
+
+	let output;
+	try {
+		output = execFileSync('git', ['diff', '--name-only', diffRef], {
+			encoding: 'utf8',
+			timeout: 5000,
+		}).trim();
+	} catch (_e) { // NOSONAR S2486
+		/* intentional: git diff failed, no affected files to report */
+		return [];
+	}
+
+	if (!output) return [];
+
+	const changedFiles = output.split('\n').filter(Boolean);
+
+	// Map lib/*.js files to test/*.test.js
+	const testFiles = [];
+	for (const file of changedFiles) {
+		if (file.startsWith('lib/') && file.endsWith('.js')) {
+			const relative = file.slice('lib/'.length);
+			const testFile = `test/${relative.replace(/\.js$/, '.test.js')}`;
+			testFiles.push(testFile);
+		}
+	}
+
+	return testFiles;
+}
+
+module.exports = {
+	name: 'test',
+	description: 'Run tests with smart defaults (timeout, Beads skip, affected-only)',
+	usage: 'forge test [--affected]',
+	flags: {
+		'--affected': 'Run only tests for changed files',
+	},
+
+	/**
+	 * Run tests with smart defaults.
+	 *
+	 * @param {string[]} _args - Positional arguments (unused)
+	 * @param {Object} flags - Parsed flags ({ affected?: boolean })
+	 * @param {string} projectRoot - Absolute path to project root
+	 * @param {Object} [deps] - Dependency injection for testability
+	 * @param {Object} [deps.fs] - fs module
+	 * @param {Function} [deps.execFileSync] - child_process.execFileSync
+	 * @param {Function} [deps.spawnSync] - child_process.spawnSync
+	 * @returns {Promise<{ success: boolean, exitCode: number, beadsSkipped: boolean }>}
+	 */
+	async handler(_args, flags, projectRoot, deps = {}) {
+		const fs = deps.fs || defaultFs;
+		const execFileSync = deps.execFileSync || defaultExecFileSync;
+		const spawnSync = deps.spawnSync || defaultSpawnSync;
+
+		// 1. Detect package manager
+		const pkgManager = detectPackageManager(projectRoot, fs);
+
+		// 2. Read timeout from package.json or use default
+		let timeout = DEFAULT_TIMEOUT;
+		try {
+			const pkgPath = path.join(projectRoot, 'package.json');
+			const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+			const testScript = pkg.scripts?.test || '';
+			const timeoutMatch = testScript.match(/--timeout\s+(\d+)/);
+			if (timeoutMatch) {
+				timeout = Number.parseInt(timeoutMatch[1], 10);
+			}
+		} catch (_e) { /* intentional: package.json missing or unreadable, use default timeout */ } // NOSONAR S2486
+
+		// 3. Check Beads connectivity
+		const beadsAvailable = checkBeadsConnectivity(execFileSync);
+		const beadsSkipped = !beadsAvailable;
+
+		const extraEnv = {};
+		if (beadsSkipped) {
+			extraEnv.BEADS_SKIP_TESTS = '1';
+		}
+
+		// 4. Build test command args
+		let testArgs = ['run', 'test'];
+
+		// 5. --affected flag: find changed test files
+		if (flags['--affected'] || flags.affected) {
+			const affectedTests = getAffectedTestFiles(projectRoot, execFileSync);
+			if (affectedTests.length > 0) {
+				testArgs = ['run', 'test', ...affectedTests];
+			}
+			// If no affected tests found, fall back to running all tests
+		}
+
+		// 6. Run tests
+		const result = spawnSync(pkgManager, testArgs, {
+			env: { ...process.env, ...extraEnv },
+			timeout,
+			stdio: 'inherit',
+			shell: process.platform === 'win32',
+		});
+
+		const exitCode = result.status ?? 1;
+
+		return {
+			success: exitCode === 0,
+			exitCode,
+			beadsSkipped,
+		};
+	},
+};

package/lib/commands/worktree.js

@@ -0,0 +1,310 @@
+'use strict';
+
+const { execFileSync, spawnSync } = require('node:child_process');
+const fs = require('node:fs');
+const path = require('node:path');
+
+/**
+ * Forge Worktree Command
+ * Manage isolated worktrees with Beads integration.
+ * Uses execFileSync (not execSync) to prevent command injection (OWASP A03).
+ *
+ * Subcommands:
+ *   create <slug> — Create worktree at .worktrees/<slug> with branch + beads + install
+ *   remove <slug> — Remove worktree via git worktree remove
+ *
+ * @module commands/worktree
+ */
+
+/**
+ * Detect the package manager for a project root.
+ * @param {string} projectRoot - Path to check for lock files
+ * @param {object} fsApi - fs module (for DI)
+ * @returns {string|null} Package manager command or null
+ */
+function detectPackageManager(projectRoot, fsApi) {
+  if (fsApi.existsSync(path.join(projectRoot, 'bun.lockb'))) return 'bun';
+  if (fsApi.existsSync(path.join(projectRoot, 'pnpm-lock.yaml'))) return 'pnpm';
+  if (fsApi.existsSync(path.join(projectRoot, 'yarn.lock'))) return 'yarn';
+  if (fsApi.existsSync(path.join(projectRoot, 'package-lock.json'))) return 'npm';
+  if (fsApi.existsSync(path.join(projectRoot, 'package.json'))) return 'npm';
+  return null;
+}
+
+/**
+ * Copy .beads/ directory excluding daemon.lock.
+ * @param {string} source - Source .beads path
+ * @param {string} dest - Destination .beads path
+ * @param {object} fsApi - fs module (for DI)
+ */
+function copyBeadsDir(source, dest, fsApi) {
+  fsApi.mkdirSync(dest, { recursive: true });
+  const entries = fsApi.readdirSync(source);
+  for (const entry of entries) {
+    if (entry === 'daemon.lock') continue;
+    fsApi.cpSync(path.join(source, entry), path.join(dest, entry), { recursive: true });
+  }
+}
+
+/**
+ * Stop a Dolt server running in a worktree to release file locks.
+ * Tries graceful `bd dolt stop` first, then falls back to PID-based kill
+ * from lock files. Never kills ALL Dolt processes — only the specific PID.
+ *
+ * @param {string} worktreePath - Absolute path to the worktree
+ * @param {object} [opts] - Options for dependency injection
+ * @param {Function} [opts._exec] - Override for execFileSync (testing)
+ * @param {object} [opts._fs] - Override for fs module (testing)
+ * @param {string} [opts._platform] - Override for process.platform (testing)
+ * @returns {{ stopped: boolean, method: string, pid?: number }}
+ */
+function stopDolt(worktreePath, opts = {}) {
+  const exec = opts._exec || execFileSync;
+  const _fs = opts._fs || fs;
+  const platform = opts._platform || process.platform;
+
+  // 1. Try graceful: bd dolt stop
+  try {
+    exec('bd', ['dolt', 'stop'], { cwd: worktreePath, timeout: 5000, stdio: 'pipe' });
+    return { stopped: true, method: 'bd-dolt-stop' };
+  } catch (_e) { /* intentional: bd not available, try PID-based kill */ } // NOSONAR S2486
+
+  // 2. Try PID-based kill from lock file
+  const lockPaths = [
+    path.join(worktreePath, '.beads', 'dolt-server.lock'),
+    path.join(worktreePath, '.beads', 'daemon.lock'),
+  ];
+  for (const lockPath of lockPaths) {
+    try {
+      const pid = Number.parseInt(_fs.readFileSync(lockPath, 'utf-8').trim(), 10);
+      if (!Number.isNaN(pid)) {
+        if (platform === 'win32') {
+          exec('taskkill', ['/F', '/PID', String(pid)], { stdio: 'pipe' });
+        } else {
+          process.kill(pid, 'SIGTERM');
+        }
+        return { stopped: true, method: 'pid-kill', pid };
+      }
+    } catch (_e) { /* intentional: try next lock file */ } // NOSONAR S2486
+  }
+
+  return { stopped: false, method: 'none' };
+}
+
+/**
+ * Check if a git branch already exists.
+ * @param {string} branchName - Branch name to check
+ * @param {Function} runFile - execFileSync function (for DI)
+ * @returns {boolean}
+ */
+function branchExists(branchName, runFile) {
+  try {
+    const output = runFile('git', ['branch', '--list', branchName], { stdio: 'pipe' });
+    return output.toString().trim().length > 0;
+  } catch (_err) { /* intentional: branch doesn't exist */ // NOSONAR S2486
+    return false;
+  }
+}
+
+/**
+ * Set up Beads integration for a new worktree (symlink/junction/copy).
+ * @param {string} worktreePath - Absolute path to the new worktree
+ * @param {string} projectRoot - Absolute path to the project root
+ * @param {string} platform - OS platform string (e.g. 'win32')
+ * @param {object} fsApi - fs module (for DI)
+ * @param {Function} exec - execFileSync-compatible function
+ * @returns {string|null} Warning message if beads setup had issues, null otherwise
+ */
+function setupBeads(worktreePath, projectRoot, platform, fsApi, exec) {
+  const beadsSource = path.resolve(projectRoot, '.beads');
+  const beadsDest = path.resolve(worktreePath, '.beads');
+
+  if (!fsApi.existsSync(beadsSource)) {
+    return 'Beads not installed — skipping .beads setup';
+  }
+
+  // Try symlink first
+  try {
+    if (platform === 'win32') {
+      fsApi.symlinkSync(beadsSource, beadsDest, 'junction');
+    } else {
+      fsApi.symlinkSync(beadsSource, beadsDest);
+    }
+  } catch (symlinkErr) {
+    if (symlinkErr.code === 'EPERM') {
+      copyBeadsDir(beadsSource, beadsDest, fsApi);
+    } else {
+      throw symlinkErr;
+    }
+  }
+
+  // Verify beads accessible (warn if fails, don't block)
+  try {
+    exec('bd', ['--version'], { cwd: worktreePath, timeout: 5000, stdio: 'pipe' });
+  } catch (_bdErr) { /* intentional: bd may not be on PATH */ // NOSONAR S2486
+    return 'Beads verification failed — .beads linked but bd may not work';
+  }
+
+  return null;
+}
+
+/**
+ * Run package install in the new worktree if a package manager is detected.
+ * @param {string} worktreePath - Absolute path to the new worktree
+ * @param {string} projectRoot - Absolute path to the project root
+ * @param {Function} spawnFn - spawnSync-compatible function
+ * @param {object} fsApi - fs module (for DI)
+ */
+function runInstall(worktreePath, projectRoot, spawnFn, fsApi) {
+  const pkgManager = detectPackageManager(projectRoot, fsApi);
+  if (pkgManager) {
+    spawnFn(pkgManager, ['install'], { cwd: worktreePath, stdio: 'pipe' });
+  }
+}
+
+/**
+ * Handle the "create" subcommand.
+ * @param {string} slug - Worktree slug
+ * @param {object} flags - CLI flags
+ * @param {string} projectRoot - Project root path
+ * @param {object} opts - DI options
+ * @returns {Promise<object>} Result object
+ */
+async function handleCreate(slug, flags, projectRoot, opts) {
+  const runFile = opts._exec || execFileSync;
+  const runSpawn = opts._spawn || spawnSync;
+  const fsApi = opts._fs || fs;
+  const platform = opts._platform || process.platform;
+
+  const branchName = flags['--branch'] || flags.branch || `feat/${slug}`;
+  const worktreesDir = path.resolve(projectRoot, '.worktrees');
+
+  // Guard: Detect bare repo state — worktrees created from bare repos produce broken branches
+  // git rev-parse --show-toplevel throws in a bare repo (no working tree)
+  try {
+    runFile('git', ['-C', projectRoot, 'rev-parse', '--show-toplevel'], { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] });
+  } catch (_e) { // NOSONAR S2486
+    /* intentional: show-toplevel fails in bare repos */
+    return { success: false, error: 'Main repo is in bare state (no working tree). Clone fresh instead: git clone <url> /tmp/forge-<slug>' };
+  }
+
+  // Security: Validate slug doesn't contain path traversal (OWASP A01/A03)
+  if (slug.includes('..') || slug.includes('/') || slug.includes('\\')) {
+    return { success: false, error: String.raw`Invalid slug: must not contain "..", "/", or "\"` };
+  }
+
+  const worktreePath = path.resolve(worktreesDir, slug);
+
+  // Step 0: Check if worktree already exists
+  if (fsApi.existsSync(worktreePath)) {
+    return {
+      success: true,
+      reused: true,
+      message: `Worktree already exists at ${worktreePath}`,
+      worktreePath,
+    };
+  }
+
+  // Step 1: Ensure .worktrees/ dir exists
+  fsApi.mkdirSync(worktreesDir, { recursive: true });
+
+  // Step 2: Create git worktree
+  const hasBranch = branchExists(branchName, runFile);
+  if (hasBranch) {
+    runFile('git', ['worktree', 'add', worktreePath, branchName], { stdio: 'pipe' });
+  } else {
+    runFile('git', ['worktree', 'add', worktreePath, '-b', branchName], { stdio: 'pipe' });
+  }
+
+  // Step 3: Beads integration
+  const beadsWarning = setupBeads(worktreePath, projectRoot, platform, fsApi, runFile);
+
+  // Step 4: Run package install
+  runInstall(worktreePath, projectRoot, runSpawn, fsApi);
+
+  const result = {
+    success: true,
+    worktreePath,
+    branch: branchName,
+  };
+  if (beadsWarning) {
+    result.beadsWarning = beadsWarning;
+  }
+  return result;
+}
+
+/**
+ * Handle the "remove" subcommand.
+ * @param {string} slug - Worktree slug
+ * @param {string} projectRoot - Project root path
+ * @param {object} opts - DI options
+ * @returns {Promise<object>} Result object
+ */
+async function handleRemove(slug, projectRoot, opts) {
+  // Security: Validate slug doesn't contain path traversal (OWASP A01/A03)
+  if (slug.includes('..') || slug.includes('/') || slug.includes('\\')) {
+    return { success: false, error: String.raw`Invalid slug: must not contain "..", "/", or "\"` };
+  }
+
+  const runFile = opts._exec || execFileSync;
+  const fsModule = opts._fs || fs;
+  const worktreePath = path.resolve(projectRoot, '.worktrees', slug);
+
+  // Stop Dolt server to release file locks
+  const stopResult = stopDolt(worktreePath, { _exec: runFile, _fs: fsModule, _platform: opts._platform });
+  if (stopResult.stopped) {
+    // Brief wait for file locks to release (Windows needs this)
+    await new Promise(r => setTimeout(r, 500));
+  }
+
+  runFile('git', ['worktree', 'remove', worktreePath], { stdio: 'pipe' });
+
+  return { success: true, removed: worktreePath };
+}
+
+module.exports = {
+  name: 'worktree',
+  description: 'Manage isolated worktrees with Beads integration',
+  usage: 'forge worktree <create|remove> <slug>',
+  flags: {
+    '--branch': 'Custom branch name (default: feat/<slug>)',
+  },
+  stopDolt,
+
+  /**
+   * Main handler for the worktree command.
+   * @param {string[]} args - Positional arguments: [subcommand, slug]
+   * @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 {Function} [opts._spawn] - Override for spawnSync (testing)
+   * @param {object} [opts._fs] - Override for fs module (testing)
+   * @param {string} [opts._platform] - Override for process.platform (testing)
+   * @returns {Promise<object>}
+   */
+  handler: async (args, flags, projectRoot, opts = {}) => {
+    const subcommand = args[0];
+    const slug = args[1];
+
+    if (!subcommand || !['create', 'remove'].includes(subcommand)) {
+      return {
+        success: false,
+        error: 'Missing or invalid subcommand. Usage: forge worktree <create|remove> <slug>',
+      };
+    }
+
+    if (!slug) {
+      return {
+        success: false,
+        error: 'Missing slug. Usage: forge worktree <create|remove> <slug>',
+      };
+    }
+
+    if (subcommand === 'create') {
+      return handleCreate(slug, flags, projectRoot, opts);
+    }
+
+    return handleRemove(slug, projectRoot, opts);
+  },
+};

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