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

graph_agents_cli/deploy/__init__.py

@@ -0,0 +1,15 @@
+# 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 deploy commands."""

graph_agents_cli/deploy/_config.py

@@ -0,0 +1,171 @@
+# 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.
+"""Deployment settings read from the project manifest.
+
+Adapts ``ProjectConfig`` (the manifest's field names) to the small set of
+values deploy, secrets, and infra need. Attributes are read defensively so the
+commands work while ``_project.py`` is being finalised; every fallback follows
+the manifest schema and the CLI's defaults.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from graph_agents_cli import _project
+from graph_agents_cli._defaults import (
+    ENVIRONMENTS,
+    auth_policy_implemented_default,
+    default_secret_keys,
+    normalize_auth_policy,
+)
+from graph_agents_cli.deploy._kube import ConfigError, Target
+
+
+@dataclass
+class DeploySettings:
+    """Everything deploy/secrets/infra need from the manifest."""
+
+    project_name: str
+    deployment_target: str = "kubernetes"
+    runtime: str = "fastapi"
+    model_provider: str = "openai"
+    registry: str = ""
+    cd: str = "skip"
+    auth_policy: str = "shared-bearer"
+    auth_policy_implemented: bool = True
+    environments: dict[str, dict[str, str]] = field(default_factory=dict)
+    secret_keys: list[str] = field(default_factory=list)
+    secrets_owner: str = ""
+
+    # -- derived -------------------------------------------------------------
+
+    @property
+    def release(self) -> str:
+        return self.project_name
+
+    @property
+    def secret_name(self) -> str:
+        return f"{self.project_name}-app"
+
+    @property
+    def metrics_secret_name(self) -> str:
+        """The Secret holding only ``METRICS_TOKEN``, for the Prometheus ServiceMonitor."""
+        return f"{self.project_name}-metrics"
+
+    @property
+    def chart_dir(self) -> Path:
+        return Path("deployment") / "helm" / self.project_name
+
+    def values_file(self, env: str) -> Path:
+        return self.chart_dir / f"values-{env}.yaml"
+
+    @property
+    def image_repository(self) -> str:
+        if not self.registry:
+            raise ConfigError(
+                "No registry is configured (create_params.registry is empty).\n"
+                "  Set it in graph-agents-cli-manifest.yaml, e.g. registry: ghcr.io/my-org"
+            )
+        return f"{self.registry.rstrip('/')}/{self.project_name}"
+
+    def environment(self, env: str) -> dict[str, str]:
+        if env not in self.environments:
+            known = ", ".join(sorted(self.environments)) or "none"
+            raise ConfigError(
+                f"Unknown environment {env!r}. Environments in the manifest: {known}."
+            )
+        return self.environments[env]
+
+    def target(self, env: str) -> Target:
+        spec = self.environment(env)
+        namespace = spec.get("namespace") or f"{self.project_name}-{env}"
+        return Target(context=spec.get("context") or None, namespace=namespace)
+
+    # -- construction --------------------------------------------------------
+
+    @classmethod
+    def from_project(cls, cfg: Any) -> DeploySettings:
+        cp = getattr(cfg, "create_params", None)
+        cp = dict(cp) if isinstance(cp, Mapping) else {}
+
+        def pick(attr: str, default: Any) -> Any:
+            value = getattr(cfg, attr, None)
+            if value is None:
+                value = cp.get(attr)
+            return default if value is None else value
+
+        name = getattr(cfg, "project_name", "") or ""
+        if not name:
+            raise ConfigError("The manifest has no project name.")
+        deployment_target = pick("deployment_target", "none")
+        if deployment_target != "kubernetes":
+            raise ConfigError(
+                f"This project has deployment_target: {deployment_target}; nothing to deploy.\n"
+                "  Re-scaffold with --deployment-target kubernetes to add a Helm chart."
+            )
+        runtime = pick("runtime", "fastapi")
+        model_provider = pick("model_provider", "openai")
+        auth_policy = normalize_auth_policy(pick("auth_policy", "shared-bearer"), warn=False)
+        implemented = pick("auth_policy_implemented", None)
+        if implemented is None:
+            implemented = auth_policy_implemented_default(auth_policy)
+
+        environments: dict[str, dict[str, str]] = {}
+        raw_envs = getattr(cfg, "environments", None)
+        if isinstance(raw_envs, Mapping):
+            for env, spec in raw_envs.items():
+                spec = spec if isinstance(spec, Mapping) else {}
+                environments[str(env)] = {
+                    "context": str(spec.get("context") or ""),
+                    "namespace": str(spec.get("namespace") or f"{name}-{env}"),
+                }
+        if not environments:
+            environments = {
+                env: {"context": "", "namespace": f"{name}-{env}"} for env in ENVIRONMENTS
+            }
+
+        secret_keys = getattr(cfg, "secret_keys", None)
+        owner = ""
+        raw_secrets = getattr(cfg, "secrets", None)
+        if isinstance(raw_secrets, Mapping):
+            if secret_keys is None:
+                secret_keys = raw_secrets.get("keys")
+            owner = str(raw_secrets.get("owner") or "")
+        if secret_keys is None:
+            secret_keys = default_secret_keys(model_provider, runtime, auth_policy=auth_policy)
+        owner = getattr(cfg, "secrets_owner", None) or owner
+
+        return cls(
+            project_name=name,
+            deployment_target=deployment_target,
+            runtime=runtime,
+            model_provider=model_provider,
+            registry=str(pick("registry", "") or ""),
+            cd=str(pick("cd", "skip") or "skip"),
+            auth_policy=auth_policy,
+            auth_policy_implemented=bool(implemented),
+            environments=environments,
+            secret_keys=[str(k) for k in secret_keys],
+            secrets_owner=owner,
+        )
+
+
+def load_settings() -> DeploySettings:
+    """chdir to the project root and read the manifest into ``DeploySettings``."""
+    _project.chdir_project_root()
+    return DeploySettings.from_project(_project.read_project_config())

graph_agents_cli/deploy/_image.py

@@ -0,0 +1,128 @@
+# 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.
+"""Image reference checks run before ``docker build``, ``docker push`` or ``helm``.
+
+``create`` writes the placeholder registry ``ghcr.io/CHANGE-ME`` when it finds
+no git remote. Docker rejects it (a repository path must be lowercase) only
+after the build starts, with a parser error that does not say which setting to
+change. These helpers catch the placeholder and any other malformed reference
+up front so ``build`` and ``deploy`` stop with a configuration error (exit 3)
+that names the setting.
+
+The grammar follows the distribution reference format Docker uses: an optional
+registry host (with port), lowercase path components separated by ``/``, and a
+tag of at most 128 word characters, dots and dashes.
+"""
+
+from __future__ import annotations
+
+import re
+
+from graph_agents_cli._defaults import REGISTRY_FIX_COMMAND, REGISTRY_FIX_EFFECT
+
+PLACEHOLDER = "CHANGE-ME"
+
+_DOMAIN_COMPONENT = r"(?:[A-Za-z0-9]|[A-Za-z0-9][A-Za-z0-9-]*[A-Za-z0-9])"
+_DOMAIN_RE = re.compile(
+    rf"^(?:{_DOMAIN_COMPONENT}(?:\.{_DOMAIN_COMPONENT})*|\[[0-9A-Fa-f:.]+\])(?::[0-9]+)?$"
+)
+_PATH_COMPONENT_RE = re.compile(r"^[a-z0-9]+(?:(?:[._]|__|-+)[a-z0-9]+)*$")
+_TAG_RE = re.compile(r"^[A-Za-z0-9_][A-Za-z0-9_.-]{0,127}$")
+MAX_NAME_LENGTH = 255
+
+
+def has_placeholder(value: str | None) -> bool:
+    """True when ``value`` still carries the scaffold's ``CHANGE-ME`` placeholder."""
+    return PLACEHOLDER.lower() in (value or "").lower()
+
+
+def _split_domain(name: str) -> tuple[str | None, str]:
+    """``(domain, path)`` using Docker's rule for what counts as a registry host.
+
+    The first component is a host when it contains ``.`` or ``:``, is
+    ``localhost``, or has an upper-case letter; otherwise the whole name is a
+    path on the default registry.
+    """
+    first, sep, rest = name.partition("/")
+    if not sep:
+        return None, name
+    if "." in first or ":" in first or first == "localhost" or first.lower() != first:
+        return first, rest
+    return None, name
+
+
+def repository_problem(repository: str) -> str | None:
+    """Why ``repository`` (``[host[:port]/]path``, no tag) is not a valid image name."""
+    if not repository:
+        return "the repository is empty"
+    if len(repository) > MAX_NAME_LENGTH:
+        return f"the repository name is longer than {MAX_NAME_LENGTH} characters"
+    domain, path = _split_domain(repository)
+    if domain is not None and not _DOMAIN_RE.match(domain):
+        return f"{domain!r} is not a valid registry host"
+    for component in path.split("/"):
+        if not component:
+            return "the repository path has an empty component (a doubled or trailing '/')"
+        if not _PATH_COMPONENT_RE.match(component):
+            if component.lower() != component:
+                return f"the repository path component {component!r} must be lowercase"
+            return (
+                f"the repository path component {component!r} may only hold lowercase letters, "
+                "digits and single '.', '_' or '-' separators"
+            )
+    return None
+
+
+def tag_problem(tag: str) -> str | None:
+    """Why ``tag`` is not a valid image tag (``None`` when it is)."""
+    if not _TAG_RE.match(tag or ""):
+        return (
+            f"the tag {tag!r} must start with a letter, digit or '_' and hold at most 128 "
+            "letters, digits, '_', '.' or '-'"
+        )
+    return None
+
+
+def placeholder_message(registry: str) -> str:
+    return (
+        f"The image registry is still the placeholder {registry!r}.\n"
+        f"  Run `{REGISTRY_FIX_COMMAND}` ({REGISTRY_FIX_EFFECT}), or set "
+        "create_params.registry in graph-agents-cli-manifest.yaml to your registry (for "
+        "example ghcr.io/<org>) by hand; `build` also takes --registry."
+    )
+
+
+def reference_problem(
+    repository: str, tag: str | None, *, registry: str | None = None
+) -> str | None:
+    """A user-facing reason the image ``repository[:tag]`` cannot be built or pushed.
+
+    ``registry`` is the configured registry the repository was derived from; a
+    placeholder there is reported as such (it names the setting to change)
+    rather than as a grammar error.
+    """
+    if has_placeholder(registry):
+        return placeholder_message(registry or "")
+    if has_placeholder(repository):
+        return (
+            f"The image reference {repository!r} still holds the {PLACEHOLDER} placeholder; "
+            "pass the real image."
+        )
+    problem = repository_problem(repository)
+    if problem is None and tag is not None:
+        problem = tag_problem(tag)
+    if problem is None:
+        return None
+    ref = f"{repository}:{tag}" if tag is not None else repository
+    return f"{ref!r} is not a valid image reference: {problem}."

