@taodigital/connectors 0.0.0-stage → 1.2.0

package/src/github.ts

@@ -0,0 +1,139 @@
+/**
+ * GitHub connector — credentials passed in, never read from env.
+ * Token is stored encrypted in Connector.config per project.
+ */
+
+import { assertResolvesToPublicAddress } from '@taodigital/core';
+
+export interface GitHubCredentials {
+  token: string;
+  repo: string;        // "owner/repository"
+  defaultBranch?: string;
+}
+
+/** Test that the stored credentials actually work. */
+export async function testConnection(creds: GitHubCredentials): Promise<{ ok: boolean; login?: string; error?: string }> {
+  try {
+    await assertResolvesToPublicAddress('https://api.github.com');
+    const res = await fetch('https://api.github.com/user', {
+      headers: { Authorization: `Bearer ${creds.token}`, 'User-Agent': 'zeta-ai' },
+    });
+    if (!res.ok) return { ok: false, error: `GitHub returned ${res.status}` };
+    const data = (await res.json()) as any;
+    return { ok: true, login: data.login };
+  } catch (err) {
+    return { ok: false, error: String(err) };
+  }
+}
+
+export async function listRecentCommits(creds: GitHubCredentials, branch?: string) {
+  await assertResolvesToPublicAddress('https://api.github.com');
+  const { getSystemConfig } = await import('@taodigital/core');
+  const ghCfg = await getSystemConfig('connectors_github');
+  const pageSize = parseInt(String(ghCfg?.pageSize ?? '10'), 10);
+  const ref = branch ?? creds.defaultBranch ?? 'main';
+  const res = await fetch(
+    `https://api.github.com/repos/${creds.repo}/commits?sha=${ref}&per_page=${pageSize}`,
+    { headers: { Authorization: `Bearer ${creds.token}`, 'User-Agent': 'zeta-ai' } }
+  );
+  if (!res.ok) throw new Error(`GitHub error: ${res.status}`);
+  const commits = (await res.json()) as any[];
+  return commits.map((c) => ({
+    sha: c.sha?.slice(0, 7),
+    message: c.commit?.message?.split('\n')[0],
+    author: c.commit?.author?.name,
+    date: c.commit?.author?.date,
+  }));
+}
+
+export async function createIssue(creds: GitHubCredentials, title: string, body: string, labels?: string[], opts?: { defaultLabels?: string[] }) {
+  await assertResolvesToPublicAddress('https://api.github.com');
+  const res = await fetch(
+    `https://api.github.com/repos/${creds.repo}/issues`,
+    {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${creds.token}`,
+        'User-Agent': 'zeta-ai',
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({ title, body, labels: labels ?? opts?.defaultLabels ?? [] }),
+    }
+  );
+  if (!res.ok) throw new Error(`GitHub error: ${res.status}`);
+  const issue = (await res.json()) as any;
+  return { number: issue.number, url: issue.html_url, title: issue.title };
+}
+
+export async function listPullRequests(creds: GitHubCredentials, state: 'open' | 'closed' | 'all' = 'open') {
+  await assertResolvesToPublicAddress('https://api.github.com');
+  const { getSystemConfig } = await import('@taodigital/core');
+  const ghCfg = await getSystemConfig('connectors_github');
+  const pageSize = parseInt(String(ghCfg?.pageSize ?? '10'), 10);
+  const res = await fetch(
+    `https://api.github.com/repos/${creds.repo}/pulls?state=${state}&per_page=${pageSize}`,
+    { headers: { Authorization: `Bearer ${creds.token}`, 'User-Agent': 'zeta-ai' } }
+  );
+  if (!res.ok) throw new Error(`GitHub error: ${res.status}`);
+  const prs = (await res.json()) as any[];
+  return prs.map((p) => ({
+    number: p.number,
+    title: p.title,
+    state: p.state,
+    branch: p.head?.ref,
+    url: p.html_url,
+  }));
+}
+
+/**
+ * Push (create or update) a single file in a GitHub repository.
+ * Uses the GitHub Contents API (PUT /repos/:owner/:repo/contents/:path).
+ */
+export async function pushFile(
+  creds: GitHubCredentials,
+  filePath: string,
+  content: string,
+  commitMessage: string,
+  branch?: string,
+): Promise<{ url: string; sha: string }> {
+  await assertResolvesToPublicAddress('https://api.github.com');
+  const targetBranch = branch ?? creds.defaultBranch ?? 'main';
+  const apiBase = 'https://api.github.com';
+  const headers: Record<string, string> = {
+    Authorization: `Bearer ${creds.token}`,
+    Accept: 'application/vnd.github.v3+json',
+    'Content-Type': 'application/json',
+    'User-Agent': 'zeta-ai',
+  };
+  const encodedContent = Buffer.from(content, 'utf8').toString('base64');
+
+  // Fetch existing file SHA (required by GitHub API to update an existing file)
+  let sha: string | undefined;
+  const existing = await fetch(
+    `${apiBase}/repos/${creds.repo}/contents/${filePath}?ref=${targetBranch}`,
+    { headers },
+  ).then((r) => (r.ok ? r.json() : null)).catch(() => null) as any;
+  if (existing?.sha) sha = existing.sha;
+
+  const body: Record<string, unknown> = {
+    message: commitMessage,
+    content: encodedContent,
+    branch: targetBranch,
+  };
+  if (sha) body.sha = sha;
+
+  const res = await fetch(`${apiBase}/repos/${creds.repo}/contents/${filePath}`, {
+    method: 'PUT',
+    headers,
+    body: JSON.stringify(body),
+  });
+  if (!res.ok) {
+    const err = await res.json().catch(() => ({}) as any) as any;
+    throw new Error(`GitHub push failed: ${err.message ?? res.statusText}`);
+  }
+  const data = await res.json() as any;
+  return {
+    url: data.content?.html_url ?? `https://github.com/${creds.repo}/blob/${targetBranch}/${filePath}`,
+    sha: data.content?.sha ?? '',
+  };
+}

package/src/gitlab.ts

@@ -0,0 +1,166 @@
+/**
+ * GitLab connector — credentials passed in, never read from env.
+ * Token (Personal Access Token or project token) stored encrypted
+ * in Connector.config per project. Supports gitlab.com and self-hosted.
+ */
+
+import { assertResolvesToPublicAddress } from '@taodigital/core';
+
+export interface GitLabCredentials {
+  token: string;
+  projectPath: string;   // "namespace/project" or numeric project ID
+  baseUrl?: string;      // defaults to https://gitlab.com
+  defaultBranch?: string;
+}
+
+function apiBase(creds: GitLabCredentials): string {
+  const host = (creds.baseUrl ?? 'https://gitlab.com').replace(/\/$/, '');
+  return `${host}/api/v4`;
+}
+
+function authHeaders(token: string): Record<string, string> {
+  return { 'PRIVATE-TOKEN': token, 'Content-Type': 'application/json' };
+}
+
+/** URL-encode a project path for use in GitLab API paths. */
+function encodeProject(projectPath: string): string {
+  return encodeURIComponent(projectPath);
+}
+
+export async function testConnection(
+  creds: GitLabCredentials,
+): Promise<{ ok: boolean; login?: string; error?: string }> {
+  try {
+    const host = creds.baseUrl ?? 'https://gitlab.com';
+    await assertResolvesToPublicAddress(host);
+    const base = apiBase(creds);
+    const res = await fetch(`${base}/projects/${encodeProject(creds.projectPath)}`, {
+      headers: authHeaders(creds.token),
+      signal: AbortSignal.timeout(10_000),
+    });
+    if (res.status === 401) return { ok: false, error: 'Invalid GitLab token.' };
+    if (res.status === 404) return { ok: false, error: `Project "${creds.projectPath}" not found or token lacks access.` };
+    if (!res.ok) return { ok: false, error: `GitLab returned ${res.status}.` };
+    const project = (await res.json()) as any;
+    return { ok: true, login: project.path_with_namespace ?? creds.projectPath };
+  } catch (err: any) {
+    return { ok: false, error: err?.message ?? 'Could not reach GitLab.' };
+  }
+}
+
+export async function listRecentCommits(creds: GitLabCredentials, branch?: string) {
+  const host = creds.baseUrl ?? 'https://gitlab.com';
+  await assertResolvesToPublicAddress(host);
+  const { getSystemConfig } = await import('@taodigital/core');
+  const cfg = await getSystemConfig('connectors_gitlab');
+  const pageSize = parseInt(String(cfg?.pageSize ?? '10'), 10);
+  const ref = branch ?? creds.defaultBranch ?? 'main';
+  const base = apiBase(creds);
+  const res = await fetch(
+    `${base}/projects/${encodeProject(creds.projectPath)}/repository/commits?ref_name=${encodeURIComponent(ref)}&per_page=${pageSize}`,
+    { headers: authHeaders(creds.token), signal: AbortSignal.timeout(15_000) },
+  );
+  if (!res.ok) throw new Error(`GitLab error: ${res.status}`);
+  const commits = (await res.json()) as any[];
+  return commits.map((c) => ({
+    sha: c.id?.slice(0, 7),
+    message: c.title ?? c.message?.split('\n')[0],
+    author: c.author_name,
+    date: c.created_at,
+  }));
+}
+
+export async function createIssue(
+  creds: GitLabCredentials,
+  title: string,
+  body: string,
+  labels?: string[],
+): Promise<{ number: number; url: string; title: string }> {
+  const host = creds.baseUrl ?? 'https://gitlab.com';
+  await assertResolvesToPublicAddress(host);
+  const base = apiBase(creds);
+  const res = await fetch(`${base}/projects/${encodeProject(creds.projectPath)}/issues`, {
+    method: 'POST',
+    headers: authHeaders(creds.token),
+    body: JSON.stringify({ title, description: body, labels: labels?.join(',') }),
+    signal: AbortSignal.timeout(15_000),
+  });
+  if (!res.ok) throw new Error(`GitLab error: ${res.status}`);
+  const issue = (await res.json()) as any;
+  return { number: issue.iid, url: issue.web_url, title: issue.title };
+}
+
+export async function listMergeRequests(
+  creds: GitLabCredentials,
+  state: 'opened' | 'closed' | 'merged' | 'all' = 'opened',
+) {
+  const host = creds.baseUrl ?? 'https://gitlab.com';
+  await assertResolvesToPublicAddress(host);
+  const { getSystemConfig } = await import('@taodigital/core');
+  const cfg = await getSystemConfig('connectors_gitlab');
+  const pageSize = parseInt(String(cfg?.pageSize ?? '10'), 10);
+  const base = apiBase(creds);
+  const res = await fetch(
+    `${base}/projects/${encodeProject(creds.projectPath)}/merge_requests?state=${state}&per_page=${pageSize}`,
+    { headers: authHeaders(creds.token), signal: AbortSignal.timeout(15_000) },
+  );
+  if (!res.ok) throw new Error(`GitLab error: ${res.status}`);
+  const mrs = (await res.json()) as any[];
+  return mrs.map((m) => ({
+    number: m.iid,
+    title: m.title,
+    state: m.state,
+    branch: m.source_branch,
+    url: m.web_url,
+  }));
+}
+
+/**
+ * Push (create or update) a single file in a GitLab repository.
+ * Uses the GitLab Repository Files API.
+ */
+export async function pushFile(
+  creds: GitLabCredentials,
+  filePath: string,
+  content: string,
+  commitMessage: string,
+  branch?: string,
+): Promise<{ url: string; sha: string }> {
+  const host = creds.baseUrl ?? 'https://gitlab.com';
+  await assertResolvesToPublicAddress(host);
+  const targetBranch = branch ?? creds.defaultBranch ?? 'main';
+  const base = apiBase(creds);
+  const encodedProject = encodeProject(creds.projectPath);
+  const encodedPath = encodeURIComponent(filePath);
+  const encodedContent = Buffer.from(content, 'utf8').toString('base64');
+
+  // Check if file exists to decide between POST (create) and PUT (update)
+  const existing = await fetch(
+    `${base}/projects/${encodedProject}/repository/files/${encodedPath}?ref=${encodeURIComponent(targetBranch)}`,
+    { headers: authHeaders(creds.token), signal: AbortSignal.timeout(10_000) },
+  ).catch(() => null);
+  const fileExists = existing?.ok ?? false;
+
+  const method = fileExists ? 'PUT' : 'POST';
+  const res = await fetch(`${base}/projects/${encodedProject}/repository/files/${encodedPath}`, {
+    method,
+    headers: authHeaders(creds.token),
+    body: JSON.stringify({
+      branch: targetBranch,
+      content: encodedContent,
+      encoding: 'base64',
+      commit_message: commitMessage,
+    }),
+    signal: AbortSignal.timeout(20_000),
+  });
+  if (!res.ok) {
+    const err = await res.json().catch(() => ({}) as any) as any;
+    throw new Error(`GitLab push failed: ${err.message ?? res.statusText}`);
+  }
+  const data = (await res.json()) as any;
+  const glBase = (creds.baseUrl ?? 'https://gitlab.com').replace(/\/$/, '');
+  return {
+    url: `${glBase}/${creds.projectPath}/-/blob/${targetBranch}/${filePath}`,
+    sha: data.file_path ?? filePath,
+  };
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+export * as github from './github.js';
+export * as gitlab from './gitlab.js';
+export * as azuredevops from './azuredevops.js';
+export * as jira from './jira.js';
+export * as figma from './figma.js';
+export * as confluence from './confluence.js';
+export * as pagerduty from './pagerduty.js';
+export * as servicenow from './servicenow.js';
+export * as salesforce from './salesforce.js';

package/src/jira.ts

@@ -0,0 +1,372 @@
+/**
+ * JIRA connector — credentials passed in, never read from env.
+ * baseUrl and email stored as-is; apiToken stored encrypted.
+ */
+
+import { assertResolvesToPublicAddress } from '@taodigital/core';
+
+export interface JiraCredentials {
+  baseUrl: string;   // e.g. https://yourcompany.atlassian.net or https://api.atlassian.com/ex/jira/{cloudId}
+  email: string;     // Atlassian email (Cloud) or username (Server/Data Center)
+  apiToken: string;  // Atlassian API token (Cloud)
+  password?: string; // Password (Server/Data Center) — takes priority over apiToken when set
+  projectKey?: string; // e.g. "APP" or "QA"
+  bearerToken?: string; // OAuth 2.0 access token — takes priority over Basic auth
+  proxyUrl?: string; // e.g. http://corporate-proxy:8080 — enables on-prem JIRA access, skips SSRF guard
+}
+
+function validateProxyUrl(proxyUrl: string): void {
+  let parsed: URL;
+  try { parsed = new URL(proxyUrl); } catch { throw new Error(`Invalid proxy URL: ${proxyUrl}`); }
+  const h = parsed.hostname.toLowerCase();
+  // Block loopback, link-local metadata
+  if (h === 'localhost' || h === '127.0.0.1' || h === '::1' || h === '169.254.169.254') {
+    throw new Error('Proxy URL must not target localhost or metadata addresses');
+  }
+  // Block RFC-1918 private ranges (10/8, 172.16-31/12, 192.168/16)
+  const parts = h.split('.').map(Number);
+  if (parts.length === 4 && !parts.some(isNaN)) {
+    const [a, b] = parts;
+    if (a === 10) throw new Error('Proxy URL must not target private network (10.0.0.0/8)');
+    if (a === 172 && b >= 16 && b <= 31) throw new Error('Proxy URL must not target private network (172.16.0.0/12)');
+    if (a === 192 && b === 168) throw new Error('Proxy URL must not target private network (192.168.0.0/16)');
+  }
+}
+
+async function makeFetch(creds: JiraCredentials): Promise<typeof fetch> {
+  const TIMEOUT_MS = 15_000;
+  if (creds.proxyUrl) {
+    validateProxyUrl(creds.proxyUrl);
+    const { ProxyAgent } = await import('undici');
+    const dispatcher = new ProxyAgent(creds.proxyUrl);
+    return (url, init) => fetch(url, { signal: AbortSignal.timeout(TIMEOUT_MS), ...(init ?? {}), dispatcher } as any);
+  }
+  // Wrap global fetch with a 15s timeout on every call
+  return (url, init) => fetch(url as any, { signal: AbortSignal.timeout(TIMEOUT_MS), ...(init ?? {}) });
+}
+
+function authHeader(creds: JiraCredentials): string {
+  if (creds.bearerToken) return `Bearer ${creds.bearerToken}`;
+  const secret = creds.password || creds.apiToken; // password = Server/DC, apiToken = Cloud
+  return 'Basic ' + Buffer.from(`${creds.email}:${secret}`).toString('base64');
+}
+
+export async function testConnection(creds: JiraCredentials): Promise<{ ok: boolean; displayName?: string; error?: string }> {
+  try {
+    const doFetch = await makeFetch(creds);
+    if (!creds.proxyUrl) await assertResolvesToPublicAddress(creds.baseUrl);
+    const res = await doFetch(`${creds.baseUrl}/rest/api/3/myself`, {
+      headers: { Authorization: authHeader(creds), Accept: 'application/json' },
+    });
+    if (!res.ok) return { ok: false, error: `JIRA returned ${res.status}` };
+    const data = (await res.json()) as any;
+    return { ok: true, displayName: data.displayName };
+  } catch (err) {
+    return { ok: false, error: String(err) };
+  }
+}
+
+export async function listProjects(creds: JiraCredentials) {
+  const doFetch = await makeFetch(creds);
+  if (!creds.proxyUrl) await assertResolvesToPublicAddress(creds.baseUrl);
+  const { getSystemConfig } = await import('@taodigital/core');
+  const jiraCfg = await getSystemConfig('connectors_jira');
+  const pageSize = parseInt(String(jiraCfg?.pageSize ?? '50'), 10);
+  const MAX_PAGES = 10;
+  const allProjects: any[] = [];
+  let startAt = 0;
+  let truncated = false;
+
+  for (let page = 0; page < MAX_PAGES; page++) {
+    const res = await doFetch(`${creds.baseUrl}/rest/api/3/project/search?maxResults=${pageSize}&startAt=${startAt}`, {
+      headers: { Authorization: authHeader(creds), Accept: 'application/json' },
+    });
+    if (!res.ok) throw new Error(`JIRA error: ${res.status}`);
+    const data = (await res.json()) as any;
+    const values: any[] = data.values ?? [];
+    allProjects.push(...values);
+    const total: number = data.total ?? 0;
+    if (values.length < pageSize || allProjects.length >= total) break;
+    startAt += values.length;
+    if (page === MAX_PAGES - 1) {
+      truncated = true;
+      console.warn(`listProjects: total=${total} exceeds page cap (${MAX_PAGES * pageSize}); results truncated`);
+      break;
+    }
+  }
+
+  return allProjects.map((p: any) => ({ key: p.key, name: p.name, id: p.id }));
+}
+
+export async function listRecentIssues(creds: JiraCredentials, maxResults?: number) {
+  const doFetch = await makeFetch(creds);
+  if (!creds.proxyUrl) await assertResolvesToPublicAddress(creds.baseUrl);
+  const { getSystemConfig } = await import('@taodigital/core');
+  const jiraCfg = await getSystemConfig('connectors_jira');
+  const resolvedMaxResults = maxResults ?? parseInt(String(jiraCfg?.recentPageSize ?? '20'), 10);
+  const jql = creds.projectKey
+    ? `project = "${(creds.projectKey ?? '').replace(/"/g, '\\"')}" ORDER BY updated DESC`
+    : 'ORDER BY updated DESC';
+
+  const res = await doFetch(
+    `${creds.baseUrl}/rest/api/3/search?jql=${encodeURIComponent(jql)}&maxResults=${resolvedMaxResults}&fields=summary,status,priority,assignee,updated`,
+    { headers: { Authorization: authHeader(creds), Accept: 'application/json' } }
+  );
+  if (!res.ok) throw new Error(`JIRA error: ${res.status}`);
+  const data = (await res.json()) as any;
+  return (data.issues ?? []).map((i: any) => ({
+    key: i.key,
+    summary: i.fields?.summary,
+    status: i.fields?.status?.name,
+    priority: i.fields?.priority?.name,
+    assignee: i.fields?.assignee?.displayName,
+    updated: i.fields?.updated,
+  }));
+}
+
+export interface GetIssueOptions {
+  acceptanceCriteriaFieldId?: string;
+}
+
+export async function getIssue(creds: JiraCredentials, issueKey: string, options: GetIssueOptions = {}) {
+  const doFetch = await makeFetch(creds);
+  if (!creds.proxyUrl) await assertResolvesToPublicAddress(creds.baseUrl);
+  const { getSystemConfig } = await import('@taodigital/core');
+  const jiraCfg = await getSystemConfig('connectors_jira');
+  const acField = options.acceptanceCriteriaFieldId ?? String(jiraCfg?.acFieldId ?? '');
+  const fieldsParam = `summary,description,status,priority,issuetype,labels,components,issuelinks,parent,subtasks${acField ? `,${acField}` : ''}`;
+  const res = await doFetch(`${creds.baseUrl}/rest/api/3/issue/${issueKey}?fields=${encodeURIComponent(fieldsParam)}`, {
+    headers: { Authorization: authHeader(creds), Accept: 'application/json' },
+  });
+  if (!res.ok) throw new Error(`JIRA error: ${res.status}`);
+  const i = (await res.json()) as any;
+  return {
+    key: i.key,
+    summary: i.fields?.summary,
+    description: i.fields?.description,
+    status: i.fields?.status?.name,
+    priority: i.fields?.priority?.name,
+    issueType: i.fields?.issuetype?.name,
+    acceptanceCriteria: acField ? (i.fields?.[acField] ?? null) : null,
+    labels: i.fields?.labels ?? [],
+    components: (i.fields?.components ?? []).map((c: any) => c.name),
+    epic: i.fields?.parent ? { key: i.fields.parent.key, summary: i.fields.parent.fields?.summary } : null,
+    links: (i.fields?.issuelinks ?? []).map((l: any) => ({
+      type: l.type?.name ?? l.type?.inward ?? l.type?.outward ?? 'relates',
+      key: l.inwardIssue?.key ?? l.outwardIssue?.key,
+      summary: l.inwardIssue?.fields?.summary ?? l.outwardIssue?.fields?.summary,
+    })).filter((x: any) => Boolean(x.key)),
+    subtasks: (i.fields?.subtasks ?? []).map((st: any) => ({ key: st.key, summary: st.fields?.summary })),
+    url: `${creds.baseUrl}/browse/${i.key}`,
+  };
+}
+
+export async function createBug(creds: JiraCredentials, opts: {
+  summary: string;
+  description: string;
+  priority?: 'Highest' | 'High' | 'Medium' | 'Low' | 'Lowest';
+  labels?: string[];
+  defaultBugPriority?: string;
+  defaultBugLabel?: string;
+}) {
+  const doFetch = await makeFetch(creds);
+  if (!creds.proxyUrl) await assertResolvesToPublicAddress(creds.baseUrl);
+  if (!creds.projectKey) throw new Error('projectKey required to create JIRA issues.');
+  const res = await doFetch(`${creds.baseUrl}/rest/api/3/issue`, {
+    method: 'POST',
+    headers: {
+      Authorization: authHeader(creds),
+      Accept: 'application/json',
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({
+      fields: {
+        project: { key: creds.projectKey },
+        summary: opts.summary,
+        description: {
+          type: 'doc',
+          version: 1,
+          content: [{ type: 'paragraph', content: [{ type: 'text', text: opts.description }] }],
+        },
+        issuetype: { name: 'Bug' },
+        priority: { name: opts.priority ?? opts.defaultBugPriority ?? 'High' },
+        labels: opts.labels ?? (opts.defaultBugLabel ? [opts.defaultBugLabel] : []),
+      },
+    }),
+  });
+  if (!res.ok) throw new Error(`JIRA error: ${res.status} ${await res.text()}`);
+  const created = (await res.json()) as any;
+  return { key: created.key, url: `${creds.baseUrl}/browse/${created.key}` };
+}
+
+export interface ListUserStoriesOptions {
+  acceptanceCriteriaFieldId?: string;
+}
+
+export async function listUserStories(creds: JiraCredentials, sprintId?: string, maxResults?: number, options: ListUserStoriesOptions = {}) {
+  const doFetch = await makeFetch(creds);
+  if (!creds.proxyUrl) await assertResolvesToPublicAddress(creds.baseUrl);
+  const { getSystemConfig } = await import('@taodigital/core');
+  const jiraCfg = await getSystemConfig('connectors_jira');
+  const pageSize = Math.min(maxResults ?? parseInt(String(jiraCfg?.pageSize ?? '50'), 10), 100);
+  const acField = options.acceptanceCriteriaFieldId ?? String(jiraCfg?.acFieldId ?? '');
+  const jql = sprintId
+    ? `project = "${(creds.projectKey ?? '').replace(/"/g, '\\"')}" AND sprint = ${sprintId} AND issuetype = Story ORDER BY priority DESC`
+    : `project = "${(creds.projectKey ?? '').replace(/"/g, '\\"')}" AND issuetype = Story ORDER BY updated DESC`;
+
+  const fieldsParam = `summary,description,status,priority,issuetype,labels,components,issuelinks,parent,subtasks${acField ? `,${acField}` : ''}`;
+  const MAX_PAGES = 20;
+  const allIssues: any[] = [];
+  let startAt = 0;
+  let truncated = false;
+
+  for (let page = 0; page < MAX_PAGES; page++) {
+    const res = await doFetch(
+      `${creds.baseUrl}/rest/api/3/search?jql=${encodeURIComponent(jql)}&maxResults=${pageSize}&startAt=${startAt}&fields=${encodeURIComponent(fieldsParam)}`,
+      { headers: { Authorization: authHeader(creds), Accept: 'application/json' } }
+    );
+    if (!res.ok) throw new Error(`JIRA error: ${res.status}`);
+    const data = (await res.json()) as any;
+    const issues: any[] = data.issues ?? [];
+    allIssues.push(...issues);
+    const total: number = data.total ?? 0;
+    if (issues.length < pageSize || allIssues.length >= total) break;
+    startAt += issues.length;
+    if (page === MAX_PAGES - 1) { truncated = true; break; }
+  }
+
+  const mapped = allIssues.map((i: any) => ({
+    key: i.key,
+    summary: i.fields?.summary,
+    description: i.fields?.description,
+    acceptanceCriteria: acField ? (i.fields?.[acField] ?? null) : null,
+    status: i.fields?.status?.name,
+    priority: i.fields?.priority?.name,
+    issueType: i.fields?.issuetype?.name,
+    labels: i.fields?.labels ?? [],
+    components: (i.fields?.components ?? []).map((c: any) => c.name),
+    epic: i.fields?.parent
+      ? { key: i.fields.parent.key, summary: i.fields.parent.summary ?? i.fields.parent.fields?.summary ?? null }
+      : null,
+    links: (i.fields?.issuelinks ?? []).map((l: any) => ({
+      type: l.type?.name ?? l.type?.inward ?? l.type?.outward ?? 'relates',
+      key: l.inwardIssue?.key ?? l.outwardIssue?.key,
+      summary: l.inwardIssue?.fields?.summary ?? l.outwardIssue?.fields?.summary,
+    })).filter((x: any) => Boolean(x.key)),
+    subtasks: (i.fields?.subtasks ?? []).map((st: any) => ({ key: st.key, summary: st.fields?.summary })),
+    url: `${creds.baseUrl}/browse/${i.key}`,
+  }));
+  return { stories: mapped, truncated };
+}
+
+export async function createTestCase(creds: JiraCredentials, opts: {
+  summary: string;
+  stepsHtml: string;
+  priority?: 'Highest' | 'High' | 'Medium' | 'Low' | 'Lowest';
+  labels?: string[];
+  defaultIssueType?: string;
+  defaultTestCaseLabel?: string;
+}): Promise<{ key: string; url: string }> {
+  const doFetch = await makeFetch(creds);
+  if (!creds.proxyUrl) await assertResolvesToPublicAddress(creds.baseUrl);
+  if (!creds.projectKey) throw new Error('projectKey required to create Jira test cases.');
+  const { stepsHtml } = opts;
+  const stepLines = (stepsHtml ?? '')
+    .split(/<br\s*\/?>|<\/li>/i)
+    .map((s: string) => s.replace(/<[^>]+>/g, '').trim())
+    .filter(Boolean);
+  const stepsNode = stepLines.length > 0
+    ? {
+        type: 'orderedList',
+        content: stepLines.map((t: string) => ({
+          type: 'listItem',
+          content: [{ type: 'paragraph', content: [{ type: 'text', text: t }] }]
+        }))
+      }
+    : { type: 'paragraph', content: [{ type: 'text', text: stepsHtml ?? '' }] };
+  const res = await doFetch(`${creds.baseUrl}/rest/api/3/issue`, {
+    method: 'POST',
+    headers: {
+      Authorization: authHeader(creds),
+      Accept: 'application/json',
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({
+      fields: {
+        project: { key: creds.projectKey },
+        summary: opts.summary,
+        description: {
+          type: 'doc',
+          version: 1,
+          content: [stepsNode],
+        },
+        // 'Test' issuetype requires Xray; falls back to 'Story' if not found (Jira returns 400)
+        issuetype: { name: opts.defaultIssueType ?? 'Test' },
+        priority: { name: opts.priority ?? 'High' },
+        labels: (opts.labels ?? []).map((l) => l.replace(/^@/, '')),
+      },
+    }),
+  });
+
+  if (!res.ok) {
+    const errText = await res.text().catch(() => '');
+    // Xray 'Test' issue type not available — retry as Story
+    if (res.status === 400 && errText.includes('issuetype')) {
+      const retry = await doFetch(`${creds.baseUrl}/rest/api/3/issue`, {
+        method: 'POST',
+        headers: {
+          Authorization: authHeader(creds),
+          Accept: 'application/json',
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+          fields: {
+            project: { key: creds.projectKey },
+            summary: opts.summary,
+            description: {
+              type: 'doc',
+              version: 1,
+              content: [stepsNode],
+            },
+            issuetype: { name: 'Story' },
+            priority: { name: opts.priority ?? 'High' },
+            labels: [...(opts.defaultTestCaseLabel ? [opts.defaultTestCaseLabel] : []), ...(opts.labels ?? []).map((l) => l.replace(/^@/, ''))],
+          },
+        }),
+      });
+      if (!retry.ok) throw new Error(`Jira error: ${retry.status} ${await retry.text().catch(() => '')}`);
+      const d = (await retry.json()) as any;
+      return { key: d.key, url: `${creds.baseUrl}/browse/${d.key}` };
+    }
+    throw new Error(`Jira error: ${res.status} ${errText.slice(0, 200)}`);
+  }
+
+  const created = (await res.json()) as any;
+  return { key: created.key, url: `${creds.baseUrl}/browse/${created.key}` };
+}
+
+/** Free-text search — finds issues that mention a screen URL or name. */
+export async function searchIssues(creds: JiraCredentials, text: string, maxResults?: number) {
+  const doFetch = await makeFetch(creds);
+  if (!creds.proxyUrl) await assertResolvesToPublicAddress(creds.baseUrl);
+  const { getSystemConfig } = await import('@taodigital/core');
+  const jiraCfg = await getSystemConfig('connectors_jira');
+  const resolvedMaxResults = maxResults ?? parseInt(String(jiraCfg?.searchPageSize ?? '10'), 10);
+  const safeText = text.replace(/["\\]/g, ' ').trim();
+  const projectClause = creds.projectKey ? `project = "${(creds.projectKey ?? '').replace(/"/g, '\\"')}" AND ` : '';
+  const jql = `${projectClause}text ~ "${safeText}" ORDER BY updated DESC`;
+  const res = await doFetch(
+    `${creds.baseUrl}/rest/api/3/search?jql=${encodeURIComponent(jql)}&maxResults=${resolvedMaxResults}&fields=summary,status,priority,updated`,
+    { headers: { Authorization: authHeader(creds), Accept: 'application/json' } }
+  );
+  if (!res.ok) throw new Error(`Jira search failed: ${res.status} ${await res.text().catch(() => '')}`);
+  const data = (await res.json()) as any;
+  return (data.issues ?? []).map((i: any) => ({
+    key: i.key,
+    summary: i.fields?.summary,
+    status: i.fields?.status?.name,
+    priority: i.fields?.priority?.name,
+    updated: i.fields?.updated,
+    url: `${creds.baseUrl}/browse/${i.key}`,
+  }));
+}