acdev 1.0.1 → 1.0.3

package/src/config.js

@@ -1,47 +1,58 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { checkClaudeAuth, publicClaudeAuthMethod } from './claude-auth.js';
 import { maskSecret } from './env.js';
+import { checkGhAuth, githubTokenFromEnv, originRemoteInfo } from './gh-auth.js';
 import { normalizeJiraBaseUrl } from './jira.js';
+import {
+  DEFAULT_MODEL,
+  MODEL_OPTIONS,
+  isValidModelId,
+} from './models.js';
 import { dataDir } from './paths.js';
 
-/** Model IDs accepted by the Claude Agent SDK / Claude Code. */
-export const MODEL_OPTIONS = [
-  { id: 'claude-sonnet-5', label: 'Sonnet 5' },
-  { id: 'claude-opus-5', label: 'Opus 5' },
-];
-
-export const DEFAULT_MODEL = 'claude-sonnet-5';
+export { DEFAULT_MODEL, MODEL_OPTIONS } from './models.js';
 
 /** Tool names the agent may be granted via config. */
 export const KNOWN_TOOLS = ['Read', 'Glob', 'Grep', 'Edit', 'Write', 'Bash'];
 
 export const TICKET_SOURCES = /** @type {const} */ (['github', 'jira']);
 
