@aholbreich/agent-skills 0.8.0 → 1.0.0

package/skills/jira-update/scripts/atlassian-browser.js

@@ -0,0 +1,261 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawn } = require('node:child_process');
+
+const sleep = ms => new Promise(r => setTimeout(r, ms));
+
+function isExecutable(file) {
+  try { fs.accessSync(file, fs.constants.X_OK); return true; } catch { return false; }
+}
+
+function resolveBrowserCandidate(candidate) {
+  if (!candidate) return null;
+  if (candidate.includes(path.sep)) return isExecutable(candidate) ? candidate : null;
+  for (const dir of String(process.env.PATH || '').split(path.delimiter)) {
+    if (!dir) continue;
+    const full = path.join(dir, candidate);
+    if (isExecutable(full)) return full;
+  }
+  return null;
+}
+
+function findBrowserExecutable() {
+  const candidates = [
+    process.env.CHROME,
+    process.env.CHROMIUM,
+    'google-chrome',
+    'google-chrome-stable',
+    'chromium',
+    'chromium-browser',
+    'brave-browser',
+    'brave',
+    'microsoft-edge',
+    'microsoft-edge-stable',
+    'vivaldi',
+    'vivaldi-stable',
+    '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+    '/Applications/Chromium.app/Contents/MacOS/Chromium',
+    '/Applications/Brave Browser.app/Contents/MacOS/Brave Browser',
+    '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
+    '/Applications/Vivaldi.app/Contents/MacOS/Vivaldi',
+  ];
+  for (const candidate of candidates) {
+    const resolved = resolveBrowserCandidate(candidate);
+    if (resolved) return resolved;
+  }
+  throw new Error('Could not find a Chromium-compatible browser. Install Chrome/Chromium/Brave/Edge/Vivaldi or set CHROME=/path/to/browser.');
+}
+
+function connectCdp(wsUrl) {
+  return new Promise((resolve, reject) => {
+    const ws = new WebSocket(wsUrl);
+    let id = 0;
+    const pending = new Map();
+    const failTimer = setTimeout(() => reject(new Error('CDP websocket timeout')), 10000);
+
+    ws.addEventListener('open', () => {
+      clearTimeout(failTimer);
+      resolve({
+        send(method, params = {}) {
+          return new Promise((res, rej) => {
+            const msgId = ++id;
+            pending.set(msgId, { res, rej });
+            ws.send(JSON.stringify({ id: msgId, method, params }));
+          });
+        },
+        close() { try { ws.close(); } catch {} },
+      });
+    });
+
+    ws.addEventListener('message', ev => {
+      let data = ev.data;
+      if (typeof data !== 'string') data = Buffer.from(data).toString('utf8');
+      const msg = JSON.parse(data);
+      if (!msg.id || !pending.has(msg.id)) return;
+      const { res, rej } = pending.get(msg.id);
+      pending.delete(msg.id);
+      if (msg.error) rej(new Error(`${msg.error.message || 'CDP error'} ${JSON.stringify(msg.error)}`));
+      else res(msg.result);
+    });
+
+    ws.addEventListener('error', err => reject(err));
+  });
+}
+
+function createBrowserSession({ port, profileDir, waitSec, serverHost, verifySession, cookieUrls, userAgent }) {
+  if (!serverHost) throw new Error('createBrowserSession requires serverHost');
+  if (typeof verifySession !== 'function') throw new Error('createBrowserSession requires verifySession callback');
+  const ua = userAgent || 'agent-skills/1.0';
+
+  async function endpoint(pathname) {
+    const res = await fetch(`http://127.0.0.1:${port}${pathname}`);
+    if (!res.ok) throw new Error(`DevTools HTTP ${res.status} for ${pathname}`);
+    return res.json();
+  }
+
+  async function devtoolsReady() {
+    try { await endpoint('/json/version'); return true; } catch { return false; }
+  }
+
+  async function waitDevtools() {
+    for (let i = 0; i < 80; i++) {
+      if (await devtoolsReady()) return;
+      await sleep(250);
+    }
+    throw new Error('Chrome DevTools endpoint did not start');
+  }
+
+  async function openDevtoolsTab(url) {
+    if (!url) return false;
+    const endpointUrl = `http://127.0.0.1:${port}/json/new?${encodeURIComponent(url)}`;
+    for (const init of [{ method: 'PUT' }, {}]) {
+      try {
+        const res = await fetch(endpointUrl, init);
+        if (res.ok) { await sleep(500); return true; }
+      } catch {}
+    }
+    return false;
+  }
+
+  async function hasDevtoolsTabForHost(url, pathPrefix) {
+    if (!url) return false;
+    const host = new URL(url).host;
+    const list = await endpoint('/json/list');
+    return list.some(t => t.type === 'page' && t.url && (() => {
+      try {
+        const tabUrl = new URL(t.url);
+        if (tabUrl.host !== host) return false;
+        if (pathPrefix && !tabUrl.pathname.startsWith(pathPrefix)) return false;
+        return true;
+      } catch { return false; }
+    })());
+  }
+
+  function launchChrome(url) {
+    const browser = findBrowserExecutable();
+    const args = [
+      `--remote-debugging-port=${port}`,
+      '--remote-debugging-address=127.0.0.1',
+      '--remote-allow-origins=*',
+      `--user-data-dir=${profileDir}`,
+      '--no-first-run',
+      '--no-default-browser-check',
+      url,
+    ];
+    console.log(`Launching browser: ${browser}`);
+    const child = spawn(browser, args, { detached: true, stdio: 'ignore' });
+    child.on('error', err => console.error(`Failed to launch browser ${browser}: ${err.message}`));
+    child.unref();
+  }
+
+  async function ensureBrowser(openUrl, { tabPathPrefix } = {}) {
+    if (!(await devtoolsReady())) {
+      console.log(`Opening Chromium-compatible browser with reusable profile: ${profileDir}`);
+      launchChrome(openUrl);
+    } else {
+      console.log(`Reusing Chrome DevTools on port ${port}`);
+      if (openUrl) {
+        const hasTab = await hasDevtoolsTabForHost(openUrl, tabPathPrefix);
+        if (hasTab) {
+          console.log(`Found existing tab for ${new URL(openUrl).host}; not opening another tab.`);
+        } else {
+          const opened = await openDevtoolsTab(openUrl);
+          if (opened) console.log(`Opened target URL in reused browser: ${openUrl}`);
+          else console.warn('Could not open target URL through DevTools; continuing with existing tabs.');
+        }
+      }
+    }
+    await waitDevtools();
+  }
+
+  async function getPageWsUrl() {
+    const list = await endpoint('/json/list');
+    const pages = list.filter(t => t.type === 'page' && t.webSocketDebuggerUrl);
+    const preferred = pages.find(t => (t.url || '').includes(serverHost)) || pages[0];
+    return preferred && preferred.webSocketDebuggerUrl;
+  }
+
+  async function getCookieHeader() {
+    const wsUrl = await getPageWsUrl();
+    if (!wsUrl) return '';
+    const cdp = await connectCdp(wsUrl);
+    try {
+      await cdp.send('Network.enable');
+      const urls = (cookieUrls && cookieUrls.length) ? cookieUrls : [`https://${serverHost}/`];
+      const result = await cdp.send('Network.getCookies', { urls });
+      const cookies = (result.cookies || [])
+        .filter(c => c.domain && (c.domain === serverHost || c.domain.endsWith(`.${serverHost}`)))
+        .map(c => `${c.name}=${c.value}`);
+      return cookies.join('; ');
+    } finally {
+      cdp.close();
+    }
+  }
+
+  async function fetchText(url, cookie, options = {}) {
+    const method = options.method || 'GET';
+    const headers = {
+      Cookie: cookie,
+      Accept: options.accept || '*/*',
+      'User-Agent': ua,
+    };
+    if (options.body !== undefined && options.body !== null) headers['Content-Type'] = options.contentType || 'application/json';
+    const res = await fetch(url, { method, redirect: 'follow', headers, body: options.body ?? null });
+    return { status: res.status, contentType: res.headers.get('content-type') || '', text: await res.text() };
+  }
+
+  async function fetchJson(url, cookie, options = {}) {
+    const result = await fetchText(url, cookie, { ...options, accept: options.accept || 'application/json' });
+    let json = null;
+    try { json = JSON.parse(result.text); } catch {}
+    return { ...result, json };
+  }
+
+  async function getCookieWithWait(openUrl, { tabPathPrefix } = {}) {
+    await ensureBrowser(openUrl, { tabPathPrefix });
+    console.log(`If prompted in Chrome, complete SSO for: ${openUrl}`);
+    const deadline = Date.now() + waitSec * 1000;
+    let last = '';
+    while (Date.now() < deadline) {
+      try {
+        const cookie = await getCookieHeader();
+        const result = await verifySession(cookie);
+        if (result && result.ok) {
+          if (process.stdout.isTTY) process.stdout.write('\n');
+          console.log(`Authenticated session verified${result.url ? ` via ${result.url}` : ''}`);
+          return cookie;
+        }
+        last = (result && result.message) || 'session not yet verified';
+      } catch (e) { last = e.message; }
+      if (process.stdout.isTTY) {
+        process.stdout.write(`\r${new Date().toLocaleTimeString()} ${last.padEnd(120).slice(0, 120)}`);
+      }
+      await sleep(3000);
+    }
+    if (process.stdout.isTTY) process.stdout.write('\n');
+    throw new Error(`Could not verify authenticated session. Last result: ${last}`);
+  }
+
+  return {
+    devtoolsReady,
+    waitDevtools,
+    openDevtoolsTab,
+    hasDevtoolsTabForHost,
+    launchChrome,
+    ensureBrowser,
+    getPageWsUrl,
+    getCookieHeader,
+    getCookieWithWait,
+    fetchText,
+    fetchJson,
+  };
+}
+
+module.exports = {
+  createBrowserSession,
+  findBrowserExecutable,
+  resolveBrowserCandidate,
+  connectCdp,
+};

