@toolu/opencode 6.8.0

package/plugins/jira/hooks/hooks.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|clear|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/session-start.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

package/plugins/jira/hooks/session-start.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+# SessionStart hook — publish the jira wrapper at a STABLE, env-independent
+# path. See context7's session-start.sh for the same fix rationale:
+# ${CLAUDE_PLUGIN_ROOT} is exported to hook subprocesses only — NOT to the
+# agent's Bash tool subshell — so a SKILL.md path of
+# "${CLAUDE_PLUGIN_ROOT}/skills/jira/scripts/jira.sh" expands to
+# "/skills/.../jira.sh: No such file" when an agent pastes it. Mirror the
+# statusline plugin: symlink the wrapper to
+#   ${CLAUDE_CONFIG_DIR:-$HOME/.claude}/jira/jira.sh
+# Refreshed every session; silent on success; every step non-fatal.
+
+# Consume stdin so Claude Code's hook IPC never stalls.
+cat > /dev/null 2>&1 || true
+
+plugin_dir="$(cd "$(dirname "$0")/.." 2>/dev/null && pwd)"
+src="${plugin_dir:+$plugin_dir/skills/jira/scripts/jira.sh}"
+[ -n "$src" ] && [ -f "$src" ] || exit 0
+
+if [ -n "${TOOLU_CONFIG_DIR:-}" ]; then
+  config_root="$TOOLU_CONFIG_DIR"
+elif [ "${TOOLU_HOST_OVERRIDE:-}" = codex ] || { [ -z "${TOOLU_HOST_OVERRIDE:-}" ] && [ -n "${PLUGIN_ROOT:-}" ]; }; then
+  config_root="${CODEX_HOME:-$HOME/.codex}"
+else
+  config_root="${CLAUDE_CONFIG_DIR:-$HOME/.claude}"
+fi
+reg_root="$config_root/jira"
+mkdir -p "$reg_root" 2>/dev/null || { echo "jira: cannot create $reg_root — wrapper not published" >&2; exit 0; }
+
+dst="$reg_root/jira.sh"
+if [ -L "$dst" ] || [ ! -e "$dst" ]; then
+  ln -sf "$src" "$dst" 2>/dev/null || true
+fi
+
+exit 0

