atlasdocs-jira 0.9.0__tar.gz

atlasdocs_jira-0.9.0/PKG-INFO

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: atlasdocs-jira
+Version: 0.9.0
+Summary: Jira integration scripts for atlasdocs-theme
+Author-email: Jason Oliver <jason.oliver@cern.ch>
+License-Expression: Apache-2.0
+Requires-Python: >=3.9
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: requests>=2.28

atlasdocs_jira-0.9.0/atlasdocs_jira/__init__.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+
+def __getattr__(name: str):
+    if name == "create_jira_pages":
+        from .prepare_jira_pages import create_jira_pages
+        return create_jira_pages
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__ = ["create_jira_pages"]

atlasdocs_jira-0.9.0/atlasdocs_jira/fetch_jira.py

@@ -0,0 +1,317 @@
+from __future__ import annotations
+
+"""
+Fetch Jira project issues and save them as JSON files.
+
+Reads which projects to fetch from jira.toml in the hub directory.
+Writes one file per project:
+    data/jira/{KEY}.json
+
+Credentials: set JIRA_TOKEN (personal access token) or
+             JIRA_USER + JIRA_PASSWORD in the environment.
+
+Usage examples
+--------------
+Fetch all projects from jira.toml:
+    python -m atlasdocs_jira.fetch_jira
+
+Specific projects:
+    python -m atlasdocs_jira.fetch_jira --projects ATLASDOC
+    python -m atlasdocs_jira.fetch_jira --projects ATLASDOC,ATWIKIPHYS
+
+Custom JQL query (saves to data/jira/tickets.json):
+    python -m atlasdocs_jira.fetch_jira --jql "project = FOO AND status = Open"
+
+Only issues created in the last 3 years:
+    python -m atlasdocs_jira.fetch_jira --since -3y
+
+List accessible projects:
+    python -m atlasdocs_jira.fetch_jira --list-projects
+    python -m atlasdocs_jira.fetch_jira --list-projects atlas
+
+Re-fetch even if cached:
+    python -m atlasdocs_jira.fetch_jira --refresh
+
+Dry-run (print first 10 tickets, don't save):
+    python -m atlasdocs_jira.fetch_jira --dry-run
+
+Pixi (args after --):
+    pixi run fetch-jira
+    pixi run fetch-jira -- --projects ATLASDOC
+"""
+
+import argparse
+import base64
+import json
+import os
+import re
+import sys
+import time
+import tomllib
+import urllib.parse
+import urllib.request
+from datetime import date, timedelta
+from pathlib import Path
+
+from dotenv import load_dotenv
+load_dotenv(Path('.env').resolve())
+
+# ── Configuration ──────────────────────────────────────────────────────────────
+
+JIRA_SITE = "https://its.cern.ch/jira"
+DATA_DIR = "data/jira"
+JIRA_CONFIG_FILE = "jira.toml"
+PAGE_SIZE = 1000
+REQUEST_DELAY = 0.3
+
+FIELDS = [
+    "summary", "description", "status", "priority",
+    "assignee", "reporter", "created", "updated",
+    "labels", "components", "issuetype", "resolution",
+    "resolutiondate", "comment",
+]
+
+
+# ── Config loading ─────────────────────────────────────────────────────────────
+
+def load_jira_config(hub_dir: str = ".") -> dict:
+    """Load jira.toml. Returns {projects: [{key, label}], site}."""
+    config_path = Path(hub_dir) / JIRA_CONFIG_FILE
+    if not config_path.exists():
+        return {"projects": [], "site": JIRA_SITE}
+    with open(config_path, "rb") as f:
+        data = tomllib.load(f)
+    return {
+        "projects": data.get("projects", []),
+        "site": data.get("site", JIRA_SITE),
+    }
+
+
+# ── Credentials ────────────────────────────────────────────────────────────────
+
+def load_credentials() -> tuple[str, str, bool]:
+    """Return (user, secret, is_token). Exits on missing credentials."""
+    user     = os.environ.get("JIRA_USER", "")
+    token    = os.environ.get("JIRA_TOKEN")
+    password = os.environ.get("JIRA_PASSWORD")
+    if token:
+        return user, token, True
+    if password:
+        if not user:
+            sys.exit("Error: JIRA_USER must be set when using JIRA_PASSWORD.")
+        return user, password, False
+    sys.exit("Error: JIRA_TOKEN or JIRA_PASSWORD not set in environment.")
+
+
+def _auth_header(user: str, secret: str, is_token: bool) -> str:
+    if is_token:
+        return f"Bearer {secret}"
+    return "Basic " + base64.b64encode(f"{user}:{secret}".encode()).decode()
+
+
+# ── HTTP ───────────────────────────────────────────────────────────────────────
+
+def _get(auth: str, url: str) -> dict:
+    req = urllib.request.Request(url, headers={
+        "Authorization": auth,
+        "Accept": "application/json",
+    })
+    with urllib.request.urlopen(req, timeout=60) as resp:
+        return json.loads(resp.read())
+
+
+# ── Date helpers ───────────────────────────────────────────────────────────────
+
+def _since_to_jql_date(since: str) -> str:
+    """Convert -3y / -6m / -2w / -30d or ISO date to a quoted JQL date string."""
+    m = re.fullmatch(r"-?(\d+)([ymwd])", since)
+    if not m:
+        return f'"{since}"'
+    n, unit = int(m.group(1)), m.group(2)
+    today = date.today()
+    if unit == "y":
+        cutoff = today.replace(year=today.year - n)
+    elif unit == "m":
+        month = today.month - n
+        year  = today.year + (month - 1) // 12
+        month = (month - 1) % 12 + 1
+        cutoff = today.replace(year=year, month=month)
+    elif unit == "w":
+        cutoff = today - timedelta(weeks=n)
+    else:
+        cutoff = today - timedelta(days=n)
+    return f'"{cutoff.isoformat()}"'
+
+
+# ── Fetch ──────────────────────────────────────────────────────────────────────
+
+def fetch_projects(auth: str, site: str) -> list[dict]:
+    return sorted(_get(auth, f"{site}/rest/api/2/project"), key=lambda p: p["key"])
+
+
+def fetch_page(auth: str, site: str, jql: str, start_at: int) -> dict:
+    params = urllib.parse.urlencode({
+        "jql": jql,
+        "startAt": start_at,
+        "maxResults": PAGE_SIZE,
+        "fields": ",".join(FIELDS),
+    })
+    return _get(auth, f"{site}/rest/api/2/search?{params}")
+
+
+def fetch_all(auth: str, site: str, jql: str) -> list[dict]:
+    tickets: list[dict] = []
+    start_at = 0
+    while True:
+        print(f"[jira]   {start_at}–{start_at + PAGE_SIZE - 1}…", end="", flush=True)
+        data = fetch_page(auth, site, jql, start_at)
+        issues = data.get("issues", [])
+        total  = data.get("total", 0)
+        tickets.extend(issues)
+        print(f" +{len(issues)} ({len(tickets)}/{total})")
+        if not issues or len(tickets) >= total:
+            break
+        start_at += len(issues)
+        time.sleep(REQUEST_DELAY)
+    return tickets
+
+
+def _print_row(t: dict) -> None:
+    f        = t.get("fields", {})
+    status   = (f.get("status")   or {}).get("name", "?")
+    priority = (f.get("priority") or {}).get("name", "?")
+    summary  = (f.get("summary")  or "").strip()
+    updated  = (f.get("updated")  or "")[:10]
+    print(f"  {t['key']:<18}  [{status:<12}]  [{priority:<16}]  {updated}  {summary[:70]}")
+
+
+# ── Save ───────────────────────────────────────────────────────────────────────
+
+def save_project(key: str, tickets: list[dict], data_dir: str) -> Path:
+    out_dir = Path(data_dir)
+    out_dir.mkdir(parents=True, exist_ok=True)
+    out_path = out_dir / f"{key}.json"
+    out_path.write_text(json.dumps(tickets, indent=2, ensure_ascii=False))
+    return out_path
+
+
+# ── Main ───────────────────────────────────────────────────────────────────────
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Fetch Jira project issues and save as JSON.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=__doc__.split("Usage examples")[1] if __doc__ and "Usage examples" in __doc__ else "",
+    )
+    parser.add_argument("--projects", metavar="KEY1,KEY2",
+                        help="Comma-separated project keys (default: all projects in jira.toml)")
+    parser.add_argument("--jql", help="Custom JQL query (saves to data/jira/tickets.json)")
+    parser.add_argument("--since", metavar="DATE_OR_OFFSET",
+                        help="Only fetch issues created on/after this date (e.g. -3y, 2022-01-01)")
+    parser.add_argument("--list-projects", nargs="?", const="", metavar="PATTERN",
+                        help="List accessible projects, optionally filtered by name/key pattern")
+    parser.add_argument("--refresh", action="store_true",
+                        help="Re-fetch even if cache exists")
+    parser.add_argument("--dry-run", action="store_true",
+                        help="Fetch 10 tickets, print summaries, exit without saving")
+    parser.add_argument("--site", default=None,
+                        help=f"Jira base URL (default: from jira.toml or {JIRA_SITE})")
+    parser.add_argument("--data-dir", default=DATA_DIR,
+                        help=f"Output directory (default: {DATA_DIR})")
+    args = parser.parse_args()
+
+    hub_dir = str(Path.cwd())
+    config  = load_jira_config(hub_dir)
+    site    = args.site or config["site"]
+
+    user, secret, is_token = load_credentials()
+    auth = _auth_header(user, secret, is_token)
+
+    resolved_data_dir = str(Path(hub_dir) / args.data_dir)
+
+    # ── list-projects ──────────────────────────────────────────────────────────
+    if args.list_projects is not None:
+        pattern  = args.list_projects.lower()
+        projects = fetch_projects(auth, site)
+        if pattern:
+            projects = [p for p in projects
+                        if pattern in p["key"].lower() or pattern in p["name"].lower()]
+        print(f"{'KEY':<24} {'TYPE':<14} {'ID':<8} NAME")
+        print("-" * 80)
+        for p in projects:
+            print(f"  {p['key']:<22} {p.get('projectTypeKey',''):<14} {p['id']:<8} {p['name']}")
+        print(f"\n{len(projects)} project(s) shown")
+        return
+
+    # ── custom JQL mode ────────────────────────────────────────────────────────
+    if args.jql:
+        out_file = Path(resolved_data_dir) / "tickets.json"
+        if out_file.exists() and not args.refresh:
+            existing = json.loads(out_file.read_text())
+            print(f"Cache hit: {len(existing):,} tickets in {out_file}  (use --refresh to re-fetch)")
+            return
+        if args.dry_run:
+            data    = fetch_page(auth, site, args.jql, 0)
+            tickets = data.get("issues", [])[:10]
+            print(f"DRY RUN  JQL: {args.jql}\nTotal: {data.get('total',0):,}  (showing {len(tickets)})\n")
+            for t in tickets:
+                _print_row(t)
+            return
+        tickets = fetch_all(auth, site, args.jql)
+        out_file.parent.mkdir(parents=True, exist_ok=True)
+        out_file.write_text(json.dumps(tickets, indent=2, ensure_ascii=False))
+        print(f"\nSaved {len(tickets):,} tickets → {out_file}")
+        return
+
+    # ── per-project mode ───────────────────────────────────────────────────────
+    if args.projects:
+        keys = [k.strip().upper() for k in args.projects.split(",") if k.strip()]
+    else:
+        keys = [p["key"] for p in config["projects"]]
+        if not keys:
+            parser.error("No projects specified — use --projects or add entries to jira.toml")
+
+    since_clause = f" AND created >= {_since_to_jql_date(args.since)}" if args.since else ""
+
+    if args.dry_run:
+        jql = f"project = {keys[0]}{since_clause} ORDER BY updated DESC"
+        data    = fetch_page(auth, site, jql, 0)
+        tickets = data.get("issues", [])[:10]
+        print(f"DRY RUN — {keys[0]}  JQL: {jql}\nTotal: {data.get('total',0):,}  (showing {len(tickets)})\n")
+        for t in tickets:
+            _print_row(t)
+        return
+
+    print(f"[jira] Fetching {len(keys)} project(s) → {resolved_data_dir}")
+    grand_total = skipped = errors = 0
+    for i, key in enumerate(keys, 1):
+        out_file = Path(resolved_data_dir) / f"{key}.json"
+        if out_file.exists() and not args.refresh:
+            existing = json.loads(out_file.read_text())
+            skipped += 1
+            grand_total += len(existing)
+            print(f"[jira] [{i}/{len(keys)}] {key}: {len(existing):,} tickets (cached)")
+            continue
+        jql = f"project = {key}{since_clause} ORDER BY updated DESC"
+        try:
+            tickets = fetch_all(auth, site, jql)
+        except Exception as e:
+            print(f"[jira] [{i}/{len(keys)}] {key}: ERROR — {e}")
+            errors += 1
+            continue
+        if tickets:
+            save_project(key, tickets, resolved_data_dir)
+            grand_total += len(tickets)
+            print(f"[jira] [{i}/{len(keys)}] {key}: {len(tickets):,} tickets → {out_file}")
+        else:
+            print(f"[jira] [{i}/{len(keys)}] {key}: no tickets")
+
+    fetched = len(keys) - skipped - errors
+    print(f"[jira] Total: {grand_total:,} tickets ({fetched} fetched, {skipped} cached{', ' + str(errors) + ' error(s)' if errors else ''})")
+
+    if errors:
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

