@geraldmaron/construct 1.4.1 → 1.5.0

package/lib/providers/contract/adapters/confluence/manifest.json

@@ -0,0 +1,17 @@
+{
+  "id": "confluence-write",
+  "version": "1.0.0",
+  "kind": "data-source",
+  "capabilities": ["write", "search"],
+  "secretEnvKeys": ["CONFLUENCE_URL", "CONFLUENCE_EMAIL", "CONFLUENCE_TOKEN"],
+  "operations": ["write:page", "write:page-update", "search"],
+  "securityClassification": "trusted",
+  "owner": "construct-core",
+  "compatVersion": 1,
+  "installSource": "builtin",
+  "exposure": "envelope-only",
+  "envelopeModule": "lib/writes/envelope.mjs",
+  "adapterModule": "lib/providers/contract/adapters/confluence/governed-write.mjs",
+  "transportModule": "lib/providers/contract/adapters/confluence/transport.mjs",
+  "notes": "Colocated write-capability manifest for LMCP-J4. Follows the lib/extensions/manifests/*.manifest.json schema (see atlassian-confluence.manifest.json, which declares read/search only). Wiring this into the shared lib/extensions/manifests/ discovery directory is out of scope for this bead; capabilities here are reachable only via writeWithEnvelope(), never a direct provider-registry lookup."
+}

package/lib/providers/contract/adapters/confluence/transport.mjs

@@ -0,0 +1,135 @@
+/**
+ * lib/providers/contract/adapters/confluence/transport.mjs — real Confluence
+ * Cloud REST v2 transport for the governed write adapter.
+ *
+ * Implements the `confluenceTransport` shape governed-write.mjs depends on:
+ * `searchPagesByTitle`, `getPage`, `createPage`, `updatePage`,
+ * `createFooterComment`. Kept separate from governed-write.mjs so tests can
+ * inject a fake transport (tests/fakes/fake-confluence-transport.mjs)
+ * without any network dependency, and separate from the read-oriented
+ * adapter in ./index.mjs so this write path never shares mutable state with
+ * the read path.
+ *
+ * Auth: API token via CONFLUENCE_URL + CONFLUENCE_EMAIL + CONFLUENCE_TOKEN
+ * env vars, or passed directly via config.
+ */
+
+import { AuthError, RateLimitError } from '../../errors.mjs';
+import { guardedFetch } from '../../../../net-guard.mjs';
+
+export function createConfluenceTransport(config = {}) {
+  const baseUrl = (config.baseUrl ?? process.env.CONFLUENCE_URL ?? '').replace(/\/$/, '');
+  const email = config.email ?? process.env.CONFLUENCE_EMAIL;
+  const token = config.token ?? process.env.CONFLUENCE_TOKEN;
+
+  if (!baseUrl || !email || !token) {
+    throw new AuthError(
+      'Confluence transport requires CONFLUENCE_URL, CONFLUENCE_EMAIL, and CONFLUENCE_TOKEN (or config.baseUrl/email/token)',
+      { provider: 'confluence' },
+    );
+  }
+
+  const auth = `Basic ${Buffer.from(`${email}:${token}`).toString('base64')}`;
+
+  // Egress runs through the N7 guard (SSRF/rebinding); a private-address
+  // self-hosted instance is an explicit, audited opt-in, never the default.
+  const allowPrivate = config.allowPrivateEgress ?? process.env.CONSTRUCT_NET_ALLOW_PRIVATE_EGRESS === '1';
+
+  async function request(path, { method = 'GET', body } = {}) {
+    const res = await guardedFetch(`${baseUrl}${path}`, {
+      method,
+      headers: {
+        Authorization: auth,
+        'Content-Type': 'application/json',
+        Accept: 'application/json',
+      },
+      body: body ? JSON.stringify(body) : undefined,
+    }, { allowPrivate });
+
+    if (res.status === 429) {
+      const retryAfter = parseInt(res.headers.get('Retry-After') ?? '60', 10);
+      throw new RateLimitError('Confluence rate limit hit', { provider: 'confluence', retryAfter });
+    }
+    if (!res.ok) {
+      const text = await res.text().catch(() => '');
+      const err = new Error(`Confluence API ${method} ${path} failed: ${res.status} ${text.slice(0, 300)}`);
+      err.status = res.status;
+      throw err;
+    }
+    if (res.status === 204) return null;
+    return res.json();
+  }
+
+  return {
+    async searchPagesByTitle(spaceId, title) {
+      const params = new URLSearchParams({ title, 'space-id': spaceId, limit: '10' });
+      const data = await request(`/wiki/api/v2/pages?${params.toString()}`);
+      return (data.results ?? []).map((p) => ({
+        id: p.id,
+        title: p.title,
+        spaceId: p.spaceId,
+        version: p.version?.number ?? null,
+        url: `${baseUrl}${p._links?.webui ?? ''}`,
+      }));
+    },
+
+    async getPage(pageId) {
+      const data = await request(`/wiki/api/v2/pages/${pageId}?body-format=storage`);
+      return {
+        id: data.id,
+        title: data.title,
+        spaceId: data.spaceId,
+        version: data.version?.number ?? null,
+        body: data.body?.storage?.value ?? '',
+        url: `${baseUrl}${data._links?.webui ?? ''}`,
+      };
+    },
+
+    async createPage({ spaceId, title, body, parentId }) {
+      const reqBody = {
+        spaceId,
+        status: 'current',
+        title,
+        parentId: parentId ?? undefined,
+        body: { representation: 'storage', value: body },
+      };
+      const data = await request('/wiki/api/v2/pages', { method: 'POST', body: reqBody });
+      return {
+        id: data.id,
+        title: data.title,
+        version: data.version?.number ?? 1,
+        url: `${baseUrl}${data._links?.webui ?? ''}`,
+      };
+    },
+
+    async updatePage({ pageId, title, body, version }) {
+      const reqBody = {
+        id: pageId,
+        status: 'current',
+        title,
+        version: { number: version },
+        body: { representation: 'storage', value: body },
+      };
+      const data = await request(`/wiki/api/v2/pages/${pageId}`, { method: 'PUT', body: reqBody });
+      return {
+        id: data.id,
+        title: data.title,
+        version: data.version?.number ?? version,
+        url: `${baseUrl}${data._links?.webui ?? ''}`,
+      };
+    },
+
+    async createFooterComment(pageId, body) {
+      const data = await request('/wiki/api/v2/footer-comments', {
+        method: 'POST',
+        body: { pageId, body: { representation: 'storage', value: body } },
+      });
+      return {
+        id: data.id,
+        url: `${baseUrl}${data._links?.webui ?? ''}`,
+      };
+    },
+  };
+}
+
+export default createConfluenceTransport;

