specweave 1.0.488 → 1.0.490

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);

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

@@ -9,6 +9,10 @@ import { toDescription } from "./content-format-adapter.js";
 import { getEpicLinkFieldForProject } from "./jira-field-discovery.js";
 import { searchAllIssues } from "./jira-paginated-search.js";
 import axios from "axios";
+import { CircuitBreakerRegistry } from "../../../src/core/sync/circuit-breaker-registry.js";
+import { SyncRetryQueue } from "../../../src/core/sync/sync-retry-queue.js";
+import { SyncError } from "../../../src/core/errors/sync-error.js";
+import { LockManager } from "../../../src/utils/lock-manager.js";
 function buildStoryDescription(us) {
   const acList = us.acceptanceCriteria.map((ac) => `${ac.status === "done" ? "[x]" : "[ ]"} ${ac.id}: ${ac.description}`).join("\n");
   return `
@@ -28,10 +32,17 @@ ${acList}
 `.trim();
 }
 class JiraSpecSync {
-  constructor(config, projectRoot = process.cwd(), projectId) {
+  constructor(config, projectRoot = process.cwd(), projectId, options) {
     this.projectRoot = projectRoot;
     this.specManager = new SpecMetadataManager(projectRoot, projectId);
     this.config = config;
+    this.circuitBreakerRegistry = options?.circuitBreakerRegistry;
+    this.retryQueue = options?.retryQueue;
+    this.incrementId = options?.incrementId ?? "";
+    this.featureId = options?.featureId ?? "";
+    if (options?.lockDir) {
+      this.lockManager = new LockManager(options.lockDir);
+    }
     this.client = axios.create({
       baseURL: getApiBaseUrl(config.domain),
       auth: {
@@ -44,6 +55,45 @@ class JiraSpecSync {
       }
     });
   }
+  async withLock(fn) {
+    if (!this.lockManager) return fn();
+    const acquired = await this.lockManager.acquire();
+    if (!acquired) {
+      throw new SyncError("jira", 0, "", "Failed to acquire JIRA sync lock");
+    }
+    try {
+      return await fn();
+    } finally {
+      await this.lockManager.release();
+    }
+  }
+  checkCircuitBreaker() {
+    if (!this.circuitBreakerRegistry) return;
+    const breaker = this.circuitBreakerRegistry.get("jira");
+    if (!breaker.canSync()) {
+      throw new SyncError("jira", 0, "", "Circuit breaker open for jira");
+    }
+  }
+  recordApiSuccess() {
+    if (!this.circuitBreakerRegistry) return;
+    this.circuitBreakerRegistry.get("jira").recordSuccess();
+  }
+  async recordApiFailure(error, operation) {
+    const httpStatus = error?.response?.status ?? 0;
+    if (this.circuitBreakerRegistry) {
+      this.circuitBreakerRegistry.get("jira").recordFailure();
+    }
+    if (this.retryQueue && httpStatus >= 500) {
+      await this.retryQueue.enqueue({
+        incrementId: this.incrementId,
+        provider: "jira",
+        featureId: this.featureId,
+        projectPath: this.projectRoot,
+        projectName: this.config.projectKey,
+        error: `${httpStatus} ${operation}: ${error?.message ?? String(error)}`
+      });
+    }
+  }
   /**
    * Initialize: detect deployment type and update client baseURL
    */
@@ -60,6 +110,8 @@ class JiraSpecSync {
   async syncSpecToJira(specId) {
     console.log(`
 \u{1F504} Syncing spec ${specId} to Jira Epic...`);
+    return this.withLock(async () => {
+    this.checkCircuitBreaker();
     try {
       const spec = await this.specManager.loadSpec(specId);
       if (!spec) {
@@ -86,6 +138,7 @@ class JiraSpecSync {
         });
       }
       const changes = await this.syncUserStories(epic.key, spec);
+      this.recordApiSuccess();
       console.log("\u2705 Sync complete!");
       return {
         success: true,
@@ -96,6 +149,7 @@ class JiraSpecSync {
         changes
       };
     } catch (error) {
+      await this.recordApiFailure(error, "syncSpecToJira");
       const axiosData = error?.response?.data;
       const detail = axiosData ? JSON.stringify(axiosData) : "";
       console.error("\u274C Error syncing to Jira:", error?.message || error, detail ? `
@@ -107,6 +161,7 @@ class JiraSpecSync {
         error: error instanceof Error ? error.message : "Unknown error"
       };
     }
+    });
   }
   /**
    * Sync FROM Jira Epic to spec (bidirectional)
@@ -114,6 +169,8 @@ class JiraSpecSync {
   async syncFromJira(specId) {
     console.log(`
 \u{1F504} Syncing FROM Jira to spec ${specId}...`);
+    return this.withLock(async () => {
+    this.checkCircuitBreaker();
     try {
       const spec = await this.specManager.loadSpec(specId);
       if (!spec) {
@@ -158,6 +215,7 @@ class JiraSpecSync {
         conflicts
       };
     } catch (error) {
+      await this.recordApiFailure(error, "syncFromJira");
       console.error("\u274C Error syncing FROM Jira:", error);
       return {
         success: false,
@@ -166,6 +224,7 @@ class JiraSpecSync {
         error: error instanceof Error ? error.message : "Unknown error"
       };
     }
+    });
   }
   /**
    * Create new Jira Epic for spec

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

@@ -31,6 +31,10 @@ import { toDescription, AdfDocument } from './content-format-adapter.js';
 import { getEpicLinkFieldForProject } from './jira-field-discovery.js';
 import { searchAllIssues } from './jira-paginated-search.js';
 import axios, { AxiosInstance } from 'axios';
+import { CircuitBreakerRegistry } from '../../../src/core/sync/circuit-breaker-registry.js';
+import { SyncRetryQueue } from '../../../src/core/sync/sync-retry-queue.js';
+import { SyncError } from '../../../src/core/errors/sync-error.js';
+import { LockManager } from '../../../src/utils/lock-manager.js';
 
 /**
  * Build a JIRA story description from a UserStory.
@@ -88,16 +92,36 @@ export interface JiraConfig {
   projectKey: string; // e.g., SPEC
 }
 
+export interface JiraSpecSyncOptions {
+  circuitBreakerRegistry?: CircuitBreakerRegistry;
+  retryQueue?: SyncRetryQueue;
+  lockDir?: string;
+  incrementId?: string;
+  featureId?: string;
+}
+
 export class JiraSpecSync {
   private specManager: SpecMetadataManager;
   private client: AxiosInstance;
   private config: JiraConfig;
   private projectRoot: string;
+  private circuitBreakerRegistry?: CircuitBreakerRegistry;
+  private retryQueue?: SyncRetryQueue;
+  private lockManager?: LockManager;
+  private incrementId: string;
+  private featureId: string;
 
-  constructor(config: JiraConfig, projectRoot: string = process.cwd(), projectId?: string) {
+  constructor(config: JiraConfig, projectRoot: string = process.cwd(), projectId?: string, options?: JiraSpecSyncOptions) {
     this.projectRoot = projectRoot;
     this.specManager = new SpecMetadataManager(projectRoot, projectId);
     this.config = config;
+    this.circuitBreakerRegistry = options?.circuitBreakerRegistry;
+    this.retryQueue = options?.retryQueue;
+    this.incrementId = options?.incrementId ?? '';
+    this.featureId = options?.featureId ?? '';
+    if (options?.lockDir) {
+      this.lockManager = new LockManager(options.lockDir);
+    }
 
     // Create Jira API client — baseURL set dynamically via init()
     this.client = axios.create({
@@ -113,6 +137,63 @@ export class JiraSpecSync {
     });
   }
 
+  /**
+   * Execute fn under file lock (if lockManager configured).
+   */
+  private async withLock<T>(fn: () => Promise<T>): Promise<T> {
+    if (!this.lockManager) return fn();
+    const acquired = await this.lockManager.acquire();
+    if (!acquired) {
+      throw new SyncError('jira', 0, '', 'Failed to acquire JIRA sync lock');
+    }
+    try {
+      return await fn();
+    } finally {
+      await this.lockManager.release();
+    }
+  }
+
+  /**
+   * Check circuit breaker before making API calls.
+   */
+  private checkCircuitBreaker(): void {
+    if (!this.circuitBreakerRegistry) return;
+    const breaker = this.circuitBreakerRegistry.get('jira');
+    if (!breaker.canSync()) {
+      throw new SyncError('jira', 0, '', 'Circuit breaker open for jira');
+    }
+  }
+
+  /**
+   * Record success on circuit breaker.
+   */
+  private recordApiSuccess(): void {
+    if (!this.circuitBreakerRegistry) return;
+    this.circuitBreakerRegistry.get('jira').recordSuccess();
+  }
+
+  /**
+   * Record failure on circuit breaker and optionally enqueue retry.
+   */
+  private async recordApiFailure(error: unknown, operation: string): Promise<void> {
+    const httpStatus = (error as any)?.response?.status ?? 0;
+
+    if (this.circuitBreakerRegistry) {
+      this.circuitBreakerRegistry.get('jira').recordFailure();
+    }
+
+    if (this.retryQueue && httpStatus >= 500) {
+      await this.retryQueue.enqueue({
+        incrementId: this.incrementId,
+        provider: 'jira',
+        featureId: this.featureId,
+        projectPath: this.projectRoot,
+        projectName: this.config.projectKey,
+        error: `${httpStatus} ${operation}: ${(error as Error)?.message ?? String(error)}`,
+      });
+    }
+  }
+
   /**
    * Initialize: detect deployment type and update client baseURL
    */
@@ -130,6 +211,9 @@ export class JiraSpecSync {
   async syncSpecToJira(specId: string): Promise<SpecSyncResult> {
     console.log(`\n🔄 Syncing spec ${specId} to Jira Epic...`);
 
+    return this.withLock(async () => {
+    this.checkCircuitBreaker();
+
     try {
       // 1. Load spec
       const spec = await this.specManager.loadSpec(specId);
@@ -168,6 +252,7 @@ export class JiraSpecSync {
       // 3. Sync user stories as Jira Stories
       const changes = await this.syncUserStories(epic.key, spec);
 
+      this.recordApiSuccess();
       console.log('✅ Sync complete!');
 
       return {
@@ -180,6 +265,7 @@ export class JiraSpecSync {
       };
 
     } catch (error: any) {
+      await this.recordApiFailure(error, 'syncSpecToJira');
       const axiosData = error?.response?.data;
       const detail = axiosData ? JSON.stringify(axiosData) : '';
       console.error('❌ Error syncing to Jira:', error?.message || error, detail ? `\n   Response: ${detail}` : '');
@@ -190,6 +276,7 @@ export class JiraSpecSync {
         error: error instanceof Error ? error.message : 'Unknown error'
       };
     }
+    });
   }
 
   /**
@@ -198,6 +285,9 @@ export class JiraSpecSync {
   async syncFromJira(specId: string): Promise<SpecSyncResult> {
     console.log(`\n🔄 Syncing FROM Jira to spec ${specId}...`);
 
+    return this.withLock(async () => {
+    this.checkCircuitBreaker();
+
     try {
       // 1. Load spec
       const spec = await this.specManager.loadSpec(specId);
@@ -258,6 +348,7 @@ export class JiraSpecSync {
       };
 
     } catch (error) {
+      await this.recordApiFailure(error, 'syncFromJira');
       console.error('❌ Error syncing FROM Jira:', error);
       return {
         success: false,
@@ -266,6 +357,7 @@ export class JiraSpecSync {
         error: error instanceof Error ? error.message : 'Unknown error'
       };
     }
+    });
   }
 
   /**