Complete async rewrite with bulk export, custom fields, and JQL support

.github/workflows/ci.yml

@@ -15,29 +15,18 @@ jobs:
         python-version: ['3.8', '3.9', '3.10', '3.11', '3.12']
 
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
 
-    - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v4
+    - uses: astral-sh/setup-uv@v7
       with:
+        enable-cache: true
         python-version: ${{ matrix.python-version }}
 
-    - name: Cache pip packages
-      uses: actions/cache@v3
-      with:
-        path: ~/.cache/pip
-        key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt', '**/pyproject.toml') }}
-        restore-keys: |
-          ${{ runner.os }}-pip-
-
     - name: Install dependencies
-      run: |
-        python -m pip install --upgrade pip
-        pip install .[dev]
+      run: uv sync --locked --all-extras --dev
 
     - name: Run tests with coverage
-      run: |
-        pytest --cov=src/jarkdown --cov-report=term-missing --cov-report=xml
+      run: uv run pytest --cov=src/jarkdown --cov-report=term-missing --cov-report=xml
 
     - name: Upload coverage reports to Codecov
       if: matrix.python-version == '3.11'
@@ -52,30 +41,22 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
 
-    - name: Set up Python
-      uses: actions/setup-python@v4
+    - uses: astral-sh/setup-uv@v7
       with:
-        python-version: '3.11'
-
-    - name: Install dependencies
-      run: |
-        python -m pip install --upgrade pip
-        pip install ruff
+        enable-cache: true
 
     - name: Lint with ruff
       run: |
-        # Stop the build if there are Python syntax errors or undefined names
-        ruff check . --select=E9,F63,F7,F82
-        # exit-zero treats all errors as warnings
-        ruff check . --exit-zero || true
+        uvx ruff check . --select=E9,F63,F7,F82
+        uvx ruff check . --exit-zero || true
 
   security:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
 
     - name: Run Trivy vulnerability scanner
       uses: aquasecurity/trivy-action@master
@@ -97,23 +78,19 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
 
-    - name: Set up Python
-      uses: actions/setup-python@v4
+    - uses: astral-sh/setup-uv@v7
       with:
-        python-version: '3.11'
+        enable-cache: true
 
     - name: Install dependencies
       run: |
-        python -m pip install --upgrade pip
-        pip install -r docs/requirements.txt
-        pip install -e .
+        uv sync --locked
+        uv pip install -r docs/requirements.txt
 
     - name: Build documentation
-      run: |
-        sphinx-build -b html docs/source docs/build/html --keep-going
+      run: uv run sphinx-build -b html docs/source docs/build/html --keep-going
 
     - name: Check for broken links
-      run: |
-        sphinx-build -b linkcheck docs/source docs/build/linkcheck
+      run: uv run sphinx-build -b linkcheck docs/source docs/build/linkcheck

.github/workflows/publish-to-pypi.yml

@@ -1,4 +1,3 @@
-# .github/workflows/publish-to-pypi.yml
 name: Publish to PyPI
 
 on:
@@ -9,23 +8,16 @@ jobs:
   publish:
     runs-on: ubuntu-latest
     permissions:
-      # This permission is mandatory for trusted publishing
       id-token: write
     steps:
       - uses: actions/checkout@v4
 
-      - name: Set up Python
-        uses: actions/setup-python@v4
+      - uses: astral-sh/setup-uv@v7
         with:
-          python-version: "3.11"
-
-      - name: Install dependencies
-        run: |
-          python -m pip install --upgrade pip
-          pip install build
+          enable-cache: true
 
       - name: Build package
-        run: python -m build
+        run: uv build
 
       - name: Publish package to PyPI
         uses: pypa/gh-action-pypi-publish@release/v1

.gitignore

@@ -50,6 +50,10 @@ claude-tmp/
 temp/
 tmp/
 
+# Jira issue output (from test runs)
+TEST-*/
+VERIFICATION.md
+
 # Documentation builds
 docs/_build/
 docs/build/

