gax-cli 0.4.0__py3-none-any.whl

gax/__init__.py

@@ -0,0 +1,3 @@
+"""GAX — Governed Agent eXecution."""
+
+__version__ = "0.1.0"

gax/adapters/__init__.py

@@ -0,0 +1,3 @@
+from gax.adapters.base import run_adapter
+
+__all__ = ["run_adapter"]

gax/adapters/base.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from typing import Any
+
+from gax.adapters import exec_adapter, http_adapter, k8s_adapter, mock_adapter, mcp_bridge
+from gax.registry import CommandManifest
+
+
+def run_adapter(
+    manifest: CommandManifest,
+    args: dict[str, Any],
+    *,
+    tenant_id: str | None = None,
+) -> dict[str, Any]:
+    if manifest.adapter == "k8s":
+        return k8s_adapter.run(manifest, args, tenant_id=tenant_id)
+    if manifest.adapter == "exec":
+        return exec_adapter.run(manifest, args, tenant_id=tenant_id)
+    if manifest.adapter == "mock":
+        return mock_adapter.run(manifest, args)
+    if manifest.adapter == "mcp":
+        return mcp_bridge.run(manifest, args, tenant_id=tenant_id)
+    if manifest.adapter == "http":
+        return http_adapter.run(manifest, args, tenant_id=tenant_id)
+    raise RuntimeError(f"unknown adapter: {manifest.adapter}")

gax/adapters/exec_adapter.py

