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

graph_agents_cli/extension/cmd_extension_group.py

@@ -0,0 +1,57 @@
+# 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.
+
+"""graph-agents-cli extension command group."""
+
+import click
+
+from graph_agents_cli._click import LazyGroup
+
+
+@click.group("extension", cls=LazyGroup)
+def extension_group():
+    """Manage graph-agents-cli extensions (experimental).
+
+    Experimental: the manifest schema and the command surface may still change
+    in a breaking way. Pin the CLI version if you depend on either.
+
+    \b
+    Subcommands:
+      add     Add an extension from a git reference or local path
+      list    List active extensions and the commands they contribute
+      update  Advance extension pins to the latest tracked ref
+      remove  Remove an installed extension
+    """
+
+
+extension_group.add_lazy_command(
+    "add",
+    "graph_agents_cli.extension.cmd_extension_add:cmd_add",
+    "Add an extension from a git reference or local path.",
+)
+extension_group.add_lazy_command(
+    "list",
+    "graph_agents_cli.extension.cmd_extension_list:cmd_list",
+    "List active extensions and the commands they contribute.",
+)
+extension_group.add_lazy_command(
+    "update",
+    "graph_agents_cli.extension.cmd_extension_update:cmd_update",
+    "Advance extension pins (re-resolve the tracked ref).",
+)
+extension_group.add_lazy_command(
+    "remove",
+    "graph_agents_cli.extension.cmd_extension_remove:cmd_remove",
+    "Remove an installed extension (checks project then user scope).",
+)

graph_agents_cli/extension/cmd_extension_list.py

