gax-cli 0.4.0__py3-none-any.whl

gax/client.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+import json
+import os
+from typing import Any
+
+import httpx
+
+from gax.paths import DEFAULT_HOST, DEFAULT_PORT
+
+
+def base_url(host: str | None = None, port: int | None = None) -> str:
+    h = host or os.environ.get("GAX_HOST", DEFAULT_HOST)
+    p = port or int(os.environ.get("GAX_PORT", DEFAULT_PORT))
+    return f"http://{h}:{p}"
+
+
+def capability_header(capability: str | None = None) -> dict[str, str]:
+    cap = (capability or os.environ.get("GAX_CAP", "")).strip()
+    if not cap:
+        return {}
+    return {"GAX-Capability": cap}
+
+
+def remote_invoke(
+    command: str,
+    args: dict[str, Any],
+    *,
+    surface: str = "model",
+    host: str | None = None,
+    port: int | None = None,
+    capability: str | None = None,
+) -> tuple[dict[str, Any], int]:
+    url = base_url(host, port) + "/invoke"
+    body = {"command": command, "args": args, "surface": surface}
+    r = httpx.post(url, json=body, headers=capability_header(capability), timeout=120.0)
+    data = r.json()
+    env = data.get("envelope", data)
+    exit_code = int(data.get("exit_code", 1 if not env.get("ok") else 0))
+    return env, exit_code
+
+
+def remote_doc(command: str, host: str | None = None, port: int | None = None) -> dict[str, Any]:
+    r = httpx.get(f"{base_url(host, port)}/commands/{command}/doc", timeout=10.0)
+    r.raise_for_status()
+    return r.json()
+
+
+def remote_search(query: str, host: str | None = None, port: int | None = None) -> dict[str, Any]:
+    r = httpx.get(f"{base_url(host, port)}/search", params={"q": query}, timeout=10.0)
+    r.raise_for_status()
+    return r.json()
+
+
+def remote_schema(command: str, host: str | None = None, port: int | None = None) -> dict[str, Any]:
+    r = httpx.get(f"{base_url(host, port)}/schema/{command}", timeout=10.0)
+    r.raise_for_status()
+    return r.json()

gax/compliance.py

@@ -0,0 +1,71 @@
+"""SOC2-friendly audit exports from ~/.gax/audit.jsonl."""
+
+from __future__ import annotations
+
+import csv
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from gax.paths import AUDIT_PATH, GAX_HOME, ensure_gax_home
+
+SOC2_FIELDS = [
+    "timestamp",
+    "audit_id",
+    "tenant_id",
+    "subject",
+    "command",
+    "ok",
+    "error_kind",
+    "duration_ms",
+    "args_json",
+]
+
+
+def load_audit_lines(path: Path | None = None) -> list[dict[str, Any]]:
+    p = path or AUDIT_PATH
+    if not p.exists():
+        return []
+    rows = []
+    for line in p.read_text().splitlines():
+        if line.strip():
+            rows.append(json.loads(line))
+    return rows
+
+
+def export_soc2_csv(out_path: Path, *, since: str | None = None) -> int:
+    rows = load_audit_lines()
+    if since:
+        rows = [r for r in rows if r.get("ts", "") >= since]
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    with out_path.open("w", newline="") as f:
+        w = csv.DictWriter(f, fieldnames=SOC2_FIELDS)
+        w.writeheader()
+        for r in rows:
+            w.writerow(
+                {
+                    "timestamp": r.get("ts"),
+                    "audit_id": r.get("audit_id"),
+                    "tenant_id": r.get("tenant_id"),
+                    "subject": r.get("subject"),
+                    "command": r.get("command"),
+                    "ok": r.get("ok"),
+                    "error_kind": r.get("error_kind") or "",
+                    "duration_ms": r.get("duration_ms") or "",
+                    "args_json": json.dumps(r.get("args") or {}),
+                }
+            )
+    return len(rows)
+
+
+def export_soc2_json(out_path: Path) -> dict[str, Any]:
+    rows = load_audit_lines()
+    bundle = {
+        "exported_at": datetime.now(timezone.utc).isoformat(),
+        "standard": "SOC2-aligned access log (MVP)",
+        "record_count": len(rows),
+        "records": rows,
+    }
+    out_path.write_text(json.dumps(bundle, indent=2))
+    return bundle

