forge-workflow 0.0.3 → 0.0.5

package/scripts/github-beads-sync/label-mapper.mjs

@@ -0,0 +1,54 @@
+/**
+ * Maps GitHub issue labels to Beads type and priority.
+ *
+ * @param {Array<string|{name: string}>} labels - GitHub labels (strings or objects)
+ * @param {object} config - Mapping configuration
+ * @param {Record<string, string>} config.labelToType - Label name to Beads type
+ * @param {Record<string, number>} config.labelToPriority - Label name to priority number
+ * @param {string} [config.defaultType="task"] - Fallback type
+ * @param {number} [config.defaultPriority=2] - Fallback priority
+ * @returns {{ type: string, priority: number }}
+ */
+export function mapLabels(labels, config) {
+  const {
+    defaultType = 'task',
+    defaultPriority = 2,
+  } = config;
+  const labelToType = (config.labelToType && typeof config.labelToType === 'object' && !Array.isArray(config.labelToType)) ? config.labelToType : {};
+  const labelToPriority = (config.labelToPriority && typeof config.labelToPriority === 'object' && !Array.isArray(config.labelToPriority)) ? config.labelToPriority : {};
+
+  // Normalize labels to lowercase strings
+  const names = labels.map((l) =>
+    (typeof l === 'string' ? l : l.name).toLowerCase()
+  );
+
+  // Build lowercase lookup maps
+  const typeLookup = Object.create(null);
+  for (const [key, value] of Object.entries(labelToType)) {
+    typeLookup[key.toLowerCase()] = value;
+  }
+
+  const priorityLookup = Object.create(null);
+  for (const [key, value] of Object.entries(labelToPriority)) {
+    priorityLookup[key.toLowerCase()] = value;
+  }
+
+  // First match wins
+  let type = defaultType;
+  for (const name of names) {
+    if (name in typeLookup) {
+      type = typeLookup[name];
+      break;
+    }
+  }
+
+  let priority = defaultPriority;
+  for (const name of names) {
+    if (name in priorityLookup) {
+      priority = priorityLookup[name];
+      break;
+    }
+  }
+
+  return { type, priority };
+}

package/scripts/github-beads-sync/mapping.mjs

@@ -0,0 +1,78 @@
+/**
+ * CRUD module for .github/beads-mapping.json
+ *
+ * Maps GitHub issue numbers (string keys) to Beads issue IDs.
+ * Format: { "42": "forge-abc", "7": "forge-xyz" }
+ *
+ * @module mapping
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Reads the mapping file and returns parsed JSON.
+ * Returns {} if the file does not exist.
+ * Throws with a helpful message if JSON is invalid.
+ *
+ * @param {string} mappingPath - Absolute path to the mapping JSON file
+ * @returns {Record<string, string>} The mapping object
+ */
+export function readMapping(mappingPath) {
+  if (!fs.existsSync(mappingPath)) {
+    return {};
+  }
+  const raw = fs.readFileSync(mappingPath, 'utf8');
+  try {
+    return JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`Failed to parse mapping file at ${mappingPath}: ${err.message}`, { cause: err });
+  }
+}
+
+/**
+ * Writes the mapping object to disk as JSON with 2-space indent.
+ * Atomic: writes to a temp file then renames.
+ * Creates parent directories if they do not exist.
+ *
+ * @param {string} mappingPath - Absolute path to the mapping JSON file
+ * @param {Record<string, string>} data - The mapping object to write
+ */
+export function writeMapping(mappingPath, data) {
+  const dir = path.dirname(mappingPath);
+  fs.mkdirSync(dir, { recursive: true });
+
+  const tmpPath = mappingPath + '.tmp';
+  const content = JSON.stringify(data, null, 2) + '\n';
+  fs.writeFileSync(tmpPath, content, 'utf8');
+  fs.renameSync(tmpPath, mappingPath);
+}
+
+/**
+ * Returns the Beads ID for a given GitHub issue number, or null if not found.
+ * Coerces numeric issueNumber to string for lookup.
+ *
+ * @param {string} mappingPath - Absolute path to the mapping JSON file
+ * @param {string|number} issueNumber - The GitHub issue number
+ * @returns {string|null} The Beads ID or null
+ */
+export function getBeadsId(mappingPath, issueNumber) {
+  const data = readMapping(mappingPath);
+  const key = String(issueNumber);
+  return data[key] ?? null;
+}
+
+/**
+ * Adds or updates a mapping entry. Reads existing data, merges, and writes back.
+ * Preserves all existing entries.
+ *
+ * @param {string} mappingPath - Absolute path to the mapping JSON file
+ * @param {string|number} issueNumber - The GitHub issue number
+ * @param {string} beadsId - The Beads issue ID
+ */
+export function setBeadsId(mappingPath, issueNumber, beadsId) {
+  const data = readMapping(mappingPath);
+  const key = String(issueNumber);
+  data[key] = beadsId;
+  writeMapping(mappingPath, data);
+}

