katalyst-plugin-harness 0.1.1a1__py3-none-any.whl

katalyst_plugin_harness/__init__.py

@@ -0,0 +1,7 @@
+"""Katalyst harness plugin: the taxonomy's agents and skills, installed into each
+coding-agent harness (OpenCode, Claude Code, ...) with OpenPackage.
+"""
+
+from katalyst_plugin_harness.plugin import HarnessPlugin
+
+__all__ = ["HarnessPlugin"]

katalyst_plugin_harness/adapters/__init__.py

@@ -0,0 +1 @@
+"""The harness plugin's adapters: OpenPackage, the package cache, Jinja, the taxonomy."""

katalyst_plugin_harness/adapters/jinja_settings.py

@@ -0,0 +1,61 @@
+"""Jinja: a harness's settings for one agent or skill, rendered and read as YAML."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any, cast
+
+import yaml
+from jinja2 import Environment, FileSystemLoader, StrictUndefined, TemplateError
+
+from katalyst_plugin_harness.domain.errors import HarnessError
+
+__all__ = ["JinjaSettingsRenderer"]
+
+
+class JinjaSettingsRenderer:
+    """Implements :class:`~katalyst_plugin_harness.ports.SettingsRenderer`.
+
+    Undefined names are errors (``StrictUndefined``): a template naming a field the node
+    does not have fails instead of rendering an empty value. An empty rendering is no
+    settings.
+    """
+
+    def __init__(self) -> None:
+        self._environments: dict[Path, Environment] = {}
+
+    def _environment(self, directory: Path) -> Environment:
+        environment = self._environments.get(directory)
+        if environment is None:
+            environment = Environment(
+                loader=FileSystemLoader(str(directory)),
+                undefined=StrictUndefined,
+                keep_trailing_newline=True,
+                autoescape=False,
+            )
+            self._environments[directory] = environment
+        return environment
+
+    def render(self, template: Path, context: Mapping[str, object]) -> Mapping[str, object]:
+        if not template.is_file():
+            raise HarnessError(f"harness template not found: {template}")
+        try:
+            text = (
+                self._environment(template.parent)
+                .get_template(template.name)
+                .render(**dict(context))
+            )
+        except TemplateError as exc:
+            raise HarnessError(f"{template}: {exc}") from exc
+        try:
+            loaded: object = yaml.safe_load(text)
+        except yaml.YAMLError as exc:
+            raise HarnessError(f"{template} did not render YAML: {exc}") from exc
+        if loaded is None:
+            return {}
+        if not isinstance(loaded, dict):
+            raise HarnessError(
+                f"{template} must render a mapping of settings, got {type(loaded).__name__}"
+            )
+        return cast("dict[str, Any]", loaded)

katalyst_plugin_harness/adapters/opkg.py

@@ -0,0 +1,214 @@
+"""OpenPackage (``opkg``) run as a subprocess: the pinned CLI, fetched with npm on first use.
+
+Where ``opkg`` comes from, in order: ``KATALYST_OPKG`` (a path to an executable — for
+machines whose endpoint security only allows an approved binary, and for offline use),
+then the pinned version installed in the Katalyst cache
+(``<cache home>/harness/opkg/<version>``), fetched there with npm the first time. An
+``opkg`` on ``PATH`` is deliberately not used: the pinned one is what is tested.
+
+What OpenPackage installed is read from its index (``.openpackage/openpackage.index.yml``
+in the workspace, or in the home directory for a global install), which it documents as
+the record of every file a package put where.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+from collections.abc import Callable, Mapping
+from pathlib import Path
+from typing import Any, cast
+
+import yaml
+
+from katalyst_plugin_harness.domain.errors import (
+    OpenPackageError,
+    OpenPackageUnavailableError,
+)
+from katalyst_plugin_harness.domain.model import Scope
+
+__all__ = [
+    "OPKG_ENV",
+    "OPKG_VERSION",
+    "SubprocessOpenPackage",
+    "opkg_cache_dir",
+    "resolve_opkg",
+]
+
+#: The OpenPackage CLI the harness plugin is built and tested against.
+OPKG_VERSION = "0.9.5"
+
+#: Overrides where ``opkg`` comes from: a path to the executable.
+OPKG_ENV = "KATALYST_OPKG"
+
+_INDEX = Path(".openpackage") / "openpackage.index.yml"
+
+#: How much of a failed run's output an error carries.
+_TAIL_LINES = 30
+
+
+def opkg_cache_dir(version: str = OPKG_VERSION) -> Path:
+    """Where the pinned ``opkg`` is installed: ``<cache home>/harness/opkg/<version>``."""
+    from katalyst_taxonomy.domain.homes import resolve_home
+
+    return resolve_home().cache_dir / "harness" / "opkg" / version
+
+
+def _opkg_in(prefix: Path) -> Path | None:
+    binary = prefix / "node_modules" / ".bin" / "opkg"
+    return binary if binary.is_file() else None
+
+
+def _fetch_opkg(
+    prefix: Path, version: str, echo: Callable[[str], None], which: Callable[[str], str | None]
+) -> Path:
+    npm = which("npm")
+    if npm is None:
+        raise OpenPackageUnavailableError(
+            f"OpenPackage (opkg {version}) is needed to install into a harness, and npm, "
+            f"which fetches it, is not on PATH (it comes with Node.js 20+). Install Node.js, "
+            f"or set {OPKG_ENV} to an opkg executable."
+        )
+    echo(f"Fetching OpenPackage {version} into {prefix} (first run only)…")
+    prefix.mkdir(parents=True, exist_ok=True)
+    result = subprocess.run(
+        [
+            npm,
+            "install",
+            "--prefix",
+            str(prefix),
+            "--no-save",
+            "--no-audit",
+            "--no-fund",
+            f"opkg@{version}",
+        ],
+        check=False,
+        capture_output=True,
+        text=True,
+        stdin=subprocess.DEVNULL,
+    )
+    binary = _opkg_in(prefix)
+    if result.returncode != 0 or binary is None:
+        raise OpenPackageUnavailableError(
+            f"Fetching OpenPackage {version} failed (npm exit {result.returncode}): "
+            f"{_tail(result.stdout + result.stderr)}\n"
+            f"Set {OPKG_ENV} to an opkg executable to use one you already have."
+        )
+    return binary
+
+
+def resolve_opkg(
+    *,
+    env: Mapping[str, str] | None = None,
+    echo: Callable[[str], None] = print,
+    which: Callable[[str], str | None] = shutil.which,
+    cache_dir: Path | None = None,
+) -> Path:
+    """The ``opkg`` executable to run: ``KATALYST_OPKG``, else the pinned one (fetched).
+
+    Raises:
+        OpenPackageUnavailableError: ``KATALYST_OPKG`` names no file, or there is no
+            cached copy and no npm to fetch one with.
+    """
+    environ = os.environ if env is None else env
+    explicit = environ.get(OPKG_ENV, "").strip()
+    if explicit:
+        chosen = Path(explicit).expanduser()
+        if not chosen.is_file():
+            raise OpenPackageUnavailableError(f"{OPKG_ENV} names no file: {chosen}")
+        return chosen
+    prefix = cache_dir if cache_dir is not None else opkg_cache_dir()
+    cached = _opkg_in(prefix)
+    if cached is not None:
+        return cached
+    return _fetch_opkg(prefix, OPKG_VERSION, echo, which)
+
+
+def _tail(output: str) -> str:
+    lines = [line for line in output.strip().splitlines() if line.strip()]
+    return "\n".join(lines[-_TAIL_LINES:])
+
+
+class SubprocessOpenPackage:
+    """Implements :class:`~katalyst_plugin_harness.ports.OpenPackage` with the ``opkg`` CLI.
+
+    *resolve* finds the executable; it is called on the first install or uninstall, so
+    reading what is installed (``status``, a dry run) never fetches anything. *home* is
+    where a global install goes (default: the user's home).
+    """
+
+    def __init__(
+        self,
+        resolve: Callable[[], Path] = resolve_opkg,
+        *,
+        home: Path | None = None,
+        env: Mapping[str, str] | None = None,
+    ) -> None:
+        self._resolve = resolve
+        self._executable: Path | None = None
+        self._home = home
+        self._env = env
+
+    def _home_dir(self) -> Path:
+        return self._home if self._home is not None else Path.home()
+
+    def _run(self, args: list[str], *, scope: Scope, workspace: Path) -> None:
+        if self._executable is None:
+            self._executable = self._resolve()
+        command = [str(self._executable), *args, *(["--global"] if scope == "global" else [])]
+        environ = {**(os.environ if self._env is None else self._env), "NO_COLOR": "1"}
+        if self._home is not None:
+            environ["HOME"] = str(self._home)
+        try:
+            result = subprocess.run(
+                command,
+                cwd=workspace,
+                env=environ,
+                check=False,
+                capture_output=True,
+                text=True,
+                stdin=subprocess.DEVNULL,
+            )
+        except OSError as exc:
+            raise OpenPackageError(f"could not run {command[0]}: {exc}") from exc
+        if result.returncode != 0:
+            raise OpenPackageError(
+                f"opkg {args[0]} failed (exit {result.returncode}):\n"
+                f"{_tail(result.stdout + result.stderr)}"
+            )
+
+    def install(self, package_dir: Path, *, platform: str, scope: Scope, workspace: Path) -> None:
+        self._run(
+            ["install", str(package_dir), "--platforms", platform, "--force"],
+            scope=scope,
+            workspace=workspace,
+        )
+
+    def uninstall(self, package: str, *, scope: Scope, workspace: Path) -> None:
+        self._run(["uninstall", package], scope=scope, workspace=workspace)
+
+    def installed(
+        self, package: str, *, scope: Scope, workspace: Path
+    ) -> Mapping[str, tuple[str, ...]] | None:
+        index = (self._home_dir() if scope == "global" else workspace) / _INDEX
+        try:
+            loaded: object = yaml.safe_load(index.read_text(encoding="utf-8"))
+        except FileNotFoundError:
+            return None
+        except (OSError, yaml.YAMLError) as exc:
+            raise OpenPackageError(f"cannot read OpenPackage's index {index}: {exc}") from exc
+        packages = _mapping(_mapping(loaded).get("packages"))
+        if package not in packages:
+            return None
+        files = _mapping(_mapping(packages[package]).get("files"))
+        return {
+            str(source): tuple(str(t) for t in cast("list[Any]", targets))
+            if isinstance(targets, list)
+            else ()
+            for source, targets in files.items()
+        }
+
+
+def _mapping(value: object) -> dict[str, Any]:
+    return cast("dict[str, Any]", value) if isinstance(value, dict) else {}

