@codyswann/lisa 2.119.1 → 2.121.0

package/plugins/lisa-cursor/skills/jira-journey/scripts/parse-plan.py

@@ -0,0 +1,368 @@
+#!/usr/bin/env python3
+"""Parse the Validation Journey section from a JIRA ticket description.
+
+Fetches the ticket via REST API, extracts the Validation Journey section
+(ADF or wiki markup), and outputs structured JSON to stdout.
+
+Usage:
+    python3 parse-plan.py <TICKET_ID>
+
+Example:
+    python3 parse-plan.py SE-3820
+
+Output (JSON):
+    {
+      "ticket": "SE-3820",
+      "prerequisites": ["Backend running", "Admin user"],
+      "steps": [
+        {"number": 1, "text": "Navigate to page", "screenshot": null},
+        {"number": 2, "text": "Click button [EVIDENCE: btn]", "screenshot": "btn"}
+      ],
+      "viewports": [
+        {"name": "Desktop", "width": 1512, "height": 768}
+      ],
+      "assertions": ["Modal fills screen"]
+    }
+"""
+
+import json
+import os
+import re
+import subprocess
+import sys
+import urllib.request
+from base64 import b64encode
+from pathlib import Path
+
+
+def get_jira_config():
+    """Read JIRA server and login from jira-cli config."""
+    config_path = Path.home() / ".config" / ".jira" / ".config.yml"
+    if not config_path.exists():
+        print(f"ERROR: jira-cli config not found at {config_path}", file=sys.stderr)
+        sys.exit(1)
+
+    server = ""
+    login = ""
+    with open(config_path) as f:
+        for line in f:
+            if line.startswith("server:"):
+                server = line.split(":", 1)[1].strip()
+            elif line.startswith("login:"):
+                login = line.split(":", 1)[1].strip()
+
+    token = os.environ.get("JIRA_API_TOKEN", "")
+    if not token:
+        print("ERROR: JIRA_API_TOKEN env var not set", file=sys.stderr)
+        sys.exit(1)
+
+    return server, login, token
+
+
+def fetch_ticket(server, login, token, ticket_id):
+    """Fetch JIRA ticket via REST API v3 (returns ADF description)."""
+    url = f"{server}/rest/api/3/issue/{ticket_id}?fields=description"
+    auth = b64encode(f"{login}:{token}".encode()).decode()
+
+    req = urllib.request.Request(url, headers={
+        "Authorization": f"Basic {auth}",
+        "Accept": "application/json",
+    })
+
+    try:
+        with urllib.request.urlopen(req) as resp:
+            return json.loads(resp.read().decode())
+    except urllib.error.HTTPError as e:
+        print(f"ERROR: JIRA API returned {e.code} for {ticket_id}", file=sys.stderr)
+        sys.exit(1)
+
+
+def extract_text_from_adf(node):
+    """Recursively extract plain text from an ADF node."""
+    if isinstance(node, str):
+        return node
+
+    if isinstance(node, dict):
+        node_type = node.get("type", "")
+
+        if node_type == "text":
+            return node.get("text", "")
+
+        if node_type == "hardBreak":
+            return "\n"
+
+        parts = []
+        for child in node.get("content", []):
+            parts.append(extract_text_from_adf(child))
+        return "".join(parts)
+
+    if isinstance(node, list):
+        return "".join(extract_text_from_adf(item) for item in node)
+
+    return ""
+
+
+def find_heading_index(content, heading_text, level=None):
+    """Find the index of a heading node matching the given text."""
+    for i, node in enumerate(content):
+        if node.get("type") != "heading":
+            continue
+        if level is not None and node.get("attrs", {}).get("level") != level:
+            continue
+        text = extract_text_from_adf(node).strip().lower()
+        if heading_text.lower() in text:
+            return i
+    return -1
+
+
+def extract_section_content(content, start_idx, same_level=True):
+    """Extract all nodes between a heading and the next heading of same or higher level."""
+    if start_idx < 0 or start_idx >= len(content):
+        return []
+
+    heading_level = content[start_idx].get("attrs", {}).get("level", 2)
+    nodes = []
+
+    for i in range(start_idx + 1, len(content)):
+        node = content[i]
+        if node.get("type") == "heading":
+            node_level = node.get("attrs", {}).get("level", 2)
+            if same_level and node_level <= heading_level:
+                break
+        nodes.append(node)
+
+    return nodes
+
+
+def parse_prerequisites(nodes):
+    """Extract prerequisite strings from ADF nodes (bullet lists or paragraphs)."""
+    prerequisites = []
+    for node in nodes:
+        if node.get("type") == "bulletList":
+            for item in node.get("content", []):
+                text = extract_text_from_adf(item).strip()
+                if text:
+                    prerequisites.append(text)
+        elif node.get("type") == "paragraph":
+            text = extract_text_from_adf(node).strip()
+            if text:
+                prerequisites.append(text)
+    return prerequisites
+
+
+def clean_step_text(text, screenshot_name):
+    """Remove [SCREENSHOT: ...] or [EVIDENCE: ...] marker from step text and deduplicate."""
+    # Remove the marker itself
+    cleaned = re.sub(r'\[(SCREENSHOT|EVIDENCE):\s*[^\]]+\]\s*', '', text).strip()
+
+    # Deduplicate: if the same phrase appears twice consecutively, keep one
+    # This handles ADF text node concatenation artifacts
+    words = cleaned.split()
+    mid = len(words) // 2
+    if mid > 2 and words[:mid] == words[mid:2 * mid]:
+        cleaned = " ".join(words[:mid] + words[2 * mid:])
+
+    return cleaned
+
+
+def parse_steps(nodes):
+    """Extract ordered steps with optional [SCREENSHOT: name] or [EVIDENCE: name] markers."""
+    steps = []
+    step_number = 0
+
+    for node in nodes:
+        if node.get("type") == "orderedList":
+            for item in node.get("content", []):
+                step_number += 1
+                text = extract_text_from_adf(item).strip()
+
+                screenshot = None
+                match = re.search(r'\[(SCREENSHOT|EVIDENCE):\s*([^\]]+)\]', text)
+                if match:
+                    screenshot = match.group(2).strip()
+
+                display_text = clean_step_text(text, screenshot) if screenshot else text
+
+                steps.append({
+                    "number": step_number,
+                    "text": display_text,
+                    "screenshot": screenshot,
+                })
+        elif node.get("type") == "paragraph":
+            text = extract_text_from_adf(node).strip()
+            if text and re.match(r'^\d+\.?\s', text):
+                step_number += 1
+                screenshot = None
+                match = re.search(r'\[(SCREENSHOT|EVIDENCE):\s*([^\]]+)\]', text)
+                if match:
+                    screenshot = match.group(2).strip()
+
+                clean_text = re.sub(r'^\d+\.?\s*', '', text)
+                display_text = clean_step_text(clean_text, screenshot) if screenshot else clean_text
+                steps.append({
+                    "number": step_number,
+                    "text": display_text,
+                    "screenshot": screenshot,
+                })
+
+    return steps
+
+
+def parse_viewports(nodes):
+    """Extract viewport definitions from ADF table nodes.
+
+    Supports two table formats:
+    - 3 columns: Name | Width | Height
+    - 2 columns: Name | Resolution (WxH)
+    """
+    viewports = []
+
+    for node in nodes:
+        if node.get("type") == "table":
+            rows = node.get("content", [])
+            for row in rows:
+                if row.get("type") != "tableRow":
+                    continue
+
+                cells = row.get("content", [])
+                if not cells:
+                    continue
+
+                # Skip header row (tableHeader cells)
+                if cells[0].get("type") == "tableHeader":
+                    continue
+
+                cell_texts = [extract_text_from_adf(c).strip() for c in cells]
+
+                # 3-column format: Name | Width | Height
+                if len(cell_texts) >= 3:
+                    name = cell_texts[0]
+                    try:
+                        width = int(cell_texts[1])
+                        height = int(cell_texts[2])
+                        viewports.append({
+                            "name": name,
+                            "width": width,
+                            "height": height,
+                        })
+                        continue
+                    except ValueError:
+                        pass
+
+                # 2-column format: Name | WxH (e.g., "1512x768")
+                if len(cell_texts) >= 2:
+                    name = cell_texts[0]
+                    resolution = cell_texts[1]
+                    match = re.match(r'(\d+)\s*[xX×]\s*(\d+)', resolution)
+                    if match:
+                        viewports.append({
+                            "name": name,
+                            "width": int(match.group(1)),
+                            "height": int(match.group(2)),
+                        })
+
+    return viewports
+
+
+def parse_assertions(nodes):
+    """Extract assertion strings from ADF nodes."""
+    assertions = []
+    for node in nodes:
+        if node.get("type") == "bulletList":
+            for item in node.get("content", []):
+                text = extract_text_from_adf(item).strip()
+                if text:
+                    assertions.append(text)
+        elif node.get("type") == "orderedList":
+            for item in node.get("content", []):
+                text = extract_text_from_adf(item).strip()
+                if text:
+                    assertions.append(text)
+        elif node.get("type") == "paragraph":
+            text = extract_text_from_adf(node).strip()
+            if text and text.startswith("-"):
+                assertions.append(text.lstrip("- ").strip())
+            elif text:
+                assertions.append(text)
+    return assertions
+
+
+def parse_adf_journey(description_adf):
+    """Parse the Validation Journey from an ADF description object."""
+    content = description_adf.get("content", [])
+
+    # Find the "Validation Journey" h2 heading
+    journey_idx = find_heading_index(content, "validation journey", level=2)
+    if journey_idx < 0:
+        # Try without level constraint
+        journey_idx = find_heading_index(content, "validation journey")
+
+    if journey_idx < 0:
+        print("ERROR: No 'Validation Journey' section found in ticket description", file=sys.stderr)
+        sys.exit(1)
+
+    # Extract sub-sections
+    prereq_idx = find_heading_index(content, "prerequisites", level=3)
+    steps_idx = find_heading_index(content, "steps", level=3)
+    viewports_idx = find_heading_index(content, "viewports", level=3)
+    assertions_idx = find_heading_index(content, "assertions", level=3)
+
+    prerequisites = []
+    if prereq_idx >= 0:
+        prereq_nodes = extract_section_content(content, prereq_idx)
+        prerequisites = parse_prerequisites(prereq_nodes)
+
+    steps = []
+    if steps_idx >= 0:
+        steps_nodes = extract_section_content(content, steps_idx)
+        steps = parse_steps(steps_nodes)
+
+    viewports = []
+    if viewports_idx >= 0:
+        viewport_nodes = extract_section_content(content, viewports_idx)
+        viewports = parse_viewports(viewport_nodes)
+
+    assertions = []
+    if assertions_idx >= 0:
+        assertion_nodes = extract_section_content(content, assertions_idx)
+        assertions = parse_assertions(assertion_nodes)
+
+    # Fallback: if no viewports defined, use Desktop as default
+    if not viewports:
+        viewports = [{"name": "Desktop", "width": 1512, "height": 768}]
+
+    return {
+        "prerequisites": prerequisites,
+        "steps": steps,
+        "viewports": viewports,
+        "assertions": assertions,
+    }
+
+
+def main():
+    if len(sys.argv) < 2:
+        print("Usage: parse-plan.py <TICKET_ID>", file=sys.stderr)
+        sys.exit(1)
+
+    ticket_id = sys.argv[1]
+    server, login, token = get_jira_config()
+    ticket_data = fetch_ticket(server, login, token, ticket_id)
+
+    description = ticket_data.get("fields", {}).get("description")
+    if not description:
+        print(f"ERROR: Ticket {ticket_id} has no description", file=sys.stderr)
+        sys.exit(1)
+
+    # ADF description is a dict, wiki markup is a string
+    if isinstance(description, dict):
+        result = parse_adf_journey(description)
+    else:
+        print("ERROR: Wiki markup parsing not implemented. Use JIRA API v3 (ADF format).", file=sys.stderr)
+        sys.exit(1)
+
+    result["ticket"] = ticket_id
+    print(json.dumps(result, indent=2))
+
+
+if __name__ == "__main__":
+    main()

