katalyst-plugin-scaffolding 1.0.1a1__tar.gz

katalyst_plugin_scaffolding-1.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_plugin_scaffolding-1.0.1a1/PKG-INFO

@@ -0,0 +1,16 @@
+Metadata-Version: 2.5
+Name: katalyst-plugin-scaffolding
+Version: 1.0.1a1
+Summary: Katalyst scaffolding plugin
+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: pydantic>=2.0
+Requires-Dist: pyyaml

katalyst_plugin_scaffolding-1.0.1a1/layer/README.md

@@ -0,0 +1,5 @@
+# scaffolding library layer
+
+This directory is the plugin's taxonomy-library layer: package-owned fixtures,
+contracts, and future layer-local resources. It is intentionally separate from
+runtime source and from the plugin's xspec project.

katalyst_plugin_scaffolding-1.0.1a1/pyproject.toml

@@ -0,0 +1,48 @@
+[project]
+name = "katalyst-plugin-scaffolding"
+version = "1.0.1a1"
+description = "Katalyst scaffolding plugin"
+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 REST routes 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",
+    # The recipe wiring is rendered from the Jinja templates a collection names.
+    "jinja2>=3.1",
+    "pydantic>=2.0",
+    "click>=8.0",
+]
+
+[project.entry-points."katalyst_taxonomy.plugins"]
+scaffolding = "katalyst_plugin_scaffolding:ScaffoldingPlugin"
+
+# node_wiring documents are ordinary registered kinds, declared like any bundle's.
+[project.entry-points."katalyst_core.modules"]
+# The schema, as LinkML modules on katalyst-core (the bundle builds its definitions
+# from them).
+scaffolding = "katalyst_plugin_scaffolding.linkml:MODULES"
+
+[project.entry-points."katalyst_engine.bundles"]
+scaffolding-schema = "katalyst_plugin_scaffolding.schema:ScaffoldingSchemaBundle"
+
+[project.entry-points."katalyst_taxonomy.cli"]
+add = "katalyst_plugin_scaffolding.templates.cli:create_group"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/katalyst_plugin_scaffolding"]
+
+[tool.hatch.build.targets.wheel.sources]
+"src" = ""

katalyst_plugin_scaffolding-1.0.1a1/src/katalyst_plugin_scaffolding/__init__.py

@@ -0,0 +1,5 @@
+"""Scaffolding plugin — universal scaffold for node creation."""
+
+from .plugin import ScaffoldingPlugin
+
+__all__ = ["ScaffoldingPlugin"]

katalyst_plugin_scaffolding-1.0.1a1/src/katalyst_plugin_scaffolding/linkml/__init__.py

