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

graph_agents_cli/extension/_spec.py

@@ -0,0 +1,253 @@
+# 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 and validate graph-agents-cli-extension.yaml (schema: graph-agents-cli-extension/v1alpha1)."""
+
+from __future__ import annotations
+
+import difflib
+import logging
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path, PurePosixPath
+from types import UnionType
+from typing import Annotated, Any, Literal, Union, get_args, get_origin
+
+from pydantic import (
+    BaseModel,
+    BeforeValidator,
+    ConfigDict,
+    Field,
+    ValidationError,
+    model_validator,
+)
+
+from graph_agents_cli.extension._compat import validate_range
+
+# The manifest format version, tracked separately from the graph-agents-cli version.
+# A second format would widen `ExtensionManifest.schema_version` to a Union.
+# Alpha while the extension system is experimental: the format may still change
+# in a breaking way, and `v1` is reserved for the point it stops doing so.
+V1ALPHA1 = "graph-agents-cli-extension/v1alpha1"
+EXTENSION_FILE = "graph-agents-cli-extension.yaml"
+
+
+class ExtensionSpecError(Exception):
+    """Raised on structural errors in an extension spec."""
+
+
+# --- Wire models -------------------------------------------------------------
+# These mirror graph-agents-cli-extension.yaml and generate the published JSON Schema.
+# `extra="forbid"` so a typo like `reqires:` is an error rather than a section
+# that silently does nothing.
+
+
+def _reject_bool(value: Any) -> Any:
+    """YAML 1.1 reads `yes`/`on` as True, which is not a number in JSON Schema."""
+    if isinstance(value, bool):
+        raise ValueError('expected a version range, e.g. ">=1.3,<2"')
+    return value
+
+
+class _Strict(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    @model_validator(mode="before")
+    @classmethod
+    def _empty_key_means_absent(cls, data: Any) -> Any:
+        """`commands:` with nothing under it is how authors comment a section out.
+
+        Only for keys this model knows: dropping unknown ones would hide the
+        typo that `extra="forbid"` exists to catch.
+        """
+        if not isinstance(data, dict):
+            return data
+        known = {f.alias or n for n, f in cls.model_fields.items()}
+        return {k: v for k, v in data.items() if v is not None or k not in known}
+
+
+class CommandEntry(_Strict):
+    run: list[str] = Field(min_length=1)
+    description: str = ""
+
+
+class Commands(_Strict):
+    override: dict[str, CommandEntry] = Field(default_factory=dict)
+    add: dict[str, CommandEntry] = Field(default_factory=dict)
+
+
+class Requires(_Strict):
+    # `agents_cli: 1.2` is natural YAML and arrives as a number; the range is
+    # validated semantically below, and a bad one is dropped rather than fatal.
+    agents_cli: Annotated[str | float | None, BeforeValidator(_reject_bool)] = None
+    on_incompatible: Literal["warn", "error"] = "warn"
+
+
+class ExtensionManifest(_Strict):
+    """`graph-agents-cli-extension.yaml` as written on disk."""
+
+    # This is the v1alpha1 document, so it accepts only v1alpha1: an editor
+    # validating against it has to agree with the loader, which rejects
+    # anything else.
+    schema_version: Literal["graph-agents-cli-extension/v1alpha1"] = Field(
+        default=V1ALPHA1, alias="schema"
+    )
+    name: str | None = Field(default=None, min_length=1)
+    description: str = ""
+    requires: Requires | None = None
+    commands: Commands = Field(default_factory=Commands)
+
+
+def _describe(error: Mapping[str, Any]) -> str:
+    """One validation error as a line an extension author can act on."""
+    loc = ".".join(str(part) for part in error["loc"] if part != "[key]")
+    if error["type"] == "extra_forbidden":
+        key = str(error["loc"][-1])
+        near = difflib.get_close_matches(key, _known_keys(error["loc"][:-1]), n=1)
+        hint = f" (did you mean {near[0]!r}?)" if near else ""
+        return f"unknown key {loc!r}{hint}"
+    # Model class names mean nothing to someone editing YAML.
+    msg = re.sub(r" or instance of \w+", "", error["msg"])
+    return f"{loc or '(root)'}: {msg}"
+
+
+def _known_keys(loc: tuple[Any, ...]) -> list[str]:
+    """Field names of the manifest model at `loc`, for did-you-mean hints.
+
+    A container's key or index consumes a `loc` part without changing the model,
+    so `commands.add.<name>.<typo>` still resolves to CommandEntry's fields.
+    """
+    current: Any = ExtensionManifest
+    for part in loc:
+        fields = getattr(current, "model_fields", {})
+        field = fields.get(str(part)) or next(
+            (f for f in fields.values() if f.alias == str(part)), None
+        )
+        if field is None:
+            # This part is a dict key or a list index, not a field name.
+            nested = _model_in(current)
+            if nested is None:
+                return []
+            current = nested
+            continue
+        current = _unwrap_optional(field.annotation)
+    return [f.alias or n for n, f in getattr(current, "model_fields", {}).items()]
+
+
+def _unwrap_optional(annotation: Any) -> Any:
+    """`X | None` -> X, leaving `dict[str, X]` and `list[X]` for the key/index step."""
+    if get_origin(annotation) not in (Union, UnionType):
+        return annotation
+    args = [a for a in get_args(annotation) if a is not type(None)]
+    return args[0] if len(args) == 1 else annotation
+
+
+def _model_in(annotation: Any) -> Any:
+    """The model a container holds, e.g. dict[str, CommandEntry] -> CommandEntry."""
+    for arg in getattr(annotation, "__args__", ()):
+        if isinstance(arg, type) and issubclass(arg, BaseModel):
+            return arg
+    return None
+
+
+@dataclass(frozen=True)
+class ExtensionCommand:
+    name: str  # dotted command path, e.g. "deploy" or "eval.generate"
+    run: tuple[str, ...]
+    description: str
+    kind: str  # "override" | "add"
+
+
+@dataclass(frozen=True)
+class ExtensionSpec:
+    name: str
+    description: str
+    root: Path
+    commands: tuple[ExtensionCommand, ...]
+    # Install scope ("user" | "project"), stamped by the loader at discovery —
+    # it comes from where the extension was found, not from the manifest.
+    scope: str = ""
+    # Optional author-declared graph-agents-cli compatibility range (e.g. ">=1.1,<2").
+    requires_agents_cli: str | None = None
+    # The manifest's "warn" | "error", resolved at parse time. Only two states
+    # exist and the manifest model already validates them, so the rest of the
+    # CLI reads a bool rather than re-comparing strings.
+    error_on_incompatible: bool = False
+
+
+def _to_command(name: str, entry: CommandEntry, kind: str) -> ExtensionCommand:
+    _warn_if_script_entrypoint(name, kind, entry.run[0])
+    return ExtensionCommand(
+        name=name, run=tuple(entry.run), description=entry.description, kind=kind
+    )
+
+
+# Suffixes that are run by an interpreter, not executed directly on Windows.
+_SCRIPT_SUFFIXES = frozenset({".py", ".sh", ".js", ".ts", ".rb", ".pl"})
+
+
+def _warn_if_script_entrypoint(name: str, kind: str, first_token: str) -> None:
+    """Executed without a shell: a bare script needs +x and a shebang on POSIX, and never runs on Windows."""
+    if PurePosixPath(first_token).suffix in _SCRIPT_SUFFIXES:
+        logging.warning(
+            "commands.%s.%s: `run` starts with the script %r; prefix an "
+            'interpreter (e.g. ["uv", "run", "python", %r]) so it also '
+            "runs on Windows.",
+            kind,
+            name,
+            first_token,
+            first_token,
+        )
+
+
+def parse_extension_spec(data: dict[str, Any], *, root: Path, default_name: str) -> ExtensionSpec:
+    """Raises ExtensionSpecError on any structural problem; the caller decides whether that is fatal."""
+    try:
+        manifest = ExtensionManifest.model_validate(data)
+    except ValidationError as e:
+        problems = "\n  - ".join(_describe(err) for err in e.errors())
+        if len(e.errors()) > 1:
+            problems = f"\n  - {problems}"
+        raise ExtensionSpecError(problems) from e
+
+    commands = [
+        _to_command(name, entry, kind)
+        for kind in ("override", "add")
+        for name, entry in getattr(manifest.commands, kind).items()
+    ]
+    requires_agents_cli, error_on_incompatible = _parse_requires(manifest.requires)
+    return ExtensionSpec(
+        name=manifest.name or default_name,
+        description=manifest.description,
+        root=root,
+        commands=tuple(commands),
+        requires_agents_cli=requires_agents_cli,
+        error_on_incompatible=error_on_incompatible,
+    )
+
+
+def _parse_requires(requires: Requires | None) -> tuple[str | None, bool]:
+    """An unparseable range is warned about and dropped: a bad compat hint must not make an otherwise-valid extension unloadable."""
+    if requires is None:
+        return None, False
+    raw_range = None if requires.agents_cli is None else str(requires.agents_cli)
+    if raw_range is not None and not validate_range(raw_range):
+        logging.warning(
+            "requires.agents_cli %r is not a valid version range; ignoring the "
+            "range (the extension still loads).",
+            raw_range,
+        )
+        raw_range = None
+    return raw_range, requires.on_incompatible == "error"

graph_agents_cli/extension/_sync.py

@@ -0,0 +1,102 @@
+# 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.
+
+"""Re-materialize vendored extension working copies from pinned SHAs."""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+import click
+
+from graph_agents_cli.__init__ import __version__
+from graph_agents_cli.extension._loader import incompatible_spec
+from graph_agents_cli.extension._manifest import (
+    EXTENSIONS_FILE,
+    read_extension_entries,
+)
+from graph_agents_cli.extension._paths import user_config_root, 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,
+)
+from graph_agents_cli.extension._spec import ExtensionSpecError
+
+
+def _scope_roots(project_root: Path | None) -> list[Path]:
+    """Roots to sync, project first. The scope label is not needed: both scopes
+    store the list under the same filename."""
+    roots = [] if project_root is None else [project_root]
+    roots.append(user_config_root())
+    return roots
+
+
+def sync_extensions(project_root: Path | None) -> list[str]:
+    """Ensure every recorded extension is vendored on disk.
+
+    Reports what it restored and returns those names.
+    """
+    restored: list[str] = []
+    for scope_root in _scope_roots(project_root):
+        manifest = scope_root / EXTENSIONS_FILE
+        for entry in read_extension_entries(manifest):
+            extension_dir = vendored_extensions_dir(scope_root) / entry.name
+            try:
+                ref = anchor_local(parse_ref(entry.source, ref_override=entry.sha), scope_root)
+                # Re-materialize when the copy is missing OR no longer matches
+                # its source: a bumped pin, a partial copy, or — for a local
+                # path, whose source is a working tree rather than a commit —
+                # any edit made to it since the copy was taken.
+                if extension_dir.exists() and read_stamp(extension_dir) == expected_stamp(
+                    ref, entry.sha
+                ):
+                    continue
+                # name=entry.name pins the vendored dir to the stable id (see
+                # materialize) so a restore survives an upstream rename.
+                materialize(
+                    ref,
+                    entry.sha,
+                    vendored_extensions_dir(scope_root),
+                    name=entry.name,
+                )
+                restored.append(entry.name)
+                # Never block a restore (that would brick `install`); just warn
+                # if the restored pin is out of range for the running CLI.
+                try:
+                    stale = incompatible_spec(extension_dir)
+                except ExtensionSpecError as e:
+                    # Restore must never fail: it is how a bad pin gets fixed.
+                    logging.warning("%s: %s.", extension_dir, e)
+                    stale = None
+                if stale is not None:
+                    logging.warning(
+                        "Restored extension %r requires graph-agents-cli %s but running %s.",
+                        entry.name,
+                        stale.requires_agents_cli,
+                        __version__,
+                    )
+            except (ResolverError, RefParseError) as e:
+                logging.warning(
+                    "Could not restore extension %r from %s: %s",
+                    entry.name,
+                    entry.source,
+                    e,
+                )
+    if restored:
+        click.echo(f"Restored extensions: {', '.join(restored)}")
+    return restored

