specweave 1.0.506 → 1.0.508

package/plugins/specweave/lib/integrations/github/github-ac-comment-poster.js

@@ -0,0 +1,191 @@
+import { readFile } from "fs/promises";
+import { existsSync } from "fs";
+import * as path from "path";
+import { execFileNoThrow } from "../../../../../src/utils/execFileNoThrow.js";
+async function postACProgressComments(incrementId, affectedUSIds, specPath, options) {
+  const result = { posted: [], errors: [] };
+  if (affectedUSIds.length === 0) {
+    return result;
+  }
+  let content;
+  try {
+    content = await readFile(specPath, "utf-8");
+  } catch (err) {
+    result.errors.push({
+      usId: affectedUSIds[0],
+      error: err instanceof Error ? err.message : String(err)
+    });
+    return result;
+  }
+  const issueLinks = await parseIssueLinks(specPath);
+  const repoSlug = `${options.owner}/${options.repo}`;
+  const env = options.token ? { GH_TOKEN: options.token } : void 0;
+  for (const usId of affectedUSIds) {
+    const link = issueLinks[usId];
+    if (!link) {
+      continue;
+    }
+    const acStates = parseACStatesForUS(content, usId);
+    const allComplete = acStates.length > 0 && acStates.every((ac) => ac.completed);
+    if (!allComplete) {
+      const commentBody = buildProgressCommentForUS(incrementId, usId, acStates);
+      const execResult = await execFileNoThrow(
+        "gh",
+        ["issue", "comment", String(link.issueNumber), "--body", commentBody, "-R", repoSlug],
+        env ? { env } : {}
+      );
+      if (execResult.success) {
+        result.posted.push({ usId, issueNumber: link.issueNumber });
+      } else {
+        result.errors.push({
+          usId,
+          error: execResult.stderr || "Unknown error posting comment"
+        });
+      }
+    }
+    if (acStates.length > 0) {
+      try {
+        await patchIssueBodyCheckboxes(link.issueNumber, acStates, repoSlug, env);
+      } catch (patchErr) {
+        result.errors.push({
+          usId,
+          error: `body-patch: ${patchErr instanceof Error ? patchErr.message : String(patchErr)}`
+        });
+      }
+    }
+  }
+  return result;
+}
+async function parseIssueLinks(specPath) {
+  const links = {};
+  try {
+    const metadataPath = path.join(path.dirname(specPath), "metadata.json");
+    if (!existsSync(metadataPath)) return links;
+    const raw = await readFile(metadataPath, "utf-8");
+    const metadata = JSON.parse(raw);
+    if (metadata.github?.issues && Array.isArray(metadata.github.issues)) {
+      for (const entry of metadata.github.issues) {
+        if (entry.userStory && entry.number) {
+          links[entry.userStory] = {
+            issueNumber: entry.number,
+            issueUrl: entry.url || ""
+          };
+        }
+      }
+    }
+    if (metadata.externalLinks?.github?.issues) {
+      const issues = metadata.externalLinks.github.issues;
+      for (const [usId, data] of Object.entries(issues)) {
+        const issueData = data;
+        if (issueData.issueNumber) {
+          links[usId] = {
+            issueNumber: issueData.issueNumber,
+            issueUrl: issueData.issueUrl || ""
+          };
+        }
+      }
+    }
+  } catch {
+  }
+  return links;
+}
+function parseUSIdParts(usId) {
+  const compoundMatch = usId.match(/^US-([A-Z]+)-(\d+)$/);
+  if (compoundMatch) {
+    return { prefix: compoundMatch[1], num: parseInt(compoundMatch[2], 10) };
+  }
+  const simpleMatch = usId.match(/^US-(\d+)$/);
+  if (simpleMatch) {
+    return { num: parseInt(simpleMatch[1], 10) };
+  }
+  const fallback = usId.match(/(\d+)$/);
+  return { num: fallback ? parseInt(fallback[1], 10) : 0 };
+}
+function buildACPrefix(usId) {
+  const { prefix, num } = parseUSIdParts(usId);
+  return prefix ? `AC-${prefix}-US${num}-` : `AC-US${num}-`;
+}
+function parseACStatesForUS(content, usId) {
+  const states = [];
+  const acPrefix = buildACPrefix(usId);
+  const escapedPrefix = acPrefix.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const acPattern = new RegExp(
+    `- \\[([ x])\\] (?:\\*\\*)?${escapedPrefix}(\\d+)(?:\\*\\*)?:\\s*(.+)`,
+    "g"
+  );
+  let match;
+  while ((match = acPattern.exec(content)) !== null) {
+    states.push({
+      id: `${acPrefix}${match[2]}`,
+      description: match[3].trim(),
+      completed: match[1] === "x"
+    });
+  }
+  return states;
+}
+function buildProgressCommentForUS(incrementId, usId, acStates) {
+  const total = acStates.length;
+  const completed = acStates.filter((ac) => ac.completed).length;
+  const percentage = total > 0 ? Math.round(completed / total * 100) : 0;
+  let comment = `**Progress Update** \u2014 ${usId} (Increment ${incrementId})
+
+`;
+  comment += `**Status**: ${completed}/${total} ACs complete (${percentage}%)
+
+`;
+  if (completed > 0) {
+    comment += `**Completed**:
+`;
+    for (const ac of acStates.filter((a) => a.completed)) {
+      comment += `- [x] **${ac.id}**: ${ac.description}
+`;
+    }
+    comment += "\n";
+  }
+  if (completed < total) {
+    comment += `**Remaining**:
+`;
+    for (const ac of acStates.filter((a) => !a.completed)) {
+      comment += `- [ ] **${ac.id}**: ${ac.description}
+`;
+    }
+    comment += "\n";
+  }
+  comment += `---
+`;
+  comment += `Auto-synced by SpecWeave | ${(/* @__PURE__ */ new Date()).toISOString().split("T")[0]}
+`;
+  return comment;
+}
+async function patchIssueBodyCheckboxes(issueNumber, acStates, repoSlug, env) {
+  const acMap = new Map(acStates.map((ac) => [ac.id, ac.completed]));
+  const fetchResult = await execFileNoThrow(
+    "gh",
+    ["issue", "view", String(issueNumber), "--json", "body", "-q", ".body", "-R", repoSlug],
+    env ? { env } : {}
+  );
+  if (!fetchResult.success || !fetchResult.stdout) return;
+  const body = fetchResult.stdout;
+  const patchedBody = body.replace(
+    /^(- \[)[ x](\] (?:\*\*)?)(AC-[A-Z0-9]+-\d+)((?:\*\*)?: .+)$/gm,
+    (_match, prefix, mid, acId, suffix) => {
+      const completed = acMap.get(acId);
+      if (completed !== void 0) {
+        return `${prefix}${completed ? "x" : " "}${mid}${acId}${suffix}`;
+      }
+      return _match;
+    }
+  );
+  if (patchedBody === body) return;
+  const editResult = await execFileNoThrow(
+    "gh",
+    ["issue", "edit", String(issueNumber), "--body", patchedBody, "-R", repoSlug],
+    env ? { env } : {}
+  );
+  if (!editResult.success) {
+    throw new Error(editResult.stderr || "Failed to update issue body");
+  }
+}
+export {
+  postACProgressComments
+};

