katalyst-taxonomy-cli 2.0.1a1__tar.gz

katalyst_taxonomy_cli-2.0.1a1/.gitignore

@@ -0,0 +1,123 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+# Not a Python build directory: Bard's SPA keeps shared helpers (utils.ts, download.ts) in
+# src/lib, and ignoring it left a fresh clone unable to build or test the SPA.
+!plugins/bard/web/src/lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy / pyright
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.pyright/
+
+# Ruff
+.ruff_cache/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Local configuration
+*.local
+
+# Browser/Playwright state files
+browser-state-*.json
+
+# Agent harness scratch (run exhaust, never the design bundle)
+.opencode/sessions/
+.opencode/analysis/
+.opencode/package-lock.json
+
+# Build artifacts
+site/
+stack-tests/cucumber-report/
+stack-tests/test-results/
+
+# Generated artifacts (rebuild with `just generate-schemas`)
+taxonomy/src/katalyst_taxonomy/engine/generated/
+.worktrees/
+.plan-74-75-76-77.md
+.HANDOFF-scaffolding-wiring.md
+.HANDOFF-2-cicd-migration.md
+.HANDOFF-action-execution-fixes.md
+.HANDOFF-bdd-coverage.md
+.HANDOFF-*.md
+docs/superpowers/
+
+# Node dependencies — installed, never committed
+node_modules/

katalyst_taxonomy_cli-2.0.1a1/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.5
+Name: katalyst-taxonomy-cli
+Version: 2.0.1a1
+Summary: CLI for katalyst-taxonomy — the kata command
+Author: eSimplicity
+License: Proprietary
+Requires-Python: >=3.12
+Requires-Dist: click>=8.1
+Requires-Dist: katalyst-core<1,>=0.1
+Requires-Dist: katalyst-engine<6,>=5
+Requires-Dist: katalyst-taxonomy-mcp<5,>=4
+Requires-Dist: katalyst-taxonomy<6,>=5

katalyst_taxonomy_cli-2.0.1a1/pyproject.toml

@@ -0,0 +1,31 @@
+[project]
+name = "katalyst-taxonomy-cli"
+version = "2.0.1a1"
+description = "CLI for katalyst-taxonomy — the kata command"
+license = { text = "Proprietary" }
+requires-python = ">=3.12"
+authors = [
+    { name = "eSimplicity" }
+]
+dependencies = [
+    # Bounded: unbounded, this resolved against the published katalyst-taxonomy 3.x and
+    # katalyst-taxonomy-mcp 3.2.0, which predate the config-rooted runtime the CLI is.
+    "katalyst-taxonomy>=5,<6",
+    "katalyst-taxonomy-mcp>=4,<5",
+    "katalyst-engine>=5,<6",
+    "click>=8.1",
+    "katalyst-core>=0.1,<1",
+]
+
+[project.scripts]
+kata = "katalyst_taxonomy_cli.__main__:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/katalyst_taxonomy_cli"]
+
+[tool.hatch.build.targets.wheel.sources]
+"src" = ""

katalyst_taxonomy_cli-2.0.1a1/src/katalyst_taxonomy_cli/__init__.py

@@ -0,0 +1,14 @@
+"""Katalyst CLI package."""
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _dist_version
+
+#: This package's own distribution: the one ``kata`` runs from.
+DISTRIBUTION = "katalyst-taxonomy-cli"
+
+try:
+    __version__ = _dist_version(DISTRIBUTION)
+except PackageNotFoundError:  # pragma: no cover - source tree without an install
+    __version__ = "0.0.0+unknown"
+
+__all__ = ["DISTRIBUTION", "__version__"]

katalyst_taxonomy_cli-2.0.1a1/src/katalyst_taxonomy_cli/__main__.py

@@ -0,0 +1,12 @@
+"""Katalyst CLI — entry point for the `kata` command."""
+
+from .app import cli
+
+
+def main() -> None:
+    """Entry point registered as `kata` script."""
+    cli()
+
+
+if __name__ == "__main__":
+    main()

katalyst_taxonomy_cli-2.0.1a1/src/katalyst_taxonomy_cli/_wiring.py