graph_agents_cli/deploy/_kube.py

@@ -0,0 +1,286 @@
+# 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.
+"""kubectl and helm wrappers used by deploy, secrets, and infra check.
+
+Every subprocess goes through ``graph_agents_cli._runner.run_resolved`` (looked
+up at call time so tests can monkeypatch it). Nothing here imports a Kubernetes
+client; the CLI shells out to ``kubectl`` and ``helm``.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shlex
+import subprocess
+from dataclasses import dataclass
+from typing import Any
+
+import click
+
+from graph_agents_cli import _runner, _tools
+from graph_agents_cli._output import Console
+
+
+class DeployError(click.ClickException):
+    """Base for deploy/secrets/infra failures; ``exit_code``: 1 refused, 2 tool failed, 3 config."""
+
+    exit_code = 1
+
+
+class Refused(DeployError):
+    """The operation was refused by policy or mode (exit 1)."""
+
+    exit_code = 1
+
+
+class ToolFailed(DeployError):
+    """helm/kubectl/docker/git/gh returned non-zero or is missing (exit 2)."""
+
+    exit_code = 2
+
+
+class ConfigError(DeployError):
+    """The project or environment is misconfigured (exit 3)."""
+
+    exit_code = 3
+
+
+@dataclass(frozen=True)
+class Target:
+    """Where a command is aimed: a kube context (``None`` = current) and a namespace."""
+
+    context: str | None
+    namespace: str
+
+
+def format_cmd(cmd: list[str]) -> str:
+    return _runner.redact_cmd(list(cmd))
+
+
+def echo_cmd(cmd: list[str], *, dry_run: bool = False, console: Console | None = None) -> None:
+    """Print a command the way the rest of the CLI does (``▸ cmd``)."""
+    prefix = "[dry-run]" if dry_run else "▸"
+    (console or Console()).print(
+        f"  {prefix} {format_cmd(cmd)}", style="cyan", highlight=False, markup=False
+    )
+
+
+def run_cmd(
+    cmd: list[str],
+    *,
+    capture: bool = True,
+    check: bool = True,
+    input_text: str | None = None,
+    env: dict[str, str] | None = None,
+    dry_run: bool = False,
+    quiet: bool = False,
+    console: Console | None = None,
+) -> subprocess.CompletedProcess[str]:
+    """Run ``cmd`` through ``run_resolved``.
+
+    ``dry_run`` prints the command and returns an empty, successful result.
+    A missing tool or a non-zero exit (with ``check``) raises ``ToolFailed`` (exit 2).
+    """
+    if not quiet:
+        echo_cmd(cmd, dry_run=dry_run, console=console)
+    if dry_run:
+        return subprocess.CompletedProcess(cmd, 0, "", "")
+    run_env = {**os.environ, **env} if env else None
+    try:
+        result = _runner.run_resolved(
+            list(cmd),
+            capture_output=capture,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            input=input_text,
+            env=run_env,
+        )
+    except _tools.ToolNotFoundError as e:
+        raise ToolFailed(str(e)) from e
+    except OSError as e:
+        raise ToolFailed(f"Could not run {format_cmd(cmd)}: {e}") from e
+    if check and result.returncode != 0:
+        detail = "\n".join(
+            part.strip()
+            for part in (result.stdout, result.stderr)
+            if isinstance(part, str) and part.strip()
+        )
+        msg = f"Command failed (exit code {result.returncode}): {format_cmd(cmd)}"
+        if detail:
+            msg += f"\n{detail}"
+        raise ToolFailed(msg)
+    return result
+
+
+def tool_available(name: str) -> bool:
+    """True when ``name`` resolves on PATH (via ``require_tool``, monkeypatchable)."""
+    try:
+        _tools.require_tool(name)
+    except _tools.ToolNotFoundError:
+        return False
+    return True
+
+
+def kubectl_args(args: list[str], target: Target | None, *, namespaced: bool = True) -> list[str]:
+    cmd = ["kubectl", *args]
+    if target is not None:
+        if namespaced and target.namespace:
+            cmd += ["-n", target.namespace]
+        if target.context:
+            cmd += ["--context", target.context]
+    return cmd
+
+
+def kubectl(
+    args: list[str],
+    target: Target | None = None,
+    *,
+    namespaced: bool = True,
+    **kwargs: Any,
+) -> subprocess.CompletedProcess[str]:
+    return run_cmd(kubectl_args(args, target, namespaced=namespaced), **kwargs)
+
+
+def kubectl_json(
+    args: list[str], target: Target | None = None, *, namespaced: bool = True, **kwargs: Any
+) -> Any:
+    """Run ``kubectl ... -o json`` and parse the result (``None`` on dry-run)."""
+    result = kubectl([*args, "-o", "json"], target, namespaced=namespaced, **kwargs)
+    if not result.stdout:
+        return None
+    try:
+        return json.loads(result.stdout)
+    except json.JSONDecodeError as e:
+        raise ToolFailed(f"kubectl returned invalid JSON: {e}") from e
+
+
+def helm_args(args: list[str], target: Target | None) -> list[str]:
+    cmd = ["helm", *args]
+    if target is not None:
+        if target.namespace:
+            cmd += ["-n", target.namespace]
+        if target.context:
+            cmd += ["--kube-context", target.context]
+    return cmd
+
+
+def helm(
+    args: list[str], target: Target | None = None, **kwargs: Any
+) -> subprocess.CompletedProcess[str]:
+    return run_cmd(helm_args(args, target), **kwargs)
+
+
+def current_context() -> str | None:
+    """The kubeconfig's current context, or ``None`` when kubectl is missing or unset."""
+    try:
+        result = run_cmd(["kubectl", "config", "current-context"], check=False, quiet=True)
+    except ToolFailed:
+        return None
+    if result.returncode != 0:
+        return None
+    return (result.stdout or "").strip() or None
+
+
+def context_names() -> set[str]:
+    """Context names in the kubeconfig (empty when they cannot be listed; never raises)."""
+    try:
+        result = run_cmd(
+            ["kubectl", "config", "get-contexts", "-o", "name"], check=False, quiet=True
+        )
+    except ToolFailed:
+        return set()
+    if result.returncode != 0:
+        return set()
+    return {line.strip() for line in (result.stdout or "").splitlines() if line.strip()}
+
+
+def server_url(context: str | None) -> str | None:
+    """The API server URL the kubeconfig records for ``context`` (read locally, never raises)."""
+    cmd = [
+        "kubectl",
+        "config",
+        "view",
+        "--minify",
+        "-o",
+        "jsonpath={.clusters[0].cluster.server}",
+    ]
+    if context:
+        cmd += ["--context", context]
+    try:
+        result = run_cmd(cmd, check=False, quiet=True)
+    except ToolFailed:
+        return None
+    if result.returncode != 0:
+        return None
+    return (result.stdout or "").strip() or None
+
+
+def in_ci() -> bool:
+    """True inside a GitHub Actions job (the runner sets ``GITHUB_ACTIONS=true``)."""
+    return os.environ.get("GITHUB_ACTIONS", "").strip().lower() == "true"
+
+
+def ensure_namespace(
+    target: Target, *, dry_run: bool = False, console: Console | None = None
+) -> None:
+    """Create ``target.namespace`` when it does not exist (idempotent).
+
+    A fresh cluster has no ``<name>-<env>`` namespace yet, and the Secret is
+    applied before ``helm --create-namespace`` runs (in CD modes helm never runs
+    from here at all). A caller without permission to read namespaces
+    (namespace-scoped RBAC) is assumed to work in an existing one; any other
+    failure is a tool failure (exit 2).
+    """
+    console = console or Console()
+    ns = target.namespace
+    create = kubectl_args(["create", "namespace", ns], target, namespaced=False)
+    if dry_run:
+        console.print(
+            f"  [dry-run] {format_cmd(create)}  (only when the namespace does not exist)",
+            style="cyan",
+            highlight=False,
+            markup=False,
+        )
+        return
+    probe = kubectl(
+        ["get", "namespace", ns, "-o", "name"], target, namespaced=False, check=False, quiet=True
+    )
+    if probe.returncode == 0:
+        return
+    stderr = (probe.stderr or "").strip()
+    if "(Forbidden)" in stderr:
+        console.print(
+            f"  Cannot read namespace {ns} (RBAC); assuming it exists.", style="dim", markup=False
+        )
+        return
+    if "(NotFound)" not in stderr:
+        raise ToolFailed(
+            f"Command failed (exit code {probe.returncode}): "
+            f"{format_cmd(kubectl_args(['get', 'namespace', ns], target, namespaced=False))}"
+            + (f"\n{stderr}" if stderr else "")
+        )
+    result = run_cmd(create, check=False, console=console)
+    if result.returncode != 0 and "(AlreadyExists)" not in (result.stderr or ""):
+        detail = (result.stderr or result.stdout or "").strip()
+        raise ToolFailed(
+            f"Command failed (exit code {result.returncode}): {format_cmd(create)}"
+            + (f"\n{detail}" if detail else "")
+        )
+    console.print(f"  Created namespace {ns}.")
+
+
+def pipe_description(first: list[str], second: list[str]) -> str:
+    return f"{shlex.join(first)} | {shlex.join(second)}"