@@ -0,0 +1,261 @@
+from __future__ import annotations
+
+import json
+import os
+import re
+import shutil
+import subprocess
+from typing import Any
+
+from gax.adapters import mock_adapter
+from gax.oauth import load_tokens
+from gax.registry import CommandManifest
+
+
+def _gh_available() -> bool:
+    return shutil.which("gh") is not None
+
+
+def _gh_env(tenant_id: str | None) -> dict[str, str]:
+    env = os.environ.copy()
+    if tenant_id:
+        tokens = load_tokens(tenant_id, "github")
+        if tokens and tokens.get("access_token"):
+            env["GH_TOKEN"] = tokens["access_token"]
+    return env
+
+
+def run(
+    manifest: CommandManifest,
+    args: dict[str, Any],
+    *,
+    tenant_id: str | None = None,
+) -> dict[str, Any]:
+    if not _gh_available():
+        return mock_adapter.run(manifest, args)
+
+    name = _HANDLERS.get(manifest.command)
+    if name is None:
+        raise RuntimeError(f"exec adapter has no handler for {manifest.command}")
+    # Resolve the handler by name at call time rather than capturing the function
+    # object in the table. Binding at import makes monkeypatching a handler
+    # silently ineffective — the table would keep calling the original.
+    handler = globals()[name]
+    if manifest.command in _MUTATING:
+        return handler(args, tenant_id=tenant_id, dry_run=bool(args.get("dry_run")))
+    return handler(args, tenant_id=tenant_id)
+
+
+def _gh_pr_list(args: dict[str, Any], *, tenant_id: str | None = None) -> dict[str, Any]:
+    repo = args["repo"]
+    limit = int(args.get("limit", 30))
+    state = args.get("state", "open")
+    cmd = [
+        "gh",
+        "pr",
+        "list",
+        "--repo",
+        repo,
+        "--limit",
+        str(limit),
+        "--state",
+        state,
+        "--json",
+        "number,title,state,url,author,isDraft",
+    ]
+    proc = subprocess.run(cmd, capture_output=True, text=True, timeout=60, env=_gh_env(tenant_id))
+    if proc.returncode != 0:
+        raise RuntimeError(proc.stderr.strip() or "gh pr list failed")
+    raw = json.loads(proc.stdout or "[]")
+    items = []
+    for row in raw:
+        author = row.get("author") or {}
+        items.append(
+            {
+                "number": row["number"],
+                "title": row["title"],
+                "state": row["state"],
+                "url": row["url"],
+                "author": author.get("login", "unknown"),
+                "draft": row.get("isDraft", False),
+            }
+        )
+    return {"items": items}
+
+
+def _gh_pr_view(args: dict[str, Any], *, tenant_id: str | None = None) -> dict[str, Any]:
+    repo = args["repo"]
+    number = int(args["number"])
+    cmd = [
+        "gh",
+        "pr",
+        "view",
+        str(number),
+        "--repo",
+        repo,
+        "--json",
+        "number,title,body,state,url,author",
+    ]
+    proc = subprocess.run(cmd, capture_output=True, text=True, timeout=60, env=_gh_env(tenant_id))
+    if proc.returncode != 0:
+        raise RuntimeError(proc.stderr.strip() or "gh pr view failed")
+    row = json.loads(proc.stdout or "{}")
+    author = row.get("author") or {}
+    return {
+        "number": row["number"],
+        "title": row["title"],
+        "body": (row.get("body") or "")[:2000],
+        "state": row["state"],
+        "url": row["url"],
+        "author": author.get("login", "unknown"),
+    }
+
+
+def _repo(args: dict[str, Any]) -> str:
+    """Validate owner/name before it reaches the gh subprocess."""
+    repo = str(args.get("repo") or "").strip()
+    if not re.fullmatch(r"[\w.-]+/[\w.-]+", repo):
+        raise ValueError(f"invalid repo {repo!r}; expected owner/name")
+    return repo
+
+
+def _gh(argv: list[str], tenant_id: str | None) -> str:
+    proc = subprocess.run(
+        ["gh", *argv], capture_output=True, text=True, timeout=60, env=_gh_env(tenant_id)
+    )
+    if proc.returncode != 0:
+        raise RuntimeError(proc.stderr.strip() or f"gh {' '.join(argv)} failed")
+    return proc.stdout
+
+
+def _gh_issue_list(args: dict[str, Any], *, tenant_id: str | None = None) -> dict[str, Any]:
+    repo = _repo(args)
+    argv = [
+        "issue", "list", "--repo", repo,
+        "--limit", str(int(args.get("limit", 30))),
+        "--state", str(args.get("state", "open")),
+        "--json", "number,title,state,url,author",
+    ]
+    rows = json.loads(_gh(argv, tenant_id) or "[]")
+    return {
+        "items": [
+            {
+                "number": r["number"],
+                "title": r["title"],
+                "state": r["state"],
+                "url": r["url"],
+                "author": (r.get("author") or {}).get("login", "unknown"),
+            }
+            for r in rows
+        ]
+    }
+
+
+def _gh_issue_view(args: dict[str, Any], *, tenant_id: str | None = None) -> dict[str, Any]:
+    repo = _repo(args)
+    number = int(args["number"])
+    row = json.loads(
+        _gh(
+            ["issue", "view", str(number), "--repo", repo,
+             "--json", "number,title,body,state,url,author"],
+            tenant_id,
+        )
+        or "{}"
+    )
+    return {
+        "number": row.get("number"),
+        "title": row.get("title"),
+        "body": (row.get("body") or "")[:2000],
+        "state": row.get("state"),
+        "url": row.get("url"),
+        "author": (row.get("author") or {}).get("login", "unknown"),
+    }
+
+
+def _gh_run_list(args: dict[str, Any], *, tenant_id: str | None = None) -> dict[str, Any]:
+    repo = _repo(args)
+    rows = json.loads(
+        _gh(
+            ["run", "list", "--repo", repo,
+             "--limit", str(int(args.get("limit", 20))),
+             "--json", "databaseId,displayTitle,status,conclusion,workflowName"],
+            tenant_id,
+        )
+        or "[]"
+    )
+    return {
+        "items": [
+            {
+                "id": r.get("databaseId"),
+                "title": r.get("displayTitle"),
+                "workflow": r.get("workflowName"),
+                "status": r.get("status"),
+                "conclusion": r.get("conclusion"),
+            }
+            for r in rows
+        ]
+    }
+
+
+def _gh_pr_comment(
+    args: dict[str, Any], *, tenant_id: str | None = None, dry_run: bool = False
+) -> dict[str, Any]:
+    repo = _repo(args)
+    number = int(args["number"])
+    body = str(args.get("body") or "").strip()
+    if not body:
+        raise ValueError("body is required")
+    if dry_run:
+        return {"posted": False, "repo": repo, "number": number, "dry_run": True}
+    out = _gh(["pr", "comment", str(number), "--repo", repo, "--body", body], tenant_id)
+    return {
+        "posted": True,
+        "repo": repo,
+        "number": number,
+        "dry_run": False,
+        "url": out.strip(),
+    }
+
+
+def _gh_pr_merge(
+    args: dict[str, Any], *, tenant_id: str | None = None, dry_run: bool = False
+) -> dict[str, Any]:
+    repo = _repo(args)
+    number = int(args["number"])
+    method = str(args.get("method") or "squash").lower()
+    if method not in {"merge", "squash", "rebase"}:
+        raise ValueError(f"invalid merge method {method!r}; expected merge|squash|rebase")
+    if dry_run:
+        return {
+            "merged": False,
+            "repo": repo,
+            "number": number,
+            "method": method,
+            "dry_run": True,
+        }
+    out = _gh(["pr", "merge", str(number), "--repo", repo, f"--{method}"], tenant_id)
+    return {
+        "merged": True,
+        "repo": repo,
+        "number": number,
+        "method": method,
+        "dry_run": False,
+        "output": out.strip(),
+    }
+
+
+# Table-driven so a new gh manifest needs one entry, not an if-branch.
+# Values are function *names*, resolved at call time in run() — see the comment
+# there. Mutating commands receive dry_run; read-only ones cannot accept one
+# they would silently ignore.
+_HANDLERS = {
+    "gh.pr.list": "_gh_pr_list",
+    "gh.pr.view": "_gh_pr_view",
+    "gh.issue.list": "_gh_issue_list",
+    "gh.issue.view": "_gh_issue_view",
+    "gh.run.list": "_gh_run_list",
+    "gh.pr.comment": "_gh_pr_comment",
+    "gh.pr.merge": "_gh_pr_merge",
+}
+
+_MUTATING = {"gh.pr.comment", "gh.pr.merge"}

