@stravica-ai/digital-operator-pa 0.1.39 → 0.1.41

package/dist/engineering-pa-core-extensions-atlassian/src/jira/adf.mjs

@@ -0,0 +1,388 @@
+// adf.mjs - Atlassian Document Format (ADF) helpers.
+//
+// Jira REST API v3 requires ADF for description and comment fields.
+// This module converts between plain text, markdown, and ADF structures.
+//
+// Zero external dependencies - pure data transformation.
+
+// ── Text → ADF ───────────────────────────────────────────────────────
+
+// Markdown block patterns.
+const HEADING_RE = /^(#{1,6})\s+(.*)$/;
+const BULLET_RE = /^[-*]\s+(.*)$/;
+const ORDERED_RE = /^\d+\.\s+(.*)$/;
+
+/**
+ * Convert text to an ADF document. Plain text by default; recognises a
+ * minimal markdown subset so descriptions render as proper Jira structure
+ * rather than literal markdown characters:
+ *
+ *   # H1 ... ###### H6     → heading (levels 1-6)
+ *   - item / * item        → bulletList
+ *   1. item / 2. item      → orderedList
+ *   **text**               → strong
+ *   *text*                 → em
+ *   `text`                 → code
+ *   [label](https://…)     → link
+ *
+ * Block separation is still double-newline (current contract). Within a
+ * block, lines either share a single block type (all-list or all-heading-line)
+ * or fall back to a paragraph with hardBreaks between lines.
+ *
+ * @param {string} text  Plain text (or minimal-markdown) input
+ * @returns {object}     ADF document
+ */
+export function textToAdf(text) {
+  if (!text || typeof text !== 'string') {
+    return {
+      version: 1,
+      type: 'doc',
+      content: [{ type: 'paragraph', content: [] }],
+    };
+  }
+
+  const blocks = text.split(/\n{2,}/);
+  const content = [];
+
+  for (const block of blocks) {
+    const lines = block.split('\n');
+    const first = lines[0];
+
+    // Heading: single-line block starting with #+
+    const hm = HEADING_RE.exec(first);
+    if (hm && lines.length === 1) {
+      content.push({
+        type: 'heading',
+        attrs: { level: hm[1].length },
+        content: parseInline(hm[2]),
+      });
+      continue;
+    }
+
+    // Bullet list: every line matches bullet pattern
+    if (lines.length > 0 && lines.every((l) => BULLET_RE.test(l))) {
+      content.push({
+        type: 'bulletList',
+        content: lines.map((l) => ({
+          type: 'listItem',
+          content: [
+            { type: 'paragraph', content: parseInline(BULLET_RE.exec(l)[1]) },
+          ],
+        })),
+      });
+      continue;
+    }
+
+    // Ordered list: every line matches ordered pattern
+    if (lines.length > 0 && lines.every((l) => ORDERED_RE.test(l))) {
+      content.push({
+        type: 'orderedList',
+        content: lines.map((l) => ({
+          type: 'listItem',
+          content: [
+            { type: 'paragraph', content: parseInline(ORDERED_RE.exec(l)[1]) },
+          ],
+        })),
+      });
+      continue;
+    }
+
+    // Default: paragraph with hardBreaks between lines, inline marks parsed
+    const inline = [];
+    for (let i = 0; i < lines.length; i++) {
+      if (i > 0) inline.push({ type: 'hardBreak' });
+      if (lines[i]) inline.push(...parseInline(lines[i]));
+    }
+    content.push({
+      type: 'paragraph',
+      content: inline.length > 0 ? inline : [],
+    });
+  }
+
+  return { version: 1, type: 'doc', content };
+}
+
+/**
+ * Parse a single line for inline marks (strong, em, code, link). Returns
+ * an array of ADF text nodes. Markers nest only by left-to-right scan;
+ * unmatched markers are treated as literal text. Designed to be
+ * predictable rather than fully markdown-compliant.
+ *
+ * @param {string} line
+ * @returns {Array}
+ */
+function parseInline(line) {
+  if (!line) return [];
+  const out = [];
+  let buf = '';
+  let i = 0;
+
+  const flush = () => {
+    if (buf) {
+      out.push({ type: 'text', text: buf });
+      buf = '';
+    }
+  };
+
+  while (i < line.length) {
+    const ch = line[i];
+
+    // Inline code: `...`
+    if (ch === '`') {
+      const close = line.indexOf('`', i + 1);
+      if (close > i) {
+        flush();
+        out.push({
+          type: 'text',
+          text: line.slice(i + 1, close),
+          marks: [{ type: 'code' }],
+        });
+        i = close + 1;
+        continue;
+      }
+    }
+
+    // Strong: **...**
+    if (ch === '*' && line[i + 1] === '*') {
+      const close = line.indexOf('**', i + 2);
+      if (close > i + 1) {
+        flush();
+        out.push({
+          type: 'text',
+          text: line.slice(i + 2, close),
+          marks: [{ type: 'strong' }],
+        });
+        i = close + 2;
+        continue;
+      }
+    }
+
+    // Em: *...*  (single asterisk; must not look like the start of **)
+    if (ch === '*' && line[i + 1] !== '*' && line[i + 1] !== ' ' && line[i + 1] !== undefined) {
+      const close = line.indexOf('*', i + 1);
+      if (close > i && line[close + 1] !== '*') {
+        flush();
+        out.push({
+          type: 'text',
+          text: line.slice(i + 1, close),
+          marks: [{ type: 'em' }],
+        });
+        i = close + 1;
+        continue;
+      }
+    }
+
+    // Link: [label](url)
+    if (ch === '[') {
+      const closeBracket = line.indexOf(']', i + 1);
+      if (closeBracket > i && line[closeBracket + 1] === '(') {
+        const closeParen = line.indexOf(')', closeBracket + 2);
+        if (closeParen > closeBracket) {
+          flush();
+          out.push({
+            type: 'text',
+            text: line.slice(i + 1, closeBracket),
+            marks: [{ type: 'link', attrs: { href: line.slice(closeBracket + 2, closeParen) } }],
+          });
+          i = closeParen + 1;
+          continue;
+        }
+      }
+    }
+
+    buf += ch;
+    i++;
+  }
+
+  flush();
+  return out;
+}
+
+// ── ADF → Plain text ─────────────────────────────────────────────────
+
+/**
+ * Extract plain text from an ADF document.
+ * Recursively walks the ADF tree and concatenates text content.
+ *
+ * @param {object} adfDoc  ADF document or node
+ * @returns {string}       Plain text
+ */
+export function adfToText(adfDoc) {
+  if (!adfDoc) return '';
+  return extractText(adfDoc).trim();
+}
+
+/**
+ * Recursively extract text from an ADF node.
+ * @param {object} node  ADF node
+ * @returns {string}
+ */
+function extractText(node) {
+  if (!node) return '';
+
+  // Leaf text node
+  if (node.type === 'text') {
+    return node.text || '';
+  }
+
+  // Hard break
+  if (node.type === 'hardBreak') {
+    return '\n';
+  }
+
+  // Mention
+  if (node.type === 'mention') {
+    return node.attrs?.text || node.attrs?.id || '@unknown';
+  }
+
+  // Inline card (smart link)
+  if (node.type === 'inlineCard') {
+    return node.attrs?.url || '';
+  }
+
+  // No children - nothing to extract
+  if (!node.content || !Array.isArray(node.content)) {
+    return '';
+  }
+
+  const childText = node.content.map(extractText).join('');
+
+  // Block-level nodes get newline separation
+  switch (node.type) {
+    case 'doc':
+      return node.content.map(extractText).join('\n\n');
+    case 'paragraph':
+      return childText;
+    case 'heading':
+      return childText;
+    case 'bulletList':
+    case 'orderedList':
+      return node.content.map((item, i) => {
+        const prefix = node.type === 'orderedList' ? `${i + 1}. ` : '- ';
+        return prefix + extractText(item);
+      }).join('\n');
+    case 'listItem':
+      return childText;
+    case 'codeBlock':
+      return childText;
+    case 'blockquote':
+      return childText;
+    default:
+      return childText;
+  }
+}
+
+// ── ADF → Markdown ───────────────────────────────────────────────────
+
+/**
+ * Convert an ADF document to markdown.
+ * Handles headings, lists, code blocks, blockquotes, and inline marks.
+ *
+ * @param {object} adfDoc  ADF document
+ * @returns {string}       Markdown text
+ */
+export function adfToMarkdown(adfDoc) {
+  if (!adfDoc) return '';
+  return renderNode(adfDoc).trim();
+}
+
+/**
+ * Render an ADF node to markdown.
+ * @param {object} node  ADF node
+ * @returns {string}
+ */
+function renderNode(node) {
+  if (!node) return '';
+
+  // Leaf text node - apply marks
+  if (node.type === 'text') {
+    let text = node.text || '';
+    if (node.marks && Array.isArray(node.marks)) {
+      for (const mark of node.marks) {
+        switch (mark.type) {
+          case 'strong':
+            text = `**${text}**`;
+            break;
+          case 'em':
+            text = `*${text}*`;
+            break;
+          case 'code':
+            text = `\`${text}\``;
+            break;
+          case 'link':
+            text = `[${text}](${mark.attrs?.href || ''})`;
+            break;
+          case 'strike':
+            text = `~~${text}~~`;
+            break;
+        }
+      }
+    }
+    return text;
+  }
+
+  // Hard break
+  if (node.type === 'hardBreak') {
+    return '\n';
+  }
+
+  // Mention
+  if (node.type === 'mention') {
+    return node.attrs?.text || `@${node.attrs?.id || 'unknown'}`;
+  }
+
+  // Inline card
+  if (node.type === 'inlineCard') {
+    return node.attrs?.url || '';
+  }
+
+  // No children
+  if (!node.content || !Array.isArray(node.content)) {
+    return '';
+  }
+
+  switch (node.type) {
+    case 'doc':
+      return node.content.map(renderNode).join('\n\n');
+
+    case 'paragraph':
+      return node.content.map(renderNode).join('');
+
+    case 'heading': {
+      const level = node.attrs?.level || 1;
+      const prefix = '#'.repeat(level);
+      const text = node.content.map(renderNode).join('');
+      return `${prefix} ${text}`;
+    }
+
+    case 'bulletList':
+      return node.content.map((item) => {
+        const text = renderNode(item);
+        return `- ${text}`;
+      }).join('\n');
+
+    case 'orderedList':
+      return node.content.map((item, i) => {
+        const text = renderNode(item);
+        return `${i + 1}. ${text}`;
+      }).join('\n');
+
+    case 'listItem':
+      // List items contain paragraphs; render inline
+      return node.content.map(renderNode).join('\n');
+
+    case 'codeBlock': {
+      const lang = node.attrs?.language || '';
+      const code = node.content.map(renderNode).join('');
+      return `\`\`\`${lang}\n${code}\n\`\`\``;
+    }
+
+    case 'blockquote': {
+      const text = node.content.map(renderNode).join('\n');
+      return text.split('\n').map((line) => `> ${line}`).join('\n');
+    }
+
+    default:
+      return node.content.map(renderNode).join('');
+  }
+}

package/dist/engineering-pa-core-extensions-atlassian/src/jira/bug-fields.mjs

@@ -0,0 +1,294 @@
+// bug-fields.mjs - First-class support for creating Bugs with the common required-field set (severity/steps/repro-rate).
+//
+// Project AI (Jira) enforces four custom fields on Bug create; the API
+// 400s with "Field 'customfield_XXXXX' cannot be set" when they are
+// missing, and rejects wrongly-shaped select payloads. This helper:
+//
+//   1. Discovers the required fields and their live allowed values from
+//      the createmeta endpoint (`/rest/api/3/issue/createmeta/<PROJECT>
+//      /issuetypes/<ISSUE_TYPE_ID>`). No hard-coded field ids or option
+//      lists - the API is truth.
+//   2. Exposes semantic flags - `--env-impacted`, `--expected`,
+//      `--actual`, `--steps` - that map onto those customfields with the
+//      correct payload shapes (multiselect = array of options; textarea
+//      = ADF doc).
+//   3. Validates every `--env-impacted` value against the live allowed
+//      list (case-insensitive), echoing the exact API casing on match
+//      and printing the allowed set on miss.
+//   4. Runs a preflight check that returns the missing required fields
+//      as an actionable error - so the CLI can fail fast with the exact
+//      flags to add, instead of relaying Jira's opaque 400.
+//
+// The module holds no state across CLI invocations. A per-process cache
+// on the createmeta response keeps the field-list to a single API call
+// per `jira create --bug` run.
+
+import { JiraError } from './client.mjs';
+import { textToAdf } from './adf.mjs';
+
+// Semantic flag → the field's canonical Jira display name in createmeta.
+// Resolution is by name (not id) so a field-id shuffle on Jira's side
+// never silently breaks the CLI. Ids come out of createmeta at runtime.
+export const BUG_FIELD_NAMES = Object.freeze({
+  envImpacted: 'Environment Impacted',
+  expected: 'Expected Behaviour',
+  actual: 'Actual Behaviour',
+  steps: 'Steps to Reproduce Issue',
+});
+
+// Human labels for the semantic flags - used in error messages.
+export const BUG_FLAG_LABELS = Object.freeze({
+  envImpacted: '--env-impacted',
+  expected: '--expected',
+  actual: '--actual',
+  steps: '--steps',
+});
+
+// Per-process cache: `${projectKey}:${issueTypeName}` → resolved meta.
+const metaCache = new Map();
+
+/**
+ * Fetch the createmeta for a given project + issue type name (e.g.
+ * `AI` / `Bug`) and index it into a semantic shape the create command
+ * can consume. Returns:
+ *
+ *   {
+ *     issueTypeId: '10102',
+ *     requiredFields: [                         // every required field
+ *       { id, name, schema, required, allowedValues, semantic|null }
+ *     ],
+ *     semantic: {                               // by semantic key
+ *       envImpacted: { id, name, allowedValues: [...] } | null,
+ *       expected:    { id, name } | null,
+ *       actual:      { id, name } | null,
+ *       steps:       { id, name } | null,
+ *     },
+ *   }
+ *
+ * Throws JiraError(2) if the issue type does not exist for the project.
+ *
+ * @param {object} client
+ * @param {string} projectKey
+ * @param {string} issueTypeName
+ * @returns {Promise<object>}
+ */
+export async function fetchBugCreateMeta(client, projectKey, issueTypeName = 'Bug') {
+  const cacheKey = `${projectKey.toUpperCase()}:${issueTypeName.toLowerCase()}`;
+  if (metaCache.has(cacheKey)) return metaCache.get(cacheKey);
+
+  // 1) Resolve the issue-type id via the createmeta issuetypes endpoint.
+  //    The v3 shape uses `values`; older/legacy responses use `issueTypes`
+  //    or return the bare array. Handle all three defensively.
+  const { data: typesResp } = await client.get(
+    `/rest/api/3/issue/createmeta/${encodeURIComponent(projectKey)}/issuetypes?maxResults=200`
+  );
+  const types = extractList(typesResp, ['values', 'issueTypes']);
+  const wanted = String(issueTypeName).toLowerCase();
+  const type = types.find((t) => t && t.name && String(t.name).toLowerCase() === wanted);
+  if (!type || !type.id) {
+    const listed = types.map((t) => t?.name).filter(Boolean).join(', ') || '(none)';
+    throw new JiraError(
+      `Issue type "${issueTypeName}" not found on project ${projectKey}. Available: ${listed}`,
+      2,
+    );
+  }
+
+  // 2) Fetch the field list for that issue type.
+  const { data: fieldsResp } = await client.get(
+    `/rest/api/3/issue/createmeta/${encodeURIComponent(projectKey)}/issuetypes/${encodeURIComponent(type.id)}?maxResults=200`
+  );
+  const fields = extractList(fieldsResp, ['values', 'fields']);
+
+  // 3) Index required fields + pick out our four semantic ones by name.
+  const requiredFields = fields
+    .filter((f) => f && f.required)
+    .map((f) => normaliseField(f));
+
+  const semantic = {
+    envImpacted: findByName(fields, BUG_FIELD_NAMES.envImpacted),
+    expected: findByName(fields, BUG_FIELD_NAMES.expected),
+    actual: findByName(fields, BUG_FIELD_NAMES.actual),
+    steps: findByName(fields, BUG_FIELD_NAMES.steps),
+  };
+
+  const meta = { issueTypeId: type.id, requiredFields, semantic };
+  metaCache.set(cacheKey, meta);
+  return meta;
+}
+
+/**
+ * Given parsed CLI args and the createmeta, build the `fields` fragment
+ * the four semantic flags contribute (envImpacted / expected / actual /
+ * steps). Also returns a `preflight` array of required-field names that
+ * are STILL missing after the fragment is applied, so the caller can
+ * fail fast with a helpful error instead of relaying a Jira 400.
+ *
+ * A required field is considered satisfied when EITHER a semantic flag
+ * supplied a value, OR an existing `--field` / `--field-adf` pair
+ * already set the same customfield id.
+ *
+ * @param {object} args              parseArgs output
+ * @param {object} meta              fetchBugCreateMeta() output
+ * @param {object} existingFields    fields already collected (via --field etc.)
+ * @returns {{ fields: object, preflight: string[] }}
+ */
+export function buildBugFieldsPatch(args, meta, existingFields = {}) {
+  const fields = {};
+
+  // --env-impacted (repeatable + comma-separated) → multiselect array.
+  const envValues = flattenListArg(args['env-impacted']);
+  if (envValues.length > 0) {
+    if (!meta.semantic.envImpacted) {
+      throw new JiraError(
+        `Cannot map --env-impacted: field "${BUG_FIELD_NAMES.envImpacted}" not found on project's Bug createmeta.`,
+        2,
+      );
+    }
+    const { id, allowedValues } = meta.semantic.envImpacted;
+    const allowedByLower = new Map(
+      (allowedValues || []).map((v) => [String(v).toLowerCase(), v]),
+    );
+    if (allowedByLower.size === 0) {
+      throw new JiraError(
+        `--env-impacted cannot be validated: createmeta returned no allowed values for "${BUG_FIELD_NAMES.envImpacted}".`,
+        2,
+      );
+    }
+    const resolved = [];
+    for (const raw of envValues) {
+      const match = allowedByLower.get(raw.toLowerCase());
+      if (!match) {
+        const allowedList = Array.from(allowedByLower.values()).join(', ');
+        throw new JiraError(
+          `--env-impacted "${raw}" is not an allowed value. Allowed (from createmeta): ${allowedList}`,
+          1,
+        );
+      }
+      // Multiselect is an ARRAY of option objects. Duplicates de-duped.
+      if (!resolved.some((r) => r.value === match)) {
+        resolved.push({ value: match });
+      }
+    }
+    fields[id] = resolved;
+  }
+
+  // Textarea customfields → ADF. Semantic flags simply wrap plain text.
+  const textareaFlags = [
+    ['expected', args.expected],
+    ['actual', args.actual],
+    ['steps', args.steps],
+  ];
+  for (const [key, raw] of textareaFlags) {
+    if (raw == null || raw === '' || raw === false) continue;
+    const semanticField = meta.semantic[key];
+    if (!semanticField) {
+      throw new JiraError(
+        `Cannot map ${BUG_FLAG_LABELS[key]}: field "${BUG_FIELD_NAMES[key]}" not found on project's Bug createmeta.`,
+        2,
+      );
+    }
+    fields[semanticField.id] = textToAdf(String(raw));
+  }
+
+  // Preflight: any required field that neither the fragment nor the
+  // caller's existingFields cover. Skip fields we cannot possibly ask
+  // for from a CLI (project / issuetype / summary / reporter are set
+  // by the create pipeline itself).
+  const alwaysProvided = new Set(['project', 'issuetype', 'summary', 'reporter']);
+  const covered = new Set([...Object.keys(existingFields), ...Object.keys(fields)]);
+  const preflight = [];
+  for (const rf of meta.requiredFields) {
+    if (alwaysProvided.has(rf.id)) continue;
+    if (covered.has(rf.id)) continue;
+    preflight.push(rf);
+  }
+
+  return { fields, preflight };
+}
+
+/**
+ * Render the preflight list as an operator-facing error message that
+ * names each missing required field, its id, and - where we know one -
+ * the semantic flag that would supply it. Missing fields with no
+ * dedicated flag are pointed at `--field`/`--field-adf` as the fallback.
+ *
+ * @param {Array} preflight  list of normalised required-field objects
+ * @returns {string}
+ */
+export function formatBugPreflightError(preflight) {
+  const nameToFlag = new Map();
+  for (const [key, name] of Object.entries(BUG_FIELD_NAMES)) {
+    nameToFlag.set(name.toLowerCase(), BUG_FLAG_LABELS[key]);
+  }
+  const lines = ['Cannot create Bug - required fields missing:'];
+  for (const rf of preflight) {
+    const flag = nameToFlag.get(String(rf.name).toLowerCase());
+    if (flag) {
+      lines.push(`  - ${rf.name} (${rf.id}) - pass ${flag} VALUE`);
+    } else {
+      const shape = describeFieldShape(rf);
+      lines.push(`  - ${rf.name} (${rf.id}) - pass --field '${rf.id}=${shape}'`);
+    }
+  }
+  return lines.join('\n');
+}
+
+// Test-only cache reset.
+export function _resetBugMetaCacheForTests() {
+  metaCache.clear();
+}
+
+// ── internals ────────────────────────────────────────────────────────
+
+function extractList(resp, keys) {
+  if (Array.isArray(resp)) return resp;
+  if (!resp || typeof resp !== 'object') return [];
+  for (const k of keys) {
+    if (Array.isArray(resp[k])) return resp[k];
+  }
+  return [];
+}
+
+function normaliseField(f) {
+  const id = f.fieldId || f.key || f.id;
+  const allowedValues = Array.isArray(f.allowedValues)
+    ? f.allowedValues.map((v) => v.value || v.name || v.id).filter(Boolean)
+    : null;
+  return {
+    id,
+    name: f.name,
+    schema: f.schema || null,
+    required: !!f.required,
+    allowedValues,
+  };
+}
+
+function findByName(fields, name) {
+  const wanted = String(name).toLowerCase();
+  const found = fields.find(
+    (f) => f && f.name && String(f.name).toLowerCase() === wanted,
+  );
+  return found ? normaliseField(found) : null;
+}
+
+/** Coerce a repeatable+comma-separated flag to an array of trimmed strings. */
+function flattenListArg(v) {
+  if (v == null || v === false) return [];
+  const raws = Array.isArray(v) ? v : [v];
+  const out = [];
+  for (const r of raws) {
+    for (const part of String(r).split(',')) {
+      const t = part.trim();
+      if (t) out.push(t);
+    }
+  }
+  return out;
+}
+
+function describeFieldShape(rf) {
+  const t = rf.schema && rf.schema.type;
+  if (t === 'array') return '[{"value":"…"}]';
+  if (t === 'option') return '{"value":"…"}';
+  if (t === 'user') return '{"accountId":"…"}';
+  return '…';
+}