gax-cli 0.4.0__py3-none-any.whl

gax/plan.py

@@ -0,0 +1,151 @@
+from __future__ import annotations
+
+import re
+import time
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from typing import Any, Callable
+
+import yaml
+
+from gax.envelope import make_envelope, timed_meta
+from gax.executor import invoke
+from gax.registry import Registry
+
+_TEMPLATE = re.compile(r"\{\{\s*([^}]+)\s*\}\}")
+
+
+def load_plan(path: str) -> dict[str, Any]:
+    with open(path, encoding="utf-8") as f:
+        return yaml.safe_load(f) or {}
+
+
+def _resolve_path(expr: str, ctx: dict[str, Any]) -> Any:
+    parts = expr.strip().split(".")
+    cur: Any = ctx
+    for p in parts:
+        if p.endswith("]"):
+            key, idx = p[:-1].split("[")
+            cur = cur[key][int(idx)]
+        elif "[" in p:
+            key, rest = p.split("[", 1)
+            idx = int(rest.rstrip("]"))
+            cur = cur[key][idx]
+        else:
+            cur = cur[p]
+    return cur
+
+
+def render_value(value: Any, ctx: dict[str, Any]) -> Any:
+    if isinstance(value, str):
+        stripped = value.strip()
+        m = re.fullmatch(r"\{\{\s*([^}]+)\s*\}\}", stripped)
+        if m:
+            return _resolve_path(m.group(1), ctx)
+
+        def repl(match: re.Match[str]) -> str:
+            resolved = _resolve_path(match.group(1), ctx)
+            return str(resolved)
+
+        return _TEMPLATE.sub(repl, value)
+    if isinstance(value, dict):
+        return {k: render_value(v, ctx) for k, v in value.items()}
+    if isinstance(value, list):
+        return [render_value(v, ctx) for v in value]
+    return value
+
+
+def _run_step(
+    step: dict[str, Any],
+    ctx: dict[str, Any],
+    surface: str,
+    invoke_fn: Callable[..., tuple[dict[str, Any], int]],
+) -> tuple[str, dict[str, Any], int]:
+    step_id = step.get("id") or step.get("command")
+    command = step["command"]
+    args = render_value(step.get("args") or {}, ctx)
+    env, code = invoke_fn(command=command, args=args, surface=surface)
+    ctx["steps"][step_id] = {
+        "ok": env.get("ok"),
+        "data": env.get("data"),
+        "meta": env.get("meta"),
+        "audit_id": env.get("audit_id"),
+    }
+    summary = {
+        "id": step_id,
+        "command": command,
+        "ok": env.get("ok"),
+        "audit_id": env.get("audit_id"),
+    }
+    return step_id, summary, code
+
+
+def run_plan(
+    registry: Registry,
+    plan: dict[str, Any],
+    *,
+    surface: str = "model",
+    capability: str | None = None,
+    invoke_fn: Callable[..., tuple[dict[str, Any], int]] | None = None,
+) -> tuple[dict[str, Any], int]:
+    """Execute plan steps (sequential or parallel groups)."""
+    start = time.perf_counter()
+    steps_def = plan.get("steps") or []
+    if not steps_def:
+        return make_envelope(
+            ok=False,
+            cmd="plan@1",
+            surface=surface,
+            data={},
+            error={"kind": "invalid_plan", "message": "no steps", "retryable": False},
+        ), 1
+
+    invoke_fn = invoke_fn or (lambda **kw: invoke(registry, capability=capability, **kw))
+    ctx: dict[str, Any] = {"steps": {}}
+    step_results: list[dict[str, Any]] = []
+    last_env: dict[str, Any] | None = None
+    exit_code = 0
+
+    for block in steps_def:
+        if "parallel" in block:
+            branches = block["parallel"]
+            with ThreadPoolExecutor(max_workers=min(8, len(branches))) as pool:
+                futures = {
+                    pool.submit(_run_step, branch, ctx, surface, invoke_fn): branch
+                    for branch in branches
+                }
+                for fut in as_completed(futures):
+                    _sid, summary, code = fut.result()
+                    step_results.append(summary)
+                    if code != 0 or not summary.get("ok"):
+                        exit_code = code or 1
+            if exit_code:
+                break
+            continue
+
+        step_id, summary, code = _run_step(block, ctx, surface, invoke_fn)
+        step_results.append(summary)
+        last_env = ctx["steps"][step_id]
+        if code != 0 or not summary.get("ok"):
+            exit_code = code or 1
+            break
+
+    combined = make_envelope(
+        ok=exit_code == 0,
+        cmd=f"plan:{plan.get('name', 'unnamed')}@1",
+        surface=surface,
+        data={
+            "steps": ctx["steps"],
+            "summary": step_results,
+            "final": (
+                ctx["steps"][step_results[-1]["id"]].get("data", {})
+                if step_results and step_results[-1]["id"] in ctx["steps"]
+                else {}
+            ),
+        },
+        schema="https://schemas.gax.dev/plan/result/v1",
+        meta=timed_meta(start, step_count=len(step_results)),
+        error={"kind": "plan_failed", "message": "one or more steps failed", "retryable": True}
+        if exit_code
+        else None,
+    )
+    return combined, exit_code

