specweave 0.17.15 → 0.17.17

package/plugins/specweave-ado/lib/ado-status-sync.ts

@@ -0,0 +1,121 @@
+/**
+ * Azure DevOps Status Sync
+ *
+ * Synchronizes SpecWeave increment statuses with ADO work item states.
+ *
+ * ADO Work Item State Updates:
+ * - Uses JSON Patch format for updates
+ * - System.State field controls work item state
+ * - Available states: New, Active, On Hold, Resolved, Closed, Removed
+ *
+ * @module ado-status-sync
+ */
+
+import axios, { AxiosInstance } from 'axios';
+
+/**
+ * External status representation (ADO-specific)
+ */
+export interface ExternalStatus {
+  state: string; // e.g., "New", "Active", "Closed"
+}
+
+/**
+ * Azure DevOps Status Sync
+ *
+ * Handles status synchronization with ADO work items.
+ */
+export class AdoStatusSync {
+  private client: AxiosInstance;
+  private organization: string;
+  private project: string;
+
+  constructor(
+    organization: string,
+    project: string,
+    personalAccessToken: string
+  ) {
+    this.organization = organization;
+    this.project = project;
+
+    // Create ADO API client
+    this.client = axios.create({
+      baseURL: `https://dev.azure.com/${organization}/${project}/_apis`,
+      auth: {
+        username: '', // Empty for PAT auth
+        password: personalAccessToken
+      },
+      headers: {
+        'Content-Type': 'application/json-patch+json',
+        'Accept': 'application/json'
+      }
+    });
+  }
+
+  /**
+   * Get current status from ADO work item
+   *
+   * @param workItemId - ADO work item ID (e.g., 123)
+   * @returns Current work item state
+   */
+  async getStatus(workItemId: number): Promise<ExternalStatus> {
+    const response = await this.client.get(
+      `/wit/workitems/${workItemId}?api-version=7.0`
+    );
+
+    return {
+      state: response.data.fields['System.State']
+    };
+  }
+
+  /**
+   * Update ADO work item state
+   *
+   * Uses JSON Patch format to update System.State field.
+   *
+   * @param workItemId - ADO work item ID (e.g., 123)
+   * @param status - Desired status
+   */
+  async updateStatus(workItemId: number, status: ExternalStatus): Promise<void> {
+    // ADO uses JSON Patch format for updates
+    const patch = [
+      {
+        op: 'add',
+        path: '/fields/System.State',
+        value: status.state
+      }
+    ];
+
+    await this.client.patch(
+      `/wit/workitems/${workItemId}?api-version=7.0`,
+      patch
+    );
+  }
+
+  /**
+   * Post comment about status change to ADO work item
+   *
+   * @param workItemId - ADO work item ID (e.g., 123)
+   * @param oldStatus - Previous SpecWeave status
+   * @param newStatus - New SpecWeave status
+   */
+  async postStatusComment(
+    workItemId: number,
+    oldStatus: string,
+    newStatus: string
+  ): Promise<void> {
+    const text = `🔄 Status Update\n\n` +
+      `SpecWeave status changed:\n` +
+      `• From: ${oldStatus}\n` +
+      `• To: ${newStatus}\n` +
+      `• When: ${new Date().toISOString()}\n\n` +
+      `Synced from SpecWeave`;
+
+    await this.client.post(
+      `/wit/workitems/${workItemId}/comments?api-version=7.0-preview.3`,
+      {
+        text
+      }
+    );
+  }
+}

package/plugins/specweave-ado/lib/enhanced-ado-sync.js

