specweave 1.0.350 → 1.0.352

package/plugins/specweave-jira/lib/content-format-adapter.ts

@@ -0,0 +1,189 @@
+/**
+ * Content Format Adapter
+ *
+ * Converts content between formats based on JIRA API version:
+ * - API v3 (Cloud): Atlassian Document Format (ADF)
+ * - API v2 (Server/DC): Wiki markup
+ *
+ * @module content-format-adapter
+ */
+
+import { getApiVersion } from './jira-deployment-detector.js';
+
+/** ADF document node */
+export interface AdfDocument {
+  type: 'doc';
+  version: 1;
+  content: AdfNode[];
+}
+
+export interface AdfNode {
+  type: string;
+  content?: AdfNode[];
+  text?: string;
+  attrs?: Record<string, any>;
+  marks?: Array<{ type: string; attrs?: Record<string, any> }>;
+}
+
+/**
+ * Convert text/wiki markup to ADF document format.
+ */
+export function toADF(text: string): AdfDocument {
+  const lines = text.split('\n');
+  const content: AdfNode[] = [];
+  let currentParagraph: AdfNode[] = [];
+
+  const flushParagraph = () => {
+    if (currentParagraph.length > 0) {
+      content.push({ type: 'paragraph', content: [...currentParagraph] });
+      currentParagraph = [];
+    }
+  };
+
+  for (const line of lines) {
+    // Headings: h1. h2. h3. or # ## ###
+    const wikiHeadingMatch = line.match(/^h(\d)\.\s+(.+)$/);
+    const mdHeadingMatch = line.match(/^(#{1,6})\s+(.+)$/);
+
+    if (wikiHeadingMatch) {
+      flushParagraph();
+      const level = parseInt(wikiHeadingMatch[1]);
+      content.push({
+        type: 'heading',
+        attrs: { level },
+        content: [{ type: 'text', text: wikiHeadingMatch[2] }],
+      });
+      continue;
+    }
+
+    if (mdHeadingMatch) {
+      flushParagraph();
+      const level = mdHeadingMatch[1].length;
+      content.push({
+        type: 'heading',
+        attrs: { level },
+        content: [{ type: 'text', text: mdHeadingMatch[2] }],
+      });
+      continue;
+    }
+
+    // Horizontal rule: ---- or ---
+    if (/^-{3,}$/.test(line.trim())) {
+      flushParagraph();
+      content.push({ type: 'rule' });
+      continue;
+    }
+
+    // Bullet list item: * item or - item
+    const bulletMatch = line.match(/^\*\s+(.+)$/) || line.match(/^-\s+(.+)$/);
+    if (bulletMatch) {
+      flushParagraph();
+      const listItem: AdfNode = {
+        type: 'listItem',
+        content: [{ type: 'paragraph', content: [{ type: 'text', text: bulletMatch[1] }] }],
+      };
+      // Append to existing bulletList if the last node is one (consecutive items)
+      const lastNode = content[content.length - 1];
+      if (lastNode && lastNode.type === 'bulletList' && lastNode.content) {
+        lastNode.content.push(listItem);
+      } else {
+        content.push({ type: 'bulletList', content: [listItem] });
+      }
+      continue;
+    }
+
+    // Empty line = paragraph break
+    if (line.trim() === '') {
+      flushParagraph();
+      continue;
+    }
+
+    // Bold: *text* → strong mark
+    let textContent = line;
+    const textNodes: AdfNode[] = [];
+
+    // Simple inline formatting: *bold* and _italic_
+    const parts = textContent.split(/(\*[^*]+\*|_[^_]+_)/);
+    for (const part of parts) {
+      if (part.startsWith('*') && part.endsWith('*') && part.length > 2) {
+        textNodes.push({
+          type: 'text',
+          text: part.slice(1, -1),
+          marks: [{ type: 'strong' }],
+        });
+      } else if (part.startsWith('_') && part.endsWith('_') && part.length > 2) {
+        textNodes.push({
+          type: 'text',
+          text: part.slice(1, -1),
+          marks: [{ type: 'em' }],
+        });
+      } else if (part) {
+        textNodes.push({ type: 'text', text: part });
+      }
+    }
+
+    currentParagraph.push(...textNodes);
+  }
+
+  flushParagraph();
+
+  // Ensure at least one paragraph
+  if (content.length === 0) {
+    content.push({
+      type: 'paragraph',
+      content: [{ type: 'text', text: text || '' }],
+    });
+  }
+
+  return {
+    type: 'doc',
+    version: 1,
+    content,
+  };
+}
+
+/**
+ * Convert content to wiki markup format (for JIRA Server/DC API v2).
+ * If already in wiki markup, returns as-is.
+ */
+export function toWikiMarkup(text: string): string {
+  // Already wiki markup — return as-is
+  return text;
+}
+
+/**
+ * Format content based on JIRA API version.
+ *
+ * @param text - Raw text/wiki markup content
+ * @param domain - JIRA domain (used to look up cached API version)
+ * @returns ADF document for v3/Cloud, wiki markup string for v2/Server
+ */
+export function formatContent(text: string, domain: string): AdfDocument | string {
+  const version = getApiVersion(domain);
+  if (version === '3') {
+    return toADF(text);
+  }
+  return toWikiMarkup(text);
+}
+
+/**
+ * Format a description field for JIRA issue create/update payload.
+ *
+ * @param text - Raw description text
+ * @param domain - JIRA domain
+ * @returns Properly formatted description for the API version
+ */
+export function toDescription(text: string, domain: string): AdfDocument | string {
+  return formatContent(text, domain);
+}
+
+/**
+ * Format a comment body for JIRA issue comment payload.
+ *
+ * @param text - Raw comment text
+ * @param domain - JIRA domain
+ * @returns Properly formatted comment body for the API version
+ */
+export function toCommentBody(text: string, domain: string): AdfDocument | string {
+  return formatContent(text, domain);
+}

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

@@ -1,6 +1,7 @@
 import { EnhancedContentBuilder } from "../../../dist/src/core/sync/enhanced-content-builder.js";
 import { SpecIncrementMapper } from "../../../dist/src/core/sync/spec-increment-mapper.js";
 import { parseSpecContent } from "../../../dist/src/core/spec-content-sync.js";
+import { readIssueKey } from "./metadata-paths.js";
 import * as path from "path";
 import * as fs from "fs/promises";
 async function syncSpecToJiraWithEnhancedContent(options) {
@@ -61,11 +62,26 @@ async function syncSpecToJiraWithEnhancedContent(options) {
       tasksLinked: taskMapping?.tasks.length || 0
     };
     if (domain && project && !dryRun) {
-      result.epicKey = `SPEC-001`;
-      result.epicUrl = `https://${domain}/browse/SPEC-001`;
-      if (verbose) {
-        console.log(`\u26A0\uFE0F  JIRA API integration not implemented in this file`);
-        console.log(`   Use jira-spec-sync.ts for actual JIRA synchronization`);
+      // Read real JIRA key from metadata if available
+      const rootDir = await findSpecWeaveRoot(specPath);
+      const metadataPath = path.join(rootDir, '.specweave', 'increments', specId, 'metadata.json');
+      let realKey = null;
+      try {
+        const meta = JSON.parse(await fs.readFile(metadataPath, 'utf-8'));
+        realKey = readIssueKey(meta);
+      } catch { /* no metadata */ }
+
+      if (realKey) {
+        result.epicKey = realKey;
+        result.epicUrl = `https://${domain}/browse/${realKey}`;
+      } else {
+        // No real JIRA key — return null instead of placeholder
+        result.epicKey = null;
+        result.epicUrl = null;
+        if (verbose) {
+          console.log(`\u26A0\uFE0F  JIRA API integration not implemented in this file`);
+          console.log(`   Use jira-spec-sync.ts for actual JIRA synchronization`);
+        }
       }
     }
     return result;

package/plugins/specweave-jira/lib/jira-deployment-detector.js

@@ -0,0 +1,63 @@
+import axios from "axios";
+const deploymentCache = /* @__PURE__ */ new Map();
+async function detectDeploymentType(domain, auth) {
+  const cached = deploymentCache.get(domain);
+  if (cached) return cached;
+  try {
+    const response = await axios.get(
+      `https://${domain}/rest/api/2/serverInfo`,
+      {
+        auth: {
+          username: auth.email,
+          password: auth.apiToken
+        },
+        headers: {
+          Accept: "application/json"
+        },
+        timeout: 1e4
+      }
+    );
+    const data = response.data;
+    const deploymentType = (data.deploymentType || "").toLowerCase();
+    const isCloud2 = deploymentType === "cloud" || domain.endsWith(".atlassian.net");
+    const info = {
+      type: isCloud2 ? "cloud" : "server",
+      apiVersion: isCloud2 ? "3" : "2",
+      baseUrl: `https://${domain}/rest/api/${isCloud2 ? "3" : "2"}`
+    };
+    deploymentCache.set(domain, info);
+    return info;
+  } catch {
+    const isCloud2 = domain.endsWith(".atlassian.net");
+    const info = {
+      type: isCloud2 ? "cloud" : "server",
+      apiVersion: isCloud2 ? "3" : "2",
+      baseUrl: `https://${domain}/rest/api/${isCloud2 ? "3" : "2"}`
+    };
+    deploymentCache.set(domain, info);
+    return info;
+  }
+}
+function getApiBaseUrl(domain) {
+  const cached = deploymentCache.get(domain);
+  if (cached) return cached.baseUrl;
+  return `https://${domain}/rest/api/3`;
+}
+function getApiVersion(domain) {
+  const cached = deploymentCache.get(domain);
+  return cached?.apiVersion ?? "3";
+}
+function isCloud(domain) {
+  const cached = deploymentCache.get(domain);
+  return cached ? cached.type === "cloud" : domain.endsWith(".atlassian.net");
+}
+function clearDeploymentCache() {
+  deploymentCache.clear();
+}
+export {
+  clearDeploymentCache,
+  detectDeploymentType,
+  getApiBaseUrl,
+  getApiVersion,
+  isCloud
+};

package/plugins/specweave-jira/lib/jira-deployment-detector.ts

@@ -0,0 +1,113 @@
+/**
+ * JIRA Deployment Type Detector
+ *
+ * Detects whether a JIRA instance is Cloud or Server/Data Center
+ * and returns the correct API version to use.
+ *
+ * - Cloud: /rest/api/3 (ADF content format)
+ * - Server/DC: /rest/api/2 (wiki markup content format)
+ *
+ * Results are cached per domain to avoid repeated lookups.
+ *
+ * @module jira-deployment-detector
+ */
+
+import axios from 'axios';
+
+export interface DeploymentInfo {
+  type: 'cloud' | 'server';
+  apiVersion: '2' | '3';
+  baseUrl: string;
+}
+
+/** Cache: domain → deployment info */
+const deploymentCache = new Map<string, DeploymentInfo>();
+
+/**
+ * Detect JIRA deployment type by calling /rest/api/2/serverInfo.
+ * This endpoint exists on both Cloud and Server/DC.
+ *
+ * Cloud instances return deploymentType: "Cloud".
+ * Server/DC instances return deploymentType: "Server" or "DataCenter".
+ */
+export async function detectDeploymentType(
+  domain: string,
+  auth: { email: string; apiToken: string }
+): Promise<DeploymentInfo> {
+  // Check cache first
+  const cached = deploymentCache.get(domain);
+  if (cached) return cached;
+
+  try {
+    const response = await axios.get(
+      `https://${domain}/rest/api/2/serverInfo`,
+      {
+        auth: {
+          username: auth.email,
+          password: auth.apiToken,
+        },
+        headers: {
+          Accept: 'application/json',
+        },
+        timeout: 10000,
+      }
+    );
+
+    const data = response.data;
+    const deploymentType = (data.deploymentType || '').toLowerCase();
+
+    const isCloud = deploymentType === 'cloud' || domain.endsWith('.atlassian.net');
+
+    const info: DeploymentInfo = {
+      type: isCloud ? 'cloud' : 'server',
+      apiVersion: isCloud ? '3' : '2',
+      baseUrl: `https://${domain}/rest/api/${isCloud ? '3' : '2'}`,
+    };
+
+    deploymentCache.set(domain, info);
+    return info;
+  } catch {
+    // Fallback: if .atlassian.net assume Cloud, otherwise Server
+    const isCloud = domain.endsWith('.atlassian.net');
+    const info: DeploymentInfo = {
+      type: isCloud ? 'cloud' : 'server',
+      apiVersion: isCloud ? '3' : '2',
+      baseUrl: `https://${domain}/rest/api/${isCloud ? '3' : '2'}`,
+    };
+
+    deploymentCache.set(domain, info);
+    return info;
+  }
+}
+
+/**
+ * Build the full API base URL for a given JIRA domain.
+ * Uses cached deployment info if available.
+ */
+export function getApiBaseUrl(domain: string): string {
+  const cached = deploymentCache.get(domain);
+  if (cached) return cached.baseUrl;
+  // Default to v3 (Cloud) if not yet detected
+  return `https://${domain}/rest/api/3`;
+}
+
+/**
+ * Get the API version string for a domain.
+ */
+export function getApiVersion(domain: string): '2' | '3' {
+  const cached = deploymentCache.get(domain);
+  return cached?.apiVersion ?? '3';
+}
+
+/**
+ * Check if a domain is Cloud deployment.
+ */
+export function isCloud(domain: string): boolean {
+  const cached = deploymentCache.get(domain);
+  return cached ? cached.type === 'cloud' : domain.endsWith('.atlassian.net');
+}
+
+/** Clear cache (for testing) */
+export function clearDeploymentCache(): void {
+  deploymentCache.clear();
+}

package/plugins/specweave-jira/lib/jira-duplicate-detector.js

@@ -1,4 +1,6 @@
 import { consoleLogger } from "../../../src/utils/logger.js";
+import { getApiBaseUrl } from "./jira-deployment-detector.js";
+import { toCommentBody } from "./content-format-adapter.js";
 class JiraDuplicateDetector {
   constructor(options = {}) {
     this.domain = options.domain || process.env.JIRA_DOMAIN || "";
@@ -53,10 +55,9 @@ class JiraDuplicateDetector {
     } catch (error) {
       this.logger.log(`\u26A0\uFE0F  Verification check failed: ${error.message}`);
       return {
-        success: true,
-        // Assume success on error
+        success: false,
         expectedCount,
-        actualCount: expectedCount,
+        actualCount: -1,
         duplicates: []
       };
     }
@@ -178,7 +179,7 @@ class JiraDuplicateDetector {
       throw new Error("JIRA credentials not configured");
     }
     const jql = encodeURIComponent(`summary ~ "${summaryPattern}" ORDER BY created ASC`);
-    const url = `https://${this.domain}/rest/api/3/search?jql=${jql}&fields=summary,status,created`;
+    const url = `${getApiBaseUrl(this.domain)}/search?jql=${jql}&fields=summary,status,created`;
     const response = await fetch(url, {
       headers: {
         Authorization: `Basic ${this.auth}`,
@@ -209,7 +210,7 @@ class JiraDuplicateDetector {
     if (!closeTransition) {
       throw new Error(`No close transition found. Available: ${transitions.map((t) => t.name).join(", ")}`);
     }
-    const url = `https://${this.domain}/rest/api/3/issue/${issueKey}/transitions`;
+    const url = `${getApiBaseUrl(this.domain)}/issue/${issueKey}/transitions`;
     const response = await fetch(url, {
       method: "POST",
       headers: {
@@ -229,7 +230,7 @@ class JiraDuplicateDetector {
    * Get available transitions for an issue
    */
   async getTransitions(issueKey) {
-    const url = `https://${this.domain}/rest/api/3/issue/${issueKey}/transitions`;
+    const url = `${getApiBaseUrl(this.domain)}/issue/${issueKey}/transitions`;
     const response = await fetch(url, {
       headers: {
         Authorization: `Basic ${this.auth}`,
@@ -246,38 +247,20 @@ class JiraDuplicateDetector {
    * Add duplicate comment to issue
    */
   async addComment(issueKey, originalKey) {
-    const url = `https://${this.domain}/rest/api/3/issue/${issueKey}/comment`;
-    const comment = `h2. Duplicate of ${originalKey}
+    const url = `${getApiBaseUrl(this.domain)}/issue/${issueKey}/comment`;
+    const commentText = `h2. Duplicate of ${originalKey}
 
 This issue was automatically closed by SpecWeave cleanup because it is a duplicate.
 
-The original issue (${originalKey}) contains the same content and should be used for tracking instead.
-
-----
-\u{1F916} Auto-closed by SpecWeave Duplicate Cleanup`;
+The original issue (${originalKey}) contains the same content and should be used for tracking instead.`;
+    const body = toCommentBody(commentText, this.domain);
     const response = await fetch(url, {
       method: "POST",
       headers: {
         Authorization: `Basic ${this.auth}`,
         "Content-Type": "application/json"
       },
-      body: JSON.stringify({
-        body: {
-          type: "doc",
-          version: 1,
-          content: [
-            {
-              type: "paragraph",
-              content: [
-                {
-                  type: "text",
-                  text: comment
-                }
-              ]
-            }
-          ]
-        }
-      })
+      body: JSON.stringify({ body })
     });
     if (!response.ok) {
       this.logger.log(`     \u26A0\uFE0F  Failed to add comment to ${issueKey}`);

package/plugins/specweave-jira/lib/jira-duplicate-detector.ts

@@ -10,6 +10,8 @@
  */
 
 import { Logger, consoleLogger } from '../../../src/utils/logger.js';
+import { getApiBaseUrl } from './jira-deployment-detector.js';
+import { toCommentBody } from './content-format-adapter.js';
 
 export interface JiraIssue {
   key: string;
@@ -122,9 +124,9 @@ export class JiraDuplicateDetector {
     } catch (error: any) {
       this.logger.log(`⚠️  Verification check failed: ${error.message}`);
       return {
-        success: true, // Assume success on error
+        success: false,
         expectedCount,
-        actualCount: expectedCount,
+        actualCount: -1,
         duplicates: [],
       };
     }
@@ -281,7 +283,7 @@ export class JiraDuplicateDetector {
     }
 
     const jql = encodeURIComponent(`summary ~ "${summaryPattern}" ORDER BY created ASC`);
-    const url = `https://${this.domain}/rest/api/3/search?jql=${jql}&fields=summary,status,created`;
+    const url = `${getApiBaseUrl(this.domain)}/search?jql=${jql}&fields=summary,status,created`;
 
     const response = await fetch(url, {
       headers: {
@@ -328,7 +330,7 @@ export class JiraDuplicateDetector {
       throw new Error(`No close transition found. Available: ${transitions.map((t: any) => t.name).join(', ')}`);
     }
 
-    const url = `https://${this.domain}/rest/api/3/issue/${issueKey}/transitions`;
+    const url = `${getApiBaseUrl(this.domain)}/issue/${issueKey}/transitions`;
 
     const response = await fetch(url, {
       method: 'POST',
@@ -351,7 +353,7 @@ export class JiraDuplicateDetector {
    * Get available transitions for an issue
    */
   private async getTransitions(issueKey: string): Promise<any[]> {
-    const url = `https://${this.domain}/rest/api/3/issue/${issueKey}/transitions`;
+    const url = `${getApiBaseUrl(this.domain)}/issue/${issueKey}/transitions`;
 
     const response = await fetch(url, {
       headers: {
@@ -372,16 +374,16 @@ export class JiraDuplicateDetector {
    * Add duplicate comment to issue
    */
   private async addComment(issueKey: string, originalKey: string): Promise<void> {
-    const url = `https://${this.domain}/rest/api/3/issue/${issueKey}/comment`;
+    const url = `${getApiBaseUrl(this.domain)}/issue/${issueKey}/comment`;
 
-    const comment = `h2. Duplicate of ${originalKey}
+    const commentText = `h2. Duplicate of ${originalKey}
 
 This issue was automatically closed by SpecWeave cleanup because it is a duplicate.
 
-The original issue (${originalKey}) contains the same content and should be used for tracking instead.
+The original issue (${originalKey}) contains the same content and should be used for tracking instead.`;
 
-----
-🤖 Auto-closed by SpecWeave Duplicate Cleanup`;
+    // Use format adapter for correct format (ADF for Cloud, wiki for Server)
+    const body = toCommentBody(commentText, this.domain);
 
     const response = await fetch(url, {
       method: 'POST',
@@ -389,23 +391,7 @@ The original issue (${originalKey}) contains the same content and should be used
         Authorization: `Basic ${this.auth}`,
         'Content-Type': 'application/json',
       },
-      body: JSON.stringify({
-        body: {
-          type: 'doc',
-          version: 1,
-          content: [
-            {
-              type: 'paragraph',
-              content: [
-                {
-                  type: 'text',
-                  text: comment,
-                },
-              ],
-            },
-          ],
-        },
-      }),
+      body: JSON.stringify({ body }),
     });
 
     if (!response.ok) {

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

@@ -1,11 +1,13 @@
 import * as fs from "../../../src/utils/fs-native.js";
 import * as path from "path";
 import * as yaml from "yaml";
+import { toDescription } from "./content-format-adapter.js";
 class JiraEpicSync {
-  constructor(client, specsDir, projectKey) {
+  constructor(client, specsDir, projectKey, domain) {
     this.client = client;
     this.specsDir = specsDir;
     this.projectKey = projectKey;
+    this.domain = domain || client["credentials"]?.domain || "";
   }
   /**
    * Sync Epic folder to JIRA (Epic + Stories)
@@ -92,8 +94,14 @@ class JiraEpicSync {
    * Find Epic folder by ID (FS-001 or just 001)
    */
   async findEpicFolder(epicId) {
-    const normalizedId = epicId.startsWith("FS-") ? epicId : `FS-${epicId.padStart(3, "0")}`;
     const folders = await fs.readdir(this.specsDir);
+    for (const folder of folders) {
+      if (folder.startsWith(epicId)) {
+        return path.join(this.specsDir, folder);
+      }
+    }
+    const prefix = `${this.projectKey}-`;
+    const normalizedId = epicId.startsWith(prefix) ? epicId : `${prefix}${epicId.padStart(3, "0")}`;
     for (const folder of folders) {
       if (folder.startsWith(normalizedId)) {
         return path.join(this.specsDir, folder);
@@ -142,12 +150,13 @@ class JiraEpicSync {
    */
   async createEpic(epic) {
     const summary = `[${epic.id}] ${epic.title}`;
-    const description = `Epic: ${epic.title}
+    const rawDescription = `Epic: ${epic.title}
 
 Progress: ${epic.completed_increments}/${epic.total_increments} increments (${epic.progress})
 
 Priority: ${epic.priority}
 Status: ${epic.status}`;
+    const description = toDescription(rawDescription, this.domain);
     const issueData = {
       issueType: "Epic",
       summary,
@@ -158,7 +167,7 @@ Status: ${epic.status}`;
     const issue = await this.client.createIssue(issueData, this.projectKey);
     return {
       key: issue.key,
-      url: issue.self.replace("/rest/api/3/issue/", "/browse/")
+      url: issue.self.replace(/\/rest\/api\/\d+\/issue\//, "/browse/")
     };
   }
   /**
@@ -166,12 +175,13 @@ Status: ${epic.status}`;
    */
   async updateEpic(epicKey, epic) {
     const summary = `[${epic.id}] ${epic.title}`;
-    const description = `Epic: ${epic.title}
+    const rawDescription = `Epic: ${epic.title}
 
 Progress: ${epic.completed_increments}/${epic.total_increments} increments (${epic.progress})
 
 Priority: ${epic.priority}
 Status: ${epic.status}`;
+    const description = toDescription(rawDescription, this.domain);
     await this.client.updateIssue({
       key: epicKey,
       summary,