@aholbreich/agent-skills 0.1.0

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

@@ -0,0 +1,109 @@
+---
+name: jira-browser-fetch
+description: Fetch Jira issue raw data through an authenticated Chrome browser session when jira-cli/API tokens do not work, especially with Microsoft/SSO. Use to archive Jira issues, linked tickets, rendered HTML/XML, remote links, and attachments into a raw wiki folder.
+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 Google Chrome/Chromium with remote debugging. No npm dependencies.
+---
+
+# Jira Browser Fetch
+
+Use this skill when Jira API-token authentication fails or the organization uses Microsoft/SSO and the user wants Jira issues archived into a local raw/wiki folder.
+
+The bundled script opens/reuses Chrome with a dedicated profile, lets the user complete SSO once, extracts Jira cookies via Chrome DevTools, and fetches Jira REST/HTML/XML/attachments into a raw directory.
+
+## Safety
+
+- Never ask the user to paste Jira cookies or API tokens into chat.
+- Prefer the browser automation flow because secrets remain in the local Chrome profile.
+- Treat fetched issue data and attachments as potentially confidential.
+- Do not update/transition/edit Jira issues with this skill; it is read-only.
+
+## Script
+
+```bash
+scripts/jira-browser-fetch.js ISSUE-KEY [options]
+```
+
+Important options:
+
+```bash
+--server URL       Jira base URL, e.g. https://example.atlassian.net
+--raw-dir DIR      folder where ISSUE-KEY/ directories are created
+--connected        fetch connected/referenced tickets too
+--depth N          recursion depth for connected tickets
+--scan-text        find issue keys in JSON/XML/HTML text, not only formal Jira links
+--jql JQL          search Jira with JQL and fetch all matching issues
+--assignee-me      fetch all issues assigned to current Jira user
+--max-attachment-size S  skip attachment files larger than S (default 5mb; use unlimited to disable)
+--prefix A,B,C     only follow keys with these project prefixes
+--wait SEC         SSO/session wait timeout per issue
+```
+
+## Typical Workflow
+
+1. Identify raw directory.
+2. Run the script and show the command first.
+3. If Chrome opens, ask the user to complete SSO in that browser window.
+4. Verify saved files.
+
+Example:
+
+```bash
+scripts/jira-browser-fetch.js \
+  SWING-4770 \
+  --server https://example.atlassian.net \
+  --raw-dir ./raw \
+  --connected \
+  --scan-text \
+  --prefix SWING,SSD,EC \
+  --depth 1
+
+# Fetch requested issues plus everything assigned to current user:
+scripts/jira-browser-fetch.js \
+  SWING-4611 SWING-4621 \
+  --server https://example.atlassian.net \
+  --raw-dir ./raw \
+  --assignee-me
+```
+
+## Output Layout
+
+For each issue:
+
+```text
+raw/ISSUE-KEY/
+├── issue.json           # Jira REST issue with renderedFields,names,schema,changelog
+├── issue.html           # Browser issue page HTML
+├── issue.xml            # Jira XML issue view
+├── remotelinks.json     # Jira remote links endpoint
+├── connected-keys.json  # Connected/referenced issue keys detected
+├── metadata.json        # Fetch metadata
+├── attachments.json     # Attachment manifest, including skipped large-file references
+└── attachments/         # Downloaded attachments under max-size threshold
+```
+
+A run manifest is written to:
+
+```text
+raw/jira-browser-fetch-run.json
+```
+
+## Installation / PATH
+
+The skill can be used directly by path. Optionally install a convenience symlink:
+
+```bash
+mkdir -p ~/.local/bin
+ln -sf ~/.pi/agent/skills/jira-browser-fetch/scripts/jira-browser-fetch.js ~/.local/bin/jira-browser-fetch
+```
+
+Then use:
+
+```bash
+jira-browser-fetch SWING-4770 --raw-dir ./raw --connected
+```
+
+## References
+
+- [Usage reference](references/usage.md)
+- [Distribution guide](references/distribution.md)

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

