forge-workflow 0.0.4 → 0.0.5

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

@@ -0,0 +1,64 @@
+/**
+ * Bot comment parser/builder for GitHub-Beads sync.
+ *
+ * Produces and parses Vercel-inspired sync comments that use an
+ * edit-don't-create pattern with a stable HTML comment tag.
+ *
+ * @module comment
+ */
+
+/** HTML comment prefix used to identify sync comments. */
+export const SYNC_TAG_PREFIX = '<!-- beads-sync:';
+
+/**
+ * Build a markdown sync comment for a GitHub issue.
+ *
+ * @param {string} beadsId   - The Beads issue ID (e.g. "forge-abc").
+ * @param {number} issueNumber - The GitHub issue number.
+ * @param {object} [metadata]  - Optional metadata fields.
+ * @param {string} [metadata.type]        - Issue type (feature, bug, etc.).
+ * @param {string} [metadata.priority]    - Priority label (P0-P4).
+ * @param {string} [metadata.externalRef] - External reference string.
+ * @returns {string} Markdown comment body.
+ */
+export function buildComment(beadsId, issueNumber, metadata = {}) {
+  const timestamp = new Date().toISOString();
+
+  const detailLines = [];
+  if (metadata.type) detailLines.push(`- Type: ${metadata.type}`);
+  if (metadata.priority != null) detailLines.push(`- Priority: ${metadata.priority}`);
+  if (metadata.externalRef) detailLines.push(`- External ref: ${metadata.externalRef}`);
+  detailLines.push(`- Synced: ${timestamp}`);
+
+  return [
+    `${SYNC_TAG_PREFIX}${issueNumber} -->`,
+    `**Beads:** \`${beadsId}\``,
+    '<details>',
+    '<summary>Sync details</summary>',
+    '',
+    ...detailLines,
+    '</details>',
+  ].join('\n');
+}
+
+/**
+ * Parse a comment body and extract sync metadata.
+ *
+ * @param {string|null|undefined} commentBody - Raw comment markdown.
+ * @returns {{ beadsId: string, issueNumber: number } | null}
+ *   Extracted IDs, or `null` if the comment is not a sync comment.
+ */
+export function parseComment(commentBody) {
+  if (!commentBody) return null;
+
+  const tagMatch = commentBody.match(/<!--\s*beads-sync:(\d+)\s*-->/);
+  if (!tagMatch) return null;
+
+  const beadsMatch = commentBody.match(/\*\*Beads:\*\*\s*`([a-zA-Z]+-[a-zA-Z0-9]+)`/);
+  if (!beadsMatch) return null;
+
+  return {
+    beadsId: beadsMatch[1],
+    issueNumber: Number(tagMatch[1]),
+  };
+}

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

