avr-cli 0.1.0__py3-none-any.whl

avrea_cli/commands/cache.py

@@ -0,0 +1,312 @@
+"""Cache management CLI commands."""
+
+from avrea_cli.api_client import ApiClient
+from avrea_cli.click_ext import GhGroup
+from avrea_cli.config import CliConfig
+from avrea_cli.display import get_console_url
+from avrea_cli.display import is_piped
+from avrea_cli.display import open_or_print_url
+from avrea_cli.display import print_piped_header
+from avrea_cli.display import print_piped_row
+from avrea_cli.helpers import ensure_authenticated
+from avrea_cli.helpers import ensure_ctx
+from avrea_cli.helpers import ensure_prompts_allowed
+from avrea_cli.helpers import format_size
+from avrea_cli.helpers import get_org_id
+from avrea_cli.helpers import get_org_slug
+from avrea_cli.helpers import handle_http_error
+from avrea_cli.json_output import emit_json
+from avrea_cli.json_output import emit_json_record
+from avrea_cli.json_output import handle_json_meta
+from avrea_cli.json_output import make_schema
+from avrea_cli.json_output import reject_web_with_json
+from avrea_cli.json_output import split_fields
+from avrea_cli.output import format_key_value
+from avrea_cli.output import format_timestamp
+from avrea_cli.output import output_list
+from avrea_cli.repo_context import resolve_repo_named
+from avrea_cli.repo_context import resolve_repo_or_detect
+from typing import Any
+import click
+import httpx
+
+
+@click.group(cls=GhGroup)
+@click.pass_context
+def cache(ctx):
+    """Inspect and manage the Avrea build cache."""
+    ensure_ctx(ctx)
+
+
+_CACHE_LIST_FIELDS = make_schema(
+    "cache_type", "key", "ref", "size_bytes", "created_at", "last_accessed_at", "version", "hit_count"
+)
+
+
+@cache.command("list")
+@click.option("--repo", "repo_id", help="Repository (org/repo or rep-xxx). Auto-detected from git remote if omitted.")
+@click.option("--org", "org_id", help="Organization ID. Uses default org if not specified (see: avr config set org).")
+@click.option(
+    "--type",
+    "cache_type",
+    type=str,
+    help="Filter by cache type (e.g. gha, bazel, turbo, rclone).",
+)
+@click.option("--key", help="Filter by key prefix.")
+@click.option("--ref", help="Filter by exact ref match.")
+@click.option(
+    "-L", "--limit", type=click.IntRange(1, 1000), default=100, show_default=True, help="Max entries to return."
+)
+@click.option("--offset", type=click.IntRange(min=0), default=0, show_default=True, help="Number of entries to skip.")
+@click.option(
+    "--order",
+    type=click.Choice(["created_at.desc", "created_at.asc"]),
+    default="created_at.desc",
+    show_default=True,
+    help="Sort order.",
+)
+@click.option(
+    "--json",
+    "json_fields",
+    default=None,
+    help='Output JSON. Pass comma-separated field names, "*" for all fields, or "?" to list available fields.',
+)
+@click.option("-q", "--jq", "jq_expr", default=None, help="Filter --json output through a jq expression.")
+@click.option("--web", is_flag=True, help="Open in browser.")
+@click.pass_context
+def cache_list(ctx, repo_id, org_id, cache_type, key, ref, limit, offset, order, json_fields, jq_expr, web: bool):
+    """List cache entries for a repository.
+
+    \b
+    Examples:
+        avr cache list --repo rep-abc123
+        avr cache list --repo rep-abc123 --type gha --limit 50
+        avr cache list --repo rep-abc123 --key "node_modules" --ref refs/heads/main
+        avr cache list --repo rep-abc123 --json key,size_bytes,created_at
+
+    \b
+    JSON FIELDS
+        cache_type, created_at, hit_count, key, last_accessed_at, ref, size_bytes, version
+    """
+    reject_web_with_json(json_fields, web)
+    if handle_json_meta(json_fields, jq_expr, _CACHE_LIST_FIELDS):
+        return
+
+    client: ApiClient = ctx.obj["client"]
+    config: CliConfig = ctx.obj["config"]
+    ensure_authenticated(config)
+
+    org_id = get_org_id(config, org_id, client=client)
+    repo_id = resolve_repo_or_detect(client, config, org_id, repo_id, required=True)
+
+    if web:
+        slug = get_org_slug(client, org_id)
+        console_url = get_console_url(config.public_api_url)
+        url = f"{console_url}/org/{slug}/caches/{repo_id}"
+        open_or_print_url(url)
+        return
+
+    params: dict[str, Any] = {"limit": limit, "order": order}
+    if cache_type:
+        params["cache_type"] = cache_type.lower()
+    if key:
+        params["key"] = key
+    if ref:
+        params["ref"] = ref
+    if offset:
+        params["offset"] = offset
+
+    try:
+        response = client.public_get(f"/orgs/{org_id}/repos/{repo_id}/cache/entries", params=params)
+    except httpx.HTTPStatusError as exc:
+        handle_http_error(exc, "list cache entries")
+
+    entries = response["data"]
+
+    if json_fields is not None:
+        emit_json(entries, split_fields(json_fields, _CACHE_LIST_FIELDS), _CACHE_LIST_FIELDS, jq_expr)
+        return
+
+    if is_piped():
+        print_piped_header(["cache_type", "key", "ref", "size_bytes", "created_at"])
+        for e in entries:
+            print_piped_row(
+                [
+                    e.get("cache_type", ""),
+                    e.get("key", ""),
+                    e.get("ref", ""),
+                    e.get("size_bytes", 0),
+                    e.get("created_at", ""),
+                ]
+            )
+        return
+
+    for entry in entries:
+        entry["size_display"] = format_size(entry.get("size_bytes", 0))
+        entry["key_display"] = entry.get("key") or "-"
+        entry["ref_display"] = entry.get("ref") or "-"
+        entry["created_display"] = format_timestamp(entry.get("created_at"))
+
+    output_list(
+        entries,
+        columns=["cache_type", "key_display", "ref_display", "size_display", "created_display"],
+        column_labels=["Type", "Key", "Ref", "Size", "Created"],
+    )
+
+    total = response.get("total", len(entries))
+    shown = offset + len(entries)
+    if shown < total:
+        click.echo(f"\nShowing {shown}/{total}. Next page: --offset {shown}", err=True)
+
+
+_CACHE_USAGE_FIELDS = make_schema(
+    total_size_bytes="data.total_size_bytes",
+    quota_bytes="data.quota_bytes",
+    over_quota="data.over_quota",
+    by_type="data.by_type",
+)
+
+
+@cache.command("usage")
+@click.option("--repo", "repo_id", help="Repository (org/repo or rep-xxx). Auto-detected from git remote if omitted.")
+@click.option("--org", "org_id", help="Organization ID. Uses default org if not specified (see: avr config set org).")
+@click.option(
+    "--json",
+    "json_fields",
+    default=None,
+    help='Output JSON. Pass comma-separated field names, "*" for all fields, or "?" to list available fields.',
+)
+@click.option("-q", "--jq", "jq_expr", default=None, help="Filter --json output through a jq expression.")
+@click.pass_context
+def cache_usage(ctx, repo_id, org_id, json_fields, jq_expr):
+    """Show cache usage summary for a repository.
+
+    \b
+    Examples:
+        avr cache usage --repo rep-abc123
+        avr cache usage --repo rep-abc123 --json '*'
+
+    \b
+    JSON FIELDS
+        by_type, over_quota, quota_bytes, total_size_bytes
+    """
+    if handle_json_meta(json_fields, jq_expr, _CACHE_USAGE_FIELDS):
+        return
+
+    client: ApiClient = ctx.obj["client"]
+    config: CliConfig = ctx.obj["config"]
+    ensure_authenticated(config)
+
+    org_id = get_org_id(config, org_id, client=client)
+    repo_id = resolve_repo_or_detect(client, config, org_id, repo_id, required=True)
+
+    try:
+        response = client.public_get(f"/orgs/{org_id}/repos/{repo_id}/cache")
+    except httpx.HTTPStatusError as exc:
+        handle_http_error(exc, "get cache usage")
+
+    if json_fields is not None:
+        emit_json_record(response, split_fields(json_fields, _CACHE_USAGE_FIELDS), _CACHE_USAGE_FIELDS, jq_expr)
+        return
+
+    data = response["data"]
+    total = data.get("total_size_bytes", 0)
+    quota = data.get("quota_bytes", 0)
+    pct = (total / quota * 100) if quota > 0 else 0
+
+    click.echo(
+        format_key_value(
+            {
+                "Total Size": format_size(total),
+                "Quota": format_size(quota),
+                "Usage": f"{pct:.1f}%",
+                "Over Quota": "yes" if data.get("over_quota") else "no",
+            }
+        )
+    )
+
+    by_type = data.get("by_type", [])
+    if by_type:
+        click.echo()
+        for bt in by_type:
+            bt["size_display"] = format_size(bt.get("size_bytes", 0))
+
+        output_list(
+            by_type,
+            columns=["cache_type", "size_display", "entry_count"],
+            column_labels=["Type", "Size", "Count"],
+        )
+
+
+@cache.command("delete")
+@click.option("--repo", "repo_id", help="Repository (org/repo or rep-xxx). Auto-detected from git remote if omitted.")
+@click.option("--org", "org_id", help="Organization ID. Uses default org if not specified (see: avr config set org).")
+@click.option(
+    "--type",
+    "cache_type",
+    type=str,
+    default=None,
+    help="Cache type (required with --key, e.g. gha, bazel, sccache).",
+)
+@click.option("--key", default=None, help="Delete entries matching this cache key name.")
+@click.option("--ref", default=None, help="Ref to narrow deletion scope (used by gha).")
+@click.option("--all", "delete_all", is_flag=True, help="Delete ALL cache entries for the repository.")
+@click.option("--yes", "-y", is_flag=True, help="Skip confirmation prompt.")
+@click.pass_context
+def cache_delete(ctx, repo_id, org_id, cache_type, key, ref, delete_all, yes):
+    """Delete cache entries by key name or all entries.
+
+    Exactly one of --key or --all must be provided.
+    When using --key, --type is required to scope the deletion.
+
+    \b
+    Examples:
+        avr cache delete --repo rep-abc123 --type gha --key "node_modules" --ref refs/heads/main --yes
+        avr cache delete --repo rep-abc123 --all --yes
+    """
+    client: ApiClient = ctx.obj["client"]
+    config: CliConfig = ctx.obj["config"]
+    ensure_authenticated(config)
+
+    provided = sum(bool(x) for x in (key, delete_all))
+    if provided != 1:
+        click.echo("Error: Provide exactly one of --key or --all.", err=True)
+        raise click.Abort()
+
+    if key and not cache_type:
+        click.echo("Error: --type is required when using --key.", err=True)
+        raise click.Abort()
+
+    org_id = get_org_id(config, org_id, client=client)
+    repo_id, repo_label = resolve_repo_named(client, config, org_id, repo_id)
+
+    if key:
+        if not yes:
+            ensure_prompts_allowed("cache delete needs confirmation")
+            ref_scope = f"ref '{ref}'" if ref else "across all refs"
+            click.confirm(
+                f"Delete entries in {repo_label} matching type '{cache_type}', key '{key}' ({ref_scope})?",
+                abort=True,
+            )
+        try:
+            params: dict[str, str] = {"cache_type": cache_type, "key": key}
+            if ref:
+                params["ref"] = ref
+            response = client.public_delete(
+                f"/orgs/{org_id}/repos/{repo_id}/cache/entries",
+                params=params,
+            )
+            count = response.get("deleted_count", 0) if response else 0
+            click.echo(f"Deleted {count} cache {'entry' if count == 1 else 'entries'}.")
+        except httpx.HTTPStatusError as exc:
+            handle_http_error(exc, "delete cache entries")
+    else:
+        if not yes:
+            ensure_prompts_allowed("cache purge needs confirmation")
+            click.confirm(f"Delete ALL cache entries for {repo_label}?", abort=True)
+        try:
+            response = client.public_delete(f"/orgs/{org_id}/repos/{repo_id}/cache")
+            count = response.get("deleted_count", 0) if response else 0
+            click.echo(f"Purged {count} cache {'entry' if count == 1 else 'entries'} from {repo_label}.")
+        except httpx.HTTPStatusError as exc:
+            handle_http_error(exc, "purge cache")

