acdev 1.0.0

package/src/github.js

@@ -0,0 +1,179 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+
+const ISSUE_URL_RE = /github\.com\/([^/]+)\/([^/]+)\/issues\/(\d+)/;
+
+/**
+ * @param {string} issueUrl
+ * @returns {{ owner: string, repo: string, number: number }}
+ */
+export function parseIssueUrl(issueUrl) {
+  const match = issueUrl.match(ISSUE_URL_RE);
+  if (!match) {
+    throw new Error(`Not a recognizable GitHub issue URL: ${issueUrl}`);
+  }
+  const [, owner, repo, number] = match;
+  return { owner, repo, number: Number(number) };
+}
+
+/**
+ * Fetch issue title/body/labels via `gh` for branch naming and type detection.
+ * @param {string} issueUrl
+ * @param {string} cwd
+ * @returns {Promise<{ title: string, body: string, labels: string[] }>}
+ */
+export async function fetchIssueDetails(issueUrl, cwd) {
+  const { stdout } = await execFileAsync(
+    'gh',
+    ['issue', 'view', issueUrl, '--json', 'title,body,labels'],
+    { cwd }
+  );
+  const data = JSON.parse(stdout);
+  const labels = Array.isArray(data.labels)
+    ? data.labels.map((l) => (typeof l === 'string' ? l : l?.name || '')).filter(Boolean)
+    : [];
+  return {
+    title: data.title || '',
+    body: data.body || '',
+    labels,
+  };
+}
+
+/**
+ * Build `gh pr create` argv (without the leading `gh`).
+ * @param {{
+ *   title: string,
+ *   body: string,
+ *   baseBranch: string,
+ *   branchName: string,
+ *   draft?: boolean,
+ * }} params
+ * @returns {string[]}
+ */
+export function buildPrCreateArgs({ title, body, baseBranch, branchName, draft = true }) {
+  const args = ['pr', 'create'];
+  if (draft) {
+    args.push('--draft');
+  }
+  args.push(
+    '--title',
+    title,
+    '--body',
+    body,
+    '--base',
+    baseBranch,
+    '--head',
+    branchName
+  );
+  return args;
+}
+
+/**
+ * Create a GitHub PR (draft or ready for review).
+ * @param {{
+ *   worktreePath: string,
+ *   branchName: string,
+ *   baseBranch: string,
+ *   title: string,
+ *   body: string,
+ *   draft?: boolean,
+ * }} params
+ * @returns {Promise<string>} PR URL
+ */
+export async function createPr({
+  worktreePath,
+  branchName,
+  baseBranch,
+  title,
+  body,
+  draft = true,
+}) {
+  try {
+    const { stdout } = await execFileAsync(
+      'gh',
+      buildPrCreateArgs({ title, body, baseBranch, branchName, draft }),
+      { cwd: worktreePath }
+    );
+    const url = stdout.trim();
+    if (url.startsWith('http')) {
+      return url;
+    }
+    const { stdout: jsonOut } = await execFileAsync(
+      'gh',
+      ['pr', 'view', branchName, '--json', 'url'],
+      { cwd: worktreePath }
+    );
+    return JSON.parse(jsonOut).url;
+  } catch (err) {
+    const message = err.stderr?.toString() || err.message || String(err);
+    if (message.includes('already exists')) {
+      const { stdout } = await execFileAsync(
+        'gh',
+        ['pr', 'view', branchName, '--json', 'url'],
+        { cwd: worktreePath }
+      );
+      return JSON.parse(stdout).url;
+    }
+    throw err;
+  }
+}
+
+/**
+ * Add a label to a GitHub issue via `gh`.
+ * @param {number | string} issueNumber
+ * @param {string} label
+ * @param {string} cwd
+ * @returns {Promise<void>}
+ */
+export async function addIssueLabel(issueNumber, label, cwd) {
+  const n = String(issueNumber);
+  const name = String(label || '').trim();
+  if (!n || !/^\d+$/.test(n)) {
+    throw new Error(`Invalid GitHub issue number: ${issueNumber}`);
+  }
+  if (!name) {
+    throw new Error('Label name is required');
+  }
+  try {
+    await execFileAsync('gh', ['issue', 'edit', n, '--add-label', name], { cwd });
+  } catch (err) {
+    const message = err.stderr?.toString() || err.message || String(err);
+    throw new Error(`Failed to add label "${name}" to issue #${n}: ${message}`);
+  }
+}
+
+/**
+ * Close a GitHub issue via `gh`.
+ * @param {number | string} issueNumber
+ * @param {string} cwd
+ * @returns {Promise<void>}
+ */
+export async function closeIssue(issueNumber, cwd) {
+  const n = String(issueNumber);
+  if (!n || !/^\d+$/.test(n)) {
+    throw new Error(`Invalid GitHub issue number: ${issueNumber}`);
+  }
+  try {
+    await execFileAsync('gh', ['issue', 'close', n], { cwd });
+  } catch (err) {
+    const message = err.stderr?.toString() || err.message || String(err);
+    throw new Error(`Failed to close issue #${n}: ${message}`);
+  }
+}
+
+/**
+ * @deprecated Prefer createPr({ draft: true })
+ * @param {{
+ *   worktreePath: string,
+ *   branchName: string,
+ *   baseBranch: string,
+ *   title: string,
+ *   body: string,
+ * }} params
+ * @returns {Promise<string>} PR URL
+ */
+export async function createDraftPr(params) {
+  return createPr({ ...params, draft: true });
+}