@@ -0,0 +1,148 @@
+/**
+ * Config loader for GitHub-Beads issue sync.
+ * @module scripts/github-beads-sync/config
+ */
+
+import { readFileSync } from 'node:fs';
+
+/**
+ * Default configuration for GitHub-Beads sync.
+ * @type {Readonly<SyncConfig>}
+ */
+export const DEFAULT_CONFIG = Object.freeze({
+  labelToType: Object.freeze({
+    bug: 'bug',
+    enhancement: 'feature',
+    documentation: 'task',
+    question: 'task',
+  }),
+  labelToPriority: Object.freeze({
+    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: Object.freeze(['MEMBER', 'COLLABORATOR', 'OWNER']),
+});
+
+/**
+ * Deep-merge source into target (one level of nesting).
+ * Arrays and scalars from source overwrite target.
+ * Plain objects are merged key-by-key.
+ * @param {object} target
+ * @param {object} source
+ * @returns {object} Merged result (new object)
+ */
+function deepMerge(target, source) {
+  const result = { ...target };
+  for (const key of Object.keys(source)) {
+    const srcVal = source[key];
+    const tgtVal = target[key];
+    if (
+      srcVal !== null &&
+      typeof srcVal === 'object' &&
+      !Array.isArray(srcVal) &&
+      tgtVal !== null &&
+      typeof tgtVal === 'object' &&
+      !Array.isArray(tgtVal)
+    ) {
+      result[key] = { ...tgtVal, ...srcVal };
+    } else {
+      result[key] = srcVal;
+    }
+  }
+  return result;
+}
+
+/**
+ * Clone DEFAULT_CONFIG into a mutable plain object.
+ * @returns {object}
+ */
+function cloneDefaults() {
+  return {
+    ...DEFAULT_CONFIG,
+    labelToType: { ...DEFAULT_CONFIG.labelToType },
+    labelToPriority: { ...DEFAULT_CONFIG.labelToPriority },
+    gateAssociations: [...DEFAULT_CONFIG.gateAssociations],
+  };
+}
+
+/**
+ * Load and validate sync configuration.
+ * - No arguments: returns a copy of DEFAULT_CONFIG.
+ * - With path: reads JSON file and deep-merges with defaults (user overrides win).
+ * - Missing file: returns defaults (no throw).
+ * - Invalid JSON: throws with helpful message.
+ *
+ * @param {string} [configPath] - Path to a JSON config file.
+ * @returns {object} Merged configuration object.
+ */
+export function loadConfig(configPath) {
+  if (!configPath) {
+    return cloneDefaults();
+  }
+
+  let raw;
+  try {
+    raw = readFileSync(configPath, 'utf-8');
+  } catch {
+    // File not found or unreadable — return defaults
+    return cloneDefaults();
+  }
+
+  let userConfig;
+  try {
+    userConfig = JSON.parse(raw);
+  } catch (parseErr) {
+    throw new Error(
+      `Invalid JSON in config file: ${configPath}\n` +
+      `Parse error: ${parseErr.message}`,
+      { cause: parseErr }
+    );
+  }
+
+  const merged = deepMerge(cloneDefaults(), userConfig);
+  return validateConfig(merged);
+}
+
+/**
+ * Validate and normalize config values.
+ * Replaces invalid types with defaults rather than throwing.
+ * @param {object} cfg
+ * @returns {object} Validated config
+ */
+function validateConfig(cfg) {
+  const defaults = cloneDefaults();
+  if (!cfg.labelToType || typeof cfg.labelToType !== 'object' || Array.isArray(cfg.labelToType)) {
+    cfg.labelToType = defaults.labelToType;
+  }
+  if (!cfg.labelToPriority || typeof cfg.labelToPriority !== 'object' || Array.isArray(cfg.labelToPriority)) {
+    cfg.labelToPriority = defaults.labelToPriority;
+  }
+  if (typeof cfg.defaultPriority !== 'number') {
+    cfg.defaultPriority = defaults.defaultPriority;
+  }
+  if (typeof cfg.mapAssignee !== 'boolean') {
+    cfg.mapAssignee = defaults.mapAssignee;
+  }
+  if (!Array.isArray(cfg.gateAssociations)) {
+    cfg.gateAssociations = defaults.gateAssociations;
+  }
+  const VALID_GATE_VALUES = ['none', 'author_association', 'label'];
+  if (!VALID_GATE_VALUES.includes(cfg.publicRepoGate)) {
+    cfg.publicRepoGate = defaults.publicRepoGate;
+  }
+  if (typeof cfg.defaultType !== 'string' || !cfg.defaultType) {
+    cfg.defaultType = defaults.defaultType;
+  }
+  if (typeof cfg.gateLabelName !== 'string' || !cfg.gateLabelName) {
+    cfg.gateLabelName = defaults.gateLabelName;
+  }
+  return cfg;
+}

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

@@ -0,0 +1,131 @@
+/**
+ * GitHub API caller module using `gh api` CLI.
+ * Builds argument arrays for execFileSync('gh', args) — no shell invocation.
+ * @module github-api
+ */
+
+import { execFileSync } from 'node:child_process';
+
+const SYNC_MARKER = '<!-- beads-sync:';
+
+/**
+ * Builds args for listing all comments on a GitHub issue.
+ * @param {string} owner - Repository owner
+ * @param {string} repo - Repository name
+ * @param {number|string} issueNumber - Issue number
+ * @returns {string[]} Args array for execFileSync('gh', args)
+ */
+export function buildFindCommentsArgs(owner, repo, issueNumber) {
+  return [
+    'api',
+    `repos/${owner}/${repo}/issues/${issueNumber}/comments`,
+  ];
+}
+
+/**
+ * Finds the beads-sync comment in a list of comment objects.
+ * @param {Array<{id: number, body: string}>} comments - Array of GitHub comment objects
+ * @returns {{id: number, body: string}|null} The sync comment or null
+ */
+export function parseFindSyncComment(comments) {
+  const match = comments.find((c) => c.body && c.body.includes(SYNC_MARKER));
+  if (!match) return null;
+  return { id: match.id, body: match.body };
+}
+
+/**
+ * Builds args for creating a comment on a GitHub issue.
+ * @param {string} owner - Repository owner
+ * @param {string} repo - Repository name
+ * @param {number|string} issueNumber - Issue number
+ * @param {string} body - Comment body
+ * @returns {string[]} Args array for execFileSync('gh', args)
+ */
+export function buildCreateCommentArgs(owner, repo, issueNumber, body) {
+  return [
+    'api',
+    `repos/${owner}/${repo}/issues/${issueNumber}/comments`,
+    '-f',
+    `body=${body}`,
+  ];
+}
+
+/**
+ * Builds args for editing an existing comment.
+ * @param {string} owner - Repository owner
+ * @param {string} repo - Repository name
+ * @param {number|string} commentId - Comment ID
+ * @param {string} body - Updated comment body
+ * @returns {string[]} Args array for execFileSync('gh', args)
+ */
+export function buildEditCommentArgs(owner, repo, commentId, body) {
+  return [
+    'api',
+    `repos/${owner}/${repo}/issues/comments/${commentId}`,
+    '-X',
+    'PATCH',
+    '-f',
+    `body=${body}`,
+  ];
+}
+
+/**
+ * Builds args for closing a GitHub issue.
+ * @param {string} owner - Repository owner
+ * @param {string} repo - Repository name
+ * @param {number|string} issueNumber - Issue number
+ * @returns {string[]} Args array for execFileSync('gh', args)
+ */
+export function buildCloseIssueArgs(owner, repo, issueNumber) {
+  return [
+    'api',
+    `repos/${owner}/${repo}/issues/${issueNumber}`,
+    '-X',
+    'PATCH',
+    '-f',
+    'state=closed',
+  ];
+}
+
+/**
+ * Finds the existing beads-sync comment on an issue, or returns null.
+ * @param {string} owner - Repository owner
+ * @param {string} repo - Repository name
+ * @param {number|string} issueNumber - Issue number
+ * @returns {{id: number, body: string}|null}
+ */
+export function findSyncComment(owner, repo, issueNumber) {
+  const args = buildFindCommentsArgs(owner, repo, issueNumber);
+  const raw = execFileSync('gh', args, { encoding: 'utf-8' });
+  const comments = JSON.parse(raw);
+  return parseFindSyncComment(comments);
+}
+
+/**
+ * Creates or edits the beads-sync comment on an issue.
+ * If a sync comment already exists, edits it; otherwise creates a new one.
+ * @param {string} owner - Repository owner
+ * @param {string} repo - Repository name
+ * @param {number|string} issueNumber - Issue number
+ * @param {string} body - Comment body (should contain the beads-sync marker)
+ * @returns {void}
+ */
+export function createOrEditComment(owner, repo, issueNumber, body) {
+  const existing = findSyncComment(owner, repo, issueNumber);
+  const args = existing
+    ? buildEditCommentArgs(owner, repo, existing.id, body)
+    : buildCreateCommentArgs(owner, repo, issueNumber, body);
+  execFileSync('gh', args, { encoding: 'utf-8' });
+}
+
+/**
+ * Closes a GitHub issue.
+ * @param {string} owner - Repository owner
+ * @param {string} repo - Repository name
+ * @param {number|string} issueNumber - Issue number
+ * @returns {void}
+ */
+export function closeIssue(owner, repo, issueNumber) {
+  const args = buildCloseIssueArgs(owner, repo, issueNumber);
+  execFileSync('gh', args, { encoding: 'utf-8' });
+}

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

@@ -0,0 +1,332 @@
+/**
+ * Main entry point for GitHub-Beads issue sync.
+ * Orchestrates all Wave 1 modules to handle GitHub webhook events.
+ *
+ * @module scripts/github-beads-sync/index
+ */
+
+import { readFileSync, appendFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { loadConfig } from './config.mjs';
+import { sanitizeTitle } from './sanitize.mjs';
+import { mapLabels } from './label-mapper.mjs';
+import { bdCreate as realBdCreate, bdClose as realBdClose, bdShow as realBdShow } from './run-bd.mjs';
+import { getBeadsId as realGetBeadsId, setBeadsId as realSetBeadsId } from './mapping.mjs';
+import { buildComment, parseComment } from './comment.mjs';
+import {
+  findSyncComment as realFindSyncComment,
+  createOrEditComment as realCreateOrEditComment,
+} from './github-api.mjs';
+
+/**
+ * Check if a sender login matches known bot patterns.
+ * @param {string} login - GitHub sender login
+ * @returns {boolean}
+ */
+function isBot(login) {
+  if (!login) return false;
+  return login.includes('[bot]') || login === 'github-actions';
+}
+
+/**
+ * Check if an issue has the skip-beads-sync label.
+ * @param {Array<{name: string}|string>} labels
+ * @returns {boolean}
+ */
+function hasSkipLabel(labels) {
+  if (!labels) return false;
+  return labels.some((l) => {
+    const name = typeof l === 'string' ? l : l.name;
+    return name === 'skip-beads-sync';
+  });
+}
+
+/**
+ * Handle a GitHub issue "opened" event.
+ *
+ * @param {object} event - Parsed GitHub webhook payload
+ * @param {object} options
+ * @param {string} [options.configPath] - Path to config JSON
+ * @param {string} options.mappingPath - Path to mapping JSON
+ * @param {string} options.owner - Repository owner
+ * @param {string} options.repo - Repository name
+ * @param {object} [options.bd] - Dependency injection for bd functions
+ * @param {object} [options.github] - Dependency injection for github-api functions
+ * @param {object} [options.mapping] - Dependency injection for mapping functions
+ * @param {object} [options.configOverride] - Merge into loaded config (for testing)
+ * @returns {object} Result object
+ */
+export function handleOpened(event, options = {}) {
+  const {
+    configPath,
+    mappingPath,
+    owner,
+    repo,
+    bd = {},
+    github = {},
+    mapping = {},
+    configOverride,
+  } = options;
+
+  const bdCreate = bd.bdCreate ?? realBdCreate;
+  const findSyncComment = github.findSyncComment ?? realFindSyncComment;
+  const createOrEditComment = github.createOrEditComment ?? realCreateOrEditComment;
+  const getBeadsId = mapping.getBeadsId ?? realGetBeadsId;
+  const setBeadsId = mapping.setBeadsId ?? realSetBeadsId;
+
+  // 1. Load config
+  let config = loadConfig(configPath);
+  if (configOverride) {
+    config = { ...config, ...configOverride };
+  }
+
+  // 2. Extract event data
+  const issue = event.issue;
+  const issueNumber = issue.number;
+  const rawTitle = issue.title;
+  const labels = issue.labels || [];
+  const assignee = config.mapAssignee ? issue.assignee?.login : undefined;
+  const htmlUrl = issue.html_url;
+  const body = issue.body ?? '';
+  const authorAssociation = issue.author_association;
+
+  // 3. Guard: bot actor
+  if (isBot(event.sender?.login)) {
+    return { skipped: true, reason: 'bot actor' };
+  }
+
+  // 4. Guard: skip label
+  if (hasSkipLabel(labels)) {
+    return { skipped: true, reason: 'skip label' };
+  }
+
+  // 5. Guard: no-beads body
+  if (body.includes('no-beads')) {
+    return { skipped: true, reason: 'no-beads in body' };
+  }
+
+  // 6. Guard: public repo gate
+  if (config.publicRepoGate === 'author_association') {
+    const allowed = config.gateAssociations || [];
+    if (!allowed.includes(authorAssociation)) {
+      return { skipped: true, reason: 'author not authorized' };
+    }
+  } else if (config.publicRepoGate === 'label') {
+    const gateLabelName = config.gateLabelName || 'beads-track';
+    const hasGateLabel = labels.some((l) => {
+      const name = typeof l === 'string' ? l : l.name;
+      return name === gateLabelName;
+    });
+    if (!hasGateLabel) {
+      return { skipped: true, reason: `missing required label: ${gateLabelName}` };
+    }
+  }
+
+  // 7. Idempotency — check mapping file first (fast, survives comment deletion)
+  const existingBeadsId = getBeadsId(mappingPath, issueNumber);
+  if (existingBeadsId) {
+    // Mapping exists — ensure the GitHub comment is present (repair if deleted)
+    const existingComment = findSyncComment(owner, repo, issueNumber);
+    if (!existingComment) {
+      const externalRef = `gh-${issueNumber}`;
+      const commentBody = buildComment(existingBeadsId, issueNumber, { externalRef });
+      createOrEditComment(owner, repo, issueNumber, commentBody);
+    }
+    return {
+      skipped: true,
+      reason: 'already synced (mapping file)',
+      beadsId: existingBeadsId,
+    };
+  }
+
+  // 7b. Fallback idempotency — check for existing sync comment
+  const existingComment = findSyncComment(owner, repo, issueNumber);
+  if (existingComment) {
+    const parsed = parseComment(existingComment.body);
+    // Repair mapping file from comment
+    if (parsed?.beadsId) {
+      setBeadsId(mappingPath, issueNumber, parsed.beadsId);
+    }
+    return {
+      skipped: true,
+      reason: 'already synced (comment)',
+      beadsId: parsed?.beadsId ?? null,
+    };
+  }
+
+  // 8. Sanitize title (labels mapped from raw names — sanitization only needed for CLI args)
+  const { sanitized: sanitizedTitle, warnings: titleWarnings } = sanitizeTitle(rawTitle);
+  if (titleWarnings.length) console.warn('sanitize:', titleWarnings);
+
+  // 9. Map labels using raw names (case-insensitive matching in mapLabels handles normalization)
+  const rawLabelNames = labels.map((l) => (typeof l === 'string' ? l : l.name));
+  const { type, priority } = mapLabels(rawLabelNames, config);
+
+  // 10. Create beads issue
+  const externalRef = `gh-${issueNumber}`;
+  const beadsId = bdCreate({
+    title: sanitizedTitle,
+    type,
+    priority,
+    assignee,
+    description: htmlUrl,
+    externalRef,
+  });
+
+  if (!beadsId) {
+    return { success: false, reason: 'bd create failed — no beads ID returned', issueNumber };
+  }
+
+  // 11. Update mapping
+  setBeadsId(mappingPath, issueNumber, beadsId);
+
+  // 12. Build and post comment
+  const commentBody = buildComment(beadsId, issueNumber, { type, priority, externalRef });
+  createOrEditComment(owner, repo, issueNumber, commentBody);
+
+  // 13. Return success
+  return { success: true, beadsId, issueNumber };
+}
+
+/**
+ * Handle a GitHub issue "closed" event.
+ *
+ * @param {object} event - Parsed GitHub webhook payload
+ * @param {object} options
+ * @param {string} options.mappingPath - Path to mapping JSON
+ * @param {string} options.owner - Repository owner
+ * @param {string} options.repo - Repository name
+ * @param {object} [options.bd] - Dependency injection for bd functions
+ * @param {object} [options.github] - Dependency injection for github-api functions
+ * @param {object} [options.mapping] - Dependency injection for mapping functions
+ * @returns {object} Result object
+ */
+export function handleClosed(event, options = {}) {
+  const {
+    mappingPath,
+    owner,
+    repo,
+    bd = {},
+    github = {},
+    mapping = {},
+  } = options;
+
+  const bdClose = bd.bdClose ?? realBdClose;
+  const bdShow = bd.bdShow ?? realBdShow;
+  const getBeadsId = mapping.getBeadsId ?? realGetBeadsId;
+  const findSyncComment = github.findSyncComment ?? realFindSyncComment;
+
+  // 1. Extract issue number, labels, and state reason
+  const issueNumber = event.issue.number;
+  const labels = event.issue.labels || [];
+  const stateReason = event.issue.state_reason;
+
+  // 2. Guard: bot actor
+  if (isBot(event.sender?.login)) {
+    return { skipped: true, reason: 'bot actor' };
+  }
+
+  // 3. Guard: skip label
+  if (hasSkipLabel(labels)) {
+    return { skipped: true, reason: 'skip label' };
+  }
+
+  // 4. Guard: skip "not planned" closures (only close on "completed")
+  if (stateReason && stateReason !== 'completed') {
+    return { skipped: true, reason: `closed as ${stateReason}` };
+  }
+
+  // 5. Read mapping
+  let beadsId = getBeadsId(mappingPath, issueNumber);
+
+  // 6. Fallback: find via sync comment
+  if (!beadsId) {
+    const comment = findSyncComment(owner, repo, issueNumber);
+    if (comment) {
+      const parsed = parseComment(comment.body);
+      // Verify the comment's tagged issue number matches current issue (prevents cross-issue close)
+      if (parsed && parsed.issueNumber === issueNumber) {
+        beadsId = parsed.beadsId;
+      }
+    }
+  }
+
+  // 7. No beads link found
+  if (!beadsId) {
+    return { skipped: true, reason: 'no beads link found' };
+  }
+
+  // 8. Check if already closed
+  const status = bdShow(beadsId);
+  if (status === null) {
+    return { skipped: true, reason: 'could not determine beads status' };
+  }
+  if (status === 'closed') {
+    return { skipped: true, reason: 'already closed' };
+  }
+
+  // 9. Close beads issue
+  bdClose(beadsId, `Closed via GitHub issue #${issueNumber}`);
+
+  // 10. Return success
+  return { success: true, beadsId, issueNumber };
+}
+
+// ---------------------------------------------------------------------------
+// CLI entry point
+// ---------------------------------------------------------------------------
+const __filename = fileURLToPath(import.meta.url);
+if (process.argv[1] === __filename) {
+  const action = process.argv[2];
+  const eventPath = process.env.GITHUB_EVENT_PATH || process.argv[3];
+
+  if (!action || !eventPath) {
+    console.error('Usage: node index.mjs <opened|closed> [event-path]');
+    console.error('  GITHUB_EVENT_PATH env var is used if event-path arg is omitted.');
+    process.exit(1);
+  }
+
+  const event = JSON.parse(readFileSync(eventPath, 'utf-8'));
+  const [owner, repo] = (process.env.GITHUB_REPOSITORY || 'unknown/unknown').split('/');
+
+  const options = {
+    configPath: process.env.BEADS_SYNC_CONFIG || undefined,
+    mappingPath: process.env.BEADS_SYNC_MAPPING || '.github/beads-mapping.json',
+    owner,
+    repo,
+  };
+
+  // Validate action explicitly — only allow known actions
+  const VALID_ACTIONS = ['opened', 'closed'];
+  if (!VALID_ACTIONS.includes(action)) {
+    console.error(`Unknown action: "${action}". Expected one of: ${VALID_ACTIONS.join(', ')}`);
+    process.exit(1);
+  }
+
+  const handler = action === 'opened' ? handleOpened : handleClosed;
+
+  Promise.resolve(handler(event, options))
+    .then((result) => {
+      console.log(JSON.stringify(result, null, 2));
+
+      // Exit non-zero on logical failure (e.g., bdCreate returned null)
+      if (result.success === false) {
+        console.error(`Sync failed: ${result.reason || 'unknown'}`);
+        process.exit(1);
+      }
+
+      // Write to GITHUB_OUTPUT if available
+      const outputPath = process.env.GITHUB_OUTPUT;
+      if (outputPath) {
+        for (const [key, value] of Object.entries(result)) {
+          if (value != null) {
+            appendFileSync(outputPath, `${key}=${value}\n`);
+          }
+        }
+      }
+    })
+    .catch((err) => {
+      console.error('Fatal:', err.message);
+      process.exit(1);
+    });
+}