graph_agents_cli/extension/_trust.py

@@ -0,0 +1,58 @@
+# 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.
+
+"""Consent gate for running third-party extension code."""
+
+from __future__ import annotations
+
+import sys
+
+import click
+
+from graph_agents_cli.extension._refs import ExtensionRef
+
+NO_TERMINAL_HINT = (
+    "  Not asking: stdin is not a terminal. Pass -y to trust this extension non-interactively."
+)
+
+
+def stdin_is_interactive() -> bool:
+    """True when a person can answer a prompt (stdin is a terminal)."""
+    try:
+        return sys.stdin is not None and sys.stdin.isatty()
+    except (AttributeError, ValueError):  # replaced or closed stdin
+        return False
+
+
+def confirm_trust(ref: ExtensionRef, *, auto_approve: bool) -> bool:
+    """Return True if it's OK to install/run this extension's code.
+
+    First-party extensions are trusted. Everything else prompts unless
+    `auto_approve`. Without a terminal to answer on (CI, a pipe, `< /dev/null`)
+    it does not prompt, which would abort or block: it says to pass -y and
+    returns False.
+    """
+    if ref.kind == "first_party" or auto_approve:
+        return True
+    click.echo()
+    click.secho(
+        f"  Extension source {ref.raw!r} is third-party. It can run arbitrary code "
+        "on your machine when its commands are invoked.",
+        fg="yellow",
+    )
+    if not stdin_is_interactive():
+        click.secho(NO_TERMINAL_HINT, fg="yellow")
+        return False
+    return click.confirm("  Install and trust this extension?", default=False)

