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

graph_agents_cli/extension/_overrides.py

@@ -0,0 +1,195 @@
+# 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.
+
+"""Synthesize Click commands that dispatch to an extension's run vector."""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import click
+
+from graph_agents_cli._project import find_project_root
+from graph_agents_cli._runner import DISABLE_OVERRIDES_ENV, run_extension_command
+from graph_agents_cli.extension._spec import ExtensionCommand
+
+if TYPE_CHECKING:
+    from graph_agents_cli.extension._loader import ResolvedCommand
+
+
+def installed_override(dotted: str) -> ResolvedCommand | None:
+    """The extension override installed for `dotted` (e.g. `eval.generate`), if any.
+
+    Click dispatch is where overrides normally take effect, so a built-in that
+    calls another command's callback in-process (`eval run` → `eval generate`)
+    would silently run the built-in. Such a command looks the override up here
+    and dispatches to it instead.
+    """
+    if os.environ.get(DISABLE_OVERRIDES_ENV) == "1":
+        return None
+    from graph_agents_cli.extension._loader import load_extension_set
+    from graph_agents_cli.extension._paths import user_config_root
+
+    extension_set = load_extension_set(find_project_root(Path.cwd()), user_config_root())
+    resolved = extension_set.commands.get(dotted)
+    if resolved is None or resolved.contribution.kind != "override":
+        return None
+    if resolved.blocked_requires:
+        raise click.ClickException(
+            f"{dotted!r} comes from extension {resolved.extension_name!r}, which "
+            f"requires graph-agents-cli {resolved.blocked_requires}.\n"
+            f"  Update it:      graph-agents-cli extension update {resolved.extension_name}\n"
+            f"  Or remove it:   graph-agents-cli extension remove {resolved.extension_name}"
+        )
+    return resolved
+
+
+def run_override(resolved: ResolvedCommand, argv: list[str], *, display_path: str) -> None:
+    """Run a resolved override's vector, exiting with its code on failure."""
+    cwd = find_project_root() or Path.cwd()
+    try:
+        code = run_extension_command(
+            resolved.contribution.run,
+            argv,
+            cwd=cwd,
+            extension_root=resolved.extension_root,
+        )
+    except FileNotFoundError as e:
+        raise click.ClickException(
+            f"Extension '{resolved.extension_name}' command {display_path!r} could not "
+            f"run: executable {resolved.contribution.run[0]!r} not found. "
+            "Check the extension's `run:` entry."
+        ) from e
+    if code != 0:
+        # Exit with the child's code, matching what a direct `graph-agents-cli <cmd>`
+        # would return; a ClickException would flatten every failure to 1.
+        click.echo(
+            f"Error: {display_path} (extension '{resolved.extension_name}') failed with "
+            f"exit code {code}.",
+            err=True,
+        )
+        sys.exit(code)
+
+
+def bypass_hint(display_path: str) -> str:
+    """How to run the built-in instead, in the shell the user is actually in.
+
+    `VAR=1 cmd` is not valid on cmd.exe or PowerShell, and this text is what
+    someone reads when an override has already broken something for them.
+    """
+    if os.name == "nt":
+        return f"set {DISABLE_OVERRIDES_ENV}=1 && graph-agents-cli {display_path}"
+    return f"{DISABLE_OVERRIDES_ENV}=1 graph-agents-cli {display_path}"
+
+
+def make_blocked_command(
+    *,
+    extension_name: str,
+    leaf_name: str,
+    display_path: str,
+    requires: str,
+    running: str,
+) -> click.Command:
+    """Build a Click command that refuses to run and says why.
+
+    Used when an extension declared `on_incompatible: error` and the running CLI is
+    outside its range. Falling back to the built-in is not safe for an override
+    — it would quietly do something else — so the command fails and points at
+    the ways out. Only this command is affected; the rest of the CLI works.
+    """
+    short = f"unavailable: extension '{extension_name}' needs graph-agents-cli {requires}"
+
+    @click.command(
+        name=leaf_name,
+        short_help=short,
+        help=(
+            f"`{display_path}` is provided by extension '{extension_name}', which "
+            f"requires graph-agents-cli {requires}; you are running {running}. The "
+            "extension asked to fail rather than fall back (`on_incompatible: "
+            "error`), because the built-in would do something different.\n\n"
+            "Fix it by updating the extension, removing it, or running the "
+            "built-in explicitly:\n"
+            f"  graph-agents-cli extension update {extension_name}\n"
+            f"  graph-agents-cli extension remove {extension_name}\n"
+            f"  {bypass_hint(display_path)}"
+        ),
+        context_settings={"ignore_unknown_options": True, "allow_extra_args": True},
+    )
+    @click.argument("extra_args", nargs=-1, type=click.UNPROCESSED)
+    def _blocked(extra_args: tuple[str, ...]) -> None:
+        raise click.ClickException(
+            f"{display_path!r} comes from extension {extension_name!r}, which requires "
+            f"graph-agents-cli {requires} (running {running}).\n"
+            f"  Update it:      graph-agents-cli extension update {extension_name}\n"
+            f"  Or remove it:   graph-agents-cli extension remove {extension_name}\n"
+            f"  Or bypass it:   {bypass_hint(display_path)}"
+        )
+
+    return _blocked
+
+
+def make_override_command(
+    contribution: ExtensionCommand,
+    *,
+    extension_name: str,
+    scope: str,
+    leaf_name: str,
+    display_path: str,
+    extension_root: Path,
+) -> click.Command:
+    """Build a Click command that runs an extension contribution.
+
+    `--help` is intercepted to describe the contribution; all other argv after
+    the command name passes verbatim to the run vector.
+    """
+    run_display = " ".join(contribution.run)
+    verb = "Overrides" if contribution.kind == "override" else "Adds"
+    help_text = (
+        f"{verb} `{display_path}` via extension '{extension_name}' ({scope} scope).\n\n"
+        f"{contribution.description}\n\n"
+        f"Runs: {run_display}\n\n"
+        "Argv after the command name passes through to the script verbatim.\n\n"
+        "To bypass extension overrides and run the built-in:\n"
+        f"  {bypass_hint(display_path)}"
+    )
+    short = f"{contribution.description or run_display}  [\u2191 {extension_name}]"
+
+    @click.command(
+        name=leaf_name,
+        short_help=short,
+        help=help_text,
+        context_settings={"ignore_unknown_options": True, "allow_extra_args": True},
+    )
+    @click.argument("extra_args", nargs=-1, type=click.UNPROCESSED)
+    def _cmd(extra_args: tuple[str, ...]) -> None:
+        cwd = find_project_root() or Path.cwd()
+        try:
+            code = run_extension_command(
+                contribution.run,
+                list(extra_args),
+                cwd=cwd,
+                extension_root=extension_root,
+            )
+        except FileNotFoundError as e:
+            raise click.ClickException(
+                f"Extension '{extension_name}' command {display_path!r} could not run: "
+                f"executable {contribution.run[0]!r} not found. "
+                "Check the extension's `run:` entry."
+            ) from e
+        sys.exit(code)
+
+    return _cmd

