@geraldmaron/construct 1.1.0 → 1.2.0

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

@@ -0,0 +1,181 @@
+/**
+ * providers/confluence/index.mjs — Confluence provider.
+ *
+ * Transport: Confluence REST API v2 (direct fetch, no SDK).
+ * Auth: API token via CONFLUENCE_TOKEN + CONFLUENCE_EMAIL + CONFLUENCE_URL,
+ *       or passed directly in config.
+ *
+ * Capabilities: read, write, search
+ *
+ * read refs:
+ *   "page:<id>"                  → single page by ID
+ *   "space:<key>:pages"          → pages in a space
+ *   "space:<key>:pages:<n>"      → first n pages in a space
+ *   "spaces"                     → list all accessible spaces
+ *
+ * write items:
+ *   { type: 'page', spaceId, title, body, parentId? }   → create page
+ *   { type: 'page-update', pageId, title, body, version } → update page
+ *   { type: 'comment', pageId, body }                   → add footer comment
+ *
+ * search: CQL query string (e.g. "space = DEV AND title ~ 'RFC'")
+ */
+
+import { AuthError, NotFoundError, RateLimitError } from '../../errors.mjs';
+
+export default {
+  name: 'confluence',
+  capabilities: ['read', 'write', 'search'],
+
+  _baseUrl: null,
+  _auth: null,
+
+  async init(config = {}) {
+    const url = config.baseUrl ?? process.env.CONFLUENCE_URL;
+    const email = config.email ?? process.env.CONFLUENCE_EMAIL;
+    const token = config.token ?? process.env.CONFLUENCE_TOKEN;
+
+    if (!url || !email || !token) {
+      throw new AuthError(
+        'Confluence provider requires CONFLUENCE_URL, CONFLUENCE_EMAIL, and CONFLUENCE_TOKEN',
+        { provider: 'confluence' },
+      );
+    }
+
+    this._baseUrl = url.replace(/\/$/, '');
+    this._auth = `Basic ${Buffer.from(`${email}:${token}`).toString('base64')}`;
+
+    const res = await this._fetch('/wiki/rest/api/user/current');
+    if (!res.ok) {
+      throw new AuthError(`Confluence auth failed: ${res.status} ${res.statusText}`, { provider: 'confluence' });
+    }
+  },
+
+  async _fetch(path, { method = 'GET', body } = {}) {
+    const url = `${this._baseUrl}${path}`;
+    const opts = {
+      method,
+      headers: {
+        Authorization: this._auth,
+        'Content-Type': 'application/json',
+        Accept: 'application/json',
+      },
+    };
+    if (body) opts.body = JSON.stringify(body);
+    const res = await fetch(url, opts);
+    if (res.status === 429) {
+      const retryAfter = parseInt(res.headers.get('Retry-After') ?? '60', 10);
+      throw new RateLimitError('Confluence rate limit hit', { provider: 'confluence', retryAfter });
+    }
+    return res;
+  },
+
+  async read(ref, _opts = {}) {
+    if (ref === 'spaces') {
+      const res = await this._fetch('/wiki/api/v2/spaces?limit=50');
+      if (!res.ok) throw new Error(`Confluence error: ${res.status}`);
+      const data = await res.json();
+      return (data.results ?? []).map((s) => ({
+        type: 'space',
+        id: s.id,
+        key: s.key,
+        name: s.name,
+        homepageId: s.homepageId,
+      }));
+    }
+
+    if (ref.startsWith('page:')) {
+      const pageId = ref.slice(5);
+      const res = await this._fetch(`/wiki/api/v2/pages/${pageId}?body-format=storage`);
+      if (res.status === 404) throw new NotFoundError(`Page not found: ${pageId}`, { provider: 'confluence' });
+      if (!res.ok) throw new Error(`Confluence error: ${res.status}`);
+      return [normalizePage(await res.json())];
+    }
+
+    const spaceMatch = ref.match(/^space:([^:]+):pages(?::(\d+))?$/);
+    if (spaceMatch) {
+      const spaceKey = spaceMatch[1];
+      const limit = parseInt(spaceMatch[2] ?? '25', 10);
+      // Look up space id from key first
+      const spacesRes = await this._fetch(`/wiki/api/v2/spaces?keys=${spaceKey}&limit=1`);
+      const spacesData = await spacesRes.json();
+      const space = spacesData.results?.[0];
+      if (!space) throw new NotFoundError(`Space not found: ${spaceKey}`, { provider: 'confluence' });
+      const res = await this._fetch(`/wiki/api/v2/spaces/${space.id}/pages?limit=${limit}&body-format=storage`);
+      if (!res.ok) throw new Error(`Confluence error: ${res.status}`);
+      const data = await res.json();
+      return (data.results ?? []).map(normalizePage);
+    }
+
+    throw new NotFoundError(`Unknown Confluence read ref: "${ref}"`, { provider: 'confluence' });
+  },
+
+  async write(item) {
+    if (item.type === 'page') {
+      const body = {
+        spaceId: item.spaceId,
+        title: item.title,
+        parentId: item.parentId ?? undefined,
+        body: { representation: 'storage', value: item.body },
+      };
+      const res = await this._fetch('/wiki/api/v2/pages', { method: 'POST', body });
+      if (!res.ok) throw new Error(`Confluence create page failed: ${res.status}`);
+      const data = await res.json();
+      return { type: 'page-created', id: data.id, title: data.title };
+    }
+
+    if (item.type === 'page-update') {
+      const body = {
+        id: item.pageId,
+        title: item.title,
+        version: { number: item.version },
+        body: { representation: 'storage', value: item.body },
+      };
+      const res = await this._fetch(`/wiki/api/v2/pages/${item.pageId}`, { method: 'PUT', body });
+      if (!res.ok) throw new Error(`Confluence update page failed: ${res.status}`);
+      return { type: 'page-updated', id: item.pageId };
+    }
+
+    if (item.type === 'comment') {
+      const body = {
+        pageId: item.pageId,
+        body: { representation: 'storage', value: item.body },
+      };
+      const res = await this._fetch('/wiki/api/v2/footer-comments', { method: 'POST', body });
+      if (!res.ok) throw new Error(`Confluence create comment failed: ${res.status}`);
+      const data = await res.json();
+      return { type: 'comment-created', id: data.id };
+    }
+
+    throw new Error(`Unknown Confluence write item type: "${item.type}"`);
+  },
+
+  async search(query, opts = {}) {
+    const limit = opts.limit ?? 25;
+    const cql = encodeURIComponent(query);
+    const res = await this._fetch(`/wiki/rest/api/content/search?cql=${cql}&limit=${limit}`);
+    if (!res.ok) throw new Error(`Confluence search failed: ${res.status}`);
+    const data = await res.json();
+    return (data.results ?? []).map((r) => ({
+      type: 'page',
+      id: r.id,
+      title: r.title,
+      spaceKey: r.space?.key,
+      url: r._links?.webui ?? null,
+    }));
+  },
+};
+
+function normalizePage(raw) {
+  return {
+    type: 'page',
+    id: raw.id,
+    title: raw.title,
+    spaceId: raw.spaceId,
+    parentId: raw.parentId ?? null,
+    version: raw.version?.number ?? null,
+    body: raw.body?.storage?.value ?? null,
+    createdAt: raw.createdAt ?? null,
+    url: raw._links?.webui ?? null,
+  };
+}

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

