specweave 0.12.1 → 0.12.2

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

@@ -0,0 +1,593 @@
+/**
+ * Azure DevOps Spec Sync
+ *
+ * CORRECT ARCHITECTURE:
+ * - Syncs .specweave/docs/internal/specs/spec-*.md ↔ ADO Features
+ * - NOT increments ↔ ADO Work Items (that was wrong!)
+ *
+ * Mapping:
+ * - Spec → ADO Feature
+ * - User Story → ADO User Story (child of feature)
+ * - Acceptance Criteria → Checklist in User Story description
+ *
+ * @module ado-spec-sync
+ */
+
+import { SpecMetadataManager } from '../../../src/core/specs/spec-metadata-manager.js';
+import { SpecParser } from '../../../src/core/specs/spec-parser.js';
+import {
+  SpecContent,
+  UserStory,
+  SpecSyncResult,
+  SpecSyncConflict
+} from '../../../src/core/types/spec-metadata.js';
+import { execFileNoThrow } from '../../../src/utils/execFileNoThrow.js';
+import axios, { AxiosInstance } from 'axios';
+
+export interface AdoFeature {
+  id: number;
+  url: string;
+  fields: {
+    'System.Title': string;
+    'System.Description': string;
+    'System.State': string; // New, Active, Resolved, Closed
+    'System.Tags': string;
+  };
+}
+
+export interface AdoUserStory {
+  id: number;
+  url: string;
+  fields: {
+    'System.Title': string;
+    'System.Description': string;
+    'System.State': string;
+    'System.Parent': number; // Feature ID
+    'System.Tags': string;
+  };
+}
+
+export interface AdoConfig {
+  organization: string; // e.g., mycompany
+  project: string; // e.g., MyProject
+  personalAccessToken: string;
+}
+
+export class AdoSpecSync {
+  private specManager: SpecMetadataManager;
+  private client: AxiosInstance;
+  private config: AdoConfig;
+
+  constructor(config: AdoConfig, projectRoot: string = process.cwd()) {
+    this.specManager = new SpecMetadataManager(projectRoot);
+    this.config = config;
+
+    // Create ADO API client
+    this.client = axios.create({
+      baseURL: `https://dev.azure.com/${config.organization}/${config.project}/_apis`,
+      auth: {
+        username: '', // Empty for PAT auth
+        password: config.personalAccessToken
+      },
+      headers: {
+        'Content-Type': 'application/json-patch+json',
+        'Accept': 'application/json'
+      }
+    });
+  }
+
+  /**
+   * Sync spec to ADO Feature (CREATE or UPDATE)
+   */
+  async syncSpecToAdo(specId: string): Promise<SpecSyncResult> {
+    console.log(`\n🔄 Syncing spec ${specId} to ADO Feature...`);
+
+    try {
+      // 1. Load spec
+      const spec = await this.specManager.loadSpec(specId);
+      if (!spec) {
+        return {
+          success: false,
+          specId,
+          provider: 'ado',
+          error: `Spec ${specId} not found`
+        };
+      }
+
+      // 2. Check if spec already linked to ADO Feature
+      const existingLink = spec.metadata.externalLinks?.ado;
+
+      let feature: AdoFeature;
+
+      if (existingLink?.featureId) {
+        // UPDATE existing feature
+        console.log(`   Found existing ADO Feature #${existingLink.featureId}`);
+        feature = await this.updateAdoFeature(existingLink.featureId, spec);
+      } else {
+        // CREATE new feature
+        console.log('   Creating new ADO Feature...');
+        feature = await this.createAdoFeature(spec);
+
+        // Link spec to feature
+        await this.specManager.linkToExternal(specId, 'ado', {
+          id: feature.id,
+          url: feature.url,
+          organization: this.config.organization,
+          project: this.config.project
+        });
+      }
+
+      // 3. Sync user stories as ADO User Stories
+      const changes = await this.syncUserStories(feature.id, spec);
+
+      console.log('✅ Sync complete!');
+
+      return {
+        success: true,
+        specId,
+        provider: 'ado',
+        externalId: feature.id.toString(),
+        url: feature.url,
+        changes
+      };
+
+    } catch (error) {
+      console.error('❌ Error syncing to ADO:', error);
+      return {
+        success: false,
+        specId,
+        provider: 'ado',
+        error: error instanceof Error ? error.message : 'Unknown error'
+      };
+    }
+  }
+
+  /**
+   * Sync FROM ADO Feature to spec (bidirectional)
+   */
+  async syncFromAdo(specId: string): Promise<SpecSyncResult> {
+    console.log(`\n🔄 Syncing FROM ADO to spec ${specId}...`);
+
+    try {
+      // 1. Load spec
+      const spec = await this.specManager.loadSpec(specId);
+      if (!spec) {
+        return {
+          success: false,
+          specId,
+          provider: 'ado',
+          error: `Spec ${specId} not found`
+        };
+      }
+
+      // 2. Get ADO Feature link
+      const adoLink = spec.metadata.externalLinks?.ado;
+      if (!adoLink?.featureId) {
+        return {
+          success: false,
+          specId,
+          provider: 'ado',
+          error: 'Spec not linked to ADO Feature'
+        };
+      }
+
+      // 3. Fetch ADO Feature state
+      const feature = await this.fetchAdoFeature(adoLink.featureId);
+
+      // 4. Detect conflicts
+      const conflicts = await this.detectConflicts(spec, feature);
+
+      if (conflicts.length === 0) {
+        console.log('✅ No conflicts - spec and ADO in sync');
+        return {
+          success: true,
+          specId,
+          provider: 'ado',
+          externalId: feature.id.toString(),
+          url: feature.url
+        };
+      }
+
+      console.log(`⚠️  Detected ${conflicts.length} conflict(s)`);
+
+      // 5. Resolve conflicts (ADO wins by default for now)
+      await this.resolveConflicts(spec, conflicts);
+
+      console.log('✅ Sync FROM ADO complete!');
+
+      return {
+        success: true,
+        specId,
+        provider: 'ado',
+        externalId: feature.id.toString(),
+        url: feature.url,
+        conflicts
+      };
+
+    } catch (error) {
+      console.error('❌ Error syncing FROM ADO:', error);
+      return {
+        success: false,
+        specId,
+        provider: 'ado',
+        error: error instanceof Error ? error.message : 'Unknown error'
+      };
+    }
+  }
+
+  /**
+   * Create new ADO Feature for spec
+   */
+  private async createAdoFeature(spec: SpecContent): Promise<AdoFeature> {
+    const featureTitle = `[${spec.metadata.id.toUpperCase()}] ${spec.metadata.title}`;
+    const featureDescription = this.generateFeatureDescription(spec);
+    const tags = [`spec:${spec.metadata.id}`, `priority:${spec.metadata.priority}`].join('; ');
+
+    const payload = [
+      {
+        op: 'add',
+        path: '/fields/System.Title',
+        value: featureTitle
+      },
+      {
+        op: 'add',
+        path: '/fields/System.Description',
+        value: featureDescription
+      },
+      {
+        op: 'add',
+        path: '/fields/System.WorkItemType',
+        value: 'Feature'
+      },
+      {
+        op: 'add',
+        path: '/fields/System.Tags',
+        value: tags
+      }
+    ];
+
+    const response = await this.client.post('/wit/workitems/$Feature?api-version=7.0', payload);
+    const featureData = response.data;
+
+    console.log(`   ✅ Created ADO Feature #${featureData.id}: ${featureData._links.html.href}`);
+
+    return {
+      id: featureData.id,
+      url: featureData._links.html.href,
+      fields: featureData.fields
+    };
+  }
+
+  /**
+   * Update existing ADO Feature
+   */
+  private async updateAdoFeature(featureId: number, spec: SpecContent): Promise<AdoFeature> {
+    const featureTitle = `[${spec.metadata.id.toUpperCase()}] ${spec.metadata.title}`;
+    const featureDescription = this.generateFeatureDescription(spec);
+
+    const payload = [
+      {
+        op: 'replace',
+        path: '/fields/System.Title',
+        value: featureTitle
+      },
+      {
+        op: 'replace',
+        path: '/fields/System.Description',
+        value: featureDescription
+      }
+    ];
+
+    const response = await this.client.patch(
+      `/wit/workitems/${featureId}?api-version=7.0`,
+      payload
+    );
+    const featureData = response.data;
+
+    console.log(`   ✅ Updated ADO Feature #${featureId}`);
+
+    return {
+      id: featureData.id,
+      url: featureData._links.html.href,
+      fields: featureData.fields
+    };
+  }
+
+  /**
+   * Sync user stories as ADO User Stories
+   */
+  private async syncUserStories(
+    featureId: number,
+    spec: SpecContent
+  ): Promise<{ created: string[]; updated: string[]; deleted: string[] }> {
+    const created: string[] = [];
+    const updated: string[] = [];
+    const deleted: string[] = [];
+
+    if (!spec.metadata.userStories || spec.metadata.userStories.length === 0) {
+      console.log('   ℹ️  No user stories to sync');
+      return { created, updated, deleted };
+    }
+
+    console.log(`   Syncing ${spec.metadata.userStories.length} user stories...`);
+
+    for (const us of spec.metadata.userStories) {
+      // Create or update ADO User Story for each user story
+      const storyTitle = `[${us.id}] ${us.title}`;
+      const storyDescription = this.generateStoryDescription(us);
+
+      // Check if story already exists (by searching for US-ID in title)
+      const existingStory = await this.findStoryByTitle(us.id);
+
+      if (existingStory) {
+        // UPDATE existing story
+        await this.updateStory(existingStory.id, {
+          title: storyTitle,
+          description: storyDescription,
+          state: us.status === 'done' ? 'Closed' : us.status === 'in-progress' ? 'Active' : 'New'
+        });
+
+        updated.push(us.id);
+        console.log(`   ✅ Updated ${us.id}`);
+      } else {
+        // CREATE new story
+        const newStory = await this.createStory({
+          title: storyTitle,
+          description: storyDescription,
+          parentId: featureId,
+          tags: [`user-story`, `spec:${spec.metadata.id}`, `priority:${us.priority}`].join('; ')
+        });
+
+        created.push(us.id);
+        console.log(`   ✅ Created ${us.id} → User Story #${newStory.id}`);
+      }
+    }
+
+    return { created, updated, deleted };
+  }
+
+  /**
+   * Generate feature description from spec
+   */
+  private generateFeatureDescription(spec: SpecContent): string {
+    const progress = spec.metadata.progress;
+    const progressText = progress
+      ? `**Progress**: ${progress.percentComplete}% (${progress.completedUserStories}/${progress.totalUserStories} user stories)`
+      : '**Progress**: N/A';
+
+    return `
+<h1>${spec.metadata.title}</h1>
+
+<p><strong>Spec ID</strong>: ${spec.metadata.id}</p>
+<p><strong>Priority</strong>: ${spec.metadata.priority}</p>
+<p><strong>Status</strong>: ${spec.metadata.status}</p>
+<p>${progressText}</p>
+
+<hr>
+
+${SpecParser.extractOverview(spec.markdown).replace(/\n/g, '<br>')}
+
+<hr>
+
+<h2>User Stories</h2>
+
+<p>${spec.metadata.userStories?.length || 0} user stories tracked in this feature.</p>
+
+<hr>
+
+<p>🤖 <strong>Auto-synced from SpecWeave</strong><br>
+Last updated: ${new Date().toISOString()}</p>
+`.trim();
+  }
+
+  /**
+   * Generate story description from user story
+   */
+  private generateStoryDescription(us: UserStory): string {
+    const acList = us.acceptanceCriteria
+      .map(ac => `<li>${ac.status === 'done' ? '☑' : '☐'} ${ac.description}</li>`)
+      .join('\n');
+
+    return `
+<h2>User Story</h2>
+
+<p>${us.title}</p>
+
+<h2>Acceptance Criteria</h2>
+
+<ul>
+${acList}
+</ul>
+
+<hr>
+
+<p><strong>Priority</strong>: ${us.priority}</p>
+<p><strong>Status</strong>: ${us.status}</p>
+
+<p>🤖 <strong>Auto-synced from SpecWeave</strong></p>
+`.trim();
+  }
+
+  /**
+   * Detect conflicts between spec and ADO
+   */
+  private async detectConflicts(
+    spec: SpecContent,
+    feature: AdoFeature
+  ): Promise<SpecSyncConflict[]> {
+    const conflicts: SpecSyncConflict[] = [];
+
+    // Compare feature title
+    const expectedTitle = `[${spec.metadata.id.toUpperCase()}] ${spec.metadata.title}`;
+    if (feature.fields['System.Title'] !== expectedTitle) {
+      conflicts.push({
+        type: 'metadata',
+        field: 'title',
+        localValue: spec.metadata.title,
+        remoteValue: feature.fields['System.Title'],
+        resolution: 'remote-wins',
+        description: 'Feature title differs from spec title'
+      });
+    }
+
+    // TODO: Compare user stories and their statuses
+
+    return conflicts;
+  }
+
+  /**
+   * Resolve conflicts
+   */
+  private async resolveConflicts(
+    spec: SpecContent,
+    conflicts: SpecSyncConflict[]
+  ): Promise<void> {
+    for (const conflict of conflicts) {
+      if (conflict.resolution === 'remote-wins') {
+        console.log(`   🔄 Resolving: ${conflict.description} (ADO wins)`);
+        // Update spec metadata from ADO
+        if (conflict.field === 'title') {
+          await this.specManager.saveMetadata(spec.metadata.id, {
+            title: conflict.remoteValue
+          });
+        }
+      }
+    }
+  }
+
+  /**
+   * Fetch ADO Feature details
+   */
+  private async fetchAdoFeature(featureId: number): Promise<AdoFeature> {
+    const response = await this.client.get(`/wit/workitems/${featureId}?api-version=7.0`);
+    const featureData = response.data;
+
+    return {
+      id: featureData.id,
+      url: featureData._links.html.href,
+      fields: featureData.fields
+    };
+  }
+
+  /**
+   * Find story by title pattern
+   */
+  private async findStoryByTitle(usId: string): Promise<AdoUserStory | null> {
+    const wiql = `
+      SELECT [System.Id], [System.Title], [System.Description], [System.State]
+      FROM WorkItems
+      WHERE [System.TeamProject] = '${this.config.project}'
+        AND [System.WorkItemType] = 'User Story'
+        AND [System.Title] CONTAINS '[${usId}]'
+    `;
+
+    const response = await this.client.post('/wit/wiql?api-version=7.0', {
+      query: wiql
+    });
+
+    const workItems = response.data.workItems;
+    if (workItems.length === 0) {
+      return null;
+    }
+
+    // Fetch full work item details
+    const workItemId = workItems[0].id;
+    const detailsResponse = await this.client.get(`/wit/workitems/${workItemId}?api-version=7.0`);
+    const storyData = detailsResponse.data;
+
+    return {
+      id: storyData.id,
+      url: storyData._links.html.href,
+      fields: storyData.fields
+    };
+  }
+
+  /**
+   * Create ADO User Story
+   */
+  private async createStory(story: {
+    title: string;
+    description: string;
+    parentId: number;
+    tags: string;
+  }): Promise<AdoUserStory> {
+    const payload = [
+      {
+        op: 'add',
+        path: '/fields/System.Title',
+        value: story.title
+      },
+      {
+        op: 'add',
+        path: '/fields/System.Description',
+        value: story.description
+      },
+      {
+        op: 'add',
+        path: '/fields/System.WorkItemType',
+        value: 'User Story'
+      },
+      {
+        op: 'add',
+        path: '/fields/System.Tags',
+        value: story.tags
+      },
+      {
+        op: 'add',
+        path: '/relations/-',
+        value: {
+          rel: 'System.LinkTypes.Hierarchy-Reverse',
+          url: `https://dev.azure.com/${this.config.organization}/${this.config.project}/_apis/wit/workitems/${story.parentId}`,
+          attributes: {
+            name: 'Parent'
+          }
+        }
+      }
+    ];
+
+    const response = await this.client.post('/wit/workitems/$User%20Story?api-version=7.0', payload);
+    const storyData = response.data;
+
+    return {
+      id: storyData.id,
+      url: storyData._links.html.href,
+      fields: storyData.fields
+    };
+  }
+
+  /**
+   * Update ADO User Story
+   */
+  private async updateStory(
+    storyId: number,
+    updates: { title?: string; description?: string; state?: string }
+  ): Promise<void> {
+    const payload: any[] = [];
+
+    if (updates.title) {
+      payload.push({
+        op: 'replace',
+        path: '/fields/System.Title',
+        value: updates.title
+      });
+    }
+
+    if (updates.description) {
+      payload.push({
+        op: 'replace',
+        path: '/fields/System.Description',
+        value: updates.description
+      });
+    }
+
+    if (updates.state) {
+      payload.push({
+        op: 'replace',
+        path: '/fields/System.State',
+        value: updates.state
+      });
+    }
+
+    await this.client.patch(`/wit/workitems/${storyId}?api-version=7.0`, payload);
+  }
+}