package/scripts/github-beads-sync/reverse-sync-cli.mjs

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+/**
+ * CLI entry point for Beads → GitHub reverse sync.
+ * Usage: node reverse-sync-cli.mjs <old-jsonl-path> <new-jsonl-path>
+ *
+ * @module scripts/github-beads-sync/reverse-sync-cli
+ */
+
+import { readFileSync } from 'node:fs';
+import { handleBeadsClosed } from './reverse-sync.mjs';
+
+const oldPath = process.argv[2];
+const newPath = process.argv[3];
+
+if (!oldPath || !newPath) {
+  console.error('Usage: node reverse-sync-cli.mjs <old-jsonl-path> <new-jsonl-path>');
+  process.exit(1);
+}
+
+const oldContent = readFileSync(oldPath, 'utf-8');
+const newContent = readFileSync(newPath, 'utf-8');
+
+const result = handleBeadsClosed(oldContent, newContent);
+console.log(JSON.stringify(result, null, 2));
+
+if (result.errors.length > 0) {
+  console.error(`${result.errors.length} issue(s) failed to close on GitHub`);
+  process.exit(1);
+}
+
+console.log(`Closed ${result.closed.length} GitHub issue(s), skipped ${result.skipped.length}`);

package/scripts/github-beads-sync/reverse-sync.mjs