@@ -0,0 +1,124 @@
+# Distribution Guide
+
+This skill follows Pi / Agent Skills layout:
+
+```text
+jira-browser-fetch/
+├── SKILL.md
+├── scripts/
+│   └── jira-browser-fetch.js
+└── references/
+    ├── usage.md
+    └── distribution.md
+```
+
+## Install for Current User
+
+Copy the whole directory to Pi's global skill location:
+
+```bash
+mkdir -p ~/.pi/agent/skills
+cp -a jira-browser-fetch ~/.pi/agent/skills/
+```
+
+Pi discovers it automatically on next start.
+
+Optional command symlink:
+
+```bash
+mkdir -p ~/.local/bin
+ln -sf ~/.pi/agent/skills/jira-browser-fetch/scripts/jira-browser-fetch.js ~/.local/bin/jira-browser-fetch
+```
+
+## Install in a Project Repository
+
+For a repo-local skill:
+
+```bash
+mkdir -p .pi/skills
+cp -a jira-browser-fetch .pi/skills/
+```
+
+Commit it:
+
+```bash
+git add .pi/skills/jira-browser-fetch
+git commit -m "Add Jira browser fetch Pi skill"
+```
+
+Anyone using Pi inside that repository gets the skill automatically.
+
+## Distribute as a Tarball
+
+From the parent directory:
+
+```bash
+tar -czf jira-browser-fetch-skill.tar.gz jira-browser-fetch
+```
+
+Install from tarball:
+
+```bash
+mkdir -p ~/.pi/agent/skills
+tar -xzf jira-browser-fetch-skill.tar.gz -C ~/.pi/agent/skills
+```
+
+## Distribute as a Git Repository
+
+Create a repo with the skill directory as content or as `skills/jira-browser-fetch`.
+
+Consumers can either copy it:
+
+```bash
+git clone <repo-url>
+cp -a <repo>/jira-browser-fetch ~/.pi/agent/skills/
+```
+
+or reference it in Pi settings if they keep a checkout:
+
+```json
+{
+  "skills": ["/path/to/repo/jira-browser-fetch"]
+}
+```
+
+## npm/package.json Distribution
+
+Pi can discover package skills from `skills/` directories or `pi.skills` entries in `package.json`.
+
+Example package layout:
+
+```text
+my-pi-skills/
+├── package.json
+└── skills/
+    └── jira-browser-fetch/
+        ├── SKILL.md
+        ├── scripts/jira-browser-fetch.js
+        └── references/
+```
+
+Minimal `package.json`:
+
+```json
+{
+  "name": "my-pi-skills",
+  "version": "1.0.0",
+  "private": true,
+  "pi": {
+    "skills": ["skills/jira-browser-fetch"]
+  }
+}
+```
+
+## Validation Checklist
+
+- Directory name matches `name` in `SKILL.md`: `jira-browser-fetch`.
+- `SKILL.md` has required `name` and `description` frontmatter.
+- Scripts use relative paths in docs.
+- No secrets, cookies, or tokens are committed.
+- Script is executable:
+
+```bash
+chmod +x scripts/jira-browser-fetch.js
+```

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

