todo-jira-sync 1.0.0__tar.gz

todo_jira_sync-1.0.0/.dockerignore

@@ -0,0 +1,17 @@
+.git
+.github
+.venv
+venv
+__pycache__
+*.pyc
+.pytest_cache
+.ruff_cache
+.mypy_cache
+build
+dist
+*.egg-info
+.env
+*.todojira.json
+tests
+Makefile
+.pre-commit-config.yaml

todo_jira_sync-1.0.0/.env.example

@@ -0,0 +1,35 @@
+# --- Connection -------------------------------------------------------------
+# Jira Cloud base URL (no trailing path), e.g. https://acme.atlassian.net
+JIRA_URL=https://your-domain.atlassian.net
+
+# Auth mode: "basic" for Jira Cloud (email + API token),
+#            "bearer" for Server/Data Center personal access tokens.
+JIRA_AUTH=basic
+
+# For basic auth (Cloud): your account email + an API token from
+# https://id.atlassian.com/manage-profile/security/api-tokens
+JIRA_EMAIL=you@example.com
+JIRA_API_TOKEN=your-api-token
+
+# --- What to sync -----------------------------------------------------------
+JIRA_PROJECT=WEB
+TODO_FILE=todo.todo
+
+# --- Behaviour --------------------------------------------------------------
+# Conflict policy when BOTH sides changed the same field: jira | todo | skip
+CONFLICT=jira
+# Re-add issues to the todo file if they were deleted locally but still in Jira
+PULL_LOCALLY_DELETED=false
+
+# --- Optional: Jira issue-type names (match your project scheme) ------------
+# TYPE_EPIC=Epic
+# TYPE_STORY=Story
+# TYPE_TASK=Task
+# TYPE_SUBTASK=Sub-task
+
+# --- Optional: Todo+ syntax overrides (comma-separated) ---------------------
+# BOX_SYMBOLS=☐,[ ]
+# DONE_SYMBOLS=✔,[x],[X],✓
+# CANCELLED_SYMBOLS=✘,[-]
+# INDENT_UNIT=  
+# CANCELLED_STATUS_NAMES=Cancelled,Canceled,Won't Do,Rejected

todo_jira_sync-1.0.0/.github/dependabot.yaml

@@ -0,0 +1,16 @@
+version: 2
+updates:
+  - package-ecosystem: pip
+    directory: "/"
+    schedule:
+      interval: weekly
+
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly
+
+  - package-ecosystem: docker
+    directory: "/"
+    schedule:
+      interval: weekly

todo_jira_sync-1.0.0/.github/workflows/ci.yaml

@@ -0,0 +1,74 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: ${{ github.head_ref || github.ref_name }}
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Create venv
+        run: uv venv --python 3.12
+
+      - name: Install
+        run: uv pip install -e ".[dev]"
+
+      - name: Auto-fix with ruff
+        run: |
+          uv run ruff check --fix .
+          uv run ruff format .
+
+      - name: Commit auto-fixes
+        run: |
+          if ! git diff --quiet; then
+            git config user.name "github-actions[bot]"
+            git config user.email "github-actions[bot]@users.noreply.github.com"
+            git commit -am "style: auto-fix ruff lint issues"
+            git push
+          fi
+
+  test:
+    needs: lint
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: ${{ github.head_ref || github.ref_name }}
+          fetch-depth: 0  # setuptools-scm needs tags/history
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      # Create a venv that uses *exactly* the matrix interpreter. uv downloads
+      # the version if the runner doesn't have it. Every step below runs via
+      # `uv run`, so it executes inside this venv on the matrix Python.
+      - name: Create venv on Python ${{ matrix.python-version }}
+        run: uv venv --python ${{ matrix.python-version }}
+
+      - name: Install
+        run: uv pip install -e ".[dev]"
+
+      - name: Show interpreter under test
+        run: uv run python --version
+
+      - name: Type check
+        run: uv run mypy todo_jira_sync
+
+      - name: Test
+        run: uv run pytest

