specweave 1.0.488 → 1.0.490

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

@@ -8,6 +8,7 @@
  */
 
 import https from 'https';
+import { AdoRateLimiter } from './ado-rate-limiter.js';
 
 // ============================================================================
 // Types
@@ -20,6 +21,8 @@ export interface AdoConfig {
   workItemType?: 'Epic' | 'Feature' | 'User Story';
   areaPath?: string;
   iterationPath?: string;
+  /** Optional rate limiter instance (shared across client instances) */
+  rateLimiter?: AdoRateLimiter;
 }
 
 export interface WorkItem {
@@ -70,11 +73,13 @@ export class AdoClient {
   private config: AdoConfig;
   private baseUrl: string;
   private authHeader: string;
+  private rateLimiter?: AdoRateLimiter;
 
   constructor(config: AdoConfig) {
     this.config = config;
     this.baseUrl = `https://dev.azure.com/${config.organization}/${config.project}`;
-    
+    this.rateLimiter = config.rateLimiter;
+
     // Basic Auth: base64(":PAT")
     this.authHeader = 'Basic ' + Buffer.from(`:${config.personalAccessToken}`).toString('base64');
   }
@@ -207,6 +212,21 @@ export class AdoClient {
     await this.request('DELETE', url);
   }
 
+  /**
+   * Pull the current state of a work item for bidirectional sync.
+   *
+   * @param id - ADO work item ID
+   * @returns state and last-modified timestamp
+   */
+  async pullWorkItemState(id: number): Promise<{ state: string; modifiedAt: Date }> {
+    const url = `${this.baseUrl}/_apis/wit/workitems/${id}?$select=System.State,System.ChangedDate&api-version=7.1`;
+    const item = await this.request<WorkItem>('GET', url);
+    return {
+      state: item.fields['System.State'],
+      modifiedAt: new Date(item.fields['System.ChangedDate']),
+    };
+  }
+
   // ==========================================================================
   // Comment Operations
   // ==========================================================================
@@ -275,6 +295,11 @@ export class AdoClient {
     body?: any,
     additionalHeaders?: Record<string, string>
   ): Promise<T> {
+    // Check rate limiter before making request
+    if (this.rateLimiter && !this.rateLimiter.consume()) {
+      throw new Error('ADO rate limit exceeded — try again later');
+    }
+
     return new Promise((resolve, reject) => {
       const urlObj = new URL(url);
 
@@ -308,6 +333,14 @@ export class AdoClient {
               reject(new Error(`Failed to parse JSON response: ${error}`));
             }
           } else {
+            // Handle 429 Too Many Requests — apply Retry-After
+            if (res.statusCode === 429 && this.rateLimiter) {
+              const retryAfter = parseInt(res.headers['retry-after'] as string, 10);
+              if (retryAfter > 0) {
+                this.rateLimiter.applyRetryAfter(retryAfter);
+              }
+            }
+
             let errorMessage = `ADO API error: ${res.statusCode} ${res.statusMessage}`;
             try {
               const errorData = JSON.parse(data);
@@ -317,7 +350,9 @@ export class AdoClient {
             } catch {
               // Ignore JSON parse errors for error responses
             }
-            reject(new Error(errorMessage));
+            const err: any = new Error(errorMessage);
+            err.status = res.statusCode;
+            reject(err);
           }
         });
       });

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

@@ -0,0 +1,35 @@
+function mapAdoStateToSpecweave(adoState) {
+  const map = {
+    "New": "planned",
+    "To Do": "planned",
+    "Active": "active",
+    "Doing": "active",
+    "In Progress": "active",
+    "Resolved": "completed",
+    "Closed": "completed",
+    "Done": "completed",
+    "Removed": "abandoned"
+  };
+  return map[adoState] ?? "active";
+}
+function pullAdoChanges(ctx) {
+  if (!ctx.canUpsertInternalItems) {
+    return { changed: false, reason: "canUpsertInternalItems is false" };
+  }
+  const mappedStatus = mapAdoStateToSpecweave(ctx.adoState);
+  if (mappedStatus === ctx.localStatus) {
+    return { changed: false, reason: "states are equivalent" };
+  }
+  if (ctx.adoModifiedAt.getTime() <= ctx.localUpdatedAt.getTime()) {
+    return { changed: false, reason: "local is newer" };
+  }
+  return {
+    changed: true,
+    newStatus: mappedStatus,
+    reason: `ADO state "${ctx.adoState}" is newer \u2014 updating to "${mappedStatus}"`
+  };
+}
+export {
+  mapAdoStateToSpecweave,
+  pullAdoChanges
+};

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

@@ -0,0 +1,74 @@
+/**
+ * ADO Pull Sync — Bidirectional state synchronization
+ *
+ * Implements last-write-wins conflict resolution for pulling
+ * ADO work item state changes back into SpecWeave metadata.
+ *
+ * @module ado-pull-sync
+ */
+
+export interface PullSyncContext {
+  localStatus: string;
+  localUpdatedAt: Date;
+  adoState: string;
+  adoModifiedAt: Date;
+  workItemId: number;
+  canUpsertInternalItems: boolean;
+}
+
+export interface PullSyncResult {
+  changed: boolean;
+  newStatus?: string;
+  reason?: string;
+}
+
+/**
+ * Map ADO work item states to SpecWeave statuses.
+ *
+ * Covers Agile/Scrum/Basic process templates.
+ */
+export function mapAdoStateToSpecweave(adoState: string): string {
+  const map: Record<string, string> = {
+    'New': 'planned',
+    'To Do': 'planned',
+    'Active': 'active',
+    'Doing': 'active',
+    'In Progress': 'active',
+    'Resolved': 'completed',
+    'Closed': 'completed',
+    'Done': 'completed',
+    'Removed': 'abandoned',
+  };
+
+  return map[adoState] ?? 'active';
+}
+
+/**
+ * Determine if ADO changes should override local state.
+ *
+ * Uses last-write-wins: if ADO was modified more recently than local,
+ * and the mapped state differs, update local metadata.
+ */
+export function pullAdoChanges(ctx: PullSyncContext): PullSyncResult {
+  if (!ctx.canUpsertInternalItems) {
+    return { changed: false, reason: 'canUpsertInternalItems is false' };
+  }
+
+  const mappedStatus = mapAdoStateToSpecweave(ctx.adoState);
+
+  // Same effective status — no change needed
+  if (mappedStatus === ctx.localStatus) {
+    return { changed: false, reason: 'states are equivalent' };
+  }
+
+  // Last-write-wins: ADO must be newer
+  if (ctx.adoModifiedAt.getTime() <= ctx.localUpdatedAt.getTime()) {
+    return { changed: false, reason: 'local is newer' };
+  }
+
+  return {
+    changed: true,
+    newStatus: mappedStatus,
+    reason: `ADO state "${ctx.adoState}" is newer — updating to "${mappedStatus}"`,
+  };
+}

package/plugins/specweave-ado/lib/ado-rate-limiter.js

@@ -0,0 +1,56 @@
+class AdoRateLimiter {
+  constructor(options) {
+    this.capacity = options?.capacity ?? 200;
+    this.windowMs = options?.windowMs ?? 6e4;
+    this.tokens = this.capacity;
+    this.windowStart = Date.now();
+    this.retryAfterUntil = 0;
+  }
+  /**
+   * Try to consume one token. Returns true if allowed, false if exhausted.
+   */
+  consume() {
+    this.refillIfWindowExpired();
+    if (Date.now() < this.retryAfterUntil) {
+      return false;
+    }
+    if (this.tokens <= 0) {
+      return false;
+    }
+    this.tokens--;
+    return true;
+  }
+  /**
+   * Number of tokens remaining in the current window.
+   */
+  remaining() {
+    this.refillIfWindowExpired();
+    return this.tokens;
+  }
+  /**
+   * Whether the bucket is fully exhausted (0 tokens remaining).
+   */
+  isExhausted() {
+    this.refillIfWindowExpired();
+    return this.tokens <= 0;
+  }
+  /**
+   * Apply a Retry-After delay (from ADO 429 response).
+   * Blocks all consumption until the delay expires.
+   *
+   * @param seconds - Number of seconds to wait
+   */
+  applyRetryAfter(seconds) {
+    this.retryAfterUntil = Date.now() + seconds * 1e3;
+  }
+  refillIfWindowExpired() {
+    const now = Date.now();
+    if (now - this.windowStart >= this.windowMs) {
+      this.tokens = this.capacity;
+      this.windowStart = now;
+    }
+  }
+}
+export {
+  AdoRateLimiter
+};

package/plugins/specweave-ado/lib/ado-rate-limiter.ts

@@ -0,0 +1,86 @@
+/**
+ * ADO Token Bucket Rate Limiter
+ *
+ * Simple token bucket that prevents exceeding Azure DevOps API rate limits.
+ * ADO's documented limit is ~200 requests per minute for PAT-based auth.
+ *
+ * Supports Retry-After header handling: when ADO returns 429, call
+ * applyRetryAfter(seconds) to block consumption until the cooldown expires.
+ *
+ * @module ado-rate-limiter
+ */
+
+export interface AdoRateLimiterOptions {
+  /** Max tokens per window (default: 200) */
+  capacity?: number;
+  /** Window duration in ms (default: 60000 = 1 minute) */
+  windowMs?: number;
+}
+
+export class AdoRateLimiter {
+  private readonly capacity: number;
+  private readonly windowMs: number;
+  private tokens: number;
+  private windowStart: number;
+  private retryAfterUntil: number;
+
+  constructor(options?: AdoRateLimiterOptions) {
+    this.capacity = options?.capacity ?? 200;
+    this.windowMs = options?.windowMs ?? 60_000;
+    this.tokens = this.capacity;
+    this.windowStart = Date.now();
+    this.retryAfterUntil = 0;
+  }
+
+  /**
+   * Try to consume one token. Returns true if allowed, false if exhausted.
+   */
+  consume(): boolean {
+    this.refillIfWindowExpired();
+
+    if (Date.now() < this.retryAfterUntil) {
+      return false;
+    }
+
+    if (this.tokens <= 0) {
+      return false;
+    }
+
+    this.tokens--;
+    return true;
+  }
+
+  /**
+   * Number of tokens remaining in the current window.
+   */
+  remaining(): number {
+    this.refillIfWindowExpired();
+    return this.tokens;
+  }
+
+  /**
+   * Whether the bucket is fully exhausted (0 tokens remaining).
+   */
+  isExhausted(): boolean {
+    this.refillIfWindowExpired();
+    return this.tokens <= 0;
+  }
+
+  /**
+   * Apply a Retry-After delay (from ADO 429 response).
+   * Blocks all consumption until the delay expires.
+   *
+   * @param seconds - Number of seconds to wait
+   */
+  applyRetryAfter(seconds: number): void {
+    this.retryAfterUntil = Date.now() + seconds * 1000;
+  }
+
+  private refillIfWindowExpired(): void {
+    const now = Date.now();
+    if (now - this.windowStart >= this.windowMs) {
+      this.tokens = this.capacity;
+      this.windowStart = now;
+    }
+  }
+}

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

@@ -1,11 +1,12 @@
 import { SpecMetadataManager } from "../../../src/core/specs/spec-metadata-manager.js";
 import { SpecParser } from "../../../src/core/specs/spec-parser.js";
+import { SyncCircuitBreaker } from "../../../src/core/increment/sync-circuit-breaker.js";
 import axios from "axios";
 import { promises as fsPromises, existsSync } from "fs";
 import path from "path";
 import yaml from "yaml";
 class AdoSpecSync {
-  constructor(config, projectRoot = process.cwd(), projectId) {
+  constructor(config, projectRoot = process.cwd(), projectId, breaker) {
     this.availableTypes = null;
     /**
      * Resolve a work item state name for the given type.
@@ -18,6 +19,7 @@ class AdoSpecSync {
     this.projectRoot = projectRoot;
     this.specManager = new SpecMetadataManager(projectRoot, projectId);
     this.config = config;
+    this.breaker = breaker ?? new SyncCircuitBreaker();
     this.client = axios.create({
       baseURL: `https://dev.azure.com/${config.organization}/${config.project}/_apis`,
       auth: {
@@ -93,6 +95,14 @@ class AdoSpecSync {
   async syncSpecToAdo(specId) {
     console.log(`
 \u{1F504} Syncing spec ${specId} to ADO Feature...`);
+    if (!this.breaker.canSync()) {
+      return {
+        success: false,
+        specId,
+        provider: "ado",
+        error: "Circuit breaker open \u2014 sync blocked"
+      };
+    }
     try {
       const spec = await this.specManager.loadSpec(specId);
       if (!spec) {
@@ -144,6 +154,14 @@ class AdoSpecSync {
   async syncFromAdo(specId) {
     console.log(`
 \u{1F504} Syncing FROM ADO to spec ${specId}...`);
+    if (!this.breaker.canSync()) {
+      return {
+        success: false,
+        specId,
+        provider: "ado",
+        error: "Circuit breaker open \u2014 sync blocked"
+      };
+    }
     try {
       const spec = await this.specManager.loadSpec(specId);
       if (!spec) {
@@ -651,6 +669,12 @@ ${acList}
     };
     return map[normalizedType] || defaultType;
   }
+  /**
+   * Check whether the circuit is closed (sync allowed).
+   */
+  canSync() {
+    return this.breaker.canSync();
+  }
 }
 export {
   AdoSpecSync

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

@@ -22,7 +22,10 @@ import {
   SpecSyncConflict
 } from '../../../src/core/types/spec-metadata.js';
 import { execFileNoThrow } from '../../../src/utils/execFileNoThrow.js';
-import axios, { AxiosInstance } from 'axios';
+import { SyncCircuitBreaker } from '../../../src/core/increment/sync-circuit-breaker.js';
+import { withRetry } from '../../../src/core/sync/retry-wrapper.js';
+import { SyncError } from '../../../src/core/errors/sync-error.js';
+import axios, { AxiosInstance, AxiosError } from 'axios';
 import { promises as fsPromises, existsSync } from 'fs';
 import path from 'path';
 import yaml from 'yaml';
@@ -62,11 +65,13 @@ export class AdoSpecSync {
   private config: AdoConfig;
   private projectRoot: string;
   private availableTypes: Set<string> | null = null;
+  private breaker: SyncCircuitBreaker;
 
-  constructor(config: AdoConfig, projectRoot: string = process.cwd(), projectId?: string) {
+  constructor(config: AdoConfig, projectRoot: string = process.cwd(), projectId?: string, breaker?: SyncCircuitBreaker) {
     this.projectRoot = projectRoot;
     this.specManager = new SpecMetadataManager(projectRoot, projectId);
     this.config = config;
+    this.breaker = breaker ?? new SyncCircuitBreaker();
 
     // Create ADO API client
     // NOTE: Do NOT set a default Content-Type here. Work item create/update
@@ -166,6 +171,15 @@ export class AdoSpecSync {
   async syncSpecToAdo(specId: string): Promise<SpecSyncResult> {
     console.log(`\n🔄 Syncing spec ${specId} to ADO Feature...`);
 
+    if (!this.breaker.canSync()) {
+      return {
+        success: false,
+        specId,
+        provider: 'ado',
+        error: 'Circuit breaker open — sync blocked',
+      };
+    }
+
     try {
       // 1. Load spec
       const spec = await this.specManager.loadSpec(specId);
@@ -232,6 +246,15 @@ export class AdoSpecSync {
   async syncFromAdo(specId: string): Promise<SpecSyncResult> {
     console.log(`\n🔄 Syncing FROM ADO to spec ${specId}...`);
 
+    if (!this.breaker.canSync()) {
+      return {
+        success: false,
+        specId,
+        provider: 'ado',
+        error: 'Circuit breaker open — sync blocked',
+      };
+    }
+
     try {
       // 1. Load spec
       const spec = await this.specManager.loadSpec(specId);
@@ -860,4 +883,11 @@ ${acList}
 
     return map[normalizedType] || defaultType;
   }
+
+  /**
+   * Check whether the circuit is closed (sync allowed).
+   */
+  canSync(): boolean {
+    return this.breaker.canSync();
+  }
 }

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

@@ -1,8 +1,12 @@
 import axios from "axios";
+import { SyncCircuitBreaker } from "../../../src/core/increment/sync-circuit-breaker.js";
+import { withRetry } from "../../../src/core/sync/retry-wrapper.js";
+import { SyncError } from "../../../src/core/errors/sync-error.js";
 class AdoStatusSync {
-  constructor(organization, project, personalAccessToken) {
+  constructor(organization, project, personalAccessToken, breaker) {
     this.organization = organization;
     this.project = project;
+    this.breaker = breaker ?? new SyncCircuitBreaker();
     this.client = axios.create({
       baseURL: `https://dev.azure.com/${organization}/${project}/_apis`,
       auth: {
@@ -23,12 +27,12 @@ class AdoStatusSync {
    * @returns Current work item state
    */
   async getStatus(workItemId) {
-    const response = await this.client.get(
-      `/wit/workitems/${workItemId}?api-version=7.0`
+    this.assertCircuitClosed();
+    return this.withResilienceWrapper(
+      () => this.client.get(`/wit/workitems/${workItemId}?api-version=7.0`).then((response) => ({
+        state: response.data.fields["System.State"]
+      }))
     );
-    return {
-      state: response.data.fields["System.State"]
-    };
   }
   /**
    * Update ADO work item state and tags
@@ -40,6 +44,7 @@ class AdoStatusSync {
    * @param status - Desired status with state and optional tags
    */
   async updateStatus(workItemId, status) {
+    this.assertCircuitClosed();
     const patch = [
       {
         op: "add",
@@ -60,11 +65,16 @@ class AdoStatusSync {
         value: allTags.join("; ")
       });
     }
-    await this.client.patch(
-      `/wit/workitems/${workItemId}?api-version=7.0`,
-      patch
+    await this.withResilienceWrapper(
+      () => this.client.patch(`/wit/workitems/${workItemId}?api-version=7.0`, patch)
     );
   }
+  /**
+   * Check whether the circuit is closed (sync allowed).
+   */
+  canSync() {
+    return this.breaker.canSync();
+  }
   /**
    * Get current tags from ADO work item
    *
@@ -91,6 +101,7 @@ class AdoStatusSync {
    * @param newStatus - New SpecWeave status
    */
   async postStatusComment(workItemId, oldStatus, newStatus) {
+    this.assertCircuitClosed();
     const text = `\u{1F504} Status Update
 
 SpecWeave status changed:
@@ -99,13 +110,40 @@ SpecWeave status changed:
 \u2022 When: ${(/* @__PURE__ */ new Date()).toISOString()}
 
 Synced from SpecWeave`;
-    await this.client.post(
-      `/wit/workitems/${workItemId}/comments?api-version=7.0-preview.3`,
-      {
-        text
-      }
+    await this.withResilienceWrapper(
+      () => this.client.post(
+        `/wit/workitems/${workItemId}/comments?api-version=7.0-preview.3`,
+        { text }
+      )
     );
   }
+  /**
+   * Assert the circuit is closed. Throws CircuitOpenError if open.
+   */
+  assertCircuitClosed() {
+    if (!this.breaker.canSync()) {
+      throw new SyncError("ado", 503, "", "Circuit breaker open \u2014 sync blocked");
+    }
+  }
+  /**
+   * Wrap an async operation with retry + circuit breaker recording.
+   */
+  async withResilienceWrapper(fn) {
+    try {
+      const result = await withRetry(fn, { maxRetries: 3, baseMs: 500, maxMs: 5e3 });
+      this.breaker.recordSuccess();
+      return result;
+    } catch (error) {
+      this.breaker.recordFailure();
+      if (error?.response?.status) {
+        const status = error.response.status;
+        const body = typeof error.response.data === "string" ? error.response.data : JSON.stringify(error.response.data ?? "");
+        const detail = error.response.statusText || "Unknown";
+        throw new SyncError("ado", status, body, detail);
+      }
+      throw error;
+    }
+  }
 }
 export {
   AdoStatusSync