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

katalyst_taxonomy_cli/app.py

@@ -0,0 +1,550 @@
+"""CLI application root — Click group, command registration, plugin discovery."""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Callable, Mapping, cast
+
+import click
+from katalyst_taxonomy.domain.output_formats import OUTPUT_FORMATS
+
+from . import __version__
+from .context import CliContext
+from .discovery import discover_plugin_commands
+
+if TYPE_CHECKING:
+    from katalyst_taxonomy.ports.config import ConfigPort
+
+#: Exit status for a permission denial (#216).
+#:
+#: Reserved for exactly that, and specified before the implementation existed:
+#: ``docs/planning/active/fixme3.md:529`` and ``docs/planning/active/plan6.md:237``.
+#: ``stack-tests/features/cli/34_kata_config_permissions.feature`` asserts it on
+#: every row of the rwx matrix, so it is observable behaviour, not a detail.
+PERMISSION_DENIED_EXIT_CODE = 7
+
+
+class PermissionDenied(click.ClickException):
+    """A :class:`click.ClickException` that exits 7 instead of 1.
+
+    Click's ``standalone_mode`` already renders ``ClickException`` as
+    ``Error: <message>`` on stderr and exits with ``exit_code``, so subclassing is
+    the whole implementation — no bespoke error plumbing, and the message keeps the
+    same shape as every other user error.
+    """
+
+    exit_code = PERMISSION_DENIED_EXIT_CODE
+
+
+class KataGroup(click.Group):
+    """The root group, which turns a permission denial into exit 7.
+
+    Translation happens **here**, at the single point every command's exception
+    must pass through, rather than in the eight commands that can write. Those
+    commands do not catch exceptions at all today, and adding a ``try``/``except``
+    to each is how you end up with seven that exit 7 and one that exits 1.
+
+    Group ``invoke`` calls nest, so catching on the root covers ``kata tax …``,
+    ``kata config …`` and every plugin-contributed subcommand, including ones this
+    package has never heard of.
+    """
+
+    def invoke(self, ctx: click.Context) -> Any:
+        from katalyst_taxonomy.config.profiles import UnknownProfileError
+        from katalyst_taxonomy.domain.homes import HomeError
+        from katalyst_taxonomy.domain.permissions import PermissionDeniedError
+        from katalyst_taxonomy.plugins.errors import PluginError
+        from katalyst_taxonomy.ports.backend import UnsupportedCapabilityError
+
+        try:
+            return super().invoke(ctx)
+        except PermissionDeniedError as exc:
+            raise PermissionDenied(str(exc)) from exc
+        except UnsupportedCapabilityError as exc:
+            # "Backend 'x' does not support UPDATE": a fact about the backend the user
+            # named, with the capabilities it does have — not a traceback.
+            raise click.ClickException(str(exc)) from exc
+        except PluginError as exc:
+            # A plugin that will not activate is a user-fixable configuration or
+            # environment problem, not a bug in this process — it gets the same
+            # `Error: …` shape as every other user error, not a traceback (#219).
+            raise click.ClickException(str(exc)) from exc
+        except (UnknownProfileError, HomeError) as exc:
+            # No profile selected among several, or a home that does not exist: the
+            # message says what to do, and a traceback would bury it.
+            raise click.ClickException(str(exc)) from exc
+
+
+class TaxGroup(click.Group):
+    """The ``tax`` group, which resolves plugin-contributed commands **lazily**.
+
+    Before #219 the CLI called ``_register_plugin_commands()`` at module scope, so
+    every installed plugin's group was attached before any configuration had been
+    read and ``enabled: false`` could not remove it.
+
+    Deferring, rather than removing commands after the fact, is the only option
+    that works for both observable paths:
+
+    - ``kata tax cicd --help``: Click's ``Group.invoke`` calls ``resolve_command``
+      → :meth:`get_command` **before** ``super().invoke(ctx)`` runs the group
+      callback, so there is no callback-time hook that fires early enough to
+      remove a command before it is resolved.
+    - ``kata tax --help``: the eager ``--help`` option short-circuits during
+      parameter processing, so the group callback never runs at all, and only
+      :meth:`list_commands` is reached.
+
+    Both funnel through this class, which is why the gate lives here.
+
+    Resolution is memoised per instance: Click calls ``list_commands`` and
+    ``get_command`` repeatedly while formatting help, and re-reading the
+    configuration each time would be both slow and inconsistent.
+    """
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self._plugin_commands_resolved = False
+
+    def list_commands(self, ctx: click.Context) -> list[str]:
+        self._ensure_plugin_commands(ctx)
+        return super().list_commands(ctx)
+
+    def get_command(self, ctx: click.Context, cmd_name: str) -> click.Command | None:
+        self._ensure_plugin_commands(ctx)
+        return super().get_command(ctx, cmd_name)
+
+    def _ensure_plugin_commands(self, ctx: click.Context) -> None:
+        if self._plugin_commands_resolved:
+            return
+        # Set first: a failure inside discovery must not retry on every lookup.
+        self._plugin_commands_resolved = True
+        for cmd in discover_plugin_commands(is_enabled=_enabled_plugin_predicate(ctx)):
+            self.add_command(cmd)
+
+
+#: Key the root group's ``--profile`` is stashed under in ``click.Context.meta``.
+#:
+#: ``meta`` rather than ``obj``: ``obj`` is already the ``CliContext`` that ``kata
+#: tax`` builds, and ``kata config`` deliberately has no ``CliContext`` at all
+#: (config resolution decides where ``tax`` operates, so it cannot depend on it).
+#: ``Context.meta`` is shared by every context in the invocation chain, which is
+#: exactly the propagation a root-level flag needs and the only mechanism that
+#: reaches a group Click resolved before the flag's own callback ran.
+ROOT_PROFILE_META_KEY = "katalyst.profile"
+
+
+def root_profile(ctx: click.Context) -> str | None:
+    """The root ``kata --profile`` value, or ``None``.
+
+    Read by both subcommand groups so a profile named once at the root is honoured
+    everywhere (#222 §3). A subcommand's own ``--profile`` still wins: it is the
+    more specific statement, and ``32_kata_config_profiles.feature`` asserts the
+    subcommand form directly.
+    """
+    value = ctx.meta.get(ROOT_PROFILE_META_KEY)
+    return value if isinstance(value, str) and value.strip() else None
+
+
+def _installed_katalyst_packages() -> list[tuple[str, str]]:
+    """Every installed Katalyst distribution, so a version report names the whole stack."""
+    import importlib.metadata
+
+    found: dict[str, str] = {}
+    for dist in importlib.metadata.distributions():
+        name = (dist.metadata["Name"] or "").strip()
+        if name.lower().replace("_", "-").startswith("katalyst-"):
+            found[name.lower().replace("_", "-")] = dist.version
+    found.pop("katalyst-taxonomy-cli", None)
+    return sorted(found.items())
+
+
+def _print_version(ctx: click.Context, _param: click.Parameter, value: bool) -> None:
+    if not value or ctx.resilient_parsing:
+        return
+    from katalyst_taxonomy.adapters.filesystem.homes import resolve_existing_home
+    from katalyst_taxonomy.domain.homes import HomeError, HomeOrigin
+
+    from .install import development_location, install_lines
+
+    click.echo(f"kata {__version__}")
+    for name, version in _installed_katalyst_packages():
+        click.echo(f"  {name} {version}")
+    for line in install_lines():
+        click.echo(line)
+    try:
+        home = resolve_existing_home()
+    except HomeError as exc:
+        raise click.ClickException(str(exc)) from exc
+    if home.origin is HomeOrigin.DEFAULT and development_location() is not None:
+        click.echo("home: none chosen (a development install needs --home or KATALYST_HOME)")
+    elif home.is_default:
+        click.echo(f"home: default ({_tilde(home.config_dir)})")
+    else:
+        click.echo(f"home: {home.label}")
+    ctx.exit()
+
+
+def _tilde(path: Path) -> str:
+    try:
+        return f"~/{path.relative_to(Path.home())}"
+    except ValueError:
+        return str(path)
+
+
+def _select_home(ctx: click.Context, _param: click.Parameter, value: str | None) -> None:
+    """``kata --home``: make it this process's home, and every child's (``KATALYST_HOME``)."""
+    if value is None or ctx.resilient_parsing:
+        return
+    from katalyst_taxonomy.adapters.filesystem.homes import select_home
+    from katalyst_taxonomy.domain.homes import HomeError
+
+    try:
+        select_home(value)
+    except HomeError as exc:
+        raise click.BadParameter(str(exc), ctx=ctx, param=_param) from exc
+
+
+@click.group(cls=KataGroup)
+@click.option(
+    "--home",
+    "home",
+    default=None,
+    expose_value=False,
+    is_eager=True,
+    callback=_select_home,
+    metavar="HOME",
+    help=(
+        "The Katalyst home: its config, state and cache. 'default' (the XDG locations), "
+        "a name (~/.katalyst/homes/NAME, see 'kata config home'), or an absolute path. "
+        "Overrides KATALYST_HOME."
+    ),
+)
+@click.option(
+    "--version",
+    is_flag=True,
+    expose_value=False,
+    # Not eager, so it runs after --home (which is) and reports the home chosen.
+    callback=_print_version,
+    help=(
+        "Show the kata version, every installed Katalyst package, the install (and what it "
+        "was built from) and the home, then exit."
+    ),
+)
+@click.option(
+    "--profile",
+    "profile",
+    default=None,
+    help=(
+        "Configuration profile to use, for every subcommand including 'kata config'. "
+        "Overrides KATALYST_PROFILE and spec.activeProfile."
+    ),
+)
+@click.pass_context
+def cli(ctx: click.Context, profile: str | None) -> None:
+    """Katalyst taxonomy management."""
+    # #213 put --profile on the `tax` group, which meant `kata config show` — the
+    # command whose entire job is reporting which configuration is in effect —
+    # could not be asked about a profile. #222 moves it here; the `tax` and
+    # `config` flags stay as the more specific spelling.
+    if profile is not None:
+        ctx.meta[ROOT_PROFILE_META_KEY] = profile
+    _configure_logging()
+    # A KATALYST_HOME that names no home fails every command here, before any of them
+    # reads or writes anything (`--home` was checked as it was parsed).
+    from katalyst_taxonomy.adapters.filesystem.homes import resolve_existing_home
+    from katalyst_taxonomy.domain.homes import HomeError
+
+    from .install import refuse_default_home_for_development
+
+    try:
+        home = resolve_existing_home()
+    except HomeError as exc:
+        raise click.ClickException(str(exc)) from exc
+    # `kata config` decides for itself: `kata config home …` manages homes, not uses one.
+    # `kata self` updates the install and uses no home.
+    if ctx.invoked_subcommand not in ("config", "self"):
+        refuse_default_home_for_development(home)
+
+
+_logging_configured = False
+
+
+def _configure_logging() -> None:
+    """Show warnings and errors on stderr; KATALYST_LOG_LEVEL (e.g. DEBUG) shows more.
+
+    loguru's default handler prints everything from DEBUG up, which buried a command's own
+    output under the services' progress lines. Only that default handler is replaced, once,
+    so handlers a caller added (a test capturing logs) are left alone.
+    """
+    global _logging_configured
+    if _logging_configured:
+        return
+    import os
+
+    from loguru import logger
+
+    try:
+        logger.remove(0)
+    except ValueError:
+        return
+    level = os.environ.get("KATALYST_LOG_LEVEL", "WARNING").upper()
+    logger.add(sys.stderr, level=level, format="<level>{level}</level>: {message}")
+    _logging_configured = True
+
+
+@cli.command("tui")
+def tui_cmd() -> None:
+    """Launch the interactive terminal UI."""
+    try:
+        subprocess.run(
+            [sys.executable, "-m", "katalyst_taxonomy_tui"],
+            check=True,
+        )
+    except (subprocess.CalledProcessError, FileNotFoundError) as e:
+        click.echo(f"Error launching TUI: {e}", err=True)
+        raise SystemExit(1) from e
+
+
+@cli.group("tax", cls=TaxGroup)
+@click.option(
+    "--format",
+    "output_format",
+    type=click.Choice(OUTPUT_FORMATS),
+    default=None,
+    help="Output format.",
+)
+@click.option("--verbose", is_flag=True, help="Enable verbose output.")
+@click.option(
+    "--profile",
+    "profile",
+    default=None,
+    help=(
+        "Configuration profile to use. Overrides KATALYST_PROFILE and "
+        "spec.activeProfile. See 'kata config profile list'."
+    ),
+)
+@click.pass_context
+def tax(
+    ctx: click.Context,
+    output_format: str | None,
+    verbose: bool,
+    profile: str | None,
+) -> None:
+    """Taxonomy operations.
+
+    Everything starts from the user config file: the repositories are the filesystem
+    backends it declares. Commands that work on one repository take --backend NAME;
+    without it, the profile's only filesystem backend, else the one the current
+    directory is inside, is used.
+    """
+    ctx.ensure_object(dict)
+    profile = profile or root_profile(ctx)
+    ctx.obj = CliContext.build(
+        cwd=Path.cwd().resolve(),
+        output_format=_resolve_output_format(output_format),
+        verbose=verbose,
+        profile=profile,
+    )
+    _register_source_providers(profile)
+    if ctx.invoked_subcommand == "plugin":
+        # `kata tax plugin remove` is how a broken source plugin is taken out; a plugin
+        # that will not activate must not stop the command that removes it.
+        from katalyst_taxonomy.plugins.errors import PluginError
+
+        try:
+            _activate_plugins(profile=profile)
+        except PluginError as exc:
+            click.echo(f"Warning: plugins not activated: {exc}", err=True)
+        return
+    _activate_plugins(profile=profile)
+
+
+def _resolve_output_format(output_format: str | None) -> str | None:
+    """The effective output format: ``--format``, else ``spec.outputFormat``.
+
+    A malformed config file must not take down every taxonomy command; ``kata config
+    show`` is where the parse error gets reported.
+    """
+    from katalyst_taxonomy.adapters.filesystem.config import FilesystemConfigAdapter
+    from katalyst_taxonomy.domain.config_files import CONFIG_FILE
+    from katalyst_taxonomy.services.layered_config import LayeredConfigService
+
+    if output_format is not None:
+        return output_format
+    service = LayeredConfigService(FilesystemConfigAdapter())
+    try:
+        resolved = service.resolve_mapping(CONFIG_FILE, service.context())
+    except ValueError:
+        return None
+
+    spec: object = resolved.data.get("spec")
+    if isinstance(spec, Mapping):
+        configured: object = cast("Mapping[str, object]", spec).get("outputFormat")
+        if isinstance(configured, str) and configured:
+            return configured
+    return None
+
+
+def _register_source_providers(profile: str | None) -> None:
+    """Make the bundles and plugins ``config.yaml`` declares with a source discoverable.
+
+    Registered once per process before any command runs, and before plugin activation:
+    the configuration is what says they exist. Each is materialised from the shared
+    source cache (:mod:`katalyst_taxonomy.services.source_providers`).
+
+    A source bundle has to reach *three* consumers, not one: the schema registry (so
+    its node kinds exist), the template resolver (so its creation and scaffold
+    templates resolve), and the source report — all through the single config-aware
+    discovery factory the provider registers with.
+    """
+    from katalyst_taxonomy.services.source_providers import ensure_source_providers
+
+    ensure_source_providers(True, profile=profile)
+
+
+# ---------------------------------------------------------------------------
+# Plugin activation (#219)
+# ---------------------------------------------------------------------------
+def _config_port() -> ConfigPort:
+    from katalyst_taxonomy.adapters.filesystem.config import FilesystemConfigAdapter
+
+    return FilesystemConfigAdapter()
+
+
+def _enabled_plugin_predicate(ctx: click.Context) -> Callable[[str], bool]:
+    """Build the enabled-plugin predicate :class:`TaxGroup` gates commands with.
+
+    Reads ``--profile`` from *ctx* when it has been parsed. On the ``kata tax --help``
+    path it has not: ``--help`` is eager, so it fires before the other options are
+    processed and ``ctx.params`` is empty; the root ``--profile`` and the documented
+    precedence then decide.
+
+    Never raises — see :func:`katalyst_taxonomy.plugins.startup.plugin_selection_for`.
+    A malformed configuration must not make ``kata tax --help`` unusable, and the
+    fallback registers every command, which is the pre-#219 behaviour.
+    """
+    from katalyst_taxonomy.plugins.startup import plugin_selection_for
+
+    raw_profile: object = ctx.params.get("profile")
+    profile = raw_profile if isinstance(raw_profile, str) else root_profile(ctx)
+
+    return plugin_selection_for(_config_port(), profile=profile).is_enabled
+
+
+def _activate_plugins(*, profile: str | None) -> None:
+    """Give plugins a host (#219, part 1).
+
+    Before this, ``PluginRegistry.activate_all()`` was never called anywhere in
+    ``src/`` — no plugin had ever received a ``PluginContext`` in production. This
+    is the CLI's half of fixing that, placed in the ``tax`` callback next to
+    ``_register_source_providers`` because both are per-invocation
+    startup wiring that every ``tax`` subcommand needs.
+
+    A plugin that will not activate fails the command: see
+    ``katalyst_taxonomy/plugins/errors.py`` for where the line between loud and
+    tolerant is drawn, and :meth:`KataGroup.invoke` for how the failure is rendered.
+    """
+    from katalyst_taxonomy.plugins.startup import activate_plugins_for
+
+    activate_plugins_for(_config_port(), profile=profile)
+
+
+def _register_core_commands() -> None:
+    """Register all built-in commands."""
+    from .commands import (
+        api,
+        backend,
+        bundle,
+        clone,
+        create,
+        deps,
+        diff,
+        drafts,
+        export,
+        init,
+        kinds,
+        lifecycle,
+        lint,
+        plugin,
+        promote,
+        query,
+        relate,
+        relocate,
+        remove,
+        resolve,
+        rollback,
+        self_update,
+        show,
+        status,
+        sync,
+        update,
+        versions,
+    )
+    from .commands import (
+        config as config_cmd,
+    )
+    from .commands import (
+        core as core_cmd,
+    )
+
+    # `config` is top-level, not under `tax`: config resolution decides where
+    # `tax` operates, so it cannot live inside the thing it configures (#212).
+    cli.add_command(config_cmd.config)
+    # How this machine's REST API may be reached. Top-level for the same reason: it is
+    # about the server, not the taxonomy it serves.
+    cli.add_command(api.api)
+    cli.add_command(self_update.self_group)
+    # katalyst-core, the LinkML base every schema module imports. Top-level: it is
+    # about the schema, not one taxonomy.
+    cli.add_command(core_cmd.core)
+
+    tax.add_command(init.init)
+    tax.add_command(create.create)
+    tax.add_command(clone.clone)
+    tax.add_command(show.show)
+    tax.add_command(kinds.kinds)
+    tax.add_command(lint.lint)
+    tax.add_command(deps.deps)
+    tax.add_command(status.status)
+    tax.add_command(rollback.rollback)
+    tax.add_command(sync.sync)
+    tax.add_command(relate.relate)
+    tax.add_command(relate.unrelate)
+    tax.add_command(relocate.rename)
+    tax.add_command(relocate.move)
+    tax.add_command(update.update)
+    tax.add_command(lifecycle.delete)
+    tax.add_command(lifecycle.restore)
+    tax.add_command(lifecycle.import_)
+    tax.add_command(query.query)
+    tax.add_command(resolve.resolve)
+    tax.add_command(promote.promote)
+    tax.add_command(diff.diff)
+    tax.add_command(drafts.drafts)
+    tax.add_command(versions.versions)
+    tax.add_command(bundle.bundle)
+    tax.add_command(plugin.plugin)
+    tax.add_command(export.export)
+    tax.add_command(backend.backend)
+    tax.add_command(remove.remove)
+
+
+def resolve_plugin_commands() -> None:
+    """Force :class:`TaxGroup`'s lazy plugin-command resolution now.
+
+    Plugin commands are resolved on first lookup, not at import (#219), which is
+    what lets ``enabled: false`` remove one. Anything that needs the *whole*
+    command tree without invoking Click — the static signature guard in
+    ``cli/tests/test_command_signatures.py``, for one — calls this. Memoised, so
+    calling it and then running a command does not resolve twice.
+    """
+    tax.list_commands(click.Context(tax))
+
+
+# Wire everything up at import time.
+#
+# Core commands only: plugin-contributed commands are resolved by `TaxGroup` on
+# first lookup, because `spec.plugins` has not been read yet at import time and
+# gating a command needs it (#219).
+_register_core_commands()