.vbw-planning/.gitignore

@@ -0,0 +1,46 @@
+# VBW transient runtime artifacts
+.execution-state.json
+.execution-state.json.tmp
+.context-*.md
+.contracts/
+.locks/
+.token-state/
+
+# Session & agent tracking
+.vbw-session
+.active-agent
+.active-agent-count
+.active-agent-count.lock/
+.agent-pids
+
+# Metrics & cost tracking
+.metrics/
+.cost-ledger.json
+
+# Caching
+.cache/
+
+# Artifacts & events (v2/v3 feature-gated)
+.artifacts/
+.events/
+.event-log.jsonl
+
+# Snapshots & recovery
+.snapshots/
+
+# Logging & markers
+.hook-errors.log
+.compaction-marker
+.session-log.jsonl
+.session-log.jsonl.tmp
+.notification-log.jsonl
+.watchdog-pid
+.watchdog.log
+.claude-md-migrated
+.tmux-mode-patched
+
+# Baselines
+.baselines/
+
+# Codebase mapping
+codebase/

.vbw-planning/.todo-flat-migrated

@@ -0,0 +1 @@
+1

.vbw-planning/PROJECT.md

@@ -0,0 +1,37 @@
+# jarkdown
+
+Export Jira Cloud issues to Markdown with attachments. A Python CLI tool that fetches issue data from the Jira REST API, downloads all attachments locally, and produces rich Markdown files with YAML frontmatter, inline images, and full comment history.
+
+**Core value:** Complete, offline-readable Jira issue archives in Markdown format.
+
+## Requirements
+
+### Validated
+- Single issue export to Markdown with YAML frontmatter
+- Attachment download with local path replacement
+- Comment export (HTML + ADF support)
+
+### Active
+- [ ] Full Jira field coverage (issue links, subtasks, time tracking, progress, votes, etc.)
+- [ ] Custom field mapping and rendering
+- [ ] Better ADF parsing (tables, panels, expand blocks, emoji)
+- [ ] Bulk export of multiple issues
+- [ ] JQL query support for batch export
+- [ ] Migration to uv package manager
+
+### Out of Scope
+- Real-time sync with Jira
+- Jira write-back / import functionality
+
+## Constraints
+- **Python 3.8+**: Broad compatibility across environments
+- **Minimal dependencies**: Only 4 runtime deps
+- **Existing test suite**: All changes must maintain passing tests
+
+## Key Decisions
+
+| Decision | Rationale | Outcome |
+|----------|-----------|---------|
+| Pipeline architecture | Simple linear data flow | Easy to extend and test |
+| Session-based auth | Reuse connections | Efficient API calls |
+| Exception hierarchy | Clean error handling | Components stay decoupled from CLI |

.vbw-planning/REQUIREMENTS.md

@@ -0,0 +1,37 @@
+# jarkdown Requirements
+
+Defined: 2026-02-17 | Core value: Complete, offline-readable Jira issue archives in Markdown
+
+## v1 Requirements
+
+### Core (Validated)
+- [x] **REQ-01**: Jira REST API v3 integration with authentication (domain standard)
+- [x] **REQ-02**: HTML to Markdown conversion via markdownify (domain standard)
+- [x] **REQ-03**: Attachment download with local path replacement (domain standard)
+- [x] **REQ-04**: YAML frontmatter with issue metadata (domain standard)
+- [x] **REQ-05**: Comment export with ADF and rendered HTML support
+
+### Field Coverage
+- [x] **REQ-06**: Full standard field coverage — project, issuelinks, subtasks, time tracking, progress, worklogs, votes, watches, duedate, environment, statusCategory
+- [x] **REQ-07**: Custom field mapping — configurable rendering of customfield_* entries in markdown output
+
+### ADF Parsing
+- [x] **REQ-08**: Complete ADF support — tables, panels, expand blocks, emoji, inline cards, decision items, task lists
+
+### Bulk Operations
+- [x] **REQ-09**: Bulk export — export multiple issues from a list of keys
+- [x] **REQ-10**: JQL query support — accept JQL queries to find and export matching issues
+
+### Tooling
+- [x] **REQ-11**: Migrate to uv package manager — replace pip with uv for cleaner install and usage
+
+## v2 Requirements
+- [ ] **REQ-12**: Parallel attachment downloads for performance
+- [ ] **REQ-13**: Incremental/delta export (only re-export changed issues)
+- [ ] **REQ-14**: Alternative output formats (JSON, HTML)
+
+## Out of Scope
+
+- Real-time sync with Jira (deliberately excluded — tool is for point-in-time export)
+- Jira write-back / import functionality (deliberately excluded — read-only tool)
+- Jira Server/Data Center support (Cloud-only for now)