package/plugins/specweave/lib/integrations/github/github-ac-comment-poster.ts

@@ -0,0 +1,315 @@
+/**
+ * GitHub AC Comment Poster — Posts progress comments to GitHub issues
+ * when acceptance criteria are completed in spec.md.
+ *
+ * Triggered by github-ac-sync-handler.sh after task-ac-sync-guard
+ * updates spec.md ACs.
+ *
+ * @module github-ac-comment-poster
+ */
+
+import { readFile } from 'fs/promises';
+import { existsSync } from 'fs';
+import * as path from 'path';
+import { execFileNoThrow } from '../../../../../src/utils/execFileNoThrow.js';
+
+export interface CommentPostOptions {
+  owner: string;
+  repo: string;
+  token?: string;
+}
+
+export interface CommentPostResult {
+  posted: Array<{ usId: string; issueNumber: number }>;
+  errors: Array<{ usId: string; error: string }>;
+}
+
+interface ParsedACState {
+  id: string;
+  description: string;
+  completed: boolean;
+}
+
+interface ParsedUSIssueLink {
+  issueNumber: number;
+  issueUrl: string;
+}
+
+/**
+ * Post AC progress comments to GitHub issues for affected user stories.
+ *
+ * For each affected US:
+ * 1. Look up GitHub issue link from spec.md frontmatter
+ * 2. Extract AC states for that US
+ * 3. Build progress comment
+ * 4. Post via `gh issue comment`
+ *
+ * Never throws — all errors are captured in result.errors.
+ */
+export async function postACProgressComments(
+  incrementId: string,
+  affectedUSIds: string[],
+  specPath: string,
+  options: CommentPostOptions,
+): Promise<CommentPostResult> {
+  const result: CommentPostResult = { posted: [], errors: [] };
+
+  if (affectedUSIds.length === 0) {
+    return result;
+  }
+
+  let content: string;
+  try {
+    content = await readFile(specPath, 'utf-8');
+  } catch (err) {
+    result.errors.push({
+      usId: affectedUSIds[0],
+      error: err instanceof Error ? err.message : String(err),
+    });
+    return result;
+  }
+
+  const issueLinks = await parseIssueLinks(specPath);
+  const repoSlug = `${options.owner}/${options.repo}`;
+  const env = options.token ? { GH_TOKEN: options.token } : undefined;
+
+  for (const usId of affectedUSIds) {
+    const link = issueLinks[usId];
+    if (!link) {
+      continue;
+    }
+
+    const acStates = parseACStatesForUS(content, usId);
+
+    // Skip progress comment when all ACs are complete — the auto-closer will
+    // post its own "All acceptance criteria completed" comment instead,
+    // preventing duplicate comments on the same issue.
+    const allComplete = acStates.length > 0 && acStates.every(ac => ac.completed);
+
+    if (!allComplete) {
+      const commentBody = buildProgressCommentForUS(incrementId, usId, acStates);
+
+      const execResult = await execFileNoThrow(
+        'gh',
+        ['issue', 'comment', String(link.issueNumber), '--body', commentBody, '-R', repoSlug],
+        env ? { env } : {},
+      );
+
+      if (execResult.success) {
+        result.posted.push({ usId, issueNumber: link.issueNumber });
+      } else {
+        result.errors.push({
+          usId,
+          error: execResult.stderr || 'Unknown error posting comment',
+        });
+      }
+    }
+
+    // Patch AC checkboxes directly in the issue body using the known issue number
+    if (acStates.length > 0) {
+      try {
+        await patchIssueBodyCheckboxes(link.issueNumber, acStates, repoSlug, env);
+      } catch (patchErr) {
+        // Body patch failure is non-blocking but should be visible
+        result.errors.push({
+          usId,
+          error: `body-patch: ${patchErr instanceof Error ? patchErr.message : String(patchErr)}`,
+        });
+      }
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Parse issue links from metadata.json (sibling of spec.md).
+ *
+ * Supports TWO formats:
+ * - OLD: metadata.github.issues[] with { userStory, number, url }
+ * - NEW: metadata.externalLinks.github.issues with { [US-XXX]: { issueNumber, issueUrl } }
+ *
+ * Falls back to empty if metadata.json is missing or invalid.
+ */
+async function parseIssueLinks(specPath: string): Promise<Record<string, ParsedUSIssueLink>> {
+  const links: Record<string, ParsedUSIssueLink> = {};
+
+  try {
+    const metadataPath = path.join(path.dirname(specPath), 'metadata.json');
+    if (!existsSync(metadataPath)) return links;
+
+    const raw = await readFile(metadataPath, 'utf-8');
+    const metadata = JSON.parse(raw);
+
+    // OLD format: metadata.github.issues[] array
+    if (metadata.github?.issues && Array.isArray(metadata.github.issues)) {
+      for (const entry of metadata.github.issues) {
+        if (entry.userStory && entry.number) {
+          links[entry.userStory] = {
+            issueNumber: entry.number,
+            issueUrl: entry.url || '',
+          };
+        }
+      }
+    }
+
+    // NEW format: metadata.externalLinks.github.issues object
+    if (metadata.externalLinks?.github?.issues) {
+      const issues = metadata.externalLinks.github.issues;
+      for (const [usId, data] of Object.entries(issues)) {
+        const issueData = data as { issueNumber?: number; issueUrl?: string };
+        if (issueData.issueNumber) {
+          // NEW format entries override OLD format for the same US
+          links[usId] = {
+            issueNumber: issueData.issueNumber,
+            issueUrl: issueData.issueUrl || '',
+          };
+        }
+      }
+    }
+  } catch {
+    // Graceful fallback: return empty if metadata.json is missing or invalid
+  }
+
+  return links;
+}
+
+/**
+ * Parse a US ID into parts for AC matching.
+ * US-001 → { prefix: undefined, num: 1 }
+ * US-SPE-001 → { prefix: 'SPE', num: 1 }
+ */
+function parseUSIdParts(usId: string): { prefix?: string; num: number } {
+  const compoundMatch = usId.match(/^US-([A-Z]+)-(\d+)$/);
+  if (compoundMatch) {
+    return { prefix: compoundMatch[1], num: parseInt(compoundMatch[2], 10) };
+  }
+  const simpleMatch = usId.match(/^US-(\d+)$/);
+  if (simpleMatch) {
+    return { num: parseInt(simpleMatch[1], 10) };
+  }
+  const fallback = usId.match(/(\d+)$/);
+  return { num: fallback ? parseInt(fallback[1], 10) : 0 };
+}
+
+/**
+ * Build the AC ID prefix for a given US ID.
+ * US-001 → "AC-US1-", US-SPE-001 → "AC-SPE-US1-"
+ */
+function buildACPrefix(usId: string): string {
+  const { prefix, num } = parseUSIdParts(usId);
+  return prefix ? `AC-${prefix}-US${num}-` : `AC-US${num}-`;
+}
+
+/**
+ * Extract AC states for a specific user story from spec.md content.
+ * Supports both simple (AC-US1-01) and compound (AC-SPE-US1-01) AC ID formats.
+ */
+function parseACStatesForUS(content: string, usId: string): ParsedACState[] {
+  const states: ParsedACState[] = [];
+  const acPrefix = buildACPrefix(usId);
+  const escapedPrefix = acPrefix.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+  // Support both bold (**AC-...**:) and plain (AC-...:) formats
+  const acPattern = new RegExp(
+    `- \\[([ x])\\] (?:\\*\\*)?${escapedPrefix}(\\d+)(?:\\*\\*)?:\\s*(.+)`,
+    'g',
+  );
+
+  let match;
+  while ((match = acPattern.exec(content)) !== null) {
+    states.push({
+      id: `${acPrefix}${match[2]}`,
+      description: match[3].trim(),
+      completed: match[1] === 'x',
+    });
+  }
+
+  return states;
+}
+
+/**
+ * Build a progress comment for a specific user story.
+ * Follows ProgressCommentBuilder format: percentage, AC checkboxes, timestamp.
+ */
+function buildProgressCommentForUS(
+  incrementId: string,
+  usId: string,
+  acStates: ParsedACState[],
+): string {
+  const total = acStates.length;
+  const completed = acStates.filter(ac => ac.completed).length;
+  const percentage = total > 0 ? Math.round((completed / total) * 100) : 0;
+
+  let comment = `**Progress Update** — ${usId} (Increment ${incrementId})\n\n`;
+  comment += `**Status**: ${completed}/${total} ACs complete (${percentage}%)\n\n`;
+
+  if (completed > 0) {
+    comment += `**Completed**:\n`;
+    for (const ac of acStates.filter(a => a.completed)) {
+      comment += `- [x] **${ac.id}**: ${ac.description}\n`;
+    }
+    comment += '\n';
+  }
+
+  if (completed < total) {
+    comment += `**Remaining**:\n`;
+    for (const ac of acStates.filter(a => !a.completed)) {
+      comment += `- [ ] **${ac.id}**: ${ac.description}\n`;
+    }
+    comment += '\n';
+  }
+
+  comment += `---\n`;
+  comment += `Auto-synced by SpecWeave | ${new Date().toISOString().split('T')[0]}\n`;
+
+  return comment;
+}
+
+/**
+ * Patch AC checkboxes in the GitHub issue body in-place.
+ * Fetches the current body, flips checkboxes to match local AC states,
+ * and updates the issue. Only modifies lines matching AC-USXX-YY patterns.
+ */
+async function patchIssueBodyCheckboxes(
+  issueNumber: number,
+  acStates: ParsedACState[],
+  repoSlug: string,
+  env?: NodeJS.ProcessEnv,
+): Promise<void> {
+  // Build a map of AC ID → completed
+  const acMap = new Map(acStates.map(ac => [ac.id, ac.completed]));
+
+  // Fetch current issue body
+  const fetchResult = await execFileNoThrow(
+    'gh',
+    ['issue', 'view', String(issueNumber), '--json', 'body', '-q', '.body', '-R', repoSlug],
+    env ? { env } : {},
+  );
+  if (!fetchResult.success || !fetchResult.stdout) return;
+
+  const body = fetchResult.stdout;
+
+  // Patch AC checkboxes: match both bold and plain AC-ID patterns
+  const patchedBody = body.replace(
+    /^(- \[)[ x](\] (?:\*\*)?)(AC-[A-Z0-9]+-\d+)((?:\*\*)?: .+)$/gm,
+    (_match: string, prefix: string, mid: string, acId: string, suffix: string) => {
+      const completed = acMap.get(acId);
+      if (completed !== undefined) {
+        return `${prefix}${completed ? 'x' : ' '}${mid}${acId}${suffix}`;
+      }
+      return _match;
+    },
+  );
+
+  if (patchedBody === body) return; // No changes needed
+
+  const editResult = await execFileNoThrow(
+    'gh',
+    ['issue', 'edit', String(issueNumber), '--body', patchedBody, '-R', repoSlug],
+    env ? { env } : {},
+  );
+  if (!editResult.success) {
+    throw new Error(editResult.stderr || 'Failed to update issue body');
+  }
+}

package/plugins/specweave/lib/integrations/github/github-board-resolver.js

@@ -0,0 +1,81 @@
+import { execFileNoThrow } from "../../../../../src/utils/execFileNoThrow.js";
+import { getGitHubAuthFromProject } from "../../../../../src/utils/auth-helpers.js";
+function getGhEnv() {
+  const { token } = getGitHubAuthFromProject(process.cwd());
+  return token ? { ...process.env, GH_TOKEN: token } : process.env;
+}
+async function fetchBoardsForRepo(owner, repo) {
+  console.log(`\u{1F50D} Fetching project boards for repo: ${owner}/${repo}`);
+  try {
+    const result = await execFileNoThrow("gh", [
+      "api",
+      `repos/${owner}/${repo}/projects`,
+      "--jq",
+      ".[] | {id: .id, name: .name, number: .number, state: .state, html_url: .html_url}",
+      "-H",
+      "Accept: application/vnd.github+json"
+    ], { env: getGhEnv() });
+    if (result.exitCode !== 0) {
+      console.error(`\u274C Failed to fetch boards for ${owner}/${repo}:`, result.stderr);
+      throw new Error(`GitHub API error (exit code ${result.exitCode}): ${result.stderr}`);
+    }
+    const boards = result.stdout.trim().split("\n").filter((line) => line.trim()).map((line) => JSON.parse(line));
+    console.log(`\u2705 Found ${boards.length} board(s) for repo ${owner}/${repo}`);
+    return boards;
+  } catch (error) {
+    console.error(`\u274C Error fetching boards for ${owner}/${repo}:`, error.message);
+    throw error;
+  }
+}
+async function fetchBoardsForOrg(org) {
+  console.log(`\u{1F50D} Fetching project boards for org: ${org}`);
+  try {
+    const result = await execFileNoThrow("gh", [
+      "api",
+      `orgs/${org}/projects`,
+      "--jq",
+      ".[] | {id: .id, name: .name, number: .number, state: .state, html_url: .html_url}",
+      "-H",
+      "Accept: application/vnd.github+json"
+    ], { env: getGhEnv() });
+    if (result.exitCode !== 0) {
+      console.error(`\u274C Failed to fetch boards for org ${org}:`, result.stderr);
+      throw new Error(`GitHub API error (exit code ${result.exitCode}): ${result.stderr}`);
+    }
+    const boards = result.stdout.trim().split("\n").filter((line) => line.trim()).map((line) => JSON.parse(line));
+    console.log(`\u2705 Found ${boards.length} board(s) for org ${org}`);
+    return boards;
+  } catch (error) {
+    console.error(`\u274C Error fetching boards for org ${org}:`, error.message);
+    throw error;
+  }
+}
+async function resolveBoardNames(owner, repo, boardNames) {
+  if (!boardNames || boardNames.length === 0) {
+    return /* @__PURE__ */ new Map();
+  }
+  const boards = await fetchBoardsForRepo(owner, repo);
+  const boardMap = /* @__PURE__ */ new Map();
+  for (const boardName of boardNames) {
+    const board = boards.find(
+      (b) => b.name.toLowerCase() === boardName.toLowerCase()
+    );
+    if (board) {
+      boardMap.set(boardName, board.number);
+      console.log(`\u2705 Resolved board "${boardName}" \u2192 Number ${board.number}`);
+    } else {
+      console.warn(`\u26A0\uFE0F  Board "${boardName}" not found in repo ${owner}/${repo}`);
+    }
+  }
+  return boardMap;
+}
+async function getBoardNumbers(owner, repo, boardNames) {
+  const boardMap = await resolveBoardNames(owner, repo, boardNames);
+  return Array.from(boardMap.values());
+}
+export {
+  fetchBoardsForOrg,
+  fetchBoardsForRepo,
+  getBoardNumbers,
+  resolveBoardNames
+};