specweave 0.17.16 → 0.17.19

package/plugins/specweave-github/lib/epic-content-builder.js

@@ -0,0 +1,227 @@
+import { readdir, readFile } from "fs/promises";
+import { existsSync } from "fs";
+import * as path from "path";
+import * as yaml from "yaml";
+class EpicContentBuilder {
+  constructor(epicFolder, projectRoot) {
+    this.epicFolder = epicFolder;
+    this.projectRoot = projectRoot;
+  }
+  /**
+   * Build hierarchical GitHub issue body
+   *
+   * Format:
+   * - Epic overview
+   * - User Stories section (checkable, with status + increment)
+   * - Tasks section (grouped by User Story)
+   */
+  async buildIssueBody() {
+    const epicData = await this.readEpicMetadata();
+    const userStories = await this.readUserStories();
+    const overview = this.buildOverviewSection(epicData);
+    const userStoriesSection = this.buildUserStoriesSection(userStories);
+    const tasksSection = this.buildTasksSection(userStories);
+    return `${overview}
+
+---
+
+${userStoriesSection}
+
+---
+
+${tasksSection}
+
+---
+
+\u{1F916} Auto-created by SpecWeave Epic Sync`;
+  }
+  /**
+   * Read Epic FEATURE.md frontmatter
+   */
+  async readEpicMetadata() {
+    const featurePath = path.join(this.epicFolder, "FEATURE.md");
+    const content = await readFile(featurePath, "utf-8");
+    const match = content.match(/^---\n([\s\S]*?)\n---/);
+    if (!match) {
+      throw new Error("FEATURE.md missing YAML frontmatter");
+    }
+    return yaml.parse(match[1]);
+  }
+  /**
+   * Read all user stories from us-*.md files
+   */
+  async readUserStories() {
+    const files = await readdir(this.epicFolder);
+    const usFiles = files.filter((f) => f.startsWith("us-") && f.endsWith(".md"));
+    const userStories = [];
+    for (const file of usFiles.sort()) {
+      const filePath = path.join(this.epicFolder, file);
+      const content = await readFile(filePath, "utf-8");
+      const match = content.match(/^---\n([\s\S]*?)\n---/);
+      if (!match) {
+        console.warn(`   \u26A0\uFE0F  ${file} missing frontmatter, skipping`);
+        continue;
+      }
+      const frontmatter = yaml.parse(match[1]);
+      const bodyContent = content.slice(match[0].length).trim();
+      const incrementMatch = bodyContent.match(/\*\*Increment\*\*:\s*\[([^\]]+)\]/);
+      const increment = incrementMatch ? incrementMatch[1] : null;
+      const tasks = await this.extractTasksForUserStory(
+        frontmatter.id,
+        increment,
+        bodyContent
+      );
+      userStories.push({
+        id: frontmatter.id,
+        title: frontmatter.title,
+        status: this.normalizeStatus(frontmatter.status),
+        increment,
+        tasks
+      });
+    }
+    return userStories;
+  }
+  /**
+   * Extract tasks for a user story from its Implementation section
+   */
+  async extractTasksForUserStory(userStoryId, incrementId, content) {
+    if (!incrementId) {
+      return [];
+    }
+    const incrementFolder = path.join(
+      this.projectRoot,
+      ".specweave",
+      "increments",
+      incrementId
+    );
+    if (!existsSync(incrementFolder)) {
+      console.warn(`   \u26A0\uFE0F  Increment folder not found: ${incrementId}`);
+      return [];
+    }
+    const tasksPath = path.join(incrementFolder, "tasks.md");
+    if (!existsSync(tasksPath)) {
+      console.warn(`   \u26A0\uFE0F  tasks.md not found in ${incrementId}`);
+      return [];
+    }
+    const tasksContent = await readFile(tasksPath, "utf-8");
+    const taskLinkPattern = /- \[([T-\d]+):\s*([^\]]+)\]/g;
+    const taskLinks = [];
+    let match;
+    while ((match = taskLinkPattern.exec(content)) !== null) {
+      taskLinks.push({
+        id: match[1],
+        // e.g., "T-001"
+        title: match[2].trim()
+      });
+    }
+    const tasks = [];
+    for (const taskLink of taskLinks) {
+      const taskPattern = new RegExp(
+        `###\\s+${taskLink.id}:\\s*([^\\n]+)[\\s\\S]*?\\*\\*Status\\*\\*:\\s*\\[([x\\s])\\]`,
+        "i"
+      );
+      const taskMatch = tasksContent.match(taskPattern);
+      const isCompleted = taskMatch ? taskMatch[2] === "x" : false;
+      tasks.push({
+        id: taskLink.id,
+        title: taskLink.title,
+        status: isCompleted,
+        userStoryId
+      });
+    }
+    return tasks;
+  }
+  /**
+   * Build overview section
+   */
+  buildOverviewSection(epic) {
+    return `# [${epic.id}] ${epic.title}
+
+**Status**: ${epic.status}
+**Created**: ${epic.created}
+**Last Updated**: ${epic.last_updated}`;
+  }
+  /**
+   * Build User Stories section
+   */
+  buildUserStoriesSection(userStories) {
+    const total = userStories.length;
+    const completed = userStories.filter((us) => us.status === "complete").length;
+    const percentage = total > 0 ? Math.round(completed / total * 100) : 0;
+    let section = `## User Stories
+
+Progress: ${completed}/${total} user stories complete (${percentage}%)
+
+`;
+    for (const us of userStories) {
+      const checkbox = us.status === "complete" ? "[x]" : "[ ]";
+      const statusEmoji = this.getStatusEmoji(us.status);
+      const incrementLink = us.increment ? `[${us.increment}](../../increments/${us.increment}/)` : "TBD";
+      section += `- ${checkbox} **${us.id}: ${us.title}** (${statusEmoji} ${us.status} | Increment: ${incrementLink})
+`;
+    }
+    return section;
+  }
+  /**
+   * Build Tasks section (grouped by User Story)
+   */
+  buildTasksSection(userStories) {
+    const totalTasks = userStories.reduce((sum, us) => sum + us.tasks.length, 0);
+    const completedTasks = userStories.reduce(
+      (sum, us) => sum + us.tasks.filter((t) => t.status).length,
+      0
+    );
+    const percentage = totalTasks > 0 ? Math.round(completedTasks / totalTasks * 100) : 0;
+    let section = `## Tasks by User Story
+
+Progress: ${completedTasks}/${totalTasks} tasks complete (${percentage}%)
+
+`;
+    for (const us of userStories) {
+      if (us.tasks.length === 0) {
+        continue;
+      }
+      const incrementLink = us.increment ? `[${us.increment}](../../increments/${us.increment}/tasks.md)` : "TBD";
+      section += `### ${us.id}: ${us.title} (Increment: ${incrementLink})
+
+`;
+      for (const task of us.tasks) {
+        const checkbox = task.status ? "[x]" : "[ ]";
+        section += `- ${checkbox} ${task.id}: ${task.title}
+`;
+      }
+      section += "\n";
+    }
+    return section;
+  }
+  /**
+   * Normalize status values
+   */
+  normalizeStatus(status) {
+    const normalized = status.toLowerCase();
+    if (normalized === "complete" || normalized === "completed") return "complete";
+    if (normalized === "active" || normalized === "in-progress") return "active";
+    if (normalized === "planning") return "planning";
+    return "not-started";
+  }
+  /**
+   * Get status emoji
+   */
+  getStatusEmoji(status) {
+    switch (status) {
+      case "complete":
+        return "\u2705";
+      case "active":
+        return "\u{1F6A7}";
+      case "planning":
+        return "\u{1F4CB}";
+      case "not-started":
+        return "\u23F3";
+      default:
+        return "\u2753";
+    }
+  }
+}
+export {
+  EpicContentBuilder
+};

