specweave 1.0.235 → 1.0.239

package/plugins/specweave-github/lib/github-spec-frontmatter-updater.ts

@@ -0,0 +1,180 @@
+/**
+ * GitHub Spec Frontmatter Updater
+ *
+ * Updates spec.md YAML frontmatter after push sync to record
+ * GitHub issue links for each user story.
+ *
+ * @module github-spec-frontmatter-updater
+ */
+
+import { readFile, writeFile } from 'fs/promises';
+import type { PushSyncResult } from './github-push-sync.js';
+import type { GitHubSyncMetadata, GitHubUserStoryLink } from '../../../src/core/types/sync-profile.js';
+
+/**
+ * Update spec.md frontmatter with GitHub sync results.
+ *
+ * Reads the spec file, parses YAML frontmatter, merges sync results
+ * into the externalLinks.github section, and writes back.
+ */
+export async function updateSpecFrontmatter(
+  specPath: string,
+  syncResult: PushSyncResult,
+  options?: { projectV2Id?: string; projectV2Number?: number },
+): Promise<GitHubSyncMetadata> {
+  const content = await readFile(specPath, 'utf-8');
+
+  // Parse frontmatter
+  const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
+  let frontmatter: Record<string, unknown> = {};
+  let body = content;
+
+  if (fmMatch) {
+    frontmatter = parseYamlSimple(fmMatch[1]);
+    body = content.slice(fmMatch[0].length);
+  }
+
+  // Get existing externalLinks
+  const externalLinks = (frontmatter.externalLinks ?? {}) as Record<string, unknown>;
+  const existingGithub = (externalLinks.github ?? {}) as Record<string, unknown>;
+  const existingUserStories = (existingGithub.userStories ?? {}) as Record<string, GitHubUserStoryLink>;
+
+  // Build updated user stories map (preserve existing)
+  const userStories: Record<string, GitHubUserStoryLink> = { ...existingUserStories };
+  const now = new Date().toISOString();
+
+  // Merge created issues
+  for (const item of syncResult.created) {
+    userStories[item.userStoryId] = {
+      issueNumber: item.issueNumber,
+      issueUrl: item.issueUrl,
+      issueNodeId: item.issueNodeId,
+      syncedAt: now,
+    };
+  }
+
+  // Merge updated issues (preserve existing nodeId)
+  for (const item of syncResult.updated) {
+    const existing = userStories[item.userStoryId];
+    userStories[item.userStoryId] = {
+      issueNumber: item.issueNumber,
+      issueUrl: item.issueUrl,
+      issueNodeId: existing?.issueNodeId,
+      syncedAt: now,
+    };
+  }
+
+  // Determine sync status
+  const syncStatus: GitHubSyncMetadata['syncStatus'] =
+    syncResult.errors.length > 0 ? 'dirty' : 'synced';
+
+  // Build metadata result
+  const metadata: GitHubSyncMetadata = {
+    syncStatus,
+    userStories,
+  };
+
+  // ProjectV2 info: prefer options, fall back to existing
+  if (options?.projectV2Id) {
+    metadata.projectV2Id = options.projectV2Id;
+  } else if (existingGithub.projectV2Id) {
+    metadata.projectV2Id = existingGithub.projectV2Id as string;
+  }
+
+  if (options?.projectV2Number) {
+    metadata.projectV2Number = options.projectV2Number;
+  } else if (existingGithub.projectV2Number) {
+    metadata.projectV2Number = existingGithub.projectV2Number as number;
+  }
+
+  // Update frontmatter
+  externalLinks.github = metadata;
+  frontmatter.externalLinks = externalLinks;
+
+  // Write back
+  const newFrontmatter = stringifyYaml(frontmatter);
+  const newContent = `---\n${newFrontmatter}\n---${body}`;
+  await writeFile(specPath, newContent, 'utf-8');
+
+  return metadata;
+}
+
+/**
+ * Simple YAML parser for spec frontmatter.
+ * Handles nested objects, strings, numbers, booleans, null.
+ */
+function parseYamlSimple(yaml: string): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  const lines = yaml.split('\n');
+  const stack: Array<{ obj: Record<string, unknown>; indent: number }> = [
+    { obj: result, indent: -1 },
+  ];
+
+  for (const line of lines) {
+    if (!line.trim() || line.trim().startsWith('#')) continue;
+
+    const indent = line.search(/\S/);
+    const trimmed = line.trim();
+    const colonIdx = trimmed.indexOf(':');
+    if (colonIdx === -1) continue;
+
+    const key = trimmed.slice(0, colonIdx).trim();
+    const rawValue = trimmed.slice(colonIdx + 1).trim();
+
+    // Pop stack to correct indent level
+    while (stack.length > 1 && stack[stack.length - 1].indent >= indent) {
+      stack.pop();
+    }
+
+    const parent = stack[stack.length - 1].obj;
+
+    if (rawValue === '' || rawValue === undefined) {
+      // Nested object
+      const child: Record<string, unknown> = {};
+      parent[key] = child;
+      stack.push({ obj: child, indent });
+    } else {
+      parent[key] = parseYamlValue(rawValue);
+    }
+  }
+
+  return result;
+}
+
+function parseYamlValue(raw: string): unknown {
+  if (raw === 'null') return null;
+  if (raw === 'true') return true;
+  if (raw === 'false') return false;
+  if (/^-?\d+$/.test(raw)) return parseInt(raw, 10);
+  if (/^-?\d+\.\d+$/.test(raw)) return parseFloat(raw);
+  if ((raw.startsWith('"') && raw.endsWith('"')) ||
+      (raw.startsWith("'") && raw.endsWith("'"))) {
+    return raw.slice(1, -1);
+  }
+  return raw;
+}
+
+/**
+ * Simple YAML stringifier.
+ */
+function stringifyYaml(obj: Record<string, unknown>, indent = 0): string {
+  const prefix = '  '.repeat(indent);
+  const parts: string[] = [];
+
+  for (const [key, value] of Object.entries(obj)) {
+    if (value === null || value === undefined) {
+      parts.push(`${prefix}${key}: null`);
+    } else if (typeof value === 'object' && !Array.isArray(value)) {
+      parts.push(`${prefix}${key}:`);
+      parts.push(stringifyYaml(value as Record<string, unknown>, indent + 1));
+    } else if (typeof value === 'string') {
+      parts.push(`${prefix}${key}: "${value}"`);
+    } else if (typeof value === 'boolean' || typeof value === 'number') {
+      parts.push(`${prefix}${key}: ${value}`);
+    } else {
+      parts.push(`${prefix}${key}: ${JSON.stringify(value)}`);
+    }
+  }
+
+  return parts.join('\n');
+}

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