@@ -0,0 +1,170 @@
+import { AdoClientV2 } from "./ado-client-v2.js";
+import { EnhancedContentBuilder } from "../../../src/core/sync/enhanced-content-builder.js";
+import { SpecIncrementMapper } from "../../../src/core/sync/spec-increment-mapper.js";
+import { parseSpecContent } from "../../../src/core/spec-content-sync.js";
+import path from "path";
+import fs from "fs/promises";
+async function syncSpecToAdoWithEnhancedContent(options) {
+  const { specPath, organization, project, dryRun = false, verbose = false } = options;
+  try {
+    const baseSpec = await parseSpecContent(specPath);
+    if (!baseSpec) {
+      return {
+        success: false,
+        action: "error",
+        error: "Failed to parse spec content"
+      };
+    }
+    if (verbose) {
+      console.log(`\u{1F4C4} Parsed spec: ${baseSpec.identifier.compact}`);
+    }
+    const specId = baseSpec.identifier.full || baseSpec.identifier.compact;
+    const rootDir = await findSpecWeaveRoot(specPath);
+    const mapper = new SpecIncrementMapper(rootDir);
+    const mapping = await mapper.mapSpecToIncrements(specId);
+    if (verbose) {
+      console.log(`\u{1F517} Found ${mapping.increments.length} related increments`);
+    }
+    const taskMapping = buildTaskMapping(mapping.increments, organization, project);
+    const architectureDocs = await findArchitectureDocs(rootDir, specId);
+    const enhancedSpec = {
+      ...baseSpec,
+      summary: baseSpec.description,
+      taskMapping,
+      architectureDocs
+    };
+    const builder = new EnhancedContentBuilder();
+    const description = builder.buildExternalDescription(enhancedSpec);
+    if (verbose) {
+      console.log(`\u{1F4DD} Generated description: ${description.length} characters`);
+    }
+    if (dryRun) {
+      console.log("\u{1F50D} DRY RUN - Would create/update feature with:");
+      console.log(`   Title: ${baseSpec.title}`);
+      console.log(`   Description length: ${description.length}`);
+      return {
+        success: true,
+        action: "no-change",
+        tasksLinked: taskMapping?.tasks.length || 0
+      };
+    }
+    if (!organization || !project) {
+      return {
+        success: false,
+        action: "error",
+        error: "Azure DevOps organization/project not specified"
+      };
+    }
+    const profile = {
+      provider: "ado",
+      displayName: `${organization}/${project}`,
+      config: {
+        organization,
+        project
+      },
+      timeRange: { default: "1M", max: "6M" }
+    };
+    const pat = process.env.AZURE_DEVOPS_PAT || "";
+    const client = new AdoClientV2(profile, pat);
+    const existingFeature = await findExistingFeature(client, baseSpec.identifier.compact);
+    let result;
+    if (existingFeature) {
+      await client.updateWorkItem(existingFeature.id, {
+        title: `[${baseSpec.identifier.compact}] ${baseSpec.title}`,
+        description
+      });
+      result = {
+        success: true,
+        action: "updated",
+        featureId: existingFeature.id,
+        featureUrl: `https://dev.azure.com/${organization}/${project}/_workitems/edit/${existingFeature.id}`,
+        tasksLinked: taskMapping?.tasks.length || 0
+      };
+    } else {
+      const feature = await client.createEpic({
+        title: `[${baseSpec.identifier.compact}] ${baseSpec.title}`,
+        description,
+        tags: ["spec", "external-tool-sync"]
+      });
+      result = {
+        success: true,
+        action: "created",
+        featureId: feature.id,
+        featureUrl: `https://dev.azure.com/${organization}/${project}/_workitems/edit/${feature.id}`,
+        tasksLinked: taskMapping?.tasks.length || 0
+      };
+    }
+    if (verbose) {
+      console.log(`\u2705 ${result.action === "created" ? "Created" : "Updated"} feature #${result.featureId}`);
+    }
+    return result;
+  } catch (error) {
+    return {
+      success: false,
+      action: "error",
+      error: error.message
+    };
+  }
+}
+async function findSpecWeaveRoot(specPath) {
+  let currentDir = path.dirname(specPath);
+  while (true) {
+    const specweaveDir = path.join(currentDir, ".specweave");
+    try {
+      await fs.access(specweaveDir);
+      return currentDir;
+    } catch {
+      const parentDir = path.dirname(currentDir);
+      if (parentDir === currentDir) {
+        throw new Error(".specweave directory not found");
+      }
+      currentDir = parentDir;
+    }
+  }
+}
+function buildTaskMapping(increments, organization, project) {
+  if (increments.length === 0) return void 0;
+  const firstIncrement = increments[0];
+  const tasks = firstIncrement.tasks.map((task) => ({
+    id: task.id,
+    title: task.title,
+    userStories: task.userStories
+  }));
+  return {
+    incrementId: firstIncrement.id,
+    tasks,
+    tasksUrl: `https://dev.azure.com/${organization}/${project}/_git/repo?path=/.specweave/increments/${firstIncrement.id}/tasks.md`
+  };
+}
+async function findArchitectureDocs(rootDir, specId) {
+  const docs = [];
+  const archDir = path.join(rootDir, ".specweave/docs/internal/architecture");
+  try {
+    const adrDir = path.join(archDir, "adr");
+    try {
+      const adrs = await fs.readdir(adrDir);
+      const relatedAdrs = adrs.filter((file) => file.includes(specId.replace("spec-", "")));
+      for (const adr of relatedAdrs) {
+        docs.push({
+          type: "adr",
+          path: path.join(adrDir, adr),
+          title: adr.replace(".md", "").replace(/-/g, " ")
+        });
+      }
+    } catch {
+    }
+  } catch {
+  }
+  return docs;
+}
+async function findExistingFeature(client, specId) {
+  try {
+    const features = await client.queryWorkItems(`[System.Title] Contains '[${specId}]' AND [System.WorkItemType] = 'Feature'`);
+    return features[0] || null;
+  } catch {
+    return null;
+  }
+}
+export {
+  syncSpecToAdoWithEnhancedContent
+};

