@aholbreich/agent-skills 0.9.0 → 1.0.0

package/skills/jira-update/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: jira-update
+description: Safely create or update Jira Cloud issues through an authenticated browser session when API tokens do not work, especially with Microsoft/SSO. Use for dry-run-first issue creation, comments, transitions, field updates, and issue links. Markdown-to-ADF conversion by default; ADF passthrough as escape hatch.
+license: MIT
+compatibility: Agent Skills standard. Tested with Pi; installable into Claude Code, Codex, OpenClaw/generic .agents skills directories. Requires Node.js 22+ with built-in fetch/WebSocket and a Chromium-compatible browser with remote debugging (Chrome, Chromium, Brave, Edge, or Vivaldi). No npm dependencies.
+---
+
+# Jira Update
+
+Use this skill when a coding agent needs to write to Jira Cloud through the same browser-authenticated flow used by the fetchers. Dry-run is the default; `--apply` is required for any write.
+
+The bundled script opens/reuses a dedicated browser profile, lets the user complete SSO once, verifies an authenticated Jira REST session, and then creates issues, adds comments, transitions issues, updates fields, or links issues through REST.
+
+## Safety
+
+- Never ask the user to paste Jira cookies or API tokens into chat.
+- Dry-run first. Require explicit user approval before adding `--apply`.
+- Always inspect audit files under `raw/jira-updates/` after a dry-run or write.
+- `update-fields` does NOT detect concurrent edits. Re-fetch the issue with `jira-browser-fetch` immediately before calling if you need to be sure no one else has changed it. The audit dir always contains `before.issue.json` for forensic recovery.
+- Treat issue content as confidential.
+
+## Script
+
+```bash
+scripts/jira-update.js <command> [options]
+```
+
+Commands:
+
+```bash
+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
+```
+
+Common options:
+
+```bash
+--server URL              Jira base URL (or set JIRA_SERVER), e.g. https://example.atlassian.net
+--file FILE               Input file (JSON manifest for create/update-fields, Markdown/ADF for comment)
+--representation REP      markdown | adf (default: markdown). Applies to comment.
+--raw-dir DIR             Audit dir (default: ./raw)
+--apply                   Actually write. Without this, only dry-run/audit files are written
+--message TEXT            Annotate the local audit record (not sent to Jira)
+--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
+```
+
+Command-specific options:
+
+```bash
+transition: --to NAME | --to-id ID, --comment-file FILE, --field key=value (repeatable)
+link:       --to ISSUE-KEY, --type "blocks" | "relates" | etc.
+```
+
+## Typical Workflow
+
+1. Run without `--apply` first.
+2. Review files in `raw/jira-updates/<command>-<key|new>-<timestamp>/`.
+3. Ask the user for approval.
+4. Re-run the same command with `--apply`.
+5. To share one Atlassian SSO login with the fetchers, set `ATLASSIAN_CHROME_PROFILE` and `ATLASSIAN_CHROME_DEBUG_PORT`.
+
+## Examples
+
+Dry-run an issue creation from a Markdown-rich manifest:
+
+```bash
+scripts/jira-update.js create \
+  --server https://example.atlassian.net \
+  --file ./new-bug.json
+```
+
+Apply after review:
+
+```bash
+scripts/jira-update.js create \
+  --server https://example.atlassian.net \
+  --file ./new-bug.json \
+  --apply
+```
+
+Add a comment from Markdown:
+
+```bash
+scripts/jira-update.js comment PROJ-123 \
+  --server https://example.atlassian.net \
+  --file ./reply.md \
+  --apply
+```
+
+Transition with a comment:
+
+```bash
+scripts/jira-update.js transition PROJ-123 \
+  --server https://example.atlassian.net \
+  --to "In Progress" \
+  --comment-file ./status.md \
+  --apply
+```
+
+## Output Layout
+
+```text
+raw/jira-updates/<command>-<key|new>-<timestamp>/
+├── before.issue.json         # existing issue for comment/transition/update-fields/link
+├── proposed.payload.json     # exact REST body that would be sent
+├── proposed.adf.json         # rendered ADF if Markdown conversion happened
+├── transitions.json          # transition: snapshot of available transitions
+├── linktypes.json            # link: resolved link-type record
+├── after.issue.json          # post-apply only
+└── update-run.json           # command metadata
+```
+
+## References
+
+- [Usage reference](references/usage.md)
+- [Distribution guide](references/distribution.md)

package/skills/jira-update/references/distribution.md

@@ -0,0 +1,5 @@
+# jira-update — Distribution
+
+Bundled with the `@aholbreich/agent-skills` npm package and Pi skills bundle. Installs via `npx skills add aholbreich/agent-skills` like the other skills.
+
+The skill folder is self-contained — `lib/atlassian-browser.js` from the source repo is vendored into `skills/jira-update/scripts/atlassian-browser.js` at pack time, so individual installations of just this skill work.

package/skills/jira-update/references/usage.md

@@ -0,0 +1,75 @@
+# jira-update — Usage Reference
+
+This skill writes to Jira Cloud through an authenticated browser session.
+
+## Commands
+
+### `create`
+
+Creates a new issue. Input is a JSON manifest with optional Markdown description.
+
+Example manifest (`new-bug.json`):
+
+```json
+{
+  "project": "PROJ",
+  "issueType": "Bug",
+  "summary": "Login fails on Safari 17",
+  "description": "## Steps to reproduce\n\n1. Open the login page\n2. ...",
+  "descriptionRepresentation": "markdown",
+  "labels": ["bug", "browser"],
+  "assignee": "accountId:5b10ac8d82e05b22cc7d4ef5",
+  "priority": "High",
+  "fields": { "components": [{"name": "frontend"}] }
+}
+```
+
+Top-level convenience keys map to standard Jira fields. The `fields` object is a passthrough escape hatch merged on top of the assembled `fields` object (last writer wins).
+
+`descriptionRepresentation` accepts `markdown` (default; converted by the skill) or `adf` (in which case `description` must be a valid ADF document).
+
+### `comment`
+
+Adds a comment. Default representation is `markdown`.
+
+```bash
+jira-update comment PROJ-123 --file reply.md
+```
+
+### `transition`
+
+Moves an issue through a workflow.
+
+```bash
+jira-update transition PROJ-123 --to "In Progress"
+jira-update transition PROJ-123 --to-id 31 --comment-file done.md
+jira-update transition PROJ-123 --to "Done" --field resolution=Fixed
+```
+
+### `update-fields`
+
+Partial field update.
+
+```bash
+jira-update update-fields PROJ-123 --file changes.json
+```
+
+`changes.json`:
+
+```json
+{ "fields": { "summary": "...", "labels": ["x", "y"] } }
+```
+
+No concurrency guard. Re-fetch with `jira-browser-fetch` first if drift matters.
+
+### `link`
+
+Links two issues.
+
+```bash
+jira-update link PROJ-123 --to PROJ-456 --type blocks
+```
+
+## Audit dir
+
+Every command writes to `raw/jira-updates/<command>-<key|new>-<timestamp>/`. Always review before running with `--apply`.

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,
+};