.vbw-planning/ROADMAP.md

@@ -0,0 +1,97 @@
+# jarkdown Roadmap
+
+**Goal:** jarkdown
+
+**Scope:** 4 phases
+
+## Progress
+| Phase | Status | Plans | Tasks | Commits |
+|-------|--------|-------|-------|---------|
+| 1 | Complete | 4 | 16 | 14 |
+| 2 | Complete | 4 | 18 | 18 |
+| 3 | Complete | 3 | 10 | 9 |
+| 4 | Complete | 4 | 19 | 17 |
+
+---
+
+## Phase List
+- [x] [Phase 1: Standard Field Coverage](#phase-1-standard-field-coverage)
+- [x] [Phase 2: Custom Fields & ADF](#phase-2-custom-fields-adf)
+- [x] [Phase 3: uv Migration & Tooling](#phase-3-uv-migration-tooling)
+- [x] [Phase 4: Bulk Export & JQL](#phase-4-bulk-export-jql)
+
+---
+
+## Phase 1: Standard Field Coverage
+
+**Goal:** Expand markdown output to cover all standard Jira fields returned by the API, closing the gap identified from PSOP-419
+
+**Requirements:** REQ-06
+
+**Success Criteria:**
+- project name/key included in frontmatter
+- issuelinks rendered as a linked issues section
+- subtasks listed with keys and summaries
+- time tracking fields (estimate, spent, remaining) in frontmatter
+- progress/aggregateprogress shown
+- votes/watches count in frontmatter
+- worklog entries rendered
+- duedate and environment included
+- statusCategory in frontmatter
+- All fields from PSOP-419 that have values appear in output
+
+**Dependencies:** None
+
+---
+
+## Phase 2: Custom Fields & ADF
+
+**Goal:** Support configurable custom field rendering and complete ADF document format parsing
+
+**Requirements:** REQ-07, REQ-08
+
+**Success Criteria:**
+- Custom fields with values rendered in a dedicated section
+- Field name resolution via Jira field metadata API
+- ADF tables converted to Markdown tables
+- ADF panels rendered as blockquotes with headers
+- ADF expand blocks, emoji, inline cards, task lists handled
+- Config file or CLI flag for field selection
+
+**Dependencies:** Phase 1
+
+---
+
+## Phase 3: uv Migration & Tooling
+
+**Goal:** Migrate from pip to uv package manager for cleaner install and usage experience
+
+**Requirements:** REQ-11
+
+**Success Criteria:**
+- uv.lock file replaces pip dependency resolution
+- pyproject.toml updated for uv compatibility
+- README and docs updated with uv install instructions
+- CI workflows updated to use uv
+- Development setup uses uv for venv and dependency management
+
+**Dependencies:** Phase 2
+
+---
+
+## Phase 4: Bulk Export & JQL
+
+**Goal:** Enable exporting multiple issues at once via key lists or JQL queries
+
+**Requirements:** REQ-09, REQ-10
+
+**Success Criteria:**
+- Accept multiple issue keys on CLI
+- Accept --jql flag with JQL query string
+- Batch API calls with rate limiting
+- Summary index file listing all exported issues
+- Progress reporting during bulk operations
+- Error handling for partial failures in batch
+
+**Dependencies:** Phase 3
+