katalyst-taxonomy-cli 2.0.1a1__py3-none-any.whl

katalyst_taxonomy_cli/commands/config_schemas.py

@@ -0,0 +1,257 @@
+"""``kata config schemas`` — which bundle provides what, and is it on (#218).
+
+Deliberately a **separate module** from :mod:`.config`: it is added to the
+``config`` group by one line there, so this command can land without touching the
+file that owns ``path``/``show``/``sources``/``profiles``/``use``.
+
+Register it with a single line at the end of ``commands/config.py``::
+
+    from .config_schemas import attach as _attach_schemas; _attach_schemas(config)
+
+The JSON shape is the contract in
+``stack-tests/features/cli/36_kata_config_schemas.feature``. Extend it additively.
+
+The command is a *report*, but it is not a read-only one in the interesting sense:
+building the payload builds the registry, so a version pin that is not satisfied,
+two bundles claiming one kind, or a declared bundle that cannot be parsed all fail
+the command. That is the point — ``kata config schemas`` is where you find out.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import click
+from katalyst_engine.core.errors import EngineConfigurationError
+from katalyst_taxonomy.config.profiles import UnknownProfileError
+
+from ..output import ConsoleOutput, OutputPort
+
+__all__ = [
+    "attach",
+    "build_schemas_payload",
+    "schemas",
+]
+
+_FORMAT_CHOICE = click.Choice(["text", "json"])
+
+
+def build_schemas_payload(
+    *,
+    profile: str | None = None,
+) -> dict[str, Any]:
+    """Build the ``kata config schemas`` payload.
+
+    Resolves the configuration, installs the resulting selection into the process
+    so the registry is built under it, then composes the report from registry
+    provenance plus the one config-aware discovery factory.
+
+    Raises:
+        UnknownProfileError: If the profile cannot be selected.
+        ValueError: If the configuration is malformed.
+        EngineConfigurationError: If a version pin is unsatisfied, a declared
+            bundle's manifest cannot be read, or two bundles claim the same kind
+            or the same install destination.
+        RuntimeError: If a declared bundle cannot be loaded.
+    """
+    from katalyst_taxonomy.adapters.filesystem.real import RealFilesystem
+    from katalyst_taxonomy.adapters.orchestration import template_bundles
+    from katalyst_taxonomy.config.backends import config_resolver
+    from katalyst_taxonomy.config.schemas import selection_from_config
+    from katalyst_taxonomy.engine import bridge
+    from katalyst_taxonomy.services.schema_gate import check_declared_bundles
+    from katalyst_taxonomy.services.schema_report import schemas_payload
+    from katalyst_taxonomy.sources.template_resolver import TemplateResolver
+
+    effective = config_resolver().resolve(profile=profile)
+    selection = selection_from_config(effective.config, effective.selection.profile)
+
+    bridge.configure_schema_bundles(selection)
+    try:
+        # Probing the declared sources is what makes an unreadable manifest and an
+        # install-target collision visible. It is opt-in per caller because it is
+        # I/O, and ``kata config schemas`` is the caller that exists to pay for it.
+        declared = check_declared_bundles(
+            selection, repo_root=None, templates=template_bundles(), probe_sources=True
+        )
+        factory = bridge.bundle_discovery_factory()
+        registry = bridge.get_default_registry()
+        resolver = TemplateResolver()
+        candidates = factory.candidates()
+        return schemas_payload(
+            selection=selection,
+            registry=registry,
+            bundle_names={
+                candidate.name: candidate.discovered.entry_point for candidate in candidates
+            },
+            distributions={
+                candidate.name: candidate.distribution
+                for candidate in candidates
+                if candidate.distribution
+            },
+            declared=declared,
+            scaffold_providers=resolver.scaffold_template_providers(),
+            repo_root=None,
+            filesystem=RealFilesystem(),
+            profile=effective.profile_name,
+            config_origin=effective.origin.value,
+        )
+    finally:
+        bridge.configure_schema_bundles(None)
+
+
+def _output() -> OutputPort:
+    return ConsoleOutput()
+
+
+@click.command("schemas")
+@click.option(
+    "--profile",
+    "profile",
+    default=None,
+    help="Profile to resolve. Overrides KATALYST_PROFILE and spec.activeProfile.",
+)
+@click.option("--format", "fmt", type=_FORMAT_CHOICE, default="text")
+def schemas(profile: str | None, fmt: str) -> None:
+    """List schema bundles, the kinds they provide, and which are enabled.
+
+    Every kind is attributed to the bundle that registered it — both by the name
+    ``spec.schemas`` uses to select it and by the distribution you install it from
+    — and every declared bundle is listed even when the active profile excludes
+    it, because a report that hid a disabled bundle would make "why is my kind
+    missing" unanswerable. Variants the profile excludes move to
+    ``disabledScaffoldVariants``, with the reason, so ``scaffoldVariants`` means
+    "what you can actually scaffold".
+
+    Fails, rather than reporting, when the configuration cannot be honoured: an
+    unsatisfied version pin, a declared bundle whose manifest cannot be read, or
+    two bundles claiming one kind or one shared install destination.
+    """
+    out = _output()
+    try:
+        payload = build_schemas_payload(profile=_selected_profile(profile))
+    except (
+        UnknownProfileError,
+        EngineConfigurationError,
+        RuntimeError,
+        ValueError,
+    ) as exc:
+        raise click.ClickException(str(exc)) from exc
+
+    if fmt == "json":
+        out.json_out(payload)
+        return
+
+    _render_text(out, payload)
+
+
+def _render_text(out: OutputPort, payload: dict[str, Any]) -> None:
+    """Render the human view: bundles, then kinds, then variants, then conflicts."""
+    out.key_value(
+        [
+            ("profile", payload["profile"] or "(none)"),
+            ("config origin", payload["configOrigin"] or "-"),
+            ("schemas declared", "yes" if payload["declared"] else "no"),
+        ]
+    )
+
+    out.heading("Bundles")
+    bundles: list[dict[str, Any]] = payload["bundles"]
+    if not bundles:
+        out.info("No schema bundles discovered.")
+    else:
+        out.table(
+            ["", "bundle", "distribution", "version", "kinds", "note"],
+            [
+                [
+                    "*" if entry["enabled"] else "x",
+                    str(entry["name"]),
+                    str(entry.get("distribution") or "-"),
+                    str(entry.get("resolvedVersion") or entry["version"] or "-"),
+                    str(len(entry["kinds"])),
+                    str(
+                        entry["reason"] or entry.get("sourceWarning") or entry["entryPoint"] or "-"
+                    ),
+                ]
+                for entry in bundles
+            ],
+        )
+
+    out.heading("Kinds")
+    out.table(
+        ["kind", "bundle", "distribution", "wing"],
+        [
+            [
+                str(entry["kind"]),
+                str(entry["bundle"] or "-"),
+                str(entry.get("distribution") or "-"),
+                str(entry["wing"] or "-"),
+            ]
+            for entry in payload["kinds"]
+        ],
+    )
+
+    variants: list[dict[str, Any]] = payload["scaffoldVariants"]
+    if variants:
+        out.heading("Scaffold variants")
+        out.table(
+            ["variant", "node type", "bundle", "origin"],
+            [
+                [
+                    str(entry["name"]),
+                    str(entry["nodeType"]),
+                    str(entry["bundle"]),
+                    str(entry["origin"]),
+                ]
+                for entry in variants
+            ],
+        )
+
+    # Rendered as its own section rather than as ``x`` rows above, for the same
+    # reason the payload splits the two keys: a reader scanning "what can I
+    # scaffold?" should not have to filter, and a reader asking "why is my variant
+    # missing?" needs the reason, which only this section has room for.
+    disabled: list[dict[str, Any]] = payload.get("disabledScaffoldVariants", [])
+    if disabled:
+        out.heading("Disabled scaffold variants")
+        out.table(
+            ["variant", "node type", "bundle", "reason"],
+            [
+                [
+                    str(entry["name"]),
+                    str(entry["nodeType"]),
+                    str(entry["bundle"]),
+                    str(entry["reason"] or "-"),
+                ]
+                for entry in disabled
+            ],
+        )
+
+    conflicts: list[dict[str, Any]] = payload["conflicts"]
+    if conflicts:
+        out.heading("Conflicts")
+        out.table(
+            ["scope", "key", "providers"],
+            [
+                [str(entry["scope"]), str(entry["key"]), ", ".join(entry["providers"])]
+                for entry in conflicts
+            ],
+        )
+
+
+def attach(group: click.Group) -> None:
+    """Add ``schemas`` to the ``kata config`` group.
+
+    A function rather than a bare ``add_command`` call so registration is one line
+    in ``commands/config.py`` and this module stays the only place that knows the
+    command's name.
+    """
+    group.add_command(schemas)
+
+
+def _selected_profile(explicit: str | None) -> str | None:
+    # Imported here: ``config`` attaches this module's command at import time, so a
+    # module-level import back into it is a cycle whenever this module loads first.
+    from .config import resolve_profile
+
+    return resolve_profile(explicit)

katalyst_taxonomy_cli/commands/config_sources.py

@@ -0,0 +1,141 @@
+"""``kata config sync`` and ``kata config status`` — profiles sourced from elsewhere.
+
+A profile may name a ``source`` (a ``git:``/``github:`` repository holding a config file,
+or another kata API) instead of declaring its backends. These commands are thin shells
+over :class:`~katalyst_taxonomy.services.config_sources.ConfigSourceService`, the same
+service the MCP ``config_sync``/``config_status`` tools and REST ``/config/sources`` call::
+
+    kata config sync [PROFILE...]     fetch each sourced profile and pin it
+    kata config status [--offline]    each sourced profile's source, pin and last fetch,
+                                      and whether the source is ahead of the pin
+
+The pin and the fetched profile are kept in the state home, never in config.yaml; every
+other command reads the pinned copy.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+import click
+
+from ..output import ConsoleOutput, OutputPort
+
+if TYPE_CHECKING:  # pragma: no cover - typing only
+    from katalyst_taxonomy.services.config_sources import SourceStatus, SourceSync
+
+__all__ = ["attach"]
+
+_FORMAT_CHOICE = click.Choice(["text", "json"])
+
+
+def _output() -> OutputPort:
+    return ConsoleOutput()
+
+
+def _short(pin: str | None) -> str:
+    """A commit sha or content hash shortened to 12 characters; an ETag as it is."""
+    if not pin:
+        return "-"
+    if pin.startswith("sha256:"):
+        return pin[: len("sha256:") + 12]
+    return pin[:12] if len(pin) in (40, 64) else pin
+
+
+@click.command("sync")
+@click.argument("names", nargs=-1, metavar="[PROFILE]...")
+@click.option("--format", "fmt", type=_FORMAT_CHOICE, default="text")
+def config_sync(names: tuple[str, ...], fmt: str) -> None:
+    """Fetch every sourced profile (or each PROFILE) and pin it.
+
+    A git source is pinned to its commit, a kata API to its ETag or content hash. Each
+    repository a sourced profile's filesystem backends name is found under
+    spec.workspace by its remote URL, or cloned there. Exits 1 if any fetch failed; a
+    failed one keeps its previous pin.
+    """
+    from katalyst_taxonomy.adapters.orchestration import sync_config_sources
+
+    out = _output()
+    try:
+        results: list[SourceSync] = sync_config_sources(names)
+    except ValueError as exc:
+        raise click.ClickException(str(exc)) from exc
+    if fmt == "json":
+        out.json_out({"profiles": [r.as_payload() for r in results]})
+    elif not results:
+        out.info("No profile is sourced from elsewhere; nothing to sync.")
+    for result in results if fmt == "text" else ():
+        if not result.ok:
+            out.warning(f"{result.profile}: {result.error}")
+            continue
+        change = (
+            f"pinned {_short(result.pin)}"
+            if not result.previous
+            else f"{_short(result.previous)} -> {_short(result.pin)}"
+            if result.changed
+            else f"unchanged at {_short(result.pin)}"
+        )
+        out.success(f"{result.profile}: {result.source} {change}")
+        for clone in result.clones:
+            how = "cloned to" if clone.cloned else "using"
+            out.info(f"  {clone.repository}: {how} {clone.path}")
+    if any(not r.ok for r in results):
+        raise SystemExit(1)
+
+
+@click.command("status")
+@click.option(
+    "--offline",
+    is_flag=True,
+    help="Do not ask the sources whether they have moved; report the pins only.",
+)
+@click.option("--format", "fmt", type=_FORMAT_CHOICE, default="text")
+def config_status(offline: bool, fmt: str) -> None:
+    """Each sourced profile: its source, pin and last fetch, and whether the source is ahead."""
+    from katalyst_taxonomy.adapters.orchestration import config_source_status
+
+    out = _output()
+    try:
+        rows: list[SourceStatus] = config_source_status(check=not offline)
+    except ValueError as exc:
+        raise click.ClickException(str(exc)) from exc
+    if fmt == "json":
+        out.json_out({"profiles": [r.as_payload() for r in rows]})
+        return
+    if not rows:
+        out.info("No profile is sourced from elsewhere.")
+        return
+    out.table(
+        ["profile", "source", "pin", "fetched", "upstream"],
+        [
+            [
+                row.profile
+                if row.source_profile == row.profile
+                else f"{row.profile} ({row.source_profile})",
+                row.source,
+                _short(row.pin) if row.pin else "never fetched",
+                row.fetched_at or "-",
+                _upstream(row, offline),
+            ]
+            for row in rows
+        ],
+    )
+    for row in rows:
+        if row.error:
+            out.warning(f"{row.profile}: {row.error}")
+
+
+def _upstream(row: Any, offline: bool) -> str:
+    if offline:
+        return "not checked"
+    if row.behind is None:
+        return "unknown"
+    if row.behind:
+        return f"behind ({_short(row.latest)}) — run 'kata config sync {row.profile}'"
+    return "current"
+
+
+def attach(group: click.Group) -> None:
+    """Add ``sync`` and ``status`` to the ``kata config`` group."""
+    group.add_command(config_sync)
+    group.add_command(config_status)