gax/config/oauth_providers.yaml

@@ -0,0 +1,21 @@
+# OAuth 2.0 device authorization (RFC 8628) providers for `gax auth login`
+#
+# GitHub: create an OAuth App at https://github.com/settings/developers
+#   - Enable Device Flow
+#   - Set GAX_GITHUB_CLIENT_ID to the Client ID
+
+providers:
+  github:
+    device_authorization_url: https://github.com/login/device/code
+    token_url: https://github.com/login/oauth/access_token
+    client_id_env: GAX_GITHUB_CLIENT_ID
+    scopes:
+      - repo
+      - read:org
+
+  # Generic template (OIDC/OAuth provider with RFC 8628 endpoints)
+  # custom:
+  #   device_authorization_url: https://auth.example.com/oauth/device
+  #   token_url: https://auth.example.com/oauth/token
+  #   client_id_env: GAX_CUSTOM_CLIENT_ID
+  #   scopes: [openid, profile]

gax/config/policy.rego

@@ -0,0 +1,20 @@
+package gax
+
+default allow = false
+
+allow {
+  input.side_effects == "read"
+  not denied_command
+  not denied_repo
+}
+
+denied_command {
+  input.command == "destructive.example"
+}
+
+denied_repo {
+  some repo
+  repo := input.args.repo
+  input.claims.tenant_id == "restricted"
+  repo != "allowed/repo"
+}

gax/config/policy.yaml

@@ -0,0 +1,59 @@
+# GAX policy bundle (MVP — YAML rules; OPA/Rego compatible path later)
+version: 1
+
+defaults:
+  # Org-wide kill switch for destructive commands. A tenant may override it.
+  # This is the blunt control; the per-capability `max_side_effect` ceiling
+  # (gax/side_effects.py) is the primary, fine-grained one.
+  deny_destructive: true
+  max_rows_per_invoke: 500
+
+tenants:
+  default:
+    # Local/dev tenant. Opt in to destructive commands here; each invoke still
+    # needs a capability minted with `--max-side-effect destructive`.
+    deny_destructive: false
+    # "*" means "any registered command", NOT "any action" — the registry is
+    # still a closed set, and the per-capability allowlist + scopes + ceiling are
+    # the real controls. A wildcard here keeps installed profiles usable without
+    # editing policy; production tenants should enumerate instead (see below).
+    allowed_commands:
+      - "*"
+    denied_commands: []
+    repo_allowlist: []  # empty = allow all repos
+
+  # Template for a production tenant: enumerate exactly what may run, and keep
+  # the destructive kill switch on unless a specific need is documented.
+  production:
+    deny_destructive: true
+    allowed_commands:
+      - gh.pr.list
+      - gh.pr.view
+      - k8s.pod.list
+      - k8s.pod.logs
+    denied_commands: []
+    repo_allowlist: []
+
+  # Example: a tenant that must never run destructive commands, regardless of
+  # what capability a caller presents.
+  readonly-tenant:
+    deny_destructive: true
+    allowed_commands:
+      - "*"
+    denied_commands: []
+    repo_allowlist: []
+  capguard:
+    allowed_commands:
+      - demo.echo
+      - gitlab.mr.search
+      - gitlab.mr.get
+      - gitlab.mr.diffs
+      - gitlab.mr.pipelines
+      - gitlab.note.draft
+    denied_commands: []
+    repo_allowlist: []  # empty = allow all repos
+
+rules:
+  - id: block_private_repos
+    description: Deny gh commands on repos marked private (future)
+    enabled: false

