kctl-github 0.2.0__tar.gz

kctl_github-0.2.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.pyc
+.ruff_cache/
+.mypy_cache/
+.pytest_cache/
+dist/
+build/
+*.egg-info/
+.venv/
+.env

kctl_github-0.2.0/PKG-INFO

@@ -0,0 +1,17 @@
+Metadata-Version: 2.4
+Name: kctl-github
+Version: 0.2.0
+Summary: Kodemeio GitHub CLI — cross-repo GitHub management
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: kctl-lib>=0.4.0
+Requires-Dist: pydantic>=2.10.0
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: rich>=13.9.0
+Requires-Dist: typer>=0.15.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.14.0; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.35.0; extra == 'dev'
+Requires-Dist: pytest>=8.3.0; extra == 'dev'
+Requires-Dist: ruff>=0.9.0; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0.0; extra == 'dev'

kctl_github-0.2.0/README.md

@@ -0,0 +1,102 @@
+# kctl-github
+
+Cross-repo GitHub management CLI for kodemeio-* repositories.
+
+## Installation
+
+```bash
+# From workspace root
+uv tool install --editable packages/kctl-github
+
+# Verify
+kctl-github --version
+```
+
+## Quick Start
+
+```bash
+# Initialize config with your GitHub token
+kctl-github config init
+
+# Check API connectivity and rate limits
+kctl-github health
+
+# View dashboard overview of all repos
+kctl-github dashboard
+
+# List all kodemeio-* repositories
+kctl-github repos list
+
+# Check CI status across all repos
+kctl-github ci status
+```
+
+## Command Groups
+
+| Group       | Commands                                   | Description                                      |
+|-------------|--------------------------------------------|--------------------------------------------------|
+| `config`    | init, add, use, show, validate, remove, set, profiles, current | Profile management |
+| `health`    | (default)                                  | API connectivity check and rate limit status     |
+| `dashboard` | (default)                                  | Quick overview of repos, PRs, and CI status      |
+| `repos`     | list, status, show                         | Cross-repo overview for kodemeio-* repositories  |
+| `ci`        | status, show, stats, rerun, bulk-status    | CI/CD monitoring across repositories             |
+| `prs`       | list, show, stale                          | Cross-repo pull request management               |
+| `secrets`   | list, audit, set, rotate                   | Cross-repo Actions secret management             |
+| `labels`    | list, sync, diff                           | Cross-repo label standardization                 |
+| `stats`     | overview, activity, languages, contributors | Repository statistics and insights              |
+| `billing`   | actions, storage, packages, overview       | GitHub Actions billing and usage                 |
+
+## Global Options
+
+All commands support these flags:
+
+| Option              | Description                              |
+|---------------------|------------------------------------------|
+| `--json`            | Output as JSON                           |
+| `--quiet`, `-q`     | Suppress info messages                   |
+| `--format`, `-f`    | Output format: pretty, json, csv, yaml   |
+| `--no-header`       | Omit header row in CSV output            |
+| `--profile`, `-p`   | Use a named config profile               |
+| `--version`, `-V`   | Show version and exit                    |
+
+## Configuration
+
+Config lives in `~/.config/kodemeio/config.yaml` under the `github` service key.
+
+```bash
+# Interactive setup
+kctl-github config init
+
+# Add a named profile
+kctl-github config add --profile work
+
+# Switch active profile
+kctl-github config use work
+
+# Show current config (tokens masked)
+kctl-github config show
+```
+
+Required config fields:
+
+| Field       | Description                        |
+|-------------|------------------------------------|
+| `token`     | GitHub personal access token       |
+| `org`       | GitHub organization (e.g. kodemeio)|
+
+## Development
+
+```bash
+# Install with dev extras
+cd packages/kctl-github
+uv sync --all-extras
+
+# Run tests
+uv run pytest tests/ -v
+
+# Lint
+uv run ruff check src/
+
+# Type check
+uv run mypy src/
+```

