forge-workflow 0.0.8 → 0.0.10

package/lib/dep-guard/keyword-ripple.js

@@ -0,0 +1,184 @@
+'use strict';
+
+const STOP_WORDS = new Set([
+	'the',
+	'a',
+	'an',
+	'and',
+	'or',
+	'is',
+	'in',
+	'to',
+	'for',
+	'of',
+	'with',
+	'on',
+	'at',
+	'by',
+	'from',
+	'add',
+	'fix',
+	'update',
+	'implement',
+	'create',
+	'remove',
+	'delete',
+	'make',
+	'use',
+	'get',
+	'set',
+	'run',
+	'test',
+	'check',
+	'all',
+	'this',
+	'that',
+	'it',
+	'be',
+	'as',
+	'not',
+	'no',
+	'but',
+	'if',
+	'do',
+	'we',
+	'they',
+	'are',
+	'was',
+	'were',
+	'been',
+	'have',
+	'has',
+	'had',
+	'will',
+	'would',
+	'could',
+	'should',
+	'may',
+	'can',
+	'each',
+	'every',
+	'both',
+	'also',
+	'into',
+	'than',
+	'then',
+	'when',
+	'where',
+	'which',
+	'what',
+	'how',
+	'why',
+	'who',
+	'its',
+	'new',
+	'first',
+	'last',
+	'same',
+	'other',
+]);
+
+function tokenizeMeaningfulTerms(title) {
+	return [...new Set(
+		String(title ?? '')
+			.toLowerCase()
+			.split(/[^a-z]+/u)
+			.filter((term) => term.length >= 3)
+			.filter((term) => !STOP_WORDS.has(term)),
+	)].sort((left, right) => left.localeCompare(right));
+}
+
+function collectSharedTerms(sourceTerms, candidateTerms) {
+	const candidateSet = new Set(candidateTerms);
+	return sourceTerms.filter((term) => candidateSet.has(term));
+}
+
+function isInProgressLine(line) {
+	return line.includes('◐') || line.includes('◐');
+}
+
+function parseActiveIssueLines(listOutput) {
+	return String(listOutput ?? '')
+		.split(/\r?\n/u)
+		.map((line) => line.trim())
+		.filter(Boolean)
+		.map((line) => {
+			const idMatch = /forge-[a-zA-Z0-9]+(?:\.[a-zA-Z0-9]+)*/u.exec(line);
+			if (!idMatch) {
+				return null;
+			}
+
+			const titleIndex = line.indexOf(' - ');
+			const priorityMatch = /P\d+/u.exec(line);
+			return {
+				id: idMatch[0],
+				priority: priorityMatch ? priorityMatch[0] : 'P2',
+				status: isInProgressLine(line) ? 'in_progress' : 'open',
+				title: titleIndex >= 0 ? line.slice(titleIndex + 3).trim() : '',
+			};
+		})
+		.filter(Boolean);
+}
+
+function renderKeywordRippleReport({ issueId, sourceTitle, activeIssues }) {
+	const sourceTerms = tokenizeMeaningfulTerms(sourceTitle);
+	const overlaps = [];
+
+	for (const candidate of activeIssues ?? []) {
+		if (!candidate || candidate.id === issueId) {
+			continue;
+		}
+
+		const sharedTerms = collectSharedTerms(sourceTerms, tokenizeMeaningfulTerms(candidate.title));
+		if (sharedTerms.length < 2) {
+			continue;
+		}
+
+		overlaps.push({
+			id: candidate.id,
+			priority: candidate.priority || 'P2',
+			status: candidate.status || 'open',
+			title: candidate.title || '',
+			sharedTerms,
+		});
+	}
+
+	if (overlaps.length === 0) {
+		return {
+			overlapCount: 0,
+			overlaps,
+			output: 'No conflicts detected',
+		};
+	}
+
+	const lines = [`Potential overlap with ${overlaps.length} issue(s):`, ''];
+	for (const overlap of overlaps) {
+		const renderedSharedTerms = overlap.sharedTerms.map((term) => `"${term}"`).join(', ');
+		lines.push(
+			`  ${overlap.id} (${overlap.status}, ${overlap.priority}): "${overlap.title}"`,
+			`  Overlap: keyword match - ${renderedSharedTerms}`,
+			'  Confidence: LOW (keyword only, no contract data)',
+			'',
+			'  Options:',
+			`  (a) Add dependency: bd dep add ${issueId} ${overlap.id}`,
+			'  (b) Proceed - no real conflict',
+			`  (c) Investigate: bd show ${overlap.id}`,
+			'',
+		);
+	}
+
+	return {
+		overlapCount: overlaps.length,
+		overlaps,
+		output: lines.join('\n').trimEnd(),
+	};
+}
+
+module.exports = {
+	STOP_WORDS,
+	collectSharedTerms,
+	isInProgressLine,
+	parseActiveIssueLines,
+	renderKeywordRippleReport,
+	tokenizeMeaningfulTerms,
+};

