specweave 1.0.506 → 1.0.508

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

@@ -1,158 +0,0 @@
-/**
- * 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-github/lib/github-us-auto-closer.js

@@ -1,190 +0,0 @@
-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-github/lib/github-us-auto-closer.ts

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