@@ -0,0 +1,15 @@
+"""LinkML modules this package ships, on katalyst-core.
+
+Registered under the ``katalyst_core.modules`` entry point, so core loads them by name.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+__all__ = ["MODULES"]
+
+MODULES: dict[str, Path] = {
+    path.stem: path for path in sorted(Path(__file__).parent.glob("*.yaml"))
+}
+"""Module name (as an ``imports:`` line writes it) to its YAML file."""

katalyst_plugin_scaffolding-1.0.1a1/src/katalyst_plugin_scaffolding/linkml/released/0.1.0/SHA256SUMS

@@ -0,0 +1 @@
+cb3f7942331947e4995dc5a067f51435bd59e2ea7292eabdf1be26eb2141340b  scaffolding.yaml

katalyst_plugin_scaffolding-1.0.1a1/src/katalyst_plugin_scaffolding/linkml/released/0.1.0/scaffolding.yaml

@@ -0,0 +1,54 @@
+# Generated once from the Python definitions (LinkML rebuild, phase 4); edit here.
+id: https://w3id.org/katalyst/scaffolding/scaffolding
+name: scaffolding
+title: scaffolding scaffolding wing
+version: 0.1.0
+license: Proprietary
+prefixes:
+  scaffolding: https://w3id.org/katalyst/scaffolding/
+  kc: https://w3id.org/katalyst/core/
+  linkml: https://w3id.org/linkml/
+  dcterms: http://purl.org/dc/terms/
+default_prefix: scaffolding
+default_range: string
+imports:
+- linkml:types
+- katalyst_core
+description: The scaffolding wing.
+annotations:
+  wing: scaffolding
+  display_name: Scaffolding
+  describes_kind: wing
+classes:
+  NodeWiring:
+    is_a: Node
+    class_uri: scaffolding:NodeWiring
+    description: 'A node wiring: a node_wiring node of the scaffolding wing.'
+    attributes:
+      description:
+        description: What this wiring adds to scaffolded nodes
+        slot_uri: dcterms:description
+      extends:
+        description: 'The templates it extends: targetKind and targetNames (''*'' for all)'
+        slot_uri: scaffolding:extends
+        range: AnyValue
+      provides_template:
+        description: Template directory whose files are added, relative to this document
+        slot_uri: scaffolding:providesTemplate
+    annotations:
+      kind: node_wiring
+      wing: scaffolding
+      label: Node Wiring
+      label_plural: Node Wirings
+      display_order: 900
+      directory_name: node_wiring
+      root: true
+      leaf: true
+      storage:
+        tag: storage
+        value:
+          root: .global/taxonomy
+          container: file
+          filename: identity
+          nest_under_parent: false
+          scaffold: null

katalyst_plugin_scaffolding-1.0.1a1/src/katalyst_plugin_scaffolding/linkml/scaffolding.yaml

@@ -0,0 +1,54 @@
+# Generated once from the Python definitions (LinkML rebuild, phase 4); edit here.
+id: https://w3id.org/katalyst/scaffolding/scaffolding
+name: scaffolding
+title: scaffolding scaffolding wing
+version: 0.1.0
+license: Proprietary
+prefixes:
+  scaffolding: https://w3id.org/katalyst/scaffolding/
+  kc: https://w3id.org/katalyst/core/
+  linkml: https://w3id.org/linkml/
+  dcterms: http://purl.org/dc/terms/
+default_prefix: scaffolding
+default_range: string
+imports:
+- linkml:types
+- katalyst_core
+description: The scaffolding wing.
+annotations:
+  wing: scaffolding
+  display_name: Scaffolding
+  describes_kind: wing
+classes:
+  NodeWiring:
+    is_a: Node
+    class_uri: scaffolding:NodeWiring
+    description: 'A node wiring: a node_wiring node of the scaffolding wing.'
+    attributes:
+      description:
+        description: What this wiring adds to scaffolded nodes
+        slot_uri: dcterms:description
+      extends:
+        description: 'The templates it extends: targetKind and targetNames (''*'' for all)'
+        slot_uri: scaffolding:extends
+        range: AnyValue
+      provides_template:
+        description: Template directory whose files are added, relative to this document
+        slot_uri: scaffolding:providesTemplate
+    annotations:
+      kind: node_wiring
+      wing: scaffolding
+      label: Node Wiring
+      label_plural: Node Wirings
+      display_order: 900
+      directory_name: node_wiring
+      root: true
+      leaf: true
+      storage:
+        tag: storage
+        value:
+          root: .global/taxonomy
+          container: file
+          filename: identity
+          nest_under_parent: false
+          scaffold: null

katalyst_plugin_scaffolding-1.0.1a1/src/katalyst_plugin_scaffolding/plugin.py

@@ -0,0 +1,79 @@
+"""Scaffolding plugin — the template-bundle machinery scaffolding copies from.
+
+Registers how template bundles are installed into, removed from, listed in and described
+for a repository; how a fetched collection's bundle manifests are found; the probe
+``node_wiring`` documents check; the create hook that writes a scaffolded node's
+wiring file; and ``/ext/scaffolding/variants``, the installed variants a form offers
+(:mod:`katalyst_plugin_scaffolding.rest_routes`). ``kata tax add`` arrives over the ``katalyst_taxonomy.cli`` entry point.
+
+The scaffold copy itself is not here. The runtime's scaffolding hook
+(:mod:`katalyst_taxonomy.services.scaffolding_hook`) populates a new node's directory
+when a scaffold variant resolves and the kind's template root holds a directory for it
+(otherwise it is a no-op); the variants it copies are the templates this plugin
+installed. There is no engine-level ``scaffoldable`` flag: where a node records its
+variant is its kind's declaration (``ScaffoldPolicy.variant_annotation``, the field with
+the scaffold-variant role).
+"""
+
+from __future__ import annotations
+
+import importlib.metadata
+
+from katalyst_taxonomy.plugins.protocol import PluginContext, PluginManifest
+
+
+def _version() -> str:
+    """The installed distribution version, for :attr:`PluginManifest.version`.
+
+    No built-in plugin populated ``version`` before #219 — it was declared and
+    always empty, so ``kata config plugins`` could not tell you what you were
+    running. Read from installed metadata rather than a hardcoded literal so it
+    cannot drift from the package it describes.
+    """
+    try:
+        return importlib.metadata.version("katalyst-plugin-scaffolding")
+    except importlib.metadata.PackageNotFoundError:  # pragma: no cover - source checkout
+        return ""
+
+
+class ScaffoldingPlugin:
+    """The scaffolding plugin: template-bundle machinery and the node wiring create hook.
+
+    ``scaffold``: it installs the templates scaffolding copies; ``post_create``: its create
+    hook runs after a node is created.
+    """
+
+    @property
+    def name(self) -> str:
+        return "scaffolding"
+
+    @property
+    def manifest(self) -> PluginManifest:
+        return PluginManifest(
+            name="scaffolding",
+            capabilities=("scaffold", "post_create"),
+            description="Template bundles for scaffolding, and the node wiring create hook",
+            version=_version(),
+        )
+
+    def register(self, context: PluginContext) -> None:
+        """Register the template-bundle machinery and the create hook with *context*."""
+        from katalyst_plugin_scaffolding.rest_routes import ScaffoldingRestRoutes
+        from katalyst_plugin_scaffolding.templates.bundle_install import (
+            describe_bundle,
+            install_template_for_plugin,
+            installed_bundles,
+        )
+        from katalyst_plugin_scaffolding.templates.plugin import register_template_contributions
+        from katalyst_plugin_scaffolding.templates.template_remove import (
+            remove_template_for_plugin,
+        )
+
+        # No init hook: `kata tax init` installs what the user config declares
+        # (spec.templates), which a bundle's own init hook may add to.
+        register_template_contributions(context)
+        context.rest_routes.append(ScaffoldingRestRoutes())
+        context.template_installers.append(install_template_for_plugin)
+        context.template_removers.append(remove_template_for_plugin)
+        context.template_listers.append(installed_bundles)
+        context.template_describers.append(describe_bundle)

katalyst_plugin_scaffolding-1.0.1a1/src/katalyst_plugin_scaffolding/rest_routes.py

@@ -0,0 +1,117 @@
+# pyright: reportUnusedFunction=false
+#
+# The routes are nested functions registered by their decorators and never referenced by
+# name; the REST app mounts the router this returns.
+"""``/ext/scaffolding`` — the installed scaffold variants, for a form that creates nodes.
+
+==================================  ======================================================
+Route                               Answers
+==================================  ======================================================
+``GET /ext/scaffolding/variants``   every scaffold variant installed in the repository
+                                    (``?kind=`` one kind's; ``?holds=ROLE`` those whose
+                                    nodes hold ROLE): its bundle and version, its
+                                    declaration, what its nodes hold, its files, its
+                                    expansions and every token it renders with where the
+                                    value comes from
+==================================  ======================================================
+
+A read: nothing is written. ``backend`` names the repository, as every REST route that
+reads one repository's files does. The answer is
+:mod:`katalyst_taxonomy.services.scaffold_catalog`'s.
+"""
+
+# No `from __future__ import annotations`: FastAPI reads the handlers' annotations.
+from pathlib import Path
+from typing import Any
+
+
+class ScaffoldingRestRoutes:
+    """Implements :class:`~katalyst_taxonomy.plugins.extensions.RestRoutes`."""
+
+    @property
+    def name(self) -> str:
+        return "scaffolding"
+
+    def router(self) -> Any:
+        from fastapi import APIRouter
+        from fastapi.responses import JSONResponse
+        from katalyst_taxonomy.config.installs import declared_config
+        from katalyst_taxonomy.services.scaffold_catalog import (
+            BundleFiles,
+            declared_tokens,
+            scaffold_variants,
+        )
+        from katalyst_taxonomy_mcp.response import ok
+        from katalyst_taxonomy_mcp.rest.repository import repository_or_refusal
+
+        from katalyst_plugin_scaffolding.templates.bundle_install import (
+            describe_bundle,
+            installed_bundles,
+        )
+
+        router = APIRouter()
+
+        def bundles(root: Path) -> list[BundleFiles]:
+            """The declared template bundles *root* has installed, with the files of each."""
+            config = declared_config()[0]
+            declared = config.spec.templates if config is not None else ()
+            have = set(installed_bundles(root, {t.name: t.source for t in declared}))
+            out: list[BundleFiles] = []
+            for template in declared:
+                if template.name not in have:
+                    continue
+                described = describe_bundle(root, template.name, template.source) or {}
+                files = [str(f) for f in described.get("files") or ()]
+                out.append(BundleFiles(template.name, str(template.version or ""), files))
+            return out
+
+        @router.get("/variants", response_model=None)
+        def variants(
+            kind: str | None = None, holds: str | None = None, backend: str | None = None
+        ) -> Any:
+            """The variants installed in *backend*'s repository: of *kind*, holding *holds*."""
+            repository = repository_or_refusal(backend)
+            if isinstance(repository, JSONResponse):
+                return repository
+            root = repository.root
+            found = scaffold_variants(
+                root,
+                filesystem=_Files(),
+                bundles=bundles(root),
+                kind=kind or None,
+                holds=holds or None,
+            )
+            return ok(
+                {
+                    "backend": repository.name,
+                    "kind": kind,
+                    "holds": holds,
+                    "variants": [variant.to_dict() for variant in found],
+                    # The kind's own scaffold tokens: fields only a template renders.
+                    "tokens": declared_tokens(kind) if kind else [],
+                }
+            )
+
+        return router
+
+
+class _Files:
+    """The repository's files, read — the ``FileReader`` the catalog reads through."""
+
+    def exists(self, path: Path) -> bool:
+        return path.exists()
+
+    def is_directory(self, path: Path) -> bool:
+        return path.is_dir()
+
+    def is_file(self, path: Path) -> bool:
+        return path.is_file()
+
+    def read_file(self, path: Path) -> str:
+        return path.read_text(encoding="utf-8")
+
+    def list_directory(self, path: Path) -> list[Path]:
+        return list(path.iterdir()) if path.is_dir() else []
+
+    def glob(self, path: Path, pattern: str) -> list[Path]:
+        return list(path.glob(pattern))