graph_agents_cli/extension/_paths.py

@@ -0,0 +1,91 @@
+# 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.
+
+"""Filesystem locations for extension scopes and caches."""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import re
+from collections.abc import Iterator
+from pathlib import Path
+
+from graph_agents_cli._project import find_project_root
+
+
+def user_config_root() -> Path:
+    # Roaming (APPDATA): config that should follow the user between machines.
+    if os.name == "nt":
+        base = os.environ.get("APPDATA")
+        if base:
+            return Path(base) / "graph-agents-cli"
+        return Path.home() / "AppData" / "Roaming" / "graph-agents-cli"
+    return Path.home() / ".config" / "graph-agents-cli"
+
+
+def vendored_extensions_dir(scope_root: Path) -> Path:
+    return scope_root / "extensions"
+
+
+def scope_root(scope: str) -> Path | None:
+    """Root for an install scope, or None for project scope outside a project.
+
+    Returning None rather than raising leaves the wording of "you need a project"
+    to the caller, since only the install commands can say what to do about it.
+    """
+    if scope == "user":
+        return user_config_root()
+    return find_project_root(Path.cwd())
+
+
+def installed_scope_roots() -> Iterator[tuple[str, Path]]:
+    """Yield (scope, root) for each resolvable scope, project before user.
+
+    Skips project scope when not inside a project, so callers can iterate both
+    scopes without repeating the "resolve root, skip if no project" boilerplate.
+    """
+    for scope in ("project", "user"):
+        root = scope_root(scope)
+        if root is not None:
+            yield scope, root
+
+
+def git_cache_root() -> Path:
+    """Return the shared git cache root directory."""
+    # Local (LOCALAPPDATA), not Roaming: re-clonable, and not worth syncing.
+    if os.name == "nt":
+        base = os.environ.get("LOCALAPPDATA")
+        root = Path(base) if base else Path.home() / "AppData" / "Local"
+        return root / "graph-agents-cli" / "git"
+    return Path.home() / ".cache" / "graph-agents-cli" / "git"
+
+
+def git_cache_dir_name(identity: str, url: str | None) -> str:
+    """Return the cache directory name for a repo, as a single path component.
+
+    ``identity`` is the readable ``org/repo``; ``url`` is the clone URL when the
+    reference was given as one, and None for the github.com shorthand.
+
+    A shorthand flattens to ``org__repo`` as it always has — the host is implied,
+    so the name is unambiguous. A URL cannot do that: two hosts can serve the
+    same ``org/repo``, and handing back one host's clone for the other's
+    extension would run the wrong code. So a URL's name carries a digest of the
+    URL, and the readable part is reduced to characters every filesystem accepts
+    (a URL holds ``:`` and ``/``, and Windows rejects both).
+    """
+    if url is None:
+        return identity.replace("/", "__")
+    slug = re.sub(r"[^A-Za-z0-9._-]+", "_", identity).strip("_") or "extension"
+    return f"{slug}__{hashlib.sha256(url.encode('utf-8')).hexdigest()[:12]}"