@@ -0,0 +1,138 @@
+/**
+ * Reverse sync: Beads → GitHub.
+ * When a Beads issue is closed (via git push updating .beads/),
+ * close the linked GitHub issue.
+ *
+ * @module scripts/github-beads-sync/reverse-sync
+ */
+
+import { execFileSync } from 'node:child_process';
+
+/**
+ * Parse JSONL lines into an array of objects, skipping empty/malformed lines.
+ * @param {string[]} lines - Array of JSONL strings
+ * @returns {Array<{id: string, status: string, description?: string}>}
+ */
+function parseJsonlLines(lines) {
+  const results = [];
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      const obj = JSON.parse(trimmed);
+      if (obj && obj.id) results.push(obj);
+    } catch (_err) {
+      // Skip malformed lines
+    }
+  }
+  return results;
+}
+
+/**
+ * Detect Beads issues that transitioned to "closed" status.
+ * Only detects transitions: issue must exist in oldLines as non-closed,
+ * and appear in newLines as "closed".
+ *
+ * @param {string[]} oldLines - JSONL lines from previous .beads/issues.jsonl
+ * @param {string[]} newLines - JSONL lines from current .beads/issues.jsonl
+ * @returns {Array<{id: string, description: string}>} Issues that transitioned to closed
+ */
+export function detectClosedIssues(oldLines, newLines) {
+  const oldMap = new Map();
+  for (const issue of parseJsonlLines(oldLines)) {
+    oldMap.set(issue.id, issue.status);
+  }
+
+  const closed = [];
+  for (const issue of parseJsonlLines(newLines)) {
+    if (issue.status !== 'closed') continue;
+    const oldStatus = oldMap.get(issue.id);
+    // Must have existed before and not been closed already
+    if (oldStatus == null || oldStatus === 'closed') continue;
+    closed.push({ id: issue.id, description: issue.description || '' });
+  }
+  return closed;
+}
+
+/**
+ * Extract GitHub owner, repo, and issue number from a description string
+ * containing a GitHub issue URL.
+ *
+ * @param {string|null|undefined} description - Text that may contain a GitHub issue URL
+ * @returns {{owner: string, repo: string, issueNumber: number}|null}
+ */
+export function extractGitHubUrl(description) {
+  if (!description) return null;
+  const match = description.match(
+    /https:\/\/github\.com\/([^/]+)\/([^/]+)\/issues\/(\d+)/,
+  );
+  if (!match) return null;
+  return {
+    owner: match[1],
+    repo: match[2],
+    issueNumber: parseInt(match[3], 10),
+  };
+}
+
+/**
+ * Close a GitHub issue using the `gh api` CLI.
+ * Uses execFileSync with array args (no shell).
+ *
+ * @param {string} owner - Repository owner
+ * @param {string} repo - Repository name
+ * @param {number|string} issueNumber - Issue number
+ */
+export function closeGitHubIssue(owner, repo, issueNumber) {
+  execFileSync('gh', [
+    'api',
+    `repos/${owner}/${repo}/issues/${issueNumber}`,
+    '-X', 'PATCH',
+    '-f', 'state=closed',
+  ], { encoding: 'utf-8' });
+}
+
+/**
+ * Handle Beads-to-GitHub reverse sync.
+ * Detects issues that transitioned to closed in .beads/issues.jsonl
+ * and closes the linked GitHub issues.
+ *
+ * @param {string} oldContent - Previous .beads/issues.jsonl content
+ * @param {string} newContent - Current .beads/issues.jsonl content
+ * @param {object} [deps] - Dependency injection
+ * @param {Function} [deps.closeGitHubIssue] - Override for testing
+ * @returns {{closed: Array, skipped: Array, errors: Array}}
+ */
+export function handleBeadsClosed(oldContent, newContent, deps = {}) {
+  const closeFn = deps.closeGitHubIssue ?? closeGitHubIssue;
+
+  const oldLines = oldContent.split('\n');
+  const newLines = newContent.split('\n');
+
+  const transitions = detectClosedIssues(oldLines, newLines);
+
+  const closed = [];
+  const skipped = [];
+  const errors = [];
+
+  for (const issue of transitions) {
+    const parsed = extractGitHubUrl(issue.description);
+    if (!parsed) {
+      skipped.push({ beadsId: issue.id, reason: 'no GitHub URL' });
+      continue;
+    }
+
+    try {
+      closeFn(parsed.owner, parsed.repo, parsed.issueNumber);
+      closed.push({
+        beadsId: issue.id,
+        owner: parsed.owner,
+        repo: parsed.repo,
+        issueNumber: parsed.issueNumber,
+      });
+    } catch (err) {
+      errors.push({ beadsId: issue.id, error: err.message });
+    }
+  }
+
+  return { closed, skipped, errors };
+}

package/scripts/github-beads-sync/run-bd.mjs

