specweave 0.18.0 → 0.20.0

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

@@ -44,6 +44,20 @@ export class GitHubClientV2 {
     return new GitHubClientV2(profile);
   }
 
+  /**
+   * Get repository owner
+   */
+  getOwner(): string {
+    return this.owner;
+  }
+
+  /**
+   * Get repository name
+   */
+  getRepo(): string {
+    return this.repo;
+  }
+
   // ==========================================================================
   // Authentication & Setup
   // ==========================================================================
@@ -272,6 +286,51 @@ export class GitHubClientV2 {
     };
   }
 
+  /**
+   * Search for issue by exact title match
+   *
+   * IDEMPOTENCY: Use this before creating issues to prevent duplicates
+   */
+  async searchIssueByTitle(title: string): Promise<GitHubIssue | null> {
+    // Escape double quotes in title for gh search
+    const escapedTitle = title.replace(/"/g, '\\"');
+
+    const result = await execFileNoThrow('gh', [
+      'issue',
+      'list',
+      '--repo',
+      this.fullRepo,
+      '--search',
+      `"${escapedTitle}" in:title`,
+      '--json',
+      'number,title,state,url,labels',
+      '--limit',
+      '1',
+    ]);
+
+    if (result.exitCode !== 0) {
+      // Search failed, return null (treat as not found)
+      return null;
+    }
+
+    const issues = JSON.parse(result.stdout || '[]');
+
+    if (!issues || issues.length === 0) {
+      return null;
+    }
+
+    // Return first exact match
+    const issue = issues[0];
+    return {
+      number: issue.number,
+      title: issue.title,
+      body: '', // Body not included in list view
+      state: issue.state,
+      html_url: issue.url,
+      labels: issue.labels?.map((l: any) => l.name) || [],
+    };
+  }
+
   /**
    * Update issue body
    */

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

@@ -4,6 +4,7 @@ import * as path from "path";
 import * as yaml from "yaml";
 import { execFileNoThrow } from "../../../src/utils/execFileNoThrow.js";
 import { DuplicateDetector } from "./duplicate-detector.js";
+import { EpicContentBuilder } from "./epic-content-builder.js";
 class GitHubEpicSync {
   constructor(client, specsDir) {
     this.client = client;
@@ -350,21 +351,20 @@ Status: ${epic.status}`;
     }
   }
   /**
-   * Create GitHub Issue for increment with FULL DUPLICATE PROTECTION
+   * Create GitHub Issue for Epic with hierarchical content (US → Tasks)
    */
   async createIssue(epicId, increment, milestoneNumber) {
     const title = `[${epicId}] ${increment.title}`;
-    const body = `# ${increment.title}
-
-${increment.overview}
-
----
-
-**Increment**: ${increment.id}
-**Epic**: ${epicId}
-**Milestone**: See milestone for Epic progress
-
-\u{1F916} Auto-created by SpecWeave Epic Sync`;
+    const epicFolder = await this.findEpicFolder(epicId);
+    if (!epicFolder) {
+      throw new Error(`Epic folder not found for ${epicId}`);
+    }
+    const contentBuilder = new EpicContentBuilder(
+      epicFolder,
+      path.dirname(this.specsDir)
+      // Project root
+    );
+    const body = await contentBuilder.buildIssueBody();
     try {
       const result = await DuplicateDetector.createWithProtection({
         title,
@@ -387,21 +387,20 @@ ${increment.overview}
     }
   }
   /**
-   * Update GitHub Issue for increment
+   * Update GitHub Issue for Epic with hierarchical content (US → Tasks)
    */
   async updateIssue(epicId, issueNumber, increment, milestoneNumber) {
     const title = `[${epicId}] ${increment.title}`;
-    const body = `# ${increment.title}
-
-${increment.overview}
-
----
-
-**Increment**: ${increment.id}
-**Epic**: ${epicId}
-**Milestone**: See milestone for Epic progress
-
-\u{1F916} Auto-updated by SpecWeave Epic Sync`;
+    const epicFolder = await this.findEpicFolder(epicId);
+    if (!epicFolder) {
+      throw new Error(`Epic folder not found for ${epicId}`);
+    }
+    const contentBuilder = new EpicContentBuilder(
+      epicFolder,
+      path.dirname(this.specsDir)
+      // Project root
+    );
+    const body = await contentBuilder.buildIssueBody();
     const result = await execFileNoThrow("gh", [
       "issue",
       "edit",

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

@@ -15,6 +15,7 @@ import * as yaml from 'yaml';
 import { GitHubClientV2 } from './github-client-v2.js';
 import { execFileNoThrow } from '../../../src/utils/execFileNoThrow.js';
 import { DuplicateDetector } from './duplicate-detector.js';
+import { EpicContentBuilder } from './epic-content-builder.js';
 
 interface EpicFrontmatter {
   id: string;
@@ -317,7 +318,7 @@ export class GitHubEpicSync {
   ): Promise<number | null> {
     try {
       // Search GitHub for issues with Epic ID in title
-      // Pattern: "[FS-031] Title" or "[INC-0031] Title"
+      // Pattern: "[FS-031] Title" (new) or "[INC-0031] Title" (deprecated, legacy support only)
       const titlePattern = `[${epicId}]`;
 
       const result = await execFileNoThrow('gh', [
@@ -526,7 +527,7 @@ export class GitHubEpicSync {
   }
 
   /**
-   * Create GitHub Issue for increment with FULL DUPLICATE PROTECTION
+   * Create GitHub Issue for Epic with hierarchical content (US → Tasks)
    */
   private async createIssue(
     epicId: string,
@@ -539,7 +540,19 @@ export class GitHubEpicSync {
     milestoneNumber: number
   ): Promise<number> {
     const title = `[${epicId}] ${increment.title}`;
-    const body = `# ${increment.title}\n\n${increment.overview}\n\n---\n\n**Increment**: ${increment.id}\n**Epic**: ${epicId}\n**Milestone**: See milestone for Epic progress\n\n🤖 Auto-created by SpecWeave Epic Sync`;
+
+    // Build hierarchical issue body using EpicContentBuilder
+    const epicFolder = await this.findEpicFolder(epicId);
+    if (!epicFolder) {
+      throw new Error(`Epic folder not found for ${epicId}`);
+    }
+
+    const contentBuilder = new EpicContentBuilder(
+      epicFolder,
+      path.dirname(this.specsDir) // Project root
+    );
+
+    const body = await contentBuilder.buildIssueBody();
 
     try {
       // Use DuplicateDetector for full 3-phase protection
@@ -568,7 +581,7 @@ export class GitHubEpicSync {
   }
 
   /**
-   * Update GitHub Issue for increment
+   * Update GitHub Issue for Epic with hierarchical content (US → Tasks)
    */
   private async updateIssue(
     epicId: string,
@@ -582,7 +595,19 @@ export class GitHubEpicSync {
     milestoneNumber: number
   ): Promise<void> {
     const title = `[${epicId}] ${increment.title}`;
-    const body = `# ${increment.title}\n\n${increment.overview}\n\n---\n\n**Increment**: ${increment.id}\n**Epic**: ${epicId}\n**Milestone**: See milestone for Epic progress\n\n🤖 Auto-updated by SpecWeave Epic Sync`;
+
+    // Build hierarchical issue body using EpicContentBuilder
+    const epicFolder = await this.findEpicFolder(epicId);
+    if (!epicFolder) {
+      throw new Error(`Epic folder not found for ${epicId}`);
+    }
+
+    const contentBuilder = new EpicContentBuilder(
+      epicFolder,
+      path.dirname(this.specsDir) // Project root
+    );
+
+    const body = await contentBuilder.buildIssueBody();
 
     const result = await execFileNoThrow('gh', [
       'issue',

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

@@ -0,0 +1,381 @@
+import { readdir, readFile, writeFile } from "fs/promises";
+import { existsSync } from "fs";
+import * as path from "path";
+import * as yaml from "yaml";
+import { UserStoryIssueBuilder } from "./user-story-issue-builder.js";
+import { CompletionCalculator } from "./completion-calculator.js";
+import { execFileNoThrow } from "../../../src/utils/execFileNoThrow.js";
+class GitHubFeatureSync {
+  constructor(client, specsDir, projectRoot) {
+    this.client = client;
+    this.specsDir = specsDir;
+    this.projectRoot = projectRoot;
+    this.calculator = new CompletionCalculator(projectRoot);
+  }
+  /**
+   * Sync Feature folder to GitHub (Milestone + User Story Issues)
+   *
+   * Process:
+   * 1. Create/update GitHub Milestone for Feature
+   * 2. Find all us-*.md files across all projects
+   * 3. Create/update GitHub Issue for EACH user story
+   * 4. Update frontmatter with GitHub issue links
+   */
+  async syncFeatureToGitHub(featureId) {
+    console.log(`
+\u{1F504} Syncing Feature ${featureId} to GitHub...`);
+    const featureFolder = await this.findFeatureFolder(featureId);
+    if (!featureFolder) {
+      throw new Error(`Feature ${featureId} not found in ${this.specsDir}`);
+    }
+    const featurePath = path.join(featureFolder, "FEATURE.md");
+    const featureData = await this.parseFeatureMd(featurePath);
+    console.log(`   \u{1F4E6} Feature: ${featureData.title}`);
+    console.log(`   \u{1F4CA} Status: ${featureData.status}`);
+    let milestoneNumber = featureData.external_tools?.github?.id;
+    let milestoneUrl = featureData.external_tools?.github?.url;
+    if (!milestoneNumber) {
+      console.log(`   \u{1F680} Creating GitHub Milestone...`);
+      const milestone = await this.createMilestone(featureData);
+      milestoneNumber = milestone.number;
+      milestoneUrl = milestone.url;
+      console.log(`   \u2705 Created Milestone #${milestoneNumber}`);
+      await this.updateFeatureMd(featurePath, {
+        type: "milestone",
+        id: milestoneNumber,
+        url: milestoneUrl
+      });
+    } else {
+      console.log(`   \u267B\uFE0F  Using existing Milestone #${milestoneNumber}`);
+      milestoneUrl = featureData.external_tools?.github?.url || milestoneUrl;
+    }
+    const userStories = await this.findUserStories(featureId);
+    console.log(`
+   \u{1F4DD} Found ${userStories.length} User Stories to sync...`);
+    let issuesCreated = 0;
+    let issuesUpdated = 0;
+    for (const userStory of userStories) {
+      console.log(`
+   \u{1F539} Processing ${userStory.id}: ${userStory.title}`);
+      const repoInfo = {
+        owner: this.client.getOwner(),
+        repo: this.client.getRepo(),
+        branch: "develop"
+        // TODO: detect from git
+      };
+      const builder = new UserStoryIssueBuilder(
+        userStory.filePath,
+        this.projectRoot,
+        featureId,
+        repoInfo
+      );
+      const issueContent = await builder.buildIssueBody();
+      issueContent.status = userStory.status;
+      if (userStory.existingIssue) {
+        console.log(`      \u267B\uFE0F  Issue #${userStory.existingIssue} exists in frontmatter`);
+        try {
+          await this.client.getIssue(userStory.existingIssue);
+          await this.updateUserStoryIssue(userStory.existingIssue, issueContent, userStory.filePath);
+          issuesUpdated++;
+          console.log(`      \u2705 Updated Issue #${userStory.existingIssue}`);
+          continue;
+        } catch (err) {
+          console.log(`      \u26A0\uFE0F  Issue #${userStory.existingIssue} deleted on GitHub, creating new`);
+        }
+      }
+      const existingByTitle = await this.client.searchIssueByTitle(issueContent.title);
+      if (existingByTitle) {
+        console.log(`      \u267B\uFE0F  Found existing issue by title: #${existingByTitle.number}`);
+        await this.updateUserStoryFrontmatter(userStory.filePath, existingByTitle.number);
+        await this.updateUserStoryIssue(existingByTitle.number, issueContent, userStory.filePath);
+        issuesUpdated++;
+        console.log(`      \u2705 Linked and updated Issue #${existingByTitle.number}`);
+        continue;
+      }
+      console.log(`      \u{1F680} Creating new issue: ${issueContent.title}`);
+      const milestoneTitle = `${featureData.id}: ${featureData.title}`;
+      const issueNumber = await this.createUserStoryIssue(
+        issueContent,
+        milestoneTitle,
+        userStory.filePath
+      );
+      issuesCreated++;
+      console.log(`      \u2705 Created Issue #${issueNumber}`);
+      await this.updateUserStoryFrontmatter(userStory.filePath, issueNumber);
+    }
+    console.log(`
+\u2705 Feature sync complete!`);
+    console.log(`   Milestone: ${milestoneUrl}`);
+    console.log(`   User Stories: ${userStories.length}`);
+    console.log(`   Issues created: ${issuesCreated}`);
+    console.log(`   Issues updated: ${issuesUpdated}`);
+    return {
+      milestoneNumber,
+      milestoneUrl,
+      issuesCreated,
+      issuesUpdated,
+      userStoriesProcessed: userStories.length
+    };
+  }
+  /**
+   * Find Feature folder in specs directory
+   */
+  async findFeatureFolder(featureId) {
+    const featuresFolder = path.join(this.specsDir, "_features", featureId);
+    if (existsSync(featuresFolder)) {
+      return featuresFolder;
+    }
+    return null;
+  }
+  /**
+   * Parse FEATURE.md frontmatter
+   */
+  async parseFeatureMd(featurePath) {
+    const content = await readFile(featurePath, "utf-8");
+    const match = content.match(/^---\n([\s\S]*?)\n---/);
+    if (!match) {
+      throw new Error(`${featurePath}: Missing YAML frontmatter`);
+    }
+    return yaml.parse(match[1]);
+  }
+  /**
+   * Find all User Story files for this feature across all projects
+   */
+  async findUserStories(featureId) {
+    const userStories = [];
+    const projectFolders = await this.findProjectFolders();
+    for (const projectFolder of projectFolders) {
+      const featureSpecsFolder = path.join(projectFolder, featureId);
+      if (!existsSync(featureSpecsFolder)) {
+        continue;
+      }
+      const files = await readdir(featureSpecsFolder);
+      const usFiles = files.filter((f) => f.startsWith("us-") && f.endsWith(".md"));
+      for (const file of usFiles.sort()) {
+        const filePath = path.join(featureSpecsFolder, 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 projectName = path.basename(projectFolder);
+        userStories.push({
+          id: frontmatter.id || file.match(/us-(\d+)/)?.[0]?.toUpperCase() || "UNKNOWN",
+          title: frontmatter.title || "Untitled User Story",
+          filePath,
+          project: projectName,
+          status: frontmatter.status || "not-started",
+          existingIssue: frontmatter.external?.github?.issue || null
+        });
+      }
+    }
+    return userStories;
+  }
+  /**
+   * Find all project folders (default, backend, frontend, etc.)
+   */
+  async findProjectFolders() {
+    const folders = [];
+    const specsRoot = this.specsDir;
+    const entries = await readdir(specsRoot, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isDirectory() && !entry.name.startsWith("_")) {
+        folders.push(path.join(specsRoot, entry.name));
+      }
+    }
+    return folders;
+  }
+  /**
+   * Create GitHub Milestone for Feature
+   */
+  async createMilestone(featureData) {
+    const title = `${featureData.id}: ${featureData.title}`;
+    const description = `Feature ${featureData.id}
+
+Status: ${featureData.status}
+Created: ${featureData.created}`;
+    const result = await execFileNoThrow("gh", [
+      "api",
+      "repos/:owner/:repo/milestones",
+      "-X",
+      "POST",
+      "-f",
+      `title=${title}`,
+      "-f",
+      `description=${description}`,
+      "-f",
+      "state=open"
+    ]);
+    if (result.exitCode !== 0) {
+      throw new Error(`Failed to create Milestone: ${result.stderr || result.stdout}`);
+    }
+    const milestone = JSON.parse(result.stdout);
+    return {
+      number: milestone.number,
+      url: milestone.html_url
+    };
+  }
+  /**
+   * Create GitHub Issue for User Story with AC/Task Verification
+   *
+   * ✅ VERIFICATION GATE FIX:
+   * - Verifies actual completion before closing
+   * - Prevents premature closure on creation
+   */
+  async createUserStoryIssue(issueContent, milestoneTitle, userStoryPath) {
+    const result = await execFileNoThrow("gh", [
+      "issue",
+      "create",
+      "--title",
+      issueContent.title,
+      "--body",
+      issueContent.body,
+      "--milestone",
+      milestoneTitle,
+      ...issueContent.labels.flatMap((label) => ["--label", label])
+    ]);
+    if (result.exitCode !== 0) {
+      throw new Error(`Failed to create GitHub Issue: ${result.stderr || result.stdout}`);
+    }
+    const match = result.stdout.match(/issues\/(\d+)/);
+    if (!match) {
+      throw new Error(`Failed to parse issue number from: ${result.stdout}`);
+    }
+    const issueNumber = parseInt(match[1], 10);
+    const completion = await this.calculator.calculateCompletion(userStoryPath);
+    if (completion.overallComplete) {
+      await execFileNoThrow("gh", [
+        "issue",
+        "close",
+        issueNumber.toString(),
+        "--comment",
+        this.calculator.buildCompletionComment(completion)
+      ]);
+      console.log(
+        `      \u2705 Created and verified complete: ${completion.acsCompleted}/${completion.acsTotal} ACs, ${completion.tasksCompleted}/${completion.tasksTotal} tasks`
+      );
+    } else {
+      await execFileNoThrow("gh", [
+        "issue",
+        "comment",
+        issueNumber.toString(),
+        "--body",
+        this.calculator.buildProgressComment(completion)
+      ]);
+      console.log(
+        `      \u{1F4CA} Created: ${completion.acsPercentage.toFixed(0)}% ACs, ${completion.tasksPercentage.toFixed(0)}% tasks`
+      );
+    }
+    return issueNumber;
+  }
+  /**
+   * Update existing GitHub Issue for User Story with AC/Task Verification
+   *
+   * ✅ VERIFICATION GATE FIX:
+   * - OLD: Closed based on frontmatter `status: complete`
+   * - NEW: Closes ONLY if all ACs and tasks are [x]
+   *
+   * This prevents Issue #574 type bugs (premature closure)
+   */
+  async updateUserStoryIssue(issueNumber, issueContent, userStoryPath) {
+    await execFileNoThrow("gh", [
+      "issue",
+      "edit",
+      issueNumber.toString(),
+      "--title",
+      issueContent.title,
+      "--body",
+      issueContent.body
+    ]);
+    const completion = await this.calculator.calculateCompletion(userStoryPath);
+    const issueData = await this.client.getIssue(issueNumber);
+    const currentlyClosed = issueData.state === "closed";
+    if (completion.overallComplete) {
+      if (!currentlyClosed) {
+        await execFileNoThrow("gh", [
+          "issue",
+          "close",
+          issueNumber.toString(),
+          "--comment",
+          this.calculator.buildCompletionComment(completion)
+        ]);
+        console.log(
+          `      \u2705 Verified complete: ${completion.acsCompleted}/${completion.acsTotal} ACs, ${completion.tasksCompleted}/${completion.tasksTotal} tasks`
+        );
+      }
+    } else {
+      if (currentlyClosed) {
+        await execFileNoThrow("gh", [
+          "issue",
+          "reopen",
+          issueNumber.toString(),
+          "--comment",
+          this.calculator.buildReopenComment(completion, "Work verification failed")
+        ]);
+        console.log(
+          `      \u26A0\uFE0F Reopened: ${completion.blockingAcs.length + completion.blockingTasks.length} items incomplete`
+        );
+      } else {
+        await execFileNoThrow("gh", [
+          "issue",
+          "comment",
+          issueNumber.toString(),
+          "--body",
+          this.calculator.buildProgressComment(completion)
+        ]);
+        console.log(
+          `      \u{1F4CA} Progress: ${completion.acsPercentage.toFixed(0)}% ACs, ${completion.tasksPercentage.toFixed(0)}% tasks`
+        );
+      }
+    }
+  }
+  /**
+   * Update FEATURE.md with GitHub Milestone link
+   */
+  async updateFeatureMd(featurePath, milestone) {
+    const content = await readFile(featurePath, "utf-8");
+    const match = content.match(/^---\n([\s\S]*?)\n---/);
+    if (!match) {
+      throw new Error(`${featurePath}: Missing YAML frontmatter`);
+    }
+    const frontmatter = yaml.parse(match[1]);
+    if (!frontmatter.external_tools) {
+      frontmatter.external_tools = {};
+    }
+    frontmatter.external_tools.github = milestone;
+    const newFrontmatter = yaml.stringify(frontmatter);
+    const bodyContent = content.slice(match[0].length);
+    const newContent = `---
+${newFrontmatter}---${bodyContent}`;
+    await writeFile(featurePath, newContent, "utf-8");
+  }
+  /**
+   * Update User Story frontmatter with GitHub issue link
+   */
+  async updateUserStoryFrontmatter(userStoryPath, issueNumber) {
+    const content = await readFile(userStoryPath, "utf-8");
+    const match = content.match(/^---\n([\s\S]*?)\n---/);
+    if (!match) {
+      throw new Error(`${userStoryPath}: Missing YAML frontmatter`);
+    }
+    const frontmatter = yaml.parse(match[1]);
+    if (!frontmatter.external) {
+      frontmatter.external = {};
+    }
+    if (!frontmatter.external.github) {
+      frontmatter.external.github = {};
+    }
+    frontmatter.external.github.issue = issueNumber;
+    frontmatter.external.github.url = `https://github.com/anton-abyzov/specweave/issues/${issueNumber}`;
+    const newFrontmatter = yaml.stringify(frontmatter);
+    const bodyContent = content.slice(match[0].length);
+    const newContent = `---
+${newFrontmatter}---${bodyContent}`;
+    await writeFile(userStoryPath, newContent, "utf-8");
+  }
+}
+export {
+  GitHubFeatureSync
+};