katalyst-plugin-harness 0.1.1a1__tar.gz

katalyst_plugin_harness-0.1.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_plugin_harness-0.1.1a1/PKG-INFO

@@ -0,0 +1,15 @@
+Metadata-Version: 2.5
+Name: katalyst-plugin-harness
+Version: 0.1.1a1
+Summary: Katalyst harness plugin — install the taxonomy's agents and skills into coding-agent harnesses with OpenPackage
+Author: eSimplicity
+License: Proprietary
+Requires-Python: >=3.12
+Requires-Dist: click>=8.0
+Requires-Dist: jinja2>=3.1
+Requires-Dist: katalyst-core<1,>=0.1
+Requires-Dist: katalyst-engine<6,>=5
+Requires-Dist: katalyst-taxonomy-cli<3,>=2
+Requires-Dist: katalyst-taxonomy-mcp<5,>=4
+Requires-Dist: katalyst-taxonomy<6,>=5
+Requires-Dist: pyyaml

katalyst_plugin_harness-0.1.1a1/pyproject.toml

@@ -0,0 +1,48 @@
+[project]
+name = "katalyst-plugin-harness"
+version = "0.1.1a1"
+description = "Katalyst harness plugin — install the taxonomy's agents and skills into coding-agent harnesses with OpenPackage"
+license = { text = "Proprietary" }
+requires-python = ">=3.12"
+authors = [
+    { name = "eSimplicity" }
+]
+dependencies = [
+    # Bounded to the config-rooted runtime this plugin is written against.
+    "katalyst-taxonomy>=5,<6",
+    "katalyst-engine>=5,<6",
+    # Its MCP tools use the server's response helpers; its commands, the CLI context and options.
+    "katalyst-taxonomy-mcp>=4,<5",
+    "katalyst-taxonomy-cli>=2,<3",
+    "katalyst-core>=0.1,<1",
+    "pyyaml",
+    # A harness's settings for an agent are rendered from the Jinja template its node names.
+    "jinja2>=3.1",
+    "click>=8.0",
+]
+
+[project.entry-points."katalyst_taxonomy.plugins"]
+harness = "katalyst_plugin_harness:HarnessPlugin"
+
+# agent, agent_skill and harness are ordinary registered kinds, declared like any bundle's,
+# so any schema bundle's repository can carry agents.
+[project.entry-points."katalyst_core.modules"]
+# The schema, as LinkML modules on katalyst-core (the bundle builds its definitions
+# from them).
+harness = "katalyst_plugin_harness.linkml:MODULES"
+
+[project.entry-points."katalyst_engine.bundles"]
+harness-schema = "katalyst_plugin_harness.schema:HarnessSchemaBundle"
+
+[project.entry-points."katalyst_taxonomy.cli"]
+harness = "katalyst_plugin_harness.cli:create_group"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/katalyst_plugin_harness"]
+
+[tool.hatch.build.targets.wheel.sources]
+"src" = ""

katalyst_plugin_harness-0.1.1a1/src/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-0.1.1a1/src/katalyst_plugin_harness/adapters/__init__.py

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

katalyst_plugin_harness-0.1.1a1/src/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-0.1.1a1/src/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-0.1.1a1/src/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