avrea_cli/commands/config_cmd.py

@@ -0,0 +1,180 @@
+"""CLI configuration commands (avr config)."""
+
+from avrea_cli import auth
+from avrea_cli.api_client import ApiClient
+from avrea_cli.click_ext import GhGroup
+from avrea_cli.config import CliConfig
+from avrea_cli.helpers import ensure_authenticated
+from avrea_cli.helpers import ensure_ctx
+from avrea_cli.helpers import get_org_slug
+from avrea_cli.helpers import handle_http_error
+from avrea_cli.repo_context import detect_repo_from_git
+from urllib.parse import urlparse
+import click
+import httpx
+import os
+
+
+def _fetch_me(client: ApiClient) -> dict | None:
+    """Best-effort fetch of /users/me; returns None on any error."""
+    try:
+        response = client.public_get("/users/me")
+        return response.get("data") or response
+    except httpx.HTTPStatusError, httpx.ConnectError, httpx.TimeoutException:
+        return None
+
+
+def _src(label: str) -> str:
+    return click.style(f"(from {label})", dim=True)
+
+
+def _print_config_status(ctx) -> None:
+    cfg: CliConfig = ctx.obj["config"]
+    client: ApiClient = ctx.obj["client"]
+
+    # Header: API host with source annotation
+    host = urlparse(cfg.public_api_url).hostname or cfg.public_api_url
+    if os.getenv("AVR_HOST"):
+        host_src = _src("AVR_HOST")
+    elif auth.load_default_host():
+        host_src = _src("hosts.json")
+    else:
+        host_src = _src("default")
+    click.echo(f"{click.style(host, bold=True)} {host_src}")
+
+    # Auth status line
+    if cfg.auth_token:
+        me = _fetch_me(client)
+        token_src = _src("AVR_TOKEN" if os.getenv("AVR_TOKEN") else "hosts.json")
+        if me and me.get("email"):
+            click.echo(f"  {click.style('✓', fg='green')} authenticated as {me['email']} {token_src}")
+        elif me:
+            click.echo(f"  {click.style('✓', fg='green')} authenticated {token_src}")
+        else:
+            click.echo(f"  {click.style('!', fg='yellow')} token set but /users/me failed {token_src}")
+    else:
+        click.echo(f"  {click.style('✗', fg='red')} not authenticated (run: avr auth login)")
+
+    # Active org — show slug if we can resolve it
+    if cfg.default_org:
+        if cfg.auth_token:
+            slug = get_org_slug(client, cfg.default_org)
+            if slug != cfg.default_org:
+                active_org = f"{click.style(slug, bold=True)} ({cfg.default_org})"
+            else:
+                active_org = click.style(cfg.default_org, bold=True)
+        else:
+            active_org = click.style(cfg.default_org, bold=True)
+        org_src = _src("AVR_ORG" if os.getenv("AVR_ORG") else "hosts.json")
+        active_org = f"{active_org} {org_src}"
+    else:
+        active_org = click.style("(not set)", dim=True)
+
+    # Default repo — explicit override or auto-detected from git remote
+    if cfg.repo_override:
+        default_repo = f"{click.style(cfg.repo_override, bold=True)} {_src('AVR_REPO')}"
+    else:
+        detected = detect_repo_from_git()
+        if detected:
+            default_repo = f"{click.style(detected, bold=True)} {_src('git remote')}"
+        else:
+            default_repo = click.style("(no git remote; pass --repo explicitly)", dim=True)
+
+    click.echo(f"  - Active org:   {active_org}")
+    click.echo(f"  - Default repo: {default_repo}")
+
+
+@click.group(cls=GhGroup, invoke_without_command=True)
+@click.pass_context
+def config(ctx):
+    """View and manage CLI configuration."""
+    ensure_ctx(ctx)
+    if ctx.invoked_subcommand is None:
+        _print_config_status(ctx)
+
+
+@config.command("set")
+@click.argument("key", type=click.Choice(["org"]))
+@click.argument("value")
+@click.pass_context
+def config_set(ctx, key: str, value: str):
+    """Set a CLI configuration value.
+
+    \b
+    Available keys:
+      org   Active organization ID
+
+    \b
+    Examples:
+        avr config set org org-abc123
+    """
+    client: ApiClient = ctx.obj["client"]
+    cfg: CliConfig = ctx.obj["config"]
+    ensure_authenticated(cfg)
+
+    if key == "org":
+        # Verify the org exists and user has access
+        try:
+            response = client.public_get("/users/me/organizations")
+            organizations = response["data"]
+        except httpx.HTTPStatusError as exc:
+            handle_http_error(exc, "fetch organizations")
+
+        org_ids = [o["organization_id"] for o in organizations]
+        if value not in org_ids:
+            click.echo(f"Error: Organization '{value}' not found or you don't have access.", err=True)
+            click.echo("Available organizations:", err=True)
+            for o in organizations:
+                click.echo(f"  {o['organization_id']} ({o['name']})", err=True)
+            raise click.Abort()
+
+        auth.store_default_org(value, host=cfg.public_api_url)
+        org_name = next((o["name"] for o in organizations if o["organization_id"] == value), value)
+        click.echo(f"Default organization set to: {org_name} ({value})")
+
+
+@config.command("get")
+@click.argument("key", type=click.Choice(["org"]))
+@click.pass_context
+def config_get(ctx, key: str):
+    """Print the value of a configuration key.
+
+    \b
+    Available keys:
+      org   Active organization ID
+    """
+    cfg: CliConfig = ctx.obj["config"]
+    values = {"org": cfg.default_org or ""}
+    click.echo(values[key])
+
+
+@config.command("list")
+@click.pass_context
+def config_list(ctx):
+    """Show the active CLI configuration (host, auth, org, default repo)."""
+    _print_config_status(ctx)
+
+
+@config.command("unset")
+@click.argument("key", type=click.Choice(["org"]))
+@click.pass_context
+def config_unset(ctx, key: str):
+    """Remove a configuration override.
+
+    \b
+    Available keys:
+      org   Drop the stored default organization for the active host
+
+    \b
+    Examples:
+        avr config unset org
+    """
+    cfg: CliConfig = ctx.obj["config"]
+    if key == "org":
+        # Match the brevity of `config set`: the host is implied by AVR_HOST
+        # / the active default. Showing it would be redundant in the common
+        # single-host install.
+        if auth.clear_default_org(host=cfg.public_api_url):
+            click.echo("Cleared default organization.")
+        else:
+            click.echo("No default organization was set.")