katalyst_plugin_harness/adapters/packages.py

@@ -0,0 +1,62 @@
+"""Packages written to the Katalyst cache, one directory per harness of one repository.
+
+``<cache home>/harness/packages/<repository key>/<harness>/``: the key is derived from
+the repository's path, so two repositories with a harness of the same name do not share a
+package. A markdown file is its generated frontmatter followed by the body file's text;
+every other file is copied as it is.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import shutil
+from pathlib import Path
+
+import yaml
+
+from katalyst_plugin_harness.domain.package import MANIFEST, Package
+
+__all__ = ["CachePackageStore", "markdown", "package_root"]
+
+
+def package_root(workspace: Path) -> Path:
+    """Where the packages of the repository at *workspace* are built."""
+    from katalyst_taxonomy.domain.homes import resolve_home
+
+    key = hashlib.sha256(str(workspace.resolve()).encode()).hexdigest()[:16]
+    return resolve_home().cache_dir / "harness" / "packages" / key
+
+
+def _yaml(data: object) -> str:
+    return yaml.safe_dump(data, sort_keys=False, width=100, allow_unicode=True)
+
+
+def markdown(frontmatter: object, body: str) -> str:
+    """A markdown file: ``---`` frontmatter ``---``, a blank line, then *body*."""
+    return f"---\n{_yaml(frontmatter)}---\n\n{body.lstrip(chr(10))}"
+
+
+class CachePackageStore:
+    """Implements :class:`~katalyst_plugin_harness.ports.PackageStore` under *root*."""
+
+    def __init__(self, root: Path) -> None:
+        self._root = root
+
+    def location(self, package: Package) -> Path:
+        return self._root / package.harness.name
+
+    def write(self, package: Package) -> Path:
+        directory = self.location(package)
+        if directory.exists():
+            shutil.rmtree(directory)
+        directory.mkdir(parents=True)
+        (directory / MANIFEST).write_text(_yaml(dict(package.manifest)), encoding="utf-8")
+        for item in package.files:
+            target = directory / item.path
+            target.parent.mkdir(parents=True, exist_ok=True)
+            if item.frontmatter is None:
+                shutil.copy2(item.source, target)
+            else:
+                body = item.source.read_text(encoding="utf-8")
+                target.write_text(markdown(dict(item.frontmatter), body), encoding="utf-8")
+        return directory

katalyst_plugin_harness/adapters/taxonomy_catalog.py

@@ -0,0 +1,206 @@
+"""The catalog of one repository, read from its loaded ``harness``, ``agent`` and
+``agent_skill`` nodes.
+
+A harness's agents and skills are read through the fields the schema declares carry them
+(the ``harness`` kind's references to ``agent`` and ``agent_skill``), not by field name.
+Each node's settings are every field its kind declares, an unset one as its default, so a
+template can test any of them.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable, Mapping, Sequence
+from dataclasses import replace
+from pathlib import Path
+from typing import Any, cast
+
+from katalyst_engine.model.node import Node
+from katalyst_engine.schema.registry import SchemaRegistry
+
+from katalyst_plugin_harness.domain.model import (
+    AGENT_KIND,
+    HARNESS_KIND,
+    SKILL_KIND,
+    Agent,
+    Catalog,
+    Harness,
+    Scope,
+    Skill,
+)
+from katalyst_plugin_harness.domain.package import SKILL_FILE
+
+__all__ = ["TaxonomyCatalog", "catalog_from"]
+
+#: Files in a skill directory that are not part of the skill.
+_JUNK = frozenset({"__pycache__", ".DS_Store", ".pytest_cache", ".ruff_cache"})
+
+
+def _settings(registry: SchemaRegistry, doc: Node) -> dict[str, object]:
+    definition = registry.get_node_definition(doc.kind)
+    declared: dict[str, object] = (
+        {f.name: doc.spec.get(f.name, f.default) for f in definition.fields}
+        if definition is not None
+        else {}
+    )
+    return {**doc.spec, **declared}
+
+
+def _description(doc: Node) -> str:
+    value = doc.spec.get("description")
+    return str(value).strip() if value else doc.description.strip()
+
+
+def _string(value: object) -> str | None:
+    return value if isinstance(value, str) and value.strip() else None
+
+
+def _skill_files(directory: Path) -> tuple[str, ...]:
+    return tuple(
+        sorted(
+            path.relative_to(directory).as_posix()
+            for path in directory.rglob("*")
+            if path.is_file() and not _JUNK.intersection(path.relative_to(directory).parts)
+        )
+    )
+
+
+def _carried(registry: SchemaRegistry, doc: Node, target_kind: str) -> tuple[str, ...]:
+    from katalyst_taxonomy.engine.relationships import carried_values, carriers_of
+
+    values = (
+        value
+        for carrier in carriers_of(registry, doc.kind)
+        if carrier.target_kinds == frozenset({target_kind})
+        for value in carried_values(doc, carrier)
+    )
+    return tuple(dict.fromkeys(values))
+
+
+def _tool_names(value: object) -> Mapping[str, str | None] | None:
+    if not isinstance(value, dict):
+        return None
+    raw = cast("dict[Any, Any]", value)
+    return {str(k): (None if v is None else str(v)) for k, v in raw.items()}
+
+
+def _mcp_servers(value: object) -> Mapping[str, str | Mapping[str, object]] | None:
+    """``mcp_servers``: each server a name (a string) or a definition (a map)."""
+    if not isinstance(value, dict):
+        return None
+    raw = cast("dict[Any, Any]", value)
+    servers: dict[str, str | Mapping[str, object]] = {}
+    for key, entry in raw.items():
+        if isinstance(entry, dict):
+            servers[str(key)] = {str(k): v for k, v in cast("dict[Any, Any]", entry).items()}
+        elif entry is not None and str(entry).strip():
+            servers[str(key)] = str(entry)
+    return servers
+
+
+def _with_additions(
+    harnesses: Mapping[str, Harness], additions: Mapping[str, tuple[str, Harness]]
+) -> tuple[list[Harness], tuple[tuple[str, str], ...]]:
+    """Each harness with what the nodes that add to it carry (theirs after its own, by
+    node name), and the ``(node, target)`` pairs whose target is not a harness."""
+    merged = dict(harnesses)
+    stray: list[tuple[str, str]] = []
+    for name, (target, node) in sorted(additions.items()):
+        base = merged.get(target)
+        if base is None:
+            stray.append((name, target))
+            continue
+        merged[target] = replace(
+            base,
+            agents=tuple(dict.fromkeys((*base.agents, *node.agents))),
+            skills=tuple(dict.fromkeys((*base.skills, *node.skills))),
+            added_by=(*base.added_by, name),
+        )
+    return list(merged.values()), tuple(stray)
+
+
+def catalog_from(documents: Iterable[Node], registry: SchemaRegistry) -> Catalog:
+    """The harnesses, agents and skills among *documents*; the first of a name wins.
+
+    A harness node that adds to another (its reference to a ``harness``) is not a harness
+    of its own: what it carries is added to that one's.
+    """
+    from katalyst_taxonomy.engine.accessors import get_source_path
+
+    harnesses: dict[str, Harness] = {}
+    additions: dict[str, tuple[str, Harness]] = {}
+    agents: dict[str, Agent] = {}
+    skills: dict[str, Skill] = {}
+    for doc in documents:
+        source = get_source_path(doc)
+        if source is None:
+            continue
+        here = source.parent
+        if doc.kind == AGENT_KIND and doc.name not in agents:
+            prompt = here / (_string(doc.spec.get("prompt_file")) or f"{doc.name}.md")
+            agents[doc.name] = Agent(
+                name=doc.name,
+                description=_description(doc),
+                node=source,
+                prompt=prompt if prompt.is_file() else None,
+                settings=_settings(registry, doc),
+            )
+        elif doc.kind == SKILL_KIND and doc.name not in skills:
+            directory = here / (_string(doc.spec.get("skill_dir")) or doc.name)
+            present = (directory / SKILL_FILE).is_file()
+            skills[doc.name] = Skill(
+                name=doc.name,
+                description=_description(doc),
+                node=source,
+                directory=directory if present else None,
+                files=_skill_files(directory) if present else (),
+                settings=_settings(registry, doc),
+            )
+        elif doc.kind == HARNESS_KIND and doc.name not in harnesses and doc.name not in additions:
+            spec = doc.spec
+            scope: Scope = "global" if spec.get("scope") == "global" else "project"
+            agent_template = _string(spec.get("agent_template"))
+            skill_template = _string(spec.get("skill_template"))
+            harness = Harness(
+                name=doc.name,
+                platform=_string(spec.get("platform")) or doc.name,
+                node=source,
+                scope=scope,
+                agents=_carried(registry, doc, AGENT_KIND),
+                skills=_carried(registry, doc, SKILL_KIND),
+                tool_names=_tool_names(spec.get("tool_names")),
+                mcp_tool_name=_string(spec.get("mcp_tool_name")),
+                mcp_servers=_mcp_servers(spec.get("mcp_servers")),
+                agent_template=here / agent_template if agent_template else None,
+                skill_template=here / skill_template if skill_template else None,
+            )
+            target = next(iter(_carried(registry, doc, HARNESS_KIND)), None)
+            if target is None:
+                harnesses[doc.name] = harness
+            else:
+                additions[doc.name] = (target, harness)
+    merged, stray = _with_additions(harnesses, additions)
+    return Catalog(
+        harnesses=tuple(sorted(merged, key=lambda h: h.name)),
+        agents=agents,
+        skills=skills,
+        stray=stray,
+    )
+
+
+class TaxonomyCatalog:
+    """Implements :class:`~katalyst_plugin_harness.ports.CatalogSource` over loaded nodes.
+
+    *load* reads the repository's nodes; *registry* gives the schema (both called once,
+    on :meth:`load`).
+    """
+
+    def __init__(
+        self,
+        load: Callable[[], Sequence[Node]],
+        registry: Callable[[], SchemaRegistry],
+    ) -> None:
+        self._load = load
+        self._registry = registry
+
+    def load(self) -> Catalog:
+        return catalog_from(self._load(), self._registry())

katalyst_plugin_harness/cli.py

@@ -0,0 +1,138 @@
+# pyright: reportUnusedFunction=false
+#
+# The commands are nested functions registered by their decorators and never referenced by
+# name; discovery calls create_group() for a configured group.
+"""``kata tax harness sync | status`` — the taxonomy's agents and skills in each harness."""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING
+
+import click
+
+if TYPE_CHECKING:
+    from katalyst_taxonomy_cli.context import CliContext
+
+    from katalyst_plugin_harness.domain.reports import HarnessState, HarnessSync
+
+
+def _sync_lines(result: HarnessSync) -> list[str]:
+    head = (
+        f"{result.harness} ({result.platform}, {result.scope}): {len(result.agents)} agent(s), "
+        f"{len(result.skills)} skill(s) as {result.package}"
+    )
+    lines = [head]
+    if result.dry_run:
+        lines.append(f"  would install {len(result.installed)} package file(s)")
+        if result.reinstalled:
+            lines.append("  would uninstall the package first (files were unwired)")
+        lines.extend(f"  would remove {path}" for path in result.removed)
+    else:
+        lines.append(f"  installed {len(result.installed)} file(s)")
+        lines.extend(f"  removed   {path}" for path in result.removed)
+    return lines
+
+
+def _status_lines(state: HarnessState) -> list[str]:
+    agents = f"{len(state.wired_agents) - len(state.missing_agents)}/{len(state.wired_agents)}"
+    skills = f"{len(state.wired_skills) - len(state.missing_skills)}/{len(state.wired_skills)}"
+    verdict = "in sync" if state.in_sync else "out of sync (run kata tax harness sync)"
+    lines = [
+        f"{state.harness} ({state.platform}, {state.scope}): {verdict}; "
+        f"{agents} agents, {skills} skills installed"
+    ]
+    if not state.package_installed and (state.wired_agents or state.wired_skills):
+        lines.append(f"  {state.package} is not installed")
+    for label, names in (
+        ("missing agent", state.missing_agents),
+        ("missing skill", state.missing_skills),
+        ("unwired agent", state.extra_agents),
+        ("unwired skill", state.extra_skills),
+    ):
+        lines.extend(f"  {label}: {name}" for name in names)
+    return lines
+
+
+def create_group() -> click.Group:
+    """Entry point for ``katalyst_taxonomy.cli``: contributes ``kata tax harness``."""
+    from katalyst_taxonomy_cli.options import repository_option
+
+    @click.group("harness")
+    def harness() -> None:
+        """Coding-agent harnesses: install the agents and skills each is wired to."""
+
+    @harness.command("sync")
+    @click.option("--harness", "name", default=None, help="Only this harness (its node's name).")
+    @click.option(
+        "--dry-run", is_flag=True, help="Show what would be installed and removed; change nothing."
+    )
+    @repository_option
+    @click.pass_obj
+    def sync(ctx: CliContext, name: str | None, dry_run: bool, backend: str | None) -> None:
+        """Install each harness's agents and skills with OpenPackage; remove unwired ones.
+
+        Builds one OpenPackage package per harness node from the agents and skills it
+        carries (their settings from the nodes' fields), installs it for the harness's
+        platform, and uninstalls what the harness no longer carries.
+
+        Examples:
+
+            kata tax harness sync
+
+            kata tax harness sync --harness claude --dry-run --backend work
+        """
+        from katalyst_plugin_harness.composition import harness_service
+        from katalyst_plugin_harness.domain.errors import HarnessError
+
+        repository = ctx.repository(backend)
+        service = harness_service(
+            repository.root, profile=ctx.profile, echo=lambda m: click.echo(m, err=True)
+        )
+        try:
+            results = service.sync(harness=name, dry_run=dry_run)
+        except HarnessError as exc:
+            raise click.ClickException(str(exc)) from exc
+
+        if ctx.output_format == "json":
+            click.echo(json.dumps([r.as_dict() for r in results], indent=2))
+        elif not results:
+            click.echo(
+                "No harness nodes in this repository. katalyst-taxonomy's taxonomy-agents "
+                "bundle ships opencode and claude: kata tax add --source <katalyst-taxonomy> "
+                "--bundle taxonomy-agents"
+            )
+        else:
+            for result in results:
+                for line in _sync_lines(result):
+                    click.echo(line)
+                for problem in result.problems:
+                    click.echo(f"{problem.severity}: {problem.message}", err=True)
+        if any(p.severity == "error" for r in results for p in r.problems):
+            raise SystemExit(1)
+
+    @harness.command("status")
+    @click.option("--harness", "name", default=None, help="Only this harness (its node's name).")
+    @repository_option
+    @click.pass_obj
+    def status(ctx: CliContext, name: str | None, backend: str | None) -> None:
+        """Show, per harness, what it carries against what OpenPackage has installed."""
+        from katalyst_plugin_harness.composition import harness_service
+        from katalyst_plugin_harness.domain.errors import HarnessError
+
+        service = harness_service(ctx.repository(backend).root, profile=ctx.profile)
+        try:
+            states = service.status(harness=name)
+        except HarnessError as exc:
+            raise click.ClickException(str(exc)) from exc
+        if ctx.output_format == "json":
+            click.echo(json.dumps([s.as_dict() for s in states], indent=2))
+            return
+        if not states:
+            click.echo("No harness nodes in this repository.")
+            return
+        for state in states:
+            for line in _status_lines(state):
+                click.echo(line)
+
+    return harness