@@ -0,0 +1,248 @@
+"""Internal wiring — factory functions for service instantiation.
+
+This is the CLI's composition root for services that need adapter wiring.
+Commands should never import adapters directly — they get services from here.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import click
+
+if TYPE_CHECKING:  # pragma: no cover - typing only
+    from katalyst_taxonomy.config.backends import BackendRegistry
+    from katalyst_taxonomy.ports.backend import PromotableBackend, TaxonomyBackend
+
+    from .context import CliContext
+
+
+def create_bundle_service():  # noqa: ANN201
+    """Wire up BundleService with the concrete bundle sources."""
+    from katalyst_taxonomy.services.bundle_service import BundleService
+    from katalyst_taxonomy.sources.bundle_sources import default_bundle_sources
+
+    return BundleService(sources=list(default_bundle_sources()))
+
+
+def create_plugin_install_service():  # noqa: ANN201
+    """Wire up PluginInstallService, recording in the user config file."""
+    from katalyst_taxonomy.services.plugin_install import plugin_install_service
+
+    return plugin_install_service()
+
+
+def create_sync_service(name: str, root: Path, *, profile: str | None = None):  # noqa: ANN201
+    """Wire up SyncService with concrete adapters.
+
+    The source is one repository — the filesystem backend *name*, rooted at *root* —
+    because sync's job is "push what is on disk". It comes from the registry, so it is
+    named (the nodes it syncs carry their real backend) and subject to the active
+    profile's ``r`` bit (#216). Targets come from the registry and are gated on ``w``
+    by construction.
+    """
+    from katalyst_taxonomy.adapters.databricks.sync import DatabricksAppender
+    from katalyst_taxonomy.config.backends import load_backends
+    from katalyst_taxonomy.services.sync import SyncService
+
+    registry = load_backends(root, profile=profile)
+    return SyncService(
+        source=registry.get(name),
+        registry=registry,
+        base_path=root,
+        appenders=(DatabricksAppender(),),
+    )
+
+
+# ---------------------------------------------------------------------------
+# Backend resolution
+# ---------------------------------------------------------------------------
+@dataclass(frozen=True, slots=True)
+class ResolvedBackend:
+    """The one backend a command operates on.
+
+    Attributes:
+        registry: The registry, so a command can still address a second backend.
+        name: The backend the command named.
+        backend: The constructed backend.
+        fqtn: The address with its ``backend:`` prefix and ``#kind`` selector stripped, or
+            ``""`` when the command supplied no address. This is what a command passes
+            downstream.
+        selector: The ``#kind`` narrowing, or ``None``.
+    """
+
+    registry: BackendRegistry
+    name: str
+    backend: TaxonomyBackend
+    fqtn: str = ""
+    selector: str | None = None
+
+    @property
+    def address(self) -> str:
+        """The FQTN with its ``#kind`` selector, as the services resolve it."""
+        return f"{self.fqtn}#{self.selector}" if self.selector else self.fqtn
+
+
+@dataclass(frozen=True, slots=True)
+class ResolvedRead:
+    """The backends a listing reads, and the address it was narrowed to.
+
+    Attributes:
+        registry: The registry.
+        sources: ``(name, backend)`` pairs — one when the command named a backend, otherwise
+            every backend the active profile lists.
+        fqtn: The address's FQTN with its prefix and selector stripped, or ``""``.
+        selector: The ``#kind`` narrowing, or ``None``.
+    """
+
+    registry: BackendRegistry
+    sources: tuple[tuple[str, TaxonomyBackend], ...]
+    fqtn: str = ""
+    selector: str | None = None
+
+
+def load_registry(ctx: CliContext) -> BackendRegistry:
+    """Load the backend registry for *ctx*, honoring the active profile."""
+    from katalyst_taxonomy.config.backends import load_backends
+
+    return load_backends(ctx.cwd, profile=ctx.profile)
+
+
+def _registry(ctx: CliContext) -> BackendRegistry:
+    try:
+        return load_registry(ctx)
+    except Exception as exc:  # noqa: BLE001 - config errors are user errors, not tracebacks
+        raise click.ClickException(str(exc)) from exc
+
+
+def _named(registry: BackendRegistry, target: str | None, address: str) -> tuple[str | None, str]:
+    """The backend named by *address* or *target*, and the bare FQTN.
+
+    A prefix and ``--backend`` that disagree is an error rather than one silently
+    winning: the command was told two different stores.
+    """
+    if address:
+        parsed = registry.address(address)
+        if target and target != parsed.backend:
+            raise click.ClickException(
+                f"{address!r} names backend {parsed.backend!r} but --backend is {target!r}."
+            )
+        return parsed.backend, parsed.fqtn
+    if target:
+        if target not in registry.profile_backends():
+            from katalyst_taxonomy.config.routing import UnknownBackendError
+
+            raise UnknownBackendError(target, registry.profile_backends())
+        return target, ""
+    return None, ""
+
+
+def resolve_backend(
+    ctx: CliContext,
+    target: str | None = None,
+    *,
+    address: str | None = None,
+) -> ResolvedBackend:
+    """The single backend a command writes to or operates on. It must be named.
+
+    Named by the address's ``backend:`` prefix, or by ``--backend``. Neither is an error
+    listing the profile's backends: there is no default, so nothing is chosen for the
+    caller.
+
+    Raises:
+        click.ClickException: If the configuration is invalid, nothing names a backend, the
+            address is unprefixed, or the backend named is not one the profile reads.
+    """
+    from katalyst_taxonomy.config.routing import BackendAddressError
+    from katalyst_taxonomy.engine.qualification import split_kind_selector
+
+    registry = _registry(ctx)
+    routable, selector = split_kind_selector(address or "")
+    try:
+        name, fqtn = _named(registry, target, routable)
+        if name is None:
+            reads = ", ".join(registry.profile_backends())
+            raise click.ClickException(
+                f"Name the backend to use with --backend. This profile reads: {reads}."
+            )
+        backend = registry.get(name)
+    except BackendAddressError as exc:
+        raise click.ClickException(str(exc)) from exc
+    return ResolvedBackend(
+        registry=registry, name=name, backend=backend, fqtn=fqtn, selector=selector
+    )
+
+
+def resolve_read(
+    ctx: CliContext,
+    target: str | None = None,
+    *,
+    address: str | None = None,
+) -> ResolvedRead:
+    """The backends a listing reads: the one named, or all of the profile's.
+
+    An address still has to carry a prefix — an unprefixed name is an error, not a search
+    across backends.
+
+    Raises:
+        click.ClickException: If the configuration is invalid, the address is unprefixed,
+            or a named backend is unknown or unavailable.
+    """
+    from katalyst_taxonomy.config.routing import BackendAddressError
+    from katalyst_taxonomy.engine.qualification import split_kind_selector
+
+    registry = _registry(ctx)
+    routable, selector = split_kind_selector(address or "")
+    try:
+        name, fqtn = _named(registry, target, routable)
+        sources = registry.read_set(name)
+    except BackendAddressError as exc:
+        raise click.ClickException(str(exc)) from exc
+    return ResolvedRead(registry=registry, sources=sources, fqtn=fqtn, selector=selector)
+
+
+def resolve_promotable_backend(
+    ctx: CliContext,
+    target: str | None = None,
+    *,
+    address: str | None = None,
+    capability: str = "promotion workflows",
+    operation: str | None = None,
+) -> tuple[str, PromotableBackend, str]:
+    """Resolve a backend that must satisfy :class:`PromotableBackend`.
+
+    A separate function rather than a ``requires=`` parameter on
+    :func:`resolve_backend` so the return type is *narrowed* — the five promotion
+    commands then call ``backend.promote_node`` and friends with no ``isinstance``
+    dance and no loss of type information, which a generic ``type[Any]`` guard
+    would have thrown away.
+
+    Args:
+        ctx: The CLI context.
+        target: Explicit ``--backend`` name.
+        address: A ``backend:fqtn`` the command operates on. Its prefix names the backend.
+        capability: Operation name used in the error message.
+        operation: When the command *changes* the backend (``promote``, ``rollback``),
+            its name — a read-only backend is then refused with ``ReadOnlyBackendError``
+            rather than "does not support promotion workflows", which is true but not
+            the reason.
+
+    Returns:
+        The resolved name, the narrowed backend, and the bare FQTN (``""`` without one).
+
+    Raises:
+        SystemExit: With status 1 if the backend does not support *capability*.
+    """
+    from katalyst_taxonomy.ports.backend import PromotableBackend as _Promotable
+
+    resolved = resolve_backend(ctx, target, address=address)
+    if operation is not None:
+        from katalyst_taxonomy.ports.backend import require_writable
+
+        require_writable(resolved.backend, operation, target=resolved.fqtn)
+    if not isinstance(resolved.backend, _Promotable):
+        ctx.output.echo(f"Error: Backend '{resolved.name}' does not support {capability}.")
+        raise SystemExit(1)
+    return resolved.name, resolved.backend, resolved.fqtn