specweave 1.0.488 → 1.0.489

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

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

@@ -11,7 +11,10 @@
  * @module ado-status-sync
  */
 
-import axios, { AxiosInstance } from 'axios';
+import axios, { AxiosInstance, AxiosError } 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';
 
 /**
  * External status representation (ADO-specific)
@@ -25,19 +28,24 @@ export interface ExternalStatus {
  * Azure DevOps Status Sync
  *
  * Handles status synchronization with ADO work items.
+ * Integrates circuit breaker (opens after 3 consecutive failures)
+ * and retry with exponential backoff for transient errors.
  */
 export class AdoStatusSync {
   private client: AxiosInstance;
   private organization: string;
   private project: string;
+  private breaker: SyncCircuitBreaker;
 
   constructor(
     organization: string,
     project: string,
-    personalAccessToken: string
+    personalAccessToken: string,
+    breaker?: SyncCircuitBreaker
   ) {
     this.organization = organization;
     this.project = project;
+    this.breaker = breaker ?? new SyncCircuitBreaker();
 
     // Create ADO API client
     this.client = axios.create({
@@ -60,13 +68,13 @@ export class AdoStatusSync {
    * @returns Current work item state
    */
   async getStatus(workItemId: number): Promise<ExternalStatus> {
-    const response = await this.client.get(
-      `/wit/workitems/${workItemId}?api-version=7.0`
-    );
+    this.assertCircuitClosed();
 
-    return {
-      state: response.data.fields['System.State']
-    };
+    return this.withResilienceWrapper(() =>
+      this.client.get(`/wit/workitems/${workItemId}?api-version=7.0`).then(response => ({
+        state: response.data.fields['System.State'] as string,
+      }))
+    );
   }
 
   /**
@@ -79,6 +87,7 @@ export class AdoStatusSync {
    * @param status - Desired status with state and optional tags
    */
   async updateStatus(workItemId: number, status: ExternalStatus): Promise<void> {
+    this.assertCircuitClosed();
     // ADO uses JSON Patch format for updates
     const patch: Array<{ op: string; path: string; value: string }> = [
       {
@@ -109,12 +118,18 @@ export class AdoStatusSync {
       });
     }
 
-    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(): boolean {
+    return this.breaker.canSync();
+  }
+
   /**
    * Get current tags from ADO work item
    *
@@ -148,6 +163,8 @@ export class AdoStatusSync {
     oldStatus: string,
     newStatus: string
   ): Promise<void> {
+    this.assertCircuitClosed();
+
     const text = `🔄 Status Update\n\n` +
       `SpecWeave status changed:\n` +
       `• From: ${oldStatus}\n` +
@@ -155,11 +172,42 @@ export class AdoStatusSync {
       `• When: ${new Date().toISOString()}\n\n` +
       `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.
+   */
+  private assertCircuitClosed(): void {
+    if (!this.breaker.canSync()) {
+      throw new SyncError('ado', 503, '', 'Circuit breaker open — sync blocked');
+    }
+  }
+
+  /**
+   * Wrap an async operation with retry + circuit breaker recording.
+   */
+  private async withResilienceWrapper<T>(fn: () => Promise<T>): Promise<T> {
+    try {
+      const result = await withRetry(fn, { maxRetries: 3, baseMs: 500, maxMs: 5000 });
+      this.breaker.recordSuccess();
+      return result;
+    } catch (error: any) {
+      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;
+    }
+  }
 }

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

@@ -256,7 +256,7 @@ export class GitHubClientV2 {
       // Derive proper FS-ID from the increment number
       const num = parseInt(incrementId.replace('E', ''), 10);
       const isExternal = incrementId.endsWith('E');
-      const properFsId = `FS-${String(num).padStart(3, '0')}${isExternal ? 'E' : ''}`;
+      const properFsId = `FS-${String(num).padStart(3, '0')}${isExternal ? 'E' : ''}`; // Legacy E suffix — error message only
       throw new Error(
         `❌ INVALID TITLE FORMAT: "${title}"\n\n` +
         `Plain increment IDs like [${incrementId}] are NOT allowed!\n\n` +

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

@@ -1,5 +1,10 @@
 import { execFileNoThrow } from "../../../src/utils/execFileNoThrow.js";
 import { generateIssueBody } from "./github-issue-body-generator.js";
+import { SyncError } from "../../../src/core/errors/sync-error.js";
+function parseHttpStatus(stderr) {
+  const match = stderr.match(/HTTP\s+(\d{3})/);
+  return match ? parseInt(match[1], 10) : 0;
+}
 async function pushSyncUserStories(userStories, options) {
   const result = { created: [], updated: [], errors: [] };
   if (options.dryRun) {
@@ -60,7 +65,8 @@ async function searchIssueByPrefix(usId, repoSlug, env) {
     "1"
   ], { env });
   if (!res.success) {
-    throw new Error(`Search failed: ${res.stderr}`);
+    const status = parseHttpStatus(res.stderr);
+    throw new SyncError("github", status, res.stderr, `Search failed: ${res.stderr}`);
   }
   const issues = JSON.parse(res.stdout);
   return issues.length > 0 ? issues[0] : null;
@@ -86,7 +92,8 @@ async function createIssue(title, body, us, repoSlug, env) {
   ];
   const res = await execFileNoThrow("gh", args, { env });
   if (!res.success) {
-    throw new Error(`Create failed: ${res.stderr}`);
+    const status = parseHttpStatus(res.stderr);
+    throw new SyncError("github", status, res.stderr, `Create failed: ${res.stderr}`);
   }
   return JSON.parse(res.stdout);
 }
@@ -106,7 +113,8 @@ async function updateIssue(issueNumber, title, body, repoSlug, env) {
   ];
   const res = await execFileNoThrow("gh", args, { env });
   if (!res.success) {
-    throw new Error(`Update failed: ${res.stderr}`);
+    const status = parseHttpStatus(res.stderr);
+    throw new SyncError("github", status, res.stderr, `Update failed: ${res.stderr}`);
   }
   return JSON.parse(res.stdout);
 }

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

@@ -9,6 +9,16 @@
 
 import { execFileNoThrow } from '../../../src/utils/execFileNoThrow.js';
 import { generateIssueBody } from './github-issue-body-generator.js';
+import { SyncError } from '../../../src/core/errors/sync-error.js';
+
+/**
+ * Extract HTTP status code from gh CLI stderr output.
+ * gh CLI typically outputs "HTTP 401: Bad credentials" or similar.
+ */
+function parseHttpStatus(stderr: string): number {
+  const match = stderr.match(/HTTP\s+(\d{3})/);
+  return match ? parseInt(match[1], 10) : 0;
+}
 
 export interface UserStoryForSync {
   id: string;
@@ -109,7 +119,8 @@ async function searchIssueByPrefix(
   ], { env });
 
   if (!res.success) {
-    throw new Error(`Search failed: ${res.stderr}`);
+    const status = parseHttpStatus(res.stderr);
+    throw new SyncError('github', status, res.stderr, `Search failed: ${res.stderr}`);
   }
 
   const issues = JSON.parse(res.stdout);
@@ -137,7 +148,8 @@ async function createIssue(
   const res = await execFileNoThrow('gh', args, { env });
 
   if (!res.success) {
-    throw new Error(`Create failed: ${res.stderr}`);
+    const status = parseHttpStatus(res.stderr);
+    throw new SyncError('github', status, res.stderr, `Create failed: ${res.stderr}`);
   }
 
   return JSON.parse(res.stdout);
@@ -161,7 +173,8 @@ async function updateIssue(
   const res = await execFileNoThrow('gh', args, { env });
 
   if (!res.success) {
-    throw new Error(`Update failed: ${res.stderr}`);
+    const status = parseHttpStatus(res.stderr);
+    throw new SyncError('github', status, res.stderr, `Update failed: ${res.stderr}`);
   }
 
   return JSON.parse(res.stdout);