package/lib/detect-worktree.js

@@ -8,7 +8,7 @@ const path = require('path');
  * 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 }}
+ * @returns {{ inWorktree: boolean, branch?: string, mainWorktree?: string, currentWorktree?: string }}
  */
 function detectWorktree(cwd = process.cwd()) {
   try {
@@ -24,20 +24,19 @@ function detectWorktree(cwd = process.cwd()) {
     const absGitDir = path.resolve(cwd, gitDir);
     const absCommonDir = path.resolve(cwd, gitCommonDir);
 
+    const branch = execFileSync('git', ['branch', '--show-current'], {
+      encoding: 'utf8', cwd, stdio: ['pipe', 'pipe', 'pipe']
+    }).trim();
+    const mainWorktree = path.resolve(absCommonDir, '..');
+    const currentWorktree = path.resolve(cwd);
+
     // 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: true, branch, mainWorktree, currentWorktree };
     }
 
-    return { inWorktree: false };
+    return { inWorktree: false, branch, mainWorktree, currentWorktree };
   } catch (_err) {
     // Not in a git repo or git not available
     return { inWorktree: false };

package/lib/forge-issues.js

@@ -0,0 +1,326 @@
+'use strict';
+
+const { spawn } = require('node:child_process');
+const { existsSync } = require('node:fs');
+const path = require('node:path');
+const { isBeadsInitialized } = require('./beads-setup');
+const { createGitHubProjectionPlan } = require('./issue-sync/project-github');
+
+const OPERATION_TO_BD = {
+  create: 'create',
+  list: 'list',
+  show: 'show',
+  close: 'close',
+  update: 'update',
+};
+
+function getSpawnOptions(projectRoot) {
+  return {
+    cwd: projectRoot,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  };
+}
+
+function getPathEntries(env = process.env, delimiter = path.delimiter) {
+  const rawPath = env.PATH || env.Path || '';
+  return rawPath
+    .split(delimiter)
+    .map(entry => entry.trim().replace(/^"(.*)"$/, '$1'))
+    .filter(Boolean);
+}
+
+function resolveWindowsCommandCandidates(commandNames, deps = {}) {
+  const env = deps.env || process.env;
+  const fileExists = deps.existsSync || existsSync;
+  const resolved = [];
+  const seen = new Set();
+  const pathEntries = getPathEntries(env, ';');
+
+  for (const dir of pathEntries) {
+    for (const commandName of commandNames) {
+      const fullPath = isWindowsPathEntry(dir)
+        ? path.win32.join(dir, commandName)
+        : path.posix.join(dir, commandName);
+      const dedupeKey = fullPath.toLowerCase();
+      if (!seen.has(dedupeKey) && fileExists(fullPath)) {
+        seen.add(dedupeKey);
+        resolved.push(fullPath);
+      }
+    }
+  }
+
+  return resolved;
+}
+
+function isWindowsPathEntry(entry = '') {
+  return /^(?:[a-zA-Z]:[\\/]|\\\\)/.test(entry) || entry.includes('\\');
+}
+
+function getBdCommandCandidates(deps = {}) {
+  const platform = deps.platform || process.platform;
+  if (platform === 'win32') {
+    const resolved = resolveWindowsCommandCandidates(['bd.exe', 'bd.cmd'], deps);
+    return [...new Set([...resolved, 'bd.exe', 'bd'])];
+  }
+
+  return ['bd'];
+}
+
+function normalizeExecOutput(output) {
+  if (typeof output === 'string') {
+    return output;
+  }
+
+  if (Buffer.isBuffer(output)) {
+    return output.toString('utf8');
+  }
+
+  return '';
+}
+
+function hasBdSoftFailure(output) {
+  return /(^|\n)Error(?: resolving| updating| fetching| adding)?\b/i.test(output);
+}
+
+function hasEmptyShowPayload(operation, output) {
+  if (operation !== 'show') {
+    return false;
+  }
+
+  const trimmedOutput = output.trim();
+  return trimmedOutput === '' || trimmedOutput === '[]' || trimmedOutput === 'null';
+}
+
+function isHelpInvocation(args = []) {
+  return args.includes('--help') || args.includes('-h');
+}
+
+function extractErrorMessage(error) {
+  if (error?.code === 'ENOENT') {
+    return 'Beads (bd) command not found. Install or initialize Beads before using forge issues.';
+  }
+
+  return error?.message?.trim() || 'Beads command failed';
+}
+
+function getCommandErrorMessage(result) {
+  const output = [result?.stdout, result?.stderr].filter(Boolean).join('\n').trim();
+  if (output) {
+    return output;
+  }
+
+  if (typeof result?.code === 'number') {
+    return `Beads command failed with exit code ${result.code}`;
+  }
+
+  return 'Beads command failed';
+}
+
+function buildBdArgs(operation, args) {
+  const bdCommand = OPERATION_TO_BD[operation];
+  if (!bdCommand) {
+    return null;
+  }
+
+  return [bdCommand, ...args];
+}
+
+function shouldCaptureOutput(operation, args, deps = {}) {
+  if (deps.captureOutput === true) {
+    return true;
+  }
+
+  if (isHelpInvocation(args)) {
+    return true;
+  }
+
+  return operation === 'update' || operation === 'show';
+}
+
+async function runBdCommand(operation, args, projectRoot, deps = {}) {
+  const spawnBd = deps.spawn || spawn;
+  const stdoutTarget = deps.stdout || process.stdout;
+  const stderrTarget = deps.stderr || process.stderr;
+  const captureOutput = shouldCaptureOutput(operation, args.slice(1), deps);
+  const commandCandidates = deps.commandCandidates || getBdCommandCandidates(deps);
+  let lastError;
+
+  for (const command of commandCandidates) {
+    try {
+      return await new Promise((resolve, reject) => {
+        const child = spawnBd(command, args, getSpawnOptions(projectRoot));
+        let stdout = '';
+        let stderr = '';
+
+        child.stdout?.setEncoding?.('utf8');
+        child.stderr?.setEncoding?.('utf8');
+        child.stdout?.on?.('data', chunk => {
+          const normalizedChunk = normalizeExecOutput(chunk);
+          if (captureOutput) {
+            stdout += normalizedChunk;
+          } else {
+            stdoutTarget?.write?.(normalizedChunk);
+          }
+        });
+        child.stderr?.on?.('data', chunk => {
+          const normalizedChunk = normalizeExecOutput(chunk);
+          if (captureOutput) {
+            stderr += normalizedChunk;
+          }
+          stderrTarget?.write?.(normalizedChunk);
+        });
+
+        child.on('error', reject);
+        child.on('close', code => {
+          resolve({
+            code,
+            stdout,
+            stderr,
+          });
+        });
+      });
+    } catch (error) {
+      lastError = error;
+      // ENOENT/EINVAL means this candidate is not directly spawnable — try next.
+      if (error?.code !== 'ENOENT' && error?.code !== 'EINVAL') {
+        throw error;
+      }
+    }
+  }
+
+  throw lastError;
+}
+
+async function runBeadsOperation(operation, args, context, deps) {
+  const checkInit = deps.isBeadsInitialized || isBeadsInitialized;
+  if (!isHelpInvocation(args) && !checkInit(context.projectRoot)) {
+    return {
+      success: false,
+      error: 'Beads is not initialized in this project. Run forge setup before using forge issues.',
+    };
+  }
+  const runCommand = deps.runBdCommand || ((bdArgs, projectRoot) => runBdCommand(operation, bdArgs, projectRoot, deps));
+
+  try {
+    const result = await runCommand(buildBdArgs(operation, args), context.projectRoot);
+    const stdout = normalizeExecOutput(result?.stdout);
+    const stderr = normalizeExecOutput(result?.stderr);
+    const combinedOutput = [stdout, stderr].filter(Boolean).join('\n');
+
+    if (result?.code !== 0) {
+      return {
+        success: false,
+        error: getCommandErrorMessage(result),
+      };
+    }
+
+    if (hasBdSoftFailure(combinedOutput)) {
+      return {
+        success: false,
+        error: combinedOutput.trim() || 'Beads command failed',
+      };
+    }
+
+    if (hasEmptyShowPayload(operation, combinedOutput)) {
+      return {
+        success: false,
+        error: `Issue not found: ${args[0] || 'unknown issue'}`,
+      };
+    }
+
+    return {
+      success: true,
+      operation,
+      output: stdout,
+      stderr,
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: extractErrorMessage(error),
+    };
+  }
+}
+
+function createBeadsIssueBackend(deps = {}) {
+  return {
+    create: async (args, context) => runBeadsOperation('create', args, context, deps),
+    list: async (args, context) => runBeadsOperation('list', args, context, deps),
+    show: async (args, context) => runBeadsOperation('show', args, context, deps),
+    close: async (args, context) => runBeadsOperation('close', args, context, deps),
+    update: async (args, context) => runBeadsOperation('update', args, context, deps),
+  };
+}
+
+function createIssueService({ backend } = {}) {
+  const resolvedBackend = backend || createBeadsIssueBackend();
+
+  return {
+    async run(operation, args = [], context = {}) {
+      const method = resolvedBackend?.[operation];
+      if (typeof method !== 'function') {
+        return {
+          success: false,
+          error: `Unsupported issue operation: ${operation}`,
+        };
+      }
+
+      return method.call(resolvedBackend, args, context);
+    },
+  };
+}
+
+async function runIssueOperation(operation, rawArgs, projectRoot, deps = {}) {
+  const createService = deps.createService || (() => {
+    const backendDeps = {
+      isBeadsInitialized: deps.isBeadsInitialized,
+      runBdCommand: deps.runBdCommand,
+      spawn: deps.spawn,
+      platform: deps.platform,
+      env: deps.env,
+    };
+
+    return createIssueService({
+      backend: createBeadsIssueBackend(backendDeps),
+    });
+  });
+
+  const service = createService();
+  const result = await service.run(operation, rawArgs, {
+    projectRoot,
+    deps,
+  });
+
+  const queueGitHubProjection = deps.enqueueGitHubProjection || deps.queueGitHubProjection;
+  if (result?.success && typeof queueGitHubProjection === 'function') {
+    const projectionPlan = createGitHubProjectionPlan(operation, rawArgs);
+    if (projectionPlan) {
+      await queueGitHubProjection(projectionPlan, {
+        operation,
+        args: rawArgs,
+        projectRoot,
+        result,
+      });
+    }
+  }
+
+  return result;
+}
+
+module.exports = {
+  createIssueService,
+  createBeadsIssueBackend,
+  runIssueOperation,
+  buildBdArgs,
+  extractErrorMessage,
+  getCommandErrorMessage,
+  getSpawnOptions,
+  hasEmptyShowPayload,
+  hasBdSoftFailure,
+  isHelpInvocation,
+  normalizeExecOutput,
+  runBdCommand,
+  getBdCommandCandidates,
+  getPathEntries,
+  resolveWindowsCommandCandidates,
+};

package/lib/issue-sync/authority.js

@@ -0,0 +1,100 @@
+const GITHUB_OWNED_FIELDS = new Set([
+  'github.number',
+  'github.nodeId',
+  'github.url',
+  'shared.title',
+  'shared.body',
+  'shared.state',
+  'shared.assignees',
+  'shared.labels',
+  'shared.milestone',
+  'sync.remoteUpdatedAt',
+]);
+
+const FORGE_OWNED_FIELDS = new Set([
+  'forge.issueId',
+  'forge.dependencies',
+  'forge.parentId',
+  'forge.childIds',
+  'forge.workflowStage',
+  'forge.acceptanceCriteria',
+  'forge.progressNotes',
+  'forge.stageTransitions',
+  'forge.decisions',
+  'forge.memory',
+  'sync.lastPulledAt',
+  'sync.lastPushedAt',
+  'sync.pendingOutbound',
+  'sync.drift',
+]);
+
+const CACHE_FIELDS = new Set([
+  'cache.githubSnapshot',
+  'cache.materializedIssue',
+  'cache.legacyLinkHints.mapping',
+  'cache.legacyLinkHints.githubIssue',
+  'cache.legacyLinkHints.syncComments',
+  'cache.legacyLinkHints.externalRef',
+  'cache.legacyLinkHints.descriptionUrl',
+]);
+
+function matchesFieldPath(fieldPath, knownFieldPath) {
+  return fieldPath === knownFieldPath || fieldPath.startsWith(`${knownFieldPath}.`);
+}
+
+function hasFieldPath(fieldPath, fieldSet) {
+  if (typeof fieldPath !== 'string' || fieldPath.length === 0) {
+    return false;
+  }
+
+  for (const knownFieldPath of fieldSet) {
+    if (matchesFieldPath(fieldPath, knownFieldPath)) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+function getFieldAuthority(fieldPath) {
+  if (hasFieldPath(fieldPath, GITHUB_OWNED_FIELDS)) {
+    return 'github';
+  }
+
+  if (hasFieldPath(fieldPath, FORGE_OWNED_FIELDS)) {
+    return 'forge';
+  }
+
+  if (hasFieldPath(fieldPath, CACHE_FIELDS)) {
+    return 'cache';
+  }
+
+  return null;
+}
+
+function isGitHubOwnedField(fieldPath) {
+  return getFieldAuthority(fieldPath) === 'github';
+}
+
+function isForgeOwnedField(fieldPath) {
+  return getFieldAuthority(fieldPath) === 'forge';
+}
+
+function isCacheField(fieldPath) {
+  return getFieldAuthority(fieldPath) === 'cache';
+}
+
+function isSharedField(fieldPath) {
+  return typeof fieldPath === 'string' && fieldPath.startsWith('shared.') && isGitHubOwnedField(fieldPath);
+}
+
+module.exports = {
+  CACHE_FIELDS,
+  FORGE_OWNED_FIELDS,
+  GITHUB_OWNED_FIELDS,
+  getFieldAuthority,
+  isCacheField,
+  isForgeOwnedField,
+  isGitHubOwnedField,
+  isSharedField,
+};