@@ -0,0 +1,56 @@
+# 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.
+
+"""graph-agents-cli extension list command."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+from graph_agents_cli._project import find_project_root
+from graph_agents_cli.extension._loader import load_extension_set
+from graph_agents_cli.extension._paths import user_config_root
+
+
+@click.command("list")
+def cmd_list() -> None:
+    """List active extensions and the commands they contribute."""
+    project_root = find_project_root(Path.cwd())
+    ps = load_extension_set(project_root, user_config_root())
+    if not ps.extensions:
+        click.echo("No extensions installed.")
+        return
+    click.echo("Extensions:")
+    # A spec can appear more than once in ps.extensions (e.g. inline manifest plus a
+    # vendored copy from the same root); deduplicate for display.
+    seen: set[tuple[str, str]] = set()
+    for spec in ps.extensions:
+        if (spec.name, spec.scope) in seen:
+            continue
+        seen.add((spec.name, spec.scope))
+        cmds = ", ".join(sorted(c.name for c in spec.commands)) or "(none)"
+        line = f"  {spec.name}  {spec.scope}  (commands: {cmds})"
+        if spec.requires_agents_cli:
+            line += f"  requires: {spec.requires_agents_cli}"
+        click.echo(line)
+    for c in ps.conflict_rows():
+        click.echo(f"  ! conflict: {c}")
+    for inc in ps.incompatible_rows():
+        effect = "its commands will not run" if inc["mode"] == "error" else "applied anyway"
+        click.echo(
+            f"  ! incompatible: {inc['extension']} requires graph-agents-cli "
+            f"{inc['requires']} (running {inc['running']}) — {effect}"
+        )

graph_agents_cli/extension/cmd_extension_remove.py

@@ -0,0 +1,61 @@
+# 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.
+
+"""graph-agents-cli extension remove command."""
+
+from __future__ import annotations
+
+import shutil
+
+import click
+
+from graph_agents_cli._trust import require_confirmation
+from graph_agents_cli.extension._manifest import (
+    EXTENSIONS_FILE,
+    read_extension_entries,
+    remove_extension_entry,
+)
+from graph_agents_cli.extension._paths import (
+    installed_scope_roots,
+    vendored_extensions_dir,
+)
+from graph_agents_cli.extension._resolver import (
+    ResolverError,
+    validate_extension_name,
+)
+
+
+@click.command("remove")
+@click.argument("name")
+@require_confirmation("Remove this extension (deletes its vendored copy)?")
+def cmd_remove(name: str, auto_approve: bool) -> None:
+    """Remove an installed extension (checks project then user scope)."""
+    for scope, root in installed_scope_roots():
+        manifest = root / EXTENSIONS_FILE
+        entries = {e.name for e in read_extension_entries(manifest)}
+        if name not in entries:
+            continue
+        # The name comes from a committed manifest and decides what gets
+        # rmtree'd, so check it before touching anything.
+        try:
+            safe_name = validate_extension_name(name)
+        except ResolverError as e:
+            raise click.ClickException(f"Refusing to remove extension {name!r}: {e}") from e
+        remove_extension_entry(manifest, name)
+        extension_dir = vendored_extensions_dir(root) / safe_name
+        if extension_dir.exists():
+            shutil.rmtree(extension_dir)
+        click.secho(f"Removed extension {name!r} ({scope} scope).", fg="green")
+        return
+    raise click.ClickException(f"Extension {name!r} is not installed.")

graph_agents_cli/extension/cmd_extension_update.py

@@ -0,0 +1,195 @@
+# 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 extension update command."""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+import click
+
+from graph_agents_cli.__init__ import __version__
+from graph_agents_cli._trust import require_confirmation
+from graph_agents_cli.extension._loader import incompatible_spec
+from graph_agents_cli.extension._manifest import (
+    EXTENSIONS_FILE,
+    ExtensionEntry,
+    read_extension_entries,
+    upsert_extension_entry,
+)
+from graph_agents_cli.extension._paths import (
+    installed_scope_roots,
+    vendored_extensions_dir,
+)
+from graph_agents_cli.extension._refs import RefParseError, anchor_local, parse_ref
+from graph_agents_cli.extension._resolver import (
+    ResolverError,
+    expected_stamp,
+    materialize,
+    read_stamp,
+    resolve_sha,
+)
+from graph_agents_cli.extension._spec import ExtensionSpecError
+from graph_agents_cli.extension._trust import confirm_trust, stdin_is_interactive
+
+
+def _restore_pin(entry: ExtensionEntry, root: Path) -> None:
+    """Put the previously pinned copy back after refusing to advance to a new one."""
+    try:
+        materialize(
+            anchor_local(parse_ref(entry.source, ref_override=entry.sha), root),
+            entry.sha,
+            vendored_extensions_dir(root),
+            name=entry.name,
+        )
+    except ResolverError as e:
+        logging.warning("Could not restore the previous pin for %r: %s", entry.name, e)
+
+
+@click.command("update")
+@click.argument("name", required=False)
+@require_confirmation("Update extension(s) to the latest pinned ref?")
+def cmd_update(
+    name: str | None,
+    auto_approve: bool,
+) -> None:
+    """Advance extension pins (re-resolve the tracked ref).
+
+    Updates every installed extension when NAME is omitted. The tracked ref is
+    resolved first: an extension whose code did not change is reported as up
+    to date without a trust prompt. New third-party code needs your trust
+    (a prompt, or -y); without a terminal to ask on it keeps its pin and the
+    command exits 1.
+    """
+    updated: list[str] = []
+    current: list[str] = []
+    skipped: list[str] = []
+    untrusted: list[str] = []
+    for scope, root in installed_scope_roots():
+        manifest = root / EXTENSIONS_FILE
+        for entry in read_extension_entries(manifest):
+            if name is not None and entry.name != name:
+                continue
+            try:
+                ref = anchor_local(
+                    parse_ref(
+                        entry.source,
+                        # "HEAD" means "follow latest"; pass None so resolve_sha re-resolves.
+                        ref_override=(None if entry.ref == "HEAD" else entry.ref),
+                    ),
+                    root,
+                )
+            except RefParseError as e:
+                logging.warning("Skipping extension %r: %s", entry.name, e)
+                skipped.append(entry.name)
+                continue
+            try:
+                # Resolving reads the source (the remote's refs, or a local tree's
+                # hash); it runs none of the extension's code, so it needs no trust.
+                new_sha = resolve_sha(ref)
+                extension_dir = vendored_extensions_dir(root) / entry.name
+                if (
+                    new_sha == entry.sha
+                    and extension_dir.exists()
+                    and read_stamp(extension_dir) == expected_stamp(ref, new_sha)
+                ):
+                    # Same commit (or, for a local source, the same tree) as the
+                    # copy on disk: nothing to do, nothing to claim, nothing to trust.
+                    current.append(entry.name)
+                    continue
+            except ResolverError as e:
+                logging.warning("Could not update %r: %s", entry.name, e)
+                skipped.append(entry.name)
+                continue
+            if not confirm_trust(ref, auto_approve=auto_approve):
+                click.secho(
+                    f"Skipped {entry.name!r} (not trusted; the installed copy is kept).",
+                    fg="yellow",
+                )
+                skipped.append(entry.name)
+                untrusted.append(entry.name)
+                continue
+            try:
+                # name=entry.name pins the vendored dir to the stable id (see
+                # materialize) so an update survives an upstream rename.
+                materialize(
+                    ref,
+                    new_sha,
+                    vendored_extensions_dir(root),
+                    name=entry.name,
+                )
+            except ResolverError as e:
+                # One unreachable source must not abandon the others, or the
+                # command reports failure after already advancing a pin.
+                logging.warning("Could not update %r: %s", entry.name, e)
+                skipped.append(entry.name)
+                continue
+            # Compat gate: if the new pin declares an `error`-mode range the
+            # running CLI is outside, keep the old pin (restore its working
+            # copy) instead of advancing to a version that won't run here.
+            try:
+                spec = incompatible_spec(vendored_extensions_dir(root) / entry.name)
+            except ExtensionSpecError as e:
+                _restore_pin(entry, root)
+                click.secho(
+                    f"Skipped {entry.name!r}: the new version's manifest is not "
+                    f"valid ({e}); kept {entry.sha[:7]}.",
+                    fg="yellow",
+                )
+                skipped.append(entry.name)
+                continue
+            if spec is not None:
+                if spec.error_on_incompatible:
+                    _restore_pin(entry, root)
+                    click.secho(
+                        f"Skipped {entry.name!r}: new version requires graph-agents-cli "
+                        f"{spec.requires_agents_cli}, running {__version__} (kept {entry.sha[:7]}).",
+                        fg="yellow",
+                    )
+                    skipped.append(entry.name)
+                    continue
+                logging.warning(
+                    "Updated %r to a version requiring graph-agents-cli %s (running %s).",
+                    entry.name,
+                    spec.requires_agents_cli,
+                    __version__,
+                )
+            upsert_extension_entry(
+                manifest,
+                ExtensionEntry(
+                    name=entry.name,
+                    source=entry.source,
+                    ref=entry.ref,
+                    sha=new_sha,
+                    scope=scope,
+                ),
+            )
+            updated.append(entry.name)
+    if not updated and not skipped and not current:
+        raise click.ClickException(
+            f"No extension named {name!r} found." if name else "No extensions to update."
+        )
+    if updated:
+        click.secho(f"Updated: {', '.join(updated)}.", fg="green")
+    if current:
+        click.secho(f"Already up to date: {', '.join(current)}.", dim=True)
+    if untrusted and not stdin_is_interactive():
+        # Nobody could answer: a script must not take "kept the old pin" for success.
+        raise click.ClickException(
+            f"Not updated: {', '.join(untrusted)} changed and needs your trust; rerun with -y "
+            "to trust the new code."
+        )