gax/policy.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from typing import Any
+
+from gax.caps import cap_allows_command, cap_allows_scopes
+from gax.opa_policy import check_opa_or_yaml
+from gax.policy_bundle import PolicyDenied
+from gax.registry import CommandManifest
+from gax.side_effects import capability_ceiling, exceeds_ceiling, normalize
+
+__all__ = ["PolicyDenied", "check_invoke"]
+
+
+def check_invoke(
+    claims: dict[str, Any],
+    manifest: CommandManifest,
+    args: dict[str, Any] | None = None,
+) -> None:
+    if not cap_allows_command(claims, manifest.command):
+        raise PolicyDenied(f"capability does not allow command: {manifest.command}")
+    if not cap_allows_scopes(claims, manifest.required_scopes):
+        raise PolicyDenied(
+            f"missing scopes: {manifest.required_scopes}; held: {claims.get('scopes')}"
+        )
+    # Danger ceiling. Deliberately checked even when the command is on the
+    # capability's allowlist: an allowlist edit should not be able to silently
+    # promote a read-only token into one that can delete things.
+    if exceeds_ceiling(claims, manifest.side_effects):
+        raise PolicyDenied(
+            f"side_effects '{normalize(manifest.side_effects)}' exceeds capability "
+            f"ceiling '{capability_ceiling(claims)}': {manifest.command}"
+        )
+    check_opa_or_yaml(claims, manifest, args or {})

gax/policy_bundle.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from gax.paths import CONFIG_DIR
+from gax.registry import CommandManifest
+
+POLICY_PATH = CONFIG_DIR / "policy.yaml"
+
+
+class PolicyDenied(Exception):
+    def __init__(self, message: str) -> None:
+        super().__init__(message)
+        self.message = message
+
+
+def load_policy(path: Path | None = None) -> dict[str, Any]:
+    p = path or POLICY_PATH
+    if not p.exists():
+        return {}
+    return yaml.safe_load(p.read_text()) or {}
+
+
+def check_policy_bundle(
+    claims: dict[str, Any],
+    manifest: CommandManifest,
+    args: dict[str, Any],
+    *,
+    policy: dict[str, Any] | None = None,
+) -> None:
+    policy = policy or load_policy()
+    defaults = policy.get("defaults") or {}
+    tenant_id = str(claims.get("tenant_id", "default"))
+    tenant_rules = (policy.get("tenants") or {}).get(tenant_id) or (policy.get("tenants") or {}).get(
+        "default", {}
+    )
+
+    # Tenant-level kill switch for destructive commands. The per-capability ceiling
+    # (gax.side_effects) is the primary control; this is the blunt org-wide override
+    # for tenants that must never run destructive commands regardless of who asks.
+    # Tenant setting wins over the global default so a tenant can opt in explicitly.
+    deny_destructive = tenant_rules.get(
+        "deny_destructive", defaults.get("deny_destructive")
+    )
+    if deny_destructive and manifest.side_effects == "destructive":
+        raise PolicyDenied(
+            f"destructive commands disabled for tenant '{tenant_id}': {manifest.command}"
+        )
+
+    denied = set(tenant_rules.get("denied_commands") or [])
+    if manifest.command in denied:
+        raise PolicyDenied(f"command denied by policy: {manifest.command}")
+
+    allowed = tenant_rules.get("allowed_commands")
+    if allowed and manifest.command not in allowed and "*" not in allowed:
+        raise PolicyDenied(f"command not in tenant allowlist: {manifest.command}")
+
+    allowlist = tenant_rules.get("repo_allowlist") or []
+    repo = args.get("repo")
+    if allowlist and repo and repo not in allowlist:
+        raise PolicyDenied(f"repo not in allowlist: {repo}")