graph_agents_cli/extension/cmd_extension_add.py

@@ -0,0 +1,259 @@
+# 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 add command."""
+
+from __future__ import annotations
+
+import logging
+import os
+import shutil
+from pathlib import Path
+
+import click
+
+from graph_agents_cli.__init__ import __version__
+from graph_agents_cli._project import NotInProjectError, find_project_root
+from graph_agents_cli._trust import require_confirmation
+from graph_agents_cli.extension._compat import is_compatible
+from graph_agents_cli.extension._loader import (
+    RECOVERY_COMMANDS,
+    load_extension_set,
+    load_extension_spec,
+)
+from graph_agents_cli.extension._manifest import (
+    EXTENSIONS_FILE,
+    ExtensionEntry,
+    read_extension_entries,
+    upsert_extension_entry,
+)
+from graph_agents_cli.extension._paths import (
+    scope_root,
+    user_config_root,
+    vendored_extensions_dir,
+)
+from graph_agents_cli.extension._refs import (
+    ExtensionRef,
+    RefParseError,
+    anchor_local,
+    parse_ref,
+)
+from graph_agents_cli.extension._resolver import ResolverError, materialize, resolve_sha
+from graph_agents_cli.extension._spec import (
+    EXTENSION_FILE,
+    ExtensionSpec,
+    ExtensionSpecError,
+)
+from graph_agents_cli.extension._trust import confirm_trust
+
+
+def _recorded_local_source(ref: ExtensionRef, root: Path, scope: str) -> str:
+    """The ``local@`` source to record, resolvable from the scope root later.
+
+    ``install`` and ``update`` resolve a relative local source against the scope
+    root, so the path typed here (relative to wherever the command ran) is
+    rewritten: relative to the project root for project scope, which keeps the
+    committed entry portable, absolute for user scope.
+    """
+    absolute = (ref.local_path or Path.cwd()).resolve()
+    path = absolute.as_posix()
+    if scope == "project":
+        try:
+            path = Path(os.path.relpath(absolute, root.resolve())).as_posix()
+        except ValueError:  # another drive on Windows: only an absolute path works
+            pass
+    selector = f"#{ref.selector}" if ref.selector else ""
+    return f"local@{path}{selector}"
+
+
+def _resolve_hint(reference: str, ref: ExtensionRef) -> str:
+    """A pointer to ``local@`` when a repo shorthand also names a local directory."""
+    if ref.kind in ("github", "first_party") and Path(reference.split("#", 1)[0]).is_dir():
+        return (
+            f"\n  {reference!r} is also a local directory: to install it from disk, use "
+            f"local@{reference} (or ./{reference})."
+        )
+    return ""
+
+
+def _parse_or_fail(extension_dir: Path) -> ExtensionSpec | None:
+    """Parse the vendored manifest, turning a bad one into a failed install.
+
+    Parsed once here and handed to both gates, so a manifest is not read twice
+    and the two cannot disagree about what it says.
+    """
+    try:
+        return load_extension_spec(extension_dir)
+    except ExtensionSpecError as e:
+        raise click.ClickException(
+            f"{EXTENSION_FILE} is not valid: {e}\nNothing was installed."
+        ) from e
+
+
+def _check_compat(spec: ExtensionSpec | None) -> None:
+    """Gate a freshly vendored extension against the running CLI version.
+
+    `error` mode raises so the install fails; `warn` mode logs and proceeds.
+    This is the deliberate install gate, the only place an incompatibility
+    hard-fails; at runtime it only ever warns.
+    """
+    if (
+        spec is None
+        or not spec.requires_agents_cli
+        or is_compatible(__version__, spec.requires_agents_cli)
+    ):
+        return
+    msg = (
+        f"Extension requires graph-agents-cli {spec.requires_agents_cli} but you're "
+        f"running {__version__}."
+    )
+    if spec.error_on_incompatible:
+        raise click.ClickException(
+            f"{msg} Not installing (on_incompatible: error). "
+            "Pin a compatible ref with --ref, or upgrade the CLI."
+        )
+    logging.warning("%s Installing anyway (on_incompatible: warn).", msg)
+
+
+def _check_reserved_commands(spec: ExtensionSpec | None) -> None:
+    """Refuse an extension that claims a command used to repair extensions.
+
+    Caught at install because that is where a human can read why. The loader
+    ignores such a claim too, for manifests edited by hand.
+    """
+    if spec is None:
+        return
+    reserved = sorted({c.name for c in spec.commands} & RECOVERY_COMMANDS)
+    if reserved:
+        raise click.ClickException(
+            f"Extension claims {', '.join(repr(r) for r in reserved)}, which "
+            "cannot be overridden: these are how you repair or remove an "
+            "extension, so an extension owning them could own its own uninstall."
+        )
+
+
+def _check_command_conflicts(
+    project_root: Path | None, spec: ExtensionSpec | None, scope: str
+) -> None:
+    """Raise if the candidate claims a command *another* extension already owns.
+
+    Re-adding the same name at the same scope is a replace, which is how a pin
+    moves, so the candidate must not be read as conflicting with the copy it is
+    about to overwrite.
+    """
+    if spec is None:
+        return
+    installed = load_extension_set(project_root, user_config_root())
+    clashes = sorted(
+        (contribution.name, owner.extension_name)
+        for contribution in spec.commands
+        if (owner := installed.commands.get(contribution.name)) is not None
+        and owner.scope == scope
+        and owner.extension_name != spec.name
+    )
+    if clashes:
+        raise click.ClickException(
+            "Command conflict(s) with an already-installed extension: "
+            + ", ".join(f"{cmd} (owned by {owner!r})" for cmd, owner in clashes)
+            + ". Remove or rename the conflicting extension."
+        )
+
+
+@click.command("add")
+@click.argument("reference")
+@click.option(
+    "--global",
+    "global_",
+    is_flag=True,
+    default=False,
+    help=(
+        "Install for all projects (user scope, global/org-wide). Default is "
+        "project scope (committed to this repo only), so the extension cannot "
+        "affect your other projects."
+    ),
+)
+@click.option("--ref", "ref_override", default=None, help="Pin a branch, tag, or SHA.")
+@require_confirmation("Install this extension?")
+def cmd_add(
+    reference: str,
+    global_: bool,
+    ref_override: str | None,
+    auto_approve: bool,
+) -> None:
+    """Add an extension from a git reference or local path."""
+    scope = "user" if global_ else "project"
+    try:
+        ref = parse_ref(reference, ref_override=ref_override)
+    except RefParseError as e:
+        raise click.ClickException(str(e)) from e
+
+    root = scope_root(scope)
+    if root is None:
+        # Checked before the trust prompt: nothing to confirm when it cannot install.
+        raise NotInProjectError(
+            "No graph-agents-cli-manifest.yaml found. Run inside a project (extensions "
+            "install at project scope by default), or pass --global to install "
+            "for all projects."
+        )
+
+    if not confirm_trust(ref, auto_approve=auto_approve):
+        raise click.ClickException("Aborted: extension not trusted.")
+
+    project_root = root if scope == "project" else find_project_root(Path.cwd())
+
+    source = ref.raw
+    if ref.kind == "local":
+        # Resolved against the current directory now; recorded against the root.
+        ref = anchor_local(ref, Path.cwd())
+        source = _recorded_local_source(ref, root, scope)
+
+    try:
+        sha = resolve_sha(ref)
+        name, extension_dir = materialize(ref, sha, vendored_extensions_dir(root))
+    except ResolverError as e:
+        error = click.ClickException(f"{e}{_resolve_hint(reference, ref)}")
+        # A local path that is not an extension is a configuration error (3);
+        # git or the network failing to resolve a repo is a tool failure (2).
+        error.exit_code = 3 if ref.kind == "local" else 2
+        raise error from e
+
+    # Every gate runs before anything is recorded, so a refused install leaves
+    # no entry to roll back. The vendored copy has to exist first (the gates read
+    # its manifest), so that is the only thing to clean up.
+    try:
+        spec = _parse_or_fail(extension_dir)
+        _check_compat(spec)
+        _check_reserved_commands(spec)
+        _check_command_conflicts(project_root, spec, scope)
+    except click.ClickException as e:
+        if extension_dir.exists():
+            shutil.rmtree(extension_dir)
+        # Removing the copy of an extension that is still recorded leaves the
+        # entry pointing at nothing, and its commands silently fall back to the
+        # built-ins until the copy is back.
+        if any(entry.name == name for entry in read_extension_entries(root / EXTENSIONS_FILE)):
+            raise click.ClickException(
+                f"{e.format_message()}\n"
+                f"  {name!r} is still recorded; restore its copy with: graph-agents-cli install"
+            ) from e
+        raise
+
+    entry = ExtensionEntry(name=name, source=source, ref=ref.ref or "HEAD", sha=sha, scope=scope)
+    upsert_extension_entry(root / EXTENSIONS_FILE, entry)
+
+    click.secho(f"Added extension {name!r} ({scope} scope) from {source}.", fg="green")
+    click.secho(
+        "Extensions are experimental; the manifest format may still change.",
+        dim=True,
+    )