katalyst_taxonomy_cli/commands/__init__.py

@@ -0,0 +1 @@
+"""CLI commands package."""

katalyst_taxonomy_cli/commands/api.py

@@ -0,0 +1,104 @@
+"""``kata api`` — how this machine's taxonomy REST API may be reached.
+
+::
+
+    kata api cors list                 the browser origins allowed to call the API
+    kata api cors add ORIGIN           allow one (scheme://host[:port], exact)
+    kata api cors remove ORIGIN        stop allowing it
+
+CORS is closed unless an origin is allowed. The allowlist is kept in the state home
+(``api.json``, beside the API's ``server.json``) and read by a running API on every browser
+request, so a change applies at once. Bard needs no entry: its pages call Bard's own
+server, which calls the API.
+
+Every request to the API carries its token (``Authorization: Bearer``); a client on this
+machine reads it from ``server.json``, one elsewhere is given it in ``KATALYST_API_TOKEN``.
+"""
+
+from __future__ import annotations
+
+import click
+
+from ..output import ConsoleOutput, OutputPort
+
+__all__ = ["api"]
+
+_FORMAT_CHOICE = click.Choice(["text", "json"])
+
+_APPLIES = "A running API on this machine applies it at once."
+
+
+def _output() -> OutputPort:
+    return ConsoleOutput()
+
+
+@click.group("api")
+def api() -> None:
+    """How the taxonomy REST API may be reached: its CORS allowlist."""
+
+
+@api.group("cors")
+def cors() -> None:
+    """The browser origins allowed to call the API. Closed unless one is added."""
+
+
+@cors.command("list")
+@click.option("--format", "fmt", type=_FORMAT_CHOICE, default="text")
+def cors_list(fmt: str) -> None:
+    """List the allowed origins."""
+    from katalyst_taxonomy.adapters.orchestration import api_cors_service
+
+    service = api_cors_service()
+    try:
+        origins = service.list()
+    except ValueError as exc:
+        raise click.ClickException(str(exc)) from exc
+    out = _output()
+    if fmt == "json":
+        out.json_out({"origins": list(origins), "path": str(service.location)})
+        return
+    if not origins:
+        out.info("CORS is closed: no browser origin may call the API.")
+        return
+    for origin in origins:
+        out.echo(origin)
+
+
+@cors.command("add")
+@click.argument("origin")
+@click.option("--format", "fmt", type=_FORMAT_CHOICE, default="text")
+def cors_add(origin: str, fmt: str) -> None:
+    """Allow pages from ORIGIN (scheme://host[:port]) to call the API."""
+    from katalyst_taxonomy.adapters.orchestration import api_cors_service
+
+    try:
+        change = api_cors_service().add(origin)
+    except ValueError as exc:
+        raise click.ClickException(str(exc)) from exc
+    out = _output()
+    if fmt == "json":
+        out.json_out(change.as_payload())
+    elif change.changed:
+        out.success(f"Allowed {change.origin}. {_APPLIES}")
+    else:
+        out.info(f"{change.origin} is already allowed.")
+
+
+@cors.command("remove")
+@click.argument("origin")
+@click.option("--format", "fmt", type=_FORMAT_CHOICE, default="text")
+def cors_remove(origin: str, fmt: str) -> None:
+    """Stop allowing pages from ORIGIN to call the API."""
+    from katalyst_taxonomy.adapters.orchestration import api_cors_service
+
+    try:
+        change = api_cors_service().remove(origin)
+    except ValueError as exc:
+        raise click.ClickException(str(exc)) from exc
+    out = _output()
+    if fmt == "json":
+        out.json_out(change.as_payload())
+    elif change.changed:
+        out.success(f"Removed {change.origin}. {_APPLIES}")
+    else:
+        out.info(f"{change.origin} was not allowed.")