forge-workflow 0.0.8 → 0.0.10

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

@@ -10,29 +10,18 @@ import { fileURLToPath } from 'node:url';
 import { loadConfig } from './config.mjs';
 import { sanitizeTitle } from './sanitize.mjs';
 import { mapLabels } from './label-mapper.mjs';
+import { resolveCanonicalBeadsLink, upsertCanonicalBeadsLink } from './mapping.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';
+import { createOrEditComment as realCreateOrEditComment, findSyncComment as realFindSyncComment } from './github-api.mjs';
+
+const DEFAULT_MAPPING_PATH = '.github/beads-mapping.json';
 
-/**
- * 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) => {
@@ -41,6 +30,39 @@ function hasSkipLabel(labels) {
   });
 }
 
+function getGitHubLink(issue = {}) {
+  return {
+    nodeId: issue.node_id ?? issue.nodeId ?? null,
+    number: issue.number ?? null,
+    url: issue.html_url ?? null,
+  };
+}
+
+function createCanonicalLinkStore(mappingPath) {
+  return {
+    resolveCanonicalLink(lookup) {
+      return resolveCanonicalBeadsLink(mappingPath, lookup);
+    },
+    upsertCanonicalLink(link) {
+      return upsertCanonicalBeadsLink(mappingPath, link);
+    },
+  };
+}
+
+function getCanonicalLinkStore(options = {}) {
+  const defaultStore = createCanonicalLinkStore(options.mappingPath ?? DEFAULT_MAPPING_PATH);
+
+  if (
+    options.linkStore &&
+    typeof options.linkStore.resolveCanonicalLink === 'function' &&
+    typeof options.linkStore.upsertCanonicalLink === 'function'
+  ) {
+    return options.linkStore;
+  }
+
+  return defaultStore;
+}
+
 /**
  * Handle a GitHub issue "opened" event.
  *
@@ -52,35 +74,30 @@ function hasSkipLabel(labels) {
  * @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.linkStore] - Dependency injection for canonical link store
  * @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;
+  const findSyncComment = github.findSyncComment ?? realFindSyncComment;
+  const canonicalLinkStore = getCanonicalLinkStore(options);
 
-  // 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;
@@ -89,23 +106,22 @@ export function handleOpened(event, options = {}) {
   const htmlUrl = issue.html_url;
   const body = issue.body ?? '';
   const authorAssociation = issue.author_association;
+  const rawLabelNames = labels.map((l) => (typeof l === 'string' ? l : l.name));
+  const { type, priority } = mapLabels(rawLabelNames, config);
+  const externalRef = `gh-${issueNumber}`;
 
-  // 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)) {
@@ -122,48 +138,54 @@ export function handleOpened(event, options = {}) {
     }
   }
 
-  // 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);
-    }
+  const canonicalLink = canonicalLinkStore.resolveCanonicalLink({
+    githubNodeId: issue.node_id ?? issue.nodeId ?? null,
+    githubNumber: issue.number,
+  });
+  if (canonicalLink) {
+    const commentBody = buildComment(canonicalLink.forgeIssueId, issueNumber, {
+      type,
+      priority,
+      externalRef,
+    });
+    createOrEditComment(owner, repo, issueNumber, commentBody);
     return {
       skipped: true,
-      reason: 'already synced (mapping file)',
-      beadsId: existingBeadsId,
+      reason: 'already synced (canonical link)',
+      beadsId: canonicalLink.forgeIssueId,
     };
   }
 
-  // 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);
-    }
+  const existingSyncComment = parseComment(findSyncComment(owner, repo, issueNumber)?.body);
+  if (existingSyncComment?.beadsId) {
+    canonicalLinkStore.upsertCanonicalLink({
+      forgeIssueId: existingSyncComment.beadsId,
+      github: getGitHubLink(issue),
+      sources: [
+        {
+          source: 'syncComment',
+          forgeIssueId: existingSyncComment.beadsId,
+          githubNumber: issueNumber,
+          url: htmlUrl,
+        },
+      ],
+      diagnostics: [],
+    });
+    const commentBody = buildComment(existingSyncComment.beadsId, issueNumber, {
+      type,
+      priority,
+      externalRef,
+    });
+    createOrEditComment(owner, repo, issueNumber, commentBody);
     return {
       skipped: true,
-      reason: 'already synced (comment)',
-      beadsId: parsed?.beadsId ?? null,
+      reason: 'already synced (sync comment)',
+      beadsId: existingSyncComment.beadsId,
     };
   }
 
-  // 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,
@@ -174,17 +196,26 @@ export function handleOpened(event, options = {}) {
   });
 
   if (!beadsId) {
-    return { success: false, reason: 'bd create failed — no beads ID returned', issueNumber };
+    return { success: false, reason: 'bd create failed - no beads ID returned', issueNumber };
   }
 
-  // 11. Update mapping
-  setBeadsId(mappingPath, issueNumber, beadsId);
+  canonicalLinkStore.upsertCanonicalLink({
+    forgeIssueId: beadsId,
+    github: getGitHubLink(issue),
+    sources: [
+      {
+        source: 'externalRef',
+        forgeIssueId: beadsId,
+        githubNumber: issueNumber,
+        url: htmlUrl,
+      },
+    ],
+    diagnostics: [],
+  });
 
-  // 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 };
 }
 
@@ -198,65 +229,66 @@ export function handleOpened(event, options = {}) {
  * @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.linkStore] - Dependency injection for canonical link store
  * @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;
+  const findSyncComment = options.github?.findSyncComment ?? realFindSyncComment;
+  const canonicalLinkStore = getCanonicalLinkStore(options);
 
-  // 1. Extract issue number, labels, and state reason
-  const issueNumber = event.issue.number;
-  const labels = event.issue.labels || [];
-  const stateReason = event.issue.state_reason;
+  const issue = event.issue;
+  const issueNumber = issue.number;
+  const labels = issue.labels || [];
+  const stateReason = 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);
+  const canonicalLink = canonicalLinkStore.resolveCanonicalLink({
+    githubNodeId: issue.node_id ?? issue.nodeId ?? null,
+    githubNumber: issue.number,
+  });
+  let beadsId = canonicalLink?.forgeIssueId ?? null;
 
-  // 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;
-      }
+    const syncCommentLink = parseComment(findSyncComment(options.owner, options.repo, issueNumber)?.body);
+    if (syncCommentLink?.beadsId && syncCommentLink.issueNumber === issueNumber) {
+      canonicalLinkStore.upsertCanonicalLink({
+        forgeIssueId: syncCommentLink.beadsId,
+        github: getGitHubLink(issue),
+        sources: [
+          {
+            source: 'syncComment',
+            forgeIssueId: syncCommentLink.beadsId,
+            githubNumber: issueNumber,
+            url: issue.html_url ?? null,
+          },
+        ],
+        diagnostics: [],
+      });
+      beadsId = syncCommentLink.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' };
@@ -265,16 +297,11 @@ export function handleClosed(event, options = {}) {
     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];
@@ -291,12 +318,11 @@ if (process.argv[1] === __filename) {
 
   const options = {
     configPath: process.env.BEADS_SYNC_CONFIG || undefined,
-    mappingPath: process.env.BEADS_SYNC_MAPPING || '.github/beads-mapping.json',
+    mappingPath: process.env.BEADS_SYNC_MAPPING || DEFAULT_MAPPING_PATH,
     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(', ')}`);
@@ -309,13 +335,11 @@ if (process.argv[1] === __filename) {
     .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)) {

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

@@ -9,6 +9,11 @@
 
 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.
@@ -76,3 +81,52 @@ export function setBeadsId(mappingPath, issueNumber, beadsId) {
   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,7 +1,7 @@
 #!/usr/bin/env node
 /**
  * CLI entry point for Beads → GitHub reverse sync.
- * Usage: node reverse-sync-cli.mjs <old-jsonl-path> <new-jsonl-path>
+ * Usage: node reverse-sync-cli.mjs <old-snapshot-jsonl-path> <new-snapshot-jsonl-path>
  *
  * @module scripts/github-beads-sync/reverse-sync-cli
  */
