specweave 1.0.235 → 1.0.239

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

@@ -0,0 +1,245 @@
+/**
+ * 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 { execFileNoThrow } from '../../../src/utils/execFileNoThrow.js';
+import { pushSyncUserStories } from './github-push-sync.js';
+import type { UserStoryForSync } from './github-push-sync.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 = parseIssueLinks(content);
+  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);
+    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',
+      });
+    }
+
+    // Targeted push-sync: update issue body with current AC states
+    const usForSync = buildUserStoryForSync(content, usId, acStates, incrementId);
+    if (usForSync) {
+      try {
+        await pushSyncUserStories([usForSync], {
+          owner: options.owner,
+          repo: options.repo,
+          token: options.token,
+        });
+      } catch {
+        // Push-sync failure is non-blocking
+      }
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Parse issue links from spec.md YAML frontmatter.
+ * Extracts externalLinks.github.userStories entries.
+ */
+function parseIssueLinks(content: string): Record<string, ParsedUSIssueLink> {
+  const links: Record<string, ParsedUSIssueLink> = {};
+
+  const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!fmMatch) return links;
+
+  const frontmatter = fmMatch[1];
+
+  // Parse userStories section from YAML frontmatter
+  const usBlockMatch = frontmatter.match(/userStories:\s*\n((?:\s{6,}[\s\S]*?)(?=\n\s{0,3}\S|$))/);
+  if (!usBlockMatch) return links;
+
+  const usBlock = usBlockMatch[1];
+  const usEntries = usBlock.match(/^\s+(US-\d+):\s*\n((?:\s+\w[\s\S]*?)(?=\n\s+US-|\s*$))/gm);
+
+  if (!usEntries) return links;
+
+  for (const entry of usEntries) {
+    const idMatch = entry.match(/(US-\d+):/);
+    const numMatch = entry.match(/issueNumber:\s*(\d+)/);
+    const urlMatch = entry.match(/issueUrl:\s*"([^"]+)"/);
+
+    if (idMatch && numMatch) {
+      links[idMatch[1]] = {
+        issueNumber: parseInt(numMatch[1], 10),
+        issueUrl: urlMatch ? urlMatch[1] : '',
+      };
+    }
+  }
+
+  return links;
+}
+
+/**
+ * Extract AC states for a specific user story from spec.md content.
+ */
+function parseACStatesForUS(content: string, usId: string): ParsedACState[] {
+  const states: ParsedACState[] = [];
+  // AC IDs use unpadded US number: US-001 → AC-US1-XX
+  const usNum = String(parseInt(usId.replace('US-', ''), 10));
+
+  const acPattern = new RegExp(
+    `- \\[([ x])\\] \\*\\*AC-US${usNum}-(\\d+)\\*\\*:\\s*(.+)`,
+    'g',
+  );
+
+  let match;
+  while ((match = acPattern.exec(content)) !== null) {
+    states.push({
+      id: `AC-US${usNum}-${match[2]}`,
+      description: match[3].trim(),
+      completed: match[1] === 'x',
+    });
+  }
+
+  return states;
+}
+
+/**
+ * Build a UserStoryForSync object for targeted push-sync.
+ */
+function buildUserStoryForSync(
+  content: string,
+  usId: string,
+  acStates: ParsedACState[],
+  incrementId: string,
+): UserStoryForSync | null {
+  // Extract US title from content
+  const usNum = String(parseInt(usId.replace('US-', ''), 10)).padStart(3, '0');
+  const titleMatch = content.match(new RegExp(`### US-${usNum}:\\s*(.+)`));
+  const title = titleMatch ? titleMatch[1].trim() : usId;
+
+  return {
+    id: usId,
+    title,
+    description: '',
+    priority: 'P1',
+    status: 'in-progress',
+    acceptanceCriteria: acStates.map(ac => ({
+      id: ac.id,
+      description: ac.description,
+      completed: ac.completed,
+    })),
+    specId: incrementId,
+  };
+}
+
+/**
+ * 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;
+}

package/plugins/specweave-github/lib/github-batch-sync.js

@@ -0,0 +1,93 @@
+import { glob } from "glob";
+import { readFile } from "fs/promises";
+import { join } from "path";
+import { GitHubSyncOrchestrator } from "./github-sync-orchestrator.js";
+async function batchSyncAllSpecs(config) {
+  const specsDir = join(config.workspaceRoot, ".specweave/docs/internal/specs");
+  const specFiles = await glob("**/spec-*.md", { cwd: specsDir });
+  const result = {
+    specsProcessed: 0,
+    specsFailed: 0,
+    totalIssuesCreated: 0,
+    totalIssuesUpdated: 0,
+    errors: [],
+    summary: ""
+  };
+  if (specFiles.length === 0) {
+    result.summary = "No specs found";
+    return result;
+  }
+  const orchestrator = new GitHubSyncOrchestrator({
+    owner: config.owner,
+    repo: config.repo,
+    token: config.token,
+    dryRun: config.dryRun,
+    projectV2Enabled: config.projectV2Enabled,
+    projectV2Number: config.projectV2Number,
+    projectV2Id: config.projectV2Id,
+    statusFieldMapping: config.statusFieldMapping,
+    priorityFieldMapping: config.priorityFieldMapping
+  });
+  for (const specFile of specFiles) {
+    const specPath = join(specsDir, specFile);
+    result.specsProcessed++;
+    try {
+      const content = await readFile(specPath, "utf-8");
+      const userStories = parseUserStoriesFromSpec(content);
+      const syncResult = await orchestrator.syncSpec(specPath, userStories);
+      result.totalIssuesCreated += syncResult.pushResult.created.length;
+      result.totalIssuesUpdated += syncResult.pushResult.updated.length;
+    } catch (err) {
+      result.specsFailed++;
+      result.errors.push({
+        specPath,
+        error: err instanceof Error ? err.message : String(err)
+      });
+    }
+  }
+  const synced = result.specsProcessed - result.specsFailed;
+  result.summary = `Synced ${synced}/${result.specsProcessed} specs, ${result.totalIssuesCreated} issues created, ${result.totalIssuesUpdated} updated`;
+  return result;
+}
+const US_HEADER_RE = /^###?\s+(US-\d{3,}E?):\s*(.+)$/;
+const AC_CHECKBOX_RE = /^-\s+\[([ xX])\]\s+\*\*(?<acId>AC-US\d+E?-\d{2})\*\*:\s*(?<desc>.+)$/;
+const PRIORITY_RE = /\*\*Priority\*\*:\s*(P[0-3])/;
+function parseUserStoriesFromSpec(content) {
+  const lines = content.split("\n");
+  const userStories = [];
+  let current = null;
+  for (const line of lines) {
+    const usMatch = line.match(US_HEADER_RE);
+    if (usMatch) {
+      if (current) userStories.push(current);
+      current = {
+        id: usMatch[1],
+        title: usMatch[2],
+        description: "",
+        priority: "P3",
+        status: "planned",
+        acceptanceCriteria: []
+      };
+      continue;
+    }
+    if (!current) continue;
+    const acMatch = line.match(AC_CHECKBOX_RE);
+    if (acMatch?.groups) {
+      current.acceptanceCriteria.push({
+        id: acMatch.groups.acId,
+        description: acMatch.groups.desc.trim(),
+        completed: acMatch[1] !== " "
+      });
+      continue;
+    }
+    const prioMatch = line.match(PRIORITY_RE);
+    if (prioMatch) {
+      current.priority = prioMatch[1];
+    }
+  }
+  if (current) userStories.push(current);
+  return userStories;
+}
+export {
+  batchSyncAllSpecs
+};

