specweave 1.0.350 → 1.0.352

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

@@ -31,6 +31,8 @@ import {
   formatForJira,
   CommentContent,
 } from '../../../src/core/comment-builder.js';
+import { readIssueKey } from './metadata-paths.js';
+import { getApiBaseUrl } from './jira-deployment-detector.js';
 import path from 'path';
 import fs from 'fs/promises';
 
@@ -84,7 +86,7 @@ export async function syncSpecCommitsToJira(
       return result;
     }
 
-    const jiraIssueKey = metadata.jira?.issueKey;
+    const jiraIssueKey = readIssueKey(metadata);
     if (!jiraIssueKey) {
       if (verbose) {
         console.log('No JIRA issue linked to increment');
@@ -94,7 +96,7 @@ export async function syncSpecCommitsToJira(
 
     // 2. Create JIRA client
     const client = axios.create({
-      baseURL: `https://${config.domain}/rest/api/3`,
+      baseURL: getApiBaseUrl(config.domain),
       auth: {
         username: config.email,
         password: config.apiToken,
@@ -285,7 +287,7 @@ export async function postCommitBatchUpdate(
 ): Promise<boolean> {
   try {
     const client = axios.create({
-      baseURL: `https://${config.domain}/rest/api/3`,
+      baseURL: getApiBaseUrl(config.domain),
       auth: {
         username: config.email,
         password: config.apiToken,

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

@@ -1,12 +1,18 @@
 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 { 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";
 class JiraSpecSync {
   constructor(config, projectRoot = process.cwd()) {
     this.specManager = new SpecMetadataManager(projectRoot);
     this.config = config;
     this.client = axios.create({
-      baseURL: `https://${config.domain}/rest/api/3`,
+      baseURL: getApiBaseUrl(config.domain),
       auth: {
         username: config.email,
         password: config.apiToken
@@ -17,6 +23,16 @@ class JiraSpecSync {
       }
     });
   }
+  /**
+   * 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)
    */
@@ -106,6 +122,7 @@ class JiraSpecSync {
         };
       }
       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 {
@@ -131,7 +148,7 @@ class JiraSpecSync {
    */
   async createJiraEpic(spec) {
     const epicSummary = `[${spec.metadata.id.toUpperCase()}] ${spec.metadata.title}`;
-    const epicDescription = this.generateEpicDescription(spec);
+    const epicDescription = toDescription(this.generateEpicDescription(spec), this.config.domain);
     const issueType = this.mapTypeToJira(spec.metadata.type, "Epic");
     const payload = {
       fields: {
@@ -169,7 +186,7 @@ class JiraSpecSync {
    */
   async updateJiraEpic(epicKey, spec) {
     const epicSummary = `[${spec.metadata.id.toUpperCase()}] ${spec.metadata.title}`;
-    const epicDescription = this.generateEpicDescription(spec);
+    const epicDescription = toDescription(this.generateEpicDescription(spec), this.config.domain);
     const payload = {
       fields: {
         summary: epicSummary,
@@ -295,20 +312,72 @@ ${acList}
     return conflicts;
   }
   /**
-   * Resolve 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) {
+  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 (conflict.resolution === "remote-wins") {
+      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
    */
@@ -329,14 +398,11 @@ ${acList}
    */
   async findStoryByTitle(usId) {
     const jql = `project = ${this.config.projectKey} AND summary ~ "[${usId}]" AND issuetype = Story`;
-    const response = await this.client.get("/search", {
-      params: {
-        jql,
-        maxResults: 1,
-        fields: "summary,description,status,labels"
-      }
+    const issues = await searchAllIssues(this.client, {
+      jql,
+      fields: "summary,description,status,labels",
+      maxResults: 1
     });
-    const issues = response.data.issues;
     return issues.length > 0 ? {
       id: issues[0].id,
       key: issues[0].key,
@@ -351,26 +417,31 @@ ${acList}
    */
   async createStory(story) {
     const issueType = this.mapTypeToJira(story.type, "Story");
-    const payload = {
-      fields: {
-        project: {
-          key: this.config.projectKey
-        },
-        summary: story.summary,
-        description: story.description,
-        issuetype: {
-          name: issueType
-        },
-        labels: story.labels,
-        // Link to epic (field name may vary by Jira configuration)
-        customfield_10014: story.epicLink,
-        // Epic Link field (adjust if needed)
-        // Set native JIRA priority field
-        priority: {
-          name: this.mapPriorityToJira(story.priority)
-        }
+    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: story.description,
+      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 {

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

@@ -15,6 +15,8 @@
 
 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 {
   SpecContent,
   UserStory,
@@ -22,13 +24,17 @@ import {
   SpecSyncConflict
 } from '../../../src/core/types/spec-metadata.js';
 import { execFileNoThrow } from '../../../src/utils/execFileNoThrow.js';
+import { detectDeploymentType, getApiBaseUrl } from './jira-deployment-detector.js';
+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';
 
 export interface JiraEpic {
   id: string;
   key: string; // e.g., SPEC-1
   summary: string;
-  description: string;
+  description: string | AdfDocument;
   status: {
     name: string; // To Do, In Progress, Done
   };
@@ -63,9 +69,9 @@ export class JiraSpecSync {
     this.specManager = new SpecMetadataManager(projectRoot);
     this.config = config;
 
-    // Create Jira API client
+    // Create Jira API client — baseURL set dynamically via init()
     this.client = axios.create({
-      baseURL: `https://${config.domain}/rest/api/3`,
+      baseURL: getApiBaseUrl(config.domain),
       auth: {
         username: config.email,
         password: config.apiToken
@@ -77,6 +83,17 @@ export class JiraSpecSync {
     });
   }
 
+  /**
+   * Initialize: detect deployment type and update client baseURL
+   */
+  async init(): Promise<void> {
+    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)
    */
@@ -191,7 +208,10 @@ export class JiraSpecSync {
 
       console.log(`⚠️  Detected ${conflicts.length} conflict(s)`);
 
-      // 5. Resolve conflicts (Jira wins by default for now)
+      // 5. Write conflict report
+      await this.writeConflictReport(specId, conflicts);
+
+      // 6. Resolve conflicts using configurable strategy (default: manual)
       await this.resolveConflicts(spec, conflicts);
 
       console.log('✅ Sync FROM Jira complete!');
@@ -221,7 +241,7 @@ export class JiraSpecSync {
    */
   private async createJiraEpic(spec: SpecContent): Promise<JiraEpic> {
     const epicSummary = `[${spec.metadata.id.toUpperCase()}] ${spec.metadata.title}`;
-    const epicDescription = this.generateEpicDescription(spec);
+    const epicDescription = toDescription(this.generateEpicDescription(spec), this.config.domain);
 
     // Determine issue type based on spec type (supports Bug for bug-type specs)
     const issueType = this.mapTypeToJira(spec.metadata.type, 'Epic');
@@ -230,7 +250,7 @@ export class JiraSpecSync {
       fields: {
         project: { key: string };
         summary: string;
-        description: string;
+        description: any;
         issuetype: { name: string };
         labels: string[];
         priority?: { name: string };
@@ -276,7 +296,7 @@ export class JiraSpecSync {
    */
   private async updateJiraEpic(epicKey: string, spec: SpecContent): Promise<JiraEpic> {
     const epicSummary = `[${spec.metadata.id.toUpperCase()}] ${spec.metadata.title}`;
-    const epicDescription = this.generateEpicDescription(spec);
+    const epicDescription = toDescription(this.generateEpicDescription(spec), this.config.domain);
 
     const payload = {
       fields: {
@@ -442,25 +462,85 @@ ${acList}
   }
 
   /**
-   * Resolve 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
    */
   private async resolveConflicts(
     spec: SpecContent,
-    conflicts: SpecSyncConflict[]
+    conflicts: SpecSyncConflict[],
+    strategy: 'manual' | 'remote-wins' | 'local-wins' | 'report-only' = 'manual'
   ): Promise<void> {
+    if (strategy === 'manual') {
+      console.log(`   ⚠️  ${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(`   ℹ️  ${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 (conflict.resolution === 'remote-wins') {
+      if (strategy === 'remote-wins') {
         console.log(`   🔄 Resolving: ${conflict.description} (Jira wins)`);
-        // Update spec metadata from Jira
         if (conflict.field === 'title') {
           await this.specManager.saveMetadata(spec.metadata.id, {
             title: conflict.remoteValue
           });
         }
+      } else if (strategy === 'local-wins') {
+        console.log(`   🔄 Resolving: ${conflict.description} (local wins — no remote update)`);
+        // Local wins: keep spec as-is, no action needed
       }
     }
   }
 
+  /**
+   * Write conflict report JSON file for detected conflicts.
+   */
+  private async writeConflictReport(
+    specId: string,
+    conflicts: SpecSyncConflict[]
+  ): Promise<void> {
+    try {
+      const report = {
+        specId,
+        provider: 'jira',
+        timestamp: 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 as any).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(`   📄 Conflict report written to ${reportPath}`);
+    } catch (err) {
+      console.warn('   ⚠️  Failed to write conflict report:', (err as Error).message);
+    }
+  }
+
   /**
    * Fetch Jira Epic details
    */
@@ -484,15 +564,12 @@ ${acList}
   private async findStoryByTitle(usId: string): Promise<JiraStory | null> {
     const jql = `project = ${this.config.projectKey} AND summary ~ "[${usId}]" AND issuetype = Story`;
 
-    const response = await this.client.get('/search', {
-      params: {
-        jql,
-        maxResults: 1,
-        fields: 'summary,description,status,labels'
-      }
+    const issues = await searchAllIssues(this.client, {
+      jql,
+      fields: 'summary,description,status,labels',
+      maxResults: 1,
     });
 
-    const issues = response.data.issues;
     return issues.length > 0 ? {
       id: issues[0].id,
       key: issues[0].key,
@@ -517,36 +594,37 @@ ${acList}
     // Determine issue type (supports Bug for bug-type stories)
     const issueType = this.mapTypeToJira(story.type, 'Story');
 
-    const payload: {
-      fields: {
-        project: { key: string };
-        summary: string;
-        description: string;
-        issuetype: { name: string };
-        labels: string[];
-        customfield_10014: string;
-        priority?: { name: string };
-      };
-    } = {
-      fields: {
-        project: {
-          key: this.config.projectKey
-        },
-        summary: story.summary,
-        description: story.description,
-        issuetype: {
-          name: issueType
-        },
-        labels: story.labels,
-        // Link to epic (field name may vary by Jira configuration)
-        customfield_10014: story.epicLink, // Epic Link field (adjust if needed)
-        // Set native JIRA priority field
-        priority: {
-          name: this.mapPriorityToJira(story.priority)
-        }
+    // Discover epic link field dynamically based on project style
+    const { field: epicField, style } = await getEpicLinkFieldForProject(
+      this.config.domain,
+      this.config.projectKey,
+      { email: this.config.email, apiToken: this.config.apiToken }
+    );
+
+    const fields: any = {
+      project: {
+        key: this.config.projectKey
+      },
+      summary: story.summary,
+      description: story.description,
+      issuetype: {
+        name: issueType
+      },
+      labels: story.labels,
+      priority: {
+        name: this.mapPriorityToJira(story.priority)
       }
     };
 
+    // Link to epic using the correct field for project style
+    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;
 

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

@@ -1,10 +1,12 @@
 import axios from "axios";
+import { detectDeploymentType, getApiBaseUrl } from "./jira-deployment-detector.js";
+import { toCommentBody } from "./content-format-adapter.js";
 class JiraStatusSync {
   constructor(domain, email, apiToken, projectKey) {
     this.domain = domain;
     this.projectKey = projectKey;
     this.client = axios.create({
-      baseURL: `https://${domain}/rest/api/3`,
+      baseURL: getApiBaseUrl(domain),
       auth: {
         username: email,
         password: apiToken
@@ -15,6 +17,16 @@ class JiraStatusSync {
       }
     });
   }
+  /**
+   * Initialize: detect deployment type and update client baseURL
+   */
+  async init() {
+    const deployment = await detectDeploymentType(this.domain, {
+      email: this.client.defaults.auth?.username || "",
+      apiToken: this.client.defaults.auth?.password || ""
+    });
+    this.client.defaults.baseURL = deployment.baseUrl;
+  }
   /**
    * Get current status from JIRA issue
    *
@@ -67,14 +79,15 @@ class JiraStatusSync {
    * @param newStatus - New SpecWeave status
    */
   async postStatusComment(issueKey, oldStatus, newStatus) {
-    const body = `\u{1F504} *Status Update*
+    const rawBody = `*Status Update*
 
 SpecWeave status changed:
-\u2022 *From*: ${oldStatus}
-\u2022 *To*: ${newStatus}
-\u2022 *When*: ${(/* @__PURE__ */ new Date()).toISOString()}
+* *From*: ${oldStatus}
+* *To*: ${newStatus}
+* *When*: ${(/* @__PURE__ */ new Date()).toISOString()}
 
 _Synced from SpecWeave_`;
+    const body = toCommentBody(rawBody, this.domain);
     await this.client.post(`/issue/${issueKey}/comment`, {
       body
     });

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

@@ -12,6 +12,8 @@
  */
 
 import axios, { AxiosInstance } from 'axios';
+import { detectDeploymentType, getApiBaseUrl } from './jira-deployment-detector.js';
+import { toCommentBody } from './content-format-adapter.js';
 
 /**
  * External status representation (JIRA-specific)
@@ -51,9 +53,9 @@ export class JiraStatusSync {
     this.domain = domain;
     this.projectKey = projectKey;
 
-    // Create JIRA API client
+    // Create JIRA API client — baseURL set dynamically via init()
     this.client = axios.create({
-      baseURL: `https://${domain}/rest/api/3`,
+      baseURL: getApiBaseUrl(domain),
       auth: {
         username: email,
         password: apiToken
@@ -65,6 +67,17 @@ export class JiraStatusSync {
     });
   }
 
+  /**
+   * Initialize: detect deployment type and update client baseURL
+   */
+  async init(): Promise<void> {
+    const deployment = await detectDeploymentType(this.domain, {
+      email: this.client.defaults.auth?.username || '',
+      apiToken: this.client.defaults.auth?.password || '',
+    });
+    this.client.defaults.baseURL = deployment.baseUrl;
+  }
+
   /**
    * Get current status from JIRA issue
    *
@@ -134,13 +147,15 @@ export class JiraStatusSync {
     oldStatus: string,
     newStatus: string
   ): Promise<void> {
-    const body = `🔄 *Status Update*\n\n` +
+    const rawBody = `*Status Update*\n\n` +
       `SpecWeave status changed:\n` +
-      `• *From*: ${oldStatus}\n` +
-      `• *To*: ${newStatus}\n` +
-      `• *When*: ${new Date().toISOString()}\n\n` +
+      `* *From*: ${oldStatus}\n` +
+      `* *To*: ${newStatus}\n` +
+      `* *When*: ${new Date().toISOString()}\n\n` +
       `_Synced from SpecWeave_`;
 
+    const body = toCommentBody(rawBody, this.domain);
+
     await this.client.post(`/issue/${issueKey}/comment`, {
       body
     });

package/plugins/specweave-jira/lib/metadata-paths.js

@@ -0,0 +1,38 @@
+const CANONICAL_JIRA_KEY_PATH = "external_sync.jira.issueKey";
+function readIssueKey(metadata) {
+  if (!metadata) return null;
+  const canonical = metadata?.external_sync?.jira?.issueKey;
+  if (canonical) return canonical;
+  const legacyIssue = metadata?.jira?.issue;
+  if (legacyIssue) return legacyIssue;
+  const legacyKey = metadata?.jira?.issueKey;
+  if (legacyKey) return legacyKey;
+  return null;
+}
+function writeIssueKey(metadata, key) {
+  if (!metadata) metadata = {};
+  if (!metadata.external_sync) metadata.external_sync = {};
+  if (!metadata.external_sync.jira) metadata.external_sync.jira = {};
+  metadata.external_sync.jira.issueKey = key;
+  return metadata;
+}
+function migrateToCanonical(metadata, cleanup = false) {
+  if (!metadata) return metadata;
+  const existingKey = readIssueKey(metadata);
+  if (!existingKey) return metadata;
+  writeIssueKey(metadata, existingKey);
+  if (cleanup) {
+    if (metadata.jira?.issue) delete metadata.jira.issue;
+    if (metadata.jira?.issueKey) delete metadata.jira.issueKey;
+    if (metadata.jira && Object.keys(metadata.jira).length === 0) {
+      delete metadata.jira;
+    }
+  }
+  return metadata;
+}
+export {
+  CANONICAL_JIRA_KEY_PATH,
+  migrateToCanonical,
+  readIssueKey,
+  writeIssueKey
+};