specfact-cli 0.37.5__tar.gz → 0.38.1__tar.gz

{specfact_cli-0.37.5 → specfact_cli-0.38.1}/.gitignore

@@ -23,6 +23,7 @@ __pycache__/
 *.pyo
 *.pyd
 *.py.bak
+.cache/
 
 # ChromaDB data files
 data/
@@ -147,3 +148,5 @@ Language.ml
 Language.mli
 
 .artifacts
+registry.bak/
+.pr-body.md

{specfact_cli-0.37.5 → specfact_cli-0.38.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specfact-cli
-Version: 0.37.5
+Version: 0.38.1
 Summary: The swiss knife CLI for agile DevOps teams. Keep backlog, specs, tests, and code in sync with validation and contract enforcement for new projects and long-lived codebases.
 Project-URL: Homepage, https://github.com/nold-ai/specfact-cli
 Project-URL: Repository, https://github.com/nold-ai/specfact-cli.git

{specfact_cli-0.37.5 → specfact_cli-0.38.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "specfact-cli"
-version = "0.37.5"
+version = "0.38.1"
 description = "The swiss knife CLI for agile DevOps teams. Keep backlog, specs, tests, and code in sync with validation and contract enforcement for new projects and long-lived codebases."
 readme = "README.md"
 requires-python = ">=3.11"

{specfact_cli-0.37.5 → specfact_cli-0.38.1}/src/__init__.py

@@ -3,4 +3,4 @@ SpecFact CLI - Spec→Contract→Sentinel tool for contract-driven development.
 """
 
 # Package version: keep in sync with pyproject.toml, setup.py, src/specfact_cli/__init__.py
-__version__ = "0.37.5"
+__version__ = "0.38.1"

{specfact_cli-0.37.5 → specfact_cli-0.38.1}/src/specfact_cli/__init__.py

@@ -8,6 +8,6 @@ This package provides command-line tools for:
 - Supporting agile ceremonies and team workflows
 """
 
-__version__ = "0.37.5"
+__version__ = "0.38.1"
 
 __all__ = ["__version__"]

{specfact_cli-0.37.5 → specfact_cli-0.38.1}/src/specfact_cli/adapters/ado.py

@@ -38,6 +38,8 @@ from specfact_cli.utils.auth_tokens import get_token, set_token
 
 
 _MAX_RESPONSE_BODY_LOG = 2048
+_ADO_STABLE_API_VERSION = "7.1"
+_ADO_COMMENTS_API_VERSION = "7.1-preview.4"
 
 console = Console()
 
@@ -203,7 +205,7 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
         """
         return "dev.azure.com" not in self.base_url.lower()
 
-    def _build_ado_url(self, path: str, api_version: str = "7.1") -> str:
+    def _build_ado_url(self, path: str, api_version: str = _ADO_STABLE_API_VERSION) -> str:
         """
         Build Azure DevOps API URL with proper formatting.
 
@@ -2474,7 +2476,7 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
             seen_tokens: set[str] = set()
 
             while True:
-                params: dict[str, Any] = {"api-version": "7.1-preview.4", "$top": 200, "order": "asc"}
+                params: dict[str, Any] = {"api-version": _ADO_COMMENTS_API_VERSION, "$top": 200, "order": "asc"}
                 if continuation_token:
                     params["continuationToken"] = continuation_token
 
@@ -2536,7 +2538,10 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
             raise ValueError(msg)
 
         # Azure DevOps API for adding comments to work items
-        url = f"{self.base_url}/{org}/{project}/_apis/wit/workitems/{work_item_id}/comments?api-version=7.1"
+        url = (
+            f"{self.base_url}/{org}/{project}/_apis/wit/workitems/{work_item_id}/comments"
+            f"?api-version={_ADO_COMMENTS_API_VERSION}"
+        )
         headers = {
             "Content-Type": "application/json",
             **self._auth_headers(),
@@ -2944,16 +2949,21 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
                 ]
 
             if filters.iteration:
-                resolved_iteration = filters.iteration
-                if filters.iteration.lower() == "current":
-                    current_iteration = self._get_current_iteration()
-                    if current_iteration:
-                        resolved_iteration = current_iteration
-                    else:
-                        return []
-                filtered_items = [
-                    item for item in filtered_items if item.iteration and item.iteration == resolved_iteration
-                ]
+                normalized_iteration = BacklogFilters.normalize_filter_value(filters.iteration)
+                if normalized_iteration not in (None, "any"):
+                    target_iteration = filters.iteration
+                    if normalized_iteration == "current":
+                        current_iteration = self._get_current_iteration()
+                        if not current_iteration:
+                            return []
+                        target_iteration = current_iteration
+
+                    filtered_items = [
+                        item
+                        for item in filtered_items
+                        if BacklogFilters.normalize_filter_value(item.iteration)
+                        == BacklogFilters.normalize_filter_value(target_iteration)
+                    ]
 
             if filters.sprint:
                 _, filtered_items = self._resolve_sprint_filter(
@@ -3698,7 +3708,7 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
         # Update story points using mapped field name (honors custom mappings)
         if update_fields is None or "story_points" in update_fields:
             story_points_field = ado_mapper.resolve_write_target_field("story_points", provider_field_names)
-            if story_points_field and item.story_points is not None:
+            if story_points_field and item.story_points is not None and story_points_field in provider_field_names:
                 operations.append(
                     {"op": "replace", "path": f"/fields/{story_points_field}", "value": item.story_points}
                 )
@@ -3706,7 +3716,11 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
         # Update business value using mapped field name (honors custom mappings)
         if update_fields is None or "business_value" in update_fields:
             business_value_field = ado_mapper.resolve_write_target_field("business_value", provider_field_names)
-            if business_value_field and item.business_value is not None:
+            if (
+                business_value_field
+                and item.business_value is not None
+                and business_value_field in provider_field_names
+            ):
                 operations.append(
                     {"op": "replace", "path": f"/fields/{business_value_field}", "value": item.business_value}
                 )
@@ -3714,7 +3728,7 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
         # Update priority using mapped field name (honors custom mappings)
         if update_fields is None or "priority" in update_fields:
             priority_field = ado_mapper.resolve_write_target_field("priority", provider_field_names)
-            if priority_field and item.priority is not None:
+            if priority_field and item.priority is not None and priority_field in provider_field_names:
                 operations.append({"op": "replace", "path": f"/fields/{priority_field}", "value": item.priority})
 
         if update_fields is None or "state" in update_fields:

{specfact_cli-0.37.5 → specfact_cli-0.38.1}/src/specfact_cli/backlog/mappers/ado_mapper.py

@@ -171,8 +171,9 @@ class AdoFieldMapper(FieldMapper):
     @beartype
     @require(lambda self, canonical_field: isinstance(canonical_field, str), "Canonical field must be str")
     @require(
-        lambda self, provider_field_names: provider_field_names is None
-        or isinstance(provider_field_names, (set, frozenset)),
+        lambda self, provider_field_names: (
+            provider_field_names is None or isinstance(provider_field_names, (set, frozenset))
+        ),
         "provider_field_names must be set-like or None",
     )
     @ensure(lambda result: result is None or isinstance(result, str), "Must return str or None")

{specfact_cli-0.37.5 → specfact_cli-0.38.1}/src/specfact_cli/cli.py

@@ -58,6 +58,7 @@ from specfact_cli.modes import OperationalMode, detect_mode
 
 # Command groups are registered via CommandRegistry (bootstrap); no top-level command imports.
 from specfact_cli.registry import CommandRegistry
+from specfact_cli.registry.alias_manager import resolve_command
 from specfact_cli.registry.bootstrap import register_builtin_commands
 from specfact_cli.registry.metadata import CommandMetadata
 from specfact_cli.runtime import get_configured_console, init_debug_log_file, set_debug_mode
@@ -348,7 +349,8 @@ class _LazyDelegateGroup(click.Group):
             from typer.main import get_command
 
             ctx = click.get_current_context()
-            real_typer = CommandRegistry.get_typer(cmd_name)
+            resolved_name = resolve_command(cmd_name)
+            real_typer = CommandRegistry.get_typer(resolved_name)
             click_cmd = get_command(real_typer)
             # Build full prog name from root (e.g. "specfact sync") so usage shows "specfact sync bridge", not "sync sync bridge"
             parts: list[str] = []
@@ -407,7 +409,8 @@ class _LazyDelegateGroup(click.Group):
         """Load and return the real command's Click Group, or None on failure."""
         from typer.main import get_command
 
-        real_typer = CommandRegistry.get_typer(self._lazy_cmd_name)
+        resolved_name = resolve_command(self._lazy_cmd_name)
+        real_typer = CommandRegistry.get_typer(resolved_name)
         click_cmd = get_command(real_typer)
         if isinstance(click_cmd, click.Group):
             return click_cmd
@@ -417,7 +420,8 @@ class _LazyDelegateGroup(click.Group):
         """Show the real Typer's Rich help instead of plain Click group help."""
         from typer.main import get_command
 
-        real_typer = CommandRegistry.get_typer(self._lazy_cmd_name)
+        resolved_name = resolve_command(self._lazy_cmd_name)
+        real_typer = CommandRegistry.get_typer(resolved_name)
         click_cmd = get_command(real_typer)
         prog_name = (
             f"{ctx.parent.command.name} {self._lazy_cmd_name}"

{specfact_cli-0.37.5 → specfact_cli-0.38.1}/src/specfact_cli/modules/module_registry/module-package.yaml

@@ -1,5 +1,5 @@
 name: module-registry
-version: 0.1.3
+version: 0.1.5
 commands:
   - module
 command_help:
@@ -15,5 +15,5 @@ publisher:
 description: 'Manage modules: search, list, show, install, and upgrade.'
 license: Apache-2.0
 integrity:
-  checksum: sha256:92a3673edb39974791afcc357a1e931b6e4152d1ad7af0e4a4d722c29431b90d
-  signature: eynkV+88hx9PPGlOnB5rwWHkiEtgFe8wNIU+5I0C8PZR+WWoRIcTcvTe5TYYAyiHi6JmJZZLvrDsTIpe3K3VDQ==
+  checksum: sha256:4837d40c55ebde6eba87b434c3ec3ae3d0d842eb6a6984d4212ffbc6fd26eac2
+  signature: m2tJyNfaHOnil3dsT5NxUB93+4nnVJHBaF7QzQf/DC8F/LG7oJJMWHU063HY9x2/d9hFVXLwItf9TNgNjnirDQ==

{specfact_cli-0.37.5 → specfact_cli-0.38.1}/src/specfact_cli/modules/module_registry/src/commands.py

@@ -12,7 +12,8 @@ from rich.console import Console
 from rich.table import Table
 
 from specfact_cli.modules import module_io_shim
-from specfact_cli.registry.marketplace_client import fetch_registry_index
+from specfact_cli.registry.alias_manager import create_alias, list_aliases, remove_alias
+from specfact_cli.registry.custom_registries import add_registry, fetch_all_indexes, list_registries, remove_registry
 from specfact_cli.registry.module_discovery import discover_all_modules
 from specfact_cli.registry.module_installer import (
     USER_MODULES_ROOT,
@@ -87,6 +88,16 @@ def install(
         "--trust-non-official",
         help="Trust and persist non-official publisher for this module install",
     ),
+    skip_deps: bool = typer.Option(
+        False,
+        "--skip-deps",
+        help="Skip dependency resolution before installing (install module only)",
+    ),
+    force: bool = typer.Option(
+        False,
+        "--force",
+        help="Force install even if dependency resolution reports conflicts",
+    ),
 ) -> None:
     """Install a module from bundled artifacts or marketplace registry."""
     scope_normalized = scope.strip().lower()
@@ -148,6 +159,8 @@ def install(
             install_root=target_root,
             trust_non_official=trust_non_official,
             non_interactive=is_non_interactive(),
+            skip_deps=skip_deps,
+            force=force,
         )
     except Exception as exc:
         console.print(f"[red]Failed installing {normalized}: {exc}[/red]")
@@ -243,6 +256,109 @@ def uninstall(
     console.print(f"[green]Uninstalled[/green] {normalized}")
 
 
+alias_app = typer.Typer(help="Manage command aliases (map name to namespaced module)")
+
+
+@alias_app.command(name="create")
+@beartype
+def alias_create(
+    alias_name: str = typer.Argument(..., help="Alias (command name) to map"),
+    command_name: str = typer.Argument(..., help="Command name to invoke (e.g. backlog, module)"),
+    force: bool = typer.Option(False, "--force", help="Allow alias to shadow built-in command"),
+) -> None:
+    """Create an alias mapping a custom name to a registered command."""
+    try:
+        create_alias(alias_name.strip(), command_name.strip(), force=force)
+    except ValueError as exc:
+        console.print(f"[red]{exc}[/red]")
+        raise typer.Exit(1) from exc
+    console.print(f"[green]Alias[/green] {alias_name!r} -> {command_name!r}")
+
+
+@alias_app.command(name="list")
+@beartype
+def alias_list() -> None:
+    """List all configured aliases."""
+    aliases = list_aliases()
+    if not aliases:
+        console.print("[dim]No aliases configured.[/dim]")
+        return
+    table = Table(title="Aliases")
+    table.add_column("Alias", style="cyan")
+    table.add_column("Command", style="green")
+    for alias, mod in sorted(aliases.items()):
+        table.add_row(alias, mod)
+    console.print(table)
+
+
+@alias_app.command(name="remove")
+@beartype
+def alias_remove(
+    alias_name: str = typer.Argument(..., help="Alias to remove"),
+) -> None:
+    """Remove an alias."""
+    remove_alias(alias_name.strip())
+    console.print(f"[green]Removed alias[/green] {alias_name!r}")
+
+
+if app.add_typer is not None:
+    app.add_typer(alias_app, name="alias")
+
+
+@app.command(name="add-registry")
+@beartype
+def add_registry_cmd(
+    url: str = typer.Argument(..., help="Registry index URL (e.g. https://company.com/index.json)"),
+    id: str | None = typer.Option(None, "--id", help="Registry id (default: derived from URL)"),
+    priority: int | None = typer.Option(None, "--priority", help="Priority (default: next available)"),
+    trust: str = typer.Option("prompt", "--trust", help="Trust level: always, prompt, or never"),
+) -> None:
+    """Add a custom registry to the config."""
+    if trust not in ("always", "prompt", "never"):
+        console.print("[red]trust must be one of: always, prompt, never.[/red]")
+        raise typer.Exit(1)
+    reg_id = (id or url.strip().rstrip("/").split("/")[-2] or "custom").strip() or "custom"
+    try:
+        add_registry(reg_id, url.strip(), priority=priority, trust=trust)
+    except Exception as exc:
+        console.print(f"[red]{exc}[/red]")
+        raise typer.Exit(1) from exc
+    console.print(f"[green]Added registry[/green] {reg_id!r} -> {url}")
+
+
+@app.command(name="list-registries")
+@beartype
+def list_registries_cmd() -> None:
+    """List all configured registries (official + custom)."""
+    registries = list_registries()
+    if not registries:
+        console.print("[dim]No registries configured.[/dim]")
+        return
+    table = Table(title="Registries")
+    table.add_column("Id", style="cyan")
+    table.add_column("URL", style="green")
+    table.add_column("Priority", style="dim")
+    table.add_column("Trust", style="yellow")
+    for r in registries:
+        table.add_row(
+            str(r.get("id", "")),
+            str(r.get("url", "")),
+            str(r.get("priority", "")),
+            str(r.get("trust", "")),
+        )
+    console.print(table)
+
+
+@app.command(name="remove-registry")
+@beartype
+def remove_registry_cmd(
+    registry_id: str = typer.Argument(..., help="Registry id to remove"),
+) -> None:
+    """Remove a custom registry from the config."""
+    remove_registry(registry_id.strip())
+    console.print(f"[green]Removed registry[/green] {registry_id!r}")
+
+
 @app.command()
 @beartype
 def enable(
@@ -320,25 +436,26 @@ def search(query: str = typer.Argument(..., help="Search query")) -> None:
     seen_ids: set[str] = set()
     rows: list[dict[str, str]] = []
 
-    index = fetch_registry_index() or {}
-    for entry in index.get("modules", []):
-        if not isinstance(entry, dict):
-            continue
-        module_id = str(entry.get("id", ""))
-        description = str(entry.get("description", ""))
-        tags = entry.get("tags", [])
-        tags_text = " ".join(str(t) for t in tags) if isinstance(tags, list) else ""
-        haystack = f"{module_id} {description} {tags_text}".lower()
-        if query_l in haystack and module_id not in seen_ids:
-            seen_ids.add(module_id)
-            rows.append(
-                {
-                    "id": module_id,
-                    "version": str(entry.get("latest_version", "")),
-                    "description": description,
-                    "scope": "marketplace",
-                }
-            )
+    for reg_id, index in fetch_all_indexes():
+        for entry in index.get("modules", []):
+            if not isinstance(entry, dict):
+                continue
+            module_id = str(entry.get("id", ""))
+            description = str(entry.get("description", ""))
+            tags = entry.get("tags", [])
+            tags_text = " ".join(str(t) for t in tags) if isinstance(tags, list) else ""
+            haystack = f"{module_id} {description} {tags_text}".lower()
+            if query_l in haystack and module_id not in seen_ids:
+                seen_ids.add(module_id)
+                rows.append(
+                    {
+                        "id": module_id,
+                        "version": str(entry.get("latest_version", "")),
+                        "description": description,
+                        "scope": "marketplace",
+                        "registry": reg_id,
+                    }
+                )
 
     for discovered in discover_all_modules():
         meta = discovered.metadata
@@ -372,9 +489,11 @@ def search(query: str = typer.Argument(..., help="Search query")) -> None:
     table.add_column("ID", style="cyan")
     table.add_column("Version", style="magenta")
     table.add_column("Scope", style="yellow")
+    table.add_column("Registry", style="dim")
     table.add_column("Description")
     for row in rows:
-        table.add_row(row["id"], row["version"], row["scope"], row["description"])
+        reg = row.get("registry", "")
+        table.add_row(row["id"], row["version"], row["scope"], reg, row["description"])
     console.print(table)
 
 

specfact_cli-0.38.1/src/specfact_cli/registry/alias_manager.py

@@ -0,0 +1,94 @@
+"""Alias storage and resolution: alias -> command name."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from beartype import beartype
+from icontract import ensure, require
+
+from specfact_cli.common import get_bridge_logger
+
+
+logger = get_bridge_logger(__name__)
+
+_ALIASES_FILENAME = "aliases.json"
+
+
+def get_aliases_path() -> Path:
+    """Return path to aliases.json under ~/.specfact/registry/."""
+    return Path.home() / ".specfact" / "registry" / _ALIASES_FILENAME
+
+
+def _builtin_command_names() -> set[str]:
+    """Return set of built-in (default) command names for shadowing check."""
+    from specfact_cli.registry.module_packages import CORE_MODULE_ORDER
+
+    return set(CORE_MODULE_ORDER)
+
+
+@beartype
+@require(lambda alias: alias.strip() != "", "alias must be non-empty")
+@require(lambda command_name: command_name.strip() != "", "command_name must be non-empty")
+@ensure(lambda: True, "no postcondition on void")
+def create_alias(alias: str, command_name: str, force: bool = False) -> None:
+    """Store alias -> command_name in aliases.json. Warn or raise if alias shadows built-in."""
+    alias = alias.strip()
+    command_name = command_name.strip()
+    path = get_aliases_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    builtin = _builtin_command_names()
+    if alias in builtin and not force:
+        logger.warning("Alias will shadow built-in module: %s", alias)
+        raise ValueError(f'Alias "{alias}" would shadow built-in module. Use --force to proceed.')
+    data = {}
+    if path.exists():
+        data = json.loads(path.read_text(encoding="utf-8"))
+    data[alias] = command_name
+    path.write_text(json.dumps(data, indent=2), encoding="utf-8")
+    if alias in builtin:
+        logger.warning("Alias will shadow built-in module: %s", alias)
+
+
+@beartype
+@ensure(lambda result: isinstance(result, dict), "returns dict")
+def list_aliases() -> dict[str, str]:
+    """Return all alias -> command name mappings. Empty dict if file missing."""
+    path = get_aliases_path()
+    if not path.exists():
+        return {}
+    raw = path.read_text(encoding="utf-8")
+    data = json.loads(raw)
+    if not isinstance(data, dict):
+        return {}
+    return {str(k): str(v) for k, v in data.items()}
+
+
+@beartype
+@require(lambda alias: alias.strip() != "", "alias must be non-empty")
+@ensure(lambda: True, "no postcondition on void")
+def remove_alias(alias: str) -> None:
+    """Remove alias from aliases.json."""
+    alias = alias.strip()
+    path = get_aliases_path()
+    if not path.exists():
+        return
+    data = json.loads(path.read_text(encoding="utf-8"))
+    if alias in data:
+        del data[alias]
+        if data:
+            path.write_text(json.dumps(data, indent=2), encoding="utf-8")
+        else:
+            path.unlink()
+
+
+@beartype
+@require(lambda invoked_name: isinstance(invoked_name, str), "invoked_name must be str")
+@ensure(lambda result: isinstance(result, str) and len(result) > 0, "returns non-empty string")
+def resolve_command(invoked_name: str) -> str:
+    """If invoked_name is an alias, return the stored command name; else return invoked_name."""
+    aliases = list_aliases()
+    if invoked_name in aliases:
+        return aliases[invoked_name]
+    return invoked_name

specfact_cli-0.38.1/src/specfact_cli/registry/custom_registries.py

@@ -0,0 +1,139 @@
+"""Custom registry management: YAML config and multi-registry index fetching."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import requests
+import yaml
+from beartype import beartype
+from icontract import ensure, require
+
+from specfact_cli.common import get_bridge_logger
+from specfact_cli.registry.marketplace_client import REGISTRY_INDEX_URL
+
+
+logger = get_bridge_logger(__name__)
+
+_REGISTRIES_FILENAME = "registries.yaml"
+OFFICIAL_REGISTRY_ID = "official"
+TRUST_LEVELS = frozenset({"always", "prompt", "never"})
+
+
+def get_registries_config_path() -> Path:
+    """Return path to registries.yaml under ~/.specfact/config/."""
+    return Path.home() / ".specfact" / "config" / _REGISTRIES_FILENAME
+
+
+def _default_official_entry() -> dict[str, Any]:
+    """Return the built-in official registry entry."""
+    return {
+        "id": OFFICIAL_REGISTRY_ID,
+        "url": REGISTRY_INDEX_URL,
+        "priority": 1,
+        "trust": "always",
+    }
+
+
+@beartype
+@require(lambda id: id.strip() != "", "id must be non-empty")
+@require(lambda url: url.strip().startswith("http"), "url must be http(s)")
+@require(lambda trust: trust in TRUST_LEVELS, "trust must be always, prompt, or never")
+@ensure(lambda: True, "no postcondition on void")
+def add_registry(
+    id: str,
+    url: str,
+    priority: int | None = None,
+    trust: str = "prompt",
+) -> None:
+    """Add a registry to config. Assigns next priority if priority is None."""
+    id = id.strip()
+    url = url.strip()
+    path = get_registries_config_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    registries: list[dict[str, Any]] = []
+    if path.exists():
+        data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+        registries = list(data.get("registries") or [])
+    existing_ids = {r.get("id") for r in registries if isinstance(r, dict) and r.get("id")}
+    if id in existing_ids:
+        registries = [r for r in registries if isinstance(r, dict) and r.get("id") != id]
+    if priority is None:
+        priorities = [
+            p
+            for r in registries
+            if isinstance(r, dict) and (p := r.get("priority")) is not None and isinstance(p, (int, float))
+        ]
+        priority = int(max(priorities, default=0)) + 1
+    registries.append({"id": id, "url": url, "priority": int(priority), "trust": trust})
+    registries.sort(key=lambda r: (r.get("priority", 999), r.get("id", "")))
+    path.write_text(yaml.dump({"registries": registries}, default_flow_style=False, sort_keys=False), encoding="utf-8")
+
+
+@beartype
+@ensure(lambda result: isinstance(result, list), "returns list")
+def list_registries() -> list[dict[str, Any]]:
+    """Return all registries: official first, then custom from config, sorted by priority."""
+    result: list[dict[str, Any]] = []
+    path = get_registries_config_path()
+    if path.exists():
+        try:
+            data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+            custom = [r for r in (data.get("registries") or []) if isinstance(r, dict) and r.get("id")]
+            has_official = any(r.get("id") == OFFICIAL_REGISTRY_ID for r in custom)
+            if not has_official:
+                result.append(_default_official_entry())
+            for r in custom:
+                result.append({k: v for k, v in r.items() if k in ("id", "url", "priority", "trust")})
+            result.sort(key=lambda r: (r.get("priority", 999), r.get("id", "")))
+        except Exception as exc:
+            logger.warning("Failed to load registries config: %s", exc)
+            result = [_default_official_entry()]
+    else:
+        result = [_default_official_entry()]
+    return result
+
+
+@beartype
+@require(lambda id: id.strip() != "", "id must be non-empty")
+@ensure(lambda: True, "no postcondition on void")
+def remove_registry(id: str) -> None:
+    """Remove a registry by id from config. Cannot remove official (no-op if official)."""
+    id = id.strip()
+    if id == OFFICIAL_REGISTRY_ID:
+        logger.debug("Cannot remove built-in official registry")
+        return
+    path = get_registries_config_path()
+    if not path.exists():
+        return
+    data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+    registries = [r for r in (data.get("registries") or []) if isinstance(r, dict) and r.get("id") != id]
+    if not registries:
+        path.unlink()
+        return
+    path.write_text(yaml.dump({"registries": registries}, default_flow_style=False, sort_keys=False), encoding="utf-8")
+
+
+@beartype
+@ensure(lambda result: isinstance(result, list), "returns list")
+def fetch_all_indexes(timeout: float = 10.0) -> list[tuple[str, dict[str, Any]]]:
+    """Fetch index from each registry in priority order. Returns list of (registry_id, index_dict)."""
+    registries = list_registries()
+    result: list[tuple[str, dict[str, Any]]] = []
+    for reg in registries:
+        reg_id = str(reg.get("id", ""))
+        url = str(reg.get("url", "")).strip()
+        if not url:
+            continue
+        try:
+            response = requests.get(url, timeout=timeout)
+            response.raise_for_status()
+            payload = response.json()
+            if isinstance(payload, dict):
+                result.append((reg_id, payload))
+            else:
+                logger.warning("Registry %s returned non-dict index", reg_id)
+        except Exception as exc:
+            logger.warning("Registry %s unavailable: %s", reg_id, exc)
+    return result