kctl-github 0.2.0__py3-none-any.whl

kctl_github/__init__.py

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

kctl_github/__main__.py

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

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/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)

kctl_github/commands/ci.py

@@ -0,0 +1,271 @@
+"""CI/CD monitoring commands."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime, timedelta
+from typing import Annotated
+
+import typer
+
+from kctl_github.core.callbacks import AppContext
+from kctl_github.core.client import gh_run
+
+app = typer.Typer(help="CI/CD monitoring across kodemeio-* repositories.")
+
+
+@app.command()
+def status(ctx: typer.Context) -> None:
+    """Latest workflow run status across ALL repos (pass/fail/running)."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+    client = actx.client
+
+    repos = client.get_repos()
+    rows = []
+
+    for repo in sorted(repos, key=lambda x: x["name"]):
+        name = repo["name"]
+        runs = client.get(
+            f"/repos/{client.organization}/{name}/actions/runs",
+            params={"per_page": 1},
+        )
+        workflow_runs = runs.get("workflow_runs", [])
+        if workflow_runs:
+            run_data = workflow_runs[0]
+            conclusion = run_data.get("conclusion") or run_data.get("status", "unknown")
+            workflow = run_data.get("name", "")
+            created = run_data.get("created_at", "")[:10]
+            rows.append([name, workflow, conclusion, created])
+        else:
+            rows.append([name, "-", "no runs", ""])
+
+    if out.json_mode:
+        out.raw_json(
+            [
+                {
+                    "repo": r[0],
+                    "workflow": r[1],
+                    "conclusion": r[2],
+                    "date": r[3],
+                }
+                for r in rows
+            ]
+        )
+        return
+
+    out.table(
+        "CI Status (latest run per repo)",
+        [("Repo", "cyan"), ("Workflow", ""), ("Status", "green"), ("Date", "yellow")],
+        rows,
+    )
+
+
+@app.command()
+def show(
+    ctx: typer.Context,
+    repo: Annotated[str, typer.Argument(help="Repository name")],
+    limit: Annotated[int, typer.Option("--limit", "-n", help="Number of runs")] = 10,
+) -> None:
+    """Show workflow runs for a specific repo."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+    client = actx.client
+
+    runs = client.get(
+        f"/repos/{client.organization}/{repo}/actions/runs",
+        params={"per_page": limit},
+    )
+    workflow_runs = runs.get("workflow_runs", [])
+
+    if out.json_mode:
+        out.raw_json(
+            [
+                {
+                    "id": r["id"],
+                    "name": r.get("name", ""),
+                    "status": r.get("status"),
+                    "conclusion": r.get("conclusion"),
+                    "branch": r.get("head_branch"),
+                    "created_at": r.get("created_at"),
+                    "run_number": r.get("run_number"),
+                }
+                for r in workflow_runs
+            ]
+        )
+        return
+
+    rows = []
+    for r in workflow_runs:
+        conclusion = r.get("conclusion") or r.get("status", "unknown")
+        rows.append(
+            [
+                str(r.get("run_number", "")),
+                r.get("name", ""),
+                r.get("head_branch", ""),
+                conclusion,
+                r.get("created_at", "")[:10],
+            ]
+        )
+
+    out.table(
+        f"Workflow Runs: {repo}",
+        [("Run #", ""), ("Workflow", "cyan"), ("Branch", ""), ("Status", "green"), ("Date", "yellow")],
+        rows,
+    )
+
+
+@app.command()
+def stats(
+    ctx: typer.Context,
+    period: Annotated[str, typer.Option("--period", help="Time period (e.g., 7d, 30d)")] = "7d",
+) -> None:
+    """CI statistics: success rate, avg duration, failure trends."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+    client = actx.client
+
+    # Parse period
+    days = int(period.rstrip("d"))
+    since = datetime.now(UTC).replace(hour=0, minute=0, second=0)
+    since = since - timedelta(days=days)
+    since_str = since.strftime("%Y-%m-%dT%H:%M:%SZ")
+
+    repos = client.get_repos()
+    total_runs = 0
+    total_success = 0
+    total_failure = 0
+    repo_stats: list[dict[str, str | int]] = []
+
+    for repo in repos:
+        name = repo["name"]
+        runs = client.get(
+            f"/repos/{client.organization}/{name}/actions/runs",
+            params={"per_page": 100, "created": f">={since_str}"},
+        )
+        workflow_runs = runs.get("workflow_runs", [])
+        count = len(workflow_runs)
+        success = sum(1 for r in workflow_runs if r.get("conclusion") == "success")
+        failure = sum(1 for r in workflow_runs if r.get("conclusion") == "failure")
+
+        total_runs += count
+        total_success += success
+        total_failure += failure
+
+        if count > 0:
+            repo_stats.append(
+                {
+                    "repo": name,
+                    "runs": count,
+                    "success": success,
+                    "failure": failure,
+                    "success_rate": f"{(success / count * 100):.0f}%",
+                }
+            )
+
+    if out.json_mode:
+        out.raw_json(
+            {
+                "period_days": days,
+                "total_runs": total_runs,
+                "total_success": total_success,
+                "total_failure": total_failure,
+                "success_rate": f"{(total_success / total_runs * 100):.0f}%" if total_runs else "N/A",
+                "repos": repo_stats,
+            }
+        )
+        return
+
+    # Summary
+    rate = f"{(total_success / total_runs * 100):.0f}%" if total_runs else "N/A"
+    out.success(f"CI Stats (last {days} days): {total_runs} runs, {rate} success rate")
+
+    rows = [
+        [str(s["repo"]), str(s["runs"]), str(s["success"]), str(s["failure"]), str(s["success_rate"])]
+        for s in sorted(repo_stats, key=lambda x: int(x["runs"]), reverse=True)
+    ]
+    out.table(
+        "Per-Repo CI Stats",
+        [("Repo", "cyan"), ("Runs", ""), ("Pass", "green"), ("Fail", "red"), ("Rate", "yellow")],
+        rows,
+    )
+
+
+@app.command()
+def rerun(
+    ctx: typer.Context,
+    repo: Annotated[str, typer.Argument(help="Repository name")],
+    workflow: Annotated[str | None, typer.Option("--workflow", "-w", help="Workflow name filter")] = None,
+) -> None:
+    """Re-trigger the latest failed workflow run."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+    client = actx.client
+    owner = client.organization
+
+    runs = client.get(
+        f"/repos/{owner}/{repo}/actions/runs",
+        params={"status": "failure", "per_page": 5},
+    )
+    workflow_runs = runs.get("workflow_runs", [])
+
+    if workflow and workflow_runs:
+        workflow_runs = [r for r in workflow_runs if workflow.lower() in r.get("name", "").lower()]
+
+    if not workflow_runs:
+        out.warn("No failed workflow runs found")
+        return
+
+    run_data = workflow_runs[0]
+    run_id = run_data["id"]
+
+    # Use gh CLI for rerun (simpler auth)
+    gh_run(["run", "rerun", str(run_id), "--repo", f"{owner}/{repo}", "--failed"])
+    out.success(f"Re-triggered run #{run_data.get('run_number')} ({run_data.get('name')}) in {repo}")
+
+
+@app.command("bulk-status")
+def bulk_status(ctx: typer.Context) -> None:
+    """Table of all repos x workflows with pass/fail matrix."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+    client = actx.client
+
+    repos = client.get_repos()
+    all_workflows: set[str] = set()
+    repo_workflow_status: dict[str, dict[str, str]] = {}
+
+    for repo in sorted(repos, key=lambda x: x["name"]):
+        name = repo["name"]
+        runs = client.get(
+            f"/repos/{client.organization}/{name}/actions/runs",
+            params={"per_page": 20},
+        )
+        workflow_runs = runs.get("workflow_runs", [])
+
+        seen: dict[str, str] = {}
+        for r in workflow_runs:
+            wf_name = r.get("name", "unknown")
+            if wf_name not in seen:
+                conclusion = r.get("conclusion") or r.get("status", "?")
+                seen[wf_name] = conclusion
+                all_workflows.add(wf_name)
+
+        repo_workflow_status[name] = seen
+
+    sorted_workflows = sorted(all_workflows)
+
+    if out.json_mode:
+        out.raw_json(repo_workflow_status)
+        return
+
+    columns: list[tuple[str, str]] = [("Repo", "cyan")]
+    columns.extend((wf, "") for wf in sorted_workflows)
+
+    rows = []
+    for repo_name in sorted(repo_workflow_status.keys()):
+        row = [repo_name]
+        for wf in sorted_workflows:
+            row.append(repo_workflow_status[repo_name].get(wf, "-"))
+        rows.append(row)
+
+    out.table("CI Bulk Status", columns, rows)