package/plugins/specweave-github/lib/epic-content-builder.ts

@@ -0,0 +1,317 @@
+/**
+ * Epic Content Builder - Hierarchical GitHub issue content for Feature Specs
+ *
+ * Architecture:
+ * - Reads FS-* folder (FEATURE.md + us-*.md files)
+ * - Reads increment tasks.md files to map tasks to user stories
+ * - Generates hierarchical issue body:
+ *   1. User Stories section (with status + increment)
+ *   2. Tasks section (grouped by User Story)
+ *
+ * Key Features:
+ * - NO single "Increment" field (epics span multiple increments)
+ * - User Stories are checkable with status and increment link
+ * - Tasks grouped under their User Story
+ * - Shows which increment each US/task belongs to
+ */
+
+import { readdir, readFile } from 'fs/promises';
+import { existsSync } from 'fs';
+import * as path from 'path';
+import * as yaml from 'yaml';
+
+interface UserStory {
+  id: string;
+  title: string;
+  status: 'complete' | 'active' | 'planning' | 'not-started';
+  increment: string | null; // e.g., "0031-external-tool-status-sync"
+  tasks: Task[];
+}
+
+interface Task {
+  id: string;
+  title: string;
+  status: boolean; // true = completed, false = not started
+  userStoryId: string; // e.g., "US-001"
+}
+
+interface EpicFrontmatter {
+  id: string;
+  title: string;
+  status: string;
+  created: string;
+  last_updated: string;
+}
+
+interface UserStoryFrontmatter {
+  id: string;
+  epic: string;
+  title: string;
+  status: string;
+  created: string;
+  completed?: string;
+}
+
+export class EpicContentBuilder {
+  private epicFolder: string;
+  private projectRoot: string;
+
+  constructor(epicFolder: string, projectRoot: string) {
+    this.epicFolder = epicFolder;
+    this.projectRoot = projectRoot;
+  }
+
+  /**
+   * Build hierarchical GitHub issue body
+   *
+   * Format:
+   * - Epic overview
+   * - User Stories section (checkable, with status + increment)
+   * - Tasks section (grouped by User Story)
+   */
+  async buildIssueBody(): Promise<string> {
+    // 1. Read Epic metadata
+    const epicData = await this.readEpicMetadata();
+
+    // 2. Read User Stories
+    const userStories = await this.readUserStories();
+
+    // 3. Build sections
+    const overview = this.buildOverviewSection(epicData);
+    const userStoriesSection = this.buildUserStoriesSection(userStories);
+    const tasksSection = this.buildTasksSection(userStories);
+
+    // 4. Combine
+    return `${overview}\n\n---\n\n${userStoriesSection}\n\n---\n\n${tasksSection}\n\n---\n\n🤖 Auto-created by SpecWeave Epic Sync`;
+  }
+
+  /**
+   * Read Epic FEATURE.md frontmatter
+   */
+  private async readEpicMetadata(): Promise<EpicFrontmatter> {
+    const featurePath = path.join(this.epicFolder, 'FEATURE.md');
+    const content = await readFile(featurePath, 'utf-8');
+    const match = content.match(/^---\n([\s\S]*?)\n---/);
+
+    if (!match) {
+      throw new Error('FEATURE.md missing YAML frontmatter');
+    }
+
+    return yaml.parse(match[1]) as EpicFrontmatter;
+  }
+
+  /**
+   * Read all user stories from us-*.md files
+   */
+  private async readUserStories(): Promise<UserStory[]> {
+    const files = await readdir(this.epicFolder);
+    const usFiles = files.filter((f) => f.startsWith('us-') && f.endsWith('.md'));
+
+    const userStories: UserStory[] = [];
+
+    for (const file of usFiles.sort()) {
+      const filePath = path.join(this.epicFolder, file);
+      const content = await readFile(filePath, 'utf-8');
+      const match = content.match(/^---\n([\s\S]*?)\n---/);
+
+      if (!match) {
+        console.warn(`   ⚠️  ${file} missing frontmatter, skipping`);
+        continue;
+      }
+
+      const frontmatter = yaml.parse(match[1]) as UserStoryFrontmatter;
+      const bodyContent = content.slice(match[0].length).trim();
+
+      // Extract increment from Implementation section
+      const incrementMatch = bodyContent.match(/\*\*Increment\*\*:\s*\[([^\]]+)\]/);
+      const increment = incrementMatch ? incrementMatch[1] : null;
+
+      // Extract tasks from Implementation section
+      const tasks = await this.extractTasksForUserStory(
+        frontmatter.id,
+        increment,
+        bodyContent
+      );
+
+      userStories.push({
+        id: frontmatter.id,
+        title: frontmatter.title,
+        status: this.normalizeStatus(frontmatter.status),
+        increment,
+        tasks,
+      });
+    }
+
+    return userStories;
+  }
+
+  /**
+   * Extract tasks for a user story from its Implementation section
+   */
+  private async extractTasksForUserStory(
+    userStoryId: string,
+    incrementId: string | null,
+    content: string
+  ): Promise<Task[]> {
+    if (!incrementId) {
+      return []; // No increment yet, no tasks
+    }
+
+    // Find increment folder
+    const incrementFolder = path.join(
+      this.projectRoot,
+      '.specweave',
+      'increments',
+      incrementId
+    );
+
+    if (!existsSync(incrementFolder)) {
+      console.warn(`   ⚠️  Increment folder not found: ${incrementId}`);
+      return [];
+    }
+
+    const tasksPath = path.join(incrementFolder, 'tasks.md');
+    if (!existsSync(tasksPath)) {
+      console.warn(`   ⚠️  tasks.md not found in ${incrementId}`);
+      return [];
+    }
+
+    // Read tasks.md
+    const tasksContent = await readFile(tasksPath, 'utf-8');
+
+    // Extract task links from user story's Implementation section
+    // Format: - [T-001: Title](link#t-001-title)
+    const taskLinkPattern = /- \[([T-\d]+):\s*([^\]]+)\]/g;
+    const taskLinks: Array<{ id: string; title: string }> = [];
+
+    let match;
+    while ((match = taskLinkPattern.exec(content)) !== null) {
+      taskLinks.push({
+        id: match[1], // e.g., "T-001"
+        title: match[2].trim(),
+      });
+    }
+
+    // Parse tasks from tasks.md to get completion status
+    const tasks: Task[] = [];
+
+    for (const taskLink of taskLinks) {
+      // Find task in tasks.md by heading pattern: ### T-001: Title
+      const taskPattern = new RegExp(
+        `###\\s+${taskLink.id}:\\s*([^\\n]+)[\\s\\S]*?\\*\\*Status\\*\\*:\\s*\\[([x\\s])\\]`,
+        'i'
+      );
+      const taskMatch = tasksContent.match(taskPattern);
+
+      const isCompleted = taskMatch ? taskMatch[2] === 'x' : false;
+
+      tasks.push({
+        id: taskLink.id,
+        title: taskLink.title,
+        status: isCompleted,
+        userStoryId,
+      });
+    }
+
+    return tasks;
+  }
+
+  /**
+   * Build overview section
+   */
+  private buildOverviewSection(epic: EpicFrontmatter): string {
+    return `# [${epic.id}] ${epic.title}\n\n**Status**: ${epic.status}\n**Created**: ${epic.created}\n**Last Updated**: ${epic.last_updated}`;
+  }
+
+  /**
+   * Build User Stories section
+   */
+  private buildUserStoriesSection(userStories: UserStory[]): string {
+    const total = userStories.length;
+    const completed = userStories.filter((us) => us.status === 'complete').length;
+    const percentage = total > 0 ? Math.round((completed / total) * 100) : 0;
+
+    let section = `## User Stories\n\nProgress: ${completed}/${total} user stories complete (${percentage}%)\n\n`;
+
+    for (const us of userStories) {
+      const checkbox = us.status === 'complete' ? '[x]' : '[ ]';
+      const statusEmoji = this.getStatusEmoji(us.status);
+      const incrementLink = us.increment
+        ? `[${us.increment}](../../increments/${us.increment}/)`
+        : 'TBD';
+
+      section += `- ${checkbox} **${us.id}: ${us.title}** (${statusEmoji} ${us.status} | Increment: ${incrementLink})\n`;
+    }
+
+    return section;
+  }
+
+  /**
+   * Build Tasks section (grouped by User Story)
+   */
+  private buildTasksSection(userStories: UserStory[]): string {
+    const totalTasks = userStories.reduce((sum, us) => sum + us.tasks.length, 0);
+    const completedTasks = userStories.reduce(
+      (sum, us) => sum + us.tasks.filter((t) => t.status).length,
+      0
+    );
+    const percentage =
+      totalTasks > 0 ? Math.round((completedTasks / totalTasks) * 100) : 0;
+
+    let section = `## Tasks by User Story\n\nProgress: ${completedTasks}/${totalTasks} tasks complete (${percentage}%)\n\n`;
+
+    for (const us of userStories) {
+      if (us.tasks.length === 0) {
+        continue; // Skip user stories with no tasks yet
+      }
+
+      const incrementLink = us.increment
+        ? `[${us.increment}](../../increments/${us.increment}/tasks.md)`
+        : 'TBD';
+
+      section += `### ${us.id}: ${us.title} (Increment: ${incrementLink})\n\n`;
+
+      for (const task of us.tasks) {
+        const checkbox = task.status ? '[x]' : '[ ]';
+        section += `- ${checkbox} ${task.id}: ${task.title}\n`;
+      }
+
+      section += '\n';
+    }
+
+    return section;
+  }
+
+  /**
+   * Normalize status values
+   */
+  private normalizeStatus(
+    status: string
+  ): 'complete' | 'active' | 'planning' | 'not-started' {
+    const normalized = status.toLowerCase();
+    if (normalized === 'complete' || normalized === 'completed') return 'complete';
+    if (normalized === 'active' || normalized === 'in-progress') return 'active';
+    if (normalized === 'planning') return 'planning';
+    return 'not-started';
+  }
+
+  /**
+   * Get status emoji
+   */
+  private getStatusEmoji(
+    status: 'complete' | 'active' | 'planning' | 'not-started'
+  ): string {
+    switch (status) {
+      case 'complete':
+        return '✅';
+      case 'active':
+        return '🚧';
+      case 'planning':
+        return '📋';
+      case 'not-started':
+        return '⏳';
+      default:
+        return '❓';
+    }
+  }
+}

