specweave 0.32.0 → 0.32.3

package/plugins/specweave-ado/lib/ado-duplicate-detector.ts

@@ -0,0 +1,407 @@
+/**
+ * Azure DevOps Duplicate Detector (v0.33.0)
+ *
+ * Implements 3-phase duplicate protection for ADO work items:
+ * 1. Detection: Check before create
+ * 2. Verification: Count check after create
+ * 3. Reflection: Auto-close duplicates
+ *
+ * Mirrors the GitHub DuplicateDetector pattern for consistency.
+ */
+
+import { Logger, consoleLogger } from '../../../src/utils/logger.js';
+
+export interface AdoWorkItem {
+  id: number;
+  title: string;
+  state: string;
+  createdDate: string;
+  url?: string;
+}
+
+export interface DuplicateGroup {
+  title: string;
+  items: AdoWorkItem[];
+  keepItem: AdoWorkItem;
+  duplicates: AdoWorkItem[];
+}
+
+export interface DetectionResult {
+  found: boolean;
+  existingItem?: AdoWorkItem;
+  count: number;
+}
+
+export interface VerificationResult {
+  success: boolean;
+  expectedCount: number;
+  actualCount: number;
+  duplicates: AdoWorkItem[];
+}
+
+export interface CleanupResult {
+  closedCount: number;
+  keptCount: number;
+  errors: string[];
+}
+
+export class AdoDuplicateDetector {
+  private org: string;
+  private project: string;
+  private pat: string;
+  private logger: Logger;
+
+  constructor(options: {
+    org?: string;
+    project?: string;
+    pat?: string;
+    logger?: Logger;
+  } = {}) {
+    this.org = options.org || process.env.AZURE_DEVOPS_ORG || '';
+    this.project = options.project || process.env.AZURE_DEVOPS_PROJECT || '';
+    this.pat = options.pat || process.env.AZURE_DEVOPS_PAT || process.env.AZURE_DEVOPS_TOKEN || '';
+    this.logger = options.logger || consoleLogger;
+  }
+
+  /**
+   * Phase 1: Check if work item exists before creating
+   */
+  async checkBeforeCreate(
+    titlePattern: string,
+    incrementId?: string
+  ): Promise<DetectionResult> {
+    try {
+      const items = await this.searchWorkItems(titlePattern);
+
+      if (items.length > 0) {
+        return {
+          found: true,
+          existingItem: items[0],
+          count: items.length,
+        };
+      }
+
+      return { found: false, count: 0 };
+    } catch (error: any) {
+      this.logger.log(`⚠️  Detection check failed: ${error.message}`);
+      // Graceful degradation - continue anyway
+      return { found: false, count: 0 };
+    }
+  }
+
+  /**
+   * Phase 2: Verify count after creation
+   */
+  async verifyAfterCreate(
+    titlePattern: string,
+    expectedCount: number = 1
+  ): Promise<VerificationResult> {
+    try {
+      const items = await this.searchWorkItems(titlePattern);
+
+      if (items.length > expectedCount) {
+        // Duplicates detected!
+        const sorted = items.sort(
+          (a, b) => a.id - b.id // Sort by ID (lowest = oldest)
+        );
+
+        return {
+          success: false,
+          expectedCount,
+          actualCount: items.length,
+          duplicates: sorted.slice(expectedCount), // All items after expected count
+        };
+      }
+
+      return {
+        success: true,
+        expectedCount,
+        actualCount: items.length,
+        duplicates: [],
+      };
+    } catch (error: any) {
+      this.logger.log(`⚠️  Verification check failed: ${error.message}`);
+      return {
+        success: true, // Assume success on error
+        expectedCount,
+        actualCount: expectedCount,
+        duplicates: [],
+      };
+    }
+  }
+
+  /**
+   * Phase 3: Auto-close duplicates
+   */
+  async closeDuplicates(
+    duplicates: AdoWorkItem[],
+    keepItemId: number
+  ): Promise<CleanupResult> {
+    const result: CleanupResult = {
+      closedCount: 0,
+      keptCount: 1,
+      errors: [],
+    };
+
+    for (const item of duplicates) {
+      try {
+        await this.closeWorkItem(item.id, keepItemId);
+        result.closedCount++;
+        this.logger.log(`  ✅ Closed #${item.id} (duplicate of #${keepItemId})`);
+      } catch (error: any) {
+        result.errors.push(`#${item.id}: ${error.message}`);
+        this.logger.log(`  ❌ Failed to close #${item.id}: ${error.message}`);
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Full cleanup: Find and close all duplicates for a feature
+   */
+  async cleanupFeatureDuplicates(
+    featureId: string,
+    dryRun: boolean = false
+  ): Promise<{
+    groups: DuplicateGroup[];
+    totalItems: number;
+    duplicateCount: number;
+    closedCount: number;
+  }> {
+    // 1. Search for all work items with feature ID
+    const searchPattern = `[${featureId}]`;
+    const items = await this.searchWorkItems(searchPattern);
+
+    this.logger.log(`\n🔍 Scanning for duplicates in Feature ${featureId}...`);
+    this.logger.log(`   Found ${items.length} total work items`);
+
+    // 2. Group by title
+    const groups = this.groupByTitle(items);
+    const duplicateGroups = groups.filter(g => g.duplicates.length > 0);
+
+    if (duplicateGroups.length === 0) {
+      this.logger.log(`   ✅ No duplicates found!`);
+      return {
+        groups: [],
+        totalItems: items.length,
+        duplicateCount: 0,
+        closedCount: 0,
+      };
+    }
+
+    this.logger.log(`   Detected ${duplicateGroups.length} duplicate groups:\n`);
+
+    // 3. Display groups
+    for (let i = 0; i < duplicateGroups.length; i++) {
+      const group = duplicateGroups[i];
+      this.logger.log(`   📋 Group ${i + 1}: "${group.title.substring(0, 50)}..."`);
+      this.logger.log(`      - #${group.keepItem.id} (KEEP) - Created ${group.keepItem.createdDate.split('T')[0]}`);
+      for (const dup of group.duplicates) {
+        this.logger.log(`      - #${dup.id} (CLOSE) - Created ${dup.createdDate.split('T')[0]} - DUPLICATE`);
+      }
+      this.logger.log('');
+    }
+
+    const totalDuplicates = duplicateGroups.reduce((sum, g) => sum + g.duplicates.length, 0);
+
+    if (dryRun) {
+      this.logger.log(`\n✅ Dry run complete!`);
+      this.logger.log(`   Total work items: ${items.length}`);
+      this.logger.log(`   Duplicate groups: ${duplicateGroups.length}`);
+      this.logger.log(`   Work items to close: ${totalDuplicates}`);
+      this.logger.log(`\n⚠️  This was a DRY RUN - no changes made.`);
+
+      return {
+        groups: duplicateGroups,
+        totalItems: items.length,
+        duplicateCount: totalDuplicates,
+        closedCount: 0,
+      };
+    }
+
+    // 4. Close duplicates
+    let closedCount = 0;
+    this.logger.log(`🗑️  Closing duplicates...`);
+
+    for (const group of duplicateGroups) {
+      const result = await this.closeDuplicates(group.duplicates, group.keepItem.id);
+      closedCount += result.closedCount;
+    }
+
+    this.logger.log(`\n✅ Cleanup complete!`);
+    this.logger.log(`   Closed: ${closedCount} duplicates`);
+    this.logger.log(`   Kept: ${duplicateGroups.length} original work items`);
+
+    return {
+      groups: duplicateGroups,
+      totalItems: items.length,
+      duplicateCount: totalDuplicates,
+      closedCount,
+    };
+  }
+
+  /**
+   * Group work items by title
+   */
+  private groupByTitle(items: AdoWorkItem[]): DuplicateGroup[] {
+    const titleMap = new Map<string, AdoWorkItem[]>();
+
+    for (const item of items) {
+      const existing = titleMap.get(item.title) || [];
+      existing.push(item);
+      titleMap.set(item.title, existing);
+    }
+
+    const groups: DuplicateGroup[] = [];
+
+    for (const [title, groupItems] of titleMap) {
+      // Sort by ID (lowest = oldest)
+      const sorted = groupItems.sort((a, b) => a.id - b.id);
+
+      groups.push({
+        title,
+        items: sorted,
+        keepItem: sorted[0],
+        duplicates: sorted.slice(1),
+      });
+    }
+
+    return groups;
+  }
+
+  /**
+   * Search for work items using WIQL
+   */
+  private async searchWorkItems(titlePattern: string): Promise<AdoWorkItem[]> {
+    if (!this.org || !this.pat) {
+      throw new Error('ADO credentials not configured');
+    }
+
+    const wiql = {
+      query: `SELECT [System.Id], [System.Title], [System.State], [System.CreatedDate]
+              FROM WorkItems
+              WHERE [System.TeamProject] = '${this.project}'
+              AND [System.Title] CONTAINS '${titlePattern}'
+              ORDER BY [System.Id] ASC`,
+    };
+
+    const auth = Buffer.from(`:${this.pat}`).toString('base64');
+    const url = `https://dev.azure.com/${this.org}/${this.project}/_apis/wit/wiql?api-version=7.1`;
+
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: {
+        Authorization: `Basic ${auth}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(wiql),
+    });
+
+    if (!response.ok) {
+      throw new Error(`WIQL query failed: ${response.status}`);
+    }
+
+    const data = await response.json();
+    const workItemIds = data.workItems?.map((wi: any) => wi.id) || [];
+
+    if (workItemIds.length === 0) {
+      return [];
+    }
+
+    // Fetch full work item details
+    return this.getWorkItemDetails(workItemIds);
+  }
+
+  /**
+   * Get work item details by IDs
+   */
+  private async getWorkItemDetails(ids: number[]): Promise<AdoWorkItem[]> {
+    if (ids.length === 0) return [];
+
+    const auth = Buffer.from(`:${this.pat}`).toString('base64');
+    const url = `https://dev.azure.com/${this.org}/_apis/wit/workitems?ids=${ids.join(',')}&api-version=7.1`;
+
+    const response = await fetch(url, {
+      headers: {
+        Authorization: `Basic ${auth}`,
+        'Content-Type': 'application/json',
+      },
+    });
+
+    if (!response.ok) {
+      throw new Error(`Failed to get work items: ${response.status}`);
+    }
+
+    const data = await response.json();
+    return (data.value || []).map((wi: any) => ({
+      id: wi.id,
+      title: wi.fields['System.Title'],
+      state: wi.fields['System.State'],
+      createdDate: wi.fields['System.CreatedDate'],
+      url: wi._links?.html?.href,
+    }));
+  }
+
+  /**
+   * Close a work item with duplicate comment
+   */
+  private async closeWorkItem(workItemId: number, originalId: number): Promise<void> {
+    const auth = Buffer.from(`:${this.pat}`).toString('base64');
+    const url = `https://dev.azure.com/${this.org}/_apis/wit/workitems/${workItemId}?api-version=7.1`;
+
+    const comment = `## Duplicate of #${originalId}
+
+This work item was automatically closed by SpecWeave cleanup because it is a duplicate.
+
+The original work item (#${originalId}) contains the same content and should be used for tracking instead.
+
+---
+🤖 Auto-closed by SpecWeave Duplicate Cleanup`;
+
+    const operations = [
+      {
+        op: 'add',
+        path: '/fields/System.State',
+        value: 'Closed',
+      },
+      {
+        op: 'add',
+        path: '/fields/System.History',
+        value: comment,
+      },
+    ];
+
+    const response = await fetch(url, {
+      method: 'PATCH',
+      headers: {
+        Authorization: `Basic ${auth}`,
+        'Content-Type': 'application/json-patch+json',
+      },
+      body: JSON.stringify(operations),
+    });
+
+    if (!response.ok) {
+      const error = await response.text();
+      throw new Error(`Failed to close work item: ${response.status} - ${error}`);
+    }
+  }
+}
+
+/**
+ * Convenience function for quick duplicate cleanup
+ */
+export async function cleanupAdoDuplicates(
+  featureId: string,
+  dryRun: boolean = false
+): Promise<{
+  groups: DuplicateGroup[];
+  totalItems: number;
+  duplicateCount: number;
+  closedCount: number;
+}> {
+  const detector = new AdoDuplicateDetector();
+  return detector.cleanupFeatureDuplicates(featureId, dryRun);
+}
+
+export default AdoDuplicateDetector;

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-docs/commands/build.md

@@ -1,19 +1,47 @@
 ---
 name: specweave-docs:build
-description: Build static documentation site for deployment. Auto-setup on first run. Outputs production-ready HTML/CSS/JS.
+description: Build static documentation site for deployment. Validates docs first, auto-fixes issues, auto-setup on first run. Outputs production-ready HTML/CSS/JS.
 ---
 
 # Documentation Build Command
 
 Build production-ready static documentation site for deployment to any static host.
 
+**CRITICAL**: Runs pre-flight validation to catch issues BEFORE building.
+
 ## Your Task
 
 **IMPORTANT**: This command must work in ANY SpecWeave user project, not just the SpecWeave repo itself.
 
-### Step 1: Ensure Docusaurus is Set Up
+### Step 1: CRITICAL - Run Pre-Flight Validation
+
+**ALWAYS validate BEFORE building to prevent cryptic webpack errors!**
+
+```typescript
+import { DocsValidator } from '../../../src/utils/docs-validator.js';
+
+const validator = new DocsValidator({
+  docsPath: '.specweave/docs/internal',
+  autoFix: true,  // Auto-fix common issues
+});
+
+console.log('\n🔍 Running pre-build validation...\n');
+const result = await validator.validate();
+
+// Show summary
+console.log(DocsValidator.formatResult(result));
+
+// If errors remain after auto-fix, STOP and report
+if (!result.valid) {
+  console.log('\n❌ Documentation has errors that must be fixed before build.');
+  console.log('   Fix the issues above, then try again.\n');
+  process.exit(1);
+}
+
+console.log('\n✅ Validation passed! Proceeding with build...\n');
+```
 
-First, ensure the cached Docusaurus installation exists:
+### Step 2: Ensure Docusaurus is Set Up
 
 ```bash
 # Check if Docusaurus is set up
@@ -26,7 +54,7 @@ fi
 
 If not set up, follow the same setup steps as `/specweave-docs:preview` (Step 3 in preview.md).
 
-### Step 2: Run Build
+### Step 3: Run Build
 
 ```bash
 cd .specweave/cache/docs-site && npm run build

package/plugins/specweave-docs/commands/preview.md

@@ -1,12 +1,14 @@
 ---
 name: specweave-docs:preview
-description: Launch Docusaurus documentation server for internal living docs. Auto-setup on first run. Port 3015.
+description: Launch Docusaurus documentation server for internal living docs. Validates docs first, auto-fixes issues, auto-setup on first run. Port 3015.
 ---
 
 # Documentation Preview Command
 
 Launch Docusaurus development server with hot reload, Mermaid diagrams, and auto-generated sidebar.
 
+**CRITICAL**: Runs pre-flight validation to catch issues BEFORE starting the server.
+
 ## Your Task
 
 **IMPORTANT**: This command must work in ANY SpecWeave user project, not just the SpecWeave repo itself.
@@ -22,6 +24,46 @@ ls -la .specweave/docs/internal/
 #  Run 'specweave init' first or create the folder structure."
 ```
 
+### Step 1.5: CRITICAL - Run Pre-Flight Validation
+
+**ALWAYS run validation BEFORE starting the server!**
+
+```typescript
+import { DocsValidator } from '../../../src/utils/docs-validator.js';
+
+const validator = new DocsValidator({
+  docsPath: '.specweave/docs/internal',
+  autoFix: true,  // Auto-fix common issues
+});
+
+console.log('\n🔍 Running pre-flight validation...\n');
+const result = await validator.validate();
+
+// Show summary
+console.log(DocsValidator.formatResult(result));
+
+// If errors remain after auto-fix, STOP and report
+if (!result.valid) {
+  console.log('\n❌ Documentation has errors that must be fixed before preview.');
+  console.log('   Fix the issues above, then try again.\n');
+  process.exit(1);
+}
+
+console.log('\n✅ Validation passed! Starting server...\n');
+```
+
+**What this catches:**
+- YAML frontmatter errors (unquoted colons, tabs)
+- MDX compatibility issues (unquoted attributes, unclosed tags)
+- Duplicate routes
+- Broken internal links
+
+**Auto-fixes applied:**
+- Wraps YAML values with colons in quotes
+- Quotes HTML attributes
+- Adds closing slashes to void elements (`<br>` → `<br />`)
+- Converts tabs to spaces in YAML
+
 ### Step 2: Check for Cached Installation
 
 ```bash