package/plugins/specweave-github/commands/specweave-github-cleanup-duplicates.md

@@ -0,0 +1,205 @@
+---
+name: specweave-github-cleanup-duplicates
+description: Clean up duplicate GitHub issues for an Epic. Finds issues with duplicate titles and closes all except the first created issue.
+---
+
+# Clean Up Duplicate GitHub Issues
+
+**CRITICAL**: This command detects and closes duplicate GitHub issues created by multiple syncs.
+
+## Usage
+
+```bash
+/specweave-github:cleanup-duplicates <epic-id> [--dry-run]
+```
+
+## What It Does
+
+**Duplicate Detection & Cleanup**:
+
+1. **Find all issues** for the Epic (searches by Epic ID in title)
+2. **Group by title** (detect duplicates)
+3. **For each duplicate group**:
+   - Keep the **FIRST created** issue (lowest number)
+   - Close all **LATER** issues with comment: "Duplicate of #XXX"
+4. **Update Epic README** with correct issue numbers
+
+## Examples
+
+### Dry Run (No Changes)
+
+```bash
+/specweave-github:cleanup-duplicates FS-031 --dry-run
+```
+
+**Output**:
+```
+🔍 Scanning for duplicates in Epic FS-031...
+   Found 25 total issues
+   Detected 10 duplicate groups:
+
+   📋 Group 1: "[FS-031] External Tool Status Synchronization"
+      - #250 (KEEP) - Created 2025-11-10
+      - #255 (CLOSE) - Created 2025-11-11 - DUPLICATE
+      - #260 (CLOSE) - Created 2025-11-12 - DUPLICATE
+
+   📋 Group 2: "[FS-031] Multi-Project GitHub Sync"
+      - #251 (KEEP) - Created 2025-11-10
+      - #256 (CLOSE) - Created 2025-11-11 - DUPLICATE
+
+   ...
+
+✅ Dry run complete!
+   Total issues: 25
+   Duplicate groups: 10
+   Issues to close: 15
+
+⚠️  This was a DRY RUN - no changes made.
+   Run without --dry-run to actually close duplicates.
+```
+
+### Actual Cleanup
+
+```bash
+/specweave-github:cleanup-duplicates FS-031
+```
+
+**Output**:
+```
+🔍 Scanning for duplicates in Epic FS-031...
+   Found 25 total issues
+   Detected 10 duplicate groups
+
+⚠️  CONFIRM: Close 15 duplicate issues? [y/N]
+> y
+
+🗑️  Closing duplicates...
+   ✅ Closed #255 (duplicate of #250)
+   ✅ Closed #256 (duplicate of #251)
+   ✅ Closed #260 (duplicate of #250)
+   ...
+
+📝 Updating Epic README frontmatter...
+   ✅ Updated frontmatter with correct issue numbers
+
+✅ Cleanup complete!
+   Closed: 15 duplicates
+   Kept: 10 original issues
+```
+
+## Arguments
+
+- `<epic-id>` - Epic ID (e.g., `FS-031` or just `031`)
+- `--dry-run` - Preview changes without actually closing issues (optional)
+
+## Safety Features
+
+✅ **Confirmation prompt**: Asks before closing issues (unless --dry-run)
+✅ **Dry run mode**: Preview changes safely
+✅ **Keeps oldest issue**: Preserves the first created issue
+✅ **Adds closure comment**: Links to the original issue
+✅ **Updates metadata**: Fixes Epic README frontmatter
+
+## What Gets Closed
+
+**Closed issues**:
+- ✅ Duplicate titles (second, third, etc. occurrences)
+- ✅ Closed with comment: "Duplicate of #XXX"
+- ✅ Original issue kept open (or maintains its status)
+
+**Example comment on closed duplicate**:
+```markdown
+Duplicate of #250
+
+This issue was automatically closed by SpecWeave cleanup because it is a duplicate.
+
+The original issue (#250) contains the same content and should be used for tracking instead.
+
+🤖 Auto-closed by SpecWeave Duplicate Cleanup
+```
+
+## Requirements
+
+1. **GitHub CLI** (`gh`) installed and authenticated
+2. **Write access** to repository (for closing issues)
+3. **Epic folder exists** at `.specweave/docs/internal/specs/FS-XXX-name/`
+
+## When to Use
+
+**Use this command when**:
+- ✅ You see multiple issues with the same title in GitHub
+- ✅ Epic sync ran multiple times and created duplicates
+- ✅ Epic README frontmatter got corrupted and reset
+- ✅ Post-sync validation warns about duplicates
+
+**Example warning that triggers this**:
+```
+⚠️  WARNING: 10 duplicate(s) detected!
+   Run cleanup command to resolve:
+   /specweave-github:cleanup-duplicates FS-031
+```
+
+## Troubleshooting
+
+**"No duplicates found"**:
+- Good! Your Epic has no duplicate issues
+- Run epic sync is working correctly with duplicate detection
+
+**"GitHub CLI not authenticated"**:
+- Run: `gh auth login`
+- Ensure you have write access to the repository
+
+**"Could not find Epic folder"**:
+- Check Epic exists: `ls .specweave/docs/internal/specs/`
+- Verify Epic ID format: `FS-031-epic-name/`
+
+**"Error closing issue"**:
+- Check GitHub CLI: `gh auth status`
+- Verify write permissions: `gh repo view`
+
+## Architecture
+
+**Duplicate Detection Logic**:
+1. Group issues by **exact title match**
+2. Within each group, sort by **issue number** (ascending)
+3. Keep **first issue** (lowest number = oldest)
+4. Close **all others** as duplicates
+
+**Why lowest number?**:
+- Lower issue numbers were created first
+- Preserves chronological order
+- Maintains links from old documentation
+
+## Related Commands
+
+- `/specweave-github:sync-epic` - Sync Epic (now with duplicate detection!)
+- `/specweave:validate` - Validate increment completeness
+- `gh issue list` - View all issues (GitHub CLI)
+
+## Implementation
+
+**File**: `plugins/specweave-github/lib/github-epic-sync.ts`
+
+**Method**: `cleanupDuplicates(epicId: string, dryRun: boolean)`
+
+**Algorithm**:
+1. Search GitHub for all issues with Epic ID
+2. Group by title (Map<string, number[]>)
+3. Filter groups with >1 issue (duplicates)
+4. For each duplicate group:
+   - Keep first issue (lowest number)
+   - Close others with gh CLI
+5. Update Epic README frontmatter
+
+## Next Steps
+
+After cleanup:
+
+1. **Verify cleanup**: `gh issue list --search "[FS-031]"`
+2. **Check Epic README**: Verify frontmatter has correct issue numbers
+3. **Re-run sync**: `/specweave-github:sync-epic FS-031` (should show no duplicates)
+4. **Enable duplicate detection**: Already enabled in v0.18.0+
+
+---
+
+**✅ SAFE TO USE**: This command is idempotent and safe to run multiple times.