atlasdocs_jira-0.9.0/atlasdocs_jira/prepare_jira_pages.py

@@ -0,0 +1,264 @@
+from __future__ import annotations
+
+"""
+Generate MkDocs pages for Jira projects from fetched JSON files.
+
+Reads which projects to include from jira.toml in the hub directory.
+For each project that has a data/jira/{KEY}.json file:
+  - Copies the JSON to docs/jira/projects/{KEY}/{KEY}.json
+  - Writes docs/jira/projects/{KEY}/index.md (JS loader page)
+Writes docs/jira/index.md as a hub page linking to all projects.
+Writes config/zensical/nav-jira.toml with the Jira nav section.
+
+Usage examples
+--------------
+    python -m atlasdocs_jira.prepare_jira_pages
+
+Pixi:
+    pixi run prepare-jira-pages
+"""
+
+import json
+import os
+import shutil
+import sys
+import tomllib
+from datetime import datetime
+from pathlib import Path
+
+
+# ── Configuration ──────────────────────────────────────────────────────────────
+
+JIRA_CONFIG_FILE = "jira.toml"
+DATA_DIR = "data/jira"
+DOCS_OUTPUT_DIR = "docs/jira"
+NAV_OUTPUT_FILE = "config/zensical/nav-jira.toml"
+
+JIRA_SITE = "https://its.cern.ch/jira"
+
+PAGE_ICON = "lucide/ticket"
+PAGE_TAGS_BASE = ['"★ JIRA"']
+
+
+# ── Config loading ─────────────────────────────────────────────────────────────
+
+def load_jira_config(hub_dir: str = ".") -> list[dict]:
+    """Load jira.toml and return [{key, label}, ...]."""
+    config_path = Path(hub_dir) / JIRA_CONFIG_FILE
+    if not config_path.exists():
+        return []
+    with open(config_path, "rb") as f:
+        data = tomllib.load(f)
+    site = data.get("site", JIRA_SITE)
+    return [
+        {
+            "key":   p["key"].upper(),
+            "label": p.get("label", p["key"].upper()),
+            "site":  site,
+        }
+        for p in data.get("projects", [])
+    ]
+
+
+# ── Stats helpers ──────────────────────────────────────────────────────────────
+
+def _project_stats(json_path: str) -> dict:
+    """Return {total, open, closed, first_year, year_counts} from a project JSON."""
+    if not os.path.exists(json_path):
+        return {}
+    with open(json_path) as f:
+        try:
+            issues = json.load(f)
+        except Exception:
+            return {}
+
+    total  = len(issues)
+    open_  = sum(1 for i in issues if i.get("fields", {}).get("resolution") is None)
+    closed = total - open_
+
+    years = [int(i["fields"]["created"][:4])
+             for i in issues if i.get("fields", {}).get("created")]
+    first_year = min(years) if years else None
+
+    year_map: dict[int, int] = {}
+    for y in years:
+        year_map[y] = year_map.get(y, 0) + 1
+    year_counts = sorted(year_map.items())
+
+    return {
+        "total": total,
+        "open": open_,
+        "closed": closed,
+        "first_year": first_year,
+        "year_counts": year_counts,
+    }
+
+
+# ── Frontmatter ────────────────────────────────────────────────────────────────
+
+def _frontmatter(title: str, tags: list[str] | None = None) -> str:
+    lines = [
+        "---",
+        f"title: {title}",
+        f"icon: {PAGE_ICON}",
+        "hide:",
+        "  - toc",
+        "pagestatus: script",
+        f"dategenerated: \"{datetime.now().strftime('%Y-%m-%d')}\"",
+    ]
+    if tags:
+        lines.append("tags:")
+        for tag in tags:
+            lines.append(f"  - {tag}")
+    lines += ["---", ""]
+    return "\n".join(lines)
+
+
+# ── Per-project page ───────────────────────────────────────────────────────────
+
+def _generate_project_page(
+    output_dir: str,
+    key: str,
+    label: str,
+    data_dir: str,
+    site: str,
+) -> bool:
+    """Generate docs/jira/projects/{KEY}/index.md and copy JSON. Returns True on success."""
+    src_json = os.path.join(data_dir, f"{key}.json")
+    if not os.path.exists(src_json):
+        print(f"[SKIP] {key}: data/jira/{key}.json not found (run fetch-jira first)")
+        return False
+
+    os.makedirs(output_dir, exist_ok=True)
+
+    dst_json = os.path.join(output_dir, f"{key}.json")
+    shutil.copy2(src_json, dst_json)
+
+    stats = _project_stats(src_json)
+    total = stats.get("total", 0)
+
+    fm = _frontmatter(
+        title=f'"{label}"',
+        tags=list(PAGE_TAGS_BASE) + [f'"▶ {key}"'],
+    )
+    md = [
+        fm,
+        f'<div id="jira-project"',
+        f'     data-json="./{key}.json"',
+        f'     data-project="{key}"',
+        f'     data-jira-base="{site}"></div>',
+        '<script src="/assets/javascripts/jira_project_loader.js"></script>',
+        "",
+    ]
+    with open(os.path.join(output_dir, "index.md"), "w") as f:
+        f.write("\n".join(md))
+
+    print(f"[DONE] docs/jira/projects/{key}/index.md — {total} issues")
+    return True
+
+
+# ── Hub page ───────────────────────────────────────────────────────────────────
+
+def _generate_hub_page(projects: list[dict], output_path: str, data_dir: str) -> None:
+    """Write docs/jira/index.md with grid cards for each project."""
+    os.makedirs(os.path.dirname(output_path), exist_ok=True)
+
+    fm = _frontmatter(title='"Jira Projects"')
+    lines = [fm, '<div class="grid cards" markdown>', ""]
+
+    for p in projects:
+        key   = p["key"]
+        label = p["label"]
+        site  = p["site"]
+        stats = _project_stats(os.path.join(data_dir, f"{key}.json"))
+        total = stats.get("total", "")
+        open_ = stats.get("open", "")
+        desc  = f"{open_} open · {total} total" if total else ""
+
+        lines += [
+            f"-   **[{label}](projects/{key}/)**",
+            "",
+            f"    ---",
+            "",
+        ]
+        if desc:
+            lines += [f"    {desc}", ""]
+        lines += [
+            f"    [:lucide-external-link: {key}]({site}/projects/{key})  "
+            f"[:lucide-list: Browse](projects/{key}/)",
+            "",
+        ]
+
+    lines += ["</div>", ""]
+
+    with open(output_path, "w") as f:
+        f.write("\n".join(lines))
+
+    print(f"[DONE] {output_path} — {len(projects)} projects")
+
+
+# ── Nav ────────────────────────────────────────────────────────────────────────
+
+def _generate_nav(projects: list[dict], output_path: str) -> None:
+    """Write config/zensical/nav-jira.toml."""
+    os.makedirs(os.path.dirname(output_path), exist_ok=True)
+
+    lines = ["nav = [", '  { "Jira" = [']
+    lines.append('    { "Overview" = "jira/index.md" },')
+    for p in projects:
+        key   = p["key"]
+        label = p["label"]
+        lines.append(f'    {{ "{label}" = "jira/projects/{key}/index.md" }},')
+    lines += ["  ]},", "]", ""]
+
+    with open(output_path, "w") as f:
+        f.write("\n".join(lines))
+
+    print(f"[DONE] {output_path} — {len(projects)} projects")
+
+
+# ── Prepare ────────────────────────────────────────────────────────────────────
+
+def create_jira_pages(
+    hub_dir: str = ".",
+    data_dir: str | None = None,
+    docs_output_dir: str | None = None,
+    nav_output_file: str | None = None,
+) -> None:
+    """Generate MkDocs pages for Jira projects fetched into data/jira/."""
+    hub = Path(hub_dir)
+    resolved_data_dir  = str(hub / (data_dir or DATA_DIR))
+    resolved_docs_dir  = str(hub / (docs_output_dir or DOCS_OUTPUT_DIR))
+    resolved_nav_file  = str(hub / (nav_output_file or NAV_OUTPUT_FILE))
+
+    config_projects = load_jira_config(hub_dir)
+    if not config_projects:
+        print("[INFO] No projects found in jira.toml — nothing to generate.")
+        return
+
+    generated: list[dict] = []
+    for p in config_projects:
+        output_dir = os.path.join(resolved_docs_dir, "projects", p["key"])
+        ok = _generate_project_page(
+            output_dir=output_dir,
+            key=p["key"],
+            label=p["label"],
+            data_dir=resolved_data_dir,
+            site=p["site"],
+        )
+        if ok:
+            generated.append(p)
+
+    _generate_hub_page(generated, os.path.join(resolved_docs_dir, "index.md"), resolved_data_dir)
+    _generate_nav(generated, resolved_nav_file)
+
+    print(f"[FINISH] Generated {len(generated)} Jira project page(s).")
+
+
+def main() -> None:
+    hub_dir = Path(sys.argv[1]).resolve() if len(sys.argv) > 1 else Path.cwd()
+    create_jira_pages(hub_dir=str(hub_dir))
+
+
+if __name__ == "__main__":
+    main()