@@ -0,0 +1,138 @@
+# Jira Browser Fetch Usage
+
+## Why Browser Fetch?
+
+Some Jira Cloud organizations use Microsoft/SSO and block or break API-token Basic auth. The browser fetcher avoids this by:
+
+1. Launching Chrome with a dedicated user profile.
+2. Letting the user complete normal SSO in Chrome.
+3. Reading Jira cookies through the local Chrome DevTools protocol.
+4. Calling Jira REST endpoints with those cookies.
+
+No token or cookie needs to be pasted into chat.
+
+## Requirements
+
+- Linux/macOS with Chrome or Chromium.
+- Node.js 22+.
+- Network access to the Jira site.
+
+Check:
+
+```bash
+node --version
+which google-chrome || which chromium || which chromium-browser
+```
+
+If Chrome has a different path:
+
+```bash
+CHROME=/path/to/chrome scripts/jira-browser-fetch.js PROJ-123
+```
+
+## Common Commands
+
+Fetch one issue:
+
+```bash
+scripts/jira-browser-fetch.js PROJ-123 \
+  --server https://example.atlassian.net \
+  --raw-dir /path/to/wiki/raw
+```
+
+Fetch one issue and formal Jira links/subtasks/parents:
+
+```bash
+scripts/jira-browser-fetch.js PROJ-123 \
+  --server https://example.atlassian.net \
+  --raw-dir /path/to/wiki/raw \
+  --connected \
+  --depth 1
+```
+
+Fetch issue keys mentioned in comments/descriptions/rendered HTML too:
+
+```bash
+scripts/jira-browser-fetch.js PROJ-123 \
+  --server https://example.atlassian.net \
+  --raw-dir /path/to/wiki/raw \
+  --connected \
+  --scan-text \
+  --prefix PROJ,HELPDESK \
+  --depth 1
+```
+
+Fetch all issues assigned to the current browser-authenticated Jira user:
+
+```bash
+scripts/jira-browser-fetch.js \
+  --server https://example.atlassian.net \
+  --raw-dir /path/to/wiki/raw \
+  --assignee-me
+```
+
+Fetch any JQL result set:
+
+```bash
+scripts/jira-browser-fetch.js \
+  --server https://example.atlassian.net \
+  --raw-dir /path/to/wiki/raw \
+  --jql "assignee = currentUser() AND statusCategory != Done ORDER BY updated DESC"
+```
+
+Use a shorter wait when the browser session is already logged in:
+
+```bash
+JIRA_FETCH_WAIT_SEC=15 scripts/jira-browser-fetch.js PROJ-123 --raw-dir ./raw
+```
+
+Skip attachment downloads above a threshold while still recording references in `attachments.json`:
+
+```bash
+scripts/jira-browser-fetch.js PROJ-123 --raw-dir ./raw --max-attachment-size 10mb
+```
+
+Default max attachment download size is `5mb`. Use `--max-attachment-size unlimited` to download all attachments.
+
+## Environment Variables
+
+| Variable | Meaning |
+|---|---|
+| `JIRA_SERVER` | Default Jira base URL |
+| `JIRA_RAW_DIR` | Default output raw directory |
+| `JIRA_CHROME_DEBUG_PORT` | Chrome DevTools port, default `9223` |
+| `JIRA_FETCH_WAIT_SEC` | Wait timeout per issue, default `900` |
+| `JIRA_MAX_SEARCH_RESULTS` | Max issues added per JQL search, default `1000` |
+| `JIRA_MAX_ATTACHMENT_SIZE` / `JIRA_MAX_ATTACHMENT_BYTES` | Max attachment download size, default `5mb`; skipped files are listed in `attachments.json` |
+| `JIRA_CHROME_PROFILE` | Dedicated Chrome profile dir |
+| `CHROME` | Chrome executable path |
+
+## Troubleshooting
+
+### `no Jira cookies yet`
+
+Complete SSO in the Chrome window opened by the script.
+
+### `HTTP 404 Issue does not exist or you do not have permission`
+
+The session works, but the account cannot see the issue or the key is not a Jira issue.
+
+### Chrome does not open
+
+Set the executable path:
+
+```bash
+CHROME=/usr/bin/chromium scripts/jira-browser-fetch.js PROJ-123
+```
+
+### DevTools port already in use
+
+Use another port:
+
+```bash
+scripts/jira-browser-fetch.js PROJ-123 --port 9333
+```
+
+### SSO opens in the wrong Chrome profile
+
+The script uses its own profile by default. That is intentional so it can enable remote debugging safely. Complete SSO once in that window; future runs reuse it.