katalyst_plugin_scaffolding-1.0.1a1/src/katalyst_plugin_scaffolding/schema.py

@@ -0,0 +1,75 @@
+"""Schema bundle for the scaffolding plugin: the ``node_wiring`` kind.
+
+A ``node_wiring`` document is ordinary taxonomy content. It lives in a repository,
+under ``.global/taxonomy/node_wiring/``, and adds files to scaffolded nodes: it names
+the templates it extends and the template directory it provides, and it activates only
+when the plugins it requires are installed.
+
+Declaring it (in the LinkML module ``linkml/scaffolding.yaml``) makes it a registered kind like any other, validated and listed. The
+runtime keeps no list of kinds to skip.
+"""
+
+from __future__ import annotations
+
+from functools import cache
+
+from katalyst_engine.bundle.protocol import BundleManifest
+from katalyst_engine.core.identity import Identity
+from katalyst_engine.core.version import Version
+from katalyst_engine.schema.definition import (
+    NodeDefinition,
+    SchemaDefinition,
+    WingDefinition,
+)
+from katalyst_engine.schema.manager import SchemaManager
+from katalyst_engine.toolkit.linkml import LinkMLDefinitions, installed_definitions
+
+#: The bundle's entry-point name, as a profile's ``schemas`` list names it.
+BUNDLE_NAME = "scaffolding-schema"
+WING = "scaffolding"
+KIND = "node_wiring"
+
+#: The LinkML module this bundle builds its definitions from (``linkml/scaffolding.yaml``).
+MODULES = ("scaffolding",)
+
+
+@cache
+def _definitions() -> LinkMLDefinitions:
+    return installed_definitions(MODULES)
+
+
+NODE_WIRING: NodeDefinition = next(n for n in _definitions().nodes if n.describes_kind == KIND)
+SCAFFOLDING_WING: WingDefinition = next(w for w in _definitions().wings if w.identity.name == WING)
+
+
+class ScaffoldingSchemaBundle:
+    """Contributes ``node_wiring``, and the wing it lives in."""
+
+    @property
+    def manifest(self) -> BundleManifest:
+        return BundleManifest(
+            identity=Identity(kind="bundle", name=BUNDLE_NAME),
+            version=Version(major=0, minor=1),
+            modules=MODULES,
+            provided_kinds=frozenset({KIND}),
+            wing_names=frozenset({WING}),
+            description="Schema for the documents the scaffolding plugin reads",
+        )
+
+    def node_definitions(self) -> list[NodeDefinition]:
+        return [NODE_WIRING]
+
+    def wing_definitions(self) -> list[WingDefinition]:
+        return [SCAFFOLDING_WING]
+
+    def schema_definition(self) -> SchemaDefinition:
+        return SchemaDefinition(
+            identity=Identity(kind="schema", name=BUNDLE_NAME),
+            describes_kind="taxonomy",
+            api_version="v2alpha",
+            schema_version=Version(major=0, minor=1),
+            node_definitions=(NODE_WIRING.identity,),
+        )
+
+    def register(self, manager: SchemaManager) -> None:
+        manager.register_schema(self.schema_definition(), node_definitions=self.node_definitions())

katalyst_plugin_scaffolding-1.0.1a1/src/katalyst_plugin_scaffolding/templates/__init__.py

@@ -0,0 +1,6 @@
+"""Template bundles, as a taxonomy plugin.
+
+Installs, lists, describes and removes the template bundles a user config declares
+(``spec.templates``) — every bundle the same way, from its manifest in its declared
+source — and contributes the ``kata tax add`` command.
+"""