todo_jira_sync-1.0.0/.github/workflows/publish-docker.yaml

@@ -0,0 +1,68 @@
+name: Publish container
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository }}
+
+jobs:
+  docker:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write  # push to GitHub Container Registry
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0  # so setuptools-scm can resolve the version
+
+      - name: Resolve version
+        id: version
+        run: |
+          if command -v git >/dev/null && git describe --tags >/dev/null 2>&1; then
+            echo "value=$(git describe --tags --always | sed 's/^v//')" >> "$GITHUB_OUTPUT"
+          else
+            echo "value=0.0.0" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v4
+
+      - name: Set up Buildx
+        uses: docker/setup-buildx-action@v4
+
+      - name: Log in to GHCR
+        uses: docker/login-action@v4
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Image metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          tags: |
+            type=ref,event=branch
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=sha
+
+      - name: Build and push (amd64 + arm64)
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          platforms: linux/amd64,linux/arm64
+          push: true
+          build-args: |
+            VERSION=${{ steps.version.outputs.value }}
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

todo_jira_sync-1.0.0/.github/workflows/publish-pypi.yaml

@@ -0,0 +1,40 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0  # setuptools-scm needs the tag history
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # OIDC for PyPI Trusted Publishing (no API token needed)
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@release/v1

todo_jira_sync-1.0.0/.gitignore

@@ -0,0 +1,27 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+
+# Virtual envs
+.venv/
+venv/
+
+# Tooling caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# Local config & secrets
+.env
+
+# Sync state sidecars (generated next to the todo file)
+*.todojira.json
+
+# Editors / OS
+.vscode/
+.idea/
+.DS_Store

todo_jira_sync-1.0.0/.pre-commit-config.yaml

@@ -0,0 +1,13 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.5.7
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.10.1
+    hooks:
+      - id: mypy
+        additional_dependencies: [types-requests, pydantic-settings, typer]
+        files: ^todo_jira_sync/

todo_jira_sync-1.0.0/AGENTS.md

@@ -0,0 +1,68 @@
+# AGENTS.md
+
+Guidance for AI coding agents (and humans) working in this repo.
+
+## What this is
+
+A bidirectional sync between a **Jira** project and a **Todo+** text file
+(the format used by the `fabiospampinato/vscode-todo-plus` VS Code extension).
+
+## Architecture (important)
+
+The package is split so the **sync core has zero third-party dependencies** and
+can be unit-tested with the standard library alone:
+
+| Module            | Depends on        | Purpose                                              |
+|-------------------|-------------------|------------------------------------------------------|
+| `config.py`       | stdlib only       | `FormatConfig` dataclass + conflict constants        |
+| `models.py`       | stdlib only       | `Node`, `JiraIssue`, `NodeKind`, `Status`            |
+| `todo_format.py`  | stdlib only       | `parse()`, `serialize()`, `resolve_jira_parents()`   |
+| `state.py`        | stdlib only       | JSON sidecar baseline for 3-way merge                |
+| `sync.py`         | stdlib only       | the 3-way merge engine: `sync(...) -> SyncResult`    |
+| `jira_client.py`  | `requests` (lazy) | `RestJiraClient` against Jira Cloud REST v3          |
+| `settings.py`     | `pydantic-settings` | env/`.env` -> `FormatConfig` + credentials         |
+| `cli.py`          | `typer`           | `sync` / `push` / `pull` / `status` commands         |
+
+**Rule:** never import `requests`, `pydantic`, or `typer` from the core
+modules (`config`, `models`, `todo_format`, `state`, `sync`). Keep them at the
+edges (`jira_client`, `settings`, `cli`).
+
+## Mapping rules
+
+- Line ending with `:` at column 0 -> **Epic**
+- Indented line ending with `:` -> **User Story**
+- A Todo+ task (leading box/done/cancelled symbol) -> **Task**
+- A task nested under another task -> **Sub-task**
+- Identity anchor is the `@jira(KEY)` tag, written back into the file.
+
+A node's Jira **parent** is its nearest enclosing container: Task -> enclosing
+Story (or Epic if none); Story -> Epic; Sub-task -> the Task it sits under
+(deeper nesting collapses onto that Task, since Jira forbids sub-task-of-sub-task).
+
+## Jira API note
+
+Uses `POST /rest/api/3/search/jql` with `nextPageToken` pagination. The legacy
+`/rest/api/3/search` endpoint was removed by Atlassian and must **not** be
+reintroduced. `fields` must be requested explicitly (the default is now `id`).
+
+## Tests
+
+```bash
+pytest                       # via uv/pip-installed pytest
+python tests/test_sync.py    # also runs standalone, no pytest needed
+python tests/test_todo_format.py
+```
+
+The engine is tested against `tests/fake_jira.py`, an in-memory double — no
+live Jira is required.
+
+## Build, container & CI
+
+uv is used everywhere (Makefile, Dockerfile, workflows). The image is a
+multi-stage build: a `uv pip install` build stage and a slim runtime stage
+whose entrypoint is the `todo-jira-sync` CLI. Versioning is `setuptools-scm`
+(git tags); pass `--build-arg VERSION=...` to the Docker build since the build
+context has no `.git`. GitHub Actions: `ci.yaml` (ruff + mypy + pytest, py3.10
+–3.14), `publish-pypi.yaml` (sdist/wheel to PyPI via OIDC on `v*` tags) and
+`publish-docker.yaml` (multi-arch image to GHCR on `v*` tags / manual dispatch).
+Dependabot tracks pip, github-actions and docker.

