specweave 1.0.488 → 1.0.489

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'
       };
     }
+    });
   }
 
   /**

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

@@ -1,10 +1,23 @@
 import axios from "axios";
 import { detectDeploymentType, getApiBaseUrl } from "./jira-deployment-detector.js";
 import { toCommentBody } from "./content-format-adapter.js";
+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";
 class JiraStatusSync {
-  constructor(domain, email, apiToken, projectKey) {
+  constructor(domain, email, apiToken, projectKey, options) {
     this.domain = domain;
     this.projectKey = projectKey;
+    this.circuitBreakerRegistry = options?.circuitBreakerRegistry;
+    this.retryQueue = options?.retryQueue;
+    this.incrementId = options?.incrementId ?? "";
+    this.featureId = options?.featureId ?? "";
+    this.projectPath = options?.projectPath ?? "";
+    this.projectName = options?.projectName ?? "";
+    if (options?.lockDir) {
+      this.lockManager = new LockManager(options.lockDir);
+    }
     this.client = axios.create({
       baseURL: getApiBaseUrl(domain),
       auth: {
@@ -17,9 +30,48 @@ class JiraStatusSync {
       }
     });
   }
-  /**
-   * Initialize: detect deployment type and update client baseURL
-   */
+  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");
+    }
+  }
+  recordSuccess() {
+    if (!this.circuitBreakerRegistry) return;
+    this.circuitBreakerRegistry.get("jira").recordSuccess();
+  }
+  async handleApiError(error, operation) {
+    const httpStatus = error?.response?.status ?? 0;
+    const responseBody = JSON.stringify(error?.response?.data ?? "");
+    const detail = error?.message ?? String(error);
+    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.projectPath,
+        projectName: this.projectName,
+        error: `${httpStatus} ${operation}: ${detail}`
+      });
+    }
+    throw new SyncError("jira", httpStatus, responseBody, detail);
+  }
   async init() {
     const deployment = await detectDeploymentType(this.domain, {
       email: this.client.defaults.auth?.username || "",
@@ -27,59 +79,52 @@ class JiraStatusSync {
     });
     this.client.defaults.baseURL = deployment.baseUrl;
   }
-  /**
-   * Get current status from JIRA issue
-   *
-   * @param issueKey - JIRA issue key (e.g., PROJ-123)
-   * @returns Current issue status
-   */
   async getStatus(issueKey) {
-    const response = await this.client.get(`/issue/${issueKey}`);
-    return {
-      state: response.data.fields.status.name
-    };
+    return this.withLock(async () => {
+      this.checkCircuitBreaker();
+      try {
+        const response = await this.client.get(`/issue/${issueKey}`);
+        this.recordSuccess();
+        return {
+          state: response.data.fields.status.name
+        };
+      } catch (error) {
+        return this.handleApiError(error, "getStatus");
+      }
+    });
   }
-  /**
-   * Update JIRA issue status via transitions
-   *
-   * JIRA requires using transitions to change status.
-   * Cannot directly set status field.
-   *
-   * Handles missing transitions gracefully by logging a warning
-   * instead of throwing an error.
-   *
-   * @param issueKey - JIRA issue key (e.g., PROJ-123)
-   * @param status - Desired status
-   * @returns true if transition succeeded, false if not available
-   */
   async updateStatus(issueKey, status) {
-    const transitionsResponse = await this.client.get(`/issue/${issueKey}/transitions`);
-    const transitions = transitionsResponse.data.transitions;
-    const targetTransition = transitions.find(
-      (t) => t.to.name.toLowerCase() === status.state.toLowerCase()
-    );
-    if (!targetTransition) {
-      console.warn(
-        `\u26A0\uFE0F  Cannot transition ${issueKey} to "${status.state}". Available transitions: ${transitions.map((t) => t.to.name).join(", ")}. This may be expected if your JIRA workflow doesn't support this status.`
-      );
-      return false;
-    }
-    await this.client.post(`/issue/${issueKey}/transitions`, {
-      transition: {
-        id: targetTransition.id
+    return this.withLock(async () => {
+      this.checkCircuitBreaker();
+      try {
+        const transitionsResponse = await this.client.get(`/issue/${issueKey}/transitions`);
+        const transitions = transitionsResponse.data.transitions;
+        const targetTransition = transitions.find(
+          (t) => t.to.name.toLowerCase() === status.state.toLowerCase()
+        );
+        if (!targetTransition) {
+          console.warn(
+            `\u26A0\uFE0F  Cannot transition ${issueKey} to "${status.state}". Available transitions: ${transitions.map((t) => t.to.name).join(", ")}. This may be expected if your JIRA workflow doesn't support this status.`
+          );
+          return false;
+        }
+        await this.client.post(`/issue/${issueKey}/transitions`, {
+          transition: {
+            id: targetTransition.id
+          }
+        });
+        this.recordSuccess();
+        return true;
+      } catch (error) {
+        return this.handleApiError(error, "updateStatus");
       }
     });
-    return true;
   }
-  /**
-   * Post comment about status change to JIRA issue
-   *
-   * @param issueKey - JIRA issue key (e.g., PROJ-123)
-   * @param oldStatus - Previous SpecWeave status
-   * @param newStatus - New SpecWeave status
-   */
   async postStatusComment(issueKey, oldStatus, newStatus) {
-    const rawBody = `*Status Update*
+    return this.withLock(async () => {
+      this.checkCircuitBreaker();
+      try {
+        const rawBody = `*Status Update*
 
 SpecWeave status changed:
 * *From*: ${oldStatus}
@@ -87,73 +132,70 @@ SpecWeave status changed:
 * *When*: ${(/* @__PURE__ */ new Date()).toISOString()}
 
 _Synced from SpecWeave_`;
-    const body = toCommentBody(rawBody, this.domain);
-    await this.client.post(`/issue/${issueKey}/comment`, {
-      body
+        const body = toCommentBody(rawBody, this.domain);
+        await this.client.post(`/issue/${issueKey}/comment`, {
+          body
+        });
+        this.recordSuccess();
+      } catch (error) {
+        return this.handleApiError(error, "postStatusComment");
+      }
     });
   }
-  /**
-   * Post AC progress comment with proper ADF formatting and dedup.
-   *
-   * Builds native ADF with:
-   * - Bold header showing completion percentage
-   * - Bullet list with checkmark/cross emojis per AC
-   * - Fingerprint marker to prevent duplicate comments
-   *
-   * @param issueKey - JIRA issue key (e.g., PROJ-123)
-   * @param acStates - Array of AC states with id, description, completed
-   * @returns true if comment was posted, false if skipped (duplicate)
-   */
   async postProgressComment(issueKey, acStates) {
-    const total = acStates.length;
-    const completed = acStates.filter((ac) => ac.completed).length;
-    const percentage = Math.round(completed / total * 100);
-    const fingerprint = `sw-progress:${completed}/${total}`;
-    try {
-      const commentsResp = await this.client.get(`/issue/${issueKey}/comment`, {
-        params: { orderBy: "-created", maxResults: 1 }
-      });
-      const lastComment = commentsResp.data?.comments?.[0];
-      if (lastComment) {
-        const lastText = extractAdfText(lastComment.body);
-        if (lastText.includes(fingerprint)) {
-          return false;
+    return this.withLock(async () => {
+      this.checkCircuitBreaker();
+      const total = acStates.length;
+      const completed = acStates.filter((ac) => ac.completed).length;
+      const percentage = Math.round(completed / total * 100);
+      const fingerprint = `sw-progress:${completed}/${total}`;
+      try {
+        const commentsResp = await this.client.get(`/issue/${issueKey}/comment`, {
+          params: { orderBy: "-created", maxResults: 1 }
+        });
+        const lastComment = commentsResp.data?.comments?.[0];
+        if (lastComment) {
+          const lastText = extractAdfText(lastComment.body);
+          if (lastText.includes(fingerprint)) {
+            return false;
+          }
         }
+      } catch {
       }
-    } catch {
-    }
-    const listItems = acStates.map((ac) => ({
-      type: "listItem",
-      content: [{
-        type: "paragraph",
-        content: [
-          { type: "text", text: `${ac.completed ? "\u2705" : "\u274C"} ${ac.id}: ${ac.description}` }
-        ]
-      }]
-    }));
-    const body = {
-      type: "doc",
-      version: 1,
-      content: [
-        {
-          type: "heading",
-          attrs: { level: 3 },
-          content: [{ type: "text", text: `Progress: ${completed}/${total} ACs (${percentage}%)` }]
-        },
-        {
-          type: "bulletList",
-          content: listItems
-        },
-        {
+      const listItems = acStates.map((ac) => ({
+        type: "listItem",
+        content: [{
           type: "paragraph",
           content: [
-            { type: "text", text: `${fingerprint} | Synced from SpecWeave`, marks: [{ type: "em" }] }
+            { type: "text", text: `${ac.completed ? "\u2705" : "\u274C"} ${ac.id}: ${ac.description}` }
           ]
-        }
-      ]
-    };
-    await this.client.post(`/issue/${issueKey}/comment`, { body });
-    return true;
+        }]
+      }));
+      const body = {
+        type: "doc",
+        version: 1,
+        content: [
+          {
+            type: "heading",
+            attrs: { level: 3 },
+            content: [{ type: "text", text: `Progress: ${completed}/${total} ACs (${percentage}%)` }]
+          },
+          {
+            type: "bulletList",
+            content: listItems
+          },
+          {
+            type: "paragraph",
+            content: [
+              { type: "text", text: `${fingerprint} | Synced from SpecWeave`, marks: [{ type: "em" }] }
+            ]
+          }
+        ]
+      };
+      await this.client.post(`/issue/${issueKey}/comment`, { body });
+      this.recordSuccess();
+      return true;
+    });
   }
 }
 function extractAdfText(adf) {