forge-workflow 0.0.10 → 0.1.0-beta.3

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

@@ -1,132 +0,0 @@
-/**
- * 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';
-import { createRequire } from 'node:module';
-
-const require = createRequire(import.meta.url);
-const { createLinkStore, resolveCanonicalLink, upsertCanonicalLink } = require('../../lib/issue-sync/link-store.js');
-const { bridgeLegacyLinkHints } = require('../../lib/issue-sync/legacy-link-bridge.js');
-
-/**
- * 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);
-}
-
-/**
- * Loads a canonical link store seeded from the legacy mapping file plus any
- * optional migration hints.
- *
- * @param {string} mappingPath - Path to the legacy mapping file
- * @param {object} [legacyHints] - Additional migration hints to bridge
- * @returns {ReturnType<typeof createLinkStore>}
- */
-export function loadCanonicalLinkStore(mappingPath, legacyHints = {}) {
-  const store = createLinkStore();
-  const mapping = readMapping(mappingPath);
-  bridgeLegacyLinkHints({ ...legacyHints, mapping }, { store });
-  return store;
-}
-
-/**
- * Resolves the canonical link record for a GitHub lookup using the legacy
- * mapping file only as a bridge input.
- *
- * @param {string} mappingPath - Path to the legacy mapping file
- * @param {object} lookup - Canonical lookup values
- * @param {object} [legacyHints] - Additional migration hints to bridge
- * @returns {object|null}
- */
-export function resolveCanonicalBeadsLink(mappingPath, lookup = {}, legacyHints = {}) {
-  const store = loadCanonicalLinkStore(mappingPath, legacyHints);
-  return resolveCanonicalLink(store, lookup);
-}
-
-/**
- * Upserts a canonical link and mirrors it into the legacy mapping file for
- * compatibility during migration.
- *
- * @param {string} mappingPath - Path to the legacy mapping file
- * @param {object} link - Canonical link record
- * @param {object} [legacyHints] - Additional migration hints to bridge
- * @returns {object}
- */
-export function upsertCanonicalBeadsLink(mappingPath, link, legacyHints = {}) {
-  const store = loadCanonicalLinkStore(mappingPath, legacyHints);
-  const canonical = upsertCanonicalLink(store, link);
-
-  if (canonical?.github?.number != null && canonical.forgeIssueId) {
-    setBeadsId(mappingPath, canonical.github.number, canonical.forgeIssueId);
-  }
-
-  return canonical;
-}

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

@@ -1,31 +0,0 @@
-#!/usr/bin/env node
-/**
- * CLI entry point for Beads → GitHub reverse sync.
- * Usage: node reverse-sync-cli.mjs <old-snapshot-jsonl-path> <new-snapshot-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-snapshot-jsonl-path> <new-snapshot-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

@@ -1,162 +0,0 @@
-/**
- * Reverse sync: Beads → GitHub.
- * When a Beads issue is closed (via git push updating exported issue snapshots),
- * 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;
-}
-
-function extractCanonicalGitHubLink(issue = {}) {
-  const github = issue.github ?? {};
-  if (typeof github.url === 'string' && github.url.length > 0) {
-    const match = github.url.match(
-      /https:\/\/github\.com\/([^/]+)\/([^/]+)\/issues\/(\d+)/,
-    );
-    if (match) {
-      return {
-        owner: match[1],
-        repo: match[2],
-        issueNumber: parseInt(match[3], 10),
-      };
-    }
-  }
-  return null;
-}
-
-function extractPreferredGitHubLink(issue = {}) {
-  return extractCanonicalGitHubLink(issue) ?? extractGitHubUrl(issue.description);
-}
-
-/**
- * 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 a previous exported issue snapshot
- * @param {string[]} newLines - JSONL lines from a current exported issue snapshot
- * @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 exported issue snapshot JSONL
- * and closes the linked GitHub issues.
- *
- * @param {string} oldContent - Previous exported issue snapshot content
- * @param {string} newContent - Current exported issue snapshot 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 latestIssues = new Map(
-    parseJsonlLines(newLines).map((issue) => [issue.id, issue]),
-  );
-
-  const closed = [];
-  const skipped = [];
-  const errors = [];
-
-  for (const issue of transitions) {
-    const parsed = extractPreferredGitHubLink(latestIssues.get(issue.id) ?? issue);
-    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

@@ -1,161 +0,0 @@
-/**
- * @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) {
-  // Match forge-xxx with optional dotted sub-IDs (e.g. forge-m1n8.6, forge-dq8j.1).
-  // \w in JS doesn't include '.', so the dotted sub-ID group is explicit.
-  const match = stdout.match(/Created issue:\s+(forge-[a-zA-Z0-9]+(?:\.[a-zA-Z0-9]+)*)/);
-  if (match) return match[1];
-  // Fallback: loose match for any forge-prefixed ID anywhere in output
-  const fallback = stdout.match(/(forge-[a-zA-Z0-9]+(?:\.[a-zA-Z0-9]+)*)/);
-  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

@@ -1,121 +0,0 @@
-/**
- * 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

@@ -1,26 +0,0 @@
-{
-  "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"]
-}