@@ -0,0 +1,159 @@
+/**
+ * @module run-bd
+ * @description Wrapper around the `bd` (Beads) CLI for GitHub-Beads sync.
+ *
+ * Exports pure arg-building and output-parsing functions (unit-testable),
+ * plus thin exec wrappers that shell out to the real `bd` binary.
+ */
+
+import { execFileSync } from 'node:child_process';
+
+const EXEC_OPTS = { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] };
+
+// ---------------------------------------------------------------------------
+// Arg builders (pure)
+// ---------------------------------------------------------------------------
+
+/**
+ * Build args array for `bd create`.
+ * Omits flags whose values are null or undefined.
+ * @param {object} opts
+ * @param {string} opts.title
+ * @param {string} [opts.type]
+ * @param {number|string} [opts.priority]
+ * @param {string} [opts.assignee]
+ * @param {string} [opts.description]
+ * @param {string} [opts.externalRef]
+ * @returns {string[]}
+ */
+export function buildCreateArgs({ title, type, priority, assignee, description, externalRef } = {}) {
+  const args = ['create', '--title', title];
+
+  if (type != null) args.push('--type', type);
+  if (priority != null) args.push('--priority', String(priority));
+  if (assignee != null) args.push('--assignee', assignee);
+  if (description != null) args.push('--description', description);
+  if (externalRef != null) args.push('--external-ref', externalRef);
+
+  return args;
+}
+
+/**
+ * Build args array for `bd close`.
+ * @param {string} beadsId
+ * @param {string} [reason]
+ * @returns {string[]}
+ */
+export function buildCloseArgs(beadsId, reason) {
+  const args = ['close', beadsId];
+  if (reason != null) args.push('--reason', reason);
+  return args;
+}
+
+/**
+ * Build args array for `bd show`.
+ * @param {string} beadsId
+ * @returns {string[]}
+ */
+export function buildShowArgs(beadsId) {
+  return ['show', beadsId, '--json'];
+}
+
+/**
+ * Build args array for `bd search`.
+ * @param {string} query
+ * @returns {string[]}
+ */
+export function buildSearchArgs(query) {
+  return ['search', query];
+}
+
+// ---------------------------------------------------------------------------
+// Output parsers (pure)
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract beads ID from `bd create` stdout.
+ * Expects pattern: "Created issue: forge-xxxx"
+ * @param {string} stdout
+ * @returns {string|null}
+ */
+export function parseCreateOutput(stdout) {
+  const match = stdout.match(/Created issue:\s+(forge-[\w-]+)/);
+  if (match) return match[1];
+  // Fallback: loose match for any forge-prefixed ID anywhere in output
+  const fallback = stdout.match(/(forge-[a-z0-9]+)/i);
+  return fallback ? fallback[1] : null;
+}
+
+/**
+ * Extract status from `bd show --json` stdout.
+ * Parses JSON output for reliable status extraction.
+ * @param {string} stdout - JSON output from `bd show --json`
+ * @returns {string|null} Lowercase status or null
+ */
+export function parseShowOutput(stdout) {
+  try {
+    const data = JSON.parse(stdout);
+    const issue = Array.isArray(data) ? data[0] : data;
+    return issue?.status ? issue.status.toLowerCase() : null;
+  } catch (_err) {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Exec wrappers (side-effectful — not unit-tested)
+// ---------------------------------------------------------------------------
+
+/**
+ * Run `bd create` and return the parsed beads ID.
+ * @param {object} opts - Same as buildCreateArgs
+ * @returns {string|null} The created beads ID, or null if parsing failed
+ */
+export function bdCreate(opts) {
+  try {
+    const stdout = execFileSync('bd', buildCreateArgs(opts), EXEC_OPTS);
+    const id = parseCreateOutput(stdout);
+    if (!id) {
+      console.error('bd create succeeded but ID not parsed. stdout:', stdout);
+    }
+    return id;
+  } catch (err) {
+    console.error('bd create failed:', err.stderr?.toString() || err.message);
+    return null;
+  }
+}
+
+/**
+ * Run `bd close`.
+ * @param {string} beadsId
+ * @param {string} [reason]
+ */
+export function bdClose(beadsId, reason) {
+  execFileSync('bd', buildCloseArgs(beadsId, reason), EXEC_OPTS);
+}
+
+/**
+ * Run `bd show` and return the parsed status.
+ * Returns null if bd exits non-zero (e.g., deleted issue, corrupted .beads/).
+ * @param {string} beadsId
+ * @returns {string|null} Lowercase status or null
+ */
+export function bdShow(beadsId) {
+  try {
+    const stdout = execFileSync('bd', buildShowArgs(beadsId), EXEC_OPTS);
+    return parseShowOutput(stdout);
+  } catch (_err) {
+    return null;
+  }
+}
+
+/**
+ * Run `bd search` and return raw stdout.
+ * @param {string} query
+ * @returns {string}
+ */
+export function bdSearch(query) {
+  return execFileSync('bd', buildSearchArgs(query), EXEC_OPTS);
+}

package/scripts/github-beads-sync/sanitize.mjs

@@ -0,0 +1,121 @@
+/**
+ * Input sanitizer for GitHub issue data before passing to bd CLI.
+ * Strips shell metacharacters, GitHub Actions interpolation, and control chars.
+ * @module sanitize
+ */
+
+/** Shell metacharacters to strip from titles and bodies */
+const SHELL_META_RE = /[;|&$`()<>\r\n]/g;
+
+/** GitHub Actions interpolation pattern: ${{ ... }} */
+const INTERPOLATION_RE = /\$\{\{[^}]*\}\}/g;
+
+/** Control characters (C0 range, excluding normal whitespace) */
+// eslint-disable-next-line no-control-regex
+const CONTROL_CHARS_RE = /[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g;
+
+/** Label: only allow alphanumeric, dot, underscore, hyphen */
+const LABEL_INVALID_RE = /[^a-zA-Z0-9._-]/g;
+
+/**
+ * Sanitize a general text field (shared logic for title/body).
+ * @param {string} input - Raw input string
+ * @param {number} maxLen - Maximum allowed length
+ * @param {string} fieldName - Name for warning messages
+ * @returns {{ sanitized: string, warnings: string[] }}
+ */
+function sanitizeText(input, maxLen, fieldName) {
+  const warnings = [];
+  let text = String(input ?? '');
+
+  // Strip GitHub Actions interpolation patterns
+  // Use local regex to avoid stateful /g lastIndex bug with .test()
+  const interpolationReLocal = /\$\{\{[^}]*\}\}/g;
+  if (interpolationReLocal.test(text)) {
+    warnings.push(`${fieldName}: stripped GitHub Actions interpolation pattern(s)`);
+  }
+  text = text.replace(INTERPOLATION_RE, '');
+
+  // Strip shell metacharacters
+  const metaMatches = text.match(SHELL_META_RE);
+  if (metaMatches) {
+    const unique = [...new Set(metaMatches)];
+    warnings.push(`${fieldName}: stripped shell metacharacters: ${unique.join(' ')}`);
+  }
+  text = text.replace(SHELL_META_RE, '');
+
+  // Strip control characters
+  // eslint-disable-next-line no-control-regex
+  const controlCharsReLocal = /[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g;
+  if (controlCharsReLocal.test(text)) {
+    warnings.push(`${fieldName}: stripped control characters`);
+  }
+  text = text.replace(CONTROL_CHARS_RE, '');
+
+  // Trim whitespace
+  text = text.trim();
+
+  // Truncate
+  if (text.length > maxLen) {
+    warnings.push(`${fieldName}: truncated from ${text.length} to ${maxLen} chars`);
+    text = text.slice(0, maxLen);
+  }
+
+  // Empty check
+  if (text.length === 0) {
+    warnings.push(`${fieldName}: empty after sanitization`);
+    text = '(empty)';
+  }
+
+  return { sanitized: text, warnings };
+}
+
+/**
+ * Sanitize an issue title for bd CLI args.
+ * @param {string} title - Raw GitHub issue title
+ * @returns {{ sanitized: string, warnings: string[] }}
+ */
+export function sanitizeTitle(title) {
+  return sanitizeText(title, 256, 'title');
+}
+
+/**
+ * Sanitize an issue body for the description field.
+ * @param {string} body - Raw GitHub issue body
+ * @returns {{ sanitized: string, warnings: string[] }}
+ */
+export function sanitizeBody(body) {
+  return sanitizeText(body, 1024, 'body');
+}
+
+/**
+ * Sanitize a single label string.
+ * Only allows [a-zA-Z0-9._-], max 64 chars.
+ * @param {string} label - Raw GitHub label name
+ * @returns {{ sanitized: string, warnings: string[] }}
+ */
+export function sanitizeLabel(label) {
+  const warnings = [];
+  let text = String(label ?? '').trim();
+
+  // Strip invalid characters
+  const invalidMatches = text.match(LABEL_INVALID_RE);
+  if (invalidMatches) {
+    warnings.push(`label: stripped invalid characters: ${[...new Set(invalidMatches)].join(' ')}`);
+    text = text.replace(LABEL_INVALID_RE, '');
+  }
+
+  // Truncate
+  if (text.length > 64) {
+    warnings.push(`label: truncated from ${text.length} to 64 chars`);
+    text = text.slice(0, 64);
+  }
+
+  // Empty check
+  if (text.length === 0) {
+    warnings.push('label: empty after sanitization');
+    text = '(empty)';
+  }
+
+  return { sanitized: text, warnings };
+}

package/scripts/github-beads-sync.config.json

@@ -0,0 +1,26 @@
+{
+  "labelToType": {
+    "bug": "bug",
+    "enhancement": "feature",
+    "documentation": "task",
+    "question": "task"
+  },
+  "labelToPriority": {
+    "P0": 0,
+    "critical": 0,
+    "P1": 1,
+    "high": 1,
+    "P2": 2,
+    "medium": 2,
+    "P3": 3,
+    "low": 3,
+    "P4": 4,
+    "backlog": 4
+  },
+  "defaultType": "task",
+  "defaultPriority": 2,
+  "mapAssignee": true,
+  "publicRepoGate": "none",
+  "gateLabelName": "beads-track",
+  "gateAssociations": ["MEMBER", "COLLABORATOR", "OWNER"]
+}