gax/daemon.py

@@ -0,0 +1,187 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import signal
+import sys
+import time
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from typing import Any
+from urllib.parse import parse_qs, urlparse
+
+import click
+
+from gax.executor import invoke
+from gax.paths import DEFAULT_HOST, DEFAULT_PORT, PID_PATH, ensure_gax_home
+from gax.registry import Registry
+
+_REGISTRY = Registry()
+
+
+class GaxdHandler(BaseHTTPRequestHandler):
+    def log_message(self, format: str, *args: Any) -> None:
+        return  # quiet by default
+
+    def _json_response(self, code: int, body: dict[str, Any]) -> None:
+        payload = json.dumps(body, indent=2).encode()
+        self.send_response(code)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(payload)))
+        self.end_headers()
+        self.wfile.write(payload)
+
+    def _read_json(self) -> dict[str, Any]:
+        length = int(self.headers.get("Content-Length", 0))
+        raw = self.rfile.read(length) if length else b"{}"
+        return json.loads(raw.decode() or "{}")
+
+    def do_GET(self) -> None:
+        parsed = urlparse(self.path)
+        path = parsed.path
+        qs = parse_qs(parsed.query)
+
+        if path == "/health":
+            # Expose a fingerprint of the signing secret (never the secret) so a
+            # client can tell it is talking to a daemon that shares its config.
+            # A daemon started against a different ~/.gax will reject every
+            # capability with "Signature verification failed", which is otherwise
+            # very hard to diagnose.
+            from gax.caps import jwt_secret
+
+            fp = hashlib.sha256(jwt_secret().encode()).hexdigest()[:12]
+            self._json_response(
+                200,
+                {
+                    "ok": True,
+                    "service": "gaxd",
+                    "commands": len(_REGISTRY.list_commands()),
+                    "config_fingerprint": fp,
+                },
+            )
+            return
+
+        if path == "/commands":
+            items = [
+                {"command": m.command, "version": m.version, "description": m.description}
+                for m in _REGISTRY.list_commands()
+            ]
+            self._json_response(200, {"commands": items})
+            return
+
+        if path.startswith("/commands/") and path.endswith("/doc"):
+            cmd = path.split("/")[2]
+            doc = _REGISTRY.doc_stub(cmd)
+            if not doc:
+                self._json_response(404, {"error": "not_found"})
+                return
+            self._json_response(200, doc)
+            return
+
+        if path == "/search":
+            q = (qs.get("q") or [""])[0]
+            hits = _REGISTRY.search(q)
+            self._json_response(
+                200,
+                {
+                    "query": q,
+                    "results": [
+                        {"command": m.command, "description": m.description, "category": m.category}
+                        for m in hits
+                    ],
+                },
+            )
+            return
+
+        if path.startswith("/schema/"):
+            cmd = path.split("/schema/", 1)[1]
+            m = _REGISTRY.get(cmd)
+            if not m:
+                self._json_response(404, {"error": "not_found"})
+                return
+            self._json_response(
+                200,
+                {"command": cmd, "input_schema": m.input_schema, "output_schema": m.output_schema},
+            )
+            return
+
+        self._json_response(404, {"error": "not_found"})
+
+    def do_POST(self) -> None:
+        if self.path != "/invoke":
+            self._json_response(404, {"error": "not_found"})
+            return
+        body = self._read_json()
+        cap = self.headers.get("GAX-Capability") or body.get("capability")
+        env, exit_code = invoke(
+            _REGISTRY,
+            command=str(body.get("command", "")),
+            args=dict(body.get("args") or {}),
+            surface=str(body.get("surface") or "model"),
+            capability=cap,
+        )
+        http_code = 200 if env.get("ok") else 400
+        self._json_response(http_code, {"envelope": env, "exit_code": exit_code})
+
+
+def run_server(host: str, port: int) -> None:
+    server = HTTPServer((host, port), GaxdHandler)
+    click.echo(f"gaxd listening on http://{host}:{port}")
+    server.serve_forever()
+
+
+@click.group()
+def main() -> None:
+    """GAX daemon (gaxd)."""
+
+
+@main.command("start")
+@click.option("--host", default=DEFAULT_HOST)
+@click.option("--port", default=DEFAULT_PORT, type=int)
+@click.option("--background", is_flag=True, help="Daemonize (write pid file)")
+def start(host: str, port: int, background: bool) -> None:
+    ensure_gax_home()
+    if background:
+        pid = os.fork()
+        if pid > 0:
+            PID_PATH.write_text(str(pid))
+            click.echo(f"gaxd started pid={pid} http://{host}:{port}")
+            return
+        os.setsid()
+        sys.stdout = open(os.devnull, "w")
+        sys.stderr = open(os.devnull, "w")
+    else:
+        PID_PATH.write_text(str(os.getpid()))
+    run_server(host, port)
+
+
+@main.command("stop")
+def stop() -> None:
+    if not PID_PATH.exists():
+        click.echo("gaxd not running (no pid file)")
+        return
+    pid = int(PID_PATH.read_text().strip())
+    try:
+        os.kill(pid, signal.SIGTERM)
+        PID_PATH.unlink(missing_ok=True)
+        click.echo(f"stopped gaxd pid={pid}")
+    except ProcessLookupError:
+        PID_PATH.unlink(missing_ok=True)
+        click.echo("stale pid file removed")
+
+
+@main.command("status")
+@click.option("--host", default=DEFAULT_HOST)
+@click.option("--port", default=DEFAULT_PORT, type=int)
+def status(host: str, port: int) -> None:
+    import httpx
+
+    try:
+        r = httpx.get(f"http://{host}:{port}/health", timeout=2.0)
+        click.echo(r.text)
+    except Exception as e:
+        click.echo(f"gaxd unreachable: {e}")
+
+
+if __name__ == "__main__":
+    main()

