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

katalyst_taxonomy_cli/commands/config_filters.py

@@ -0,0 +1,159 @@
+"""``kata config filter`` — is this node visible, and which clause decided (#217).
+
+Include/exclude resolution is invisible by nature: nothing in an FQTN says which
+clause claimed it, and "``exclude`` wins over every ``include``" is not something
+anyone should have to simulate in their head against a config file. This command is
+the inspection surface, and it answers from the *same*
+:class:`~katalyst_taxonomy.config.filters.FilterPolicy` object the read paths
+narrow with — a verdict resolved by a second code path is not an explanation of
+the first.
+
+Deliberately a **separate module** from :mod:`.config`, following the pattern
+``config_schemas`` and ``config_plugins`` established: it is added to the group by
+one line there, so this command lands without touching the file that owns
+``path``/``show``/``sources``/``profiles``/``use``/``explain``/``permissions``.
+
+The JSON shape is the contract in
+``stack-tests/features/cli/35_kata_config_filters.feature``. Extend it additively.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import click
+from katalyst_taxonomy.config.profiles import UnknownProfileError
+
+from ..output import ConsoleOutput, OutputPort
+from .config import resolve_profile
+
+__all__ = [
+    "attach",
+    "build_filter_payload",
+    "filter_command",
+]
+
+_FORMAT_CHOICE = click.Choice(["text", "json"])
+
+
+def build_filter_payload(
+    fqtn: str = "",
+    *,
+    profile: str | None = None,
+) -> dict[str, Any]:
+    """Build the ``kata config filter`` payload.
+
+    Delegates wholesale to
+    :func:`katalyst_taxonomy.services.filters.filter_payload` rather than
+    assembling anything here, which is what lets the MCP ``config_filter`` tool be
+    byte-identical without ``mcp/`` importing ``cli/``.
+
+    Raises:
+        UnknownProfileError: If the profile cannot be selected.
+        ValueError: If the configuration is malformed, if ``filters.include`` was
+            declared as an empty list, or if a clause declares ``match.backend``.
+    """
+    from katalyst_taxonomy.services.filters import filter_payload
+
+    return filter_payload(fqtn, base_path=Path.cwd(), profile=profile)
+
+
+def _output() -> OutputPort:
+    return ConsoleOutput()
+
+
+@click.command("filter")
+@click.option(
+    "--fqtn",
+    default=None,
+    help="Node FQTN to decide. Omitted, only the declared clauses are listed.",
+)
+@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 filter_command(
+    fqtn: str | None,
+    profile: str | None,
+    fmt: str,
+) -> None:
+    """Report whether an FQTN is visible under its backend's filters, and why.
+
+    Filters live on backends and apply in every profile that reads them. Resolution is: criteria AND within a clause, clauses OR across a list, and
+    ``exclude`` always beats ``include``. An absent ``include`` list admits
+    everything; ``include: []`` is refused outright, because an empty list cannot
+    be told apart from an omitted one.
+
+    A backend with no ``filters`` block reports every node as included with a null
+    clause and ``clauseType: unfiltered`` — that is the back-compat guarantee, not
+    an omission.
+
+    Pure resolution: it reads the repository's own documents to learn each node's
+    kind, wing and labels, and never opens a connection to a remote store. An FQTN
+    with no node behind it still resolves — the criteria that need facts simply
+    cannot match, which is fail-closed.
+    """
+    out = _output()
+    try:
+        payload = build_filter_payload(fqtn or "", profile=resolve_profile(profile))
+    except (UnknownProfileError, ValueError) as exc:
+        raise click.ClickException(str(exc)) from exc
+
+    if fmt == "json":
+        out.json_out(payload)
+        return
+
+    _render_text(out, payload, asked=bool(fqtn))
+
+
+def _render_text(out: OutputPort, payload: dict[str, Any], *, asked: bool) -> None:
+    """Render the human view: the verdict, then every declared clause."""
+    if asked:
+        out.key_value(
+            [
+                ("fqtn", payload["fqtn"]),
+                ("backend", payload["backend"] or "-"),
+                ("visible", "yes" if payload["included"] else "NO"),
+                ("decided by", payload["clauseType"]),
+                ("clause", payload["clause"] or "-"),
+                ("matched on", payload["matchedOn"] or "-"),
+                ("profile", payload["profile"] or "(none)"),
+                ("source", payload["source"] or "-"),
+            ]
+        )
+    else:
+        out.key_value([("profile", payload["profile"] or "(none)")])
+
+    clauses: list[dict[str, Any]] = payload["backendClauses"]
+    if not clauses:
+        out.info("No backend declares filter clauses — every node is visible.")
+        return
+
+    out.heading("Backend clauses")
+    out.table(
+        ["backend", "type", "clause", "match", "source"],
+        [
+            [
+                str(entry["backend"]),
+                str(entry["type"]),
+                str(entry["name"] or "-"),
+                ", ".join(f"{key}={value}" for key, value in entry["match"].items()) or "*",
+                str(entry["source"] or "-"),
+            ]
+            for entry in clauses
+        ],
+    )
+
+
+def attach(group: click.Group) -> None:
+    """Add ``filter`` 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(filter_command)

