katalyst-forge 2.1.0__tar.gz

katalyst_forge-2.1.0/.gitignore

@@ -0,0 +1,104 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+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
+
+# Build artifacts
+site/
+stack-tests/cucumber-report/
+stack-tests/test-results/
+
+# Generated artifacts (rebuild with `just generate-schemas`)
+taxonomy/src/katalyst_taxonomy/engine/generated/

katalyst_forge-2.1.0/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: katalyst-forge
+Version: 2.1.0
+Summary: The Forge bundle — 31 node-type definitions for software delivery taxonomy
+Author: eSimplicity
+License: Proprietary
+Requires-Python: >=3.12
+Requires-Dist: katalyst-engine

katalyst_forge-2.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[project]
+name = "katalyst-forge"
+version = "2.1.0"
+description = "The Forge bundle — 31 node-type definitions for software delivery taxonomy"
+license = { text = "Proprietary" }
+requires-python = ">=3.12"
+authors = [
+    { name = "eSimplicity" }
+]
+dependencies = [
+    "katalyst-engine",
+]
+
+[project.entry-points."katalyst_engine.bundles"]
+forge = "katalyst_forge.bundle:ForgeBundle"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/katalyst_forge"]
+
+[tool.hatch.build.targets.wheel.sources]
+"src" = ""
+
+[tool.hatch.build]
+include = [
+    "src/katalyst_forge/**/*.py",
+    "src/katalyst_forge/**/*.yaml.j2",
+    "src/katalyst_forge/**/*.yaml",
+    "src/katalyst_forge/**/*.json",
+    "src/katalyst_forge/**/*.tf",
+    "src/katalyst_forge/**/*.hcl",
+    "src/katalyst_forge/**/*.md",
+    "src/katalyst_forge/**/*.just",
+    "src/katalyst_forge/**/*.sh",
+    "src/katalyst_forge/**/Justfile",
+    "src/katalyst_forge/**/Dockerfile",
+    "src/katalyst_forge/**/.dockerignore",
+    "src/katalyst_forge/**/.env.example",
+    "src/katalyst_forge/py.typed",
+]

katalyst_forge-2.1.0/src/katalyst_forge/__init__.py

@@ -0,0 +1,10 @@
+"""katalyst-forge — The Forge bundle for katalyst-engine.
+
+Provides 33 node-type definitions across 8 wings for software delivery taxonomy.
+"""
+
+from __future__ import annotations
+
+from katalyst_forge.bundle import ForgeBundle
+
+__all__ = ["ForgeBundle"]

katalyst_forge-2.1.0/src/katalyst_forge/bundle.py

