specweave 1.0.506 → 1.0.508

package/plugins/specweave/lib/integrations/github/github-sync-orchestrator.ts

@@ -0,0 +1,158 @@
+/**
+ * GitHub Sync Orchestrator — Wires push sync, Projects V2, and frontmatter updates
+ *
+ * Composes all sync sub-components into a single flow:
+ * 1. Push user stories → GitHub issues
+ * 2. (Optional) Add issues to Projects V2 board
+ * 3. (Optional) Set Status/Priority fields on V2 items
+ * 4. Update spec frontmatter with sync results
+ *
+ * @module github-sync-orchestrator
+ */
+
+import { pushSyncUserStories } from './github-push-sync.js';
+import { GitHubBoardResolverV2 } from './github-board-resolver-v2.js';
+import { GitHubFieldSync } from './github-field-sync.js';
+import { updateSpecFrontmatter } from './github-spec-frontmatter-updater.js';
+import { GitHubGraphQLClient } from './github-graphql-client.js';
+import type { UserStoryForSync, PushSyncResult } from './github-push-sync.js';
+import type { FieldSyncResult } from './github-field-sync.js';
+import type { GitHubSyncMetadata } from '../../../../../src/core/types/sync-profile.js';
+
+export interface SyncOrchestratorConfig {
+  owner: string;
+  repo: string;
+  token?: string;
+  dryRun?: boolean;
+  projectV2Enabled?: boolean;
+  projectV2Number?: number;
+  projectV2Id?: string;
+  boardName?: string;
+  statusFieldMapping?: Record<string, string>;
+  priorityFieldMapping?: Record<string, string>;
+}
+
+export interface ProjectV2Result {
+  projectId: string;
+  projectNumber: number;
+  itemIds: string[];
+  fieldSyncResult: FieldSyncResult;
+}
+
+export interface SyncOrchestratorResult {
+  pushResult: PushSyncResult;
+  projectV2Result?: ProjectV2Result;
+  frontmatterResult: GitHubSyncMetadata;
+}
+
+export class GitHubSyncOrchestrator {
+  private config: SyncOrchestratorConfig;
+
+  constructor(config: SyncOrchestratorConfig) {
+    this.config = config;
+  }
+
+  /**
+   * Run the full sync flow for a spec.
+   */
+  async syncSpec(
+    specPath: string,
+    userStories: UserStoryForSync[],
+  ): Promise<SyncOrchestratorResult> {
+    // Step 1: Push sync — create/update GitHub issues
+    const pushResult = await pushSyncUserStories(userStories, {
+      owner: this.config.owner,
+      repo: this.config.repo,
+      token: this.config.token,
+      dryRun: this.config.dryRun,
+    });
+
+    // Step 2: Projects V2 (optional, skip in dry run)
+    let projectV2Result: ProjectV2Result | undefined;
+
+    if (this.config.projectV2Enabled && !this.config.dryRun) {
+      projectV2Result = await this.syncProjectV2(pushResult, userStories);
+    }
+
+    // Step 3: Update spec frontmatter
+    const frontmatterOptions: { projectV2Id?: string; projectV2Number?: number } = {};
+    if (projectV2Result) {
+      frontmatterOptions.projectV2Id = projectV2Result.projectId;
+      frontmatterOptions.projectV2Number = projectV2Result.projectNumber;
+    }
+
+    const frontmatterResult = await updateSpecFrontmatter(
+      specPath,
+      pushResult,
+      frontmatterOptions,
+    );
+
+    return {
+      pushResult,
+      projectV2Result,
+      frontmatterResult,
+    };
+  }
+
+  private async syncProjectV2(
+    pushResult: PushSyncResult,
+    userStories: UserStoryForSync[],
+  ): Promise<ProjectV2Result> {
+    const graphqlClient = new GitHubGraphQLClient(this.config.token);
+
+    // Find or create the Projects V2 board
+    const boardResolver = new GitHubBoardResolverV2(graphqlClient, {
+      owner: this.config.owner,
+      projectV2Number: this.config.projectV2Number,
+      projectV2Id: this.config.projectV2Id,
+    });
+
+    const boardName = this.config.boardName || 'SpecWeave Sync Board';
+    const project = await boardResolver.findOrCreateProject(boardName);
+
+    // Collect issue node IDs from created issues
+    const nodeIds = pushResult.created
+      .filter(item => item.issueNodeId)
+      .map(item => item.issueNodeId);
+
+    // Add issues to project
+    const itemIds = await boardResolver.addIssuesToProject(project.id, nodeIds);
+
+    // Build a map from nodeId → user story for field sync
+    const nodeIdToStory = new Map<string, UserStoryForSync>();
+    for (const created of pushResult.created) {
+      if (created.issueNodeId) {
+        const story = userStories.find(s => s.id === created.userStoryId);
+        if (story) {
+          nodeIdToStory.set(created.issueNodeId, story);
+        }
+      }
+    }
+
+    // Sync Status and Priority fields
+    const fieldSync = new GitHubFieldSync(graphqlClient, {
+      projectId: project.id,
+      statusFieldMapping: this.config.statusFieldMapping,
+      priorityFieldMapping: this.config.priorityFieldMapping,
+    });
+
+    const fieldSyncItems = itemIds.map((itemId, idx) => {
+      const nodeId = nodeIds[idx];
+      const story = nodeId ? nodeIdToStory.get(nodeId) : undefined;
+      return {
+        itemId,
+        status: story?.status,
+        priority: story?.priority,
+      };
+    });
+
+    const fieldSyncResult = await fieldSync.syncItemFields(fieldSyncItems);
+
+    return {
+      projectId: project.id,
+      projectNumber: project.number,
+      itemIds,
+      fieldSyncResult,
+    };
+  }
+}