gax/envelope.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+import time
+import uuid
+from typing import Any
+
+
+def new_audit_id() -> str:
+    return f"aud_{uuid.uuid4().hex[:16]}"
+
+
+def make_envelope(
+    *,
+    ok: bool,
+    cmd: str,
+    surface: str,
+    data: Any,
+    audit_id: str | None = None,
+    schema: str | None = None,
+    meta: dict[str, Any] | None = None,
+    error: dict[str, Any] | None = None,
+    next_actions: list[dict[str, Any]] | None = None,
+) -> dict[str, Any]:
+    env: dict[str, Any] = {
+        "v": 1,
+        "ok": ok,
+        "cmd": cmd,
+        "audit_id": audit_id or new_audit_id(),
+        "surface": surface,
+        "data": data if data is not None else {},
+        "meta": meta or {},
+        "error": error,
+    }
+    if schema:
+        env["schema"] = schema
+    if next_actions:
+        env["next"] = next_actions
+    return env
+
+
+def fail_envelope(
+    *,
+    cmd: str,
+    surface: str,
+    kind: str,
+    message: str,
+    retryable: bool = False,
+    audit_id: str | None = None,
+) -> dict[str, Any]:
+    return make_envelope(
+        ok=False,
+        cmd=cmd,
+        surface=surface,
+        data={},
+        audit_id=audit_id,
+        error={"kind": kind, "message": message, "retryable": retryable},
+        meta={"duration_ms": 0},
+    )
+
+
+def timed_meta(start: float, **extra: Any) -> dict[str, Any]:
+    meta = {"duration_ms": round((time.perf_counter() - start) * 1000, 2)}
+    meta.update(extra)
+    return meta

gax/executor.py