@@ -0,0 +1,175 @@
+"""Forge bundle — the pre-installed taxonomy for software delivery.
+
+Assembles 33 node types across 8 wings from the wing modules into
+a single ``ForgeBundle`` that implements the engine's ``Bundle``
+protocol. Discovered via the ``katalyst_engine.bundles`` entry point.
+
+"Forge" — where delivery artifacts are forged.
+
+Wing modules:
+- ``wings/system.py``    — system, environment, stack, layer, library, capability
+- ``wings/org.py``       — organization, program, project, team, team_member, role
+- ``wings/practices.py`` — practice_area, competency, skill, tool
+- ``wings/design.py``    — business_domain_model, user_type, user_story, adr, nfr, specification, assertion
+- ``wings/delivery.py``  — work_item, change_entry
+- ``wings/dx.py``        — template, action, template_overlay
+- ``wings/pipeline.py``  — cicd_stage, cicd_job_template, cicd_workflow_template
+- ``wings/agentic.py``   — agent, agent_skill
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+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,
+    RelationshipDefinition,
+    SchemaDefinition,
+    WingDefinition,
+)
+from katalyst_engine.schema.manager import SchemaManager
+
+from katalyst_forge.relationships import ALL_RELATIONSHIP_DEFINITIONS
+from katalyst_forge.wings.agentic import AGENTIC_WING, AGENTIC_WING_NODES
+from katalyst_forge.wings.delivery import DELIVERY_WING, DELIVERY_WING_NODES
+from katalyst_forge.wings.design import DESIGN_WING, DESIGN_WING_NODES
+from katalyst_forge.wings.dx import DX_WING, DX_WING_NODES
+from katalyst_forge.wings.org import ORG_WING, ORG_WING_NODES
+from katalyst_forge.wings.pipeline import PIPELINE_WING, PIPELINE_WING_NODES
+from katalyst_forge.wings.practices import PRACTICES_WING, PRACTICES_WING_NODES
+from katalyst_forge.wings.system import SYSTEM_WING, SYSTEM_WING_NODES
+
+# ---------------------------------------------------------------------------
+# Aggregate all definitions from wing modules
+# ---------------------------------------------------------------------------
+
+ALL_NODE_DEFINITIONS: list[NodeDefinition] = [
+    *SYSTEM_WING_NODES,
+    *ORG_WING_NODES,
+    *PRACTICES_WING_NODES,
+    *DESIGN_WING_NODES,
+    *DELIVERY_WING_NODES,
+    *DX_WING_NODES,
+    *PIPELINE_WING_NODES,
+    *AGENTIC_WING_NODES,
+]
+
+ALL_KINDS: frozenset[str] = frozenset(nd.describes_kind for nd in ALL_NODE_DEFINITIONS)
+
+ALL_WING_DEFINITIONS: list[WingDefinition] = [
+    SYSTEM_WING,
+    ORG_WING,
+    DESIGN_WING,
+    DELIVERY_WING,
+    PRACTICES_WING,
+    DX_WING,
+    PIPELINE_WING,
+    AGENTIC_WING,
+]
+
+ALL_WING_NAMES: frozenset[str] = frozenset(wd.identity.name for wd in ALL_WING_DEFINITIONS)
+
+
+# ---------------------------------------------------------------------------
+# Bundle class
+# ---------------------------------------------------------------------------
+
+
+class ForgeBundle:
+    """The Forge bundle — 33 node types across 8 wings.
+
+    This is the pre-installed taxonomy bundle that ships with
+    Katalyst Taxonomy. It models software delivery organizations
+    using systems, stacks, layers, teams, practices, and more.
+
+    "Forge" — where delivery artifacts are forged.
+    """
+
+    @property
+    def manifest(self) -> BundleManifest:
+        return BundleManifest(
+            identity=Identity(kind="bundle", name="forge"),
+            version=Version(major=2, minor=0),
+            provided_kinds=ALL_KINDS,
+            wing_names=ALL_WING_NAMES,
+            description="Forge taxonomy — 33 node types for modeling software delivery organizations",
+        )
+
+    def node_definitions(self) -> list[NodeDefinition]:
+        return list(ALL_NODE_DEFINITIONS)
+
+    def wing_definitions(self) -> list[WingDefinition]:
+        return list(ALL_WING_DEFINITIONS)
+
+    def relationship_definitions(self) -> list[RelationshipDefinition]:
+        return list(ALL_RELATIONSHIP_DEFINITIONS)
+
+    def schema_definition(self) -> SchemaDefinition:
+        return SchemaDefinition(
+            identity=Identity(kind="schema", name="forge"),
+            describes_kind="taxonomy",
+            api_version="v2alpha",
+            schema_version=Version(major=2),
+            node_definitions=tuple(nd.identity for nd in ALL_NODE_DEFINITIONS),
+            wing_definitions=tuple(wd.identity for wd in ALL_WING_DEFINITIONS),
+        )
+
+    def register(self, manager: SchemaManager) -> None:
+        manager.register_schema(
+            self.schema_definition(),
+            node_definitions=self.node_definitions(),
+            wing_definitions=self.wing_definitions(),
+            relationship_definitions=self.relationship_definitions(),
+        )
+
+    # ------------------------------------------------------------------
+    # Optional template declarations
+    # ------------------------------------------------------------------
+
+    def creation_templates(self) -> dict[str, str]:
+        """Return the 7 creation templates for Forge node types.
+
+        Templates are Jinja2-rendered ``.yaml.j2`` files that produce
+        the taxonomy YAML document when a node is created. The ``_base``
+        key provides a generic fallback for kinds without a dedicated
+        template.
+
+        Returns:
+            Mapping of kind name (or ``"_base"``) to template content.
+        """
+        creation_dir = Path(__file__).parent / "templates" / "creation"
+        templates: dict[str, str] = {}
+        if not creation_dir.is_dir():
+            return templates
+        for template_file in sorted(creation_dir.glob("*.yaml.j2")):
+            if template_file.name.startswith("_"):
+                # _base.yaml.j2 → key "_base"
+                key = template_file.stem.split(".")[0]  # "_base"
+            else:
+                # system.yaml.j2 → key "system"
+                key = template_file.stem.split(".")[0]
+            templates[key] = template_file.read_text(encoding="utf-8")
+        return templates
+
+    def scaffold_templates(self) -> dict[str, Path]:
+        """Return scaffold template directories for layer variants.
+
+        Each subdirectory under ``templates/bundled/plugins/layer_types/``
+        is a scaffold variant (e.g. ``app-docker``, ``iac-terragrunt``).
+        Keys use the format ``layer:{variant}`` so the scaffolding plugin
+        can look up templates by ``(node_kind, scaffold_variant)``.
+
+        Returns:
+            Mapping of ``"layer:{variant}"`` to the scaffold directory path.
+        """
+        scaffold_dir = Path(__file__).parent / "templates" / "scaffolds"
+        result: dict[str, Path] = {}
+        if not scaffold_dir.is_dir():
+            return result
+        for child in sorted(scaffold_dir.iterdir()):
+            if child.is_dir():
+                result[f"layer:{child.name}"] = child
+        return result

katalyst_forge-2.1.0/src/katalyst_forge/relationships.py

@@ -0,0 +1,263 @@
+"""Relationship definitions for the Forge bundle."""
+
+from __future__ import annotations
+
+from katalyst_engine.core.identity import Identity
+from katalyst_engine.core.relation import Cardinality
+from katalyst_engine.schema.definition import RelationshipDefinition
+
+
+def _rel_id(name: str) -> Identity:
+    return Identity(kind="relationship_definition", name=name)
+
+
+# ── Structural wing ───────────────────────────────────────────────────
+
+CHILD_OF_REL = RelationshipDefinition(
+    identity=_rel_id("child_of"),
+    describes_kind="child_of",
+    description="Hierarchical parent-child containment",
+    wing="structural",
+    display_order=10,
+    cardinality=Cardinality.MANY_TO_ONE,
+    directed=True,
+    structural=True,
+)
+
+EXTENDS_REL = RelationshipDefinition(
+    identity=_rel_id("extends"),
+    describes_kind="extends",
+    description="Node augments target with additional behavior or configuration",
+    wing="structural",
+    display_order=20,
+    cardinality=Cardinality.MANY_TO_MANY,
+    directed=True,
+    structural=True,
+)
+
+DEPENDS_ON_REL = RelationshipDefinition(
+    identity=_rel_id("depends_on"),
+    describes_kind="depends_on",
+    description="Runtime or build dependency between nodes",
+    wing="structural",
+    display_order=30,
+    cardinality=Cardinality.MANY_TO_MANY,
+    directed=True,
+    structural=True,
+)
+
+DEPLOYS_TO_REL = RelationshipDefinition(
+    identity=_rel_id("deploys_to"),
+    describes_kind="deploys_to",
+    description="Node is deployed to an environment",
+    wing="structural",
+    display_order=40,
+    cardinality=Cardinality.MANY_TO_MANY,
+    directed=True,
+    structural=True,
+)
+
+# ── Capability wing ──────────────────────────────────────────────────
+
+PROVIDES_CAPABILITY_REL = RelationshipDefinition(
+    identity=_rel_id("provides_capability"),
+    describes_kind="provides_capability",
+    description="System, stack, or layer provides a capability",
+    wing="capability",
+    display_order=100,
+    cardinality=Cardinality.MANY_TO_MANY,
+)
+
+REQUIRES_CAPABILITY_REL = RelationshipDefinition(
+    identity=_rel_id("requires_capability"),
+    describes_kind="requires_capability",
+    description="User story requires a capability",
+    wing="capability",
+    display_order=110,
+    cardinality=Cardinality.MANY_TO_MANY,
+)
+
+DEPENDS_ON_CAPABILITY_REL = RelationshipDefinition(
+    identity=_rel_id("depends_on_capability"),
+    describes_kind="depends_on_capability",
+    description="Capability depends on another capability",
+    wing="capability",
+    display_order=120,
+    cardinality=Cardinality.MANY_TO_MANY,
+)
+
+SPECIFIES_CAPABILITY_REL = RelationshipDefinition(
+    identity=_rel_id("specifies_capability"),
+    describes_kind="specifies_capability",
+    description="Specification defines requirements for a capability",
+    wing="capability",
+    display_order=130,
+    cardinality=Cardinality.MANY_TO_MANY,
+)
+
+TESTS_CAPABILITY_REL = RelationshipDefinition(
+    identity=_rel_id("tests_capability"),
+    describes_kind="tests_capability",
+    description="Assertion verifies a capability",
+    wing="capability",
+    display_order=140,
+    cardinality=Cardinality.MANY_TO_MANY,
+)
+
+# ── Organizational wing ──────────────────────────────────────────────
+
+FILLED_BY_REL = RelationshipDefinition(
+    identity=_rel_id("filled_by"),
+    describes_kind="filled_by",
+    description="Role is filled by team members",
+    wing="organizational",
+    display_order=200,
+    cardinality=Cardinality.MANY_TO_MANY,
+)
+
+DEVELOPS_COMPETENCY_REL = RelationshipDefinition(
+    identity=_rel_id("develops_competency"),
+    describes_kind="develops_competency",
+    description="Practice area develops a competency",
+    wing="organizational",
+    display_order=210,
+    cardinality=Cardinality.MANY_TO_MANY,
+)
+
+USES_TOOL_REL = RelationshipDefinition(
+    identity=_rel_id("uses_tool"),
+    describes_kind="uses_tool",
+    description="Practice area uses a tool",
+    wing="organizational",
+    display_order=220,
+    cardinality=Cardinality.MANY_TO_MANY,
+)
+
+REQUIRES_SKILL_REL = RelationshipDefinition(
+    identity=_rel_id("requires_skill"),
+    describes_kind="requires_skill",
+    description="Competency requires a skill",
+    wing="organizational",
+    display_order=230,
+    cardinality=Cardinality.MANY_TO_MANY,
+)
+
+# ── Verification wing ────────────────────────────────────────────────
+
+VERIFIED_BY_REL = RelationshipDefinition(
+    identity=_rel_id("verified_by"),
+    describes_kind="verified_by",
+    description="Specification is verified by assertions",
+    wing="verification",
+    display_order=300,
+    cardinality=Cardinality.MANY_TO_MANY,
+)
+
+TESTS_SPECIFICATION_REL = RelationshipDefinition(
+    identity=_rel_id("tests_specification"),
+    describes_kind="tests_specification",
+    description="Assertion tests a specification",
+    wing="verification",
+    display_order=310,
+    cardinality=Cardinality.MANY_TO_MANY,
+)
+
+CAPTURES_STORY_REL = RelationshipDefinition(
+    identity=_rel_id("captures_story"),
+    describes_kind="captures_story",
+    description="Specification captures a user story",
+    wing="verification",
+    display_order=320,
+    cardinality=Cardinality.MANY_TO_MANY,
+)
+
+# ── Workflow wing ─────────────────────────────────────────────────────
+
+BLOCKS_REL = RelationshipDefinition(
+    identity=_rel_id("blocks"),
+    describes_kind="blocks",
+    description="Work item blocks another work item",
+    wing="workflow",
+    display_order=400,
+    cardinality=Cardinality.MANY_TO_MANY,
+)
+
+BLOCKED_BY_REL = RelationshipDefinition(
+    identity=_rel_id("blocked_by"),
+    describes_kind="blocked_by",
+    description="Work item is blocked by another work item",
+    wing="workflow",
+    display_order=410,
+    cardinality=Cardinality.MANY_TO_MANY,
+)
+
+SUPERSEDED_BY_REL = RelationshipDefinition(
+    identity=_rel_id("superseded_by"),
+    describes_kind="superseded_by",
+    description="ADR is superseded by another ADR",
+    wing="workflow",
+    display_order=420,
+    cardinality=Cardinality.MANY_TO_ONE,
+)
+
+REFERENCES_ROAD_ITEM_REL = RelationshipDefinition(
+    identity=_rel_id("references_road_item"),
+    describes_kind="references_road_item",
+    description="Change entry references a road item",
+    wing="workflow",
+    display_order=430,
+    cardinality=Cardinality.MANY_TO_ONE,
+)
+
+# ── Pipeline wing ────────────────────────────────────────────────────
+
+STAGE_DEPENDS_ON_REL = RelationshipDefinition(
+    identity=_rel_id("stage_depends_on"),
+    describes_kind="stage_depends_on",
+    description="CI/CD stage depends on another stage",
+    wing="pipeline",
+    display_order=500,
+    cardinality=Cardinality.MANY_TO_MANY,
+)
+
+BELONGS_TO_STAGE_REL = RelationshipDefinition(
+    identity=_rel_id("belongs_to_stage"),
+    describes_kind="belongs_to_stage",
+    description="CI/CD job template belongs to a stage",
+    wing="pipeline",
+    display_order=510,
+    cardinality=Cardinality.MANY_TO_ONE,
+)
+
+# ── Aggregate list ────────────────────────────────────────────────────
+
+ALL_RELATIONSHIP_DEFINITIONS: list[RelationshipDefinition] = [
+    # structural
+    CHILD_OF_REL,
+    EXTENDS_REL,
+    DEPENDS_ON_REL,
+    DEPLOYS_TO_REL,
+    # capability
+    PROVIDES_CAPABILITY_REL,
+    REQUIRES_CAPABILITY_REL,
+    DEPENDS_ON_CAPABILITY_REL,
+    SPECIFIES_CAPABILITY_REL,
+    TESTS_CAPABILITY_REL,
+    # organizational
+    FILLED_BY_REL,
+    DEVELOPS_COMPETENCY_REL,
+    USES_TOOL_REL,
+    REQUIRES_SKILL_REL,
+    # verification
+    VERIFIED_BY_REL,
+    TESTS_SPECIFICATION_REL,
+    CAPTURES_STORY_REL,
+    # workflow
+    BLOCKS_REL,
+    BLOCKED_BY_REL,
+    SUPERSEDED_BY_REL,
+    REFERENCES_ROAD_ITEM_REL,
+    # pipeline
+    STAGE_DEPENDS_ON_REL,
+    BELONGS_TO_STAGE_REL,
+]

katalyst_forge-2.1.0/src/katalyst_forge/templates/creation/_base.yaml.j2

@@ -0,0 +1,12 @@
+apiVersion: katalyst.taxonomy/v2alpha
+kind: {{ node_type }}
+metadata:
+  name: "{{ name }}"
+spec:
+  description: "{{ description }}"
+  owners:
+    - "{{ primary_owner }}"
+  annotations:
+    templateVersion: "{{ template_version }}"
+{{ parents_block }}  environments:
+{{ environments_block }}

katalyst_forge-2.1.0/src/katalyst_forge/templates/creation/layer.yaml.j2

@@ -0,0 +1,21 @@
+apiVersion: katalyst.taxonomy/v2alpha
+kind: layer
+metadata:
+  name: "{{ name }}"
+spec:
+  description: "{{ description }}"
+  owners:
+    - "{{ primary_owner }}"
+  annotations:
+    layout: root
+    layerType: "{{ layer_type }}"
+    templateVersion: "{{ template_version }}"
+    layerTypeVersion: "{{ layer_type_version }}"
+  parents:
+    node: "{{ parent_stack }}"
+  environments:
+{{ environments_block }}
+  dependsOn:
+    nodes:
+      - "{{ parent_stack }}"
+  extensions: {}

katalyst_forge-2.1.0/src/katalyst_forge/templates/creation/project.yaml.j2

@@ -0,0 +1,16 @@
+apiVersion: katalyst.taxonomy/v2alpha
+kind: project
+metadata:
+  name: "{{ name }}"
+spec:
+  description: "{{ description }}"
+  owners:
+    - "{{ primary_owner }}"
+  annotations:
+    templateVersion: "{{ template_version }}"
+  parents:
+    node: "{{ parent }}"
+  environments:
+{{ environments_block }}
+  project:
+    status: active

katalyst_forge-2.1.0/src/katalyst_forge/templates/creation/stack.yaml.j2

@@ -0,0 +1,18 @@
+apiVersion: katalyst.taxonomy/v2alpha
+kind: stack
+metadata:
+  name: "{{ name }}"
+spec:
+  description: "{{ description }}"
+  owners:
+    - "{{ primary_owner }}"
+  annotations:
+    layout: root
+    templateVersion: "{{ template_version }}"
+  parents:
+    node: "{{ parent_system }}"
+  environments:
+{{ environments_block }}
+  dependsOn:
+    nodes:
+      - "{{ parent_system }}"

katalyst_forge-2.1.0/src/katalyst_forge/templates/creation/system.yaml.j2

@@ -0,0 +1,15 @@
+apiVersion: katalyst.taxonomy/v2alpha
+kind: system
+metadata:
+  name: "{{ name }}"
+spec:
+  description: "{{ description }}"
+  owners:
+    - "{{ primary_owner }}"
+  annotations:
+    layout: root
+    templateVersion: "{{ template_version }}"
+{{ parents_block }}  environments:
+{{ environments_block }}
+  dependsOn:
+    nodes: []