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

graph_agents_cli/_skills_check.py

@@ -0,0 +1,274 @@
+# 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.
+
+"""Skills version drift detection for graph-agents-cli.
+
+Owns the ``graph-agents-cli-`` skills prefix filter that ``info`` relies on.
+The check is opt-out for disconnected installs: it is
+skipped when ``GRAPH_AGENTS_CLI_NO_UPDATE_CHECK=1`` or a CI marker is set, and
+it degrades silently (debug log only) when ``npx`` or the network is absent.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import time
+from pathlib import Path
+
+import click
+import yaml
+
+# Pin the skills npm package to avoid executing an unverified version.
+SKILLS_NPX_PACKAGE = "skills@1.5.9"
+
+SKILL_PREFIX = "graph-agents-cli-"
+
+# Opt-out for the update and skills-version checks (disconnected installs). `main.py` reads the
+# same variable before importing this module; the check re-reads it so that a
+# direct call honours the opt-out too.
+NO_UPDATE_CHECK_ENV = "GRAPH_AGENTS_CLI_NO_UPDATE_CHECK"
+
+_SKILLS_CHECK_INTERVAL = 12 * 60 * 60  # 12 hours in seconds
+_SKILLS_CHECK_STAMP = Path.home() / ".agents" / ".graph_agents_cli_skills_check"
+
+
+def _parse_skill_version(skill_md: Path) -> str | None:
+    """Extract ``metadata.version`` from a SKILL.md YAML frontmatter.
+
+    Returns the version string, or ``None`` on any failure.
+    Logs at debug level when the file exists but cannot be parsed.
+    """
+    try:
+        content = skill_md.read_text(encoding="utf-8")
+    except OSError:
+        return None
+
+    if not content.startswith("---"):
+        logging.debug("Malformed skill file (no frontmatter): %s", skill_md)
+        return None
+    parts = content.split("---", 2)
+    if len(parts) < 3:
+        logging.debug("Malformed skill file (incomplete frontmatter): %s", skill_md)
+        return None
+    try:
+        frontmatter = yaml.safe_load(parts[1])
+    except yaml.YAMLError:
+        logging.debug("Malformed skill file (invalid YAML): %s", skill_md)
+        return None
+
+    metadata = (frontmatter or {}).get("metadata") or {}
+    version = metadata.get("version") if isinstance(metadata, dict) else None
+    if not version:
+        logging.debug("Malformed skill file (missing metadata.version): %s", skill_md)
+    return str(version) if version else None
+
+
+def _find_installed_skills() -> dict[str, str]:
+    """Return ``{skill_name: version}`` for every installed graph-agents-cli skill.
+
+    Fast path (~8 ms): scan ``~/.agents/skills/graph-agents-cli-*/SKILL.md``
+    directly.  Falls back to ``npx skills list --json`` (~400 ms+) if
+    the well-known directory is empty or missing, which is more robust
+    when skills are installed to a non-default location.
+    """
+    import json
+
+    result: dict[str, str] = {}
+
+    # Fast path: well-known global install location
+    skills_dir = Path.home() / ".agents" / "skills"
+    if skills_dir.is_dir():
+        for skill_dir in sorted(skills_dir.iterdir()):
+            if not skill_dir.name.startswith(SKILL_PREFIX):
+                continue
+            version = _parse_skill_version(skill_dir / "SKILL.md")
+            if version:
+                result[skill_dir.name] = version
+
+    if result:
+        return result
+
+    # Slow path: ask npx skills for actual install locations
+    try:
+        from graph_agents_cli._runner import run_resolved
+
+        proc = run_resolved(
+            ["npx", "-y", SKILLS_NPX_PACKAGE, "list", "--json"],
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            timeout=15,
+        )
+        if proc.returncode != 0:
+            return {}
+        entries = json.loads(proc.stdout)
+    except Exception as e:
+        # Broad by design: this freshness check runs on every CLI invocation and
+        # must never abort a user's command, so any failure (no npx, no network)
+        # degrades silently to "no skills found" rather than propagating.
+        logging.debug("Could not query installed skills via npx: %s", e)
+        return {}
+
+    if not isinstance(entries, list):
+        return {}
+
+    for entry in entries:
+        if not isinstance(entry, dict):
+            logging.debug("Skipping malformed skills entry (expected an object): %r", entry)
+            continue
+        name = entry.get("name", "")
+        if not name.startswith(SKILL_PREFIX):
+            continue
+        path = entry.get("path")
+        if not path:
+            continue
+        version = _parse_skill_version(Path(path) / "SKILL.md")
+        if version:
+            result[name] = version
+
+    return result
+
+
+def get_installed_skills() -> list[dict] | None:
+    """Return installed graph-agents-cli skills as a list of dicts.
+
+    Returns None if the query fails (no ``npx``, no network, malformed output),
+    and without running it when :func:`skills_listing_skipped` names a reason:
+    ``npx -y skills@... list`` may download the package, which a disconnected
+    install (``GRAPH_AGENTS_CLI_NO_UPDATE_CHECK=1``) and CI opt out of.
+    """
+    import json
+
+    if skills_listing_skipped():
+        return None
+    try:
+        from graph_agents_cli._runner import run_resolved
+
+        result = run_resolved(
+            ["npx", "-y", SKILLS_NPX_PACKAGE, "list", "--json"],
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            timeout=15,
+        )
+        if result.returncode != 0:
+            logging.debug(
+                "npx skills list failed (exit %d): %s",
+                result.returncode,
+                (result.stderr or "").strip(),
+            )
+            return None
+        skills = json.loads(result.stdout)
+        return [
+            s
+            for s in skills
+            if isinstance(s, dict) and str(s.get("name", "")).startswith(SKILL_PREFIX)
+        ]
+    except Exception as e:
+        logging.debug("Could not query installed skills: %s", e)
+        return None
+
+
+def skills_listing_skipped() -> str | None:
+    """Why the skills listing (``npx skills list``) is not run, or None when it is.
+
+    The same opt-out as :func:`check_skills_version`: ``GRAPH_AGENTS_CLI_NO_UPDATE_CHECK=1``
+    (the disconnected profile) or a CI marker.
+    """
+    if _is_opted_out():
+        return f"{NO_UPDATE_CHECK_ENV}=1"
+    marker = next((var for var in _CI_MARKERS if os.environ.get(var)), None)
+    return f"{marker} is set (CI)" if marker else None
+
+
+_CI_MARKERS = ("CI", "BUILD_ID", "GITHUB_ACTIONS", "GITLAB_CI")
+
+
+def _is_ci() -> bool:
+    """Return True when running in a CI/automation environment.
+
+    The skills version-drift warning is a local developer-experience nicety: in
+    CI there is no human to act on it and skills are not installed, so the check
+    only adds noise (and may spawn a doomed ``npx`` subprocess). We skip it when
+    a well-known CI marker is present.
+    """
+    return any(os.environ.get(var) for var in _CI_MARKERS)
+
+
+def _is_opted_out() -> bool:
+    """Return True when the user disabled the check."""
+    return os.environ.get(NO_UPDATE_CHECK_ENV) == "1"
+
+
+def _skills_check_is_due() -> bool:
+    """Return True if enough time has elapsed since the last check."""
+    try:
+        last = float(_SKILLS_CHECK_STAMP.read_text().strip())
+        return (time.time() - last) > _SKILLS_CHECK_INTERVAL
+    except (OSError, ValueError):
+        return True
+
+
+def _record_skills_check() -> None:
+    """Write the current timestamp to the stamp file."""
+    try:
+        _SKILLS_CHECK_STAMP.parent.mkdir(parents=True, exist_ok=True)
+        _SKILLS_CHECK_STAMP.write_text(str(time.time()))
+    except OSError:
+        pass
+
+
+def check_skills_version() -> None:
+    """Warn if any installed skill version doesn't match the running CLI version.
+
+    Rate-limited to once per 12 hours via a timestamp file so it can
+    run globally on every command without adding latency.
+
+    Scans all installed ``graph-agents-cli-*`` skills, compares each
+    ``metadata.version`` with the running ``__version__``, and lists
+    the mismatched ones.  Never blocks execution. Skipped entirely in CI
+    and when ``GRAPH_AGENTS_CLI_NO_UPDATE_CHECK=1``. Silent offline.
+    """
+    if _is_opted_out() or _is_ci() or not _skills_check_is_due():
+        return
+
+    try:
+        installed = _find_installed_skills()
+    except Exception as e:  # never abort the user's command
+        logging.debug("Skills check skipped: %s", e)
+        return
+    if not installed:
+        return
+
+    from graph_agents_cli import __version__
+
+    _record_skills_check()
+
+    mismatched = {name: ver for name, ver in installed.items() if ver != __version__}
+    if not mismatched:
+        return
+
+    lines = [f"  - {name} (v{ver})" for name, ver in mismatched.items()]
+    click.echo(
+        f"\n⚠️  Skills version mismatch — CLI is v{__version__}, "
+        f"but {len(mismatched)} skill(s) differ:\n"
+        + "\n".join(lines)
+        + "\n   Run 'graph-agents-cli setup' to install the skills of this version (or "
+        "'graph-agents-cli update' to move the CLI and the skills to the latest release).\n",
+        err=True,
+    )

graph_agents_cli/_tools.py

@@ -0,0 +1,189 @@
+# 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.
+
+"""Tool resolution utilities.
+
+Every external program the CLI shells out to (helm, kubectl, docker, gh, uv,
+npx, ...) is resolved through :func:`require_tool`, which caches the resolved
+path and, on Windows, retries with a cleaned PATH. Nothing here imports a
+model SDK, LangChain, LangGraph, or a Kubernetes/Docker client.
+"""
+
+import os
+import re
+import shlex
+import shutil
+from functools import cache
+
+import click
+
+_tool_paths: dict[str, str] = {}
+
+# Matches ANSI escape sequences (CSI/SGR), used to scrub any residual color
+# codes from captured subprocess output. We disable color at the source via
+# NO_COLOR/FORCE_COLOR, but strip defensively in case the tool emits them anyway
+# (e.g. on Windows PowerShell, where embedded escapes have caused error lines
+# to render as the previous line's color).
+_ANSI_RE = re.compile(r"\x1b\[[0-9;?]*[a-zA-Z]")
+
+# Where `graph-agents-cli setup` fetches the skills from by default (pinned to the
+# running release's tag, see `default_skills_source`).
+# Keep in sync with extension._refs.FIRST_PARTY_REPO.
+DEFAULT_SKILLS_SOURCE = "https://github.com/ss7172/graph-agents-cli"
+
+
+def default_skills_source(version: str | None) -> str:
+    """The first-party skills matching CLI ``version``: ``<repo>#v<version>``.
+
+    A release installs the skills of its own tag, so they never drift from the
+    CLI when the default branch moves on. A development build (a source
+    checkout, ``0.0.0-dev``, an unknown ``0.0.0``, a ``.devN`` or ``+local``
+    version) has no matching tag and uses the default branch.
+    """
+    from packaging.version import InvalidVersion, Version
+
+    try:
+        parsed = Version(version or "")
+    except InvalidVersion:
+        return DEFAULT_SKILLS_SOURCE
+    if parsed.is_devrelease or parsed.local or parsed == Version("0.0.0"):
+        return DEFAULT_SKILLS_SOURCE
+    return f"{DEFAULT_SKILLS_SOURCE}#v{version}"
+
+
+_UV_HINT = "Install uv (https://docs.astral.sh/uv/getting-started/installation/) and ensure it is in your PATH."
+_NODE_HINT = "Install Node.js (https://nodejs.org/en/download) and ensure it is in your PATH."
+
+# Default installation hints for the tools the CLI shells out to.
+# These are used as fallbacks in require_tool when no specific hint is provided,
+# ensuring helpful error messages even when tools are resolved implicitly (e.g. via run_resolved).
+DEFAULT_INSTALL_HINTS = {
+    "helm": "Install Helm (https://helm.sh/docs/intro/install/) and ensure it is in your PATH.",
+    "kubectl": "Install kubectl (https://kubernetes.io/docs/tasks/tools/) and ensure it is in your PATH.",
+    "docker": "Install Docker (https://docs.docker.com/get-docker/) or a Docker-compatible CLI named 'docker' and ensure it is in your PATH.",
+    "argocd": "Install the Argo CD CLI (https://argo-cd.readthedocs.io/en/stable/cli_installation/) and ensure it is in your PATH.",
+    "gh": "Install the GitHub CLI (https://cli.github.com/) and ensure it is in your PATH.",
+    "uv": _UV_HINT,
+    # uvx is shipped by uv, so the install instructions are the same.
+    "uvx": f"uvx is part of uv. {_UV_HINT}",
+    "npx": f"npx is part of Node.js. {_NODE_HINT}",
+    "npm": f"npm is part of Node.js. {_NODE_HINT}",
+    "node": _NODE_HINT,
+    "git": "Install Git (https://git-scm.com/downloads) and ensure it is in your PATH.",
+    "langgraph": (
+        "langgraph is a project dependency (langgraph-cli), not a global tool: run "
+        "'graph-agents-cli install' inside the project, then invoke it as 'uv run langgraph'."
+    ),
+}
+
+
+class ToolNotFoundError(click.ClickException):
+    """Raised when a required external tool is not found on PATH."""
+
+    pass
+
+
+@cache
+def _get_cleaned_path() -> str:
+    """Returns a cleaned and expanded version of the PATH environment variable.
+
+    This function performs the following steps:
+    1. Splits the PATH environment variable using the OS-specific path separator.
+    2. Strips quotes from each path segment.
+    3. Filters out empty path segments.
+    4. Expands environment variables (like $HOME or %USERPROFILE%) within each segment.
+    5. Reconstructs the PATH string with the cleaned segments.
+    """
+    raw_path = os.environ.get("PATH", "")
+    parts = raw_path.split(os.pathsep)
+    cleaned_parts = []
+
+    for part in parts:
+        # Strip quotes from each path segment.
+        part = part.strip('"').strip("'")
+        if not part:
+            continue
+        cleaned_parts.append(os.path.expandvars(part))
+    return os.pathsep.join(cleaned_parts)
+
+
+def is_windows() -> bool:
+    """Returns True if the current operating system is Windows."""
+    return os.name == "nt"
+
+
+def install_hint(name: str) -> str:
+    """Return the default installation hint for ``name`` (empty when unknown)."""
+    return DEFAULT_INSTALL_HINTS.get(name, "")
+
+
+def require_tool(name: str, install_hint: str = "") -> str:
+    """Finds a required external tool on the system PATH and returns its path.
+
+    This function performs the following steps:
+    1. Checks if the tool's path is already cached in `_tool_paths`.
+    2. If not cached, searches for the tool using `shutil.which` with the default PATH.
+    3. If not found and running on Windows, searches again using `shutil.which` with a cleaned PATH.
+    4. If still not found, raises a `ToolNotFoundError` with an install hint
+       (the explicit ``install_hint`` or the default for that tool).
+    5. If found, caches the path and returns it.
+    """
+    if name in _tool_paths:
+        return _tool_paths[name]
+
+    path = shutil.which(name)
+
+    if path is None and is_windows():
+        path = shutil.which(name, path=_get_cleaned_path())
+
+    if path is None:
+        msg = f"'{name}' is not installed or not on PATH."
+        hint = install_hint or DEFAULT_INSTALL_HINTS.get(name, "")
+        if hint:
+            msg += f"\n  {hint}"
+        raise ToolNotFoundError(msg)
+
+    _tool_paths[name] = path
+    return path
+
+
+def tool_available(name: str) -> bool:
+    """Return True when ``name`` resolves on PATH, without raising."""
+    try:
+        require_tool(name)
+    except ToolNotFoundError:
+        return False
+    return True
+
+
+def run_npx_skills(args: list[str], spinner_msg: str):
+    """Run an npx skills command, streaming output in real-time.
+
+    Always starts with ``["npx", "-y", SKILLS_NPX_PACKAGE]`` and appends
+    the additional ``args`` provided.
+
+    Raises:
+        click.ClickException: If the npx process exits non-zero.
+    """
+    from graph_agents_cli._runner import run_resolved
+    from graph_agents_cli._skills_check import SKILLS_NPX_PACKAGE
+
+    full_args = ["npx", "-y", SKILLS_NPX_PACKAGE, *args]
+    click.secho(f"  ▸ {shlex.join(full_args)}", fg="cyan", dim=True)
+
+    try:
+        run_resolved(full_args, check=True, encoding="utf-8", errors="replace")
+    except Exception as e:
+        raise click.ClickException("Error running npx skills") from e

graph_agents_cli/_trust.py

@@ -0,0 +1,66 @@
+# 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
+#
+#     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.
+
+"""Trust tier decorators for agents CLI commands."""
+
+import functools
+
+import click
+
+
+def require_confirmation(message: str):
+    """Decorator that adds --yes/-y and --interactive/-i options to destructive commands.
+
+    In interactive mode (-i), the user is prompted to confirm the action.
+    In auto-approve mode (-y) or strict programmatic mode (no flags), proceeds silently.
+    The decorated function receives an 'auto_approve' parameter.
+
+    Args:
+        message: Confirmation prompt shown to the user.
+    """
+
+    def decorator(f):
+        @click.option(
+            "--interactive",
+            "-i",
+            is_flag=True,
+            default=False,
+            help="Enable interactive confirmation prompt.",
+        )
+        @click.option(
+            "-y",
+            "--yes",
+            "--auto-approve",
+            "auto_approve",
+            is_flag=True,
+            default=False,
+            help="Skip confirmation prompt.",
+        )
+        @functools.wraps(f)
+        def wrapper(*args, interactive=False, auto_approve=False, **kwargs):
+            if interactive and not auto_approve:
+                click.echo()
+                if not click.confirm(f"  {message}", default=False):
+                    click.echo()
+                    click.secho("  Aborted.", fg="yellow")
+                    return
+                click.echo()
+            # In strict programmatic mode (no -i, no -y): auto-proceed silently.
+            # `interactive` is not passed on: the prompt happens here, and no
+            # decorated command has ever read it.
+            return f(*args, auto_approve=auto_approve, **kwargs)
+
+        return wrapper
+
+    return decorator

graph_agents_cli/api/__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 api``: declare and change a project's outbound API access policy."""