package/skills/jira-update/scripts/jira-update.js

@@ -0,0 +1,404 @@
+#!/usr/bin/env node
+'use strict';
+
+const fsp = require('node:fs/promises');
+const os = require('node:os');
+const path = require('node:path');
+const { createBrowserSession } = require('./atlassian-browser');
+const lib = require('./lib');
+
+function topUsage() {
+  console.log(`Usage: jira-update <command> [options]
+
+Commands:
+  create                       Create a new issue from a JSON manifest
+  comment ISSUE-KEY            Add a comment
+  transition ISSUE-KEY         Move through workflow
+  update-fields ISSUE-KEY      Partial field update
+  link FROM-KEY                Link two issues
+
+Run "jira-update <command> --help" for command-specific options.
+Dry-run is the default; --apply is required to write.
+
+Common options:
+  --server URL          Jira base URL (or JIRA_SERVER), e.g. https://example.atlassian.net
+  --raw-dir DIR         Audit directory (default: ./raw)
+  --apply               Actually write to Jira
+  --message TEXT        Annotate the local audit record
+  --wait SEC            Wait time for SSO/session (default: 900)
+  --port PORT           Chrome DevTools port (default: 9225 or ATLASSIAN_CHROME_DEBUG_PORT)
+  --profile-dir DIR     Chrome profile dir
+`);
+}
+
+const opts = {
+  command: '',
+  issueKey: '',
+  server: process.env.JIRA_SERVER || '',
+  rawDir: process.env.JIRA_UPDATE_RAW_DIR || process.env.JIRA_RAW_DIR || path.resolve(process.cwd(), 'raw'),
+  port: Number(process.env.JIRA_CHROME_DEBUG_PORT || process.env.ATLASSIAN_CHROME_DEBUG_PORT || 9225),
+  waitSec: Number(process.env.JIRA_UPDATE_WAIT_SEC || 900),
+  profileDir: process.env.JIRA_CHROME_PROFILE || process.env.ATLASSIAN_CHROME_PROFILE || path.join(os.homedir(), '.local/share/jira-browser-fetch-chrome'),
+  file: '',
+  representation: 'markdown',
+  apply: false,
+  message: '',
+  to: '',
+  toId: '',
+  commentFile: '',
+  fieldOverrides: {},
+  linkType: '',
+};
+
+const args = process.argv.slice(2);
+if (!args.length || args[0] === '-h' || args[0] === '--help') { topUsage(); process.exit(0); }
+
+opts.command = args.shift();
+if (!['create', 'comment', 'transition', 'update-fields', 'link'].includes(opts.command)) {
+  console.error(`Unknown command: ${opts.command}`);
+  topUsage();
+  process.exit(2);
+}
+
+if (['comment', 'transition', 'update-fields', 'link'].includes(opts.command)) {
+  if (!args.length || args[0].startsWith('-')) {
+    console.error(`${opts.command} requires an issue key as the first argument.`);
+    process.exit(2);
+  }
+  opts.issueKey = args.shift();
+}
+
+for (let i = 0; i < args.length; i++) {
+  const a = args[i];
+  if (a === '--server') opts.server = args[++i];
+  else if (a === '--raw-dir') opts.rawDir = args[++i];
+  else if (a === '--file') opts.file = args[++i];
+  else if (a === '--representation') opts.representation = args[++i];
+  else if (a === '--apply') opts.apply = true;
+  else if (a === '--message') opts.message = args[++i];
+  else if (a === '--wait') opts.waitSec = Number(args[++i]);
+  else if (a === '--port') opts.port = Number(args[++i]);
+  else if (a === '--profile-dir') opts.profileDir = args[++i];
+  else if (a === '--to') opts.to = args[++i];
+  else if (a === '--to-id') opts.toId = args[++i];
+  else if (a === '--comment-file') opts.commentFile = args[++i];
+  else if (a === '--field') {
+    const kv = args[++i] || '';
+    const eq = kv.indexOf('=');
+    if (eq === -1) { console.error(`--field expects key=value, got: ${kv}`); process.exit(2); }
+    opts.fieldOverrides[kv.slice(0, eq)] = kv.slice(eq + 1);
+  }
+  else if (a === '--type') opts.linkType = args[++i];
+  else { console.error(`Unknown argument: ${a}`); process.exit(2); }
+}
+
+opts.server = opts.server.replace(/\/$/, '');
+opts.rawDir = path.resolve(opts.rawDir);
+
+if (!opts.server) {
+  console.error('Missing Jira server. Pass --server https://example.atlassian.net or set JIRA_SERVER.');
+  process.exit(2);
+}
+
+let session = null;
+function getSession() {
+  if (session) return session;
+  session = createBrowserSession({
+    port: opts.port,
+    profileDir: opts.profileDir,
+    waitSec: opts.waitSec,
+    serverHost: new URL(opts.server).host,
+    cookieUrls: [`${opts.server}/`],
+    userAgent: 'jira-update/1.0',
+    verifySession: cookie => verifyJiraSession(cookie),
+  });
+  return session;
+}
+
+async function verifyJiraSession(cookie) {
+  if (!cookie) return { ok: false, message: 'no Atlassian cookies yet' };
+  const probes = [`${opts.server}/rest/api/3/myself`, `${opts.server}/rest/api/2/myself`];
+  for (const url of probes) {
+    const result = await getSession().fetchJson(url, cookie, { accept: 'application/json' });
+    if (result.status === 200 && result.json && (result.json.accountId || result.json.name || result.json.displayName)) return { ok: true, url };
+    if (result.status === 401 || result.status === 403) return { ok: false, message: `not authenticated yet (${result.status} from ${url})` };
+    if (result.status === 302 || result.status === 303) return { ok: false, message: `still redirected to login (${result.status} from ${url})` };
+    if (result.status === 404) continue;
+    return { ok: false, message: `session probe HTTP ${result.status} from ${url}` };
+  }
+  return { ok: false, message: 'could not verify Jira session' };
+}
+
+function safeName(s) {
+  return String(s || 'item').replace(/[\\/\0]/g, '_').replace(/^\.+$/, '_').slice(0, 120);
+}
+
+async function makeRunDir(label) {
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const dir = path.join(opts.rawDir, 'jira-updates', `${safeName(label)}-${stamp}`);
+  await fsp.mkdir(dir, { recursive: true });
+  return dir;
+}
+
+async function writeAudit(dir, manifestRecord, files) {
+  for (const [name, content] of Object.entries(files)) await fsp.writeFile(path.join(dir, name), content);
+  await fsp.writeFile(path.join(dir, 'update-run.json'), JSON.stringify(manifestRecord, null, 2));
+}
+
+async function postJson(url, cookie, body) {
+  return getSession().fetchJson(url, cookie, { method: 'POST', body: JSON.stringify(body) });
+}
+
+async function putJson(url, cookie, body) {
+  return getSession().fetchJson(url, cookie, { method: 'PUT', body: JSON.stringify(body) });
+}
+
+async function getJson(url, cookie) {
+  return getSession().fetchJson(url, cookie, { accept: 'application/json' });
+}
+
+async function runCreate() {
+  if (!opts.file) { console.error('create requires --file FILE.'); process.exit(2); }
+  const raw = await fsp.readFile(path.resolve(opts.file), 'utf8');
+  const manifest = JSON.parse(raw);
+  const payload = lib.buildCreatePayload(manifest);
+
+  const dir = await makeRunDir(`create-${manifest.project || 'unknown'}`);
+  const record = {
+    command: 'create',
+    dryRun: !opts.apply,
+    server: opts.server,
+    project: manifest.project,
+    issueType: manifest.issueType,
+    summary: manifest.summary,
+    message: opts.message || undefined,
+    auditDir: dir,
+  };
+  const files = {
+    'proposed.payload.json': JSON.stringify(payload, null, 2),
+  };
+  if (payload.fields.description && payload.fields.description.type === 'doc') {
+    files['proposed.adf.json'] = JSON.stringify(payload.fields.description, null, 2);
+  }
+  await writeAudit(dir, record, files);
+
+  console.log(`${opts.apply ? 'Applying' : 'Dry-run'} create: ${manifest.project} / ${manifest.issueType} / "${manifest.summary}"`);
+  console.log(`Audit files: ${dir}`);
+  if (!opts.apply) {
+    console.log('Dry-run only. Re-run with --apply to write to Jira.');
+    return;
+  }
+
+  const browseUrl = `${opts.server}/issues/?jql=project=${encodeURIComponent(manifest.project)}`;
+  const cookie = await getSession().getCookieWithWait(browseUrl);
+  const result = await postJson(`${opts.server}/rest/api/3/issue`, cookie, payload);
+  if (result.status !== 201 || !result.json || !result.json.key) {
+    throw new Error(`Create failed HTTP ${result.status}: ${(result.text || '').slice(0, 500).replace(/\s+/g, ' ')}`);
+  }
+  await fsp.writeFile(path.join(dir, 'after.issue.json'), JSON.stringify(result.json, null, 2));
+  console.log(`Created issue ${result.json.key} (${result.json.id})`);
+}
+
+async function runComment() {
+  if (!opts.file) { console.error('comment requires --file FILE.'); process.exit(2); }
+  const raw = await fsp.readFile(path.resolve(opts.file), 'utf8');
+  const body = lib.renderDescription(raw, opts.representation);
+  const payload = { body };
+
+  const dir = await makeRunDir(`comment-${opts.issueKey}`);
+  const record = {
+    command: 'comment',
+    dryRun: !opts.apply,
+    server: opts.server,
+    issueKey: opts.issueKey,
+    representation: opts.representation,
+    message: opts.message || undefined,
+    auditDir: dir,
+  };
+  await writeAudit(dir, record, {
+    'proposed.payload.json': JSON.stringify(payload, null, 2),
+    'proposed.adf.json': JSON.stringify(body, null, 2),
+  });
+
+  console.log(`${opts.apply ? 'Applying' : 'Dry-run'} comment on ${opts.issueKey}`);
+  console.log(`Audit files: ${dir}`);
+  if (!opts.apply) {
+    console.log('Dry-run only. Re-run with --apply to write to Jira.');
+    return;
+  }
+
+  const browseUrl = `${opts.server}/browse/${opts.issueKey}`;
+  const cookie = await getSession().getCookieWithWait(browseUrl);
+  const result = await postJson(`${opts.server}/rest/api/3/issue/${opts.issueKey}/comment`, cookie, payload);
+  if (result.status !== 201 || !result.json || !result.json.id) {
+    throw new Error(`Comment failed HTTP ${result.status}: ${(result.text || '').slice(0, 500).replace(/\s+/g, ' ')}`);
+  }
+  await fsp.writeFile(path.join(dir, 'after.issue.json'), JSON.stringify(result.json, null, 2));
+  console.log(`Added comment ${result.json.id} on ${opts.issueKey}`);
+}
+
+async function runTransition() {
+  if (!opts.to && !opts.toId) { console.error('transition requires --to NAME or --to-id ID.'); process.exit(2); }
+  const browseUrl = `${opts.server}/browse/${opts.issueKey}`;
+  const cookie = await getSession().getCookieWithWait(browseUrl);
+
+  const transitionsResp = await getJson(`${opts.server}/rest/api/3/issue/${opts.issueKey}/transitions`, cookie);
+  if (transitionsResp.status !== 200 || !transitionsResp.json) {
+    throw new Error(`Could not list transitions for ${opts.issueKey}. HTTP ${transitionsResp.status}`);
+  }
+  const transition = lib.resolveTransition(transitionsResp.json, opts.toId ? { id: opts.toId } : { name: opts.to });
+
+  let commentBody = null;
+  if (opts.commentFile) {
+    const raw = await fsp.readFile(path.resolve(opts.commentFile), 'utf8');
+    commentBody = lib.renderDescription(raw, opts.representation);
+  }
+  const payload = lib.buildTransitionPayload({
+    transitionId: transition.id,
+    commentBody,
+    fields: opts.fieldOverrides,
+  });
+
+  const before = await getJson(`${opts.server}/rest/api/3/issue/${opts.issueKey}?fields=status,summary`, cookie);
+  const dir = await makeRunDir(`transition-${opts.issueKey}`);
+  const record = {
+    command: 'transition',
+    dryRun: !opts.apply,
+    server: opts.server,
+    issueKey: opts.issueKey,
+    transition,
+    fieldOverrides: opts.fieldOverrides,
+    message: opts.message || undefined,
+    auditDir: dir,
+  };
+  await writeAudit(dir, record, {
+    'before.issue.json': JSON.stringify(before.json || {}, null, 2),
+    'transitions.json': JSON.stringify(transitionsResp.json, null, 2),
+    'proposed.payload.json': JSON.stringify(payload, null, 2),
+  });
+
+  console.log(`${opts.apply ? 'Applying' : 'Dry-run'} transition ${opts.issueKey} -> "${transition.name}" (id ${transition.id})`);
+  console.log(`Audit files: ${dir}`);
+  if (!opts.apply) {
+    console.log('Dry-run only. Re-run with --apply to write to Jira.');
+    return;
+  }
+  const result = await postJson(`${opts.server}/rest/api/3/issue/${opts.issueKey}/transitions`, cookie, payload);
+  if (result.status !== 204) {
+    throw new Error(`Transition failed HTTP ${result.status}: ${(result.text || '').slice(0, 500).replace(/\s+/g, ' ')}`);
+  }
+  const after = await getJson(`${opts.server}/rest/api/3/issue/${opts.issueKey}?fields=status,summary`, cookie);
+  await fsp.writeFile(path.join(dir, 'after.issue.json'), JSON.stringify(after.json || {}, null, 2));
+  console.log(`Transitioned ${opts.issueKey} to "${transition.name}"`);
+}
+
+async function runUpdateFields() {
+  if (!opts.file) { console.error('update-fields requires --file FILE.'); process.exit(2); }
+  const raw = await fsp.readFile(path.resolve(opts.file), 'utf8');
+  const manifest = JSON.parse(raw);
+  if (!manifest.fields || typeof manifest.fields !== 'object') {
+    console.error('update-fields manifest must have a "fields" object.');
+    process.exit(2);
+  }
+  const payload = { fields: manifest.fields };
+
+  const dir = await makeRunDir(`update-fields-${opts.issueKey}`);
+  const record = {
+    command: 'update-fields',
+    dryRun: !opts.apply,
+    server: opts.server,
+    issueKey: opts.issueKey,
+    fieldKeys: Object.keys(manifest.fields),
+    message: opts.message || undefined,
+    auditDir: dir,
+  };
+
+  if (!opts.apply) {
+    await writeAudit(dir, record, {
+      'proposed.payload.json': JSON.stringify(payload, null, 2),
+    });
+    console.log(`Dry-run update-fields on ${opts.issueKey}: ${Object.keys(manifest.fields).join(', ')}`);
+    console.log(`Audit files: ${dir}`);
+    console.log('Dry-run only. Re-run with --apply to write to Jira.');
+    console.log('Note: update-fields does NOT detect concurrent edits. Re-fetch with jira-browser-fetch first if drift matters.');
+    return;
+  }
+
+  const browseUrl = `${opts.server}/browse/${opts.issueKey}`;
+  const cookie = await getSession().getCookieWithWait(browseUrl);
+  const before = await getJson(`${opts.server}/rest/api/3/issue/${opts.issueKey}`, cookie);
+  await writeAudit(dir, record, {
+    'before.issue.json': JSON.stringify(before.json || {}, null, 2),
+    'proposed.payload.json': JSON.stringify(payload, null, 2),
+  });
+  console.log(`Applying update-fields on ${opts.issueKey}: ${Object.keys(manifest.fields).join(', ')}`);
+  console.log(`Audit files: ${dir}`);
+
+  const result = await putJson(`${opts.server}/rest/api/3/issue/${opts.issueKey}`, cookie, payload);
+  if (result.status !== 204) {
+    throw new Error(`update-fields failed HTTP ${result.status}: ${(result.text || '').slice(0, 500).replace(/\s+/g, ' ')}`);
+  }
+  const after = await getJson(`${opts.server}/rest/api/3/issue/${opts.issueKey}`, cookie);
+  await fsp.writeFile(path.join(dir, 'after.issue.json'), JSON.stringify(after.json || {}, null, 2));
+  console.log(`Updated ${opts.issueKey}`);
+}
+
+async function runLink() {
+  if (!opts.to) { console.error('link requires --to ISSUE-KEY.'); process.exit(2); }
+  if (!opts.linkType) { console.error('link requires --type "blocks" (or any link type name/inward/outward).'); process.exit(2); }
+  const browseUrl = `${opts.server}/browse/${opts.issueKey}`;
+  const cookie = await getSession().getCookieWithWait(browseUrl);
+
+  const typesResp = await getJson(`${opts.server}/rest/api/3/issueLinkType`, cookie);
+  if (typesResp.status !== 200 || !typesResp.json) {
+    throw new Error(`Could not list link types. HTTP ${typesResp.status}`);
+  }
+  const linkType = lib.resolveLinkType(typesResp.json, opts.linkType);
+  const payload = lib.buildLinkPayload({ from: opts.issueKey, to: opts.to, linkType });
+
+  const dir = await makeRunDir(`link-${opts.issueKey}-${opts.to}`);
+  const record = {
+    command: 'link',
+    dryRun: !opts.apply,
+    server: opts.server,
+    fromKey: opts.issueKey,
+    toKey: opts.to,
+    linkType,
+    message: opts.message || undefined,
+    auditDir: dir,
+  };
+  await writeAudit(dir, record, {
+    'linktypes.json': JSON.stringify(typesResp.json, null, 2),
+    'proposed.payload.json': JSON.stringify(payload, null, 2),
+  });
+
+  console.log(`${opts.apply ? 'Applying' : 'Dry-run'} link ${opts.issueKey} ${linkType.outward} ${opts.to}`);
+  console.log(`Audit files: ${dir}`);
+  if (!opts.apply) {
+    console.log('Dry-run only. Re-run with --apply to write to Jira.');
+    return;
+  }
+  const result = await postJson(`${opts.server}/rest/api/3/issueLink`, cookie, payload);
+  if (result.status !== 201 && result.status !== 200) {
+    throw new Error(`link failed HTTP ${result.status}: ${(result.text || '').slice(0, 500).replace(/\s+/g, ' ')}`);
+  }
+  console.log(`Linked ${opts.issueKey} ${linkType.outward} ${opts.to}`);
+}
+
+async function main() {
+  await fsp.mkdir(opts.rawDir, { recursive: true });
+  switch (opts.command) {
+    case 'create': return runCreate();
+    case 'comment': return runComment();
+    case 'transition': return runTransition();
+    case 'update-fields': return runUpdateFields();
+    case 'link': return runLink();
+    default:
+      throw new Error(`Unhandled command: ${opts.command}`);
+  }
+}
+
+main().catch(err => {
+  console.error(`\nERROR: ${err.stack || err.message}`);
+  process.exit(1);
+});