package/plugins/specweave-github/lib/github-batch-sync.ts

@@ -0,0 +1,152 @@
+/**
+ * GitHub Batch Sync — Sync all specs in workspace
+ *
+ * Discovers all spec files and syncs them sequentially
+ * using the GitHubSyncOrchestrator.
+ *
+ * @module github-batch-sync
+ */
+
+import { glob } from 'glob';
+import { readFile } from 'fs/promises';
+import { join } from 'path';
+import { GitHubSyncOrchestrator } from './github-sync-orchestrator.js';
+import type { UserStoryForSync } from './github-push-sync.js';
+
+export interface BatchSyncConfig {
+  owner: string;
+  repo: string;
+  workspaceRoot: string;
+  token?: string;
+  dryRun?: boolean;
+  projectV2Enabled?: boolean;
+  projectV2Number?: number;
+  projectV2Id?: string;
+  statusFieldMapping?: Record<string, string>;
+  priorityFieldMapping?: Record<string, string>;
+}
+
+export interface BatchSyncResult {
+  specsProcessed: number;
+  specsFailed: number;
+  totalIssuesCreated: number;
+  totalIssuesUpdated: number;
+  errors: Array<{ specPath: string; error: string }>;
+  summary: string;
+}
+
+/**
+ * Discover all specs and sync them sequentially.
+ */
+export async function batchSyncAllSpecs(config: BatchSyncConfig): Promise<BatchSyncResult> {
+  const specsDir = join(config.workspaceRoot, '.specweave/docs/internal/specs');
+
+  // Discover specs
+  const specFiles = await glob('**/spec-*.md', { cwd: specsDir });
+
+  const result: BatchSyncResult = {
+    specsProcessed: 0,
+    specsFailed: 0,
+    totalIssuesCreated: 0,
+    totalIssuesUpdated: 0,
+    errors: [],
+    summary: '',
+  };
+
+  if (specFiles.length === 0) {
+    result.summary = 'No specs found';
+    return result;
+  }
+
+  // Create orchestrator
+  const orchestrator = new GitHubSyncOrchestrator({
+    owner: config.owner,
+    repo: config.repo,
+    token: config.token,
+    dryRun: config.dryRun,
+    projectV2Enabled: config.projectV2Enabled,
+    projectV2Number: config.projectV2Number,
+    projectV2Id: config.projectV2Id,
+    statusFieldMapping: config.statusFieldMapping,
+    priorityFieldMapping: config.priorityFieldMapping,
+  });
+
+  // Sync each spec sequentially
+  for (const specFile of specFiles) {
+    const specPath = join(specsDir, specFile);
+    result.specsProcessed++;
+
+    try {
+      const content = await readFile(specPath, 'utf-8');
+      const userStories = parseUserStoriesFromSpec(content);
+      const syncResult = await orchestrator.syncSpec(specPath, userStories);
+
+      result.totalIssuesCreated += syncResult.pushResult.created.length;
+      result.totalIssuesUpdated += syncResult.pushResult.updated.length;
+    } catch (err) {
+      result.specsFailed++;
+      result.errors.push({
+        specPath,
+        error: err instanceof Error ? err.message : String(err),
+      });
+    }
+  }
+
+  const synced = result.specsProcessed - result.specsFailed;
+  result.summary = `Synced ${synced}/${result.specsProcessed} specs, ${result.totalIssuesCreated} issues created, ${result.totalIssuesUpdated} updated`;
+
+  return result;
+}
+
+// US header: ### US-001: Title
+const US_HEADER_RE = /^###?\s+(US-\d{3,}E?):\s*(.+)$/;
+// AC checkbox: - [x] **AC-US1-01**: Description
+const AC_CHECKBOX_RE = /^-\s+\[([ xX])\]\s+\*\*(?<acId>AC-US\d+E?-\d{2})\*\*:\s*(?<desc>.+)$/;
+// Priority: **Priority**: P1
+const PRIORITY_RE = /\*\*Priority\*\*:\s*(P[0-3])/;
+
+/**
+ * Parse user stories from spec.md content.
+ */
+function parseUserStoriesFromSpec(content: string): UserStoryForSync[] {
+  const lines = content.split('\n');
+  const userStories: UserStoryForSync[] = [];
+  let current: UserStoryForSync | null = null;
+
+  for (const line of lines) {
+    const usMatch = line.match(US_HEADER_RE);
+    if (usMatch) {
+      if (current) userStories.push(current);
+      current = {
+        id: usMatch[1],
+        title: usMatch[2],
+        description: '',
+        priority: 'P3',
+        status: 'planned',
+        acceptanceCriteria: [],
+      };
+      continue;
+    }
+
+    if (!current) continue;
+
+    const acMatch = line.match(AC_CHECKBOX_RE);
+    if (acMatch?.groups) {
+      current.acceptanceCriteria.push({
+        id: acMatch.groups.acId,
+        description: acMatch.groups.desc.trim(),
+        completed: acMatch[1] !== ' ',
+      });
+      continue;
+    }
+
+    const prioMatch = line.match(PRIORITY_RE);
+    if (prioMatch) {
+      current.priority = prioMatch[1];
+    }
+  }
+
+  if (current) userStories.push(current);
+
+  return userStories;
+}

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