gax/profiles/github/gh.issue.list.yaml

@@ -0,0 +1,25 @@
+command: gh.issue.list
+version: "1.0.0"
+description: List issues in a repository
+category: github
+adapter: exec
+required_scopes:
+  - github:issues:read
+side_effects: read
+idempotent: true
+input_schema:
+  type: object
+  properties:
+    repo:
+      type: string
+      description: owner/name
+    limit:
+      type: integer
+      description: Max results (default 30)
+    state:
+      type: string
+      description: open | closed | all
+  required:
+    - repo
+output_schema:
+  type: object

gax/profiles/github/gh.issue.view.yaml

@@ -0,0 +1,23 @@
+command: gh.issue.view
+version: "1.0.0"
+description: View a single issue
+category: github
+adapter: exec
+required_scopes:
+  - github:issues:read
+side_effects: read
+idempotent: true
+input_schema:
+  type: object
+  properties:
+    repo:
+      type: string
+      description: owner/name
+    number:
+      type: integer
+      description: Issue number
+  required:
+    - repo
+    - number
+output_schema:
+  type: object

gax/profiles/github/gh.pr.comment.yaml

@@ -0,0 +1,30 @@
+command: gh.pr.comment
+version: "1.0.0"
+description: Post a comment on a pull request
+category: github
+adapter: exec
+required_scopes:
+  - github:pull_request:write
+side_effects: write
+idempotent: false
+input_schema:
+  type: object
+  properties:
+    repo:
+      type: string
+      description: owner/name
+    number:
+      type: integer
+      description: PR number
+    body:
+      type: string
+      description: Comment body
+    dry_run:
+      type: boolean
+      description: Validate without posting
+  required:
+    - repo
+    - number
+    - body
+output_schema:
+  type: object

gax/profiles/github/gh.pr.merge.yaml

@@ -0,0 +1,29 @@
+command: gh.pr.merge
+version: "1.0.0"
+description: Merge a pull request. Irreversible on a shared branch.
+category: github
+adapter: exec
+required_scopes:
+  - github:pull_request:write
+side_effects: destructive
+idempotent: false
+input_schema:
+  type: object
+  properties:
+    repo:
+      type: string
+      description: owner/name
+    number:
+      type: integer
+      description: PR number
+    method:
+      type: string
+      description: merge | squash | rebase (default squash)
+    dry_run:
+      type: boolean
+      description: Validate without merging
+  required:
+    - repo
+    - number
+output_schema:
+  type: object

gax/profiles/github/gh.run.list.yaml

@@ -0,0 +1,22 @@
+command: gh.run.list
+version: "1.0.0"
+description: List recent GitHub Actions runs
+category: github
+adapter: exec
+required_scopes:
+  - github:actions:read
+side_effects: read
+idempotent: true
+input_schema:
+  type: object
+  properties:
+    repo:
+      type: string
+      description: owner/name
+    limit:
+      type: integer
+      description: Max results (default 20)
+  required:
+    - repo
+output_schema:
+  type: object

gax/profiles/k8s/k8s.deployment.list.yaml