-/** GitHub post-PR actions (issues have no Jira-like workflow statuses). */
-export const GITHUB_AFTER_PR_ACTIONS = /** @type {const} */ ([
+/**
+ * Shared post-PR actions for Jira and GitHub Issues rules.
+ * - Jira `set_status` / `close_issue`: workflow transitions (close → Done-like status).
+ * - GitHub `set_status`: applies a label named after `targetStatus` (no board API).
+ * - Both `add_label`: add the configured label name.
+ */
+export const AFTER_PR_ACTIONS = /** @type {const} */ ([
   'none',
+  'set_status',
   'add_label',
   'close_issue',
 ]);
 
-const ALLOWED_MODELS = new Set(MODEL_OPTIONS.map((m) => m.id));
+/** @deprecated Prefer AFTER_PR_ACTIONS — same vocabulary for both sources. */
+export const GITHUB_AFTER_PR_ACTIONS = AFTER_PR_ACTIONS;
+
 const ALLOWED_TOOLS_SET = new Set(KNOWN_TOOLS);
 const ALLOWED_TICKET_SOURCES = new Set(TICKET_SOURCES);
-const ALLOWED_GITHUB_AFTER_PR_ACTIONS = new Set(GITHUB_AFTER_PR_ACTIONS);
+const ALLOWED_AFTER_PR_ACTIONS = new Set(AFTER_PR_ACTIONS);
+
+/** @typedef {'none' | 'set_status' | 'add_label' | 'close_issue'} AfterPrAction */
+
+const DEFAULT_AFTER_PR_OPENED = {
+  enabled: false,
+  action: /** @type {AfterPrAction} */ ('none'),
+  targetStatus: 'In Review',
+  label: '',
+};
 
 const DEFAULT_JIRA_RULES = {
-  afterPrOpened: {
-    enabled: false,
-    targetStatus: 'In Review',
-  },
+  afterPrOpened: structuredClone(DEFAULT_AFTER_PR_OPENED),
 };
 
 const DEFAULT_GITHUB_RULES = {
-  afterPrOpened: {
-    enabled: false,
-    action: /** @type {'none' | 'add_label' | 'close_issue'} */ ('none'),
-    label: '',
-  },
+  afterPrOpened: structuredClone(DEFAULT_AFTER_PR_OPENED),
 };
 
 const DEFAULTS = {
@@ -60,17 +71,19 @@ const DEFAULTS = {
 };
 
 /**
- * Normalize / validate jiraRules from config or PATCH body.
+ * @param {string} prefix e.g. jiraRules / githubRules
  * @param {unknown} raw
- * @param {{ throwOnInvalid?: boolean }} [opts]
+ * @param {{ throwOnInvalid?: boolean, migrateLegacyJira?: boolean }} [opts]
  * @returns {typeof DEFAULT_JIRA_RULES}
  */
-export function normalizeJiraRules(raw, opts = {}) {
+function normalizeAfterPrRules(prefix, raw, opts = {}) {
   const throwOnInvalid = opts.throwOnInvalid === true;
-  const base = structuredClone(DEFAULT_JIRA_RULES);
+  const base = {
+    afterPrOpened: structuredClone(DEFAULT_AFTER_PR_OPENED),
+  };
   if (raw == null || typeof raw !== 'object' || Array.isArray(raw)) {
     if (throwOnInvalid && raw != null) {
-      throw new Error('jiraRules must be an object');
+      throw new Error(`${prefix} must be an object`);
     }
     return base;
   }
@@ -82,25 +95,40 @@ export function normalizeJiraRules(raw, opts = {}) {
       : {};
 
   if (throwOnInvalid && obj.afterPrOpened != null && (typeof obj.afterPrOpened !== 'object' || Array.isArray(obj.afterPrOpened))) {
-    throw new Error('jiraRules.afterPrOpened must be an object');
+    throw new Error(`${prefix}.afterPrOpened must be an object`);
   }
 
   if (after.enabled !== undefined) {
     if (typeof after.enabled !== 'boolean') {
-      if (throwOnInvalid) throw new Error('jiraRules.afterPrOpened.enabled must be a boolean');
+      if (throwOnInvalid) throw new Error(`${prefix}.afterPrOpened.enabled must be a boolean`);
     } else {
       base.afterPrOpened.enabled = after.enabled;
     }
   }
 
+  if (after.action !== undefined) {
+    if (typeof after.action !== 'string' || !ALLOWED_AFTER_PR_ACTIONS.has(after.action)) {
+      if (throwOnInvalid) {
+        throw new Error(
+          `Invalid ${prefix}.afterPrOpened.action "${after.action}". Allowed: ${AFTER_PR_ACTIONS.join(', ')}`
+        );
+      }
+    } else {
+      base.afterPrOpened.action = /** @type {AfterPrAction} */ (after.action);
+    }
+  } else if (opts.migrateLegacyJira && base.afterPrOpened.enabled) {
+    // Legacy Jira configs only had enabled + targetStatus (implied move status).
+    base.afterPrOpened.action = 'set_status';
+  }
+
   if (after.targetStatus !== undefined) {
     if (typeof after.targetStatus !== 'string') {
-      if (throwOnInvalid) throw new Error('jiraRules.afterPrOpened.targetStatus must be a string');
+      if (throwOnInvalid) throw new Error(`${prefix}.afterPrOpened.targetStatus must be a string`);
     } else {
       const trimmed = after.targetStatus.trim();
       if (!trimmed) {
         if (throwOnInvalid) {
-          throw new Error('jiraRules.afterPrOpened.targetStatus must be a non-empty string');
+          throw new Error(`${prefix}.afterPrOpened.targetStatus must be a non-empty string`);
         }
       } else {
         base.afterPrOpened.targetStatus = trimmed;
@@ -108,58 +136,9 @@ export function normalizeJiraRules(raw, opts = {}) {
     }
   }
 
-  return base;
-}
-
-/**
- * Normalize / validate githubRules from config or PATCH body.
- * @param {unknown} raw
- * @param {{ throwOnInvalid?: boolean }} [opts]
- * @returns {typeof DEFAULT_GITHUB_RULES}
- */
-export function normalizeGithubRules(raw, opts = {}) {
-  const throwOnInvalid = opts.throwOnInvalid === true;
-  const base = structuredClone(DEFAULT_GITHUB_RULES);
-  if (raw == null || typeof raw !== 'object' || Array.isArray(raw)) {
-    if (throwOnInvalid && raw != null) {
-      throw new Error('githubRules must be an object');
-    }
-    return base;
-  }
-  /** @type {Record<string, unknown>} */
-  const obj = /** @type {Record<string, unknown>} */ (raw);
-  const after =
-    obj.afterPrOpened != null && typeof obj.afterPrOpened === 'object' && !Array.isArray(obj.afterPrOpened)
-      ? /** @type {Record<string, unknown>} */ (obj.afterPrOpened)
-      : {};
-
-  if (throwOnInvalid && obj.afterPrOpened != null && (typeof obj.afterPrOpened !== 'object' || Array.isArray(obj.afterPrOpened))) {
-    throw new Error('githubRules.afterPrOpened must be an object');
-  }
-
-  if (after.enabled !== undefined) {
-    if (typeof after.enabled !== 'boolean') {
-      if (throwOnInvalid) throw new Error('githubRules.afterPrOpened.enabled must be a boolean');
-    } else {
-      base.afterPrOpened.enabled = after.enabled;
-    }
-  }
-
-  if (after.action !== undefined) {
-    if (typeof after.action !== 'string' || !ALLOWED_GITHUB_AFTER_PR_ACTIONS.has(after.action)) {
-      if (throwOnInvalid) {
-        throw new Error(
-          `Invalid githubRules.afterPrOpened.action "${after.action}". Allowed: ${GITHUB_AFTER_PR_ACTIONS.join(', ')}`
-        );
-      }
-    } else {
-      base.afterPrOpened.action = /** @type {'none' | 'add_label' | 'close_issue'} */ (after.action);
-    }
-  }
-
   if (after.label !== undefined) {
     if (typeof after.label !== 'string') {
-      if (throwOnInvalid) throw new Error('githubRules.afterPrOpened.label must be a string');
+      if (throwOnInvalid) throw new Error(`${prefix}.afterPrOpened.label must be a string`);
     } else {
       base.afterPrOpened.label = after.label.trim();
     }
@@ -171,12 +150,45 @@ export function normalizeGithubRules(raw, opts = {}) {
     base.afterPrOpened.action === 'add_label' &&
     !base.afterPrOpened.label
   ) {
-    throw new Error('githubRules.afterPrOpened.label is required when action is add_label');
+    throw new Error(`${prefix}.afterPrOpened.label is required when action is add_label`);
+  }
+
+  if (
+    throwOnInvalid &&
+    base.afterPrOpened.enabled &&
+    base.afterPrOpened.action === 'set_status' &&
+    !base.afterPrOpened.targetStatus
+  ) {
+    throw new Error(`${prefix}.afterPrOpened.targetStatus is required when action is set_status`);
   }
 
   return base;
 }
 
+/**
+ * Normalize / validate jiraRules from config or PATCH body.
+ * Legacy `{ enabled, targetStatus }` (no `action`) migrates to `set_status` when enabled.
+ * @param {unknown} raw
+ * @param {{ throwOnInvalid?: boolean }} [opts]
+ * @returns {typeof DEFAULT_JIRA_RULES}
+ */
+export function normalizeJiraRules(raw, opts = {}) {
+  return normalizeAfterPrRules('jiraRules', raw, {
+    ...opts,
+    migrateLegacyJira: true,
+  });
+}
+
+/**
+ * Normalize / validate githubRules from config or PATCH body.
+ * @param {unknown} raw
+ * @param {{ throwOnInvalid?: boolean }} [opts]
+ * @returns {typeof DEFAULT_GITHUB_RULES}
+ */
+export function normalizeGithubRules(raw, opts = {}) {
+  return normalizeAfterPrRules('githubRules', raw, opts);
+}
+
 /**
  * Persist config to `.acdev/config.json`.
  * @param {string} repoRoot
@@ -222,7 +234,7 @@ function positiveInt(value, field) {
 
 /**
  * Load or create `.acdev/config.json` inside the repo root.
- * Unknown / removed model IDs are mapped to {@link DEFAULT_MODEL}.
+ * Empty / malformed model IDs are mapped to {@link DEFAULT_MODEL}.
  * @param {string} repoRoot
  * @returns {typeof DEFAULTS}
  */
@@ -254,9 +266,11 @@ export function loadConfig(repoRoot) {
     githubRules: normalizeGithubRules(raw.githubRules),
   };
 
-  if (!ALLOWED_MODELS.has(config.model)) {
+  if (!isValidModelId(config.model)) {
     config.model = DEFAULT_MODEL;
     saveConfig(repoRoot, persistable(config));
+  } else {
+    config.model = String(config.model).trim();
   }
 
   if (!ALLOWED_TICKET_SOURCES.has(config.ticketSource)) {
@@ -284,12 +298,12 @@ export function loadConfig(repoRoot) {
  */
 export function updateConfig(repoRoot, config, patch) {
   if (patch.model != null) {
-    if (!ALLOWED_MODELS.has(patch.model)) {
+    if (!isValidModelId(patch.model)) {
       throw new Error(
-        `Invalid model "${patch.model}". Allowed: ${[...ALLOWED_MODELS].join(', ')}`
+        `Invalid model "${patch.model}". Expected a non-empty Claude model id`
       );
     }
-    config.model = patch.model;
+    config.model = String(patch.model).trim();
   }
 
   if (patch.baseBranch !== undefined) {
@@ -373,12 +387,18 @@ export function updateConfig(repoRoot, config, patch) {
 
 /**
  * Public-safe config snapshot for the UI / API.
- * Never returns the full Jira API token.
+ * Never returns full secrets (Jira token, GH PAT, Anthropic keys).
  * @param {object} config
- * @param {{ repoRoot?: string }} [opts]
+ * @param {{
+ *   repoRoot?: string,
+ *   ghAuth?: import('./gh-auth.js').GhAuthResult,
+ *   claudeAuth?: import('./claude-auth.js').ClaudeAuthResult,
+ * }} [opts]
  */
 export function publicConfig(config, opts = {}) {
-  const model = ALLOWED_MODELS.has(config.model) ? config.model : DEFAULT_MODEL;
+  const model = isValidModelId(config.model)
+    ? String(config.model).trim()
+    : DEFAULT_MODEL;
   const repoName = opts.repoRoot ? path.basename(opts.repoRoot) : undefined;
   const ticketSource = ALLOWED_TICKET_SOURCES.has(config.ticketSource)
     ? config.ticketSource
@@ -401,6 +421,13 @@ export function publicConfig(config, opts = {}) {
     jiraBaseUrl && jiraEmail && tokenMask.set
   );
 
+  const ghAuth = opts.ghAuth ?? checkGhAuth();
+  const claudeAuth = opts.claudeAuth ?? checkClaudeAuth();
+  const origin = originRemoteInfo(opts.repoRoot);
+  const ghTokenMask = maskSecret(githubTokenFromEnv());
+  const anthropicMask = maskSecret(process.env.ANTHROPIC_API_KEY);
+  const claudeOauthMask = maskSecret(process.env.CLAUDE_CODE_OAUTH_TOKEN);
+
   return {
     model,
     baseBranch: config.baseBranch,
@@ -421,6 +448,19 @@ export function publicConfig(config, opts = {}) {
     jiraApiTokenSet: tokenMask.set,
     jiraApiTokenMasked: tokenMask.masked,
     jiraConfigured,
+    ghAuthOk: ghAuth.ok === true,
+    ghInstalled: Boolean(ghAuth.ghInstalled),
+    ghTokenSet: ghTokenMask.set,
+    ghTokenMasked: ghTokenMask.masked,
+    ghAuthMethod: ghAuth.ok ? ghAuth.method : null,
+    originRemoteUrl: origin.url,
+    originRemoteSsh: origin.ssh,
+    claudeAuthOk: claudeAuth.ok === true,
+    claudeAuthMethod: publicClaudeAuthMethod(claudeAuth),
+    anthropicApiKeySet: anthropicMask.set,
+    anthropicApiKeyMasked: anthropicMask.masked,
+    claudeOauthTokenSet: claudeOauthMask.set,
+    claudeOauthTokenMasked: claudeOauthMask.masked,
     ...(repoName ? { repoName } : {}),
   };
 }

package/src/env.js

@@ -6,7 +6,7 @@ import { dataDir } from './paths.js';
 /**
  * Load environment variables from `.acdev/.env` in the repo root.
  * Existing process.env values take precedence (standard dotenv behavior).
- * Loads ANTHROPIC_*, CLAUDE_*, JIRA_BASE_URL, JIRA_EMAIL, JIRA_API_TOKEN, etc.
+ * Loads ANTHROPIC_*, CLAUDE_*, GH_TOKEN, GITHUB_TOKEN, JIRA_*, etc.
  * @param {string} repoRoot
  */
 export function loadEnv(repoRoot) {

package/src/gh-auth.js

@@ -1,8 +1,25 @@
 import { execFileSync, execSync } from 'node:child_process';
 
+/** @typedef {'token' | 'gh-login'} GhAuthMethod */
+/** @typedef {{
+ *   ok: true,
+ *   ghInstalled: true,
+ *   tokenSet: boolean,
+ *   method: GhAuthMethod,
+ * } | {
+ *   ok: false,
+ *   reason: 'not-found' | 'not-authenticated',
+ *   ghInstalled: boolean,
+ *   tokenSet: boolean,
+ *   method: null,
+ * }} GhAuthResult */
+
 /** @type {() => string | null} */
 let ghBinaryResolver = findGhBinary;
 
+/** @type {() => NodeJS.ProcessEnv} */
+let envResolver = () => process.env;
+
 /** @param {() => string | null} fn */
 export function _setGhBinaryResolver(fn) {
   ghBinaryResolver = fn;
@@ -12,6 +29,15 @@ export function _resetGhBinaryResolver() {
   ghBinaryResolver = findGhBinary;
 }
 
+/** @param {() => NodeJS.ProcessEnv} fn */
+export function _setEnvResolver(fn) {
+  envResolver = fn;
+}
+
+export function _resetEnvResolver() {
+  envResolver = () => process.env;
+}
+
 function findGhBinary() {
   try {
     return execSync('command -v gh', { encoding: 'utf8', shell: true }).trim();
@@ -21,21 +47,112 @@ function findGhBinary() {
 }
 
 /**
- * Verify GitHub CLI is installed and the active github.com account is authenticated.
- * @returns {{ ok: true } | { ok: false, reason: 'not-found' | 'not-authenticated' }}
+ * Token gh honors for github.com API calls (`GH_TOKEN` then `GITHUB_TOKEN`).
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {string}
+ */
+export function githubTokenFromEnv(env = process.env) {
+  return String(env.GH_TOKEN || env.GITHUB_TOKEN || '').trim();
+}
+
+/**
+ * SSH remotes can push/fetch git; they do not authenticate `gh` for issues/PRs.
+ * @param {string | null | undefined} url
+ */
+export function originRemoteLooksSsh(url) {
+  return /^(?:git@|ssh:\/\/)/i.test(String(url || ''));
+}
+
+/**
+ * Read-only origin remote URL (SSH vs HTTPS). SSH is not gh API auth.
+ * @param {string | undefined | null} repoRoot
+ * @returns {{ url: string | null, ssh: boolean }}
+ */
+export function originRemoteInfo(repoRoot) {
+  if (!repoRoot) return { url: null, ssh: false };
+  try {
+    const url = execFileSync('git', ['-C', repoRoot, 'remote', 'get-url', 'origin'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    }).trim();
+    if (!url) return { url: null, ssh: false };
+    return { url, ssh: originRemoteLooksSsh(url) };
+  } catch {
+    return { url: null, ssh: false };
+  }
+}
+
+/**
+ * Verify GitHub CLI is installed and github.com is authenticated.
+ *
+ * Success covers interactive `gh auth login` and a PAT in `GH_TOKEN` /
+ * `GITHUB_TOKEN` (gh reads those env vars). SSH remotes are not checked here.
+ *
+ * @returns {GhAuthResult}
  */
 export function checkGhAuth() {
+  const env = { ...process.env, ...envResolver() };
+  const token = githubTokenFromEnv(env);
+  const tokenSet = Boolean(token);
+  if (token) {
+    env.GH_TOKEN = token;
+  }
+
   const gh = ghBinaryResolver();
   if (!gh) {
-    return { ok: false, reason: 'not-found' };
+    return {
+      ok: false,
+      reason: 'not-found',
+      ghInstalled: false,
+      tokenSet,
+      method: null,
+    };
   }
 
   try {
-    execFileSync(gh, ['auth', 'status', '--hostname', 'github.com', '--active'], {
+    // `--active` refers to stored gh accounts. Env tokens are not "active"
+    // in hosts.yml, so omit it when GH_TOKEN / GITHUB_TOKEN is set.
+    const args = ['auth', 'status', '--hostname', 'github.com'];
+    if (!tokenSet) {
+      args.push('--active');
+    }
+    execFileSync(gh, args, {
       stdio: 'ignore',
+      env,
     });
-    return { ok: true };
+    return {
+      ok: true,
+      ghInstalled: true,
+      tokenSet,
+      method: tokenSet ? 'token' : 'gh-login',
+    };
   } catch {
-    return { ok: false, reason: 'not-authenticated' };
+    return {
+      ok: false,
+      reason: 'not-authenticated',
+      ghInstalled: true,
+      tokenSet,
+      method: null,
+    };
+  }
+}
+
+/**
+ * Human-readable startup error for a failed {@link checkGhAuth}.
+ * @param {GhAuthResult} result
+ */
+export function formatGhAuthError(result) {
+  if (result.reason === 'not-found') {
+    return '✖ GitHub CLI (gh) not found in PATH. Install it from https://cli.github.com/';
   }
+  return [
+    '✖ GitHub CLI is not authenticated for github.com.',
+    '',
+    'Authenticate with one of:',
+    '  1. Interactive (browser/device): gh auth login -h github.com',
+    '  2. Personal access token: Settings → GitHub / PR auth, or set GH_TOKEN in `.acdev/.env`',
+    '  3. Non-interactive CLI: echo YOUR_PAT | gh auth login --with-token -h github.com',
+    '',
+    'SSH remotes can push/fetch git, but do not authenticate gh for issues or PRs.',
+  ].join('\n');
 }

package/src/jira.js

@@ -416,3 +416,174 @@ export async function transitionJiraIssue(key, targetStatusName, creds) {
     statusName: match.to?.name || want,
   };
 }
+
+/** Status names commonly used for “done / closed” when category is unavailable. */
+const CLOSE_STATUS_NAME_HINTS = new Set([
+  'done',
+  'closed',
+  'resolved',
+  'complete',
+  'completed',
+]);
+
+/**
+ * Prefer a transition whose target statusCategory.key is `done`, else a
+ * well-known Done/Closed/Resolved-like status name (case-insensitive).
+ * @param {Array<{
+ *   id?: string,
+ *   name?: string,
+ *   to?: { name?: string, statusCategory?: { key?: string, name?: string } },
+ * }>} transitions
+ * @returns {{ id: string, name?: string, to?: { name?: string } } | null}
+ */
+export function findCloseTransition(transitions) {
+  const list = Array.isArray(transitions) ? transitions : [];
+  for (const t of list) {
+    if (!t || t.id == null) continue;
+    const catKey = String(t.to?.statusCategory?.key || '')
+      .trim()
+      .toLowerCase();
+    if (catKey === 'done') {
+      return /** @type {{ id: string, name?: string, to?: { name?: string } }} */ (t);
+    }
+  }
+  for (const t of list) {
+    if (!t || t.id == null) continue;
+    const toName = String(t.to?.name || '')
+      .trim()
+      .toLowerCase();
+    if (toName && CLOSE_STATUS_NAME_HINTS.has(toName)) {
+      return /** @type {{ id: string, name?: string, to?: { name?: string } }} */ (t);
+    }
+  }
+  return null;
+}
+
+/**
+ * Add a label to a Jira issue (REST update `labels` add op).
+ * @param {string} key
+ * @param {string} label
+ * @param {{
+ *   baseUrl: string,
+ *   email: string,
+ *   apiToken: string,
+ *   fetchFn?: typeof fetch,
+ * }} creds
+ * @returns {Promise<{ ok: true, key: string, label: string }>}
+ */
+export async function addJiraIssueLabel(key, label, creds) {
+  const fetchFn = creds.fetchFn || fetch;
+  const base = normalizeJiraBaseUrl(creds.baseUrl);
+  const normalizedKey = String(key).toUpperCase();
+  const name = String(label || '').trim();
+  if (!name) {
+    throw new Error('Jira label name is required');
+  }
+
+  const headers = {
+    Authorization: jiraAuthHeader({
+      email: creds.email,
+      apiToken: creds.apiToken,
+    }),
+    Accept: 'application/json',
+    'Content-Type': 'application/json',
+  };
+
+  const url = `${base}/rest/api/3/issue/${encodeURIComponent(normalizedKey)}`;
+  const res = await fetchFn(url, {
+    method: 'PUT',
+    headers,
+    body: JSON.stringify({
+      update: {
+        labels: [{ add: name }],
+      },
+    }),
+  });
+
+  if (!res.ok) {
+    const body = await res.text().catch(() => '');
+    const detail = body ? `: ${body.slice(0, 300)}` : '';
+    throw new Error(
+      `Failed to add Jira label "${name}" on ${normalizedKey} (${res.status} ${res.statusText})${detail}`
+    );
+  }
+
+  return { ok: true, key: normalizedKey, label: name };
+}
+
+/**
+ * Close a Jira issue by transitioning to a Done-category (or Done/Closed-like) status.
+ * There is no dedicated “close” REST endpoint; this reuses the transitions API.
+ * @param {string} key
+ * @param {{
+ *   baseUrl: string,
+ *   email: string,
+ *   apiToken: string,
+ *   fetchFn?: typeof fetch,
+ * }} creds
+ * @returns {Promise<{
+ *   ok: true,
+ *   key: string,
+ *   transitionId: string,
+ *   statusName: string,
+ * }>}
+ */
+export async function closeJiraIssue(key, creds) {
+  const fetchFn = creds.fetchFn || fetch;
+  const base = normalizeJiraBaseUrl(creds.baseUrl);
+  const normalizedKey = String(key).toUpperCase();
+
+  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 = findCloseTransition(listData.transitions || []);
+  if (!match) {
+    const available = (listData.transitions || [])
+      .map((t) => t?.to?.name)
+      .filter(Boolean)
+      .join(', ');
+    throw new Error(
+      `No Jira close transition (Done/Closed-like status) 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)}` : '';
+    const statusName = match.to?.name || 'Done';
+    throw new Error(
+      `Failed to close Jira issue ${normalizedKey} via "${statusName}" (${postRes.status} ${postRes.statusText})${detail}`
+    );
+  }
+
+  return {
+    ok: true,
+    key: normalizedKey,
+    transitionId: String(match.id),
+    statusName: match.to?.name || 'Done',
+  };
+}