gax/adapters/http_adapter.py

@@ -0,0 +1,33 @@
+"""Generic HTTP adapter for OpenAPI-generated manifests."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from gax.registry import CommandManifest
+
+
+def run(manifest: CommandManifest, args: dict[str, Any], **_: Any) -> dict[str, Any]:
+    http = (manifest.raw or {}).get("http") or {}
+    method = str(http.get("method", "GET")).upper()
+    url_template = str(http.get("url", ""))
+    if not url_template:
+        raise RuntimeError(f"http.url missing for {manifest.command}")
+
+    url = url_template
+    path_params = http.get("path_params") or []
+    query_params = http.get("query_params") or []
+    for p in path_params:
+        url = url.replace("{" + p + "}", str(args[p]))
+    query = {p: args[p] for p in query_params if p in args}
+
+    headers = dict(http.get("headers") or {})
+    with httpx.Client(timeout=60.0) as client:
+        resp = client.request(method, url, params=query, headers=headers)
+        resp.raise_for_status()
+        try:
+            return resp.json()
+        except Exception:
+            return {"text": resp.text}

gax/adapters/k8s_adapter.py

@@ -0,0 +1,338 @@
+"""
+Kubernetes exec adapter — the first commands in GAX with real blast radius.
+
+Until now every registered command was `side_effects: read`, so the destructive
+path through policy had never executed. These commands exist to make that path
+real: `k8s.pod.delete` and `k8s.deployment.scale` can genuinely break a running
+system, which is what makes the enforcement guarantee demonstrable rather than
+architectural.
+
+Three safety properties, in order of importance:
+
+1. **`--dry-run` is honored server-side**, not by the caller. A dry run maps to
+   `kubectl --dry-run=server` where kubectl supports it, so the API server
+   validates without mutating.
+2. **Args are passed as an argv list**, never through a shell. There is no string
+   interpolation into a command line anywhere in this module, so a namespace of
+   `; rm -rf /` is an invalid k8s name rather than an injection.
+3. **Identifiers are validated** against the DNS-1123 subset kubectl accepts,
+   before the subprocess is spawned.
+
+`kubectl` absent → mock response, so tests and demos run without a cluster.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import shutil
+import subprocess
+from typing import Any
+
+from gax.registry import CommandManifest
+
+# DNS-1123: lowercase alphanumerics and '-', must start/end alphanumeric.
+# Deliberately strict — anything outside this is rejected before exec.
+_NAME_RE = re.compile(r"^[a-z0-9]([-a-z0-9]*[a-z0-9])?$")
+_MAX_NAME = 253
+
+TIMEOUT_S = 60
+
+
+class K8sArgError(ValueError):
+    """Invalid Kubernetes identifier — raised before any subprocess runs."""
+
+
+def _validate_name(value: Any, field: str) -> str:
+    name = str(value or "").strip()
+    if not name:
+        raise K8sArgError(f"{field} is required")
+    if len(name) > _MAX_NAME:
+        raise K8sArgError(f"{field} exceeds {_MAX_NAME} characters")
+    if not _NAME_RE.match(name):
+        raise K8sArgError(
+            f"invalid {field}: {name!r} (must match DNS-1123: lowercase "
+            "alphanumeric and '-', starting and ending alphanumeric)"
+        )
+    return name
+
+
+def _kubectl_available() -> bool:
+    """
+    Whether to drive real kubectl.
+
+    `kubectl` being on PATH is not enough — it is commonly installed with no
+    reachable cluster (CI, laptops), where every call fails with a connection
+    error. `GAX_K8S_MOCK=1` forces the mock path so tests and demos are
+    deterministic regardless of local kube context.
+    """
+    if os.environ.get("GAX_K8S_MOCK") == "1":
+        return False
+    return shutil.which("kubectl") is not None
+
+
+def _run_kubectl(argv: list[str]) -> str:
+    proc = subprocess.run(
+        ["kubectl", *argv],
+        capture_output=True,
+        text=True,
+        timeout=TIMEOUT_S,
+    )
+    if proc.returncode != 0:
+        raise RuntimeError(proc.stderr.strip() or f"kubectl {' '.join(argv)} failed")
+    return proc.stdout
+
+
+def run(
+    manifest: CommandManifest,
+    args: dict[str, Any],
+    *,
+    tenant_id: str | None = None,
+) -> dict[str, Any]:
+    dry_run = bool(args.get("dry_run"))
+
+    name = _HANDLERS.get(manifest.command)
+    if name is None:
+        raise RuntimeError(f"k8s adapter has no handler for {manifest.command}")
+    # Resolved by name at call time so monkeypatching a handler actually takes
+    # effect; a table of function objects binds at import and silently ignores it.
+    handler = globals()[name]
+    if manifest.command in _MUTATING:
+        return handler(args, dry_run=dry_run)
+    return handler(args)
+
+
+def _pod_list(args: dict[str, Any]) -> dict[str, Any]:
+    namespace = _validate_name(args.get("namespace", "default"), "namespace")
+    if not _kubectl_available():
+        return {
+            "items": [{"name": "mock-pod-1", "namespace": namespace, "status": "Running"}],
+            "_mock": True,
+        }
+    out = _run_kubectl(["get", "pods", "-n", namespace, "-o", "json"])
+    payload = json.loads(out or "{}")
+    return {
+        "items": [
+            {
+                "name": (i.get("metadata") or {}).get("name"),
+                "namespace": namespace,
+                "status": (i.get("status") or {}).get("phase"),
+            }
+            for i in payload.get("items", [])
+        ]
+    }
+
+
+def _pod_delete(args: dict[str, Any], *, dry_run: bool) -> dict[str, Any]:
+    namespace = _validate_name(args.get("namespace", "default"), "namespace")
+    pod = _validate_name(args.get("pod"), "pod")
+
+    if not _kubectl_available():
+        return {
+            "deleted": not dry_run,
+            "pod": pod,
+            "namespace": namespace,
+            "dry_run": dry_run,
+            "_mock": True,
+        }
+
+    argv = ["delete", "pod", pod, "-n", namespace]
+    if dry_run:
+        argv.append("--dry-run=server")
+    out = _run_kubectl(argv)
+    return {
+        "deleted": not dry_run,
+        "pod": pod,
+        "namespace": namespace,
+        "dry_run": dry_run,
+        "output": out.strip(),
+    }
+
+
+def _resource_list(kind: str, args: dict[str, Any]) -> dict[str, Any]:
+    namespace = _validate_name(args.get("namespace", "default"), "namespace")
+    if not _kubectl_available():
+        return {
+            "items": [{"name": f"mock-{kind}-1", "namespace": namespace}],
+            "_mock": True,
+        }
+    payload = json.loads(_run_kubectl(["get", kind, "-n", namespace, "-o", "json"]) or "{}")
+    return {
+        "items": [
+            {
+                "name": (i.get("metadata") or {}).get("name"),
+                "namespace": namespace,
+            }
+            for i in payload.get("items", [])
+        ]
+    }
+
+
+def _deployment_list(args: dict[str, Any]) -> dict[str, Any]:
+    return _resource_list("deployments", args)
+
+
+def _service_list(args: dict[str, Any]) -> dict[str, Any]:
+    return _resource_list("services", args)
+
+
+def _pod_logs(args: dict[str, Any]) -> dict[str, Any]:
+    namespace = _validate_name(args.get("namespace", "default"), "namespace")
+    pod = _validate_name(args.get("pod"), "pod")
+    tail = int(args.get("tail") or 100)
+    if tail < 1:
+        raise K8sArgError("tail must be >= 1")
+    container = args.get("container")
+    if container:
+        container = _validate_name(container, "container")
+
+    if not _kubectl_available():
+        return {
+            "pod": pod,
+            "namespace": namespace,
+            "lines": [f"[mock] log line for {pod}"],
+            "_mock": True,
+        }
+    argv = ["logs", pod, "-n", namespace, f"--tail={tail}"]
+    if container:
+        argv += ["-c", container]
+    out = _run_kubectl(argv)
+    return {
+        "pod": pod,
+        "namespace": namespace,
+        "lines": out.splitlines(),
+    }
+
+
+def _pod_describe(args: dict[str, Any]) -> dict[str, Any]:
+    namespace = _validate_name(args.get("namespace", "default"), "namespace")
+    pod = _validate_name(args.get("pod"), "pod")
+    if not _kubectl_available():
+        return {"pod": pod, "namespace": namespace, "status": "Running", "_mock": True}
+    payload = json.loads(_run_kubectl(["get", "pod", pod, "-n", namespace, "-o", "json"]) or "{}")
+    status = payload.get("status") or {}
+    return {
+        "pod": pod,
+        "namespace": namespace,
+        "status": status.get("phase"),
+        "conditions": [
+            {"type": c.get("type"), "status": c.get("status")}
+            for c in status.get("conditions", [])
+        ],
+        "containers": [
+            {"name": c.get("name"), "ready": c.get("ready"), "restarts": c.get("restartCount")}
+            for c in status.get("containerStatuses", [])
+        ],
+    }
+
+
+def _deployment_restart(args: dict[str, Any], *, dry_run: bool) -> dict[str, Any]:
+    namespace = _validate_name(args.get("namespace", "default"), "namespace")
+    deployment = _validate_name(args.get("deployment"), "deployment")
+    if not _kubectl_available():
+        return {
+            "restarted": not dry_run,
+            "deployment": deployment,
+            "namespace": namespace,
+            "dry_run": dry_run,
+            "_mock": True,
+        }
+    argv = ["rollout", "restart", f"deployment/{deployment}", "-n", namespace]
+    if dry_run:
+        argv.append("--dry-run=server")
+    out = _run_kubectl(argv)
+    return {
+        "restarted": not dry_run,
+        "deployment": deployment,
+        "namespace": namespace,
+        "dry_run": dry_run,
+        "output": out.strip(),
+    }
+
+
+def _namespace_delete(args: dict[str, Any], *, dry_run: bool) -> dict[str, Any]:
+    namespace = _validate_name(args.get("namespace"), "namespace")
+    if not _kubectl_available():
+        return {
+            "deleted": not dry_run,
+            "namespace": namespace,
+            "dry_run": dry_run,
+            "_mock": True,
+        }
+    argv = ["delete", "namespace", namespace]
+    if dry_run:
+        argv.append("--dry-run=server")
+    out = _run_kubectl(argv)
+    return {
+        "deleted": not dry_run,
+        "namespace": namespace,
+        "dry_run": dry_run,
+        "output": out.strip(),
+    }
+
+
+def _deployment_scale(args: dict[str, Any], *, dry_run: bool) -> dict[str, Any]:
+    namespace = _validate_name(args.get("namespace", "default"), "namespace")
+    deployment = _validate_name(args.get("deployment"), "deployment")
+
+    raw = args.get("replicas")
+    if raw is None:
+        raise K8sArgError("replicas is required")
+    try:
+        replicas = int(raw)
+    except (TypeError, ValueError):
+        raise K8sArgError(f"replicas must be an integer, got {raw!r}") from None
+    if replicas < 0:
+        raise K8sArgError("replicas must be >= 0")
+
+    if not _kubectl_available():
+        return {
+            "scaled": not dry_run,
+            "deployment": deployment,
+            "namespace": namespace,
+            "replicas": replicas,
+            "dry_run": dry_run,
+            "_mock": True,
+        }
+
+    argv = [
+        "scale",
+        f"deployment/{deployment}",
+        f"--replicas={replicas}",
+        "-n",
+        namespace,
+    ]
+    if dry_run:
+        argv.append("--dry-run=server")
+    out = _run_kubectl(argv)
+    return {
+        "scaled": not dry_run,
+        "deployment": deployment,
+        "namespace": namespace,
+        "replicas": replicas,
+        "dry_run": dry_run,
+        "output": out.strip(),
+    }
+
+
+# Dispatch table. Mutating commands receive `dry_run`; read-only ones do not —
+# so a read command can never silently accept a dry_run it would ignore.
+_HANDLERS = {
+    "k8s.pod.list": "_pod_list",
+    "k8s.pod.logs": "_pod_logs",
+    "k8s.pod.describe": "_pod_describe",
+    "k8s.deployment.list": "_deployment_list",
+    "k8s.service.list": "_service_list",
+    "k8s.pod.delete": "_pod_delete",
+    "k8s.deployment.scale": "_deployment_scale",
+    "k8s.deployment.restart": "_deployment_restart",
+    "k8s.namespace.delete": "_namespace_delete",
+}
+
+_MUTATING = {
+    "k8s.pod.delete",
+    "k8s.deployment.scale",
+    "k8s.deployment.restart",
+    "k8s.namespace.delete",
+}