heinzel-github 0.9.1__tar.gz

heinzel_github-0.9.1/.gitignore

@@ -0,0 +1,15 @@
+.venv/
+.tools/
+__pycache__/
+.pytest_cache/
+.mypy_cache/
+.pyright/
+.coverage*
+htmlcov/
+node_modules/
+dist/
+release-dist/
+*.egg-info/
+.acceptance/
+.preview/
+.candidates/

heinzel_github-0.9.1/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 0.9.1
+
+Move this plugin to its independent repository project for the Heinzel 0.9.1 plugin contract.
+Own its dependencies, tests and artifacts; consume public contracts without concrete provider dependencies.
+
+Earlier history is preserved in the source repository named in README.md.

heinzel_github-0.9.1/LICENSE

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

heinzel_github-0.9.1/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.5
+Name: heinzel-github
+Version: 0.9.1
+Summary: Read pull requests and issues from GitHub: the code-host and tracker capabilities.
+Project-URL: Source, https://github.com/helmut-hoffer-von-ankershoffen/heinzel-plugins/tree/main/plugins/heinzel-github
+Project-URL: Changelog, https://github.com/helmut-hoffer-von-ankershoffen/heinzel-plugins/blob/main/plugins/heinzel-github/CHANGELOG.md
+Project-URL: Issues, https://github.com/helmut-hoffer-von-ankershoffen/heinzel-plugins/issues
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: heinzel<0.10,>=0.9.1
+Description-Content-Type: text/markdown
+
+# heinzel-github
+
+Read pull requests and issues from GitHub, the `code-host` and `tracker` capabilities ([ADR 0028](https://github.com/helmut-hoffer-von-ankershoffen/heinzel/blob/main/docs/adr/0028-integrations-are-capability-adapters.md)): a first-party
+[Heinzelmännchen](https://github.com/helmut-hoffer-von-ankershoffen/heinzel) plugin. It is independently released and installed explicitly:
+
+```bash
+hz system plugin add github --confirm             # a compatible plugin release; run it again to upgrade
+hz system plugin remove heinzel-github
+```
+
+## Set up
+
+The adapter talks to GitHub only through the [GitHub CLI](https://cli.github.com) `gh` (2.40.0 or later), which owns
+authentication ([ADR 0035](https://github.com/helmut-hoffer-von-ankershoffen/heinzel/blob/main/docs/adr/0035-integrations-go-through-vendor-clis-as-an-ordinary-employee.md)). It reads what you can read, as you:
+no app to register, no token to create or store. Install `gh` and log in once:
+
+```bash
+gh auth login                           # or: gh auth login --hostname ghe.example.com
+```
+
+The adapter acts with whatever that login may do, which is usually more than reading; it only ever sends GET
+requests. As for any `gh` command, a `GH_TOKEN` or `GITHUB_TOKEN` (`GH_ENTERPRISE_TOKEN` for a GitHub Enterprise
+Server) in your environment takes precedence over the stored login: it is gh's own variable, passed to gh and never
+read by Heinzelmännchen. If you stored a token for an earlier version, remove it:
+`hz system credential remove github-token --service github` (or unset `HZ_CREDENTIAL_GITHUB_GITHUB_TOKEN`).
+
+Bind the adapter in your user configuration, never in a project `hz.toml`, which Heinzelmännchen ignores for bindings:
+
+```bash
+hz system config set capabilities.code_host github
+hz system config set capabilities.tracker github
+```
+
+which writes
+
+```toml
+[capabilities]
+code_host = "github"
+tracker = "github"
+```
+
+Or per shell: `HZ_CAPABILITIES__CODE_HOST=github`, `HZ_CAPABILITIES__TRACKER=github`.
+
+For GitHub Enterprise Server, name its host in your user configuration or `HZ_GITHUB__HOST`; the adapter passes it to
+`gh` as `--hostname` and `GH_HOST`, so `gh` uses its login for that host:
+
+```bash
+hz system config set github.host ghe.example.com
+```
+
+or in the file (`api_url` from earlier versions is refused; `host` replaced it):
+
+```toml
+[github]
+host = "ghe.example.com"
+gh = "gh"      # the GitHub CLI: a name on PATH (absolute entries only) or an absolute path
+timeout = 60   # seconds per gh call
+```
+
+`host`, `gh` and `timeout` are ignored in a project `hz.toml`, so a repository can't send your login elsewhere or pick
+the program that runs. The adapter's hosts come
+from it: `hz system capability list` shows `api.github.com`, or your GitHub Enterprise Server's host.
+
+### Is it connected?
+
+Bound automatically while it is the only installed adapter of a capability (usually `code-host`; `tracker` once another
+tracker is installed needs a choice), [ADR
+0055](https://github.com/helmut-hoffer-von-ankershoffen/heinzel/blob/main/docs/adr/0055-connectors-show-their-sign-in-test-live-on-demand-and-bind-themselves-when-alone.md). `hz
+system connector list` (or Settings → Connectors in `hz ui`) shows whether `gh` is logged in and as whom, read from gh's
+hosts file without asking GitHub; `hz system connector test github` asks GitHub who gh is (`gh api user`, 15 s at most),
+and only when you run it.
+
+## Use
+
+Workflows ask for `code-host` and `tracker`, never for GitHub:
+
+```python
+from datetime import datetime
+
+from heinzel import CodeHost, Module, PullRequest, Window
+
+module = Module("digest", "Weekly digest.", requires=["code-host:read", "tracker:read"])
+
+
+@module.operation
+def merged(code_host: CodeHost, since: datetime, until: datetime) -> list[PullRequest]:
+    """Pull requests merged this week."""
+    return code_host.merged_pull_requests("acme/widgets", Window(since=since, until=until))
+```
+
+| Method | Capability | `gh api` call |
+| --- | --- | --- |
+| `merged_pull_requests(repository, window)` | `code-host:read` | `repos/{owner}/{repo}/pulls?state=closed&sort=updated&direction=desc`, kept when `merged_at` is in the window; paging stops before the window |
+| `issues_updated(project, window)` | `tracker:read` | `repos/{owner}/{repo}/issues?state=all&since=...&sort=updated&direction=asc`, without pull requests |
+
+Repositories and projects are written `owner/repo`; windows are half-open `[since, until)` with timezone-aware times;
+results are oldest first. The adapter pages with the API's `page` and `per_page` parameters rather than
+`gh api --paginate`, so it can stop as soon as the window is covered. A call reads at most 100 pages of 100 (10,000
+items), 50 MiB in all and ten times `github.timeout`, then fails and says what to ask for instead: merged pull requests page through every pull request updated since `since`, even after `until`, so they need
+a window that starts more recently; issues stop at `until`, so they need a shorter window. Why the pulls list and not
+the search API: [ADR 0033](https://github.com/helmut-hoffer-von-ankershoffen/heinzel/blob/main/docs/adr/0033-github-rest-api-over-urllib.md); why `gh`:
+[ADR 0035](https://github.com/helmut-hoffer-von-ankershoffen/heinzel/blob/main/docs/adr/0035-integrations-go-through-vendor-clis-as-an-ordinary-employee.md).
+
+```bash
+hz github info                  # this plugin, its version and the GitHub host it reads
+hz system capability list       # who reads what, through which adapter and hosts
+hz system doctor                # gh on PATH, its version and login, the bindings; never contacts GitHub
+```
+
+Errors say what to do: no `gh`, or one too old, names where to get it; no login, or a login GitHub rejects, names
+`gh auth login --hostname <host>`; a rate limit says to wait and how to see when it resets; a missing or forbidden
+repository says to check the spelling and what your account can see; a slow call names the timeout setting.
+
+How `gh` is run: with an argument list, never a shell, from your home directory, in its own process group, stopped
+(SIGTERM, then SIGKILL) at the timeout, with its output capped, and with an allowlisted environment: never
+Heinzelmännchen's `HZ_CREDENTIAL_*` variables or debug switches such as `GH_DEBUG`, which would print request
+headers. Doctor runs only `gh --version` and looks for the host in gh's hosts file (or a token variable gh reads); it
+never runs a command that prints a token. Everything GitHub or `gh` says is redacted of anything shaped like a GitHub
+token, stripped of control and bidirectional characters, and only then cut to length; every string the adapter
+returns is cleaned too.
+
+Development and release commands: [repository guide](../../README.md).
+
+Migration provenance: heinzel, before the 0.9 plugin-boundary migration.

heinzel_github-0.9.1/README.md

@@ -0,0 +1,124 @@
+# heinzel-github
+
+Read pull requests and issues from GitHub, the `code-host` and `tracker` capabilities ([ADR 0028](https://github.com/helmut-hoffer-von-ankershoffen/heinzel/blob/main/docs/adr/0028-integrations-are-capability-adapters.md)): a first-party
+[Heinzelmännchen](https://github.com/helmut-hoffer-von-ankershoffen/heinzel) plugin. It is independently released and installed explicitly:
+
+```bash
+hz system plugin add github --confirm             # a compatible plugin release; run it again to upgrade
+hz system plugin remove heinzel-github
+```
+
+## Set up
+
+The adapter talks to GitHub only through the [GitHub CLI](https://cli.github.com) `gh` (2.40.0 or later), which owns
+authentication ([ADR 0035](https://github.com/helmut-hoffer-von-ankershoffen/heinzel/blob/main/docs/adr/0035-integrations-go-through-vendor-clis-as-an-ordinary-employee.md)). It reads what you can read, as you:
+no app to register, no token to create or store. Install `gh` and log in once:
+
+```bash
+gh auth login                           # or: gh auth login --hostname ghe.example.com
+```
+
+The adapter acts with whatever that login may do, which is usually more than reading; it only ever sends GET
+requests. As for any `gh` command, a `GH_TOKEN` or `GITHUB_TOKEN` (`GH_ENTERPRISE_TOKEN` for a GitHub Enterprise
+Server) in your environment takes precedence over the stored login: it is gh's own variable, passed to gh and never
+read by Heinzelmännchen. If you stored a token for an earlier version, remove it:
+`hz system credential remove github-token --service github` (or unset `HZ_CREDENTIAL_GITHUB_GITHUB_TOKEN`).
+
+Bind the adapter in your user configuration, never in a project `hz.toml`, which Heinzelmännchen ignores for bindings:
+
+```bash
+hz system config set capabilities.code_host github
+hz system config set capabilities.tracker github
+```
+
+which writes
+
+```toml
+[capabilities]
+code_host = "github"
+tracker = "github"
+```
+
+Or per shell: `HZ_CAPABILITIES__CODE_HOST=github`, `HZ_CAPABILITIES__TRACKER=github`.
+
+For GitHub Enterprise Server, name its host in your user configuration or `HZ_GITHUB__HOST`; the adapter passes it to
+`gh` as `--hostname` and `GH_HOST`, so `gh` uses its login for that host:
+
+```bash
+hz system config set github.host ghe.example.com
+```
+
+or in the file (`api_url` from earlier versions is refused; `host` replaced it):
+
+```toml
+[github]
+host = "ghe.example.com"
+gh = "gh"      # the GitHub CLI: a name on PATH (absolute entries only) or an absolute path
+timeout = 60   # seconds per gh call
+```
+
+`host`, `gh` and `timeout` are ignored in a project `hz.toml`, so a repository can't send your login elsewhere or pick
+the program that runs. The adapter's hosts come
+from it: `hz system capability list` shows `api.github.com`, or your GitHub Enterprise Server's host.
+
+### Is it connected?
+
+Bound automatically while it is the only installed adapter of a capability (usually `code-host`; `tracker` once another
+tracker is installed needs a choice), [ADR
+0055](https://github.com/helmut-hoffer-von-ankershoffen/heinzel/blob/main/docs/adr/0055-connectors-show-their-sign-in-test-live-on-demand-and-bind-themselves-when-alone.md). `hz
+system connector list` (or Settings → Connectors in `hz ui`) shows whether `gh` is logged in and as whom, read from gh's
+hosts file without asking GitHub; `hz system connector test github` asks GitHub who gh is (`gh api user`, 15 s at most),
+and only when you run it.
+
+## Use
+
+Workflows ask for `code-host` and `tracker`, never for GitHub:
+
+```python
+from datetime import datetime
+
+from heinzel import CodeHost, Module, PullRequest, Window
+
+module = Module("digest", "Weekly digest.", requires=["code-host:read", "tracker:read"])
+
+
+@module.operation
+def merged(code_host: CodeHost, since: datetime, until: datetime) -> list[PullRequest]:
+    """Pull requests merged this week."""
+    return code_host.merged_pull_requests("acme/widgets", Window(since=since, until=until))
+```
+
+| Method | Capability | `gh api` call |
+| --- | --- | --- |
+| `merged_pull_requests(repository, window)` | `code-host:read` | `repos/{owner}/{repo}/pulls?state=closed&sort=updated&direction=desc`, kept when `merged_at` is in the window; paging stops before the window |
+| `issues_updated(project, window)` | `tracker:read` | `repos/{owner}/{repo}/issues?state=all&since=...&sort=updated&direction=asc`, without pull requests |
+
+Repositories and projects are written `owner/repo`; windows are half-open `[since, until)` with timezone-aware times;
+results are oldest first. The adapter pages with the API's `page` and `per_page` parameters rather than
+`gh api --paginate`, so it can stop as soon as the window is covered. A call reads at most 100 pages of 100 (10,000
+items), 50 MiB in all and ten times `github.timeout`, then fails and says what to ask for instead: merged pull requests page through every pull request updated since `since`, even after `until`, so they need
+a window that starts more recently; issues stop at `until`, so they need a shorter window. Why the pulls list and not
+the search API: [ADR 0033](https://github.com/helmut-hoffer-von-ankershoffen/heinzel/blob/main/docs/adr/0033-github-rest-api-over-urllib.md); why `gh`:
+[ADR 0035](https://github.com/helmut-hoffer-von-ankershoffen/heinzel/blob/main/docs/adr/0035-integrations-go-through-vendor-clis-as-an-ordinary-employee.md).
+
+```bash
+hz github info                  # this plugin, its version and the GitHub host it reads
+hz system capability list       # who reads what, through which adapter and hosts
+hz system doctor                # gh on PATH, its version and login, the bindings; never contacts GitHub
+```
+
+Errors say what to do: no `gh`, or one too old, names where to get it; no login, or a login GitHub rejects, names
+`gh auth login --hostname <host>`; a rate limit says to wait and how to see when it resets; a missing or forbidden
+repository says to check the spelling and what your account can see; a slow call names the timeout setting.
+
+How `gh` is run: with an argument list, never a shell, from your home directory, in its own process group, stopped
+(SIGTERM, then SIGKILL) at the timeout, with its output capped, and with an allowlisted environment: never
+Heinzelmännchen's `HZ_CREDENTIAL_*` variables or debug switches such as `GH_DEBUG`, which would print request
+headers. Doctor runs only `gh --version` and looks for the host in gh's hosts file (or a token variable gh reads); it
+never runs a command that prints a token. Everything GitHub or `gh` says is redacted of anything shaped like a GitHub
+token, stripped of control and bidirectional characters, and only then cut to length; every string the adapter
+returns is cleaned too.
+
+Development and release commands: [repository guide](../../README.md).
+
+Migration provenance: heinzel, before the 0.9 plugin-boundary migration.

heinzel_github-0.9.1/plugin-lock.json

@@ -0,0 +1,40 @@
+{
+  "format": 1,
+  "sdk": 1,
+  "inputs": [
+    "coverage>=7.12",
+    "editables>=0.5",
+    "hatchling>=1.29.0",
+    "heinzel>=0.9.1,<0.10",
+    "mypy>=1.19.0,<3",
+    "pyright[nodejs]==1.1.414",
+    "pytest-timeout>=2.4.0,<3",
+    "pytest-xdist>=3.8",
+    "pytest>=9.0.3,<10",
+    "ruff==0.17.2"
+  ],
+  "core": {
+    "version": "0.9.1",
+    "dependencies": [
+      "croniter>=6.2.4",
+      "fastapi>=0.161",
+      "keyring>=25.6",
+      "mcp>=2.3",
+      "packaging>=25.0",
+      "platformdirs>=4.5",
+      "pluggy<2,>=1.6.0",
+      "psutil==7.2.2",
+      "pydantic-ai-slim==2.61.0",
+      "pydantic-ai-slim[anthropic]==2.61.0; extra == \"anthropic\"",
+      "pydantic-ai-slim[openai]==2.61.0; extra == \"openai\"",
+      "pydantic-settings<3,>=2.11.0",
+      "pydantic<3,>=2.12.0",
+      "pyyaml<7,>=6.0.2",
+      "rich>=14.2.0",
+      "tomlkit>=0.13",
+      "typer>=0.23.0",
+      "uvicorn>=0.54",
+      "wsproto>=1.3"
+    ]
+  }
+}

heinzel_github-0.9.1/pyproject.toml

@@ -0,0 +1,131 @@
+[project]
+name = "heinzel-github"
+version = "0.9.1"
+description = "Read pull requests and issues from GitHub: the code-host and tracker capabilities."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.12"
+dependencies = ["heinzel>=0.9.1,<0.10"]
+
+[project.urls]
+Source = "https://github.com/helmut-hoffer-von-ankershoffen/heinzel-plugins/tree/main/plugins/heinzel-github"
+Changelog = "https://github.com/helmut-hoffer-von-ankershoffen/heinzel-plugins/blob/main/plugins/heinzel-github/CHANGELOG.md"
+Issues = "https://github.com/helmut-hoffer-von-ankershoffen/heinzel-plugins/issues"
+
+[project.entry-points."heinzel.modules"]
+github = "heinzel_github"
+
+[build-system]
+requires = ["hatchling>=1.29.0"]
+build-backend = "hatchling.build"
+
+[dependency-groups]
+test = ["editables>=0.5", "pytest>=9.0.3,<10", "pytest-timeout>=2.4.0,<3", "pytest-xdist>=3.8", "ruff==0.17.2", "mypy>=1.19.0,<3", "coverage>=7.12", "pyright[nodejs]==1.1.414"]
+
+
+[tool.ruff]
+line-length = 120
+fix = true
+extend-exclude = ["template"] # rendered and checked by `make template-test`
+
+[tool.ruff.lint]
+select = ["ALL"]
+# pydoclint (DOC): docstring sections must match what the code raises, returns and yields. Preview rules, opted into
+# one by one so no other preview rule sneaks in.
+preview = true
+explicit-preview-rules = true
+extend-select = ["DOC201", "DOC202", "DOC402", "DOC403", "DOC501", "DOC502"]
+ignore = [
+    "COM812",  # conflicts with the ruff formatter
+    "CPY001",  # no copyright header in OSS files
+    "D203",    # incompatible with D211
+    "DOC201",  # a return value is documented by the type and the summary line; Returns: only when it adds meaning
+    "DOC502",  # documenting exceptions raised by callees is useful for callers
+    "D213",    # incompatible with D212
+    "FBT001",  # boolean positional arguments are idiomatic for Typer options
+    "FBT002",  # same as FBT001
+    "ISC001",  # conflicts with the ruff formatter
+    "TD003",   # todos don't need an issue link
+    "FIX002",  # todos are allowed
+]
+
+[tool.ruff.lint.per-file-ignores]
+".claude/hooks/*.py" = [
+    "D103",    # hook entry points are documented by the module docstring
+    "INP001",  # hooks are scripts, not a package
+    "S603",    # subprocess calls with fixed argument lists
+    "S607",    # tools (uv, git, make) are resolved from PATH on purpose
+    "T201",    # hooks talk to the agent through stdout/stderr
+]
+"fuzz/*.py" = [
+    "INP001",  # fuzz targets are scripts, not a package
+]
+"hatch_build.py" = [
+    "INP001",  # the build hook hatch loads by path, not a package
+]
+"scripts/*.py" = [
+    "INP001",  # scripts are not a package
+    "T201",    # scripts report on stdout/stderr
+]
+"**/tests/**/*.py" = [
+    "ANN",     # fixtures and tests don't need full annotations
+    "DOC",     # test docstrings describe behaviour, not interfaces
+    "ARG",     # fixtures are used for their side effects
+    "D",       # test names are the documentation
+    "INP001",  # tests are not a package
+    "PLC0415", # local imports keep fixtures isolated
+    "PLR2004", # magic values are fine in assertions
+    "S101",    # asserts are what tests do
+    "S105",    # fake tokens and passwords are test data (credentials, adapters for tracker and document services)
+    "S106",    # same as S105, passed as arguments
+    "S603",    # subprocess calls with trusted input
+    "S607",    # partial executable paths (uv, hz) are resolved from PATH on purpose
+    "SLF001",  # private access is needed for solitary unit tests
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.format]
+docstring-code-format = true
+
+[tool.mypy]
+strict = true
+mypy_path = ["src"]
+files = ["src"]
+plugins = ["pydantic.mypy"]
+
+[tool.pydantic-mypy]
+init_forbid_extra = true
+init_typed = true
+warn_required_dynamic_aliases = true
+
+[tool.pytest]
+minversion = "9.0"
+strict = true
+testpaths = ["tests"]
+addopts = ["-ra", "--import-mode=importlib"]
+filterwarnings = ["error"]
+markers = ["unit: Offline isolated behavior.", "integration: Offline public-contract integration.", "e2e: Installed artifacts or real external services.", "perf: Explicit timing tests.", "long_running: Extended end-to-end budget."]
+
+[tool.heinzel.plugin]
+profiles = []
+requires = ["core:plugin-api@1"]
+provides = ["code-host:read", "tracker:read"]
+
+[tool.coverage.run]
+source = ["heinzel_github"]
+branch = true
+
+[tool.coverage.report]
+fail_under = 90
+show_missing = true
+
+[tool.pyright]
+typeCheckingMode = "strict"
+include = ["src"]
+pythonVersion = "3.12"
+
+[tool.hatch.build.targets.sdist]
+exclude = [".venv", ".acceptance", ".preview", "dist", "web/node_modules", "**/__pycache__", ".pytest_cache", ".mypy_cache", ".coverage*"]