@@ -0,0 +1,84 @@
+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";
+class GitHubSyncOrchestrator {
+  constructor(config) {
+    this.config = config;
+  }
+  /**
+   * Run the full sync flow for a spec.
+   */
+  async syncSpec(specPath, userStories) {
+    const pushResult = await pushSyncUserStories(userStories, {
+      owner: this.config.owner,
+      repo: this.config.repo,
+      token: this.config.token,
+      dryRun: this.config.dryRun
+    });
+    let projectV2Result;
+    if (this.config.projectV2Enabled && !this.config.dryRun) {
+      projectV2Result = await this.syncProjectV2(pushResult, userStories);
+    }
+    const frontmatterOptions = {};
+    if (projectV2Result) {
+      frontmatterOptions.projectV2Id = projectV2Result.projectId;
+      frontmatterOptions.projectV2Number = projectV2Result.projectNumber;
+    }
+    const frontmatterResult = await updateSpecFrontmatter(
+      specPath,
+      pushResult,
+      frontmatterOptions
+    );
+    return {
+      pushResult,
+      projectV2Result,
+      frontmatterResult
+    };
+  }
+  async syncProjectV2(pushResult, userStories) {
+    const graphqlClient = new GitHubGraphQLClient(this.config.token);
+    const boardResolver = new GitHubBoardResolverV2(graphqlClient, {
+      owner: this.config.owner,
+      projectV2Number: this.config.projectV2Number,
+      projectV2Id: this.config.projectV2Id
+    });
+    const project = await boardResolver.findOrCreateProject("SpecWeave Sync Board");
+    const nodeIds = pushResult.created.filter((item) => item.issueNodeId).map((item) => item.issueNodeId);
+    const itemIds = await boardResolver.addIssuesToProject(project.id, nodeIds);
+    const nodeIdToStory = /* @__PURE__ */ new Map();
+    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);
+        }
+      }
+    }
+    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) : void 0;
+      return {
+        itemId,
+        status: story?.status,
+        priority: story?.priority
+      };
+    });
+    const fieldSyncResult = await fieldSync.syncItemFields(fieldSyncItems);
+    return {
+      projectId: project.id,
+      projectNumber: project.number,
+      itemIds,
+      fieldSyncResult
+    };
+  }
+}
+export {
+  GitHubSyncOrchestrator
+};

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

@@ -0,0 +1,156 @@
+/**
+ * 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;
+  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 project = await boardResolver.findOrCreateProject('SpecWeave Sync Board');
+
+    // 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

@@ -0,0 +1,134 @@
+import { readFile } from "fs/promises";
+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 = parseIssueLinks(content);
+  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) {
+      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;
+}
+function parseIssueLinks(content) {
+  const links = {};
+  const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!fmMatch) return links;
+  const frontmatter = fmMatch[1];
+  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;
+}
+function parseACStatesForUS(content, usId) {
+  const states = [];
+  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;
+}
+export {
+  autoCloseCompletedUserStories
+};