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

katalyst_plugin_bard/__init__.py

@@ -0,0 +1,5 @@
+"""Katalyst bard plugin — schema-driven web UI for the taxonomy."""
+
+from .plugin import BardPlugin
+
+__all__ = ["BardPlugin"]

katalyst_plugin_bard/build.py

@@ -0,0 +1,224 @@
+"""Build a contribution: validate its source manifest, bundle it, write the built manifest.
+
+``kata tax bard build-contribution <source> --out <dir>`` is the one build a
+contribution author needs. It turns a source directory (``bard.manifest.json``
+naming ``.ts``/``.tsx`` entries, importing only ``@katalyst/bard-host``) into a
+directory Bard loads at runtime: one ES module per view or slot, its stylesheet,
+and a built manifest naming them. Ship that directory in a Python package and
+declare it under the ``katalyst_bard.contributions`` entry point
+(:mod:`katalyst_plugin_bard.contributions`).
+
+The bundling itself is ``contrib/build.mjs`` (esbuild, from the contribution's own
+``node_modules``). React, react-dom and the host contract are not bundled: the
+host provides them at runtime (``contrib/shared.json``), so there is one React.
+
+Validation happens here, before Node runs, so a bad manifest fails with the
+reason rather than as a bundler error far from its cause.
+"""
+
+from __future__ import annotations
+
+import copy
+import json
+import shutil
+import subprocess
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from katalyst_plugin_bard.contributions import MANIFEST
+
+#: The bundling script and the shared-module list it reads, shipped in this package.
+BUILD_SCRIPT = Path(__file__).parent / "contrib" / "build.mjs"
+
+#: Predicates the runtime cannot honour yet. Rejected at build time so the failure is
+#: a build error rather than a fragment that renders nowhere. See
+#: katalyst-taxonomy#196 — the REST API does not expose ``spec.extends``.
+UNSUPPORTED_PREDICATES = ("attachedKind",)
+
+
+@dataclass(frozen=True)
+class BuiltEntry:
+    id: str
+    module: str
+    styles: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class BuildResult:
+    name: str
+    out: Path
+    entries: tuple[BuiltEntry, ...]
+
+
+#: ``(script, payload, cwd) -> stdout``. Raises RuntimeError on failure.
+RunNode = Callable[[Path, dict[str, Any], Path], str]
+
+
+def default_schema_path() -> Path:
+    """The schema shipped inside the wheel, falling back to a repo checkout."""
+    packaged = Path(__file__).parent / "schemas" / "bard.manifest.schema.json"
+    if packaged.is_file():
+        return packaged
+    # src/katalyst_plugin_bard/build.py -> plugin root is parents[2].
+    return Path(__file__).parents[2] / "schemas" / "bard.manifest.schema.json"
+
+
+def load_schema(schema_path: Path | None = None) -> dict[str, Any]:
+    """Load the contribution manifest schema."""
+    return json.loads((schema_path or default_schema_path()).read_text())
+
+
+def _schema_errors(doc: Any, schema: dict[str, Any]) -> list[str]:
+    """Validation messages for a document, as plain strings.
+
+    `jsonschema` ships no type stubs, so this is the single place the untyped
+    boundary is crossed — keeping the ignore localised instead of scattered
+    through the validation logic.
+    """
+    from jsonschema import Draft202012Validator
+
+    validator = Draft202012Validator(schema)  # pyright: ignore[reportUnknownMemberType]
+    messages: list[str] = []
+    for error in validator.iter_errors(doc):  # pyright: ignore[reportUnknownMemberType, reportUnknownVariableType]
+        path = "/".join(str(p) for p in error.absolute_path) or "(root)"  # pyright: ignore[reportUnknownMemberType, reportUnknownArgumentType]
+        messages.append(f"{path}: {error.message}")  # pyright: ignore[reportUnknownMemberType, reportUnknownArgumentType]
+    return messages
+
+
+def validate_source(source: Path, schema: dict[str, Any]) -> tuple[dict[str, Any], list[str]]:
+    """Read and validate a source manifest. Returns the document and every problem."""
+    manifest = source / MANIFEST
+    if not manifest.is_file():
+        return {}, [f"no {MANIFEST} in {source}"]
+    try:
+        doc: dict[str, Any] = json.loads(manifest.read_text())
+    except json.JSONDecodeError as exc:
+        return {}, [f"invalid JSON: {exc}"]
+
+    errors = _schema_errors(doc, schema)
+    if errors:
+        return doc, errors
+
+    problems: list[str] = []
+    name = doc["metadata"]["name"]
+    if name != source.resolve().name:
+        problems.append(
+            f"metadata.name '{name}' does not match directory '{source.resolve().name}'"
+        )
+
+    spec: dict[str, Any] = doc.get("spec", {})
+    if "hostRange" not in spec:
+        # Bard skips a contribution it cannot check, so building one would only defer
+        # the failure to whoever installs it.
+        problems.append("spec.hostRange is required: the host versions this contribution supports")
+
+    entries: list[dict[str, Any]] = [*spec.get("views", ()), *spec.get("slots", ())]
+    if not entries:
+        problems.append("declares no views or slots — it would contribute nothing")
+
+    seen: set[str] = set()
+    for entry in entries:
+        if entry["id"] in seen:
+            problems.append(f"id '{entry['id']}' is declared twice")
+        seen.add(entry["id"])
+        if not (source / entry["entry"]).is_file():
+            problems.append(f"entry '{entry['entry']}' (id '{entry['id']}') does not exist")
+
+    for view in spec.get("views", ()):
+        if view.get("placement") != "footer" and "section" not in view and "section" not in spec:
+            # Bard refuses a contributed main view with no subsection to list it under.
+            problems.append(
+                f"view '{view['id']}' declares no section: set \"section\" on the view, or "
+                "on spec for all of them — the subsection it is listed under in your "
+                "package's sidebar heading"
+            )
+
+    for slot in spec.get("slots", ()):
+        applies = slot.get("appliesWhen", {})
+        for predicate in UNSUPPORTED_PREDICATES:
+            if predicate in applies:
+                problems.append(
+                    f"slot '{slot['id']}' uses appliesWhen.{predicate}, which the runtime "
+                    "cannot honour yet (the taxonomy API does not expose spec.extends — "
+                    "see katalyst-taxonomy#196)"
+                )
+    return doc, problems
+
+
+def _default_run_node(script: Path, payload: dict[str, Any], cwd: Path) -> str:
+    node = shutil.which("node")
+    if node is None:
+        raise RuntimeError("node is required to build a contribution. Install Node.js 20 or newer.")
+    result = subprocess.run(
+        [node, str(script), json.dumps(payload)],
+        cwd=cwd,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if result.returncode != 0:
+        raise RuntimeError(
+            f"bundling failed (node exit {result.returncode}):\n{result.stderr.strip()}"
+        )
+    return result.stdout
+
+
+def _prepare_out(out: Path) -> None:
+    """Empty *out* for a fresh build, refusing a directory that is not a previous one.
+
+    The whole directory is replaced so a module renamed in source does not linger in
+    the shipped build; a directory with other content is refused rather than wiped.
+    """
+    if out.exists():
+        if not out.is_dir():
+            raise RuntimeError(f"--out {out} is not a directory")
+        if any(out.iterdir()) and not (out / MANIFEST).is_file():
+            raise RuntimeError(
+                f"--out {out} is not empty and holds no {MANIFEST}; refusing to replace it"
+            )
+        shutil.rmtree(out)
+    out.mkdir(parents=True)
+
+
+def build_contribution(
+    source: Path,
+    out: Path,
+    *,
+    schema: dict[str, Any] | None = None,
+    run_node: RunNode = _default_run_node,
+) -> BuildResult:
+    """Validate *source*, bundle it into *out*, and write the built manifest there."""
+    doc, problems = validate_source(source, schema if schema is not None else load_schema())
+    if problems:
+        raise RuntimeError(
+            f"{source / MANIFEST} is not buildable:\n" + "\n".join(f"  - {p}" for p in problems)
+        )
+
+    spec: dict[str, Any] = doc["spec"]
+    entries = {e["id"]: e["entry"] for e in (*spec.get("views", ()), *spec.get("slots", ()))}
+    _prepare_out(out)
+    stdout = run_node(
+        BUILD_SCRIPT,
+        {"root": str(source.resolve()), "out": str(out.resolve()), "entries": entries},
+        source.resolve(),
+    )
+    bundled: dict[str, dict[str, Any]] = json.loads(stdout)
+
+    missing = sorted(set(entries) - set(bundled))
+    if missing:
+        raise RuntimeError(f"bundling produced no module for: {', '.join(missing)}")
+
+    built = copy.deepcopy(doc)
+    results: list[BuiltEntry] = []
+    for key in ("views", "slots"):
+        for entry in built["spec"].get(key, ()):
+            output = bundled[entry["id"]]
+            entry["entry"] = output["module"]
+            styles = tuple(output.get("styles", ()))
+            if styles:
+                entry["styles"] = list(styles)
+            results.append(BuiltEntry(entry["id"], output["module"], styles))
+    (out / MANIFEST).write_text(json.dumps(built, indent=2) + "\n")
+    return BuildResult(doc["metadata"]["name"], out, tuple(results))

katalyst_plugin_bard/cli.py

@@ -0,0 +1,234 @@
+"""CLI contribution — `kata tax bard <command>`."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Protocol
+
+import click
+
+from katalyst_plugin_bard.contributions import NO_CONTRIBUTIONS_ENV
+
+
+class _Output(Protocol):
+    def echo(self, message: str) -> None: ...
+
+
+class CliContextLike(Protocol):
+    """The slice of the CLI context bard needs.
+
+    Declared structurally rather than importing ``CliContext``: the concrete
+    class lives in the CLI package, and depending on the shape rather than the
+    type keeps this plugin loadable without it while staying type-checked.
+    """
+
+    @property
+    def output(self) -> _Output: ...
+
+
+def create_group() -> click.Group:
+    """Factory called by CLI discovery to register the bard command group."""
+
+    @click.group("bard")
+    def bard() -> None:
+        """Bard — a schema-driven web UI for the taxonomy."""
+
+    @bard.command("serve")
+    @click.option("--port", "ui_port", type=int, default=5273, help="Port for the bard UI.")
+    @click.option(
+        "--api-port",
+        type=int,
+        default=None,
+        help=(
+            "Port for the local REST API when Bard starts one; starting fails if it is in "
+            "use. An API already running for your config file is reused on its own port. "
+            "Default: a free port."
+        ),
+    )
+    @click.option(
+        "--api-url",
+        default=None,
+        help=(
+            "Use an existing taxonomy API instead of starting one locally. "
+            "Bard reads all data over HTTP, so this can be any reachable server; "
+            "its token is read from KATALYST_API_TOKEN."
+        ),
+    )
+    @click.option("--no-open", is_flag=True, help="Do not open a browser.")
+    @click.option(
+        "--no-contributions",
+        is_flag=True,
+        envvar=NO_CONTRIBUTIONS_ENV,
+        help=(
+            "Plain Bard: load none of the views installed packages contribute, only "
+            f"Bard's own. Also set by {NO_CONTRIBUTIONS_ENV}=1."
+        ),
+    )
+    @click.option("--dev", is_flag=True, help="Print dev-server instructions instead of serving.")
+    @click.pass_obj
+    def serve(
+        ctx: CliContextLike,
+        ui_port: int,
+        api_port: int | None,
+        api_url: str | None,
+        no_open: bool,
+        no_contributions: bool,
+        dev: bool,
+    ) -> None:
+        """Serve the bard UI, ensuring a taxonomy API is reachable.
+
+        Runs from any directory: the API starts from the user config file, and every
+        repository is a filesystem backend declared there. With KATALYST_CONFIG_WRITE=1
+        the local API accepts configuration writes (a running one that does not is
+        restarted). Requires Node.js 20+ and built assets (`just build` in plugins/bard).
+        """
+        # Deferred: CLI discovery imports this module on every `kata` invocation,
+        # so the heavy import stays inside the command body.
+        from katalyst_plugin_bard.serve import BardConfig, guard_teardown, run_bard
+
+        if dev:
+            ctx.output.echo("Dev mode — run the Node server and Vite dev server manually:")
+            ctx.output.echo("  cd plugins/bard/web && npm install && npm run dev")
+            ctx.output.echo("Set TAXONOMY_API_URL if your API is not on http://127.0.0.1:8000")
+            raise SystemExit(0)
+
+        config = BardConfig(
+            ui_port=ui_port,
+            api_port=api_port,
+            open_browser=not no_open,
+            taxonomy_api_url=api_url,
+            contributions=not no_contributions,
+        )
+        try:
+            url, handle = run_bard(config, echo=ctx.output.echo)
+        except RuntimeError as exc:
+            ctx.output.echo(f"Error: {exc}")
+            raise SystemExit(1) from exc
+
+        guard_teardown(handle)
+        ctx.output.echo(f"Bard serving at {url}")
+        ctx.output.echo("Press Ctrl+C to stop.")
+        try:
+            code = handle.wait()
+        except KeyboardInterrupt:
+            handle.terminate()
+            code = 0
+        raise SystemExit(code)
+
+    @bard.command("desktop")
+    @click.option(
+        "--api-url",
+        default=None,
+        help=(
+            "Use an existing taxonomy API instead of starting one locally; its token is "
+            "read from KATALYST_API_TOKEN. Settings can save only if that API was started "
+            "with KATALYST_CONFIG_WRITE=1."
+        ),
+    )
+    @click.option(
+        "--api-port",
+        type=int,
+        default=None,
+        help=(
+            "Port for the local REST API when Bard starts one; starting fails if it is in "
+            "use. An API already running for your config file is reused on its own port. "
+            "Default: a free port."
+        ),
+    )
+    @click.option(
+        "--electron",
+        "electron",
+        type=click.Path(dir_okay=False, path_type=Path),
+        default=None,
+        help=(
+            "Electron executable to use. Default: KATALYST_ELECTRON, else the pinned "
+            "version, fetched into the Katalyst cache with npm on first run."
+        ),
+    )
+    @click.option(
+        "--no-contributions",
+        is_flag=True,
+        envvar=NO_CONTRIBUTIONS_ENV,
+        help=(
+            "Plain Bard: load none of the views installed packages contribute, only "
+            f"Bard's own. Also set by {NO_CONTRIBUTIONS_ENV}=1."
+        ),
+    )
+    @click.pass_obj
+    def desktop(
+        ctx: CliContextLike,
+        api_url: str | None,
+        api_port: int | None,
+        electron: Path | None,
+        no_contributions: bool,
+    ) -> None:
+        """Open bard in a desktop window, with settings editable.
+
+        The desktop shell serves the UI over a custom protocol rather than a
+        local HTTP server, so there is no port to bind and nothing to collide
+        with. It starts the taxonomy API for your config file with configuration
+        writes enabled. With --api-url it starts nothing, and saving settings
+        needs that API to have been started with KATALYST_CONFIG_WRITE=1.
+        Requires Node.js 20+ (npm fetches Electron on first run).
+        """
+        from katalyst_plugin_bard.serve import BardConfig, guard_teardown, run_desktop
+
+        config = BardConfig(
+            ui_port=0,  # unused: the desktop shell binds no port
+            api_port=api_port,
+            open_browser=False,
+            taxonomy_api_url=api_url,
+            contributions=not no_contributions,
+        )
+        try:
+            handle = run_desktop(config, electron=electron, echo=ctx.output.echo)
+        except RuntimeError as exc:
+            ctx.output.echo(f"Error: {exc}")
+            raise SystemExit(1) from exc
+
+        guard_teardown(handle)
+        ctx.output.echo("Bard desktop running. Close the window to exit.")
+        try:
+            code = handle.wait()
+        except KeyboardInterrupt:
+            handle.terminate()
+            code = 0
+        raise SystemExit(code)
+
+    @bard.command("build-contribution")
+    @click.argument("source", type=click.Path(exists=True, file_okay=False, path_type=Path))
+    @click.option(
+        "--out",
+        required=True,
+        type=click.Path(file_okay=False, path_type=Path),
+        help="Directory to write the built contribution to. Replaced on every build.",
+    )
+    @click.pass_obj
+    def build_contribution_cmd(ctx: CliContextLike, source: Path, out: Path) -> None:
+        """Build a contribution for Bard to load at runtime.
+
+        SOURCE holds a bard.manifest.json naming .ts/.tsx entries that import only
+        @katalyst/bard-host. Writes one ES module per view or slot, its stylesheet and
+        the built manifest to --out; ship that directory in a Python package under the
+        `katalyst_bard.contributions` entry point. Requires Node.js 20+ and esbuild
+        installed for SOURCE (a devDependency).
+        """
+        from katalyst_plugin_bard.build import build_contribution
+
+        try:
+            result = build_contribution(source, out)
+        except RuntimeError as exc:
+            ctx.output.echo(f"Error: {exc}")
+            raise SystemExit(1) from exc
+
+        for entry in result.entries:
+            styles = f" + {', '.join(entry.styles)}" if entry.styles else ""
+            ctx.output.echo(f"  {entry.id}: {entry.module}{styles}")
+        ctx.output.echo(f"Built {result.name} into {result.out} ({len(result.entries)} module(s))")
+
+    _ = (
+        serve,
+        desktop,
+        build_contribution_cmd,
+    )  # registered by decorators; silence unused warnings
+    return bard

katalyst_plugin_bard/contrib/build.mjs

@@ -0,0 +1,65 @@
+// Bundle a Bard contribution's entries into browser ES modules.
+//
+// Run by `kata tax bard build-contribution`, which validates the manifest first and
+// writes the built manifest after; this script only bundles. Input is one JSON
+// argument: { root, out, entries: { <id>: <entry path relative to root> } }. Output,
+// on stdout, is { <id>: { module, styles } } with paths relative to `out`.
+//
+// The modules in shared.json are not bundled: they stay bare imports, which the
+// host's import map resolves to its own React and host contract. Any bundler that
+// leaves exactly those external produces an equivalent module.
+//
+// esbuild comes from the contribution's own node_modules (a devDependency), so the
+// host does not have to ship a bundler. ESBUILD_BINARY_PATH is honoured, as always.
+
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { join, relative, resolve } from "node:path";
+
+const shared = JSON.parse(readFileSync(new URL("./shared.json", import.meta.url), "utf8"));
+const { root, out, entries } = JSON.parse(process.argv[2] ?? "{}");
+
+function loadEsbuild(from) {
+  try {
+    return createRequire(join(from, "package.json"))("esbuild");
+  } catch {
+    process.stderr.write(
+      `esbuild is not installed for ${from}. Add it as a devDependency ` +
+        "(npm install --save-dev esbuild) and run this again.\n",
+    );
+    process.exit(2);
+  }
+}
+
+const esbuild = loadEsbuild(resolve(root));
+const absOut = resolve(out);
+const result = await esbuild.build({
+  absWorkingDir: resolve(root),
+  entryPoints: Object.fromEntries(Object.entries(entries).map(([id, entry]) => [id, resolve(root, entry)])),
+  outdir: absOut,
+  entryNames: "[name]",
+  assetNames: "assets/[name]-[hash]",
+  bundle: true,
+  format: "esm",
+  platform: "browser",
+  target: "es2022",
+  jsx: "automatic",
+  minify: true,
+  legalComments: "none",
+  define: { "process.env.NODE_ENV": '"production"' },
+  loader: { ".svg": "file", ".png": "file", ".woff2": "file" },
+  metafile: true,
+  logLevel: "warning",
+  // Left as bare imports: the host's import map resolves them to its own instances.
+  external: shared.modules,
+});
+
+const built = {};
+for (const [file, output] of Object.entries(result.metafile.outputs)) {
+  if (output.entryPoint === undefined || !file.endsWith(".js")) continue;
+  const id = Object.keys(entries).find((key) => resolve(root, entries[key]) === resolve(root, output.entryPoint));
+  if (id === undefined) continue;
+  const rel = (p) => `./${relative(absOut, resolve(root, p)).split("\\").join("/")}`;
+  built[id] = { module: rel(file), styles: output.cssBundle ? [rel(output.cssBundle)] : [] };
+}
+process.stdout.write(JSON.stringify(built));

katalyst_plugin_bard/contrib/shared.json

@@ -0,0 +1,10 @@
+{
+  "description": "Modules a contribution imports from the Bard host at runtime instead of bundling. The host's build serves each as a module re-exporting its own instance and maps the name to it in an import map (web/vite/shared-modules.ts), so every contribution renders with the host's React. build-contribution marks exactly these external.",
+  "modules": [
+    "@katalyst/bard-host",
+    "react",
+    "react-dom",
+    "react-dom/client",
+    "react/jsx-runtime"
+  ]
+}