graph_agents_cli/info/__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/info/cmd_info.py

@@ -0,0 +1,222 @@
+# 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.
+
+"""Show project configuration, paths, and CLI version."""
+
+from __future__ import annotations
+
+import platform
+from pathlib import Path
+from typing import Any
+
+import click
+
+import graph_agents_cli as _cli_pkg
+from graph_agents_cli.__init__ import __version__
+from graph_agents_cli._build import BuildInfo, current_build
+from graph_agents_cli._output import emit
+from graph_agents_cli._project import (
+    ProjectConfig,
+    check_cli_version,
+    find_project_root,
+    read_project_config,
+)
+from graph_agents_cli._skills_check import get_installed_skills, skills_listing_skipped
+from graph_agents_cli.extension._loader import ExtensionSet, load_extension_set
+from graph_agents_cli.extension._paths import user_config_root
+
+_CLI_INSTALL_PATH = str(Path(_cli_pkg.__file__).parent)
+
+
+def _print_extensions(extension_set: ExtensionSet) -> None:
+    rows = extension_set.command_rows()
+    conflicts = extension_set.conflict_rows()
+    incompatible = extension_set.incompatible_rows()
+    if not rows and not conflicts and not incompatible:
+        return
+    click.echo()
+    click.echo("Extensions (experimental):")
+    for r in rows:
+        line = (
+            f"  {r['command']}  ({r['kind']}, {r['scope']}) "
+            f"<- {r['extension']}: {' '.join(r['run'])}"
+        )
+        if r.get("requires"):
+            line += f"  [requires graph-agents-cli {r['requires']}]"
+        if r.get("blocked"):
+            line += "  [BLOCKED: out of range, this command will not run]"
+        click.echo(line)
+    for c in conflicts:
+        click.echo(f"  ! conflict: {c} (claimed by multiple same-scope extensions)")
+    for inc in incompatible:
+        click.echo(
+            f"  ! incompatible: {inc['extension']} requires graph-agents-cli "
+            f"{inc['requires']} (running {inc['running']})"
+        )
+
+
+def _print_installed_skills(skills: list[dict] | None, skipped: str | None = None) -> None:
+    """Print installed skills summary."""
+    if skipped:
+        click.echo(f"Installed skills:   not listed ({skipped} skips `npx skills list`)")
+        return
+    if skills is None:
+        click.echo("Installed skills:   (could not query)")
+        return
+    if not skills:
+        click.echo("Installed skills:   none")
+        return
+    # Group by scope
+    by_scope: dict[str, list[str]] = {}
+    for s in skills:
+        scope = s.get("scope", "unknown")
+        by_scope.setdefault(scope, []).append(s["name"])
+    for scope, names in sorted(by_scope.items()):
+        click.echo(f"Installed skills:   {len(names)} ({scope})")
+        for name in sorted(names):
+            click.echo(f"  - {name}")
+
+
+def build_info_json(build: BuildInfo) -> dict[str, Any]:
+    """The ``cli_build`` block of ``info --json``."""
+    return {
+        "id": build.id,
+        "commit": build.commit,
+        "dirty": build.dirty,
+        "release": build.is_release,
+    }
+
+
+def project_info(project_root: Path, cfg: ProjectConfig) -> dict[str, Any]:
+    """The project block of ``info``: what the manifest records."""
+    return {
+        "project_root": str(project_root),
+        "project_name": cfg.project_name,
+        "cli_version": cfg.cli_version,
+        "cli_build": cfg.cli_build if isinstance(cfg.cli_build, dict) else None,
+        "language": cfg.language,
+        "base_template": cfg.base_template,
+        "agent_directory": cfg.agent_directory,
+        "runtime": cfg.runtime,
+        "model_provider": cfg.model_provider,
+        "model": cfg.model,
+        "checkpointer": cfg.checkpointer,
+        "deployment_target": cfg.deployment_target,
+        "registry": cfg.registry,
+        "cd": cfg.cd,
+        "auth_policy": cfg.auth_policy,
+        "auth_policy_implemented": cfg.auth_policy_implemented,
+        "api_policy_file": cfg.api_policy_file,
+        "process": cfg.process,
+        "environments": cfg.environments,
+        "secret_keys": cfg.secret_keys,
+        "secrets_owner": cfg.secrets.owner,
+    }
+
+
+def _scaffolded_with(cfg: ProjectConfig) -> str:
+    """The version and, when the manifest records it, the build that rendered the project."""
+    version = cfg.cli_version or "(unknown)"
+    build = cfg.cli_build.get("id") if isinstance(cfg.cli_build, dict) else None
+    if not build:
+        return f"{version} (no build recorded)" if cfg.cli_version else version
+    return version if build == cfg.cli_version else f"{version} (build {build})"
+
+
+def _print_project(project_root: Path, cfg: ProjectConfig) -> None:
+    click.echo()
+    click.echo(f"Project root:       {project_root}")
+    click.echo(f"Project name:       {cfg.project_name or '(not set)'}")
+    click.echo(f"Scaffolded with:    {_scaffolded_with(cfg)}")
+    click.echo(f"Base template:      {cfg.base_template}")
+    click.echo(f"Agent directory:    {cfg.agent_directory}")
+    click.echo(f"Runtime:            {cfg.runtime}")
+    click.echo(f"Model provider:     {cfg.model_provider}")
+    click.echo(f"Model:              {cfg.model}")
+    click.echo(f"Checkpointer:       {cfg.checkpointer}")
+    click.echo(f"Deployment target:  {cfg.deployment_target}")
+    click.echo(f"Registry:           {cfg.registry or '(none)'}")
+    click.echo(f"CD:                 {cfg.cd}")
+    implemented = "" if cfg.auth_policy_implemented else "  (stub, not yet implemented)"
+    click.echo(f"Auth policy:        {cfg.auth_policy}{implemented}")
+    click.echo(f"API policy:         {cfg.api_policy_file or 'none'}")
+    click.echo(f"Process:            {cfg.process or 'none'}")
+    if cfg.environments:
+        click.echo("Environments:")
+        for env_name, env in cfg.environments.items():
+            context = env.get("context") or "(current context)"
+            click.echo(f"  - {env_name}: namespace={env.get('namespace')} context={context}")
+    else:
+        click.echo("Environments:       none")
+
+
+@click.command()
+@click.option("--json", "as_json", is_flag=True, default=False, help="Output as JSON.")
+def cmd_info(as_json: bool) -> None:
+    """Show project configuration, paths, and CLI version.
+
+    The installed skills come from `npx skills list`, which is not run (and
+    reported as not listed) with GRAPH_AGENTS_CLI_NO_UPDATE_CHECK=1 or in CI.
+    """
+    installed_skills = get_installed_skills()
+    # Why there is no listing: the opt-out, not a failure (None from a failed query too).
+    skills_skipped = skills_listing_skipped() if installed_skills is None else None
+    project_root = find_project_root()
+    os_info = platform.platform()
+    extension_set = load_extension_set(project_root, user_config_root())
+
+    build = current_build()
+    base: dict[str, Any] = {
+        "cli_version": __version__,
+        "cli_build": build_info_json(build),
+        "cli_install_path": _CLI_INSTALL_PATH,
+        "os_info": os_info,
+        "installed_skills": installed_skills,
+        "installed_skills_skipped": skills_skipped,
+        "extensions": extension_set.command_rows(),
+        "extension_conflicts": extension_set.conflict_rows(),
+        "extension_incompatible": extension_set.incompatible_rows(),
+    }
+
+    if project_root is None:
+        if as_json:
+            emit({**base, "project": None})
+        else:
+            click.echo(f"CLI version:        {__version__}")
+            click.echo(f"CLI build:          {build.describe()}")
+            click.echo(f"CLI install path:   {_CLI_INSTALL_PATH}")
+            click.echo(f"OS info:            {os_info}")
+            _print_installed_skills(installed_skills, skills_skipped)
+            _print_extensions(extension_set)
+            click.echo()
+            click.echo("No agent project found in the current directory or any parent.")
+            click.echo("  Run this command from within a project, or create one:")
+            click.echo("    graph-agents-cli create my-agent")
+        return
+
+    cfg = read_project_config(str(project_root))
+    check_cli_version(cfg)
+
+    if as_json:
+        emit({**base, "project": project_info(project_root, cfg)})
+        return
+
+    click.echo(f"CLI version:        {__version__}")
+    click.echo(f"CLI build:          {build.describe()}")
+    click.echo(f"CLI install path:   {_CLI_INSTALL_PATH}")
+    click.echo(f"OS info:            {os_info}")
+    _print_installed_skills(installed_skills, skills_skipped)
+    _print_project(project_root, cfg)
+    _print_extensions(extension_set)

graph_agents_cli/infra/__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 infra commands."""