forge-workflow 0.0.9 → 0.1.0-beta.2

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

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

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

@@ -1,332 +0,0 @@
-/**
- * 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);
-    });
-}

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

@@ -1,54 +0,0 @@
-/**
- * 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 };
-}