todo_jira_sync-1.0.0/Dockerfile

@@ -0,0 +1,44 @@
+# syntax=docker/dockerfile:1
+
+# ---------------------------------------------------------------------------
+# Build stage: install the package (and its deps) into an isolated venv with uv.
+# ---------------------------------------------------------------------------
+FROM python:3.14-slim-bookworm AS build
+
+# uv, copied from its official distroless image (pinned by the publish workflow).
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
+
+ENV UV_COMPILE_BYTECODE=1 \
+    UV_LINK_MODE=copy \
+    UV_PYTHON_DOWNLOADS=never
+
+# setuptools-scm derives the version from git. In CI we pass the resolved
+# version as a build arg so the build does not need the .git directory.
+ARG VERSION=0.0.0
+ENV SETUPTOOLS_SCM_PRETEND_VERSION=${VERSION}
+
+WORKDIR /app
+COPY pyproject.toml README.md ./
+COPY todo_jira_sync ./todo_jira_sync
+
+# Create the venv and install the project into it.
+RUN uv venv /opt/venv \
+    && VIRTUAL_ENV=/opt/venv uv pip install --no-cache .
+
+# ---------------------------------------------------------------------------
+# Runtime stage: copy only the venv onto a slim base. No compilers, no uv.
+# ---------------------------------------------------------------------------
+FROM python:3.14-slim-bookworm AS runtime
+
+# Run as a non-root user.
+RUN useradd --create-home --uid 1000 app
+
+COPY --from=build /opt/venv /opt/venv
+ENV PATH="/opt/venv/bin:$PATH"
+
+# Work against a mounted directory holding the todo file and its .env.
+WORKDIR /work
+USER app
+
+ENTRYPOINT ["todo-jira-sync"]
+CMD ["--help"]

todo_jira_sync-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Regis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

todo_jira_sync-1.0.0/Makefile

