@aholbreich/agent-skills 0.8.0 → 1.0.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## Unreleased
+
+(empty)
+
+## 0.10.0 - 2026-05-08
+
+Added:
+
+- New `jira-update` skill for dry-run-first Jira Cloud writes through an authenticated browser session: `create`, `comment`, `transition`, `update-fields`, and `link` commands. Markdown-to-ADF conversion by default; ADF passthrough as escape hatch.
+
+Changed:
+
+- Extracted browser/CDP/cookie helpers from all four existing skills into a single source-of-truth `lib/atlassian-browser.js`. Vendored at pack time into each `skills/*/scripts/atlassian-browser.js` so each skill folder remains self-contained on disk. Eliminates ~870 lines of duplicated code across the bundle.
+
+## 0.9.0 - 2026-05-07
+
+Added:
+
+- New `bitbucket-browser-fetch` skill for browser-authenticated Bitbucket Cloud project repository inventory, SSH/HTTPS clone URL lists, Markdown summaries, and safe clone helper scripts.
+
 ## 0.8.0 - 2026-05-07
 
 Added:

package/README.md

@@ -2,15 +2,17 @@
 
 Handcrafted [Agent Skills](https://agentskills.io/) for developer and LLM-wiki workflows. The package is intentionally a pure skills package with broad compatibility across Pi, Claude Code, Codex, OpenClaw/generic `.agents` setups, and other Agent Skills-compatible harnesses.
 
-This repository is a pure skills package. It currently contains browser-authenticated Atlassian fetch/update tools that work well when Jira/Confluence API-token authentication is unavailable because an organization uses Microsoft/SSO.
+This repository is a pure skills package. It currently contains browser-authenticated Atlassian fetch and update tools (Jira read+write, Confluence read+write, Bitbucket read) that work well when Jira/Confluence/Bitbucket API-token authentication is unavailable because an organization uses Microsoft/SSO.
 
 ## Skills
 
 | Skill | Purpose |
 |---|---|
 | [`jira-browser-fetch`](skills/jira-browser-fetch/) | Fetch Jira issue JSON, rendered HTML/XML, linked/referenced issues, Jira Software board backlogs, JQL result sets, and attachments through an authenticated Chrome session. |
+| [`jira-update`](skills/jira-update/) | Dry-run-first Jira Cloud writes through an authenticated browser session: create issues, add comments, transition workflows, update fields, and link issues. Markdown-to-ADF conversion by default; ADF passthrough as escape hatch. |
 | [`confluence-browser-fetch`](skills/confluence-browser-fetch/) | Fetch Confluence page JSON, storage/view HTML, browser HTML, descendants, CQL result sets, and attachments through an authenticated Chrome session. |
 | [`confluence-update`](skills/confluence-update/) | Dry-run-first Confluence page updates, agent-owned block replacement, Markdown-to-storage conversion, and page creation through an authenticated browser session. |
+| [`bitbucket-browser-fetch`](skills/bitbucket-browser-fetch/) | Fetch Bitbucket Cloud project repository inventories and clone URL lists through an authenticated browser session. |
 
 ## Compatibility
 
@@ -175,8 +177,10 @@ If installed globally via npm, the package exposes:
 ```bash
 agent-skills
 jira-browser-fetch
+jira-update
 confluence-browser-fetch
 confluence-update
+bitbucket-browser-fetch
 ```
 
 ## Reuse one Atlassian browser login
@@ -188,7 +192,17 @@ export ATLASSIAN_CHROME_PROFILE="$HOME/.local/share/atlassian-browser-fetch-chro
 export ATLASSIAN_CHROME_DEBUG_PORT=9223
 ```
 
-Skill-specific variables such as `JIRA_CHROME_PROFILE` or `CONFLUENCE_CHROME_PROFILE` still override the shared profile when needed.
+Skill-specific variables such as `JIRA_CHROME_PROFILE`, `CONFLUENCE_CHROME_PROFILE`, or `BITBUCKET_CHROME_PROFILE` still override the shared profile when needed.
+
+## Bitbucket examples
+
+Fetch all repositories in a Bitbucket project and write SSH clone URL lists:
+
+```bash
+bitbucket-browser-fetch \
+  'https://bitbucket.org/myneva/workspace/projects/SWI' \
+  --raw-dir ./raw
+```
 
 ## Confluence update examples
 
@@ -269,6 +283,54 @@ Example user requests that should invoke this skill:
 - "Pull my assigned Jira issues without asking me for an API token."
 - "Use this JQL and store the raw Jira evidence under the wiki raw folder."
 
+## Jira update examples
+
+Dry-run an issue creation from a manifest:
+
+```bash
+jira-update create \
+  --server https://example.atlassian.net \
+  --file ./new-bug.json
+```
+
+Apply after review:
+
+```bash
+jira-update create \
+  --server https://example.atlassian.net \
+  --file ./new-bug.json \
+  --apply
+```
+
+Add a comment from Markdown:
+
+```bash
+jira-update comment PROJ-123 \
+  --server https://example.atlassian.net \
+  --file ./reply.md \
+  --apply
+```
+
+Transition with a comment:
+
+```bash
+jira-update transition PROJ-123 \
+  --server https://example.atlassian.net \
+  --to "In Progress" \
+  --comment-file ./status.md \
+  --apply
+```
+
+Link two issues:
+
+```bash
+jira-update link PROJ-123 \
+  --server https://example.atlassian.net \
+  --to PROJ-456 \
+  --type blocks \
+  --apply
+```
+
 ## Confluence examples
 
 Fetch one page by URL:

package/SECURITY.md

@@ -2,16 +2,16 @@
 
 ## Read this before installing or running
 
-These skills are local automation tools. They can fetch potentially sensitive Jira and Confluence data into your filesystem, and `confluence-update` can write to Confluence when explicitly run with `--apply`.
+These skills are local automation tools. They can fetch potentially sensitive Jira, Confluence, and Bitbucket data into your filesystem, and `confluence-update` can write to Confluence when explicitly run with `--apply`.
 
 ## Browser authentication model
 
-The Jira and Confluence browser tools:
+The Jira, Confluence, and Bitbucket browser tools:
 
 1. launch or reuse a Chromium-compatible browser with a dedicated local profile,
 2. let you complete normal Atlassian SSO in the browser,
 3. read Atlassian cookies through the local Chrome DevTools protocol,
-4. verify those cookies represent an authenticated Jira/Confluence REST session,
+4. verify those cookies represent an authenticated Jira/Confluence/Bitbucket session,
 5. call Atlassian REST endpoints with those cookies.
 
 They do **not** require you to paste API tokens or cookies into chat.
@@ -20,7 +20,7 @@ They do **not** require you to paste API tokens or cookies into chat.
 
 - Do not paste Atlassian cookies, API tokens, passwords, or session headers into prompts, issues, logs, or commits.
 - Treat everything under `raw/` as confidential unless you know it is public.
-- Do not commit fetched Jira/Confluence exports, update audit files, or attachments to a public repository.
+- Do not commit fetched Jira/Confluence/Bitbucket exports, update audit files, clone URL lists, or attachments to a public repository.
 - Review generated `attachments.json` manifests before sharing; they may contain private URLs and filenames.
 - Chrome remote debugging is configured for `127.0.0.1`; do not expose it to a network interface.
 - Use dedicated browser profiles for fetch automation. If reusing SSO between Jira and Confluence, share only a dedicated automation profile via `ATLASSIAN_CHROME_PROFILE`, not your everyday browser profile.

package/bin/vendor.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const repoRoot = path.resolve(__dirname, '..');
+const source = path.join(repoRoot, 'lib/atlassian-browser.js');
+const skillsDir = path.join(repoRoot, 'skills');
+
+if (!fs.existsSync(source)) {
+  console.error(`vendor: source not found at ${source}`);
+  process.exit(1);
+}
+
+const content = fs.readFileSync(source);
+const skills = fs.readdirSync(skillsDir, { withFileTypes: true }).filter(d => d.isDirectory());
+for (const skill of skills) {
+  const scriptsDir = path.join(skillsDir, skill.name, 'scripts');
+  if (!fs.existsSync(scriptsDir)) continue;
+  const dest = path.join(scriptsDir, 'atlassian-browser.js');
+  fs.writeFileSync(dest, content);
+  console.log(`vendored -> ${path.relative(repoRoot, dest)}`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aholbreich/agent-skills",
-  "version": "0.8.0",
+  "version": "1.0.0",
   "description": "Handcrafted Agent Skills for browser-authenticated Jira and Confluence ingestion, LLM wiki workflows, and developer automation.",
   "license": "MIT",
   "type": "commonjs",
@@ -38,10 +38,14 @@
     "agent-skills": "bin/agent-skills.js",
     "jira-browser-fetch": "skills/jira-browser-fetch/scripts/jira-browser-fetch.js",
     "confluence-browser-fetch": "skills/confluence-browser-fetch/scripts/confluence-browser-fetch.js",
-    "confluence-update": "skills/confluence-update/scripts/confluence-update.js"
+    "confluence-update": "skills/confluence-update/scripts/confluence-update.js",
+    "bitbucket-browser-fetch": "skills/bitbucket-browser-fetch/scripts/bitbucket-browser-fetch.js",
+    "jira-update": "skills/jira-update/scripts/jira-update.js"
   },
   "scripts": {
-    "check": "node --check bin/agent-skills.js && node --check skills/jira-browser-fetch/scripts/jira-browser-fetch.js && node --check skills/jira-browser-fetch/scripts/lib.js && node --check skills/confluence-browser-fetch/scripts/confluence-browser-fetch.js && node --check skills/confluence-browser-fetch/scripts/lib.js && node --check skills/confluence-update/scripts/confluence-update.js && node --check skills/confluence-update/scripts/lib.js",
+    "vendor": "node bin/vendor.js",
+    "check": "node --check bin/agent-skills.js && node --check bin/vendor.js && node --check lib/atlassian-browser.js && npm run vendor && node --check skills/jira-browser-fetch/scripts/jira-browser-fetch.js && node --check skills/jira-browser-fetch/scripts/lib.js && node --check skills/jira-browser-fetch/scripts/atlassian-browser.js && node --check skills/confluence-browser-fetch/scripts/confluence-browser-fetch.js && node --check skills/confluence-browser-fetch/scripts/lib.js && node --check skills/confluence-browser-fetch/scripts/atlassian-browser.js && node --check skills/confluence-update/scripts/confluence-update.js && node --check skills/confluence-update/scripts/lib.js && node --check skills/confluence-update/scripts/atlassian-browser.js && node --check skills/bitbucket-browser-fetch/scripts/bitbucket-browser-fetch.js && node --check skills/bitbucket-browser-fetch/scripts/lib.js && node --check skills/bitbucket-browser-fetch/scripts/atlassian-browser.js && node --check skills/jira-update/scripts/jira-update.js && node --check skills/jira-update/scripts/lib.js && node --check skills/jira-update/scripts/atlassian-browser.js",
+    "pretest": "npm run vendor",
     "test": "node --test",
     "ci": "npm run check && npm test && npm pack --dry-run",
     "pack:dry": "npm pack --dry-run",

package/skills/bitbucket-browser-fetch/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: bitbucket-browser-fetch
+description: Fetch Bitbucket Cloud project repository inventory through an authenticated browser session when API tokens/app passwords are unavailable, especially with Atlassian SSO. Use to list repositories in a Bitbucket workspace project and produce JSON, Markdown, SSH clone URL lists, HTTPS clone URL lists, and a safe clone helper script.
+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.
+---
+
+# Bitbucket Browser Fetch
+
+Use this skill when a user wants all repositories in a Bitbucket Cloud project inventoried through an authenticated browser session. This is useful when Bitbucket app passwords/API tokens are unavailable or inconvenient because the organization uses Atlassian SSO.
+
+The script opens/reuses Chrome with a dedicated profile, lets the user complete Bitbucket login once, extracts Bitbucket cookies via Chrome DevTools, verifies project access, and fetches the repository list using Bitbucket's browser/internal API.
+
+## Safety
+
+- Never ask the user to paste Bitbucket cookies, app passwords, or API tokens into chat.
+- The skill is read-only and does not clone repositories itself.
+- It writes clone URL lists and a helper script; review before executing any clone script.
+- Treat repository names/URLs as potentially confidential.
+
+## Script
+
+```bash
+scripts/bitbucket-browser-fetch.js <PROJECT_URL> [options]
+```
+
+Important options:
+
+```bash
+--workspace NAME   override workspace parsed from URL
+--project KEY      override project key parsed from URL
+--raw-dir DIR      output raw directory
+--pagelen N        internal API page size, default 100
+--wait SEC         SSO/session wait timeout
+--port PORT        Chrome DevTools port
+--profile-dir DIR  Chrome profile dir
+```
+
+## Example
+
+```bash
+scripts/bitbucket-browser-fetch.js \
+  'https://bitbucket.org/myneva/workspace/projects/SWI' \
+  --raw-dir ./raw
+```
+
+## Output
+
+```text
+raw/bitbucket/<workspace>/projects/<project-key>/
+├── repositories.json
+├── repositories.md
+├── clone-ssh.txt
+├── clone-https.txt
+├── clone-ssh.sh
+├── bitbucket-browser-fetch-run.json
+└── pages/
+    └── repositories-page-1.json
+```
+
+Agents should normally use `repositories.json` for metadata and `clone-ssh.txt` for selective checkout with normal Git SSH credentials.
+
+## References
+
+- [Usage reference](references/usage.md)
+- [Distribution guide](references/distribution.md)

package/skills/bitbucket-browser-fetch/references/distribution.md

@@ -0,0 +1,25 @@
+# Bitbucket Browser Fetch Distribution
+
+This skill is distributed as part of `@aholbreich/agent-skills`.
+
+Directory layout:
+
+```text
+bitbucket-browser-fetch/
+├── SKILL.md
+├── references/
+│   ├── distribution.md
+│   └── usage.md
+└── scripts/
+    ├── bitbucket-browser-fetch.js
+    └── lib.js
+```
+
+Use directly by path or install a convenience symlink:
+
+```bash
+mkdir -p ~/.local/bin
+ln -sf ~/.pi/agent/skills/bitbucket-browser-fetch/scripts/bitbucket-browser-fetch.js ~/.local/bin/bitbucket-browser-fetch
+```
+
+The package exposes a `bitbucket-browser-fetch` npm bin when installed globally.

package/skills/bitbucket-browser-fetch/references/usage.md

@@ -0,0 +1,84 @@
+# Bitbucket Browser Fetch Usage
+
+## Why Browser Fetch?
+
+Bitbucket Cloud organizations often rely on Atlassian SSO. Browser fetch avoids pasted secrets by:
+
+1. Launching/reusing a dedicated Chromium-compatible browser profile.
+2. Letting the user complete normal Bitbucket/Atlassian login in the browser.
+3. Reading Bitbucket cookies through local Chrome DevTools.
+4. Verifying access to the requested Bitbucket project.
+5. Calling Bitbucket's browser/internal API to list project repositories.
+
+The official `api.bitbucket.org/2.0` API does not reliably accept browser cookies, so this skill uses the same internal API the Bitbucket UI uses for project repository lists.
+
+## Common Command
+
+```bash
+scripts/bitbucket-browser-fetch.js \
+  'https://bitbucket.org/myneva/workspace/projects/SWI' \
+  --raw-dir ./raw
+```
+
+## Output Files
+
+For `https://bitbucket.org/myneva/workspace/projects/SWI`:
+
+```text
+raw/bitbucket/myneva/projects/SWI/
+├── repositories.json              # normalized machine-readable inventory
+├── repositories.md                # human/LLM-friendly table
+├── clone-ssh.txt                  # one SSH git clone URL per line
+├── clone-https.txt                # one HTTPS git clone URL per line
+├── clone-ssh.sh                   # safe helper script; not executed automatically
+├── bitbucket-browser-fetch-run.json
+└── pages/
+    ├── repositories-page-1.json   # raw Bitbucket internal API responses
+    └── repositories-page-2.json
+```
+
+## Agent Checkout Workflow
+
+The skill does not clone automatically. After reviewing the output, agents can selectively clone with normal Git SSH credentials:
+
+```bash
+mkdir -p repos
+while read -r url; do
+  name="$(basename "$url" .git)"
+  [ -d "repos/$name/.git" ] && echo "SKIP $name" && continue
+  git clone "$url" "repos/$name"
+done < raw/bitbucket/myneva/projects/SWI/clone-ssh.txt
+```
+
+Or run the generated helper script after review:
+
+```bash
+raw/bitbucket/myneva/projects/SWI/clone-ssh.sh repos
+```
+
+## Environment Variables
+
+| Variable | Meaning |
+|---|---|
+| `BITBUCKET_RAW_DIR` | Default output raw directory |
+| `BITBUCKET_CHROME_DEBUG_PORT` | Chrome DevTools port; overrides `ATLASSIAN_CHROME_DEBUG_PORT` |
+| `ATLASSIAN_CHROME_DEBUG_PORT` | Shared DevTools port for Atlassian browser tools |
+| `BITBUCKET_CHROME_PROFILE` | Dedicated Chrome profile dir; overrides `ATLASSIAN_CHROME_PROFILE` |
+| `ATLASSIAN_CHROME_PROFILE` | Shared browser profile dir for Atlassian tools |
+| `BITBUCKET_FETCH_WAIT_SEC` | Wait timeout, default `900` |
+| `BITBUCKET_PAGELEN` | Internal API page size, default `100` |
+| `CHROME` / `CHROMIUM` | Browser executable path override |
+
+## Troubleshooting
+
+### Project not found / no access
+
+Complete Bitbucket/Atlassian login in the opened browser and confirm you can view the project URL manually.
+
+### Official API returns empty but UI shows repositories
+
+Expected in SSO/browser-cookie mode. This skill intentionally uses Bitbucket's browser/internal API.
+
+### Git clone fails
+
+Browser authentication and Git authentication are separate. Configure SSH keys or Git credentials for Bitbucket before cloning.

package/skills/bitbucket-browser-fetch/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,
+};