package/plugins/jira/skills/jira/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: jira
+description: Search and act on Jira issues from the session via a REST wrapper — JQL search, read/create/comment/transition/assign issues, plus boards, sprints, worklogs, projects, users, attachments. Works against Jira Cloud and Server/Data Center. Triggers when the user mentions Jira, a JQL query, an issue key like ABC-123, a pasted atlassian.net/browse/ABC-123 link, "my tickets", "create a task at Jira", "create/comment on/transition/assign an issue", sprints or boards. Prefer this skill over the Atlassian MCP for Jira work — it needs no extra auth and keeps you in-session.
+---
+
+# Jira
+
+Use this skill to work a Jira ticket without leaving the session: search by JQL, read an issue, comment, move it through its workflow, manage sprints/worklogs, or reach any endpoint via `raw`.
+
+**Trigger phrases:** jira, JQL, my open tickets, issue ABC-123, a pasted atlassian.net/browse link, create a task at jira, create an issue, comment on, transition / move to, assign to, log work, sprint, board, plan the ticket, break down ABC-123.
+
+**Prefer this over the Atlassian MCP.** When the user mentions Jira, an issue key, or pastes a Jira link, use this skill — not `mcp__*Atlassian*` tools. This wrapper reuses your existing Jira/`jira` CLI auth and stays in-session; reach for the MCP only if this skill cannot reach the endpoint.
+
+## CLI tool
+
+Invoke at the **stable published path** (a symlink the plugin's SessionStart hook refreshes every session):
+
+```bash
+# Codex
+TOOLU_HOST_OVERRIDE=codex \
+  "${TOOLU_CONFIG_DIR:-${CODEX_HOME:-$HOME/.codex}}/jira/jira.sh" [--api-version N] [--lean] <family> <action> [options]
+# Claude Code
+TOOLU_HOST_OVERRIDE=claude \
+  "${TOOLU_CONFIG_DIR:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}}/jira/jira.sh" [--api-version N] [--lean] <family> <action> [options]
+```
+
+Choose the complete command for the active host, including its override; every
+`jira.sh` shorthand below means that chosen prefix. The override propagates to
+nested plan checks and their state paths. Ordinary shell calls do not inherit
+plugin lifecycle variables, so never collapse these into one ambiguous
+fallback. Use the published path; plugin-root variables are lifecycle-only.
+
+Repo-checkout fallback (for tests/dev when the plugin is not installed): `plugins/jira/skills/jira/scripts/jira.sh`.
+
+## Setup
+
+**Easiest:** if the [`jira` CLI](https://github.com/ankitpokhrel/jira-cli) is configured (`jira init`), this plugin reuses its login automatically — server + login from `~/.config/.jira/.config.yml`, API token from the OS keyring (or `$JIRA_API_TOKEN`). No extra setup.
+
+**Or set environment variables** (these always take precedence; never a `.env` file):
+
+```
+JIRA_BASE_URL                  required, e.g. https://acme.atlassian.net (no trailing slash)
+JIRA_PAT                       Bearer auth — Personal Access Token (Cloud or Server/DC)
+JIRA_EMAIL + JIRA_API_TOKEN    basic auth — Cloud API token (used when JIRA_PAT is unset)
+JIRA_API_VERSION               2 or 3 (default 3). Server/Data Center → 2.
+```
+
+Resolution: explicit env wins; else the jira CLI config + keyring fill the gaps. Auth: `JIRA_PAT` → Bearer; else `JIRA_EMAIL`+`JIRA_API_TOKEN` → basic. When nothing is available the plugin prints a short, friendly setup prompt (not an error) and exits.
+
+## Families
+
+```
+jira.sh search -q '<JQL>' [-n MAX] [--all] [--fields f1,f2] [--lean]
+jira.sh issue get <KEY> [--lean]
+jira.sh issue create -p <PROJECT> -t <TYPE> -s <SUMMARY> [-d DESC] [--assignee ID] [-f field=val]...
+jira.sh issue comment <KEY> <TEXT>
+jira.sh issue transitions <KEY>                 # list available transitions
+jira.sh issue transition <KEY> <NAME|ID>        # name resolved case-insensitively
+jira.sh issue assign <KEY> <ACCOUNT_ID|->       # '-' unassigns
+jira.sh issue update <KEY> [-s SUMMARY] [-d DESC] [-f field=val]...
+jira.sh issue delete <KEY>
+jira.sh board   list [-p PROJECT] | get <ID> | issues <ID> [-q JQL]
+jira.sh sprint  list <BOARD_ID> | get <ID> | issues <ID> | create <BOARD_ID> -n NAME
+              | move <SPRINT_ID> <KEY...> | start <ID> | complete <ID>
+jira.sh worklog add <KEY> -t <TIME> [-c COMMENT] | list <KEY> | delete <KEY> <WORKLOG_ID>
+jira.sh project list | get <KEY> | versions <KEY> | components <KEY>
+jira.sh user    whoami | search -q <QUERY> | get <ACCOUNT_ID>
+jira.sh attachment add <KEY> <FILE> | list <KEY> | get <ATTACHMENT_ID>
+              | download <ATTACHMENT_ID> [-o FILE] | read <ATTACHMENT_ID>   # read: text→context, binary→saved path
+jira.sh raw <GET|POST|PUT|DELETE> <PATH> [JSON_BODY]   # escape hatch; PATH relative to JIRA_BASE_URL
+jira.sh plan init <KEY>                                # scaffold the plan doc, titled from a live issue get
+jira.sh plan run <DOC> [--step <id>] [--activity <s>]  # run the checks, write the ledger
+jira.sh plan status <KEY> | path <KEY>                 # ledger summary / ledger path
+```
+
+## Plan first — when to decompose
+
+**Read-only lookup → call directly.** `issue get`, `search`, `board list`, `sprint list`, `user whoami`, `attachment read` and friends are one-shot. No plan.
+
+**Mutating, or two-or-more actions → write a plan first.** Anything that changes a live ticket (`issue create/update/comment/transition/assign`, `sprint create/move/start/complete`, `worklog add/delete`, `attachment add`), or any task needing more than one call, gets decomposed:
+
+1. `jira.sh plan init <KEY>` — scaffolds the active host's project state path:
+   `.claude/tmp/jira/plans/<KEY>.md` or `.codex/tmp/jira/plans/<KEY>.md`.
+2. Author the `## Steps (machine-readable)` array: one `{id, title, check}` per small, independently verifiable action.
+3. `jira.sh plan run <DOC> --step <id>` after doing each step; a final full `jira.sh plan run <DOC>` at the end.
+
+This writes a ledger below the active host's `<repo>/.claude/tmp/plan-ledger/`
+or `<repo>/.codex/tmp/plan-ledger/`. It is **not** the branch ledger and never
+blocks `git push`.
+
+## Authoring a `check`
+
+A `check` is a shell command that must exit 0 **only when Jira itself reflects the change**. Assert against a live read — never `true`, never a marker file. `$JIRA` is bound to this CLI when the check runs.
+
+| Mutation | Assertion |
+|---|---|
+| `issue transition` | `"$JIRA" issue get K --lean \| jq -e '.status=="Done"'` |
+| `issue assign` | `"$JIRA" issue get K \| jq -e '.fields.assignee.accountId=="<id>"'` |
+| `issue comment` | `"$JIRA" raw GET /rest/api/3/issue/K/comment \| jq -e '[.comments[].body] \| any(tostring \| contains("<text>"))'` |
+| `issue update` (field) | `"$JIRA" issue get K \| jq -e '.fields.summary=="<new>"'` |
+| `sprint move` | `"$JIRA" sprint issues <SID> \| jq -e '[.issues[].key] \| index("K")'` |
+| `worklog add` | `"$JIRA" worklog list K \| jq -e '[.worklogs[].timeSpent] \| index("2h")'` |
+
+`plan run` probes Jira once (`user whoami`) before any check. If Jira is unreachable it aborts and writes **no** statuses — an auth or network failure never marks a step red. A step goes red only when a check ran and Jira disagreed; the reason is kept in the step's `evidence_tail`.
+
+## Mutating operations — confirm intent first
+
+These change live tickets and have no undo prompt (the verb is the confirmation):
+`issue create`, `issue update`, `issue comment`, `issue transition`, `issue assign`, `issue delete`,
+`sprint create/move/start/complete`, `worklog add/delete`, `attachment add`. Know the target `KEY`/`ID` before running them.
+
+Each of these is also a **plan-first** operation — decompose before you mutate (see above).
+
+## Notes & constraints
+
+| Topic | Detail |
+|---|---|
+| Search endpoint | v3 (Cloud) uses `POST /rest/api/3/search/jql` (`nextPageToken`, no `total`); v2 uses `/rest/api/2/search` (`startAt`). `--all` follows whichever model applies. |
+| Comment/description bodies | v3 needs ADF — the tool converts your plain text automatically; v2 takes plain text. Rich ADF (tables, mentions) is not supported — use `raw`. |
+| Boards & sprints | Always hit `/rest/agile/1.0` regardless of `--api-version`. |
+| `-f field=val` | Sets string scalars only. Fields needing objects/arrays (e.g. a custom-field object) → use `jira raw`. |
+| `--lean` | Strips null/empty fields and Jira's verbose envelopes — use it when feeding results back to the model to cut tokens. |
+| Anything unwrapped | `jira raw <METHOD> <path> [body]` reaches every endpoint the families don't cover. |

package/plugins/jira/skills/jira/scripts/jira.sh

@@ -0,0 +1,70 @@
+#!/usr/bin/env bash
+# jira.sh — Jira CLI dispatcher. Strips global flags (--api-version, --lean) from
+# anywhere in argv, then routes <family> <action> to the matching lib module.
+# Reads creds from JIRA_* env (never .env). See SKILL.md for full usage.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+LIB="$SCRIPT_DIR/lib"
+FAMILIES="search issue board sprint worklog project user attachment raw plan"
+
+usage() {
+  cat >&2 <<'EOF'
+jira — Jira from the session (Cloud + Server/DC)
+
+Usage: jira [--api-version N] [--lean] <family> <action> [options]
+
+Families:
+  search       JQL search
+  issue        get|create|update|delete|comment|transition|transitions|assign
+  board        list|get|issues
+  sprint       list|get|create|issues|move|start|complete
+  worklog      add|list|delete
+  project      list|get|versions|components
+  user         whoami|search|get
+  attachment   add|list|get
+  raw          <METHOD> <path> [body]
+  plan         init|run|status|path
+
+Environment:
+  JIRA_BASE_URL                      required (e.g. https://acme.atlassian.net)
+  JIRA_PAT                           Bearer auth (Cloud or Server/DC)
+  JIRA_EMAIL + JIRA_API_TOKEN        basic auth (Cloud API token)
+  JIRA_API_VERSION                   2 or 3 (default 3)
+EOF
+  exit 1
+}
+
+# Strip global flags from anywhere; export resolved transport globals.
+args=()
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --api-version)   export _JIRA_VER="${2:-}"; shift 2;;
+    --api-version=*) export _JIRA_VER="${1#*=}"; shift;;
+    --lean)          export _JIRA_LEAN=1; shift;;
+    *)               args+=("$1"); shift;;
+  esac
+done
+set -- ${args[@]+"${args[@]}"}
+
+[[ $# -lt 1 ]] && usage
+family="$1"; shift
+
+case " $FAMILIES " in
+  *" $family "*) ;;
+  *) echo "jira: unknown family '$family'" >&2; usage;;
+esac
+
+# shellcheck source=/dev/null
+source "$LIB/http.sh"
+source "$LIB/adf.sh"
+source "$LIB/paginate.sh"
+# shellcheck source=/dev/null
+source "$LIB/$family.sh"
+
+# `plan path` only prints a local ledger path — it never reaches Jira, so it must
+# work without credentials. Every other family/action does reach Jira.
+if ! { [ "$family" = "plan" ] && [ "${1:-}" = "path" ]; }; then
+  jira_require_env
+fi
+"jira_$family" "$@"