@@ -0,0 +1,46 @@
+.PHONY: help install lint format typecheck test check run docker docker-run clean
+
+help:
+	@echo "Targets:"
+	@echo "  install    Create the venv and install in editable mode (uv)"
+	@echo "  lint       Run ruff"
+	@echo "  format     Auto-fix with ruff"
+	@echo "  typecheck  Run mypy"
+	@echo "  test       Run the test suite (pytest)"
+	@echo "  check      lint + typecheck + test"
+	@echo "  run        Run the CLI (pass ARGS=...)"
+	@echo "  docker     Build the container image"
+	@echo "  clean      Remove caches and build artifacts"
+
+install:
+	uv venv
+	uv pip install -e ".[dev]"
+
+lint:
+	uv run ruff check .
+
+format:
+	uv run ruff check --fix .
+	uv run ruff format .
+
+typecheck:
+	uv run mypy todo_jira_sync
+
+test:
+	uv run pytest
+
+check: lint typecheck test
+
+run:
+	uv run todo-jira-sync $(ARGS)
+
+VERSION ?= 0.0.0
+docker:
+	docker build --build-arg VERSION=$(VERSION) -t todo-jira-sync:local .
+
+docker-run:
+	docker run --rm --env-file .env -v "$(PWD):/work" todo-jira-sync:local $(ARGS)
+
+clean:
+	rm -rf .pytest_cache .ruff_cache .mypy_cache build dist *.egg-info
+	find . -type d -name __pycache__ -prune -exec rm -rf {} +

todo_jira_sync-1.0.0/PKG-INFO