package/lib/providers/contract/adapters/github/governed-write.mjs

@@ -0,0 +1,121 @@
+/**
+ * lib/providers/contract/adapters/github/governed-write.mjs — envelope-shaped
+ * GitHub write adapter.
+ *
+ * Wraps the CLI-backed github adapter (./index.mjs) in the provider shape
+ * lib/writes/envelope.mjs expects: write(config, payload), meta.id, search().
+ * Adds two behaviors the raw CLI adapter cannot provide on its own:
+ *
+ *   - Cross-run duplicate detection: every created issue carries a hidden
+ *     idempotency marker (HTML comment) in its body. Before creating, this
+ *     wrapper searches GitHub itself for an issue carrying that marker, so
+ *     dedup survives across process restarts and machines, not just the
+ *     local sent-log.
+ *   - Secondary-rate-limit backoff: GitHub content-creation endpoints return
+ *     403 with a "secondary rate limit" message (no clean HTTP Retry-After
+ *     on the gh CLI transport). This wrapper retries a bounded number of
+ *     times honoring the parsed retry-after, then surfaces the error rather
+ *     than spinning silently — the envelope's own generic retry/backoff is
+ *     bypassed here because it is not retry-after aware.
+ *
+ * Only `type: 'issue'` writes get marker + dedup treatment; other write
+ * types pass straight through to the underlying adapter.
+ */
+
+import { RateLimitError } from '../../errors.mjs';
+
+const MARKER_PREFIX = 'construct:idempotency:';
+
+function markerFor(key) {
+  return `<!-- ${MARKER_PREFIX}${key} -->`;
+}
+
+function extractMarkerKey(text) {
+  const match = new RegExp(`${MARKER_PREFIX}([a-zA-Z0-9_-]+)`).exec(text || '');
+  return match ? match[1] : null;
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * @param {object} opts
+ * @param {object} opts.ghAdapter - underlying CLI adapter (default export of ./index.mjs)
+ * @param {number} [opts.maxRateLimitRetries] - bounded retry-after retries before surfacing (default 2)
+ * @param {function} [opts.sleepFn] - injectable sleep for tests
+ */
+export function createGovernedGithubProvider({ ghAdapter, maxRateLimitRetries = 2, sleepFn = sleep } = {}) {
+  if (!ghAdapter) throw new Error('createGovernedGithubProvider: ghAdapter is required');
+
+  async function findExistingByMarker(config, { title, markerKey }) {
+    const results = await ghAdapter.search(`${title} in:title`, { scope: 'issues' });
+    for (const candidate of results || []) {
+      const body = candidate.body ?? candidate.textMatches?.map((m) => m.fragment).join(' ') ?? '';
+      const haystack = `${candidate.title ?? ''} ${body}`;
+      if (extractMarkerKey(haystack) === markerKey || candidate.title === title) {
+        return candidate;
+      }
+    }
+    return null;
+  }
+
+  async function writeIssueWithRetry(config, payload, markerKey) {
+    const bodyWithMarker = `${payload.body ?? ''}\n\n${markerFor(markerKey)}`;
+    let attempt = 0;
+    for (;;) {
+      try {
+        return await ghAdapter.write({
+          type: 'issue',
+          title: payload.title,
+          body: bodyWithMarker,
+          labels: payload.labels,
+        });
+      } catch (err) {
+        const isSecondaryRateLimit = err instanceof RateLimitError || err.status === 403;
+        if (!isSecondaryRateLimit || attempt >= maxRateLimitRetries) {
+          throw err;
+        }
+        attempt += 1;
+        const retryAfterMs = (err.retryAfter ?? 60) * 1000;
+        await sleepFn(retryAfterMs);
+      }
+    }
+  }
+
+  return {
+    meta: {
+      id: 'github',
+      displayName: 'GitHub (governed)',
+      capabilities: ['write', 'search'],
+      description: 'Envelope-routed GitHub writes with marker-based dedup and retry-after backoff.',
+    },
+
+    async write(config, payload) {
+      if (payload?.type !== 'issue') {
+        return ghAdapter.write(payload);
+      }
+      if (!payload.title) throw new Error('github governed write: payload.title is required for type "issue"');
+
+      const markerKey = payload.idempotencyKey || payload.title;
+      const existing = await findExistingByMarker(config, { title: payload.title, markerKey });
+      if (existing) {
+        return {
+          type: 'issue-duplicate',
+          id: existing.number ?? existing.id,
+          number: existing.number,
+          url: existing.url,
+          linkback: existing.url,
+        };
+      }
+
+      return writeIssueWithRetry(config, payload, markerKey);
+    },
+
+    async search(config, query) {
+      return ghAdapter.search(query, { scope: 'issues' });
+    },
+  };
+}
+
+export default createGovernedGithubProvider;

package/lib/providers/contract/adapters/github/index.mjs

@@ -27,7 +27,26 @@
  */
 
 import { spawnSync } from 'node:child_process';
-import { AuthError, NotFoundError } from '../../errors.mjs';
+import { AuthError, NotFoundError, RateLimitError } from '../../errors.mjs';
+
+// gh CLI has no HTTP header access; secondary rate limits surface as a 403
+// with "secondary rate limit" text in stderr and sometimes a suggested wait
+// in seconds. Default to GitHub's documented minimum backoff when absent.
+const SECONDARY_RATE_LIMIT_DEFAULT_RETRY_AFTER = 60;
+
+function parseRetryAfterSeconds(stderr) {
+  const match = /retry.{0,10}?(\d+)\s*second/i.exec(stderr || '');
+  return match ? parseInt(match[1], 10) : SECONDARY_RATE_LIMIT_DEFAULT_RETRY_AFTER;
+}
+
+function throwIfRateLimited(stderr) {
+  if (/secondary rate limit|403/i.test(stderr || '') && /rate limit/i.test(stderr || '')) {
+    throw new RateLimitError(stderr.trim(), {
+      provider: 'github',
+      retryAfter: parseRetryAfterSeconds(stderr),
+    });
+  }
+}
 
 function gh(args, { json = true, input } = {}) {
   const fullArgs = json ? [...args, '--json', ...ghJsonFields(args)] : args;
@@ -115,6 +134,10 @@ export default {
       const args = ['issue', 'create', ...repoFlag, '--title', item.title, '--body', item.body ?? ''];
       if (item.labels?.length) args.push('--label', item.labels.join(','));
       const out = spawnSync('gh', args, { encoding: 'utf8', env: process.env });
+      if (out.status !== 0) {
+        throwIfRateLimited(out.stderr);
+        throw new Error(`gh issue create failed: ${out.stderr?.trim() || `exit ${out.status}`}`);
+      }
       return { type: 'issue-created', url: out.stdout.trim() };
     }
 
@@ -127,21 +150,33 @@ export default {
       ];
       if (item.draft) args.push('--draft');
       const out = spawnSync('gh', args, { encoding: 'utf8', env: process.env });
+      if (out.status !== 0) {
+        throwIfRateLimited(out.stderr);
+        throw new Error(`gh pr create failed: ${out.stderr?.trim() || `exit ${out.status}`}`);
+      }
       return { type: 'pr-created', url: out.stdout.trim() };
     }
 
     if (item.type === 'comment') {
       const args = ['issue', 'comment', String(item.issue_number), ...repoFlag, '--body', item.body];
-      spawnSync('gh', args, { encoding: 'utf8', env: process.env });
+      const out = spawnSync('gh', args, { encoding: 'utf8', env: process.env });
+      if (out.status !== 0) {
+        throwIfRateLimited(out.stderr);
+        throw new Error(`gh issue comment failed: ${out.stderr?.trim() || `exit ${out.status}`}`);
+      }
       return { type: 'comment-created', issue_number: item.issue_number };
     }
 
     if (item.type === 'pr-merge') {
       const method = item.merge_method ?? 'squash';
-      spawnSync('gh', ['pr', 'merge', String(item.number), ...repoFlag, `--${method}`], {
+      const out = spawnSync('gh', ['pr', 'merge', String(item.number), ...repoFlag, `--${method}`], {
         encoding: 'utf8',
         env: process.env,
       });
+      if (out.status !== 0) {
+        throwIfRateLimited(out.stderr);
+        throw new Error(`gh pr merge failed: ${out.stderr?.trim() || `exit ${out.status}`}`);
+      }
       return { type: 'pr-merged', number: item.number };
     }
 

package/lib/providers/contract/adapters/jira/adf.mjs

@@ -0,0 +1,151 @@
+/**
+ * lib/providers/contract/adapters/jira/adf.mjs — Atlassian Document Format
+ * (ADF) construction for Jira Cloud write fields.
+ *
+ * Jira Cloud REST API v3 requires `description`, `comment.body`, and any
+ * multiline custom field of type `doc` to be submitted as an ADF document
+ * rather than plain text. Covers the minimal ADF subset issue/comment write
+ * ops need: paragraphs split on blank lines, single-level bullet lists for
+ * lines starting with "- " or "* ", and inline text nodes. Full markdown
+ * fidelity (headings, tables, nested lists) is out of scope.
+ *
+ * `renderAdfPreview(adf)` renders an ADF document back to a readable plain
+ * string for dry-run display, so a human reviewing a dry-run payload sees
+ * text rather than a raw ADF tree.
+ */
+
+const ADF_VERSION = 1;
+
+function textNode(text) {
+  return { type: 'text', text: String(text) };
+}
+
+function paragraphNode(text) {
+  return { type: 'paragraph', content: text ? [textNode(text)] : [] };
+}
+
+function bulletListNode(items) {
+  return {
+    type: 'bulletList',
+    content: items.map((item) => ({
+      type: 'listItem',
+      content: [paragraphNode(item)],
+    })),
+  };
+}
+
+// Blank-line-separated blocks become paragraphs; a contiguous run of lines
+// each starting with "- " or "* " becomes a single bullet list. This covers
+// the shapes specialists actually produce (short prose + a checklist) without
+// pretending to be a markdown parser.
+
+function blocksFromText(text) {
+  const lines = String(text ?? '').split('\n');
+  const blocks = [];
+  let paragraphLines = [];
+  let listItems = [];
+
+  function flushParagraph() {
+    if (paragraphLines.length) {
+      blocks.push(paragraphNode(paragraphLines.join(' ').trim()));
+      paragraphLines = [];
+    }
+  }
+  function flushList() {
+    if (listItems.length) {
+      blocks.push(bulletListNode(listItems));
+      listItems = [];
+    }
+  }
+
+  for (const rawLine of lines) {
+    const line = rawLine.trim();
+    const bulletMatch = /^[-*]\s+(.*)$/.exec(line);
+    if (bulletMatch) {
+      flushParagraph();
+      listItems.push(bulletMatch[1]);
+    } else if (line === '') {
+      flushParagraph();
+      flushList();
+    } else {
+      flushList();
+      paragraphLines.push(line);
+    }
+  }
+  flushParagraph();
+  flushList();
+
+  return blocks.length ? blocks : [paragraphNode('')];
+}
+
+/**
+ * Build a full ADF document from a plain-text (or already-ADF) input.
+ * Passing an object that already looks like an ADF doc (`{ type: 'doc' }`)
+ * returns it unchanged so callers can pass through pre-built documents.
+ *
+ * @param {string|object} content
+ * @returns {object} ADF document
+ */
+export function buildAdfDocument(content) {
+  if (content && typeof content === 'object' && content.type === 'doc') {
+    return content;
+  }
+  return {
+    type: 'doc',
+    version: ADF_VERSION,
+    content: blocksFromText(content),
+  };
+}
+
+/**
+ * Render an ADF document (or plain text) back to a flat human-readable
+ * string, for dry-run display. Not a full ADF renderer — only understands
+ * the node types buildAdfDocument produces plus a defensive fallback for
+ * unknown node types (renders as `[<type>]`).
+ *
+ * @param {object|string} adf
+ * @returns {string}
+ */
+export function renderAdfPreview(adf) {
+  if (typeof adf === 'string') return adf;
+  if (!adf || typeof adf !== 'object') return '';
+
+  function renderNode(node) {
+    if (!node || typeof node !== 'object') return '';
+    switch (node.type) {
+      case 'doc':
+        return (node.content ?? []).map(renderNode).join('\n');
+      case 'paragraph':
+        return (node.content ?? []).map(renderNode).join('');
+      case 'text':
+        return node.text ?? '';
+      case 'bulletList':
+        return (node.content ?? []).map((item) => `- ${renderNode(item)}`).join('\n');
+      case 'listItem':
+        return (node.content ?? []).map(renderNode).join('').trim();
+      default:
+        return `[${node.type ?? 'unknown'}]`;
+    }
+  }
+
+  return renderNode(adf);
+}
+
+/**
+ * True when the given value is a well-formed ADF document envelope
+ * (`{ type: 'doc', version, content: [...] }`). Distinguishes a doc node
+ * from a bare string, for rejecting fields the API requires as ADF but
+ * were submitted as plain text.
+ *
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+export function isAdfDocument(value) {
+  return (
+    !!value &&
+    typeof value === 'object' &&
+    value.type === 'doc' &&
+    typeof value.version === 'number' &&
+    Array.isArray(value.content)
+  );
+}

package/lib/providers/contract/adapters/jira/createmeta.mjs

@@ -0,0 +1,143 @@
+/**
+ * lib/providers/contract/adapters/jira/createmeta.mjs — Jira Cloud createmeta
+ * validation for write payloads.
+ *
+ * Jira Cloud's `GET /rest/api/3/issue/createmeta` (expanded with
+ * `projects.issuetypes.fields`) reports, per project + issue type, which
+ * fields exist, which are required, and which accept a `doc` (ADF) shape
+ * versus a plain scalar. `validateAgainstCreatemeta` runs before any issue
+ * create/comment submit so a bad project key, unknown issue type, missing
+ * required field, or wrong ADF/plain-text shape surfaces as a client-side
+ * error with an actionable message instead of a raw 400 from Jira after the
+ * request has already gone out.
+ *
+ * Providers inject a `fetchCreatemeta(projectKey, issueTypeName)` function
+ * so this module has no transport dependency and the fake-jira test double
+ * can simulate arbitrary createmeta shapes and failure modes.
+ */
+
+import { isAdfDocument } from './adf.mjs';
+
+/**
+ * Normalize a raw createmeta API response into a lookup map of
+ * `{ [fieldKey]: { required, schema } }` for the requested issue type.
+ *
+ * @param {object} raw - createmeta response body
+ * @param {string} projectKey
+ * @param {string} issueTypeName
+ * @returns {{ issueTypeId: string|null, fields: Record<string, {required: boolean, schema: object}> } | null}
+ */
+export function extractIssueTypeMeta(raw, projectKey, issueTypeName) {
+  const project = (raw?.projects ?? []).find((p) => p.key === projectKey);
+  if (!project) return null;
+
+  const issueType = (project.issuetypes ?? []).find(
+    (it) => it.name?.toLowerCase() === issueTypeName?.toLowerCase(),
+  );
+  if (!issueType) return null;
+
+  const fields = {};
+  for (const [key, def] of Object.entries(issueType.fields ?? {})) {
+    fields[key] = { required: !!def.required, schema: def.schema ?? {} };
+  }
+  return { issueTypeId: issueType.id ?? null, fields };
+}
+
+/**
+ * Validate an issue-create payload against createmeta for its project +
+ * issue type before submit. Returns a structured result rather than
+ * throwing, so callers can map failures to actionable messages themselves.
+ *
+ * @param {object} opts
+ * @param {function(string, string): Promise<object>} opts.fetchCreatemeta
+ * @param {string} opts.projectKey
+ * @param {string} opts.issueTypeName
+ * @param {object} opts.fieldValues - candidate field values keyed by createmeta field key
+ *   (e.g. { summary, description, labels }). `description` is checked for
+ *   ADF shape when createmeta reports its schema type as `doc`.
+ * @returns {Promise<{ ok: true } | { ok: false, reason: string, errors: string[] }>}
+ */
+export async function validateAgainstCreatemeta({ fetchCreatemeta, projectKey, issueTypeName, fieldValues }) {
+  let raw;
+  try {
+    raw = await fetchCreatemeta(projectKey, issueTypeName);
+  } catch (err) {
+    return {
+      ok: false,
+      reason: 'createmeta-fetch-failed',
+      errors: [mapCreatemetaTransportError(err, { projectKey })],
+    };
+  }
+
+  const meta = extractIssueTypeMeta(raw, projectKey, issueTypeName);
+  if (!meta) {
+    const knownProjects = (raw?.projects ?? []).map((p) => p.key);
+    if (!knownProjects.includes(projectKey)) {
+      return {
+        ok: false,
+        reason: 'unknown-project',
+        errors: [
+          `Project "${projectKey}" was not found or you lack the Browse Projects / Create Issues permission for it.` +
+          (knownProjects.length ? ` Accessible projects: ${knownProjects.join(', ')}.` : ''),
+        ],
+      };
+    }
+    return {
+      ok: false,
+      reason: 'unknown-issue-type',
+      errors: [`Issue type "${issueTypeName}" is not available in project "${projectKey}".`],
+    };
+  }
+
+  const errors = [];
+
+  for (const [fieldKey, def] of Object.entries(meta.fields)) {
+    if (!def.required) continue;
+    const present = fieldValues[fieldKey] !== undefined && fieldValues[fieldKey] !== null && fieldValues[fieldKey] !== '';
+    if (!present) {
+      errors.push(`Field "${fieldKey}" is required by project "${projectKey}" / issue type "${issueTypeName}" but was not provided.`);
+    }
+  }
+
+  for (const [fieldKey, value] of Object.entries(fieldValues)) {
+    const def = meta.fields[fieldKey];
+    if (!def) continue;
+    if (def.schema?.type === 'doc' && value !== undefined && value !== null && !isAdfDocument(value)) {
+      errors.push(`Field "${fieldKey}" requires an Atlassian Document Format (ADF) body, but a plain value was submitted.`);
+    }
+  }
+
+  if (errors.length) {
+    return { ok: false, reason: 'field-validation-failed', errors };
+  }
+
+  return { ok: true, issueTypeId: meta.issueTypeId };
+}
+
+/**
+ * Map a createmeta transport failure (401/403/404/5xx) to an actionable
+ * message. Jira Cloud returns 404 for both "project does not exist" and
+ * "no permission to view project" — the same ambiguity the create-issue
+ * endpoint itself has — so the message names both possibilities rather
+ * than asserting one.
+ *
+ * @param {Error & {status?: number}} err
+ * @param {{ projectKey: string }} ctx
+ * @returns {string}
+ */
+export function mapCreatemetaTransportError(err, { projectKey }) {
+  const status = err?.status;
+  if (status === 401) {
+    return 'Jira authentication failed while fetching createmeta. Check JIRA_EMAIL / JIRA_TOKEN.';
+  }
+  if (status === 403) {
+    return `Forbidden: the authenticated account lacks permission to create issues in project "${projectKey}".`;
+  }
+  if (status === 404) {
+    return `Project "${projectKey}" was not found, or the authenticated account cannot browse it.`;
+  }
+  if (status && status >= 500) {
+    return `Jira createmeta endpoint returned a server error (${status}); retry later.`;
+  }
+  return `Failed to fetch createmeta for project "${projectKey}": ${err?.message ?? String(err)}`;
+}