atlasdocs_jira-0.9.0/pixi.toml

@@ -0,0 +1,19 @@
+[workspace]
+name = "atlasdocs-jira-dev"
+description = "Development environment for the atlasdocs-jira package"
+channels = ["conda-forge"]
+platforms = ["osx-arm64", "linux-64"]
+
+[dependencies]
+python = ">=3.11,<3.15"
+uv = ">=0.4"
+requests = ">=2.0"
+
+[tasks.build]
+cmd = "uv build"
+description = "Build wheel and sdist"
+
+[tasks.newrelease]
+cmd = "bash scripts/release.sh"
+depends-on = []
+description = "Bump version in pyproject.toml, build, and publish to PyPI"

atlasdocs_jira-0.9.0/pyproject.toml

@@ -0,0 +1,21 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "atlasdocs-jira"
+version = "0.9.0"
+description = "Jira integration scripts for atlasdocs-theme"
+authors = [
+  { name = "Jason Oliver", email = "jason.oliver@cern.ch" }
+]
+license = "Apache-2.0"
+requires-python = ">=3.9"
+dependencies = ["requests>=2.28", "python-dotenv>=1.0"]
+
+[tool.hatch.build.targets.wheel]
+include = ["atlasdocs_jira"]
+
+[project.scripts]
+fetch-jira        = "atlasdocs_jira.fetch_jira:main"
+prepare-jira-pages = "atlasdocs_jira.prepare_jira_pages:main"