@@ -0,0 +1,17 @@
+command: k8s.deployment.list
+version: "1.0.0"
+description: List deployments in a namespace
+category: kubernetes
+adapter: k8s
+required_scopes:
+  - k8s:deployments:read
+side_effects: read
+idempotent: true
+input_schema:
+  type: object
+  properties:
+    namespace:
+      type: string
+      description: Kubernetes namespace
+output_schema:
+  type: object

gax/profiles/k8s/k8s.deployment.restart.yaml

@@ -0,0 +1,25 @@
+command: k8s.deployment.restart
+version: "1.0.0"
+description: Roll a deployment (restarts every pod)
+category: kubernetes
+adapter: k8s
+required_scopes:
+  - k8s:deployments:write
+side_effects: write
+idempotent: true
+input_schema:
+  type: object
+  properties:
+    namespace:
+      type: string
+      description: Kubernetes namespace
+    deployment:
+      type: string
+      description: Deployment name
+    dry_run:
+      type: boolean
+      description: Validate server-side without restarting
+  required:
+    - deployment
+output_schema:
+  type: object

gax/profiles/k8s/k8s.namespace.delete.yaml

@@ -0,0 +1,22 @@
+command: k8s.namespace.delete
+version: "1.0.0"
+description: Delete a namespace and everything in it. Irreversible.
+category: kubernetes
+adapter: k8s
+required_scopes:
+  - k8s:namespaces:write
+side_effects: destructive
+idempotent: false
+input_schema:
+  type: object
+  properties:
+    namespace:
+      type: string
+      description: Namespace to delete
+    dry_run:
+      type: boolean
+      description: Validate server-side without deleting
+  required:
+    - namespace
+output_schema:
+  type: object

gax/profiles/k8s/k8s.pod.describe.yaml

@@ -0,0 +1,22 @@
+command: k8s.pod.describe
+version: "1.0.0"
+description: Describe a pod (status, events, conditions)
+category: kubernetes
+adapter: k8s
+required_scopes:
+  - k8s:pods:read
+side_effects: read
+idempotent: true
+input_schema:
+  type: object
+  properties:
+    namespace:
+      type: string
+      description: Kubernetes namespace
+    pod:
+      type: string
+      description: Pod name
+  required:
+    - pod
+output_schema:
+  type: object

gax/profiles/k8s/k8s.pod.logs.yaml

@@ -0,0 +1,28 @@
+command: k8s.pod.logs
+version: "1.0.0"
+description: Fetch recent logs for a pod
+category: kubernetes
+adapter: k8s
+required_scopes:
+  - k8s:pods:read
+side_effects: read
+idempotent: true
+input_schema:
+  type: object
+  properties:
+    namespace:
+      type: string
+      description: Kubernetes namespace
+    pod:
+      type: string
+      description: Pod name
+    tail:
+      type: integer
+      description: Number of lines from the end (default 100)
+    container:
+      type: string
+      description: Container name when the pod has several
+  required:
+    - pod
+output_schema:
+  type: object

gax/profiles/k8s/k8s.service.list.yaml

@@ -0,0 +1,17 @@
+command: k8s.service.list
+version: "1.0.0"
+description: List services in a namespace
+category: kubernetes
+adapter: k8s
+required_scopes:
+  - k8s:services:read
+side_effects: read
+idempotent: true
+input_schema:
+  type: object
+  properties:
+    namespace:
+      type: string
+      description: Kubernetes namespace
+output_schema:
+  type: object

gax/profiles.py