package/plugins/specweave-github/lib/github-client.js

@@ -1,4 +1,5 @@
 import { execSync } from "child_process";
+import { DuplicateDetector } from "./duplicate-detector.js";
 class GitHubClient {
   constructor(repo) {
     this.repo = repo || this.detectRepo();
@@ -70,21 +71,31 @@ class GitHubClient {
     }
   }
   /**
-   * Create epic issue (increment-level)
+   * Create epic issue (increment-level) with FULL DUPLICATE PROTECTION
    */
   async createEpicIssue(title, body, milestone, labels = []) {
-    const labelArgs = labels.map((l) => `-l "${l}"`).join(" ");
-    const milestoneArg = milestone ? `-m "${milestone}"` : "";
-    const createCmd = `gh issue create --repo ${this.repo} --title "${this.escapeQuotes(title)}" --body "${this.escapeQuotes(body)}" ${labelArgs} ${milestoneArg}`;
+    const titlePattern = DuplicateDetector.extractTitlePattern(title);
+    if (!titlePattern) {
+      throw new Error(`Epic issue title must start with pattern like [FS-XXX] or [INC-XXXX]: ${title}`);
+    }
     try {
-      const issueUrl = execSync(createCmd, { encoding: "utf-8" }).trim();
-      const issueNumber = parseInt(issueUrl.split("/").pop() || "0", 10);
-      if (!issueNumber) {
-        throw new Error("Failed to extract issue number from URL: " + issueUrl);
-      }
-      const viewCmd = `gh issue view ${issueNumber} --repo ${this.repo} --json number,title,body,state,url,labels,milestone`;
+      const result = await DuplicateDetector.createWithProtection({
+        title,
+        body,
+        titlePattern,
+        labels: labels.length > 0 ? labels : ["specweave", "increment"],
+        milestone: milestone?.toString(),
+        repo: this.repo
+      });
+      const viewCmd = `gh issue view ${result.issue.number} --repo ${this.repo} --json number,title,body,state,url,labels,milestone`;
       const output = execSync(viewCmd, { encoding: "utf-8" });
       const issue = JSON.parse(output);
+      if (result.wasReused) {
+        console.log(`   \u267B\uFE0F  Reused existing issue #${result.issue.number} (duplicate prevention)`);
+      }
+      if (result.duplicatesFound > 0) {
+        console.log(`   \u{1F6E1}\uFE0F  Duplicates detected: ${result.duplicatesFound} (auto-closed: ${result.duplicatesClosed})`);
+      }
       return {
         ...issue,
         html_url: issue.url,

package/plugins/specweave-github/lib/github-client.ts

@@ -5,6 +5,7 @@
 
 import { execSync } from 'child_process';
 import { GitHubIssue, GitHubMilestone } from './types';
+import { DuplicateDetector } from './duplicate-detector.js';
 
 export class GitHubClient {
   private repo: string;
@@ -96,7 +97,7 @@ export class GitHubClient {
   }
 
   /**
-   * Create epic issue (increment-level)
+   * Create epic issue (increment-level) with FULL DUPLICATE PROTECTION
    */
   async createEpicIssue(
     title: string,
@@ -104,27 +105,37 @@ export class GitHubClient {
     milestone?: number | string,
     labels: string[] = []
   ): Promise<GitHubIssue> {
-    const labelArgs = labels.map(l => `-l "${l}"`).join(' ');
-    const milestoneArg = milestone ? `-m "${milestone}"` : '';
+    // Extract title pattern for duplicate detection (e.g., "[FS-031]" from "[FS-031] Feature Title")
+    const titlePattern = DuplicateDetector.extractTitlePattern(title);
 
-    // Create issue (returns URL)
-    const createCmd = `gh issue create --repo ${this.repo} --title "${this.escapeQuotes(title)}" --body "${this.escapeQuotes(body)}" ${labelArgs} ${milestoneArg}`;
+    if (!titlePattern) {
+      throw new Error(`Epic issue title must start with pattern like [FS-XXX] or [INC-XXXX]: ${title}`);
+    }
 
     try {
-      const issueUrl = execSync(createCmd, { encoding: 'utf-8' }).trim();
-
-      // Extract issue number from URL (e.g., https://github.com/owner/repo/issues/123)
-      const issueNumber = parseInt(issueUrl.split('/').pop() || '0', 10);
-
-      if (!issueNumber) {
-        throw new Error('Failed to extract issue number from URL: ' + issueUrl);
-      }
-
-      // Fetch issue details
-      const viewCmd = `gh issue view ${issueNumber} --repo ${this.repo} --json number,title,body,state,url,labels,milestone`;
+      // Use DuplicateDetector for full 3-phase protection
+      const result = await DuplicateDetector.createWithProtection({
+        title,
+        body,
+        titlePattern,
+        labels: labels.length > 0 ? labels : ['specweave', 'increment'],
+        milestone: milestone?.toString(),
+        repo: this.repo
+      });
+
+      // Fetch full issue details (DuplicateDetector returns minimal info)
+      const viewCmd = `gh issue view ${result.issue.number} --repo ${this.repo} --json number,title,body,state,url,labels,milestone`;
       const output = execSync(viewCmd, { encoding: 'utf-8' });
       const issue = JSON.parse(output);
 
+      // Log duplicate detection results if any
+      if (result.wasReused) {
+        console.log(`   ♻️  Reused existing issue #${result.issue.number} (duplicate prevention)`);
+      }
+      if (result.duplicatesFound > 0) {
+        console.log(`   🛡️  Duplicates detected: ${result.duplicatesFound} (auto-closed: ${result.duplicatesClosed})`);
+      }
+
       return {
         ...issue,
         html_url: issue.url,