@@ -0,0 +1,47 @@
+class GitHubBoardResolverV2 {
+  constructor(client, config) {
+    this.client = client;
+    this.config = config;
+  }
+  /**
+   * Find an existing project or create a new one.
+   *
+   * Priority:
+   * 1. If projectV2Id is configured, use it directly (skip lookup)
+   * 2. If projectV2Number is configured, return with that number
+   * 3. Otherwise, create a new project
+   */
+  async findOrCreateProject(title) {
+    if (this.config.projectV2Id) {
+      return {
+        id: this.config.projectV2Id,
+        number: this.config.projectV2Number || 0
+      };
+    }
+    if (this.config.projectV2Number) {
+      const ownerId2 = await this.client.getOwnerNodeId(this.config.owner);
+      return {
+        id: ownerId2,
+        // Will be resolved to actual project ID during operations
+        number: this.config.projectV2Number
+      };
+    }
+    const ownerId = await this.client.getOwnerNodeId(this.config.owner);
+    return this.client.createProjectV2(ownerId, title);
+  }
+  /**
+   * Add issues (by node ID) to a Projects V2 board.
+   * Returns the project item IDs for each added issue.
+   */
+  async addIssuesToProject(projectId, issueNodeIds) {
+    const itemIds = [];
+    for (const nodeId of issueNodeIds) {
+      const itemId = await this.client.addProjectV2Item(projectId, nodeId);
+      itemIds.push(itemId);
+    }
+    return itemIds;
+  }
+}
+export {
+  GitHubBoardResolverV2
+};

