planpilot 1.0.0__tar.gz

planpilot-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 aryeko
+
+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.

planpilot-1.0.0/PKG-INFO

@@ -0,0 +1,199 @@
+Metadata-Version: 2.4
+Name: planpilot
+Version: 1.0.0
+Summary: Sync roadmap plans (epics, stories, tasks) to GitHub Issues and Projects v2
+License: MIT
+License-File: LICENSE
+Keywords: github,projects,roadmap,sync,issues
+Author: aryeko
+Requires-Python: >=3.11
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Dist: pydantic (>=2.12.5,<3.0.0)
+Project-URL: Homepage, https://github.com/aryeko/planpilot
+Project-URL: Repository, https://github.com/aryeko/planpilot
+Description-Content-Type: text/markdown
+
+# planpilot
+
+[![CI](https://github.com/aryeko/planpilot/actions/workflows/ci.yml/badge.svg)](https://github.com/aryeko/planpilot/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/aryeko/planpilot/graph/badge.svg?token=3I2A515YTI)](https://codecov.io/gh/aryeko/planpilot)
+[![PyPI](https://img.shields.io/pypi/v/planpilot)](https://pypi.org/project/planpilot/)
+[![Python](https://img.shields.io/pypi/pyversions/planpilot)](https://pypi.org/project/planpilot/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Sync roadmap plans (epics, stories, tasks) to GitHub Issues and Projects v2.
+
+## What it does
+
+**planpilot** takes structured plan files and turns them into a fully linked project board:
+
+```mermaid
+flowchart LR
+    A["roadmap.md"] --> B["epics.json\nstories.json\ntasks.json"]
+    B -->|planpilot| C["GitHub Issues\n+ Projects v2"]
+    C --> D["Epic / Story / Task\nissue types"]
+    C --> E["Sub-issue\nhierarchy"]
+    C --> F["Blocked-by\ndependencies"]
+    C --> G["Project fields\nstatus, priority,\niteration, size"]
+```
+
+- **One-way sync**: local plan files -> GitHub
+- **Idempotent**: safe to rerun -- updates existing issues via markers
+- **Dry-run first**: preview all changes before applying
+- **Multi-epic**: slice large plans and sync each epic sequentially
+- **Provider-agnostic**: adapter pattern supports GitHub today, with Jira/Linear planned
+- **Async-first**: built on asyncio for fast, concurrent sync operations
+
+## Architecture
+
+planpilot follows SOLID principles with a modular, provider-agnostic design:
+
+```text
+src/planpilot/
+├── models/          # Pydantic domain models (Plan, Epic, Story, Task, …)
+├── plan/            # Plan loading, validation, and hashing
+├── providers/       # Provider adapter pattern (ABC + implementations)
+│   └── github/      # GitHub adapter (gh CLI)
+├── rendering/       # Issue body rendering (Protocol + Markdown impl)
+├── sync/            # Sync engine orchestrator + relation logic
+├── config.py        # SyncConfig (pydantic)
+├── exceptions.py    # Custom exception hierarchy
+├── cli.py           # CLI entry point
+└── slice.py         # Multi-epic plan slicing
+```
+
+The sync engine depends only on abstract interfaces (`Provider` ABC and `BodyRenderer` Protocol), making it easy to add new providers (Jira, Linear) without touching the core sync logic.
+
+See [docs/architecture.md](docs/architecture.md) for the full architecture guide.
+
+## Requirements
+
+- Python 3.11+
+- [`gh` CLI](https://cli.github.com/) installed and authenticated
+- GitHub token scopes: `repo`, `project`
+
+## Installation
+
+```bash
+pip install planpilot
+```
+
+Or with Poetry:
+
+```bash
+poetry add planpilot
+```
+
+## Quickstart
+
+### 1. Dry-run (preview changes)
+
+```bash
+planpilot \
+  --repo your-org/your-repo \
+  --project-url https://github.com/orgs/your-org/projects/1 \
+  --epics-path .plans/epics.json \
+  --stories-path .plans/stories.json \
+  --tasks-path .plans/tasks.json \
+  --sync-path .plans/github-sync-map.json \
+  --dry-run
+```
+
+### 2. Apply changes
+
+```bash
+planpilot \
+  --repo your-org/your-repo \
+  --project-url https://github.com/orgs/your-org/projects/1 \
+  --epics-path .plans/epics.json \
+  --stories-path .plans/stories.json \
+  --tasks-path .plans/tasks.json \
+  --sync-path .plans/github-sync-map.json \
+  --apply
+```
+
+### 3. Multi-epic plans
+
+The sync tool expects one epic per run. For multi-epic plans, slice first:
+
+```bash
+planpilot-slice \
+  --epics-path .plans/epics.json \
+  --stories-path .plans/stories.json \
+  --tasks-path .plans/tasks.json \
+  --out-dir .plans/tmp
+```
+
+Then sync each epic:
+
+```bash
+for f in .plans/tmp/epics.*.json; do
+  id=$(basename "$f" .json | sed 's/epics\.//')
+  planpilot \
+    --repo your-org/your-repo \
+    --project-url https://github.com/orgs/your-org/projects/1 \
+    --epics-path ".plans/tmp/epics.${id}.json" \
+    --stories-path ".plans/tmp/stories.${id}.json" \
+    --tasks-path ".plans/tmp/tasks.${id}.json" \
+    --sync-path ".plans/github-sync-map.${id}.json" \
+    --apply
+done
+```
+
+## Optional flags
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--label` | `codex` | Label applied to created issues |
+| `--status` | `Backlog` | Project status field value |
+| `--priority` | `P1` | Project priority field value |
+| `--iteration` | `active` | Iteration title, `active`, or `none` |
+| `--size-field` | `Size` | Project size field name |
+| `--no-size-from-tshirt` | off | Disable t-shirt size mapping |
+| `--verbose` | off | Enable verbose logging |
+
+Full CLI reference: [docs/cli-reference.md](docs/cli-reference.md)
+
+## Plan file schemas
+
+See [docs/schemas.md](docs/schemas.md) for the expected structure of `epics.json`, `stories.json`, and `tasks.json`, with full examples.
+
+A complete working example is in the [examples/](examples/) directory, including sample rendered issue bodies and a sync-map output.
+
+## Documentation
+
+- [How It Works](docs/how-it-works.md) -- sync pipeline, idempotency, what gets created
+- [CLI Reference](docs/cli-reference.md) -- all flags and commands
+- [Plan Schemas](docs/schemas.md) -- JSON format with examples and validation rules
+- [Architecture](docs/architecture.md) -- module map, data flow, provider pattern, extension guide
+- [Release Guide](RELEASE.md) -- automated versioning, publishing, and release pipeline
+
+## Development
+
+Development tasks use [poethepoet](https://github.com/nat-n/poethepoet):
+
+```bash
+poe lint           # ruff check
+poe format         # ruff format
+poe test           # pytest -v
+poe coverage       # pytest + HTML coverage report
+poe typecheck      # mypy
+poe check          # lint + format-check + tests (all-in-one)
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for setup and development instructions.
+
+## License
+
+[MIT](LICENSE)
+

planpilot-1.0.0/README.md

@@ -0,0 +1,175 @@
+# planpilot
+
+[![CI](https://github.com/aryeko/planpilot/actions/workflows/ci.yml/badge.svg)](https://github.com/aryeko/planpilot/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/aryeko/planpilot/graph/badge.svg?token=3I2A515YTI)](https://codecov.io/gh/aryeko/planpilot)
+[![PyPI](https://img.shields.io/pypi/v/planpilot)](https://pypi.org/project/planpilot/)
+[![Python](https://img.shields.io/pypi/pyversions/planpilot)](https://pypi.org/project/planpilot/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Sync roadmap plans (epics, stories, tasks) to GitHub Issues and Projects v2.
+
+## What it does
+
+**planpilot** takes structured plan files and turns them into a fully linked project board:
+
+```mermaid
+flowchart LR
+    A["roadmap.md"] --> B["epics.json\nstories.json\ntasks.json"]
+    B -->|planpilot| C["GitHub Issues\n+ Projects v2"]
+    C --> D["Epic / Story / Task\nissue types"]
+    C --> E["Sub-issue\nhierarchy"]
+    C --> F["Blocked-by\ndependencies"]
+    C --> G["Project fields\nstatus, priority,\niteration, size"]
+```
+
+- **One-way sync**: local plan files -> GitHub
+- **Idempotent**: safe to rerun -- updates existing issues via markers
+- **Dry-run first**: preview all changes before applying
+- **Multi-epic**: slice large plans and sync each epic sequentially
+- **Provider-agnostic**: adapter pattern supports GitHub today, with Jira/Linear planned
+- **Async-first**: built on asyncio for fast, concurrent sync operations
+
+## Architecture
+
+planpilot follows SOLID principles with a modular, provider-agnostic design:
+
+```text
+src/planpilot/
+├── models/          # Pydantic domain models (Plan, Epic, Story, Task, …)
+├── plan/            # Plan loading, validation, and hashing
+├── providers/       # Provider adapter pattern (ABC + implementations)
+│   └── github/      # GitHub adapter (gh CLI)
+├── rendering/       # Issue body rendering (Protocol + Markdown impl)
+├── sync/            # Sync engine orchestrator + relation logic
+├── config.py        # SyncConfig (pydantic)
+├── exceptions.py    # Custom exception hierarchy
+├── cli.py           # CLI entry point
+└── slice.py         # Multi-epic plan slicing
+```
+
+The sync engine depends only on abstract interfaces (`Provider` ABC and `BodyRenderer` Protocol), making it easy to add new providers (Jira, Linear) without touching the core sync logic.
+
+See [docs/architecture.md](docs/architecture.md) for the full architecture guide.
+
+## Requirements
+
+- Python 3.11+
+- [`gh` CLI](https://cli.github.com/) installed and authenticated
+- GitHub token scopes: `repo`, `project`
+
+## Installation
+
+```bash
+pip install planpilot
+```
+
+Or with Poetry:
+
+```bash
+poetry add planpilot
+```
+
+## Quickstart
+
+### 1. Dry-run (preview changes)
+
+```bash
+planpilot \
+  --repo your-org/your-repo \
+  --project-url https://github.com/orgs/your-org/projects/1 \
+  --epics-path .plans/epics.json \
+  --stories-path .plans/stories.json \
+  --tasks-path .plans/tasks.json \
+  --sync-path .plans/github-sync-map.json \
+  --dry-run
+```
+
+### 2. Apply changes
+
+```bash
+planpilot \
+  --repo your-org/your-repo \
+  --project-url https://github.com/orgs/your-org/projects/1 \
+  --epics-path .plans/epics.json \
+  --stories-path .plans/stories.json \
+  --tasks-path .plans/tasks.json \
+  --sync-path .plans/github-sync-map.json \
+  --apply
+```
+
+### 3. Multi-epic plans
+
+The sync tool expects one epic per run. For multi-epic plans, slice first:
+
+```bash
+planpilot-slice \
+  --epics-path .plans/epics.json \
+  --stories-path .plans/stories.json \
+  --tasks-path .plans/tasks.json \
+  --out-dir .plans/tmp
+```
+
+Then sync each epic:
+
+```bash
+for f in .plans/tmp/epics.*.json; do
+  id=$(basename "$f" .json | sed 's/epics\.//')
+  planpilot \
+    --repo your-org/your-repo \
+    --project-url https://github.com/orgs/your-org/projects/1 \
+    --epics-path ".plans/tmp/epics.${id}.json" \
+    --stories-path ".plans/tmp/stories.${id}.json" \
+    --tasks-path ".plans/tmp/tasks.${id}.json" \
+    --sync-path ".plans/github-sync-map.${id}.json" \
+    --apply
+done
+```
+
+## Optional flags
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--label` | `codex` | Label applied to created issues |
+| `--status` | `Backlog` | Project status field value |
+| `--priority` | `P1` | Project priority field value |
+| `--iteration` | `active` | Iteration title, `active`, or `none` |
+| `--size-field` | `Size` | Project size field name |
+| `--no-size-from-tshirt` | off | Disable t-shirt size mapping |
+| `--verbose` | off | Enable verbose logging |
+
+Full CLI reference: [docs/cli-reference.md](docs/cli-reference.md)
+
+## Plan file schemas
+
+See [docs/schemas.md](docs/schemas.md) for the expected structure of `epics.json`, `stories.json`, and `tasks.json`, with full examples.
+
+A complete working example is in the [examples/](examples/) directory, including sample rendered issue bodies and a sync-map output.
+
+## Documentation
+
+- [How It Works](docs/how-it-works.md) -- sync pipeline, idempotency, what gets created
+- [CLI Reference](docs/cli-reference.md) -- all flags and commands
+- [Plan Schemas](docs/schemas.md) -- JSON format with examples and validation rules
+- [Architecture](docs/architecture.md) -- module map, data flow, provider pattern, extension guide
+- [Release Guide](RELEASE.md) -- automated versioning, publishing, and release pipeline
+
+## Development
+
+Development tasks use [poethepoet](https://github.com/nat-n/poethepoet):
+
+```bash
+poe lint           # ruff check
+poe format         # ruff format
+poe test           # pytest -v
+poe coverage       # pytest + HTML coverage report
+poe typecheck      # mypy
+poe check          # lint + format-check + tests (all-in-one)
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for setup and development instructions.
+
+## License
+
+[MIT](LICENSE)

planpilot-1.0.0/pyproject.toml

@@ -0,0 +1,119 @@
+[tool.poetry]
+name = "planpilot"
+version = "1.0.0"
+description = "Sync roadmap plans (epics, stories, tasks) to GitHub Issues and Projects v2"
+readme = "README.md"
+license = "MIT"
+authors = ["aryeko"]
+homepage = "https://github.com/aryeko/planpilot"
+repository = "https://github.com/aryeko/planpilot"
+keywords = ["github", "projects", "roadmap", "sync", "issues"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Build Tools",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+packages = [{include = "planpilot", from = "src"}]
+
+[tool.poetry.scripts]
+planpilot = "planpilot.cli:main"
+planpilot-slice = "planpilot.slice:slice_cli"
+
+[tool.poetry.dependencies]
+python = ">=3.11"
+pydantic = "^2.12.5"
+
+[tool.poetry.group.dev.dependencies]
+pytest = ">=7.0"
+ruff = ">=0.4"
+mypy = ">=1.0"
+pytest-cov = "^7.0.0"
+pytest-asyncio = "^1.3.0"
+commitlint = ">=1.3"
+poethepoet = "^0.40.0"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.poe.tasks]
+lint = "ruff check ."
+format = "ruff format ."
+format-check = "ruff format --check ."
+test = "pytest -v"
+coverage = "pytest -v --cov-report=html:.coverage/html"
+typecheck = "mypy src/planpilot"
+check = ["lint", "format-check", "test"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--cov=planpilot --cov-report=term-missing --cov-report=xml:.coverage/coverage.xml"
+asyncio_mode = "auto"
+
+[tool.coverage.run]
+source = ["planpilot"]
+branch = true
+data_file = ".coverage/coverage.db"
+
+[tool.coverage.report]
+show_missing = true
+skip_empty = true
+exclude_lines = [
+    "pragma: no cover",
+    "if __name__ == .__main__.",
+    "if TYPE_CHECKING:",
+]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 120
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = [
+    "E",   # pycodestyle errors
+    "F",   # pyflakes
+    "I",   # isort
+    "UP",  # pyupgrade
+    "B",   # bugbear
+    "SIM", # simplify
+    "RUF", # ruff-specific
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["planpilot"]
+
+[tool.mypy]
+python_version = "3.11"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+plugins = ["pydantic.mypy"]
+
+[tool.semantic_release]
+version_toml = ["pyproject.toml:tool.poetry.version"]
+version_variables = ["src/planpilot/__init__.py:__version__"]
+commit_parser = "conventional"
+commit_message = "chore(release): {version}"
+tag_format = "v{version}"
+major_on_zero = true
+allow_zero_version = true
+
+[tool.semantic_release.commit_parser_options]
+minor_tags = ["feat"]
+patch_tags = ["fix", "perf"]
+
+[tool.semantic_release.branches.main]
+match = "main"
+
+[tool.semantic_release.changelog]
+mode = "update"
+
+[tool.semantic_release.remote]
+type = "github"

planpilot-1.0.0/src/planpilot/__init__.py

@@ -0,0 +1,4 @@
+"""planpilot — sync roadmap plans to GitHub Issues and Projects v2."""
+
+__all__ = ["__version__"]
+__version__ = "1.0.0"

planpilot-1.0.0/src/planpilot/__main__.py

@@ -0,0 +1,8 @@
+"""Allow running planpilot as ``python -m planpilot``."""
+
+from __future__ import annotations
+
+from planpilot.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())