package/plugins/specweave-ado/skills/ado-sync/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ado-sync
-description: Bidirectional synchronization between SpecWeave increments and Azure DevOps work items (two-way sync by default). Creates work items from increments, tracks progress via comments, updates increment status from work item state, syncs changes in both directions automatically. Activates for: Azure DevOps, ADO, work items, project management, sync to ADO, ADO integration, TFS integration, bidirectional ADO sync.
+description: Bidirectional synchronization between SpecWeave increments and Azure DevOps work items (two-way sync by default). Activates ONLY when user asks questions about Azure DevOps integration or needs help configuring ADO sync. Does NOT activate for slash commands. For syncing, use /specweave-ado:sync command instead.
 ---
 
 # Azure DevOps Sync Skill
@@ -9,6 +9,8 @@ description: Bidirectional synchronization between SpecWeave increments and Azur
 
 **Default Behavior**: **Bidirectional (two-way) sync** - Changes in either system are automatically synchronized
 
+**⚠️ IMPORTANT**: This skill provides HELP and GUIDANCE about Azure DevOps sync. For actual syncing, users should use the `/specweave-ado:sync` command directly. This skill should NOT auto-activate when the command is being invoked.
+
 **Capabilities**:
 - Bidirectional sync: SpecWeave ↔ ADO (default)
 - Create ADO work items from increments
@@ -22,12 +24,16 @@ description: Bidirectional synchronization between SpecWeave increments and Azur
 
 ## When This Skill Activates
 
-**Keywords**: Azure DevOps, ADO, work items, sync to ADO, ADO integration, TFS, Visual Studio Team Services
+✅ **Do activate when**:
+- User asks: "How do I set up Azure DevOps sync?"
+- User asks: "What ADO credentials do I need?"
+- User asks: "How does ADO integration work?"
+- User needs help configuring Azure DevOps integration
 
-**Examples**:
-- "Sync this increment with Azure DevOps"
-- "Create ADO work item for this feature"
-- "Update work item #12345 with progress"
+❌ **Do NOT activate when**:
+- User invokes `/specweave-ado:sync` command (command handles it)
+- Command is already running (avoid duplicate invocation)
+- Task completion hook is syncing (automatic process)
 - "Close ADO work item when done"
 
 ---