avrea_cli/commands/health.py

@@ -0,0 +1,76 @@
+"""Health check command."""
+
+from avrea_cli.api_client import ApiClient
+from avrea_cli.config import CliConfig
+from avrea_cli.json_output import emit_json_record
+from avrea_cli.json_output import handle_json_meta
+from avrea_cli.json_output import json_options
+from avrea_cli.json_output import make_schema
+from avrea_cli.json_output import split_fields
+from urllib.parse import urlparse
+import click
+import httpx
+
+# Single-key schema for now; add explicit entries as the endpoint grows new
+# keys (build hash, etc.) so `--json '*'` stays in sync with the typed surface.
+_HEALTH_FIELDS = make_schema("status")
+
+
+@click.command("health")
+@json_options
+@click.pass_context
+def health(ctx, json_fields, jq_expr):
+    """Check Avrea platform status.
+
+    \b
+    Examples:
+        avr health
+        avr health --json status
+        avr health --json '*' -q '.status'
+    """
+    if handle_json_meta(json_fields, jq_expr, _HEALTH_FIELDS):
+        return
+
+    client: ApiClient = ctx.obj["client"]
+    config: CliConfig = ctx.obj["config"]
+    host = urlparse(config.public_api_url).hostname or config.public_api_url
+    is_json = json_fields is not None
+
+    if not is_json:
+        click.echo("Checking API health...")
+
+    try:
+        result = client.public_get("/health")
+    except (httpx.HTTPStatusError, httpx.ConnectError, httpx.TimeoutException) as exc:
+        reason = _humanize_health_failure(exc, host)
+        if is_json:
+            # Same JSON shape as success — schema-projected, no extra keys.
+            # Humans get the friendly reason on stderr; consumers get the
+            # stable {"status": "unreachable"} record.
+            click.echo(f"API unreachable: {reason}", err=True)
+            emit_json_record(
+                {"status": "unreachable"},
+                split_fields(json_fields, _HEALTH_FIELDS),
+                _HEALTH_FIELDS,
+                jq_expr,
+            )
+        else:
+            click.echo(f"✗ API: {reason}", err=True)
+        raise click.Abort() from None
+
+    if is_json:
+        emit_json_record(result, split_fields(json_fields, _HEALTH_FIELDS), _HEALTH_FIELDS, jq_expr)
+        return
+
+    status = result.get("status", "unknown")
+    click.echo(f"✓ API: {status}")
+
+
+def _humanize_health_failure(exc: Exception, host: str) -> str:
+    if isinstance(exc, httpx.ConnectError):
+        return f"couldn't reach {host} — check your network connection."
+    if isinstance(exc, httpx.TimeoutException):
+        return f"{host} took too long to respond."
+    if isinstance(exc, httpx.HTTPStatusError):
+        return f"HTTP {exc.response.status_code} from {host}."
+    return f"{host} unreachable."

avrea_cli/commands/internal.py

@@ -0,0 +1,18 @@
+"""Hidden ``avr internal`` command group.
+
+Houses maintenance commands that ship with the CLI but aren't part of the
+public surface — listed here so the published ``avr`` binary can dogfood
+its own docs generator (``avr internal docs``) without polluting the
+top-level help text.
+"""
+
+from avrea_cli.docs_gen import docs_command
+import click
+
+
+@click.group("internal", hidden=True)
+def internal() -> None:
+    """Maintenance commands (hidden)."""
+
+
+internal.add_command(docs_command)