@@ -0,0 +1,202 @@
+Metadata-Version: 2.4
+Name: todo-jira-sync
+Version: 1.0.0
+Summary: Bidirectionally sync a Jira project with a Todo+ (vscode-todo-plus) text file.
+Author: Regis
+License: MIT
+Project-URL: Homepage, https://github.com/kalw/todo-jira-sync
+Project-URL: Issues, https://github.com/kalw/todo-jira-sync/issues
+Keywords: jira,todo,todo-plus,sync,taskpaper,vscode
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer>=0.12
+Requires-Dist: requests>=2.31
+Requires-Dist: pydantic-settings>=2.2
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: types-requests; extra == "dev"
+Dynamic: license-file
+
+# todo-jira-sync
+
+Bidirectionally sync a **Jira** project with a **Todo+** plain-text file — the
+format used by the [`vscode-todo-plus`](https://github.com/fabiospampinato/vscode-todo-plus)
+extension. Edit your backlog as a flat, version-controllable text file in your
+editor; run one command; Jira and the file converge.
+
+Scaffolded from [`tedivm/robs_awesome_python_template`](https://github.com/tedivm/robs_awesome_python_template)
+conventions (uv, `pyproject.toml`, Typer, Pydantic Settings, Ruff, mypy,
+pytest, GitHub Actions).
+
+## Mapping rules
+
+Each non-blank, non-comment line maps to one Jira issue, by indentation and the
+trailing colon:
+
+| Todo+ line                                   | Jira issue type |
+|----------------------------------------------|-----------------|
+| ends with `:`, **no** leading indent         | **Epic**        |
+| ends with `:`, **indented**                  | **User Story**  |
+| a task (`☐` / `✔` / `✘` …)                    | **Task**        |
+| a task **nested under another task**         | **Sub-task**    |
+
+```text
+Authentication:                 ← Epic
+  Login flow:                   ← Story    (parent: Authentication)
+    ☐ Build the login form      ← Task     (parent: Login flow)
+    ☐ Add OAuth providers       ← Task     (parent: Login flow)
+      ☐ Google provider         ← Sub-task (parent: Add OAuth providers)
+  ☐ Password reset email        ← Task     (parent: Authentication)
+```
+
+A node's Jira parent is its **nearest enclosing container**: a Task takes the
+Story it sits under, or the Epic if there is no enclosing Story; a Story takes
+its Epic; a Sub-task takes the Task it sits under.
+
+### Status mapping
+
+| Todo+ symbol            | Status        | Jira category        |
+|-------------------------|---------------|----------------------|
+| `☐` `[ ]`               | To Do         | *new*                |
+| `@started(...)`         | In Progress   | *indeterminate*      |
+| `✔` `✓` `[x]`           | Done          | *done*               |
+| `✘` `[-]` `@cancelled`  | Cancelled     | *done* + cancelled status name |
+
+Jira has no "cancelled" status *category*; cancelled is detected by status
+**name** (configurable via `CANCELLED_STATUS_NAMES`).
+
+### How identity works
+
+Each synced line gets a `@jira(KEY)` tag written back into the file (inserted
+*before* the trailing colon for projects, so it still reads as a project):
+
+```text
+Authentication @jira(WEB-1):
+  ☐ Build the login form @jira(WEB-3)
+```
+
+That tag is the stable anchor — rename a line freely and the link survives.
+
+## Install
+
+Requires Python ≥ 3.10. Using [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv venv
+uv pip install -e ".[dev]"
+```
+
+or with pip:
+
+```bash
+python -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+## Configure
+
+Copy `.env.example` to `.env` and fill in your details:
+
+```bash
+cp .env.example .env
+```
+
+For Jira Cloud, create an API token at
+<https://id.atlassian.com/manage-profile/security/api-tokens> and set
+`JIRA_EMAIL` + `JIRA_API_TOKEN` with `JIRA_AUTH=basic`. For Server/Data Center,
+use a personal access token with `JIRA_AUTH=bearer`.
+
+## Use
+
+```bash
+# See what would happen — touches nothing:
+todo-jira-sync status --todo todo.todo --project WEB
+
+# Full bidirectional sync:
+todo-jira-sync sync --todo todo.todo --project WEB
+
+# One-way only:
+todo-jira-sync push    # local file -> Jira (never edits the file)
+todo-jira-sync pull    # Jira -> local file (never creates/edits Jira)
+
+# Conflict policy when both sides changed the same field:
+todo-jira-sync sync --conflict jira   # jira | todo | skip
+```
+
+A JSON sidecar `todo.todo.todojira.json` is written next to your file. It is
+the 3-way-merge baseline (the common ancestor) — keep it, but it need not be
+committed (it is git-ignored by default).
+
+## How sync decides (3-way merge)
+
+For each issue the engine compares the **live file** and **live Jira** against
+the **baseline** from the last run:
+
+- only the file changed → **push** to Jira
+- only Jira changed → **pull** into the file
+- both changed the same field → **conflict**, resolved by `--conflict`
+- new in file → **created** in Jira (parents first)
+- new in Jira → **pulled** into the file (under the right parent)
+- gone from Jira but known → kept locally and reported (never silently lost)
+
+The engine **never deletes Jira issues** and **never deletes local lines**.
+
+## Docker
+
+A multi-stage, uv-based image is included. It builds the package into a slim
+runtime image whose entrypoint is the CLI, running as a non-root user.
+
+```bash
+# Build (VERSION is only needed because versioning comes from git tags):
+docker build --build-arg VERSION=0.1.0 -t todo-jira-sync .
+
+# Run against a working directory that holds your todo file and .env:
+docker run --rm --env-file .env -v "$PWD:/work" todo-jira-sync \
+  sync --todo todo.todo --project WEB
+```
+
+Or via Compose (put your `todo` file and `.env` in `./work`):
+
+```bash
+docker compose run --rm sync status
+docker compose run --rm sync sync --todo todo.todo --project WEB
+```
+
+Prebuilt multi-arch images (amd64 + arm64) are published to GitHub Container
+Registry by CI on version tags (and on demand via the workflow's manual
+trigger).
+
+## Releasing
+
+Versioning is derived from git tags via `setuptools-scm`. Pushing a tag like
+`v0.1.0` triggers two workflows: one builds the sdist/wheel and publishes to
+PyPI (via OIDC Trusted Publishing — no API token stored), the other builds and
+pushes the multi-arch container image. CI (`ci.yaml`) runs ruff, mypy and
+pytest on a Python 3.10–3.14 matrix for every push and PR.
+
+## Develop
+
+```bash
+make check     # ruff + mypy + pytest
+make test
+```
+
+The sync core (`config`, `models`, `todo_format`, `state`, `sync`) is pure
+standard library, so the tests run against an in-memory fake Jira with no
+network and no live credentials. The two test files also run standalone:
+
+```bash
+python tests/test_todo_format.py
+python tests/test_sync.py
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).