specweave 1.0.506 → 1.0.508

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

@@ -0,0 +1,689 @@
+import { SpecMetadataManager } from "../../../../../src/core/specs/spec-metadata-manager.js";
+import { SpecParser } from "../../../../../src/core/specs/spec-parser.js";
+import * as fs from "fs/promises";
+import * as path from "path";
+import { existsSync } from "fs";
+import yaml from "yaml";
+import { detectDeploymentType, getApiBaseUrl } from "./jira-deployment-detector.js";
+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 `
+h2. User Story
+
+${us.title}
+
+h2. Acceptance Criteria
+
+${acList}
+
+----
+
+*Priority*: ${us.priority}
+
+*Status*: ${us.status}
+`.trim();
+}
+class JiraSpecSync {
+  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: {
+        username: config.email,
+        password: config.apiToken
+      },
+      headers: {
+        "Accept": "application/json",
+        "Content-Type": "application/json"
+      }
+    });
+  }
+  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
+   */
+  async init() {
+    const deployment = await detectDeploymentType(this.config.domain, {
+      email: this.config.email,
+      apiToken: this.config.apiToken
+    });
+    this.client.defaults.baseURL = deployment.baseUrl;
+  }
+  /**
+   * Sync spec to Jira Epic (CREATE or UPDATE)
+   */
+  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) {
+        return {
+          success: false,
+          specId,
+          provider: "jira",
+          error: `Spec ${specId} not found`
+        };
+      }
+      const existingLink = spec.metadata.externalLinks?.jira;
+      let epic;
+      if (existingLink?.epicKey) {
+        console.log(`   Found existing Jira Epic ${existingLink.epicKey}`);
+        epic = await this.updateJiraEpic(existingLink.epicKey, spec);
+      } else {
+        console.log("   Creating new Jira Epic...");
+        epic = await this.createJiraEpic(spec);
+        await this.specManager.linkToExternal(specId, "jira", {
+          id: epic.key,
+          url: epic.url,
+          projectKey: this.config.projectKey,
+          domain: this.config.domain
+        });
+      }
+      const changes = await this.syncUserStories(epic.key, spec);
+      this.recordApiSuccess();
+      console.log("\u2705 Sync complete!");
+      return {
+        success: true,
+        specId,
+        provider: "jira",
+        externalId: epic.key,
+        url: epic.url,
+        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 ? `
+   Response: ${detail}` : "");
+      return {
+        success: false,
+        specId,
+        provider: "jira",
+        error: error instanceof Error ? error.message : "Unknown error"
+      };
+    }
+    });
+  }
+  /**
+   * Sync FROM Jira Epic to spec (bidirectional)
+   */
+  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) {
+        return {
+          success: false,
+          specId,
+          provider: "jira",
+          error: `Spec ${specId} not found`
+        };
+      }
+      const jiraLink = spec.metadata.externalLinks?.jira;
+      if (!jiraLink?.epicKey) {
+        return {
+          success: false,
+          specId,
+          provider: "jira",
+          error: "Spec not linked to Jira Epic"
+        };
+      }
+      const epic = await this.fetchJiraEpic(jiraLink.epicKey);
+      const conflicts = await this.detectConflicts(spec, epic);
+      if (conflicts.length === 0) {
+        console.log("\u2705 No conflicts - spec and Jira in sync");
+        return {
+          success: true,
+          specId,
+          provider: "jira",
+          externalId: epic.key,
+          url: epic.url
+        };
+      }
+      console.log(`\u26A0\uFE0F  Detected ${conflicts.length} conflict(s)`);
+      await this.writeConflictReport(specId, conflicts);
+      await this.resolveConflicts(spec, conflicts);
+      console.log("\u2705 Sync FROM Jira complete!");
+      return {
+        success: true,
+        specId,
+        provider: "jira",
+        externalId: epic.key,
+        url: epic.url,
+        conflicts
+      };
+    } catch (error) {
+      await this.recordApiFailure(error, "syncFromJira");
+      console.error("\u274C Error syncing FROM Jira:", error);
+      return {
+        success: false,
+        specId,
+        provider: "jira",
+        error: error instanceof Error ? error.message : "Unknown error"
+      };
+    }
+    });
+  }
+  /**
+   * Create new Jira Epic for spec
+   */
+  async createJiraEpic(spec) {
+    const epicSummary = `[${spec.metadata.id.toUpperCase()}] ${spec.metadata.title}`;
+    const epicDescription = toDescription(this.generateEpicDescription(spec), this.config.domain);
+    const issueType = this.mapTypeToJira(spec.metadata.type, "Epic");
+    const payload = {
+      fields: {
+        project: {
+          key: this.config.projectKey
+        },
+        summary: epicSummary,
+        description: epicDescription,
+        issuetype: {
+          name: issueType
+        },
+        labels: [`spec:${spec.metadata.id}`, `priority:${spec.metadata.priority}`],
+        // Set native JIRA priority field (P0→Highest, P1→High, P2→Medium, P3→Low)
+        priority: {
+          name: this.mapPriorityToJira(spec.metadata.priority)
+        }
+      }
+    };
+    const response = await this.client.post("/issue", payload);
+    const epicData = response.data;
+    const epicKey = epicData.key;
+    const epicUrl = `https://${this.config.domain}/browse/${epicKey}`;
+    console.log(`   \u2705 Created Jira Epic ${epicKey}: ${epicUrl}`);
+    return {
+      id: epicData.id,
+      key: epicKey,
+      summary: epicSummary,
+      description: epicDescription,
+      status: { name: "To Do" },
+      url: epicUrl
+    };
+  }
+  /**
+   * Update existing Jira Epic
+   */
+  async updateJiraEpic(epicKey, spec) {
+    const epicSummary = `[${spec.metadata.id.toUpperCase()}] ${spec.metadata.title}`;
+    const epicDescription = toDescription(this.generateEpicDescription(spec), this.config.domain);
+    const payload = {
+      fields: {
+        summary: epicSummary,
+        description: epicDescription
+      }
+    };
+    await this.client.put(`/issue/${epicKey}`, payload);
+    const response = await this.client.get(`/issue/${epicKey}`);
+    const epicData = response.data;
+    console.log(`   \u2705 Updated Jira Epic ${epicKey}`);
+    return {
+      id: epicData.id,
+      key: epicKey,
+      summary: epicData.fields.summary,
+      description: epicData.fields.description,
+      status: epicData.fields.status,
+      url: `https://${this.config.domain}/browse/${epicKey}`
+    };
+  }
+  /**
+   * Sync user stories as Jira Stories
+   */
+  async syncUserStories(epicKey, spec) {
+    const created = [];
+    const updated = [];
+    const deleted = [];
+    if (!spec.metadata.userStories || spec.metadata.userStories.length === 0) {
+      console.log("   \u2139\uFE0F  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) {
+      const storySummary = `[${us.id}] ${us.title}`;
+      const storyDescription = this.generateStoryDescription(us);
+      const existingStory = await this.findStoryByTitle(us.id, spec.metadata.id);
+      let storyKey;
+      if (existingStory) {
+        await this.updateStory(existingStory.key, {
+          summary: storySummary,
+          description: storyDescription,
+          status: us.status === "done" ? "Done" : us.status === "in-progress" ? "In Progress" : "To Do",
+          epicLink: epicKey
+        });
+        storyKey = existingStory.key;
+        updated.push(us.id);
+        console.log(`   \u2705 Updated ${us.id}`);
+      } else {
+        const newStory = await this.createStory({
+          summary: storySummary,
+          description: storyDescription,
+          epicLink: epicKey,
+          labels: [`user-story`, `spec:${spec.metadata.id}`, `priority:${us.priority}`],
+          priority: us.priority
+        });
+        storyKey = newStory.key;
+        created.push(us.id);
+        console.log(`   \u2705 Created ${us.id} \u2192 Story ${newStory.key}`);
+      }
+      await this.writeJiraKeyToUSFile(spec.metadata.id, us.id, storyKey);
+    }
+    return { created, updated, deleted };
+  }
+  /**
+   * Write JIRA story key back to living doc US file frontmatter.
+   * Searches all project subdirs for the matching US file and adds external_tools.jira.key.
+   */
+  async writeJiraKeyToUSFile(featureId, usId, storyKey) {
+    try {
+      const specsRoot = path.join(this.projectRoot, ".specweave/docs/internal/specs");
+      if (!existsSync(specsRoot)) return;
+      for (const proj of await fs.readdir(specsRoot)) {
+        const featureDir = path.join(specsRoot, proj, featureId);
+        if (!existsSync(featureDir)) continue;
+        for (const file of await fs.readdir(featureDir)) {
+          if (!file.startsWith("us-") || !file.endsWith(".md")) continue;
+          const filePath = path.join(featureDir, file);
+          const content = await fs.readFile(filePath, "utf-8");
+          const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
+          if (!fmMatch) continue;
+          const frontmatter = yaml.parse(fmMatch[1]);
+          if (frontmatter.id !== usId) continue;
+          if (frontmatter.external_tools?.jira?.key === storyKey) return;
+          if (!frontmatter.external_tools) frontmatter.external_tools = {};
+          if (!frontmatter.external_tools.jira) frontmatter.external_tools.jira = {};
+          frontmatter.external_tools.jira.key = storyKey;
+          const newFm = yaml.stringify(frontmatter).trimEnd();
+          const rest = content.slice(fmMatch[0].length);
+          await fs.writeFile(filePath, `---
+${newFm}
+---${rest}`, "utf-8");
+          console.log(`      \u{1F4DD} Saved JIRA key ${storyKey} to ${file}`);
+          return;
+        }
+      }
+    } catch {
+    }
+  }
+  /**
+   * Generate epic description from spec
+   */
+  generateEpicDescription(spec) {
+    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}
+
+*Spec ID*: ${spec.metadata.id}
+
+*Priority*: ${spec.metadata.priority}
+
+*Status*: ${spec.metadata.status}
+
+${progressText}
+
+----
+
+${SpecParser.extractOverview(spec.markdown)}
+
+----
+
+h2. User Stories
+
+${spec.metadata.userStories?.length || 0} user stories tracked in this epic.
+
+----
+
+Last updated: ${(/* @__PURE__ */ new Date()).toISOString()}
+`.trim();
+  }
+  /**
+   * Generate story description from user story
+   */
+  generateStoryDescription(us) {
+    return buildStoryDescription(us);
+  }
+  /**
+   * Detect conflicts between spec and Jira
+   */
+  async detectConflicts(spec, epic) {
+    const conflicts = [];
+    const expectedSummary = `[${spec.metadata.id.toUpperCase()}] ${spec.metadata.title}`;
+    if (epic.summary !== expectedSummary) {
+      conflicts.push({
+        type: "metadata",
+        field: "title",
+        localValue: spec.metadata.title,
+        remoteValue: epic.summary,
+        resolution: "remote-wins",
+        description: "Epic summary differs from spec title"
+      });
+    }
+    return conflicts;
+  }
+  /**
+   * Resolve conflicts based on configurable strategy.
+   *
+   * Strategies:
+   * - 'manual' (default): Halt sync, report conflicts to user, no auto-resolve
+   * - 'remote-wins': Auto-resolve in favor of JIRA (remote)
+   * - 'local-wins': Auto-resolve in favor of spec (local)
+   * - 'report-only': Log conflicts, continue without resolving
+   */
+  async resolveConflicts(spec, conflicts, strategy = "manual") {
+    if (strategy === "manual") {
+      console.log(`   \u26A0\uFE0F  ${conflicts.length} conflict(s) require manual resolution.`);
+      for (const conflict of conflicts) {
+        console.log(`   - ${conflict.field}: local="${conflict.localValue}" vs remote="${conflict.remoteValue}"`);
+      }
+      console.log(`   Sync halted. Review conflicts and resolve manually.`);
+      return;
+    }
+    if (strategy === "report-only") {
+      console.log(`   \u2139\uFE0F  ${conflicts.length} conflict(s) detected (report-only mode):`);
+      for (const conflict of conflicts) {
+        console.log(`   - ${conflict.field}: local="${conflict.localValue}" vs remote="${conflict.remoteValue}"`);
+      }
+      return;
+    }
+    for (const conflict of conflicts) {
+      if (strategy === "remote-wins") {
+        console.log(`   \u{1F504} Resolving: ${conflict.description} (Jira wins)`);
+        if (conflict.field === "title") {
+          await this.specManager.saveMetadata(spec.metadata.id, {
+            title: conflict.remoteValue
+          });
+        }
+      } else if (strategy === "local-wins") {
+        console.log(`   \u{1F504} Resolving: ${conflict.description} (local wins \u2014 no remote update)`);
+      }
+    }
+  }
+  /**
+   * Write conflict report JSON file for detected conflicts.
+   */
+  async writeConflictReport(specId, conflicts) {
+    try {
+      const report = {
+        specId,
+        provider: "jira",
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        conflicts: conflicts.map((c) => ({
+          field: c.field,
+          localValue: c.localValue,
+          remoteValue: c.remoteValue,
+          description: c.description
+        }))
+      };
+      const reportsDir = path.join(
+        this.specManager.projectRoot || process.cwd(),
+        ".specweave",
+        "reports"
+      );
+      await fs.mkdir(reportsDir, { recursive: true });
+      const reportPath = path.join(reportsDir, "conflict-report.json");
+      await fs.writeFile(reportPath, JSON.stringify(report, null, 2));
+      console.log(`   \u{1F4C4} Conflict report written to ${reportPath}`);
+    } catch (err) {
+      console.warn("   \u26A0\uFE0F  Failed to write conflict report:", err.message);
+    }
+  }
+  /**
+   * Fetch Jira Epic details
+   */
+  async fetchJiraEpic(epicKey) {
+    const response = await this.client.get(`/issue/${epicKey}`);
+    const epicData = response.data;
+    return {
+      id: epicData.id,
+      key: epicKey,
+      summary: epicData.fields.summary,
+      description: epicData.fields.description,
+      status: epicData.fields.status,
+      url: `https://${this.config.domain}/browse/${epicKey}`
+    };
+  }
+  /**
+   * Find story by title pattern scoped to a specific spec (via label).
+   * US IDs like "US-001" are reused across features, so we must scope to
+   * the spec label (e.g. "spec:FS-526") to avoid false matches.
+   */
+  async findStoryByTitle(usId, specId) {
+    const specFilter = specId ? ` AND labels = "spec:${specId}"` : "";
+    const jql = `project = ${this.config.projectKey} AND summary ~ "[${usId}]"${specFilter} AND issuetype not in (Epic)`;
+    const issues = await searchAllIssues(this.client, {
+      jql,
+      fields: "summary,description,status,labels",
+      maxResults: 1
+    });
+    return issues.length > 0 ? {
+      id: issues[0].id,
+      key: issues[0].key,
+      summary: issues[0].fields.summary,
+      description: issues[0].fields.description,
+      status: issues[0].fields.status,
+      labels: issues[0].fields.labels || []
+    } : null;
+  }
+  /**
+   * Create Jira Story
+   */
+  async createStory(story) {
+    const preferredType = this.mapTypeToJira(story.type, "Story");
+    const issueType = await this.resolveIssueType(preferredType);
+    const { field: epicField, style } = await getEpicLinkFieldForProject(
+      this.config.domain,
+      this.config.projectKey,
+      { email: this.config.email, apiToken: this.config.apiToken }
+    );
+    const fields = {
+      project: {
+        key: this.config.projectKey
+      },
+      summary: story.summary,
+      description: toDescription(story.description, this.config.domain),
+      issuetype: {
+        name: issueType
+      },
+      labels: story.labels,
+      priority: {
+        name: this.mapPriorityToJira(story.priority)
+      }
+    };
+    if (style === "next-gen") {
+      fields.parent = { key: story.epicLink };
+    } else {
+      fields[epicField] = story.epicLink;
+    }
+    const payload = { fields };
+    const response = await this.client.post("/issue", payload);
+    const storyData = response.data;
+    return {
+      id: storyData.id,
+      key: storyData.key,
+      summary: story.summary,
+      description: story.description,
+      status: { name: "To Do" },
+      labels: story.labels
+    };
+  }
+  /**
+   * Update Jira Story
+   */
+  async updateStory(storyKey, updates) {
+    const payload = {
+      fields: {}
+    };
+    if (updates.summary) {
+      payload.fields.summary = updates.summary;
+    }
+    if (updates.description) {
+      payload.fields.description = toDescription(updates.description, this.config.domain);
+    }
+    if (updates.epicLink) {
+      const { field: epicField, style } = await getEpicLinkFieldForProject(
+        this.config.domain,
+        this.config.projectKey,
+        { email: this.config.email, apiToken: this.config.apiToken }
+      );
+      if (style === "next-gen") {
+        payload.fields.parent = { key: updates.epicLink };
+      } else {
+        payload.fields[epicField] = updates.epicLink;
+      }
+    }
+    await this.client.put(`/issue/${storyKey}`, payload);
+    if (updates.status) {
+      await this.transitionIssue(storyKey, updates.status);
+    }
+  }
+  /**
+   * Transition issue to new status
+   */
+  async transitionIssue(issueKey, targetStatus) {
+    const transitionsResponse = await this.client.get(`/issue/${issueKey}/transitions`);
+    const transitions = transitionsResponse.data.transitions;
+    const transition = transitions.find(
+      (t) => t.to.name.toLowerCase() === targetStatus.toLowerCase()
+    );
+    if (!transition) {
+      console.warn(`   \u26A0\uFE0F  Cannot transition ${issueKey} to ${targetStatus} (no valid transition)`);
+      return;
+    }
+    await this.client.post(`/issue/${issueKey}/transitions`, {
+      transition: {
+        id: transition.id
+      }
+    });
+  }
+  /**
+   * Resolve the actual issue type name available in this project.
+   * Falls back through preferred → alternatives if the preferred type doesn't exist.
+   */
+  async resolveIssueType(preferred) {
+    try {
+      const response = await this.client.get(
+        `/issue/createmeta/${this.config.projectKey}/issuetypes`
+      );
+      const types = response.data.issueTypes || [];
+      const available = types.filter((t) => !t.subtask).map((t) => t.name);
+      if (available.includes(preferred)) return preferred;
+      const fallbacks = ["Story", "Task", "New Feature", "Improvement"];
+      for (const fb of fallbacks) {
+        if (available.includes(fb)) {
+          console.log(`   \u2139\uFE0F  Issue type "${preferred}" not available, using "${fb}"`);
+          return fb;
+        }
+      }
+      if (available.length > 0) {
+        console.log(`   \u2139\uFE0F  Issue type "${preferred}" not available, using "${available[0]}"`);
+        return available[0];
+      }
+    } catch {
+    }
+    return preferred;
+  }
+  /**
+   * Map SpecWeave priority to JIRA priority name
+   *
+   * JIRA standard priority names: Highest, High, Medium, Low, Lowest
+   */
+  mapPriorityToJira(priority) {
+    if (!priority) return "Medium";
+    const map = {
+      P0: "Highest",
+      P1: "High",
+      P2: "Medium",
+      P3: "Low",
+      p0: "Highest",
+      p1: "High",
+      p2: "Medium",
+      p3: "Low"
+    };
+    return map[priority] || "Medium";
+  }
+  /**
+   * Map SpecWeave type to JIRA issue type
+   *
+   * Supports: Epic, Story, Bug, Task
+   */
+  mapTypeToJira(type, defaultType = "Story") {
+    if (!type) return defaultType;
+    const normalizedType = type.toLowerCase();
+    const map = {
+      bug: "Bug",
+      feature: "Epic",
+      epic: "Epic",
+      story: "Story",
+      task: "Task",
+      enhancement: "Story"
+    };
+    return map[normalizedType] || defaultType;
+  }
+}
+export {
+  JiraSpecSync,
+  buildStoryDescription
+};