graph_agents_cli/extension/_refs.py

@@ -0,0 +1,193 @@
+# 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.
+
+"""Parse extension references for `graph-agents-cli extension add`."""
+
+from __future__ import annotations
+
+import dataclasses
+import os
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from urllib.parse import urlsplit
+
+# First-party public repository. Keep in sync with _tools.DEFAULT_SKILLS_SOURCE.
+FIRST_PARTY_REPO = "ss7172/graph-agents-cli"
+
+# Schemes an extension may be cloned from: the set `--agent` already accepts for
+# a template repo (scaffold/utils/remote_template.py), plus ssh://, which is how
+# a self-hosted host is usually reached, and file://, for a bare repo on a shared
+# mount — `local@` copies a working tree and cannot pin a commit against one.
+# `git://` is left out deliberately: it is unauthenticated, and an extension's
+# commands run arbitrary code on the machine that installs it.
+GIT_URL_SCHEMES = ("https", "http", "ssh", "file")
+
+_SCHEME_RE = re.compile(r"^([A-Za-z][A-Za-z0-9+.-]*)://")
+# scp-style, as offered by most hosts' "clone with SSH" button: git@host:org/repo.
+_SCP_RE = re.compile(r"^[A-Za-z0-9._-]+@[A-Za-z0-9._-]+:(?P<path>.+)$")
+# A reference written as a filesystem path: absolute, ./ or ../ relative, ~, or a
+# Windows drive. These are local sources even without the `local@` prefix
+# (`org/repo` stays the github.com shorthand: it is not written as a path).
+_PATH_RE = re.compile(r"^(?:/|\.{1,2}(?:[/\\]|$)|~|[A-Za-z]:[/\\])")
+
+
+class RefParseError(Exception):
+    """Raised when an extension reference cannot be parsed."""
+
+
+@dataclass(frozen=True)
+class ExtensionRef:
+    raw: str
+    kind: str  # "first_party" | "github" | "git" | "local"
+    repo: str | None
+    # Clone URL, set only for kind == "git". A github/first_party ref names a
+    # repo on github.com and lets the resolver build the URL from it.
+    url: str | None
+    local_path: Path | None
+    selector: str | None
+    ref: str | None
+
+
+def looks_like_path(value: str) -> bool:
+    """True for a reference written as a filesystem path rather than a repo."""
+    return bool(_PATH_RE.match(value))
+
+
+def anchor_local(ref: ExtensionRef, base: Path) -> ExtensionRef:
+    """``ref`` with a relative local path resolved against ``base`` (a scope root).
+
+    A recorded ``local@../team-tools`` is relative to the scope root it was
+    recorded in, so ``install``/``update`` find it from any working directory.
+    """
+    if ref.kind != "local" or ref.local_path is None or ref.local_path.is_absolute():
+        return ref
+    return dataclasses.replace(ref, local_path=base / ref.local_path)
+
+
+def _split_selector(value: str) -> tuple[str, str | None]:
+    if "#" in value:
+        base, selector = value.split("#", 1)
+        return base, (selector or None)
+    return value, None
+
+
+def _as_git_url(base: str) -> str | None:
+    """Return ``base`` unchanged if it is a clonable git URL, else None.
+
+    A string carrying a scheme git cannot clone is an error rather than a None,
+    so that `ftp://host/org/repo` is reported as a bad scheme instead of falling
+    through and being read as the `org/repo` shorthand `ftp:/host/org`.
+    """
+    scheme = _SCHEME_RE.match(base)
+    if scheme is not None:
+        if scheme.group(1).lower() not in GIT_URL_SCHEMES:
+            raise RefParseError(
+                f"unsupported scheme in {base!r}: use "
+                f"{', '.join(s + '://' for s in GIT_URL_SCHEMES)}, a 'git@host:org/repo' "
+                "URL, an 'org/repo' shorthand, or 'local@<path>'."
+            )
+        return base
+    return base if _SCP_RE.match(base) else None
+
+
+def _repo_identity(url: str) -> str:
+    """Return an ``org/repo`` label for a clone URL.
+
+    Used for messages, for the vendored directory's fallback name and for the
+    readable part of the cache directory. The clone itself always uses the URL
+    as given, so nothing here has to round-trip.
+    """
+    scp = _SCP_RE.match(url)
+    path = scp.group("path") if scp is not None else urlsplit(url).path
+    parts = [p for p in path.split("/") if p]
+    if not parts:
+        raise RefParseError(f"no repository path in {url!r}.")
+    if parts[-1].endswith(".git"):
+        parts[-1] = parts[-1].removesuffix(".git")
+    if not parts[-1]:
+        raise RefParseError(f"no repository name in {url!r}.")
+    return "/".join(parts[-2:])
+
+
+def parse_ref(raw: str, *, ref_override: str | None = None) -> ExtensionRef:
+    """Parse an extension reference string into a structured ExtensionRef.
+
+    Supported forms:
+      - ``soc2``                            first-party shorthand
+      - ``acme/acli-extensions``            any org/repo on github.com
+      - ``acme/acli-extensions#soc2``       org/repo with extension selector
+      - ``https://git.example.com/acme/acli-extensions``   any git host
+      - ``git@git.example.com:acme/acli-extensions``       the same, over ssh
+      - ``local@../my-extension``           local path
+      - ``../my-extension``, ``/abs/dir``, ``~/dir``   a local path without ``local@``
+      - pass ``ref_override`` to pin a branch, tag, or SHA
+    """
+    raw = (raw or "").strip()
+    if not raw:
+        raise RefParseError("empty extension reference.")
+
+    if raw.startswith("local@") or looks_like_path(raw):
+        body = raw[len("local@") :] if raw.startswith("local@") else raw
+        path_part, selector = _split_selector(body)
+        if not path_part:
+            raise RefParseError(f"local reference missing a path: {raw!r}.")
+        return ExtensionRef(
+            raw=raw if raw.startswith("local@") else f"local@{raw}",
+            kind="local",
+            repo=None,
+            url=None,
+            local_path=Path(os.path.expanduser(path_part)),
+            selector=selector,
+            ref=ref_override,
+        )
+
+    base, selector = _split_selector(raw)
+
+    # Checked before the org/repo shorthand: a URL contains slashes too, and
+    # would otherwise be silently mangled into one.
+    url = _as_git_url(base)
+    if url is not None:
+        return ExtensionRef(
+            raw=raw,
+            kind="git",
+            repo=_repo_identity(url),
+            url=url,
+            local_path=None,
+            selector=selector,
+            ref=ref_override,
+        )
+
+    if "/" in base:
+        return ExtensionRef(
+            raw=raw,
+            kind="github",
+            repo=base,
+            url=None,
+            local_path=None,
+            selector=selector,
+            ref=ref_override,
+        )
+
+    # First-party shorthand: a bare name selects that extension from the
+    # first-party repo (ss7172/graph-agents-cli).
+    return ExtensionRef(
+        raw=raw,
+        kind="first_party",
+        repo=FIRST_PARTY_REPO,
+        url=None,
+        local_path=None,
+        selector=selector or base,
+        ref=ref_override,
+    )