kctl_github-0.2.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "kctl-github"
+version = "0.2.0"
+description = "Kodemeio GitHub CLI — cross-repo GitHub management"
+requires-python = ">=3.12"
+dependencies = [
+    "kctl-lib>=0.4.0",
+    "typer>=0.15.0",
+    "rich>=13.9.0",
+    "pydantic>=2.10.0",
+    "pyyaml>=6.0.2",
+    "httpx>=0.28.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.3.0",
+    "pytest-httpx>=0.35.0",
+    "ruff>=0.9.0",
+    "mypy>=1.14.0",
+    "types-PyYAML>=6.0.0",
+]
+
+[project.scripts]
+kctl-github = "kctl_github.cli:_run"
+
+[tool.uv.sources]
+kctl-lib = { workspace = true }
+
+[project.entry-points."kctl_github.plugins"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/kctl_github"]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 120
+
+[tool.mypy]
+python_version = "3.12"
+strict = true

kctl_github-0.2.0/skills/github-admin/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: github-admin
+description: >
+  GitHub cross-repo management via kctl-github CLI (11 groups, ~39 commands).
+  MUST use for ANY kctl-github operation.
+  Triggers on: "actions", "activity", "audit", "billing", "bulk-status", "ci", "config", "contributors", "current", "dashboard", "diff", "generate", "health", "init", "kctl-github", "labels", "languages", "monitor", "overview", "packages", "profile", "profiles", "prs", "remove", "repos", "rerun", "rotate", "secrets", "skill", "stale", "stats", "storage", "sync", "test", "validate".
+  Auto-generated: 2026-04-05
+  registry_hash: 226d58bc8834
+---
+
+# github-admin — kctl-github CLI Reference
+
+> Auto-generated from `kctl-github` command registry. Do not edit manually.
+> To regenerate: `kctl-github skill generate`
+> To add custom content: edit `SKILL.extra.md` in the same directory.
+
+## Overview
+
+**CLI:** `kctl-github`
+**Command groups:** 11
+**Total commands:** ~39
+**Install:** `cd cli && uv tool install --editable .`
+
+## Global Options
+
+| Flag | Description |
+|------|-------------|
+| `--json` | JSON output |
+| `--quiet`, `-q` | Suppress info messages |
+| `--format`, `-f` | Output format: pretty/json/csv/yaml |
+| `--no-header` | Omit CSV header row |
+| `--profile`, `-p` | Config profile name |
+| `--version`, `-V` | Show version |
+
+## Command Reference
+
+### `kctl-github billing`
+
+GitHub Actions billing and usage.
+
+| Command | Description |
+|---------|-------------|
+| `billing actions` | Actions minutes used this billing cycle. |
+| `billing overview` | Combined billing summary. |
+| `billing packages` | Packages data transfer. |
+| `billing storage` | Git LFS + Packages storage usage. |
+
+### `kctl-github ci`
+
+CI/CD monitoring across kodemeio-* repositories.
+
+| Command | Description |
+|---------|-------------|
+| `ci bulk-status` | Table of all repos x workflows with pass/fail matrix. |
+| `ci rerun <repo> [--workflow]` | Re-trigger the latest failed workflow run. |
+| `ci show <repo> [--limit]` | Show workflow runs for a specific repo. |
+| `ci stats [--period]` | CI statistics: success rate, avg duration, failure trends. |
+| `ci status` | Latest workflow run status across ALL repos (pass/fail/running). |
+
+### `kctl-github config`
+
+Profile and configuration management.
+
+| Command | Description |
+|---------|-------------|
+| `config add <name>` | Add a new config profile. |
+| `config current` | Show active profile and resolved context. |
+| `config init` | Interactive config setup. |
+| `config profiles` | List all config profiles. |
+| `config remove <name>` | Remove a config profile. |
+| `config set <key> <value>` | Set a single config value. |
+| `config show` | Show current configuration. |
+| `config test` | Test API connection with current configuration. |
+| `config use <name>` | Switch active config profile. |
+| `config validate` | Validate current config completeness. |
+
+### `kctl-github dashboard`
+
+Quick overview dashboard.
+
+### `kctl-github health`
+
+API connectivity and rate limits.
+
+### `kctl-github labels`
+
+Cross-repo label management.
+
+| Command | Description |
+|---------|-------------|
+| `labels diff` | Show label differences across repos. |
+| `labels list <repo>` | List labels for a repo. |
+| `labels sync <source>` | Copy labels from source repo to all other kodemeio-* repos. |
+
+### `kctl-github prs`
+
+Cross-repo PR management.
+
+| Command | Description |
+|---------|-------------|
+| `prs list` | Open PRs across all kodemeio-* repos. |
+| `prs show <repo> <number>` | Show PR details (delegates to gh pr view). |
+| `prs stale [--days]` | Find PRs with no activity for N days. |
+
+### `kctl-github repos`
+
+Cross-repo overview for kodemeio-* repositories.
+
+| Command | Description |
+|---------|-------------|
+| `repos list` | List all kodemeio-* repos with visibility, default branch, last push. |
+| `repos show <name>` | Show single repo details (size, languages, contributors). |
+| `repos status` | Aggregated status: open PRs, failing CI, stale branches per repo. |
+
+### `kctl-github secrets`
+
+Cross-repo Actions secret management.
+
+| Command | Description |
+|---------|-------------|
+| `secrets audit` | Check which repos have which secrets (matrix view). |
+| `secrets list <repo>` | List Actions secrets for a repo. |
+| `secrets rotate <name>` | Update a secret across all repos that have it. |
+| `secrets set <name> <repos>` | Set a secret across multiple repos (prompts for value). |
+
+### `kctl-github skill`
+
+Claude Code skill management.
+
+| Command | Description |
+|---------|-------------|
+| `skill generate [--output] [--install] [--check]` | Auto-generate SKILL.md from CLI command registry. |
+
+**Examples:**
+```bash
+kctl-github skill generate
+kctl-github skill generate --install
+kctl-github skill generate --check
+```
+
+### `kctl-github stats`
+
+Repository statistics across kodemeio-* repos.
+
+| Command | Description |
+|---------|-------------|
+| `stats activity [--period]` | Commit activity, PR merge rate, issue velocity. |
+| `stats contributors` | Contributor activity across all repos. |
+| `stats languages` | Language breakdown across all repos. |
+| `stats overview` | Total repos, total stars, total issues, total PRs. |
+
+## Configuration
+
+Shared config: `~/.config/kodemeio/config.yaml`
+
+```bash
+kctl-github config init       # Interactive setup
+kctl-github config show       # Show current config
+kctl-github config profiles   # List profiles
+kctl-github config current    # Show active profile
+kctl-github config validate   # Verify config
+```

kctl_github-0.2.0/src/kctl_github/__init__.py

@@ -0,0 +1,3 @@
+"""kctl-github: GitHub integration management."""
+
+__version__ = "0.2.0"

kctl_github-0.2.0/src/kctl_github/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as python -m kctl_github."""
+
+from kctl_github.cli import _run
+
+_run()

kctl_github-0.2.0/src/kctl_github/cli.py

@@ -0,0 +1,133 @@
+"""Main CLI entry point for kctl-github."""
+
+from __future__ import annotations
+
+
+from typing import Annotated
+
+import typer
+from kctl_lib import KctlError, handle_cli_error
+
+from kctl_github import __version__
+from kctl_github.commands.billing import app as billing_app
+from kctl_github.commands.ci import app as ci_app
+from kctl_github.commands.config_cmd import app as config_app
+from kctl_github.commands.dashboard import app as dashboard_app
+from kctl_github.commands.health import app as health_app
+from kctl_github.commands.labels import app as labels_app
+from kctl_github.commands.prs import app as prs_app
+from kctl_github.commands.repos import app as repos_app
+from kctl_github.commands.secrets import app as secrets_app
+from kctl_github.commands.stats import app as stats_app
+from kctl_github.core.callbacks import AppContext
+from kctl_github.core.plugins import discover_and_load_plugins
+from kctl_github.commands.doctor_cmd import app as doctor_app
+from kctl_github.commands.skill_cmd import app as skill_app
+from kctl_lib.self_update import notify_if_outdated
+
+
+def version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"kctl-github {__version__}")
+        raise typer.Exit()
+
+
+app = typer.Typer(
+    name="kctl-github",
+    help="GitHub cross-repo management for kodemeio-* repositories",
+    no_args_is_help=True,
+    rich_markup_mode="rich",
+    pretty_exceptions_enable=False,
+)
+
+
+@app.callback()
+def main(
+    ctx: typer.Context,
+    json_output: Annotated[bool, typer.Option("--json", help="Output as JSON")] = False,
+    quiet: Annotated[bool, typer.Option("--quiet", "-q", help="Suppress info messages")] = False,
+    profile: Annotated[str | None, typer.Option("--profile", "-p", help="Config profile name")] = None,
+    format: Annotated[str, typer.Option("--format", "-f", help="Output format: pretty, json, csv, yaml")] = "pretty",
+    no_header: Annotated[bool, typer.Option("--no-header", help="Omit header row in CSV output")] = False,
+    version: Annotated[
+        bool, typer.Option("--version", "-V", callback=version_callback, is_eager=True, help="Show version")
+    ] = False,
+) -> None:
+    """GitHub cross-repo management for kodemeio-* repositories."""
+    ctx.ensure_object(dict)
+    ctx.obj = AppContext(
+        json_mode=json_output,
+        quiet=quiet,
+        profile=profile,
+        format=format,
+        no_header=no_header,
+    )
+    notify_if_outdated(ctx.obj.output, "kctl-github", __version__)
+
+
+# Register command groups
+app.add_typer(config_app, name="config")
+app.add_typer(health_app, name="health")
+app.add_typer(dashboard_app, name="dashboard")
+app.add_typer(repos_app, name="repos")
+app.add_typer(ci_app, name="ci")
+app.add_typer(prs_app, name="prs")
+app.add_typer(secrets_app, name="secrets")
+app.add_typer(labels_app, name="labels")
+app.add_typer(stats_app, name="stats")
+app.add_typer(billing_app, name="billing")
+app.add_typer(doctor_app, name="doctor")
+app.add_typer(skill_app, name="skill", hidden=True)
+
+# Load third-party plugins via entry points
+discover_and_load_plugins(app)
+
+
+@app.command("self-update")
+def self_update_cmd(ctx: typer.Context) -> None:
+    """Check for updates and upgrade kctl-github."""
+    actx = ctx.obj
+    out = actx.output
+
+    from kctl_lib.self_update import check_update
+    from kctl_lib.self_update import update as do_update
+
+    latest = check_update("kctl-github", __version__)
+    if latest:
+        out.info(f"Updating to {latest}...")
+        do_update("kctl-github")
+        out.success(f"Updated to {latest}")
+    else:
+        out.success("Already up to date")
+
+
+@app.command()
+def completions(
+    shell: Annotated[str, typer.Argument(help="Shell type: zsh, bash, fish")] = "zsh",
+    install: Annotated[bool, typer.Option("--install", help="Install completions")] = False,
+) -> None:
+    """Generate or install shell completions."""
+    from kctl_lib.completions import get_completion_script, install_completions
+
+    if install:
+        path = install_completions("kctl-github", shell)
+        if path:
+            typer.echo(f"Completions installed to {path}")
+        else:
+            typer.echo(f"Could not install completions for {shell}", err=True)
+            raise typer.Exit(code=1)
+    else:
+        script = get_completion_script("kctl-github", shell)
+        typer.echo(script)
+
+
+def _run() -> None:
+    """Entry point with error handling."""
+    try:
+        app()
+    except KctlError as e:
+        handle_cli_error(e)
+
+
+if __name__ == "__main__":
+    _run()

kctl_github-0.2.0/src/kctl_github/commands/billing.py

@@ -0,0 +1,182 @@
+"""GitHub billing and usage commands."""
+
+from __future__ import annotations
+
+import typer
+
+from kctl_github.core.callbacks import AppContext
+
+app = typer.Typer(help="GitHub Actions billing and usage.")
+
+
+@app.command()
+def actions(ctx: typer.Context) -> None:
+    """Actions minutes used this billing cycle."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+    client = actx.client
+    org = client.organization
+
+    # Try org endpoint first, fall back to user
+    try:
+        data = client.get(f"/orgs/{org}/settings/billing/actions")
+    except Exception:  # noqa: BLE001
+        try:
+            data = client.get(f"/users/{org}/settings/billing/actions")
+        except Exception:  # noqa: BLE001
+            out.error("Unable to fetch billing data. Token may lack billing scope.")
+            raise typer.Exit(1) from None
+
+    if out.json_mode:
+        out.raw_json(data)
+        return
+
+    total_min = data.get("total_minutes_used", 0)
+    included_min = data.get("included_minutes", 0)
+    paid_min = data.get("total_paid_minutes_used", 0)
+
+    sections = [
+        (
+            "Actions Minutes",
+            [
+                ("Total Used", f"{total_min} min"),
+                ("Included", f"{included_min} min"),
+                ("Paid Overage", f"{paid_min} min"),
+            ],
+        ),
+    ]
+
+    # Per-OS breakdown if available
+    breakdown = data.get("minutes_used_breakdown", {})
+    if breakdown:
+        os_lines = [(os_name, f"{minutes} min") for os_name, minutes in breakdown.items() if minutes > 0]
+        if os_lines:
+            sections.append(("By OS", os_lines))
+
+    out.detail("Actions Billing", sections)
+
+
+@app.command()
+def storage(ctx: typer.Context) -> None:
+    """Git LFS + Packages storage usage."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+    client = actx.client
+    org = client.organization
+
+    try:
+        data = client.get(f"/orgs/{org}/settings/billing/shared-storage")
+    except Exception:  # noqa: BLE001
+        try:
+            data = client.get(f"/users/{org}/settings/billing/shared-storage")
+        except Exception:  # noqa: BLE001
+            out.error("Unable to fetch storage billing data.")
+            raise typer.Exit(1) from None
+
+    if out.json_mode:
+        out.raw_json(data)
+        return
+
+    sections = [
+        (
+            "Storage",
+            [
+                ("Days Left in Cycle", str(data.get("days_left_in_billing_cycle", "?"))),
+                ("Estimated Paid Storage (GB)", f"{data.get('estimated_paid_storage_for_month', 0):.2f}"),
+                ("Estimated Storage (GB)", f"{data.get('estimated_storage_for_month', 0):.2f}"),
+            ],
+        ),
+    ]
+    out.detail("Storage Billing", sections)
+
+
+@app.command()
+def packages(ctx: typer.Context) -> None:
+    """Packages data transfer."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+    client = actx.client
+    org = client.organization
+
+    try:
+        data = client.get(f"/orgs/{org}/settings/billing/packages")
+    except Exception:  # noqa: BLE001
+        try:
+            data = client.get(f"/users/{org}/settings/billing/packages")
+        except Exception:  # noqa: BLE001
+            out.error("Unable to fetch packages billing data.")
+            raise typer.Exit(1) from None
+
+    if out.json_mode:
+        out.raw_json(data)
+        return
+
+    sections = [
+        (
+            "Packages",
+            [
+                ("Total Bandwidth (GB)", f"{data.get('total_gigabytes_bandwidth_used', 0):.2f}"),
+                ("Included Bandwidth (GB)", f"{data.get('included_gigabytes_bandwidth', 0)}"),
+                ("Paid Bandwidth (GB)", f"{data.get('total_paid_gigabytes_bandwidth_used', 0):.2f}"),
+            ],
+        ),
+    ]
+    out.detail("Packages Billing", sections)
+
+
+@app.command()
+def overview(ctx: typer.Context) -> None:
+    """Combined billing summary."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+    client = actx.client
+    org = client.organization
+
+    results: dict[str, dict] = {}
+
+    # Fetch all billing endpoints
+    for endpoint_name, path_suffix in [
+        ("actions", "actions"),
+        ("storage", "shared-storage"),
+        ("packages", "packages"),
+    ]:
+        try:
+            data = client.get(f"/orgs/{org}/settings/billing/{path_suffix}")
+        except Exception:  # noqa: BLE001
+            try:
+                data = client.get(f"/users/{org}/settings/billing/{path_suffix}")
+            except Exception:  # noqa: BLE001
+                data = {}
+        results[endpoint_name] = data
+
+    if out.json_mode:
+        out.raw_json(results)
+        return
+
+    actions_data = results.get("actions", {})
+    storage_data = results.get("storage", {})
+    packages_data = results.get("packages", {})
+
+    sections = [
+        (
+            "Actions",
+            [
+                ("Minutes Used", f"{actions_data.get('total_minutes_used', 0)}"),
+                ("Minutes Included", f"{actions_data.get('included_minutes', 0)}"),
+            ],
+        ),
+        (
+            "Storage",
+            [
+                ("Estimated (GB)", f"{storage_data.get('estimated_storage_for_month', 0):.2f}"),
+            ],
+        ),
+        (
+            "Packages",
+            [
+                ("Bandwidth Used (GB)", f"{packages_data.get('total_gigabytes_bandwidth_used', 0):.2f}"),
+                ("Bandwidth Included (GB)", f"{packages_data.get('included_gigabytes_bandwidth', 0)}"),
+            ],
+        ),
+    ]
+    out.detail("Billing Overview", sections)