package/plugins/specweave/lib/integrations/github/github-us-auto-closer.js

@@ -0,0 +1,190 @@
+import { readFile } from "fs/promises";
+import { existsSync } from "fs";
+import * as path from "path";
+import { execFileNoThrow } from "../../../../../src/utils/execFileNoThrow.js";
+async function autoCloseCompletedUserStories(incrementId, affectedUSIds, specPath, options) {
+  const result = { closed: [], skipped: [], 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;
+  const execOpts = env ? { env } : {};
+  for (const usId of affectedUSIds) {
+    const acStates = parseACStatesForUS(content, usId);
+    if (acStates.length === 0 || acStates.some((ac) => !ac.completed)) {
+      result.skipped.push({ usId, reason: "incomplete-acs" });
+      continue;
+    }
+    const link = issueLinks[usId];
+    if (!link) {
+      result.skipped.push({ usId, reason: "no-issue-link" });
+      continue;
+    }
+    const issueNum = String(link.issueNumber);
+    const viewResult = await execFileNoThrow(
+      "gh",
+      ["issue", "view", issueNum, "--json", "state", "-R", repoSlug],
+      execOpts
+    );
+    if (viewResult.success) {
+      try {
+        const issueState = JSON.parse(viewResult.stdout);
+        if (issueState.state === "CLOSED") {
+          result.skipped.push({ usId, reason: "already-closed" });
+          continue;
+        }
+      } catch {
+      }
+    }
+    const commentBody = buildCompletionComment(incrementId, usId, acStates);
+    await execFileNoThrow(
+      "gh",
+      ["issue", "comment", issueNum, "--body", commentBody, "-R", repoSlug],
+      execOpts
+    );
+    const closeResult = await execFileNoThrow(
+      "gh",
+      ["issue", "close", issueNum, "-R", repoSlug],
+      execOpts
+    );
+    if (closeResult.success) {
+      await ensureLabelExists("status:completed", repoSlug, execOpts, {
+        color: "6f42c1",
+        description: "Completed work item"
+      });
+      await execFileNoThrow(
+        "gh",
+        ["issue", "edit", issueNum, "--remove-label", "status:active", "--add-label", "status:completed", "-R", repoSlug],
+        execOpts
+      );
+      result.closed.push({ usId, issueNumber: link.issueNumber });
+    } else {
+      result.errors.push({
+        usId,
+        error: closeResult.stderr || "Unknown error closing issue"
+      });
+    }
+  }
+  return result;
+}
+function buildCompletionComment(incrementId, usId, acStates) {
+  const total = acStates.length;
+  let comment = `**All acceptance criteria completed** \u2014 ${usId} (Increment ${incrementId})
+
+`;
+  comment += `**Status**: ${total}/${total} ACs complete (100%)
+
+`;
+  comment += `**Completed**:
+`;
+  for (const ac of acStates) {
+    comment += `- [x] **${ac.id}**: ${ac.description}
+`;
+  }
+  comment += "\n";
+  comment += `---
+`;
+  comment += `Auto-closed by SpecWeave | ${(/* @__PURE__ */ new Date()).toISOString().split("T")[0]}
+`;
+  return comment;
+}
+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;
+}
+async function ensureLabelExists(labelName, repoSlug, execOpts, defaults) {
+  const checkResult = await execFileNoThrow(
+    "gh",
+    ["label", "list", "--repo", repoSlug, "--search", labelName, "--json", "name", "--jq", ".[].name"],
+    execOpts
+  );
+  if (checkResult.success) {
+    const existing = (checkResult.stdout || "").trim().split("\n").filter(Boolean);
+    if (existing.some((name) => name === labelName)) {
+      return;
+    }
+  }
+  const createResult = await execFileNoThrow(
+    "gh",
+    ["label", "create", labelName, "--repo", repoSlug, "--color", defaults.color, "--description", defaults.description, "--force"],
+    execOpts
+  );
+  if (!createResult.success) {
+    console.warn(`\u26A0\uFE0F  Could not create label "${labelName}": ${createResult.stderr || "unknown error"} (continuing without label)`);
+  }
+}
+function buildACPrefix(usId) {
+  const compoundMatch = usId.match(/^US-([A-Z]+)-(\d+)$/);
+  if (compoundMatch) {
+    return `AC-${compoundMatch[1]}-US${parseInt(compoundMatch[2], 10)}-`;
+  }
+  const simpleMatch = usId.match(/^US-(\d+)$/);
+  if (simpleMatch) {
+    return `AC-US${parseInt(simpleMatch[1], 10)}-`;
+  }
+  const fallback = usId.match(/(\d+)$/);
+  const num = fallback ? parseInt(fallback[1], 10) : 0;
+  return `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;
+}
+export {
+  autoCloseCompletedUserStories
+};

package/plugins/specweave/lib/integrations/github/github-us-auto-closer.ts

@@ -0,0 +1,313 @@
+/**
+ * GitHub US Auto-Closer — Closes GitHub issues when all ACs are complete
+ *
+ * For each affected user story, checks if ALL acceptance criteria are
+ * marked complete in spec.md. If so, posts a completion comment and
+ * closes the associated GitHub issue.
+ *
+ * @module github-us-auto-closer
+ */
+
+import { readFile } from 'fs/promises';
+import { existsSync } from 'fs';
+import * as path from 'path';
+import { execFileNoThrow } from '../../../../../src/utils/execFileNoThrow.js';
+
+export interface AutoCloseOptions {
+  owner: string;
+  repo: string;
+  token?: string;
+}
+
+export interface AutoCloseResult {
+  closed: Array<{ usId: string; issueNumber: number }>;
+  skipped: Array<{ usId: string; reason: string }>;
+  errors: Array<{ usId: string; error: string }>;
+}
+
+interface ParsedACState {
+  id: string;
+  description: string;
+  completed: boolean;
+}
+
+interface ParsedUSIssueLink {
+  issueNumber: number;
+  issueUrl: string;
+}
+
+/**
+ * Auto-close GitHub issues for user stories with all ACs complete.
+ *
+ * For each affected US:
+ * 1. Parse AC states from spec.md
+ * 2. Skip if not all ACs complete
+ * 3. Look up GitHub issue link from frontmatter
+ * 4. Check if issue already closed (idempotent)
+ * 5. Post completion comment
+ * 6. Close issue via `gh issue close`
+ *
+ * Never throws — all errors captured in result.errors.
+ */
+export async function autoCloseCompletedUserStories(
+  incrementId: string,
+  affectedUSIds: string[],
+  specPath: string,
+  options: AutoCloseOptions,
+): Promise<AutoCloseResult> {
+  const result: AutoCloseResult = { closed: [], skipped: [], 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;
+  const execOpts = env ? { env } : {};
+
+  for (const usId of affectedUSIds) {
+    const acStates = parseACStatesForUS(content, usId);
+
+    // Skip if not all ACs complete
+    if (acStates.length === 0 || acStates.some(ac => !ac.completed)) {
+      result.skipped.push({ usId, reason: 'incomplete-acs' });
+      continue;
+    }
+
+    // Skip if no issue link
+    const link = issueLinks[usId];
+    if (!link) {
+      result.skipped.push({ usId, reason: 'no-issue-link' });
+      continue;
+    }
+
+    const issueNum = String(link.issueNumber);
+
+    // Check if already closed (idempotent)
+    const viewResult = await execFileNoThrow(
+      'gh',
+      ['issue', 'view', issueNum, '--json', 'state', '-R', repoSlug],
+      execOpts,
+    );
+
+    if (viewResult.success) {
+      try {
+        const issueState = JSON.parse(viewResult.stdout);
+        if (issueState.state === 'CLOSED') {
+          result.skipped.push({ usId, reason: 'already-closed' });
+          continue;
+        }
+      } catch {
+        // Parse error — proceed with close attempt
+      }
+    }
+
+    // Post completion comment
+    const commentBody = buildCompletionComment(incrementId, usId, acStates);
+    await execFileNoThrow(
+      'gh',
+      ['issue', 'comment', issueNum, '--body', commentBody, '-R', repoSlug],
+      execOpts,
+    );
+
+    // Close the issue
+    const closeResult = await execFileNoThrow(
+      'gh',
+      ['issue', 'close', issueNum, '-R', repoSlug],
+      execOpts,
+    );
+
+    if (closeResult.success) {
+      // Ensure required labels exist before applying them
+      await ensureLabelExists('status:completed', repoSlug, execOpts, {
+        color: '6f42c1',
+        description: 'Completed work item',
+      });
+
+      // Update labels: remove status:active, add status:completed
+      await execFileNoThrow(
+        'gh',
+        ['issue', 'edit', issueNum, '--remove-label', 'status:active', '--add-label', 'status:completed', '-R', repoSlug],
+        execOpts,
+      );
+      result.closed.push({ usId, issueNumber: link.issueNumber });
+    } else {
+      result.errors.push({
+        usId,
+        error: closeResult.stderr || 'Unknown error closing issue',
+      });
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Build a completion comment for a fully-complete user story.
+ */
+function buildCompletionComment(
+  incrementId: string,
+  usId: string,
+  acStates: ParsedACState[],
+): string {
+  const total = acStates.length;
+
+  let comment = `**All acceptance criteria completed** — ${usId} (Increment ${incrementId})\n\n`;
+  comment += `**Status**: ${total}/${total} ACs complete (100%)\n\n`;
+
+  comment += `**Completed**:\n`;
+  for (const ac of acStates) {
+    comment += `- [x] **${ac.id}**: ${ac.description}\n`;
+  }
+  comment += '\n';
+
+  comment += `---\n`;
+  comment += `Auto-closed by SpecWeave | ${new Date().toISOString().split('T')[0]}\n`;
+
+  return comment;
+}
+
+/**
+ * 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) {
+          links[usId] = {
+            issueNumber: issueData.issueNumber,
+            issueUrl: issueData.issueUrl || '',
+          };
+        }
+      }
+    }
+  } catch {
+    // Graceful fallback: return empty if metadata.json is missing or invalid
+  }
+
+  return links;
+}
+
+/**
+ * Ensure a label exists in the repo before applying it.
+ * Creates the label if missing; logs a warning and continues on permission errors.
+ */
+async function ensureLabelExists(
+  labelName: string,
+  repoSlug: string,
+  execOpts: { env?: Record<string, string> },
+  defaults: { color: string; description: string },
+): Promise<void> {
+  // Check if label exists
+  const checkResult = await execFileNoThrow(
+    'gh',
+    ['label', 'list', '--repo', repoSlug, '--search', labelName, '--json', 'name', '--jq', '.[].name'],
+    execOpts,
+  );
+
+  if (checkResult.success) {
+    const existing = (checkResult.stdout || '').trim().split('\n').filter(Boolean);
+    if (existing.some(name => name === labelName)) {
+      return; // Label already exists
+    }
+  }
+
+  // Create the label
+  const createResult = await execFileNoThrow(
+    'gh',
+    ['label', 'create', labelName, '--repo', repoSlug, '--color', defaults.color, '--description', defaults.description, '--force'],
+    execOpts,
+  );
+
+  if (!createResult.success) {
+    // Permission error or other failure — log warning and continue
+    console.warn(`⚠️  Could not create label "${labelName}": ${createResult.stderr || 'unknown error'} (continuing without label)`);
+  }
+}
+
+/**
+ * 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 compoundMatch = usId.match(/^US-([A-Z]+)-(\d+)$/);
+  if (compoundMatch) {
+    return `AC-${compoundMatch[1]}-US${parseInt(compoundMatch[2], 10)}-`;
+  }
+  const simpleMatch = usId.match(/^US-(\d+)$/);
+  if (simpleMatch) {
+    return `AC-US${parseInt(simpleMatch[1], 10)}-`;
+  }
+  const fallback = usId.match(/(\d+)$/);
+  const num = fallback ? parseInt(fallback[1], 10) : 0;
+  return `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;
+}