@@ -0,0 +1,143 @@
+"""
+Profiles — bundled sets of ready-to-use commands.
+
+The adoption problem this solves: GAX shipped 11 commands, mostly mocks, so a new
+user's first task was authoring YAML for everything they actually cared about.
+A framework that ships empty doesn't get adopted.
+
+A profile is a directory of manifests under `gax/profiles/<name>/`. Installing one
+copies them into `~/.gax/manifests/`, which the registry loads *after* the packaged
+set — so profile commands survive package upgrades and can be edited in place.
+
+Profiles deliberately span the danger ladder (`read` → `write` → `destructive`).
+A profile of only read commands would make the side-effect ceiling untestable in
+practice, and the ceiling is the thing worth demonstrating.
+
+Installing a profile **grants nothing**. It registers commands; invoking them still
+requires a capability naming the command, holding the scope, and reaching the
+ceiling. `gax init --profile k8s` still hands out a read-only capability.
+"""
+
+from __future__ import annotations
+
+import shutil
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from gax.paths import PROFILES_DIR, USER_MANIFESTS_DIR
+
+
+@dataclass
+class ProfileCommand:
+    command: str
+    description: str
+    side_effects: str
+    required_scopes: list[str] = field(default_factory=list)
+
+
+@dataclass
+class Profile:
+    name: str
+    path: Path
+    commands: list[ProfileCommand]
+
+    @property
+    def scopes(self) -> list[str]:
+        seen: list[str] = []
+        for c in self.commands:
+            for s in c.required_scopes:
+                if s not in seen:
+                    seen.append(s)
+        return sorted(seen)
+
+    def by_level(self, level: str) -> list[ProfileCommand]:
+        return [c for c in self.commands if c.side_effects == level]
+
+    @property
+    def summary(self) -> str:
+        parts = [
+            f"{len(self.by_level(lvl))} {lvl}"
+            for lvl in ("read", "write", "destructive")
+            if self.by_level(lvl)
+        ]
+        return ", ".join(parts)
+
+
+def _read_profile(directory: Path) -> Profile:
+    commands: list[ProfileCommand] = []
+    for path in sorted(directory.glob("*.yaml")):
+        data = yaml.safe_load(path.read_text()) or {}
+        if not data.get("command"):
+            continue
+        commands.append(
+            ProfileCommand(
+                command=str(data["command"]),
+                description=str(data.get("description", "")),
+                side_effects=str(data.get("side_effects", "destructive")),
+                required_scopes=list(data.get("required_scopes") or []),
+            )
+        )
+    return Profile(name=directory.name, path=directory, commands=commands)
+
+
+def available_profiles() -> dict[str, Profile]:
+    if not PROFILES_DIR.exists():
+        return {}
+    return {
+        d.name: _read_profile(d)
+        for d in sorted(PROFILES_DIR.iterdir())
+        if d.is_dir() and not d.name.startswith(("_", "."))
+    }
+
+
+def get_profile(name: str) -> Profile | None:
+    return available_profiles().get(name)
+
+
+def installed_commands() -> set[str]:
+    """Commands currently present in the user manifests directory."""
+    out: set[str] = set()
+    if not USER_MANIFESTS_DIR.exists():
+        return out
+    for path in USER_MANIFESTS_DIR.glob("*.yaml"):
+        data = yaml.safe_load(path.read_text()) or {}
+        if data.get("command"):
+            out.add(str(data["command"]))
+    return out
+
+
+def install_profile(name: str, *, force: bool = False) -> dict[str, Any]:
+    """
+    Copy a profile's manifests into `~/.gax/manifests/`.
+
+    Existing files are skipped unless `force`, so a locally edited command is never
+    silently overwritten by a reinstall.
+    """
+    profile = get_profile(name)
+    if profile is None:
+        raise KeyError(name)
+
+    USER_MANIFESTS_DIR.mkdir(parents=True, exist_ok=True)
+    installed: list[str] = []
+    skipped: list[str] = []
+
+    for src in sorted(profile.path.glob("*.yaml")):
+        dst = USER_MANIFESTS_DIR / src.name
+        if dst.exists() and not force:
+            skipped.append(src.stem)
+            continue
+        shutil.copy2(src, dst)
+        installed.append(src.stem)
+
+    return {
+        "profile": name,
+        "installed": installed,
+        "skipped": skipped,
+        "target": str(USER_MANIFESTS_DIR),
+        "scopes": profile.scopes,
+        "commands": [c.command for c in profile.commands],
+        "summary": profile.summary,
+    }