@@ -0,0 +1,115 @@
+/**
+ * providers/git/index.mjs — git repo provider.
+ *
+ * Transport: git CLI (via child_process). No external deps.
+ *
+ * Capabilities: read, search
+ *
+ * read refs:
+ *   "commits"              → recent commits (default 20)
+ *   "commits:<n>"          → last n commits
+ *   "branches"             → all branch names
+ *   "file:<path>"          → file contents at HEAD
+ *   "status"               → working tree status
+ *   "log:<path>"           → commit log for a specific path
+ *
+ * search: grep across tracked files (git grep)
+ */
+
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { AuthError, NotFoundError } from '../../errors.mjs';
+
+function git(args, cwd) {
+  const result = spawnSync('git', args, { cwd, encoding: 'utf8' });
+  if (result.error) throw new Error(`git spawn error: ${result.error.message}`);
+  return { stdout: result.stdout ?? '', stderr: result.stderr ?? '', status: result.status };
+}
+
+export default {
+  name: 'git',
+  capabilities: ['read', 'search'],
+
+  _cwd: null,
+
+  async init(config = {}) {
+    const cwd = config.cwd ?? process.cwd();
+    // Verify this is actually a git repo
+    const check = git(['rev-parse', '--git-dir'], cwd);
+    if (check.status !== 0) {
+      throw new AuthError(`Not a git repository: ${cwd}`, { provider: 'git' });
+    }
+    this._cwd = cwd;
+  },
+
+  async read(ref, _opts = {}) {
+    const cwd = this._cwd ?? process.cwd();
+
+    if (ref === 'branches') {
+      const r = git(['branch', '-a', '--format=%(refname:short)'], cwd);
+      return r.stdout.trim().split('\n').filter(Boolean).map((name) => ({ type: 'branch', name }));
+    }
+
+    if (ref === 'status') {
+      const r = git(['status', '--porcelain=v1'], cwd);
+      return r.stdout.trim().split('\n').filter(Boolean).map((line) => ({
+        type: 'status-entry',
+        code: line.slice(0, 2).trim(),
+        path: line.slice(3),
+      }));
+    }
+
+    if (ref.startsWith('commits') || ref === 'commits') {
+      const n = ref.includes(':') ? parseInt(ref.split(':')[1], 10) : 20;
+      const r = git(['log', `--max-count=${n}`, '--pretty=format:%H\t%an\t%ae\t%ai\t%s'], cwd);
+      return r.stdout.trim().split('\n').filter(Boolean).map((line) => {
+        const [hash, author, email, date, ...subjectParts] = line.split('\t');
+        return { type: 'commit', hash, author, email, date, subject: subjectParts.join('\t') };
+      });
+    }
+
+    if (ref.startsWith('file:')) {
+      const filePath = ref.slice(5);
+      const r = git(['show', `HEAD:${filePath}`], cwd);
+      if (r.status !== 0) {
+        throw new NotFoundError(`File not found in HEAD: ${filePath}`, { provider: 'git' });
+      }
+      return [{ type: 'file', path: filePath, content: r.stdout }];
+    }
+
+    if (ref.startsWith('log:')) {
+      const filePath = ref.slice(4);
+      const r = git(['log', '--follow', '--pretty=format:%H\t%an\t%ai\t%s', '--', filePath], cwd);
+      return r.stdout.trim().split('\n').filter(Boolean).map((line) => {
+        const [hash, author, date, ...subjectParts] = line.split('\t');
+        return { type: 'commit', hash, author, date, subject: subjectParts.join('\t'), path: filePath };
+      });
+    }
+
+    throw new NotFoundError(`Unknown git read ref: "${ref}"`, { provider: 'git' });
+  },
+
+  async search(query, opts = {}) {
+    const cwd = this._cwd ?? process.cwd();
+    const args = ['grep', '--line-number', '-I'];
+    if (opts.ignoreCase) args.push('-i');
+    args.push(query);
+    if (opts.paths) args.push('--', ...opts.paths);
+    const r = git(args, cwd);
+    if (r.status === 1 && r.stdout === '') return []; // no matches
+    if (r.status !== 0 && r.status !== 1) {
+      throw new Error(`git grep failed: ${r.stderr}`);
+    }
+    return r.stdout.trim().split('\n').filter(Boolean).map((line) => {
+      const colonIdx = line.indexOf(':');
+      const rest = line.slice(colonIdx + 1);
+      const lineNumIdx = rest.indexOf(':');
+      return {
+        type: 'grep-match',
+        file: line.slice(0, colonIdx),
+        lineNumber: parseInt(rest.slice(0, lineNumIdx), 10),
+        text: rest.slice(lineNumIdx + 1),
+      };
+    });
+  },
+};

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