@@ -0,0 +1,151 @@
+from __future__ import annotations
+
+import time
+from typing import Any
+
+from gax.adapters.base import run_adapter
+from gax.audit import log_event
+from gax.caps import decode_capability
+from gax.envelope import fail_envelope, make_envelope, timed_meta
+from gax.policy import PolicyDenied, check_invoke
+from gax.projection import project_data
+from gax.registry import Registry
+
+
+def invoke(
+    registry: Registry,
+    *,
+    command: str,
+    args: dict[str, Any],
+    surface: str = "model",
+    capability: str | None = None,
+) -> tuple[dict[str, Any], int]:
+    start = time.perf_counter()
+    manifest = registry.get(command)
+    cmd_label = f"{command}@?" if not manifest else manifest.cmd_id
+
+    try:
+        claims = decode_capability(capability)
+    except Exception as e:
+        env = fail_envelope(
+            cmd=cmd_label,
+            surface=surface,
+            kind="capability_invalid",
+            message=str(e),
+        )
+        log_event(
+            audit_id=env["audit_id"],
+            tenant_id="unknown",
+            subject="unknown",
+            command=command,
+            args=args,
+            ok=False,
+            error_kind="capability_invalid",
+        )
+        return env, 3
+
+    tenant_id = str(claims.get("tenant_id", "unknown"))
+    subject = str(claims.get("sub", "unknown"))
+
+    if not manifest:
+        env = fail_envelope(
+            cmd=cmd_label,
+            surface=surface,
+            kind="not_found",
+            message=f"unknown command: {command}",
+        )
+        log_event(
+            audit_id=env["audit_id"],
+            tenant_id=tenant_id,
+            subject=subject,
+            command=command,
+            args=args,
+            ok=False,
+            error_kind="not_found",
+        )
+        return env, 4
+
+    cmd_label = manifest.cmd_id
+    try:
+        check_invoke(claims, manifest, args)
+    except PolicyDenied as e:
+        env = fail_envelope(
+            cmd=cmd_label,
+            surface=surface,
+            kind="policy_denied",
+            message=e.message,
+            retryable=False,
+        )
+        log_event(
+            audit_id=env["audit_id"],
+            tenant_id=tenant_id,
+            subject=subject,
+            command=command,
+            args=args,
+            ok=False,
+            error_kind="policy_denied",
+        )
+        return env, 2
+
+    audit_id = make_envelope(ok=True, cmd=cmd_label, surface=surface, data={})["audit_id"]
+
+    try:
+        raw = run_adapter(manifest, args, tenant_id=tenant_id)
+    except Exception as e:
+        env = fail_envelope(
+            cmd=cmd_label,
+            surface=surface,
+            kind="adapter_error",
+            message=str(e),
+            retryable=True,
+            audit_id=audit_id,
+        )
+        log_event(
+            audit_id=audit_id,
+            tenant_id=tenant_id,
+            subject=subject,
+            command=command,
+            args=args,
+            ok=False,
+            error_kind="adapter_error",
+            duration_ms=timed_meta(start)["duration_ms"],
+        )
+        return env, 5
+
+    projected, proj_meta = project_data(raw, surface)
+    meta = timed_meta(start, **proj_meta)
+
+    next_actions = None
+    if manifest.command == "gh.pr.list" and isinstance(projected, dict):
+        items = projected.get("items") or []
+        if items:
+            first = items[0]
+            next_actions = [
+                {
+                    "cmd": "gh.pr.view",
+                    "args": {"repo": args.get("repo"), "number": first.get("number")},
+                    "reason": "inspect first PR in list",
+                }
+            ]
+
+    env = make_envelope(
+        ok=True,
+        cmd=cmd_label,
+        surface=surface,
+        data=projected,
+        audit_id=audit_id,
+        schema=manifest.schema_uri,
+        meta=meta,
+        next_actions=next_actions,
+    )
+
+    log_event(
+        audit_id=audit_id,
+        tenant_id=tenant_id,
+        subject=subject,
+        command=command,
+        args=args,
+        ok=True,
+        duration_ms=meta.get("duration_ms"),
+    )
+    return env, 0