atlasdocs_jira-0.9.0/scripts/release.sh

@@ -0,0 +1,79 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+PYPROJECT="$(dirname "$0")/../pyproject.toml"
+PYPROJECT="$(realpath "$PYPROJECT")"
+PKG_DIR="$(dirname "$PYPROJECT")"
+
+current_version() {
+  grep '^version' "$PYPROJECT" | sed 's/version = "\(.*\)"/\1/'
+}
+
+bump_version() {
+  local part="${1:-patch}"
+  local ver
+  ver="$(current_version)"
+  IFS='.' read -r major minor patch <<< "$ver"
+  case "$part" in
+    major) major=$((major + 1)); minor=0; patch=0 ;;
+    minor) minor=$((minor + 1)); patch=0 ;;
+    patch) patch=$((patch + 1)) ;;
+    *) echo "Unknown part: $part (use major|minor|patch)"; exit 1 ;;
+  esac
+  echo "${major}.${minor}.${patch}"
+}
+
+set_version() {
+  local new="$1"
+  sed -i '' "s/^version = \".*\"/version = \"${new}\"/" "$PYPROJECT"
+  echo "Version set to ${new}"
+}
+
+PART="${1:-}"
+SKIP_PUBLISH="${2:-}"
+CURRENT="$(current_version)"
+
+if [[ -z "$PART" ]]; then
+  echo "Current version: ${CURRENT}"
+  echo "Increment:  [1] patch  [2] minor  [3] major"
+  read -r -p "Choice [1]: " choice
+  case "${choice:-1}" in
+    1|patch) PART="patch" ;;
+    2|minor) PART="minor" ;;
+    3|major) PART="major" ;;
+    *) echo "Invalid choice."; exit 1 ;;
+  esac
+fi
+
+if [[ "$PART" == exact:* ]]; then
+  NEW_VERSION="${PART#exact:}"
+else
+  NEW_VERSION="$(bump_version "$PART")"
+fi
+
+echo "Current: ${CURRENT}  →  New: ${NEW_VERSION}  (${PART})"
+read -r -p "Continue? [y/N] " confirm
+[[ "$confirm" =~ ^[Yy]$ ]] || { echo "Aborted."; exit 0; }
+
+set_version "$NEW_VERSION"
+
+echo ""
+echo "▶ uv build"
+uv build --project "$PKG_DIR"
+
+if [[ "$SKIP_PUBLISH" != "--no-publish" ]]; then
+  echo ""
+  echo "▶ uv publish"
+  uv publish dist/atlasdocs_jira-"${NEW_VERSION}"*.whl dist/atlasdocs_jira-"${NEW_VERSION}".tar.gz
+fi
+
+echo ""
+echo "▶ git add + commit + tag"
+REPO_ROOT="$(git -C "$PKG_DIR" rev-parse --show-toplevel)"
+git -C "$REPO_ROOT" add "$PYPROJECT"
+git -C "$REPO_ROOT" commit -m "chore(jira): release ${NEW_VERSION}"
+git -C "$REPO_ROOT" tag "atlasdocs-jira/v${NEW_VERSION}"
+
+echo ""
+echo "✓ Released atlasdocs-jira ${NEW_VERSION}"
+echo "  Push with: git push && git push --tags"