package/plugins/specweave-github/lib/github-board-resolver-v2.ts

@@ -0,0 +1,73 @@
+/**
+ * GitHub Board Resolver V2 — Projects V2 Integration
+ *
+ * Finds or creates GitHub Projects V2 boards and adds issues to them.
+ * Replaces the deprecated V1 Classic Projects board resolver.
+ *
+ * @module github-board-resolver-v2
+ */
+
+import { GitHubGraphQLClient } from './github-graphql-client.js';
+
+export interface BoardResolverConfig {
+  owner: string;
+  projectV2Number?: number;
+  projectV2Id?: string;
+}
+
+export class GitHubBoardResolverV2 {
+  private client: GitHubGraphQLClient;
+  private config: BoardResolverConfig;
+
+  constructor(client: GitHubGraphQLClient, config: BoardResolverConfig) {
+    this.client = client;
+    this.config = config;
+  }
+
+  /**
+   * Find an existing project or create a new one.
+   *
+   * Priority:
+   * 1. If projectV2Id is configured, use it directly (skip lookup)
+   * 2. If projectV2Number is configured, return with that number
+   * 3. Otherwise, create a new project
+   */
+  async findOrCreateProject(title: string): Promise<{ id: string; number: number }> {
+    // If we have a direct project ID, use it
+    if (this.config.projectV2Id) {
+      return {
+        id: this.config.projectV2Id,
+        number: this.config.projectV2Number || 0,
+      };
+    }
+
+    // If we have a project number, look it up by querying the owner
+    if (this.config.projectV2Number) {
+      const ownerId = await this.client.getOwnerNodeId(this.config.owner);
+      // Return the project reference — the number is known, ID will be resolved on first use
+      return {
+        id: ownerId, // Will be resolved to actual project ID during operations
+        number: this.config.projectV2Number,
+      };
+    }
+
+    // No project configured — create a new one
+    const ownerId = await this.client.getOwnerNodeId(this.config.owner);
+    return this.client.createProjectV2(ownerId, title);
+  }
+
+  /**
+   * Add issues (by node ID) to a Projects V2 board.
+   * Returns the project item IDs for each added issue.
+   */
+  async addIssuesToProject(projectId: string, issueNodeIds: string[]): Promise<string[]> {
+    const itemIds: string[] = [];
+
+    for (const nodeId of issueNodeIds) {
+      const itemId = await this.client.addProjectV2Item(projectId, nodeId);
+      itemIds.push(itemId);
+    }
+
+    return itemIds;
+  }
+}