@@ -13,7 +13,7 @@ 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>');
+  console.error('Usage: node reverse-sync-cli.mjs <old-snapshot-jsonl-path> <new-snapshot-jsonl-path>');
   process.exit(1);
 }
 

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

@@ -1,6 +1,6 @@
 /**
  * Reverse sync: Beads → GitHub.
- * When a Beads issue is closed (via git push updating .beads/),
+ * 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
@@ -28,13 +28,34 @@ function parseJsonlLines(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 previous .beads/issues.jsonl
- * @param {string[]} newLines - JSONL lines from current .beads/issues.jsonl
+ * @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) {
@@ -93,11 +114,11 @@ export function closeGitHubIssue(owner, repo, issueNumber) {
 
 /**
  * Handle Beads-to-GitHub reverse sync.
- * Detects issues that transitioned to closed in .beads/issues.jsonl
+ * Detects issues that transitioned to closed in exported issue snapshot JSONL
  * and closes the linked GitHub issues.
  *
- * @param {string} oldContent - Previous .beads/issues.jsonl content
- * @param {string} newContent - Current .beads/issues.jsonl content
+ * @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}}
@@ -109,13 +130,16 @@ export function handleBeadsClosed(oldContent, newContent, deps = {}) {
   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 = extractGitHubUrl(issue.description);
+    const parsed = extractPreferredGitHubLink(latestIssues.get(issue.id) ?? issue);
     if (!parsed) {
       skipped.push({ beadsId: issue.id, reason: 'no GitHub URL' });
       continue;

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

@@ -79,10 +79,12 @@ export function buildSearchArgs(query) {
  * @returns {string|null}
  */
 export function parseCreateOutput(stdout) {
-  const match = stdout.match(/Created issue:\s+(forge-[\w-]+)/);
+  // 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-z0-9]+)/i);
+  const fallback = stdout.match(/(forge-[a-zA-Z0-9]+(?:\.[a-zA-Z0-9]+)*)/);
   return fallback ? fallback[1] : null;
 }