graph-agents-cli 0.3.1__py3-none-any.whl

graph_agents_cli/deploy/local_load.py

@@ -0,0 +1,273 @@
+# Copyright 2026 graph-agents-cli contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Load a locally built image into a single-node dev cluster (kind, k3d, k3s, minikube, ...).
+
+A context name is only a label: a renamed kind context would otherwise make
+``deploy`` push a dev build to the real registry, and a production context that
+happens to be called ``kind-...`` would be treated as a laptop cluster. So the
+cluster is identified from the cluster itself: its nodes' ``providerID``, name
+and labels (kind ``kind://<provider>/<cluster>/<node>``, k3d ``k3d-<cluster>-server-N``,
+k3s ``k3s://``, minikube's ``minikube.k8s.io/name`` label, Docker Desktop and
+OrbStack node names). A kind cluster is also confirmed with ``kind get
+clusters``, since ``kind load`` only reaches clusters on this machine. Only
+when the nodes cannot be read (no permission to list nodes, cluster down)
+does the context name decide, and a ``kind-*`` name is still confirmed with
+the kind CLI.
+
+Only the ``docker`` CLI is supported for builds; Docker Desktop, Rancher
+Desktop and OrbStack share the daemon with the cluster, so nothing needs
+loading there.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from graph_agents_cli.deploy import _kube
+
+KIND = "kind"
+K3D = "k3d"
+K3S = "k3s"
+MINIKUBE = "minikube"
+SHARED_DAEMON = "shared-daemon"
+
+_K3D_NODE = re.compile(r"^k3d-(?P<cluster>.+)-(?:server|agent)-\d+$")
+_SHARED_DAEMON_NODES = ("docker-desktop", "orbstack")
+NODE_READ_TIMEOUT = "10s"
+
+
+@dataclass(frozen=True)
+class LocalCluster:
+    """A single-node dev cluster the image can be loaded into."""
+
+    kind: str
+    name: str = ""
+    evidence: str = ""
+
+    def describe(self) -> str:
+        label = {
+            KIND: f"kind cluster {self.name!r}",
+            K3D: f"k3d cluster {self.name!r}",
+            K3S: "k3s",
+            MINIKUBE: f"minikube profile {self.name!r}",
+            SHARED_DAEMON: f"{self.name or 'local cluster'} (shares the docker daemon)",
+        }.get(self.kind, self.kind)
+        return f"{label}{f', {self.evidence}' if self.evidence else ''}"
+
+
+def from_context_name(context: str | None) -> LocalCluster | None:
+    """The dev cluster a context name suggests (unverified), or ``None``."""
+    name = (context or "").strip()
+    if name.startswith("kind-"):
+        return LocalCluster(KIND, name[len("kind-") :], "from the context name")
+    if name.startswith("k3d-"):
+        return LocalCluster(K3D, name[len("k3d-") :], "from the context name")
+    if name.startswith("minikube"):
+        return LocalCluster(MINIKUBE, name, "from the context name")
+    if name.startswith("k3s"):
+        return LocalCluster(K3S, "", "from the context name")
+    if name in ("docker-desktop", "rancher-desktop", "orbstack"):
+        return LocalCluster(SHARED_DAEMON, name, "from the context name")
+    return None
+
+
+def from_nodes(nodes: list[dict[str, Any]]) -> LocalCluster | None:
+    """The dev cluster the node objects identify, or ``None`` for any other cluster."""
+    for node in nodes:
+        meta = node.get("metadata") if isinstance(node.get("metadata"), dict) else {}
+        spec = node.get("spec") if isinstance(node.get("spec"), dict) else {}
+        labels = meta.get("labels") if isinstance(meta.get("labels"), dict) else {}
+        node_name = str(meta.get("name") or "")
+        provider_id = str(spec.get("providerID") or "")
+        if provider_id.startswith("kind://"):
+            # kind://<provider>/<cluster>/<node>
+            parts = provider_id[len("kind://") :].split("/")
+            if len(parts) >= 3 and parts[1]:
+                return LocalCluster(KIND, parts[1], f"node providerID {provider_id}")
+        if labels.get("minikube.k8s.io/name"):
+            profile = str(labels["minikube.k8s.io/name"])
+            return LocalCluster(MINIKUBE, profile, f"node label minikube.k8s.io/name={profile}")
+        if node_name in _SHARED_DAEMON_NODES or "rancher-desktop" in node_name:
+            return LocalCluster(SHARED_DAEMON, node_name, f"node {node_name}")
+        if provider_id.startswith("k3s://"):
+            match = _K3D_NODE.match(node_name)
+            if match:
+                return LocalCluster(K3D, match.group("cluster"), f"node {node_name}")
+            return LocalCluster(K3S, "", f"node providerID {provider_id}")
+    return None
+
+
+def read_nodes(context: str | None) -> list[dict[str, Any]] | None:
+    """The cluster's Node objects, ``None`` when they cannot be read (never raises)."""
+    target = _kube.Target(context=context, namespace="")
+    try:
+        result = _kube.kubectl(
+            ["get", "nodes", "-o", "json", f"--request-timeout={NODE_READ_TIMEOUT}"],
+            target,
+            namespaced=False,
+            check=False,
+            quiet=True,
+        )
+    except _kube.ToolFailed:
+        return None
+    if result.returncode != 0 or not (result.stdout or "").strip():
+        return None
+    try:
+        data = json.loads(result.stdout)
+    except json.JSONDecodeError:
+        return None
+    items = data.get("items") if isinstance(data, dict) else None
+    if not isinstance(items, list) or not items:
+        return None
+    return [item for item in items if isinstance(item, dict)]
+
+
+def _tool_output(cmd: list[str]) -> str | None:
+    """stdout of a local CLI, ``None`` when it is missing or fails (never raises)."""
+    try:
+        result = _kube.run_cmd(cmd, check=False, quiet=True)
+    except _kube.ToolFailed:
+        return None
+    if result.returncode != 0:
+        return None
+    return result.stdout or ""
+
+
+def kind_clusters() -> set[str] | None:
+    """Names ``kind get clusters`` reports on this machine, ``None`` when kind is unavailable."""
+    out = _tool_output(["kind", "get", "clusters"])
+    if out is None:
+        return None
+    return {line.strip() for line in out.splitlines() if line.strip()}
+
+
+def _json_or_none(text: str | None) -> Any:
+    if text is None:
+        return None
+    try:
+        return json.loads(text or "null")
+    except json.JSONDecodeError:
+        return None
+
+
+def k3d_clusters() -> set[str] | None:
+    """Names ``k3d cluster list`` reports on this machine, ``None`` when k3d is unavailable."""
+    data = _json_or_none(_tool_output(["k3d", "cluster", "list", "-o", "json"]))
+    if not isinstance(data, list):
+        return None
+    return {str(c.get("name")) for c in data if isinstance(c, dict) and c.get("name")}
+
+
+def minikube_profiles() -> set[str] | None:
+    """Valid profiles ``minikube profile list`` reports, ``None`` when minikube is unavailable."""
+    data = _json_or_none(_tool_output(["minikube", "profile", "list", "-o", "json"]))
+    valid = data.get("valid") if isinstance(data, dict) else None
+    if not isinstance(valid, list):
+        return None
+    return {str(p.get("Name")) for p in valid if isinstance(p, dict) and p.get("Name")}
+
+
+def _local_hostnames() -> set[str]:
+    import socket
+
+    name = socket.gethostname().lower()
+    return {name, name.split(".")[0]}
+
+
+_LISTINGS = {
+    KIND: ("kind get clusters", kind_clusters),
+    K3D: ("k3d cluster list", k3d_clusters),
+    MINIKUBE: ("minikube profile list", minikube_profiles),
+}
+
+
+def _verify(
+    cluster: LocalCluster, nodes: list[dict[str, Any]] | None
+) -> tuple[LocalCluster | None, str]:
+    """Confirm that ``cluster`` runs on this machine, where its load command can reach it."""
+    if cluster.kind in _LISTINGS:
+        command, listing = _LISTINGS[cluster.kind]
+        names = listing()
+        if names is None:
+            return None, (
+                f"{cluster.describe()}, but `{command}` is not available on this machine to "
+                "load images into it"
+            )
+        if cluster.name not in names:
+            return None, (
+                f"{cluster.describe()}, but `{command}` on this machine does not list "
+                f"{cluster.name!r}"
+            )
+        evidence = f"{cluster.evidence}; `{command}` lists it"
+        return LocalCluster(cluster.kind, cluster.name, evidence), ""
+    if cluster.kind == K3S and nodes is not None:
+        # k3s also runs production clusters: only this machine's own node can import images.
+        node_names = {
+            str(n["metadata"].get("name") or "").lower()
+            for n in nodes
+            if isinstance(n.get("metadata"), dict)
+        }
+        if not node_names & _local_hostnames():
+            return None, f"{cluster.describe()}, but none of its nodes is this machine"
+    return cluster, ""
+
+
+def detect(context: str | None) -> tuple[LocalCluster | None, str]:
+    """Identify a local dev cluster behind ``context``: ``(cluster or None, reason)``.
+
+    ``reason`` explains, in one line, why the cluster is not treated as local.
+    """
+    nodes = read_nodes(context)
+    if nodes is not None:
+        cluster = from_nodes(nodes)
+        if cluster is None:
+            return None, "its nodes are not a local dev cluster"
+    else:
+        cluster = from_context_name(context)
+        if cluster is None:
+            return None, "its nodes cannot be read and the context name is not a dev cluster"
+    verified, why = _verify(cluster, nodes)
+    if verified is None:
+        # Docker Desktop can run its Kubernetes on kind nodes that the kind CLI does
+        # not list; the desktop apps share the docker daemon with the cluster, so
+        # their own context names still mean "no load needed" (never a push).
+        named = from_context_name(context)
+        if named is not None and named.kind == SHARED_DAEMON:
+            return named, ""
+    return verified, why
+
+
+def local_load_commands(
+    cluster: LocalCluster, image: str, *, tar_path: Path | None = None
+) -> list[list[str]]:
+    """The commands that make ``image`` visible to ``cluster``.
+
+    An empty list means the cluster already sees the docker daemon's images.
+    """
+    if cluster.kind == KIND:
+        return [["kind", "load", "docker-image", image, "--name", cluster.name]]
+    if cluster.kind == K3D:
+        return [["k3d", "image", "import", image, "-c", cluster.name]]
+    if cluster.kind == MINIKUBE:
+        if cluster.name and cluster.name != "minikube":
+            return [["minikube", "image", "load", image, "-p", cluster.name]]
+        return [["minikube", "image", "load", image]]
+    if cluster.kind == K3S:
+        tar = str(tar_path or Path(".graph-agents-cli") / "image.tar")
+        return [["docker", "save", "-o", tar, image], ["k3s", "ctr", "images", "import", tar]]
+    return []