package/plugins/jira/skills/jira/scripts/lib/adf.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+# adf.sh — render a plain-text comment/description body for the resolved API
+# version: a minimal ADF document for v3 (Cloud), a plain JSON string for v2
+# (Server/DC). Sourced; defines a function only.
+
+# jira_text_to_adf TEXT: print the JSON *value* for a body field (not wrapped).
+# v3 -> {"type":"doc","version":1,"content":[{"type":"paragraph",...}]}
+# v2 -> the text as a JSON string. Callers wrap it, e.g. {"body": <value>}.
+jira_text_to_adf() {
+  local text="$1"
+  if [[ "${_JIRA_VER:-3}" == "2" ]]; then
+    jq -n --arg t "$text" '$t'
+  else
+    jq -n --arg t "$text" \
+      '{type:"doc",version:1,content:[{type:"paragraph",content:[{type:"text",text:$t}]}]}'
+  fi
+}

package/plugins/jira/skills/jira/scripts/lib/attachment.sh

@@ -0,0 +1,94 @@
+#!/usr/bin/env bash
+# attachment.sh — Jira issue attachments: add (multipart upload), list, get
+# (metadata), download (binary content), read (download + surface text content
+# as context). Sourced; depends on http.sh (jira_curl/jira_lean/jira_download and
+# the resolved transport state). The multipart `add` builds its own curl
+# (jira_curl only speaks JSON), reusing the same auth resolution.
+
+jira_attachment() {
+  local action="${1:-}"; [[ $# -gt 0 ]] && shift
+  case "$action" in
+    add)      _jira_attachment_add "$@";;
+    list)     _jira_attachment_list "$@";;
+    get)      _jira_attachment_get "$@";;
+    download) _jira_attachment_download "$@";;
+    read)     _jira_attachment_read "$@";;
+    *) echo "Usage: jira attachment <add|list|get|download|read> ..." >&2; return 1;;
+  esac
+}
+
+# _jira_attachment_add KEY FILE: multipart-upload FILE to issue KEY's attachments.
+_jira_attachment_add() {
+  local key="${1:-}" file="${2:-}"
+  [[ -z "$key" || -z "$file" ]] && { echo "Usage: jira attachment add <KEY> <FILE>" >&2; return 1; }
+  [[ -f "$file" ]] || { echo "attachment add: file not found: $file" >&2; return 1; }
+  local args=(-sS --fail-with-body -X POST -H "X-Atlassian-Token: no-check" \
+    -H "Accept: application/json" -F "file=@$file")
+  if [[ "${_JIRA_AUTH_MODE:-}" == "bearer" ]]; then
+    args+=(-H "Authorization: Bearer ${JIRA_PAT}")
+  else
+    args+=(-u "${JIRA_EMAIL}:${JIRA_API_TOKEN}")
+  fi
+  curl "${args[@]}" "${_JIRA_BASE}/rest/api/${_JIRA_VER}/issue/${key}/attachments" | jira_lean '.'
+}
+
+# _jira_attachment_list KEY: list KEY's attachments (id, filename, size).
+_jira_attachment_list() {
+  local key="${1:-}"
+  [[ -z "$key" ]] && { echo "Usage: jira attachment list <KEY>" >&2; return 1; }
+  jira_curl GET "/rest/api/${_JIRA_VER}/issue/${key}?fields=attachment" \
+    | jira_lean '{attachments:[.fields.attachment[]|{id, filename, size}]}'
+}
+
+# _jira_attachment_get ATTACHMENT_ID: fetch one attachment's metadata.
+_jira_attachment_get() {
+  local id="${1:-}"
+  [[ -z "$id" ]] && { echo "Usage: jira attachment get <ATTACHMENT_ID>" >&2; return 1; }
+  jira_curl GET "/rest/api/${_JIRA_VER}/attachment/${id}" | jira_lean '.'
+}
+
+# _jira_attachment_download ATTACHMENT_ID [-o OUTFILE]: download the binary
+# content. Without -o, the filename is taken from the attachment metadata.
+_jira_attachment_download() {
+  local id="${1:-}"; [[ $# -gt 0 ]] && shift
+  local out=""
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      -o|--output) out="$2"; shift 2;;
+      *) echo "attachment download: unknown option '$1'" >&2; return 1;;
+    esac
+  done
+  [[ -z "$id" ]] && { echo "Usage: jira attachment download <ATTACHMENT_ID> [-o OUTFILE]" >&2; return 1; }
+  if [[ -z "$out" ]]; then
+    local fn; fn=$(jira_curl GET "/rest/api/${_JIRA_VER}/attachment/${id}" | jq -r '.filename // empty')
+    out="${fn:-attachment-${id}}"
+  fi
+  jira_download "/rest/api/${_JIRA_VER}/attachment/content/${id}" "$out"
+  echo "downloaded attachment ${id} -> ${out}"
+}
+
+# _jira_attachment_read ATTACHMENT_ID: download the content and, for text-like
+# types, print it (so it becomes usable context); for binary types, report the
+# type/size and the saved path instead of dumping bytes.
+_jira_attachment_read() {
+  local id="${1:-}"
+  [[ -z "$id" ]] && { echo "Usage: jira attachment read <ATTACHMENT_ID>" >&2; return 1; }
+  local meta mime fn
+  meta=$(jira_curl GET "/rest/api/${_JIRA_VER}/attachment/${id}") || return 1
+  mime=$(jq -r '.mimeType // ""' <<<"$meta")
+  fn=$(jq -r '.filename // "attachment"' <<<"$meta")
+  local tmp; tmp="$(mktemp -t jira-attachment.XXXXXX)"
+  jira_download "/rest/api/${_JIRA_VER}/attachment/content/${id}" "$tmp" || { rm -f "$tmp"; return 1; }
+  case "$mime" in
+    text/*|application/json|application/xml|application/javascript|application/x-yaml|application/yaml|*+json|*+xml)
+      printf '# %s (%s)\n\n' "$fn" "$mime"
+      cat "$tmp"
+      rm -f "$tmp"
+      ;;
+    *)
+      local size; size=$(wc -c < "$tmp" | tr -d ' ')
+      printf '%s — binary attachment (%s, %s bytes) saved to %s\n' "$fn" "${mime:-unknown}" "$size" "$tmp"
+      printf 'Run `jira attachment download %s -o <path>` to save it elsewhere.\n' "$id"
+      ;;
+  esac
+}

package/plugins/jira/skills/jira/scripts/lib/board.sh

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+# board.sh — Jira Agile board operations: list boards, fetch one, list a board's
+# issues. Sourced; depends on http.sh (jira_curl/jira_lean). Agile endpoints are
+# always under /rest/agile/1.0 regardless of the configured REST API version.
+
+# jira_board <list|get|issues> ...: dispatch on the first arg (sub-action).
+jira_board() {
+  local action="${1:-}"; [[ $# -gt 0 ]] && shift
+  case "$action" in
+    list)   _jira_board_list "$@";;
+    get)    _jira_board_get "$@";;
+    issues) _jira_board_issues "$@";;
+    *) echo "Usage: jira board <list|get|issues> ..." >&2; return 1;;
+  esac
+}
+
+# _jira_board_list [-p PROJECT]: GET /rest/agile/1.0/board, optionally scoped to
+# a project key/id via ?projectKeyOrId=PROJECT.
+_jira_board_list() {
+  local project=""
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      -p|--project) project="$2"; shift 2;;
+      *) echo "board list: unknown option '$1'" >&2; return 1;;
+    esac
+  done
+  local path="/rest/agile/1.0/board"
+  [[ -n "$project" ]] && path="${path}?projectKeyOrId=${project}"
+  jira_curl GET "$path" | jira_lean '{values: [.values[] | {id, name, type}]}'
+}
+
+# _jira_board_get <ID>: GET /rest/agile/1.0/board/<ID>.
+_jira_board_get() {
+  local id="${1:-}"
+  [[ -z "$id" ]] && { echo "Usage: jira board get <ID>" >&2; return 1; }
+  jira_curl GET "/rest/agile/1.0/board/$id" | jira_lean '.'
+}
+
+# _jira_board_issues <ID> [-q JQL] [-n MAX]: GET /rest/agile/1.0/board/<ID>/issue,
+# appending ?jql=...&maxResults=... when those filters are supplied.
+_jira_board_issues() {
+  local id="${1:-}"; [[ $# -gt 0 ]] && shift
+  [[ -z "$id" ]] && { echo "Usage: jira board issues <ID> [-q JQL] [-n MAX]" >&2; return 1; }
+  local jql="" max=""
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      -q|--query) jql="$2"; shift 2;;
+      -n|--num)   max="$2"; shift 2;;
+      *) echo "board issues: unknown option '$1'" >&2; return 1;;
+    esac
+  done
+  local path="/rest/agile/1.0/board/$id/issue" query=""
+  [[ -n "$jql" ]] && query="${query}&jql=$(jira_urlencode "$jql")"
+  [[ -n "$max" ]] && query="${query}&maxResults=${max}"
+  [[ -n "$query" ]] && path="${path}?${query#&}"
+  jira_curl GET "$path" \
+    | jira_lean '{issues: [.issues[] | {key, summary: .fields.summary, status: .fields.status.name}]}'
+}

package/plugins/jira/skills/jira/scripts/lib/http.sh

@@ -0,0 +1,184 @@
+#!/usr/bin/env bash
+# http.sh — shared Jira transport: credential resolution, the curl wrapper, lean
+# output. Credentials come from JIRA_* env, or are reused from an installed
+# ankitpokhrel jira-cli (config + OS keyring) when the env vars are unset.
+# Sourced by jira.sh and every per-family lib module; defines functions only
+# (no top-level side effects), so it is safe to source in unit tests.
+
+# jira_require_env: validate JIRA_* env and resolve transport state.
+# Sets _JIRA_AUTH_MODE (bearer|basic), _JIRA_VER (2|3), _JIRA_BASE (no trailing
+# slash). Returns 1 (naming the offending var) on missing tools/creds/base/version.
+jira_require_env() {
+  command -v curl >/dev/null 2>&1 || { echo "jira: curl required" >&2; return 1; }
+  command -v jq   >/dev/null 2>&1 || { echo "jira: jq required" >&2; return 1; }
+
+  # Fill any unset JIRA_* from an installed jira CLI (best-effort; explicit env
+  # always wins, and a missing CLI is a no-op — never an error).
+  jira_load_cli_creds
+
+  if [[ -z "${JIRA_BASE_URL:-}" ]]; then jira_creds_help; return 1; fi
+  _JIRA_BASE="$JIRA_BASE_URL"
+  while [[ "$_JIRA_BASE" == */ ]]; do _JIRA_BASE="${_JIRA_BASE%/}"; done
+
+  if [[ -n "${JIRA_PAT:-}" ]]; then
+    _JIRA_AUTH_MODE="bearer"
+  elif [[ -n "${JIRA_EMAIL:-}" && -n "${JIRA_API_TOKEN:-}" ]]; then
+    _JIRA_AUTH_MODE="basic"
+  else
+    jira_creds_help; return 1
+  fi
+
+  _JIRA_VER="${_JIRA_VER:-${JIRA_API_VERSION:-3}}"
+  if [[ "$_JIRA_VER" != "2" && "$_JIRA_VER" != "3" ]]; then
+    echo "jira: api version must be 2 or 3 (got '$_JIRA_VER')" >&2
+    return 1
+  fi
+  export _JIRA_AUTH_MODE _JIRA_VER _JIRA_BASE
+}
+
+# jira_curl METHOD PATH [BODY]: authenticated request to _JIRA_BASE+PATH.
+# Adds the resolved auth, JSON Accept, and --fail-with-body; BODY (when given)
+# is sent as a JSON payload. Stdout is the raw response body.
+jira_curl() {
+  local method="$1" path="$2" body="${3:-}"
+  local args=(-sS --fail-with-body -X "$method" -H "Accept: application/json")
+  if [[ "${_JIRA_AUTH_MODE:-}" == "bearer" ]]; then
+    args+=(-H "Authorization: Bearer ${JIRA_PAT}")
+  else
+    args+=(-u "${JIRA_EMAIL}:${JIRA_API_TOKEN}")
+  fi
+  if [[ -n "$body" ]]; then
+    args+=(-H "Content-Type: application/json" --data "$body")
+  fi
+  curl "${args[@]}" "${_JIRA_BASE}${path}"
+}
+
+# jira_lean [JQ_PROJECTION]: filter stdin through PROJECTION when _JIRA_LEAN=1
+# (token-frugal output for LLM prompts), else pretty-print the full body.
+jira_lean() {
+  local projection="${1:-.}"
+  if [[ "${_JIRA_LEAN:-}" == "1" ]]; then
+    jq "$projection"
+  else
+    jq '.'
+  fi
+}
+
+# jira_urlencode TEXT: percent-encode TEXT for safe use as a URL query value
+# (spaces, =, &, etc.). Used by families that pass user input via query params.
+jira_urlencode() {
+  jq -nr --arg s "$1" '$s|@uri'
+}
+
+# jira_download PATH OUTFILE: authenticated GET that follows redirects and
+# writes the response body to OUTFILE (Jira attachment content 302-redirects to
+# a media host). Auth is inlined rather than shared via a nameref to stay
+# portable to bash 3.2.
+jira_download() {
+  local path="$1" out="$2"
+  local args=(-sS --fail-with-body -L -o "$out" -H "Accept: */*")
+  if [[ "${_JIRA_AUTH_MODE:-}" == "bearer" ]]; then
+    args+=(-H "Authorization: Bearer ${JIRA_PAT}")
+  else
+    args+=(-u "${JIRA_EMAIL}:${JIRA_API_TOKEN}")
+  fi
+  curl "${args[@]}" "${_JIRA_BASE}${path}"
+}
+
+# ── credential discovery (ankitpokhrel jira-cli) ───────────────────────────
+# jira-cli keeps server+login in a flat YAML config and the API token in one of
+# several places. We reuse them to fill any unset JIRA_* var, matching jira-cli's
+# own token order (config api_token → $JIRA_API_TOKEN → ~/.netrc → OS keyring),
+# so a configured CLI needs no extra setup. Explicit JIRA_* env always wins.
+
+# _jira_yaml_get FILE KEY: print a top-level scalar (key: value) from flat YAML.
+_jira_yaml_get() {
+  [[ -r "$1" ]] || return 0
+  awk -v k="$2" 'index($0, k":")==1 { sub(/^[^:]*:[[:space:]]*/,""); sub(/[[:space:]]+$/,""); print; exit }' "$1"
+}
+
+# _jira_keyring_token LOGIN: best-effort token from the OS keyring (macOS
+# security, then Linux secret-tool). Empty string on any miss — never errors.
+# macOS may require interactive keychain authorization the first time.
+_jira_keyring_token() {
+  local login="$1" svc="${JIRA_KEYRING_SERVICE:-jira-cli}" tok=""
+  if command -v security >/dev/null 2>&1; then
+    tok=$(security find-generic-password -s "$svc" -a "$login" -w 2>/dev/null || true)
+  fi
+  if [[ -z "$tok" ]] && command -v secret-tool >/dev/null 2>&1; then
+    tok=$(secret-tool lookup service "$svc" username "$login" 2>/dev/null || true)
+  fi
+  printf '%s' "$tok"
+}
+
+# _jira_netrc_token HOST: token (password) for HOST from ~/.netrc (or $NETRC).
+# Flattens tokens so multi-line entries work. Empty on miss — never errors.
+_jira_netrc_token() {
+  local host="$1" file="${NETRC:-$HOME/.netrc}"
+  [[ -r "$file" ]] || return 0
+  awk -v h="$host" '
+    { for (i=1;i<=NF;i++) a[++n]=$i }
+    END { for (i=1;i<=n;i++) {
+            if (a[i]=="machine" && a[i+1]==h) inhost=1
+            else if (a[i]=="machine") inhost=0
+            if (inhost && a[i]=="password") { print a[i+1]; exit }
+          } }' "$file"
+}
+
+# jira_load_cli_creds: fill unset JIRA_* from the jira-cli config + keyring.
+# No-op (and no error) when the CLI is not configured.
+jira_load_cli_creds() {
+  local cfg="${JIRA_CLI_CONFIG:-${XDG_CONFIG_HOME:-$HOME/.config}/.jira/.config.yml}"
+  [[ -r "$cfg" ]] || return 0
+  local server login installation
+  server=$(_jira_yaml_get "$cfg" server)
+  login=$(_jira_yaml_get "$cfg" login)
+  installation=$(_jira_yaml_get "$cfg" installation)
+  [[ -z "${JIRA_BASE_URL:-}" && -n "$server" ]] && export JIRA_BASE_URL="$server"
+  [[ -z "${JIRA_EMAIL:-}"    && -n "$login"  ]] && export JIRA_EMAIL="$login"
+  if [[ -z "${JIRA_API_VERSION:-}" && -n "$installation" ]]; then
+    case "$installation" in
+      [Cc]loud) export JIRA_API_VERSION=3 ;;
+      *)        export JIRA_API_VERSION=2 ;;
+    esac
+  fi
+  if [[ -z "${JIRA_PAT:-}" && -z "${JIRA_API_TOKEN:-}" ]]; then
+    # Match jira-cli's token sources, in its order: config api_token, then
+    # ~/.netrc (by server host), then the OS keyring.
+    local tok host
+    tok=$(_jira_yaml_get "$cfg" api_token)
+    if [[ -z "$tok" && -n "$server" ]]; then
+      host="${server#*://}"; host="${host%%/*}"
+      tok=$(_jira_netrc_token "$host")
+    fi
+    [[ -z "$tok" && -n "$login" ]] && tok=$(_jira_keyring_token "$login")
+    [[ -n "$tok" ]] && export JIRA_API_TOKEN="$tok"
+  fi
+  return 0
+}
+
+# jira_creds_help: friendly, non-error guidance when no credentials resolve.
+# Reads as a one-time setup step, not a failure.
+jira_creds_help() {
+  cat >&2 <<'EOF'
+jira: no Jira credentials found yet — let's get you connected.
+
+This plugin reuses your `jira` CLI login automatically when it's configured,
+or reads JIRA_* environment variables. Right now neither is set.
+
+Connect with either:
+
+  • Your jira CLI (easiest if it's installed):
+      jira init
+    then re-run your command — the plugin picks up the server, login, and
+    API token from the CLI automatically.
+
+  • Or environment variables:
+      export JIRA_BASE_URL=https://your-site.atlassian.net
+      export JIRA_EMAIL=you@example.com
+      export JIRA_API_TOKEN=…        # id.atlassian.com → Security → API tokens
+    (Jira Server/Data Center: use JIRA_PAT instead of JIRA_EMAIL + JIRA_API_TOKEN.)
+
+Nothing is broken — this is just a one-time setup step.
+EOF
+}