hugoh-repokit 0.1.0__tar.gz

hugoh_repokit-0.1.0/.gitignore

@@ -0,0 +1,4 @@
+__pycache__/
+*.pyc
+dist/
+public/

hugoh_repokit-0.1.0/LICENSE

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

hugoh_repokit-0.1.0/PKG-INFO

@@ -0,0 +1,72 @@
+Metadata-Version: 2.5
+Name: hugoh-repokit
+Version: 0.1.0
+Summary: Repo listing/filtering and CLI-entrypoint plumbing shared by repo-admin's scripts
+Project-URL: Homepage, https://github.com/hugoh/gh-workflows/tree/main/repokit
+Project-URL: Issues, https://github.com/hugoh/gh-workflows/issues
+Project-URL: Repository, https://github.com/hugoh/gh-workflows
+Author: Hugo Haas
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: asyncgh>=0.2.0
+Requires-Dist: reconcilekit>=0.2.0
+Description-Content-Type: text/markdown
+
+# repokit
+
+Repo listing/filtering and CLI-entrypoint plumbing shared by repo-admin-style
+scripts: fetch an account's repos via [`asyncgh`](../asyncgh/README.md), keep
+the non-archived/non-fork (by default) ones matching an `only`/`skip` filter,
+and run work over them in bounded parallel via
+[`reconcilekit`](../reconcilekit/README.md). No config-file loading, no sops,
+no fork/exclude policy — those are a caller concern, which is why
+`list_repos`'s `include_forks` defaults to none included rather than reading
+any file.
+
+Published to PyPI as `hugoh-repokit`; imported as `repokit`.
+
+## API
+
+Full API reference, generated from the docstrings:
+[hugoh.github.io/gh-workflows/repokit](https://hugoh.github.io/gh-workflows/repokit/)
+(rebuilt on every push that touches this package — see
+`.github/workflows/docs.yml`).
+
+## Example
+
+```python
+import asyncio
+
+from repokit import DEFAULT_OWNER, list_repos, run_cli
+
+
+async def main(args) -> int:
+    repos = await list_repos(DEFAULT_OWNER, only=args.only, skip=args.skip)
+    for repo in repos:
+        print(repo.name)
+    return 0
+
+
+def cli(argv: list[str]) -> int:
+    return run_cli(main, parse_args(argv))
+```
+
+## Consumers
+
+`repo-admin/` (in this repo) uses it for `repo_admin.py`/`activity.py`,
+consumed as a uv workspace member there — `repo-admin/lib.py` layers its
+own config-file-backed fork/exclude policy, sops-based secrets, and
+`console`/`progress_bar`/etc. re-exports from `asyncgh`/`reconcilekit` on
+top, kept local since none of that is generic.
+[`digest-action`](https://github.com/hugoh/digest-action) (a separate repo,
+since GitHub Marketplace only publishes actions from a repository root)
+consumes it as a regular PyPI dependency.

hugoh_repokit-0.1.0/README.md

@@ -0,0 +1,49 @@
+# repokit
+
+Repo listing/filtering and CLI-entrypoint plumbing shared by repo-admin-style
+scripts: fetch an account's repos via [`asyncgh`](../asyncgh/README.md), keep
+the non-archived/non-fork (by default) ones matching an `only`/`skip` filter,
+and run work over them in bounded parallel via
+[`reconcilekit`](../reconcilekit/README.md). No config-file loading, no sops,
+no fork/exclude policy — those are a caller concern, which is why
+`list_repos`'s `include_forks` defaults to none included rather than reading
+any file.
+
+Published to PyPI as `hugoh-repokit`; imported as `repokit`.
+
+## API
+
+Full API reference, generated from the docstrings:
+[hugoh.github.io/gh-workflows/repokit](https://hugoh.github.io/gh-workflows/repokit/)
+(rebuilt on every push that touches this package — see
+`.github/workflows/docs.yml`).
+
+## Example
+
+```python
+import asyncio
+
+from repokit import DEFAULT_OWNER, list_repos, run_cli
+
+
+async def main(args) -> int:
+    repos = await list_repos(DEFAULT_OWNER, only=args.only, skip=args.skip)
+    for repo in repos:
+        print(repo.name)
+    return 0
+
+
+def cli(argv: list[str]) -> int:
+    return run_cli(main, parse_args(argv))
+```
+
+## Consumers
+
+`repo-admin/` (in this repo) uses it for `repo_admin.py`/`activity.py`,
+consumed as a uv workspace member there — `repo-admin/lib.py` layers its
+own config-file-backed fork/exclude policy, sops-based secrets, and
+`console`/`progress_bar`/etc. re-exports from `asyncgh`/`reconcilekit` on
+top, kept local since none of that is generic.
+[`digest-action`](https://github.com/hugoh/digest-action) (a separate repo,
+since GitHub Marketplace only publishes actions from a repository root)
+consumes it as a regular PyPI dependency.

hugoh_repokit-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[project]
+name = "hugoh-repokit"
+version = "0.1.0"
+description = "Repo listing/filtering and CLI-entrypoint plumbing shared by repo-admin's scripts"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+  { name = "Hugo Haas" },
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Typing :: Typed",
+]
+
+dependencies = ["asyncgh>=0.2.0", "reconcilekit>=0.2.0"]
+
+[project.urls]
+Homepage = "https://github.com/hugoh/gh-workflows/tree/main/repokit"
+Issues = "https://github.com/hugoh/gh-workflows/issues"
+Repository = "https://github.com/hugoh/gh-workflows"
+
+[dependency-groups]
+dev = ["pytest>=8", "pytest-asyncio>=0.24"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/repokit"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.uv.sources]
+asyncgh = { workspace = true }
+reconcilekit = { workspace = true }

hugoh_repokit-0.1.0/src/repokit/__init__.py

@@ -0,0 +1,39 @@
+"""repokit -- repo listing/filtering and CLI-entrypoint plumbing shared by
+repo-admin's scripts.
+
+Fetches repos via `asyncgh` and runs bounded-parallel work over them via
+`reconcilekit`; adds a `Repo`/`RepoResult` shape and a couple of CLI
+conveniences (`run_cli`, `as_set`) on top. No config-file loading, no sops,
+no fork/exclude policy -- those stay with the caller, which is why
+`list_repos`'s `include_forks` defaults to none included rather than to any
+file-backed default.
+"""
+
+from __future__ import annotations
+
+from .core import (
+    DEFAULT_JOBS,
+    DEFAULT_OWNER,
+    Repo,
+    RepoResult,
+    as_set,
+    filter_repos,
+    list_repos,
+    run_cli,
+    run_parallel,
+)
+from .email import send_email, send_email_from_env
+
+__all__ = [
+    "DEFAULT_JOBS",
+    "DEFAULT_OWNER",
+    "Repo",
+    "RepoResult",
+    "as_set",
+    "filter_repos",
+    "list_repos",
+    "run_cli",
+    "run_parallel",
+    "send_email",
+    "send_email_from_env",
+]

hugoh_repokit-0.1.0/src/repokit/core.py

@@ -0,0 +1,142 @@
+"""Repo listing/filtering and the CLI-entrypoint plumbing shared by
+repo-admin's scripts.
+
+Fetches repos via `asyncgh.fetch_repos` and runs bounded-parallel work over
+them via `reconcilekit.run_parallel` -- this module adds nothing beyond
+that except the `Repo`/`RepoResult` shapes and a couple of CLI conveniences
+(`run_cli`, `as_set`). Config-file-backed policy (which forks to include,
+which repos to exclude from a specific check, secrets) is a caller concern,
+not this package's -- `include_forks` here is just a plain set, with no
+default derived from any file.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import sys
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import TypeVar, cast
+
+from asyncgh import GhError, aclose_client, fetch_repos
+from reconcilekit import Status
+from reconcilekit import run_parallel as _run_parallel
+
+DEFAULT_OWNER = os.environ.get("GH_OWNER", "hugoh")
+DEFAULT_JOBS = int(os.environ.get("GH_JOBS", "6"))
+
+_Args = TypeVar("_Args")
+
+
+@dataclass(frozen=True)
+class Repo:
+    name: str
+    default_branch: str
+    is_private: bool
+    is_fork: bool
+    homepage: str = ""
+
+
+@dataclass
+class RepoResult:
+    repo: Repo
+    line: str
+    status: Status = Status.OK
+    tag: str | None = None
+
+
+def as_set(value: str | None) -> set[str] | None:
+    """Splits a comma-separated string into a set, or `None` if `value` is
+    falsy -- the CLI-argument convention every repo-admin script's
+    `--skip`/repo-list arguments share.
+    """
+    if not value:
+        return None
+    return {v.strip() for v in value.split(",") if v.strip()}
+
+
+def filter_repos(
+    repos_json: list[dict],
+    *,
+    only: set[str] | None = None,
+    skip: set[str] | None = None,
+    include_forks: set[str] | None = None,
+) -> list[Repo]:
+    """Keeps every non-archived repo that's either not a fork or is listed in
+    include_forks, then applies only/skip.
+    """
+    include_forks = include_forks or set()
+    repos = []
+    for entry in repos_json:
+        if entry["archived"]:
+            continue
+        name = entry["name"]
+        if entry["fork"] and name not in include_forks:
+            continue
+        if only and name not in only:
+            continue
+        if skip and name in skip:
+            continue
+        repos.append(
+            Repo(
+                name=name,
+                default_branch=entry.get("default_branch") or "",
+                is_private=entry["private"],
+                is_fork=entry["fork"],
+                homepage=entry.get("homepage") or "",
+            )
+        )
+    return repos
+
+
+async def list_repos(
+    owner: str = DEFAULT_OWNER,
+    *,
+    only: set[str] | None = None,
+    skip: set[str] | None = None,
+    include_forks: set[str] | None = None,
+) -> list[Repo]:
+    """Fetches every repo for `owner` and applies `filter_repos`.
+    `include_forks` defaults to none included -- callers with a
+    file/env-backed fork policy (like repo-admin's) resolve it themselves
+    and pass it in.
+    """
+    # RepoJSON (a TypedDict) isn't assignable to plain dict per ty -- these
+    # helpers work on repo JSON generically, not asyncgh's specific shape.
+    repos_json = cast("list[dict]", await fetch_repos(owner))
+    return filter_repos(repos_json, only=only, skip=skip, include_forks=include_forks)
+
+
+def run_cli(
+    entrypoint: Callable[[_Args], Awaitable[int]],
+    args: _Args,
+) -> int:
+    """Runs an async CLI entrypoint under asyncio, always closing the shared
+    HTTP client afterwards and turning a GhError into a stderr message plus
+    exit code 1 -- the wrapper every repo-admin-style script's main() shares.
+    """
+
+    async def _run() -> int:
+        try:
+            return await entrypoint(args)
+        finally:
+            await aclose_client()
+
+    try:
+        return asyncio.run(_run())
+    except GhError as exc:
+        print(exc, file=sys.stderr)
+        return 1
+
+
+async def run_parallel(
+    repos: list[Repo], worker, *, jobs: int = DEFAULT_JOBS, verbose: bool = False
+) -> list[RepoResult]:
+    """reconcilekit.run_parallel with GhError bound as the failure exception
+    type. See reconcilekit.kernel for the concurrency, failure-isolation,
+    and quiet-suppression behaviour.
+    """
+    return await _run_parallel(
+        repos, worker, jobs=jobs, verbose=verbose, error_cls=GhError
+    )

hugoh_repokit-0.1.0/src/repokit/email.py

@@ -0,0 +1,54 @@
+"""Sends a rendered HTML report via an SMTP relay.
+
+Kept separate from repo-fetching concerns so a consumer can swap this for a
+Slack post, a workflow artifact, or nothing at all, without touching how it
+fetches or renders a report.
+"""
+
+from __future__ import annotations
+
+import os
+import smtplib
+from email.mime.multipart import MIMEMultipart
+from email.mime.text import MIMEText
+
+
+def send_email(
+    html_body: str,
+    *,
+    smtp_host: str,
+    smtp_port: int,
+    smtp_user: str,
+    smtp_password: str,
+    from_addr: str,
+    to_addr: str,
+    subject: str,
+) -> None:
+    msg = MIMEMultipart("alternative")
+    msg["Subject"] = subject
+    msg["From"] = from_addr
+    msg["To"] = to_addr
+    msg.attach(MIMEText("This email requires an HTML-capable mail client.", "plain"))
+    msg.attach(MIMEText(html_body, "html"))
+
+    with smtplib.SMTP(smtp_host, smtp_port) as server:
+        server.starttls()
+        server.login(smtp_user, smtp_password)
+        server.send_message(msg)
+
+
+def send_email_from_env(html_body: str, *, subject: str) -> None:
+    """send_email(), reading the relay and recipient from the environment:
+    SMTP_HOST, SMTP_PORT, SMTP_USERNAME, SMTP_PASSWORD, DIGEST_FROM_EMAIL,
+    DIGEST_TO_EMAIL.
+    """
+    send_email(
+        html_body,
+        smtp_host=os.environ["SMTP_HOST"],
+        smtp_port=int(os.environ["SMTP_PORT"]),
+        smtp_user=os.environ["SMTP_USERNAME"],
+        smtp_password=os.environ["SMTP_PASSWORD"],
+        from_addr=os.environ["DIGEST_FROM_EMAIL"],
+        to_addr=os.environ["DIGEST_TO_EMAIL"],
+        subject=subject,
+    )

hugoh_repokit-0.1.0/tests/test_core.py

@@ -0,0 +1,148 @@
+import pytest
+
+from asyncgh import GhError
+from reconcilekit import Status
+from repokit import Repo, RepoResult, filter_repos, run_cli
+
+REPOS_JSON = [
+    {
+        "name": "public-repo",
+        "fork": False,
+        "archived": False,
+        "private": False,
+        "default_branch": "main",
+    },
+    {
+        "name": "archived-repo",
+        "fork": False,
+        "archived": True,
+        "private": False,
+        "default_branch": "main",
+    },
+    {
+        "name": "fork-repo",
+        "fork": True,
+        "archived": False,
+        "private": False,
+        "default_branch": "main",
+    },
+    {
+        "name": "maintained-fork",
+        "fork": True,
+        "archived": False,
+        "private": True,
+        "default_branch": "master",
+    },
+    {
+        "name": "empty-repo",
+        "fork": False,
+        "archived": False,
+        "private": False,
+        "default_branch": None,
+    },
+]
+
+
+def test_filter_repos_excludes_archived():
+    repos = filter_repos(REPOS_JSON)
+    assert "archived-repo" not in [r.name for r in repos]
+
+
+def test_filter_repos_excludes_forks_by_default():
+    repos = filter_repos(REPOS_JSON)
+    assert "fork-repo" not in [r.name for r in repos]
+    assert "maintained-fork" not in [r.name for r in repos]
+
+
+def test_filter_repos_includes_listed_forks():
+    repos = filter_repos(REPOS_JSON, include_forks={"maintained-fork"})
+    names = [r.name for r in repos]
+    assert "maintained-fork" in names
+    assert "fork-repo" not in names
+
+
+def test_filter_repos_only_filter():
+    repos = filter_repos(REPOS_JSON, only={"public-repo"})
+    assert [r.name for r in repos] == ["public-repo"]
+
+
+def test_filter_repos_skip_filter():
+    repos = filter_repos(REPOS_JSON, skip={"public-repo"})
+    assert "public-repo" not in [r.name for r in repos]
+
+
+def test_filter_repos_fields():
+    repos = filter_repos(REPOS_JSON, only={"public-repo"})
+    assert repos == [
+        Repo(name="public-repo", default_branch="main", is_private=False, is_fork=False)
+    ]
+
+
+def test_filter_repos_reads_homepage():
+    repos_json = [
+        {
+            "name": "site-repo",
+            "fork": False,
+            "archived": False,
+            "private": False,
+            "default_branch": "main",
+            "homepage": "https://example.com",
+        }
+    ]
+    assert filter_repos(repos_json)[0].homepage == "https://example.com"
+
+
+def test_filter_repos_homepage_defaults_to_empty_when_null():
+    repos = filter_repos(REPOS_JSON, only={"public-repo"})
+    assert repos[0].homepage == ""
+
+
+def test_filter_repos_handles_null_default_branch():
+    repos = filter_repos(REPOS_JSON, only={"empty-repo"})
+    assert repos[0].default_branch == ""
+
+
+def test_repo_result_defaults_to_ok_status():
+    repo = Repo(name="repo", default_branch="main", is_private=False, is_fork=False)
+    assert RepoResult(repo, "line").status == Status.OK
+
+
+def test_run_cli_runs_entrypoint_and_closes_client(monkeypatch):
+    closed = []
+    monkeypatch.setattr("repokit.core.aclose_client", _record_close(closed))
+
+    async def entrypoint(args):
+        assert args == "ARGS"
+        return 0
+
+    assert run_cli(entrypoint, "ARGS") == 0
+    assert closed == [True]
+
+
+def test_run_cli_closes_client_even_when_entrypoint_raises(monkeypatch):
+    closed = []
+    monkeypatch.setattr("repokit.core.aclose_client", _record_close(closed))
+
+    async def entrypoint(args):
+        raise RuntimeError("boom")
+
+    with pytest.raises(RuntimeError, match="boom"):
+        run_cli(entrypoint, None)
+    assert closed == [True]
+
+
+def test_run_cli_converts_gh_error_to_exit_code_1(monkeypatch, capsys):
+    monkeypatch.setattr("repokit.core.aclose_client", _record_close([]))
+
+    async def entrypoint(args):
+        raise GhError("nope")
+
+    assert run_cli(entrypoint, None) == 1
+    assert "nope" in capsys.readouterr().err
+
+
+def _record_close(sink):
+    async def _aclose():
+        sink.append(True)
+
+    return _aclose

hugoh_repokit-0.1.0/tests/test_email.py

@@ -0,0 +1,121 @@
+from email import message_from_bytes
+from typing import ClassVar
+
+import pytest
+from repokit.email import send_email, send_email_from_env
+
+
+class FakeSMTP:
+    instances: ClassVar[list] = []
+
+    def __init__(self, host, port):
+        self.host = host
+        self.port = port
+        self.calls = []
+        FakeSMTP.instances.append(self)
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc_info):
+        return False
+
+    def starttls(self):
+        self.calls.append("starttls")
+
+    def login(self, user, password):
+        self.calls.append(("login", user, password))
+
+    def send_message(self, msg):
+        self.calls.append(("send_message", msg))
+
+
+@pytest.fixture(autouse=True)
+def fake_smtp(monkeypatch):
+    FakeSMTP.instances = []
+    monkeypatch.setattr("smtplib.SMTP", FakeSMTP)
+    return FakeSMTP
+
+
+def test_send_email_starttls_login_and_sends(fake_smtp):
+    send_email(
+        "<html>hi</html>",
+        smtp_host="smtp.example.com",
+        smtp_port=587,
+        smtp_user="user",
+        smtp_password="pass",
+        from_addr="from@example.com",
+        to_addr="to@example.com",
+        subject="PR digest",
+    )
+    (instance,) = fake_smtp.instances
+    assert instance.host == "smtp.example.com"
+    assert instance.port == 587
+    assert instance.calls[0] == "starttls"
+    assert instance.calls[1] == ("login", "user", "pass")
+    assert instance.calls[2][0] == "send_message"
+
+
+def test_send_email_message_has_plain_and_html_parts(fake_smtp):
+    send_email(
+        "<html><body>hi</body></html>",
+        smtp_host="smtp.example.com",
+        smtp_port=587,
+        smtp_user="user",
+        smtp_password="pass",
+        from_addr="from@example.com",
+        to_addr="to@example.com",
+        subject="PR digest",
+    )
+    (instance,) = fake_smtp.instances
+    msg = instance.calls[2][1]
+    parsed = message_from_bytes(msg.as_bytes())
+    content_types = {part.get_content_type() for part in parsed.walk()}
+    assert "text/plain" in content_types
+    assert "text/html" in content_types
+
+
+def test_send_email_sets_subject_and_addresses(fake_smtp):
+    send_email(
+        "<html>hi</html>",
+        smtp_host="smtp.example.com",
+        smtp_port=587,
+        smtp_user="user",
+        smtp_password="pass",
+        from_addr="from@example.com",
+        to_addr="to@example.com",
+        subject="PR digest",
+    )
+    (instance,) = fake_smtp.instances
+    msg = instance.calls[2][1]
+    assert msg["Subject"] == "PR digest"
+    assert msg["From"] == "from@example.com"
+    assert msg["To"] == "to@example.com"
+
+
+def test_send_email_from_env_reads_smtp_settings_from_environment(
+    fake_smtp, monkeypatch
+):
+    monkeypatch.setenv("SMTP_HOST", "smtp.example.com")
+    monkeypatch.setenv("SMTP_PORT", "587")
+    monkeypatch.setenv("SMTP_USERNAME", "user")
+    monkeypatch.setenv("SMTP_PASSWORD", "pass")
+    monkeypatch.setenv("DIGEST_FROM_EMAIL", "from@example.com")
+    monkeypatch.setenv("DIGEST_TO_EMAIL", "to@example.com")
+
+    send_email_from_env("<html>hi</html>", subject="PR digest")
+
+    (instance,) = fake_smtp.instances
+    assert instance.host == "smtp.example.com"
+    assert instance.port == 587
+    assert instance.calls[1] == ("login", "user", "pass")
+    msg = instance.calls[2][1]
+    assert msg["Subject"] == "PR digest"
+    assert msg["From"] == "from@example.com"
+    assert msg["To"] == "to@example.com"
+
+
+def test_send_email_from_env_raises_on_missing_env_var(fake_smtp, monkeypatch):
+    monkeypatch.delenv("SMTP_HOST", raising=False)
+    with pytest.raises(KeyError):
+        send_email_from_env("<html>hi</html>", subject="PR digest")