katalyst_taxonomy_cli/commands/config_home.py

@@ -0,0 +1,179 @@
+"""``kata config home`` — list, create and remove named Katalyst homes (#257).
+
+A home is the config, state and cache a process uses (:mod:`katalyst_taxonomy.domain.homes`).
+``kata --home NAME`` or ``KATALYST_HOME=NAME`` selects one; a named home must exist first::
+
+    kata config home list
+    kata config home create NAME [--from HOME]
+    kata config home rm NAME [--yes]
+
+Path homes (an absolute ``KATALYST_HOME``, for tests and CI) are never listed: they are
+wherever their caller put them.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+from typing import Any
+
+import click
+from katalyst_taxonomy.adapters.filesystem.homes import (
+    create_home,
+    home_for,
+    named_homes,
+)
+from katalyst_taxonomy.domain.homes import (
+    DEFAULT_HOME,
+    Home,
+    HomeError,
+    named_home,
+    resolve_home,
+)
+from katalyst_taxonomy.domain.paths import CONFIG_FILE_NAME
+
+from ..output import ConsoleOutput
+
+__all__ = ["attach", "home"]
+
+_FORMAT_CHOICE = click.Choice(["text", "json"])
+
+
+#: The running API's state record in a home's state directory (one API per home), as
+#: ``katalyst_taxonomy_mcp.rest.state`` writes it.
+_API_RECORD = "server.json"
+
+
+def _running_api(home: Home) -> dict[str, Any] | None:
+    """The API whose state record is in *home*, when its process is alive."""
+    try:
+        record = json.loads((home.state_dir / _API_RECORD).read_text(encoding="utf-8"))
+        pid, host, port = int(record["pid"]), str(record["host"]), int(record["port"])
+    except (OSError, ValueError, KeyError, TypeError):
+        return None
+    try:
+        os.kill(pid, 0)
+    except OSError:
+        return None
+    return {"pid": pid, "url": f"http://{host}:{port}"}
+
+
+def _same(a: Home, b: Home) -> bool:
+    return a.kind == b.kind and a.root == b.root
+
+
+def build_list_payload() -> dict[str, Any]:
+    """Every listed home: the default one, then ``~/.katalyst/homes/*``."""
+    active = resolve_home()
+    homes = [home_for(DEFAULT_HOME), *named_homes()]
+    return {
+        "active": active.to_dict(),
+        "homes": [
+            {
+                "name": home.name,
+                "kind": home.kind.value,
+                "root": None if home.root is None else str(home.root),
+                "active": _same(home, active),
+                "api": _running_api(home),
+            }
+            for home in homes
+        ],
+    }
+
+
+@click.group("home")
+def home() -> None:
+    """List, create and remove named homes (~/.katalyst/homes/NAME).
+
+    Select one with 'kata --home NAME' or KATALYST_HOME=NAME. 'default' is the XDG
+    locations (~/.config/katalyst, ~/.local/state/katalyst, ~/.cache/katalyst).
+    """
+
+
+@home.command("list")
+@click.option("--format", "fmt", type=_FORMAT_CHOICE, default="text")
+def home_list(fmt: str) -> None:
+    """List the default home and every named home, marking the active one."""
+    payload = build_list_payload()
+    out = ConsoleOutput()
+    if fmt == "json":
+        out.json_out(payload)
+        return
+    out.table(
+        ["", "home", "root", "api"],
+        [
+            [
+                "*" if entry["active"] else "",
+                entry["name"],
+                entry["root"] or "(XDG locations)",
+                entry["api"]["url"] if entry["api"] else "-",
+            ]
+            for entry in payload["homes"]
+        ],
+    )
+    active = payload["active"]
+    if active["kind"] == "path":
+        out.info(f"Active: {active['name']} (a path home, not listed)")
+
+
+@home.command("create")
+@click.argument("name")
+@click.option(
+    "--from",
+    "source",
+    default=None,
+    metavar="HOME",
+    help="Copy config.yaml (only) from this home: 'default', a name, or an absolute path.",
+)
+def home_create(name: str, source: str | None) -> None:
+    """Create the named home NAME, empty or with another home's config.yaml."""
+    try:
+        origin = home_for(source) if source is not None else None
+        created = create_home(name)
+    except HomeError as exc:
+        raise click.ClickException(str(exc)) from exc
+    copied = ""
+    if origin is not None:
+        config_file = origin.config_dir / CONFIG_FILE_NAME
+        if config_file.is_file():
+            shutil.copy2(config_file, created.config_dir / CONFIG_FILE_NAME)
+            copied = f", with config.yaml from {origin.name}"
+    ConsoleOutput().success(f"Created home {created.label}{copied}")
+
+
+@home.command("rm")
+@click.argument("name")
+@click.option("--yes", is_flag=True, help="Do not ask before deleting.")
+def home_rm(name: str, yes: bool) -> None:
+    """Delete the named home NAME: its config, state and cache.
+
+    Refuses the default home, the active home, and a home whose API is running.
+    """
+    try:
+        target = named_home(name)
+    except HomeError as exc:
+        raise click.ClickException(str(exc)) from exc
+    root = target.root
+    if root is None or not root.is_dir():
+        raise click.ClickException(f"home {name!r} does not exist")
+    if _same(target, resolve_home()):
+        raise click.ClickException(f"home {name!r} is the active home; select another first")
+    api = _running_api(target)
+    if api is not None:
+        raise click.ClickException(
+            f"home {name!r} has a running API ({api['url']}, pid {api['pid']}); stop it first"
+        )
+    out = ConsoleOutput()
+    out.info(f"This deletes {root} and everything in it:")
+    for entry in sorted(root.iterdir()):
+        out.info(f"  {entry.name}{'/' if entry.is_dir() else ''}")
+    if not yes and not click.confirm(f"Delete home {name!r}?", default=False):
+        raise click.ClickException("not deleted")
+    shutil.rmtree(root)
+    out.success(f"Deleted home {name!r}")
+
+
+def attach(group: click.Group) -> None:
+    """Add ``home`` to the ``kata config`` group."""
+    group.add_command(home)

katalyst_taxonomy_cli/commands/config_plugins.py

@@ -0,0 +1,180 @@
+"""``kata config plugins`` — which plugins ran, in what order, with what config (#219).
+
+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_plugins import attach as _attach_plugins; _attach_plugins(config)
+
+The JSON shape is the contract in
+``stack-tests/features/cli/37_kata_config_plugins.feature``. Extend it additively.
+
+The command is a *report*, but not a read-only one in the interesting sense:
+building the payload **activates the plugins**, so a plugin that raises during
+``register()`` or a ``spec.plugins`` entry naming something that is not installed
+fails this command. That is the point — ``kata config plugins`` is where you find
+out, and a report that said "activated: true" without having activated anything
+would be exactly the illusion this issue exists to remove.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import click
+from katalyst_taxonomy.config.profiles import UnknownProfileError
+from katalyst_taxonomy.plugins.errors import PluginError
+
+from ..output import ConsoleOutput, OutputPort
+
+__all__ = [
+    "attach",
+    "build_plugins_payload",
+    "plugins",
+]
+
+_FORMAT_CHOICE = click.Choice(["text", "json"])
+
+
+def build_plugins_payload(
+    *,
+    profile: str | None = None,
+) -> dict[str, Any]:
+    """Build the ``kata config plugins`` payload.
+
+    Resolves the configuration, activates plugins under the resulting selection,
+    then reports what actually happened. Activation is process-memoised, so when
+    this runs inside a process that already activated — it does not today, since
+    ``config`` is not under ``tax``, but a future embedding might — the report
+    describes that activation rather than performing a second one.
+
+    Raises:
+        UnknownProfileError: If the profile cannot be selected.
+        ValueError: If the configuration is malformed.
+        PluginError: If a declared plugin is unknown, cannot be loaded, or raised
+            during ``register()``.
+    """
+    from katalyst_engine.events.bus import EventBus
+    from katalyst_taxonomy.config.backends import config_resolver
+    from katalyst_taxonomy.config.plugins import selection_from_config
+    from katalyst_taxonomy.plugins.activation import activate_once, plugins_payload
+    from katalyst_taxonomy.plugins.startup import plugin_schema_registry
+
+    effective = config_resolver().resolve(profile=profile)
+    selection = selection_from_config(effective.config, effective.selection.profile)
+
+    activation = activate_once(
+        selection=selection,
+        schema_registry=plugin_schema_registry(),
+        event_bus=EventBus(),
+    )
+    return plugins_payload(
+        activation,
+        profile=effective.profile_name,
+        config_origin=effective.origin.value,
+    )
+
+
+def _output() -> OutputPort:
+    return ConsoleOutput()
+
+
+@click.command("plugins")
+@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 plugins(profile: str | None, fmt: str) -> None:
+    """List plugins, whether they activated, their order, and their config.
+
+    Every discovered plugin is listed even when configuration disables it — a
+    report that hid a disabled plugin would make "why is this plugin not doing
+    anything" unanswerable, which is the opposite of what this command is for.
+
+    ``activated`` means the plugin's ``register()`` was called and returned.
+    """
+    # Imported here, not at module scope: ``commands/config.py`` attaches this
+    # command at the end of its own module body, so a module-level
+    # ``from .config import resolve_profile`` makes importing *this* module first
+    # fail with a partially-initialised-module ImportError. Deferring mirrors
+    # ``resolve_profile`` itself, which defers ``from ..app import root_profile``
+    # for the same reason.
+    from .config import resolve_profile
+
+    out = _output()
+    try:
+        payload = build_plugins_payload(profile=resolve_profile(profile))
+    except (
+        UnknownProfileError,
+        PluginError,
+        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: the resolved context, then plugins, then the order."""
+    out.key_value(
+        [
+            ("profile", payload["profile"] or "(none)"),
+            ("config origin", payload["configOrigin"] or "-"),
+            ("plugins declared", "yes" if payload["declared"] else "no"),
+        ]
+    )
+
+    out.heading("Plugins")
+    entries: list[dict[str, Any]] = payload["plugins"]
+    if not entries:
+        out.info("No plugins discovered.")
+    else:
+        out.table(
+            ["", "plugin", "version", "priority", "capabilities", "note"],
+            [
+                [
+                    "*" if entry["activated"] else "x",
+                    str(entry["name"]),
+                    str(entry["version"] or "-"),
+                    "-" if entry["priority"] is None else str(entry["priority"]),
+                    ", ".join(entry["capabilities"]) or "-",
+                    str(entry["reason"] or entry["entryPoint"] or "-"),
+                ]
+                for entry in entries
+            ],
+        )
+
+    order: list[str] = payload["activationOrder"]
+    out.heading("Activation order")
+    out.echo(" → ".join(order) if order else "(nothing activated)")
+
+    configured = [entry for entry in entries if entry["config"]]
+    if configured:
+        out.heading("Configuration")
+        out.table(
+            ["plugin", "key", "value"],
+            [
+                [str(entry["name"]), str(key), str(value)]
+                for entry in configured
+                for key, value in sorted(entry["config"].items())
+            ],
+        )
+
+
+def attach(group: click.Group) -> None:
+    """Add ``plugins`` 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(plugins)