package/plugins/lisa-cursor/skills/jira-read-ticket/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: jira-read-ticket
+description: "Fetches the full scope of a JIRA ticket — metadata, description, acceptance criteria, all comments, remote links (PRs, Confluence, dashboards), issue links (blocks/is blocked by/relates to/duplicates/clones), epic parent with siblings, and subtasks. Produces a consolidated context bundle that downstream agents consume so they never act on a single ticket in isolation."
+allowed-tools: ["Bash", "Skill"]
+---
+
+# Read JIRA Ticket: $ARGUMENTS
+
+All Atlassian operations in this skill go through `lisa:atlassian-access`. Do not call MCP tools or `acli` directly.
+
+Fetch the full scope of the ticket AND its related graph. Downstream agents must never act on a ticket in isolation — always call this skill first so they see blockers, epic siblings, linked PRs, and historical comments.
+
+Repository name for scoped comments and logs: `basename $(git rev-parse --show-toplevel)`.
+
+## Phase 1 — Resolve Context
+
+1. Invoke `lisa:atlassian-access` via the Skill tool with `operation: list-sites` to confirm the configured site is reachable and resolve the cloud ID.
+2. If $ARGUMENTS is not a ticket key (e.g. `PROJ-123`), stop and report. Do NOT guess.
+
+## Phase 2 — Fetch Primary Ticket
+
+Invoke `lisa:atlassian-access` via the Skill tool with `operation: read-ticket key: <TICKET-KEY>` for the target ticket. Extract and preserve:
+
+### Metadata
+
+- Key, summary, issue type, status, resolution
+- Priority, assignee, reporter, creator
+- Labels, components, fix versions, affects versions
+- Sprint, story points, original/remaining estimate
+- Created, updated, resolved dates
+- Parent (epic link or parent issue)
+- Custom fields relevant to the project (read every custom field — do not filter)
+
+### Body
+
+- Full description (preserve formatting)
+- Acceptance criteria section if separately structured
+- **Validation Journey** section if present (pass verbatim to downstream)
+- Attachments list — capture `id`, `filename`, `mimeType`, `size`, and `content` URL for each. Do not download unless a downstream task needs the bytes (see "Downloading attachments" below).
+
+#### Downloading attachments (opt-in)
+
+The Atlassian MCP exposes attachment metadata but no binary-fetch tool ([JRACLOUD-97830](https://jira.atlassian.com/browse/JRACLOUD-97830), [ECO-1265](https://jira.atlassian.com/browse/ECO-1265)). Fetch attachment bytes only when a downstream task explicitly needs them — e.g., a design-fidelity check on an image, log-file analysis, PDF text extraction. For everything else, keep the URL reference and move on.
+
+```bash
+bash .claude/skills/jira-read-ticket/scripts/download-attachment.sh <id-or-content-url> <output-path>
+```
+
+Requires `JIRA_SERVER`, `JIRA_LOGIN`, and `JIRA_API_TOKEN` in the environment (same contract as `jira-evidence`). If those are not set the helper exits with code 2 and a clear remediation message — record the URL only and continue.
+
+After download, branch on `mimeType`:
+- `image/*` — pass the local path to image-aware downstream tools
+- `text/*`, `application/json`, `application/xml`, `application/x-yaml` — read inline as text
+- `application/pdf` — extract text via downstream tooling if needed
+- everything else — record path only; do not attempt to inline binary content
+
+### Comments
+
+Fetch ALL comments in chronological order. Do not truncate. For each:
+- Author, timestamp, body
+- Flag comments that contain: credentials, reproduction steps, status updates from stakeholders, decisions, or triage headers like `[repo-name]`
+
+## Phase 3 — Fetch Remote Links
+
+The primary ticket payload returned by `lisa:atlassian-access` `operation: read-ticket` includes the issue's remote links. If the substrate returns remote links separately, request them via `lisa:atlassian-access` with `operation: read-ticket key: <K>` (the operation MUST return remote links — extend `atlassian-access` if it doesn't). For each remote link:
+
+- **GitHub PR or commit** (`github.com/.../(pull|commit)/...`): run `gh pr view <url> --json title,state,body,mergedAt,reviewDecision,comments,reviews` (for PRs) or `gh api repos/<owner>/<repo>/commits/<sha>` (for commits). Capture title, state, body, unresolved review comments, merge status.
+- **Confluence page**: capture title and URL. Do not fetch body unless a downstream task explicitly needs it.
+- **Dashboard, log link, or external URL**: capture title and URL only.
+
+If `gh` is not authenticated, note "gh auth required" and continue — do not abort.
+
+## Phase 4 — Fetch Issue Links (Relationships)
+
+Every linked ticket must be fetched. Do not skip any link type. For each link in the primary ticket's `issuelinks` field, group by type:
+
+- `blocks` / `is blocked by`
+- `relates to`
+- `duplicates` / `is duplicated by`
+- `clones` / `is cloned by`
+- Any other custom link types configured in the project
+
+For each linked ticket, invoke `lisa:atlassian-access` with `operation: read-ticket key: <LINKED-KEY>` and capture:
+
+- Key, summary, type, status, resolution
+- Description (full, unless closed with resolution `Won't Do`/`Duplicate` — then summary only)
+- Acceptance criteria
+- Last 10 comments (chronological)
+- Remote links (PR URLs and state only — skip deep fetch unless the link is `blocks` or `is blocked by`)
+
+**Special handling for `is blocked by`:** fetch the full PR/commit details via `gh` for each blocker's remote links so the agent knows whether the blocker is actually shipped.
+
+## Phase 5 — Fetch Epic Context
+
+If the primary ticket has an epic parent (or IS an epic):
+
+1. Fetch the epic itself via `lisa:atlassian-access` `operation: read-ticket key: <EPIC-KEY>` — full description, acceptance criteria, all comments, Validation Journey.
+2. Find epic siblings via JQL:
+   ```jql
+   "Epic Link" = <EPIC-KEY> AND key != <TICKET-KEY>
+   ```
+   Invoke `lisa:atlassian-access` with `operation: search-issues jql: "<above-JQL>"`. For each sibling capture: key, summary, type, status, assignee, priority.
+3. Read each sibling's description at a SUMMARY level (first paragraph only) — the goal is to surface related in-flight work, not duplicate full content. If a sibling is `In Progress` or `In Review` with an assignee different from the current ticket, flag it prominently.
+
+If the primary ticket IS an epic, also fetch all children via the JQL above.
+
+## Phase 6 — Fetch Subtasks
+
+If the primary ticket has subtasks, fetch each via `lisa:atlassian-access` `operation: read-ticket key: <SUBTASK-KEY>`: key, summary, type, status, assignee, description (first paragraph), acceptance criteria.
+
+## Phase 7 — Assemble Context Bundle
+
+Produce a single structured output that the caller can pass verbatim to downstream agents. Use this format:
+
+```text
+# Ticket Context: <KEY>
+
+## Primary Ticket
+- Key: <KEY>
+- Type: <type>
+- Status: <status>
+- Priority: <priority>
+- Assignee: <name>
+- Epic: <epic-key> — <epic-summary>
+- Sprint: <sprint>
+- Labels: <labels>
+- Components: <components>
+
+### Description
+<full description>
+
+### Acceptance Criteria
+<criteria>
+
+### Validation Journey
+<section or "None">
+
+### Comments (<count>)
+<chronological comments, flagged items called out>
+
+### Attachments
+<list with id, filename, mimeType, size, content URL — note any that were downloaded and their local paths>
+
+## Remote Links
+### Pull Requests (<count>)
+- <url> — <title> — <state> — <reviewDecision>
+  <body summary + unresolved review comments>
+
+### Confluence
+- <title> — <url>
+
+### Other
+- <title> — <url>
+
+## Issue Links
+### Blocks (<count>)
+<per-ticket block>
+
+### Is Blocked By (<count>)
+<per-ticket block with PR state>
+
+### Relates To (<count>)
+<per-ticket block>
+
+### Duplicates / Clones
+<per-ticket block>
+
+## Epic Context
+### Epic <EPIC-KEY> — <summary>
+- Status: <status>
+- Description: <full>
+- Comments: <chronological>
+- Validation Journey: <section or None>
+
+### Siblings In-Flight (<count>)
+- <KEY> — <status> — <assignee> — <summary>  **[FLAG: in progress by other assignee]**
+
+### Other Siblings (<count>)
+- <KEY> — <status> — <summary>
+
+## Subtasks (<count>)
+- <KEY> — <status> — <assignee> — <summary>
+
+## Summary for Downstream
+- Full ticket count pulled: <N>
+- Blockers still open: <list>
+- Related in-flight work: <list>
+- Relevant PRs: <list with state>
+```
+
+## Rules
+
+- Never summarize or truncate the primary ticket's description or Validation Journey.
+- Never skip a link type, even if it seems unrelated — the agent downstream decides relevance.
+- If a linked ticket returns an access error, capture the error and continue. Do not abort the read.
+- Flag in-flight sibling work prominently so the caller can avoid duplicate implementation.
+- If the ticket has no epic parent, state this explicitly — do not silently skip Phase 5.
+- Output is pure context. This skill never modifies the ticket.

package/plugins/lisa-cursor/skills/jira-read-ticket/scripts/download-attachment.sh

@@ -0,0 +1,110 @@
+#!/usr/bin/env bash
+# download-attachment.sh — Download a JIRA attachment to a local file.
+#
+# Usage:
+#   bash download-attachment.sh <ATTACHMENT_ID_OR_URL> <OUTPUT_PATH>
+#
+# Why this helper exists:
+#   The Atlassian MCP server (mcp__atlassian__*) returns attachment metadata
+#   (id, filename, mimeType, size, content URL) on getJiraIssue but provides
+#   no tool to fetch the binary content. This script closes the gap by
+#   hitting the Jira REST API directly with Basic auth, mirroring the
+#   env-var contract already used by jira-evidence/scripts/post-evidence.sh.
+#
+#   See https://jira.atlassian.com/browse/JRACLOUD-97830 for the upstream
+#   gap; remove this helper once Atlassian ships a download tool in the MCP.
+#
+# Required env vars:
+#   JIRA_SERVER     - https://<your-tenant>.atlassian.net
+#   JIRA_LOGIN      - login email
+#   JIRA_API_TOKEN  - API token (https://id.atlassian.com/manage-profile/security/api-tokens)
+#
+# Exit codes:
+#   0  success
+#   1  download failed (HTTP error)
+#   2  missing required env var
+#   3  invalid arguments
+
+set -euo pipefail
+
+if [[ $# -lt 2 ]]; then
+  echo "Usage: download-attachment.sh <ATTACHMENT_ID_OR_URL> <OUTPUT_PATH>" >&2
+  exit 3
+fi
+ID_OR_URL="$1"
+OUTPUT_PATH="$2"
+
+# Resolve credentials: prefer env, fall back to jira-cli config for server/login.
+JIRA_CONFIG="${HOME}/.config/.jira/.config.yml"
+if [[ -z "${JIRA_SERVER:-}" && -f "$JIRA_CONFIG" ]]; then
+  JIRA_SERVER=$(grep '^server:' "$JIRA_CONFIG" | awk '{print $2}')
+fi
+if [[ -z "${JIRA_LOGIN:-}" && -f "$JIRA_CONFIG" ]]; then
+  JIRA_LOGIN=$(grep '^login:' "$JIRA_CONFIG" | awk '{print $2}')
+fi
+
+for VAR in JIRA_SERVER JIRA_LOGIN JIRA_API_TOKEN; do
+  if [[ -z "${!VAR:-}" ]]; then
+    echo "ERROR: $VAR is not set." >&2
+    echo "Required env vars: JIRA_SERVER, JIRA_LOGIN, JIRA_API_TOKEN." >&2
+    echo "Generate an API token: https://id.atlassian.com/manage-profile/security/api-tokens" >&2
+    exit 2
+  fi
+done
+
+OUTPUT_DIR=$(dirname "$OUTPUT_PATH")
+if [[ ! -d "$OUTPUT_DIR" ]]; then
+  echo "ERROR: Output directory does not exist: $OUTPUT_DIR" >&2
+  exit 3
+fi
+
+if [[ "$ID_OR_URL" == http*://* ]]; then
+  ATTACHMENT_URL="$ID_OR_URL"
+else
+  ATTACHMENT_URL="${JIRA_SERVER%/}/rest/api/3/attachment/content/$ID_OR_URL"
+fi
+
+JIRA_AUTH=$(printf '%s' "$JIRA_LOGIN:$JIRA_API_TOKEN" | base64 | tr -d '\n')
+
+# Atlassian responds 302 to a signed URL on media.atlassian.com that has its
+# own auth and rejects Basic. Two-step: capture Location, then GET unauthed.
+HEADERS_FILE=$(mktemp)
+trap 'rm -f "$HEADERS_FILE"' EXIT
+
+HTTP_CODE=$(curl -sS -o /dev/null -w '%{http_code}' \
+  --max-redirs 0 \
+  -D "$HEADERS_FILE" \
+  -H "Authorization: Basic $JIRA_AUTH" \
+  -H "Accept: */*" \
+  "$ATTACHMENT_URL" || true)
+
+case "$HTTP_CODE" in
+  302|303|307)
+    SIGNED_URL=$(awk '/^[Ll]ocation:/{sub(/^[Ll]ocation:[ \t]*/,""); sub(/\r$/,""); print; exit}' "$HEADERS_FILE")
+    if [[ -z "$SIGNED_URL" ]]; then
+      echo "ERROR: Got HTTP $HTTP_CODE but no Location header in response." >&2
+      exit 1
+    fi
+    curl -sSf -o "$OUTPUT_PATH" "$SIGNED_URL" || { echo "ERROR: Download from signed URL failed." >&2; exit 1; }
+    ;;
+  200)
+    curl -sSf -o "$OUTPUT_PATH" \
+      -H "Authorization: Basic $JIRA_AUTH" \
+      -H "Accept: */*" \
+      "$ATTACHMENT_URL" || { echo "ERROR: Direct download from $ATTACHMENT_URL failed." >&2; exit 1; }
+    ;;
+  401|403)
+    echo "ERROR: Authentication failed (HTTP $HTTP_CODE). Verify JIRA_LOGIN and JIRA_API_TOKEN." >&2
+    exit 1
+    ;;
+  404)
+    echo "ERROR: Attachment not found at $ATTACHMENT_URL (HTTP 404). Verify the ID and your access." >&2
+    exit 1
+    ;;
+  *)
+    echo "ERROR: Unexpected HTTP $HTTP_CODE from $ATTACHMENT_URL" >&2
+    exit 1
+    ;;
+esac
+
+echo "  ✓ Downloaded -> $OUTPUT_PATH"