@@ -0,0 +1,166 @@
+/**
+ * providers/github/index.mjs — GitHub provider.
+ *
+ * Transport: gh CLI (must be installed and authenticated).
+ *
+ * Capabilities: read, write, search, webhook
+ *
+ * read refs:
+ *   "prs"                     → open pull requests
+ *   "prs:all"                 → all PRs (open + closed)
+ *   "pr:<number>"             → single PR detail
+ *   "issues"                  → open issues
+ *   "issue:<number>"          → single issue detail
+ *   "releases"                → recent releases
+ *   "repo"                    → repo metadata
+ *
+ * write items:
+ *   { type: 'pr', title, body, head, base }            → create PR
+ *   { type: 'issue', title, body, labels? }            → create issue
+ *   { type: 'comment', issue_number, body }            → comment on issue/PR
+ *   { type: 'pr-merge', number, merge_method? }        → merge a PR
+ *
+ * search: gh search issues/prs/code
+ *   { scope: 'issues'|'prs'|'code', q: 'query string' }
+ *
+ * webhook: process GitHub webhook event objects
+ */
+
+import { spawnSync } from 'node:child_process';
+import { AuthError, NotFoundError } from '../../errors.mjs';
+
+function gh(args, { json = true, input } = {}) {
+  const fullArgs = json ? [...args, '--json', ...ghJsonFields(args)] : args;
+  const result = spawnSync('gh', fullArgs, {
+    encoding: 'utf8',
+    input,
+    env: process.env,
+  });
+  if (result.error) throw new Error(`gh spawn error: ${result.error.message}`);
+  if (result.status !== 0) {
+    const msg = result.stderr?.trim() || `gh exited with status ${result.status}`;
+    if (msg.includes('authentication') || msg.includes('401')) {
+      throw new AuthError(msg, { provider: 'github' });
+    }
+    throw new Error(`gh error: ${msg}`);
+  }
+  if (json && result.stdout) {
+    try { return JSON.parse(result.stdout); } catch { return result.stdout; }
+  }
+  return result.stdout;
+}
+
+// gh requires --json to list specific fields; default to a safe broad set
+function ghJsonFields(args) {
+  const cmd = args[0];
+  if (cmd === 'pr') return ['number,title,state,url,body,headRefName,baseRefName,author,createdAt,mergeable,labels'];
+  if (cmd === 'issue') return ['number,title,state,url,body,author,createdAt,labels,assignees'];
+  if (cmd === 'release') return ['tagName,name,publishedAt,url,body'];
+  if (cmd === 'repo') return ['name,description,url,defaultBranchRef,isPrivate,stargazerCount'];
+  return [''];
+}
+
+export default {
+  name: 'github',
+  capabilities: ['read', 'write', 'search', 'webhook'],
+
+  _repo: null,
+
+  async init(config = {}) {
+    this._repo = config.repo ?? null; // optional "owner/repo" override
+    // Verify gh is available and authenticated
+    const check = spawnSync('gh', ['auth', 'status'], { encoding: 'utf8', env: process.env });
+    if (check.status !== 0) {
+      throw new AuthError('gh CLI not authenticated. Run: gh auth login', { provider: 'github' });
+    }
+  },
+
+  async read(ref, _opts = {}) {
+    const repoFlag = this._repo ? ['-R', this._repo] : [];
+
+    if (ref === 'prs' || ref === 'prs:all') {
+      const stateFlag = ref === 'prs:all' ? ['--state', 'all'] : ['--state', 'open'];
+      return gh(['pr', 'list', ...repoFlag, ...stateFlag, '--limit', '50']);
+    }
+
+    if (ref.startsWith('pr:')) {
+      const num = ref.slice(3);
+      return [gh(['pr', 'view', num, ...repoFlag])];
+    }
+
+    if (ref === 'issues') {
+      return gh(['issue', 'list', ...repoFlag, '--state', 'open', '--limit', '50']);
+    }
+
+    if (ref.startsWith('issue:')) {
+      const num = ref.slice(6);
+      return [gh(['issue', 'view', num, ...repoFlag])];
+    }
+
+    if (ref === 'releases') {
+      return gh(['release', 'list', ...repoFlag, '--limit', '20']);
+    }
+
+    if (ref === 'repo') {
+      return [gh(['repo', 'view', ...repoFlag])];
+    }
+
+    throw new NotFoundError(`Unknown GitHub read ref: "${ref}"`, { provider: 'github' });
+  },
+
+  async write(item) {
+    const repoFlag = this._repo ? ['-R', this._repo] : [];
+
+    if (item.type === 'issue') {
+      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 });
+      return { type: 'issue-created', url: out.stdout.trim() };
+    }
+
+    if (item.type === 'pr') {
+      const args = ['pr', 'create', ...repoFlag,
+        '--title', item.title,
+        '--body', item.body ?? '',
+        '--head', item.head,
+        '--base', item.base ?? 'main',
+      ];
+      if (item.draft) args.push('--draft');
+      const out = spawnSync('gh', args, { encoding: 'utf8', env: process.env });
+      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 });
+      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}`], {
+        encoding: 'utf8',
+        env: process.env,
+      });
+      return { type: 'pr-merged', number: item.number };
+    }
+
+    throw new Error(`Unknown GitHub write item type: "${item.type}"`);
+  },
+
+  async search(query, opts = {}) {
+    const scope = opts.scope ?? 'issues';
+    const repoFlag = this._repo ? ['--repo', this._repo] : [];
+    const args = ['search', scope, query, ...repoFlag, '--limit', '30', '--json',
+      scope === 'code' ? 'path,repository,url,textMatches' : 'number,title,state,url,repository',
+    ];
+    const results = gh(args, { json: false });
+    try { return JSON.parse(results); } catch { return []; }
+  },
+
+  async webhook(event) {
+    // Normalize inbound GitHub webhook event to a common shape for core to consume
+    const type = event?.action ? `${event.type ?? 'unknown'}.${event.action}` : (event?.type ?? 'unknown');
+    return { provider: 'github', type, raw: event };
+  },
+};

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

@@ -0,0 +1,187 @@
+/**
+ * providers/jira/index.mjs — Jira provider.
+ *
+ * Transport: Jira REST API v3 (direct fetch, no SDK).
+ * Auth: API token via JIRA_TOKEN + JIRA_EMAIL + JIRA_URL env vars,
+ *       or passed directly in config.
+ *
+ * Capabilities: read, write, search, webhook
+ *
+ * read refs:
+ *   "issue:<KEY>"              → single issue (e.g. "issue:PROJ-123")
+ *   "project:<KEY>"            → project metadata
+ *   "board:<id>:sprint"        → active sprint issues for a board
+ *   "search:<JQL>"             → JQL query (shorthand; prefer search() for full control)
+ *
+ * write items:
+ *   { type: 'issue', project, issueType, summary, description?, assignee?, labels? }
+ *   { type: 'comment', issueKey, body }
+ *   { type: 'transition', issueKey, transitionId }
+ *   { type: 'update', issueKey, fields }
+ *
+ * search: JQL string (e.g. "project = PROJ AND status = 'In Progress'")
+ *
+ * webhook: process Jira webhook event objects
+ */
+
+import { AuthError, NotFoundError, RateLimitError } from '../../errors.mjs';
+
+export default {
+  name: 'jira',
+  capabilities: ['read', 'write', 'search', 'webhook'],
+
+  _baseUrl: null,
+  _auth: null,
+
+  async init(config = {}) {
+    const url = config.baseUrl ?? process.env.JIRA_URL;
+    const email = config.email ?? process.env.JIRA_EMAIL;
+    const token = config.token ?? process.env.JIRA_TOKEN;
+
+    if (!url || !email || !token) {
+      throw new AuthError(
+        'Jira provider requires JIRA_URL, JIRA_EMAIL, and JIRA_TOKEN (or config.baseUrl/email/token)',
+        { provider: 'jira' },
+      );
+    }
+
+    this._baseUrl = url.replace(/\/$/, '');
+    this._auth = `Basic ${Buffer.from(`${email}:${token}`).toString('base64')}`;
+
+    // Verify credentials
+    const res = await this._fetch('/rest/api/3/myself');
+    if (!res.ok) {
+      throw new AuthError(`Jira auth failed: ${res.status} ${res.statusText}`, { provider: 'jira' });
+    }
+  },
+
+  async _fetch(path, { method = 'GET', body } = {}) {
+    const url = `${this._baseUrl}${path}`;
+    const opts = {
+      method,
+      headers: {
+        Authorization: this._auth,
+        'Content-Type': 'application/json',
+        Accept: 'application/json',
+      },
+    };
+    if (body) opts.body = JSON.stringify(body);
+    const res = await fetch(url, opts);
+    if (res.status === 429) {
+      const retryAfter = parseInt(res.headers.get('Retry-After') ?? '60', 10);
+      throw new RateLimitError('Jira rate limit hit', { provider: 'jira', retryAfter });
+    }
+    return res;
+  },
+
+  async read(ref, _opts = {}) {
+    if (ref.startsWith('issue:')) {
+      const key = ref.slice(6);
+      const res = await this._fetch(`/rest/api/3/issue/${key}`);
+      if (res.status === 404) throw new NotFoundError(`Issue not found: ${key}`, { provider: 'jira' });
+      const data = await res.json();
+      return [normalizeIssue(data)];
+    }
+
+    if (ref.startsWith('project:')) {
+      const key = ref.slice(8);
+      const res = await this._fetch(`/rest/api/3/project/${key}`);
+      if (res.status === 404) throw new NotFoundError(`Project not found: ${key}`, { provider: 'jira' });
+      return [await res.json()];
+    }
+
+    if (ref.startsWith('search:')) {
+      const jql = ref.slice(7);
+      return this.search(jql);
+    }
+
+    throw new NotFoundError(`Unknown Jira read ref: "${ref}"`, { provider: 'jira' });
+  },
+
+  async write(item) {
+    if (item.type === 'issue') {
+      const body = {
+        fields: {
+          project: { key: item.project },
+          issuetype: { name: item.issueType ?? 'Task' },
+          summary: item.summary,
+          ...(item.description ? { description: adfDoc(item.description) } : {}),
+          ...(item.assignee ? { assignee: { accountId: item.assignee } } : {}),
+          ...(item.labels ? { labels: item.labels } : {}),
+        },
+      };
+      const res = await this._fetch('/rest/api/3/issue', { method: 'POST', body });
+      const data = await res.json();
+      return { type: 'issue-created', key: data.key, id: data.id };
+    }
+
+    if (item.type === 'comment') {
+      const body = { body: adfDoc(item.body) };
+      const res = await this._fetch(`/rest/api/3/issue/${item.issueKey}/comment`, { method: 'POST', body });
+      const data = await res.json();
+      return { type: 'comment-created', id: data.id, issueKey: item.issueKey };
+    }
+
+    if (item.type === 'transition') {
+      await this._fetch(`/rest/api/3/issue/${item.issueKey}/transitions`, {
+        method: 'POST',
+        body: { transition: { id: String(item.transitionId) } },
+      });
+      return { type: 'transitioned', issueKey: item.issueKey, transitionId: item.transitionId };
+    }
+
+    if (item.type === 'update') {
+      await this._fetch(`/rest/api/3/issue/${item.issueKey}`, {
+        method: 'PUT',
+        body: { fields: item.fields },
+      });
+      return { type: 'updated', issueKey: item.issueKey };
+    }
+
+    throw new Error(`Unknown Jira write item type: "${item.type}"`);
+  },
+
+  async search(query, opts = {}) {
+    const body = {
+      jql: query,
+      maxResults: opts.maxResults ?? 50,
+      fields: opts.fields ?? ['summary', 'status', 'assignee', 'priority', 'issuetype', 'created', 'updated'],
+    };
+    const res = await this._fetch('/rest/api/3/search', { method: 'POST', body });
+    const data = await res.json();
+    return (data.issues ?? []).map(normalizeIssue);
+  },
+
+  async webhook(event) {
+    const type = event?.webhookEvent ?? 'unknown';
+    return { provider: 'jira', type, raw: event };
+  },
+};
+
+// ── Helpers ──────────────────────────────────────────────────────────────
+
+function normalizeIssue(raw) {
+  const f = raw.fields ?? {};
+  return {
+    type: 'issue',
+    key: raw.key,
+    id: raw.id,
+    summary: f.summary,
+    status: f.status?.name,
+    assignee: f.assignee?.displayName ?? null,
+    priority: f.priority?.name ?? null,
+    issueType: f.issuetype?.name,
+    created: f.created,
+    updated: f.updated,
+    url: raw.self?.replace(/\/rest\/api\/.*/, `/browse/${raw.key}`) ?? null,
+  };
+}
+
+/** Wrap plain text in minimal ADF document for Jira REST API v3 */
+function adfDoc(text) {
+  return {
+    type: 'doc',
+    version: 1,
+    content: [{ type: 'paragraph', content: [{ type: 'text', text: String(text) }] }],
+  };
+}