graph_agents_cli/dev/__init__.py

@@ -0,0 +1,13 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.

graph_agents_cli/dev/cmd_build.py

@@ -0,0 +1,131 @@
+# Copyright 2026 Google LLC
+# Modifications Copyright 2026 graph-agents-cli contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""graph-agents-cli build command: ``docker build`` on the project's Dockerfile.
+
+One runtime-specific Dockerfile per project, selected at scaffold time;
+``build``, CI, and local-load all run ``docker build``. There is no experiment
+gate. Exit codes: 0 ok, 2 when docker fails, 3 for a configuration error.
+"""
+
+from __future__ import annotations
+
+import shlex
+from pathlib import Path
+
+import click
+
+from graph_agents_cli import _tools
+from graph_agents_cli._project import chdir_project_root, read_project_config
+from graph_agents_cli._runner import run
+from graph_agents_cli.deploy._image import reference_problem as image_reference_problem
+
+DEFAULT_TAG = "latest"
+DOCKERFILE = "Dockerfile"
+EXIT_TOOL_FAILURE = 2
+EXIT_CONFIG_ERROR = 3
+
+
+def image_name(*, project_name: str, registry: str | None) -> str:
+    """``<registry>/<project>`` when a registry is set, else ``<project>``."""
+    name = (project_name or "").strip()
+    if not name:
+        raise click.ClickException(
+            "The manifest has no project name; cannot derive an image name.\n"
+            "  Set 'name' in graph-agents-cli-manifest.yaml."
+        )
+    reg = (registry or "").strip().rstrip("/")
+    return f"{reg}/{name}" if reg else name
+
+
+def build_commands(
+    *, image: str, tag: str, push: bool, dockerfile: str = DOCKERFILE
+) -> list[list[str]]:
+    ref = f"{image}:{tag}"
+    commands = [["docker", "build", "-t", ref, "-f", dockerfile, "."]]
+    if push:
+        commands.append(["docker", "push", ref])
+    return commands
+
+
+@click.command("build")
+@click.option("--tag", default=DEFAULT_TAG, show_default=True, help="Image tag.")
+@click.option("--registry", default=None, help="Override the manifest registry (e.g. ghcr.io/org).")
+@click.option("--push", is_flag=True, default=False, help="Push the image after building.")
+@click.option(
+    "--dry-run",
+    "dry_run",
+    is_flag=True,
+    default=False,
+    help="Print the docker commands without running them.",
+)
+@click.pass_context
+def cmd_build(
+    ctx: click.Context, tag: str, registry: str | None, push: bool, dry_run: bool
+) -> None:
+    """Build the agent container image.
+
+    Runs `docker build -t <registry>/<name>:<tag> .` with the project's
+    runtime-specific Dockerfile. The registry defaults to the manifest's
+    `create_params.registry`; without one the image is named after the project.
+    """
+    chdir_project_root()
+    cfg = read_project_config()
+    project_root = Path.cwd()
+
+    if not (project_root / DOCKERFILE).is_file():
+        click.secho(
+            f"Error: No {DOCKERFILE} at the project root ({project_root}).\n"
+            "  Add deployment support with: graph-agents-cli scaffold enhance",
+            fg="red",
+            err=True,
+        )
+        ctx.exit(EXIT_CONFIG_ERROR)
+
+    project_name = getattr(cfg, "project_name", "") or getattr(cfg, "name", "")
+    effective_registry = registry if registry is not None else getattr(cfg, "registry", "")
+    image = image_name(project_name=project_name, registry=effective_registry)
+    # Checked before docker runs (and under --dry-run): the scaffold's placeholder
+    # registry, or any malformed reference, would otherwise surface as a docker
+    # parser error that does not name the setting to change.
+    problem = image_reference_problem(image, tag, registry=effective_registry)
+    if problem:
+        # "Error:" like every other command's configuration error.
+        click.secho(f"Error: {problem}", fg="red", err=True)
+        ctx.exit(EXIT_CONFIG_ERROR)
+    commands = build_commands(image=image, tag=tag, push=push)
+
+    if dry_run:
+        click.echo("Dry run; would execute:")
+        for cmd in commands:
+            click.echo(f"  {shlex.join(cmd)}")
+        return
+
+    _tools.require_tool(
+        "docker",
+        "Install Docker (https://docs.docker.com/get-docker/) and ensure it is in your PATH.",
+    )
+    for cmd in commands:
+        result = run(cmd, check=False)
+        if result.returncode != 0:
+            click.secho(
+                f"Error: {shlex.join(cmd[:2])} failed (exit code {result.returncode}).",
+                fg="red",
+                err=True,
+            )
+            ctx.exit(EXIT_TOOL_FAILURE)
+    click.echo(f"Built image: {image}:{tag}")
+    if push:
+        click.echo(f"Pushed image: {image}:{tag}")

graph_agents_cli/dev/cmd_install.py

@@ -0,0 +1,78 @@
+# Copyright 2026 Google LLC
+# Modifications Copyright 2026 graph-agents-cli contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""graph-agents-cli install command: install project dependencies with uv."""
+
+from __future__ import annotations
+
+import logging
+import shutil
+from pathlib import Path
+
+import click
+
+from graph_agents_cli import _tools
+from graph_agents_cli._project import chdir_project_root, find_project_root
+from graph_agents_cli._runner import run
+
+
+@click.command("install")
+@click.option(
+    "--clean",
+    is_flag=True,
+    help="Delete and recreate the uv virtual environment (e.g. after moving the project folder).",
+)
+@click.option(
+    "--locked",
+    is_flag=True,
+    help="Assert that uv.lock is up to date with pyproject.toml; fail instead of updating it.",
+)
+def cmd_install(clean: bool, locked: bool) -> None:
+    """Install project dependencies."""
+    chdir_project_root()
+    # Re-materialize any missing extension working copies from their pinned
+    # SHAs before syncing: the loader tells a user with a missing copy to run
+    # this command. Never advances pins.
+    from graph_agents_cli.extension._sync import sync_extensions
+
+    sync_extensions(find_project_root(Path.cwd()))
+    install_python(clean=clean, locked=locked)
+
+
+def install_python(*, clean: bool, locked: bool) -> None:
+    """Run ``uv sync`` (``--locked`` when asked), deleting ``.venv`` first under ``--clean``."""
+    # Resolve uv up front: --clean deletes the venv. Fail quickly here (before
+    # any destructive work) rather than when calling uv.
+    _tools.require_tool("uv")
+    if clean:
+        _delete_venv()
+    cmd = ["uv", "sync"]
+    if locked:
+        cmd.append("--locked")
+    run(cmd, check_err_msg="Failed to install dependencies")
+
+
+def _delete_venv() -> None:
+    root = find_project_root()
+    if not root:
+        logging.warning("Could not find the project root; nothing to clean.")
+        return
+    venv_path = root / ".venv"
+    if not venv_path.exists():
+        return
+    try:
+        shutil.rmtree(venv_path)
+    except Exception as exc:
+        logging.warning("Failed to remove venv: %s", exc)