package/src/jira.js

@@ -0,0 +1,418 @@
+/**
+ * Jira Cloud REST API v3 helpers — parse refs, fetch issues, test connection,
+ * map issuetype → feat/fix.
+ */
+
+const JIRA_KEY_RE = /^([A-Z][A-Z0-9]+)-(\d+)$/i;
+const JIRA_BROWSE_RE =
+  /^(?:https?:\/\/)?([^/]+\.atlassian\.net)\/browse\/([A-Z][A-Z0-9]+-\d+)(?:[/?#]|$)/i;
+const JIRA_KEY_IN_TEXT_RE = /\b([A-Z][A-Z0-9]+-\d+)\b/i;
+
+/**
+ * @param {string} baseUrl
+ * @returns {string} normalized origin without trailing slash
+ */
+export function normalizeJiraBaseUrl(baseUrl) {
+  const raw = String(baseUrl || '').trim();
+  if (!raw) {
+    throw new Error('Jira base URL is required');
+  }
+  let withScheme = raw;
+  if (!/^https?:\/\//i.test(withScheme)) {
+    withScheme = `https://${withScheme}`;
+  }
+  let parsed;
+  try {
+    parsed = new URL(withScheme);
+  } catch {
+    throw new Error(`Invalid Jira base URL: ${baseUrl}`);
+  }
+  if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
+    throw new Error(`Invalid Jira base URL: ${baseUrl}`);
+  }
+  return `${parsed.protocol}//${parsed.host}`;
+}
+
+/**
+ * Parse a Jira issue key or browse URL.
+ * Accepts: `PROJ-123`, `https://xxx.atlassian.net/browse/PROJ-123`
+ * @param {string} input
+ * @param {{ baseUrl?: string }} [opts]
+ * @returns {{ key: string, browseUrl: string, host?: string }}
+ */
+export function parseJiraIssueRef(input, opts = {}) {
+  const raw = String(input || '').trim();
+  if (!raw) {
+    throw new Error('Empty Jira issue reference');
+  }
+
+  const browse = raw.match(JIRA_BROWSE_RE);
+  if (browse) {
+    const host = browse[1].toLowerCase();
+    const key = browse[2].toUpperCase();
+    return {
+      key,
+      host,
+      browseUrl: `https://${host}/browse/${key}`,
+    };
+  }
+
+  const keyOnly = raw.match(JIRA_KEY_RE);
+  if (keyOnly) {
+    const key = `${keyOnly[1].toUpperCase()}-${keyOnly[2]}`;
+    let browseUrl = key;
+    if (opts.baseUrl) {
+      const base = normalizeJiraBaseUrl(opts.baseUrl);
+      browseUrl = `${base}/browse/${key}`;
+    }
+    return { key, browseUrl };
+  }
+
+  // Fallback: key embedded in free text / odd URL shapes
+  const embedded = raw.match(JIRA_KEY_IN_TEXT_RE);
+  if (embedded && !raw.includes('github.com')) {
+    const key = embedded[1].toUpperCase();
+    let browseUrl = key;
+    if (opts.baseUrl) {
+      const base = normalizeJiraBaseUrl(opts.baseUrl);
+      browseUrl = `${base}/browse/${key}`;
+    }
+    return { key, browseUrl };
+  }
+
+  throw new Error(`Not a recognizable Jira issue key or URL: ${input}`);
+}
+
+/**
+ * Map Jira issuetype name → branch type.
+ * Bug → fix; Story / Feature / Task / Improvement → feat; else fix (safer).
+ * @param {string | { name?: string } | null | undefined} issueType
+ * @returns {'feat' | 'fix'}
+ */
+export function mapJiraIssueType(issueType) {
+  const name = (
+    typeof issueType === 'string' ? issueType : issueType?.name || ''
+  )
+    .trim()
+    .toLowerCase();
+
+  if (!name) return 'fix';
+  if (name === 'bug' || name === 'defect' || name.includes('bug')) return 'fix';
+
+  const featNames = new Set([
+    'story',
+    'feature',
+    'task',
+    'improvement',
+    'enhancement',
+    'new feature',
+    'epic',
+  ]);
+  if (featNames.has(name)) return 'feat';
+  if (name.includes('feature') || name.includes('story') || name.includes('improvement')) {
+    return 'feat';
+  }
+  return 'fix';
+}
+
+/**
+ * Flatten Atlassian Document Format (ADF) to plain text.
+ * @param {unknown} node
+ * @returns {string}
+ */
+export function adfToPlainText(node) {
+  if (node == null) return '';
+  if (typeof node === 'string') return node;
+  if (typeof node !== 'object') return String(node);
+
+  /** @type {Record<string, unknown>} */
+  const n = /** @type {Record<string, unknown>} */ (node);
+
+  if (Array.isArray(n)) {
+    return n.map((child) => adfToPlainText(child)).join('');
+  }
+
+  const type = n.type;
+  const content = Array.isArray(n.content) ? n.content : [];
+  const text = typeof n.text === 'string' ? n.text : '';
+
+  if (type === 'text') return text;
+
+  const inner = content.map((child) => adfToPlainText(child)).join('');
+
+  if (type === 'hardBreak') return '\n';
+  if (type === 'paragraph' || type === 'heading') return inner ? `${inner}\n\n` : '';
+  if (type === 'bulletList' || type === 'orderedList') return `${inner}\n`;
+  if (type === 'listItem') return `- ${inner.trim()}\n`;
+  if (type === 'codeBlock') return inner ? `\`\`\`\n${inner}\n\`\`\`\n\n` : '';
+  if (type === 'blockquote') return inner ? `> ${inner.trim()}\n\n` : '';
+
+  return inner || text;
+}
+
+/**
+ * @param {{ email: string, apiToken: string }} creds
+ * @returns {string}
+ */
+export function jiraAuthHeader({ email, apiToken }) {
+  const token = Buffer.from(`${email}:${apiToken}`, 'utf8').toString('base64');
+  return `Basic ${token}`;
+}
+
+/**
+ * Resolve Jira credentials from env (and optional overrides).
+ * @param {{
+ *   baseUrl?: string,
+ *   email?: string,
+ *   apiToken?: string,
+ *   configBaseUrl?: string,
+ * }} [opts]
+ * @returns {{ baseUrl: string, email: string, apiToken: string } | { error: string }}
+ */
+export function resolveJiraCredentials(opts = {}) {
+  const baseUrlRaw =
+    opts.baseUrl ||
+    process.env.JIRA_BASE_URL ||
+    opts.configBaseUrl ||
+    '';
+  const email = (opts.email || process.env.JIRA_EMAIL || '').trim();
+  const apiToken = (opts.apiToken || process.env.JIRA_API_TOKEN || '').trim();
+
+  if (!baseUrlRaw.trim()) {
+    return { error: 'Jira base URL is missing. Set JIRA_BASE_URL or configure it in Settings.' };
+  }
+  if (!email) {
+    return { error: 'Jira email is missing. Set JIRA_EMAIL in `.acdev/.env` or Settings.' };
+  }
+  if (!apiToken) {
+    return {
+      error: 'Jira API token is missing. Set JIRA_API_TOKEN in `.acdev/.env` or Settings.',
+    };
+  }
+
+  try {
+    return {
+      baseUrl: normalizeJiraBaseUrl(baseUrlRaw),
+      email,
+      apiToken,
+    };
+  } catch (err) {
+    return { error: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+/**
+ * @param {{
+ *   baseUrl: string,
+ *   email: string,
+ *   apiToken: string,
+ *   fetchFn?: typeof fetch,
+ * }} params
+ * @returns {Promise<{ ok: true, displayName: string, accountId?: string, emailAddress?: string } | { ok: false, error: string }>}
+ */
+export async function testJiraConnection({
+  baseUrl,
+  email,
+  apiToken,
+  fetchFn = fetch,
+}) {
+  const url = `${normalizeJiraBaseUrl(baseUrl)}/rest/api/3/myself`;
+  try {
+    const res = await fetchFn(url, {
+      method: 'GET',
+      headers: {
+        Authorization: jiraAuthHeader({ email, apiToken }),
+        Accept: 'application/json',
+      },
+    });
+    if (!res.ok) {
+      const body = await res.text().catch(() => '');
+      const detail = body ? `: ${body.slice(0, 200)}` : '';
+      return {
+        ok: false,
+        error: `Jira connection failed (${res.status} ${res.statusText})${detail}`,
+      };
+    }
+    const data = await res.json();
+    return {
+      ok: true,
+      displayName: data.displayName || data.emailAddress || email,
+      accountId: data.accountId,
+      emailAddress: data.emailAddress,
+    };
+  } catch (err) {
+    return {
+      ok: false,
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+}
+
+/**
+ * Fetch a Jira issue for agent context + branch naming.
+ * @param {string} key
+ * @param {{
+ *   baseUrl: string,
+ *   email: string,
+ *   apiToken: string,
+ *   fetchFn?: typeof fetch,
+ * }} creds
+ * @returns {Promise<{
+ *   key: string,
+ *   summary: string,
+ *   description: string,
+ *   issueType: string,
+ *   labels: string[],
+ *   comments: Array<{ author: string, body: string, created?: string }>,
+ *   browseUrl: string,
+ * }>}
+ */
+export async function fetchJiraIssue(key, creds) {
+  const fetchFn = creds.fetchFn || fetch;
+  const base = normalizeJiraBaseUrl(creds.baseUrl);
+  const normalizedKey = String(key).toUpperCase();
+  const fields = ['summary', 'description', 'issuetype', 'labels', 'comment'].join(',');
+  const url = `${base}/rest/api/3/issue/${encodeURIComponent(normalizedKey)}?fields=${fields}`;
+
+  const res = await fetchFn(url, {
+    method: 'GET',
+    headers: {
+      Authorization: jiraAuthHeader({
+        email: creds.email,
+        apiToken: creds.apiToken,
+      }),
+      Accept: 'application/json',
+    },
+  });
+
+  if (!res.ok) {
+    const body = await res.text().catch(() => '');
+    const detail = body ? `: ${body.slice(0, 300)}` : '';
+    throw new Error(
+      `Failed to fetch Jira issue ${normalizedKey} (${res.status} ${res.statusText})${detail}`
+    );
+  }
+
+  const data = await res.json();
+  const f = data.fields || {};
+  const issueType =
+    typeof f.issuetype === 'string' ? f.issuetype : f.issuetype?.name || '';
+
+  const commentsRaw = f.comment?.comments || [];
+  const comments = commentsRaw.map((c) => ({
+    author: c.author?.displayName || c.author?.emailAddress || 'unknown',
+    body: adfToPlainText(c.body).trim(),
+    created: c.created,
+  }));
+
+  return {
+    key: data.key || normalizedKey,
+    summary: f.summary || '',
+    description: adfToPlainText(f.description).trim(),
+    issueType,
+    labels: Array.isArray(f.labels) ? f.labels.map(String) : [],
+    comments,
+    browseUrl: `${base}/browse/${data.key || normalizedKey}`,
+  };
+}
+
+/**
+ * Find a transition whose target status name matches (case-insensitive).
+ * @param {Array<{ id?: string, name?: string, to?: { name?: string } }>} transitions
+ * @param {string} targetStatusName
+ * @returns {{ id: string, name?: string, to?: { name?: string } } | null}
+ */
+export function findTransitionByStatusName(transitions, targetStatusName) {
+  const want = String(targetStatusName || '').trim().toLowerCase();
+  if (!want) return null;
+  const list = Array.isArray(transitions) ? transitions : [];
+  for (const t of list) {
+    if (!t || t.id == null) continue;
+    const toName = String(t.to?.name || '').trim().toLowerCase();
+    if (toName && toName === want) {
+      return /** @type {{ id: string, name?: string, to?: { name?: string } }} */ (t);
+    }
+  }
+  return null;
+}
+
+/**
+ * Transition a Jira issue to a status by target status name (best-effort helper).
+ * Lists available transitions, matches `to.name` case-insensitively, then POSTs the id.
+ * @param {string} key
+ * @param {string} targetStatusName
+ * @param {{
+ *   baseUrl: string,
+ *   email: string,
+ *   apiToken: string,
+ *   fetchFn?: typeof fetch,
+ * }} creds
+ * @returns {Promise<{
+ *   ok: true,
+ *   key: string,
+ *   transitionId: string,
+ *   statusName: string,
+ * }>}
+ */
+export async function transitionJiraIssue(key, targetStatusName, creds) {
+  const fetchFn = creds.fetchFn || fetch;
+  const base = normalizeJiraBaseUrl(creds.baseUrl);
+  const normalizedKey = String(key).toUpperCase();
+  const want = String(targetStatusName || '').trim();
+  if (!want) {
+    throw new Error('Jira target status name is required');
+  }
+
+  const headers = {
+    Authorization: jiraAuthHeader({
+      email: creds.email,
+      apiToken: creds.apiToken,
+    }),
+    Accept: 'application/json',
+    'Content-Type': 'application/json',
+  };
+
+  const listUrl = `${base}/rest/api/3/issue/${encodeURIComponent(normalizedKey)}/transitions`;
+  const listRes = await fetchFn(listUrl, { method: 'GET', headers });
+  if (!listRes.ok) {
+    const body = await listRes.text().catch(() => '');
+    const detail = body ? `: ${body.slice(0, 300)}` : '';
+    throw new Error(
+      `Failed to list Jira transitions for ${normalizedKey} (${listRes.status} ${listRes.statusText})${detail}`
+    );
+  }
+
+  const listData = await listRes.json();
+  const match = findTransitionByStatusName(listData.transitions || [], want);
+  if (!match) {
+    const available = (listData.transitions || [])
+      .map((t) => t?.to?.name)
+      .filter(Boolean)
+      .join(', ');
+    throw new Error(
+      `No Jira transition to status "${want}" for ${normalizedKey}` +
+        (available ? ` (available: ${available})` : '')
+    );
+  }
+
+  const postRes = await fetchFn(listUrl, {
+    method: 'POST',
+    headers,
+    body: JSON.stringify({ transition: { id: String(match.id) } }),
+  });
+
+  if (!postRes.ok) {
+    const body = await postRes.text().catch(() => '');
+    const detail = body ? `: ${body.slice(0, 300)}` : '';
+    throw new Error(
+      `Failed to transition Jira issue ${normalizedKey} to "${want}" (${postRes.status} ${postRes.statusText})${detail}`
+    );
+  }
+
+  return {
+    ok: true,
+    key: normalizedKey,
+    transitionId: String(match.id),
+    statusName: match.to?.name || want,
+  };
+}