package/plugins/specweave-github/lib/github-conflict-resolver.js

@@ -0,0 +1,90 @@
+class GitHubConflictResolver {
+  constructor(config) {
+    this.statusResolution = config?.defaultStatusResolution ?? "github-wins";
+    this.contentResolution = config?.defaultContentResolution ?? "prompt";
+    this.acResolution = config?.defaultACResolution ?? "github-wins";
+  }
+  /**
+   * Detect conflicts between spec and GitHub states.
+   */
+  detectConflicts(specState, githubState) {
+    const conflicts = [];
+    if (specState.title !== githubState.title) {
+      conflicts.push({
+        field: "title",
+        specValue: specState.title,
+        githubValue: githubState.title,
+        defaultResolution: this.contentResolution
+      });
+    }
+    const githubStatus = githubState.state;
+    const specStatus = specState.status;
+    const statusMismatch = this.isStatusConflict(specStatus, githubStatus);
+    if (statusMismatch) {
+      conflicts.push({
+        field: "status",
+        specValue: specStatus,
+        githubValue: githubStatus,
+        defaultResolution: this.statusResolution
+      });
+    }
+    const ghAcMap = new Map(
+      githubState.acceptanceCriteria.map((ac) => [ac.id, ac.completed])
+    );
+    for (const specAc of specState.acceptanceCriteria) {
+      const ghCompleted = ghAcMap.get(specAc.id);
+      if (ghCompleted !== void 0 && specAc.completed !== ghCompleted) {
+        conflicts.push({
+          field: `ac:${specAc.id}`,
+          specValue: String(specAc.completed),
+          githubValue: String(ghCompleted),
+          defaultResolution: this.acResolution
+        });
+      }
+    }
+    return conflicts;
+  }
+  /**
+   * Resolve all conflicts using their default resolution strategy.
+   */
+  resolveConflicts(conflicts) {
+    return conflicts.map((c) => this.resolveConflict(c));
+  }
+  /**
+   * Resolve a single conflict with optional override.
+   */
+  resolveConflict(conflict, resolution) {
+    const effectiveResolution = resolution ?? conflict.defaultResolution;
+    let resolvedValue;
+    switch (effectiveResolution) {
+      case "github-wins":
+        resolvedValue = conflict.githubValue;
+        break;
+      case "spec-wins":
+        resolvedValue = conflict.specValue;
+        break;
+      case "prompt":
+        resolvedValue = conflict.specValue;
+        break;
+    }
+    return {
+      field: conflict.field,
+      specValue: conflict.specValue,
+      githubValue: conflict.githubValue,
+      resolution: effectiveResolution,
+      resolvedValue,
+      resolvedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+  }
+  /**
+   * Check if spec status and GitHub state represent a conflict.
+   */
+  isStatusConflict(specStatus, githubState) {
+    if (specStatus === "completed" && githubState === "open") return true;
+    if (specStatus !== "completed" && githubState === "closed") return true;
+    return false;
+  }
+}
+export {
+  GitHubConflictResolver
+};