graph_agents_cli/dev/cmd_lint.py

@@ -0,0 +1,119 @@
+# Copyright 2026 Google LLC
+# Modifications Copyright 2026 graph-agents-cli contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""graph-agents-cli lint command: ruff, the API-policy check of every tool, the response schema."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+from graph_agents_cli import _response_schema
+from graph_agents_cli._api_policy import POLICY_FILENAME, ensure_no_legacy_api_policy
+from graph_agents_cli._project import chdir_project_root, read_project_config
+from graph_agents_cli._runner import run
+from graph_agents_cli.dev.policy_check import run_policy_check
+
+
+@click.command("lint")
+@click.option("--fix", is_flag=True, default=False, help="Auto-fix lint and formatting issues.")
+@click.option(
+    "--policy-only",
+    "policy_only",
+    is_flag=True,
+    default=False,
+    help="Run only the API-policy check (skip ruff).",
+)
+def cmd_lint(fix: bool, policy_only: bool) -> None:
+    """Run code quality checks and the API-policy check.
+
+    \b
+    ruff check .            (--fix applies fixes)
+    ruff format . --check   (--fix reformats in place)
+    API-policy check        api-policy.yaml must pass the strict schema, and
+                            every API_CALLS entry of every tool must name a
+                            declared API and be allowed by its rules (and
+                            exist in its OpenAPI spec when one is named)
+    Response schema         <agent directory>/response_schema.json, when the
+                            project has one (structured final answers), must
+                            be a schema the agent starts with; a warning when
+                            agent.py does not pass response_format() to the
+                            agent or has no StructuredAnswer() in its
+                            middleware
+
+    \b
+    Exit codes:
+      0  clean
+      1  a refused call or an unreadable API_CALLS, or ruff failed
+      3  configuration error: an invalid api-policy.yaml or response
+         schema, the retired product policy, or not in a project
+    """
+    chdir_project_root()
+    cfg = read_project_config()
+    ensure_no_legacy_api_policy(Path.cwd())
+    check_response_schema(Path.cwd(), cfg.agent_directory)
+    if not policy_only:
+        lint_python(fix=fix)
+    violations = run_policy_check(
+        Path.cwd(),
+        cfg.agent_directory,
+        policy_file=cfg.api_policy_file or POLICY_FILENAME,
+        runtime=cfg.runtime,
+        policy_declared=bool(cfg.api_policy_file),
+        auth_policy=cfg.auth_policy,
+    )
+    if violations:
+        raise click.ClickException(
+            f"API policy check failed: {violations} violation(s). Fix the tool declarations, "
+            "or change api-policy.yaml with `graph-agents-cli api` (the commands above) in a "
+            "reviewed pull request."
+        )
+
+
+def check_response_schema(project_root: Path, agent_directory: str) -> None:
+    """The project's response schema, when it has one: refused (exit 3) unless the agent starts
+    with it; a warning when ``agent.py`` does not build the agent with ``response_format()`` or
+    lacks ``StructuredAnswer()`` in its middleware."""
+    path = _response_schema.schema_file(project_root, agent_directory)
+    if not path.is_file():
+        return
+    _response_schema.load_schema(path)
+    problems = _response_schema.wiring_problems(project_root, agent_directory)
+    if problems:
+        click.secho(
+            f"Warning: {agent_directory}/{_response_schema.SCHEMA_FILENAME} declares structured "
+            f"answers, but {'; and '.join(problems)}. Pass "
+            "response_format=response_format(model, tools) to create_agent and put "
+            "StructuredAnswer() last in middleware(); see the template's "
+            "app_utils/structured.py.",
+            fg="yellow",
+            err=True,
+        )
+    else:
+        click.echo(f"Response schema: {agent_directory}/{_response_schema.SCHEMA_FILENAME} OK")
+
+
+def lint_python(*, fix: bool) -> None:
+    """Run ``ruff check`` and ``ruff format`` in the project."""
+    if fix:
+        run(["uv", "run", "ruff", "check", ".", "--fix"], check_err_msg="Ruff check --fix failed")
+        run(["uv", "run", "ruff", "format", "."], check_err_msg="Ruff format failed")
+    else:
+        run(["uv", "run", "ruff", "check", "."], check_err_msg="Ruff check failed")
+        run(
+            ["uv", "run", "ruff", "format", ".", "--check"],
+            check_err_msg="Ruff format check failed",
+        )