operaton-contracts 0.1.0__py3-none-any.whl

OperatonContracts/__init__.py

@@ -0,0 +1,61 @@
+"""Engine-facing Operaton external task contracts.
+
+A worker declares one ``TaskContract`` input and output model per external
+task topic. Element templates are generated from those models (see
+``OperatonContracts.templates`` and the ``operaton-contracts`` command), and
+tasks validate their variables against them at runtime with
+``validate_input`` and ``validate_output``.
+
+With the ``robot`` extra, the package is also a Robot Framework library:
+
+    *** Settings ***
+    Library     OperatonContracts    OperatonTasks
+
+    *** Tasks ***
+    Rescind Study Rights
+        ${input}=    Validate Task Input    RescindStudyRightsInput
+
+The library class is imported lazily, so ``import OperatonContracts`` never
+loads Robot Framework.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+from typing import Any
+
+from OperatonContracts.contracts import TEMPLATE_KEY
+from OperatonContracts.contracts import TaskContract
+from OperatonContracts.contracts import load_contract
+from OperatonContracts.contracts import template_hints
+from OperatonContracts.contracts import validate_input
+from OperatonContracts.contracts import validate_output
+
+if TYPE_CHECKING:
+    from OperatonContracts.robotframework import OperatonContracts
+
+__all__ = [
+    "TEMPLATE_KEY",
+    "OperatonContracts",
+    "TaskContract",
+    "load_contract",
+    "template_hints",
+    "validate_input",
+    "validate_output",
+]
+
+
+def __getattr__(name: str) -> Any:
+    # Robot Framework finds the library class with getattr(module, name).
+    if name == "OperatonContracts":
+        try:
+            from OperatonContracts.robotframework import OperatonContracts
+        except ModuleNotFoundError as error:
+            if error.name is None or not error.name.startswith("robot"):
+                raise
+            raise ImportError(
+                "The OperatonContracts Robot Framework library needs Robot "
+                "Framework: install operaton-contracts[robot]"
+            ) from error
+        return OperatonContracts
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

OperatonContracts/__main__.py

@@ -0,0 +1,3 @@
+from OperatonContracts.cli import main
+
+raise SystemExit(main())

OperatonContracts/checks.py

@@ -0,0 +1,88 @@
+"""Consistency checks between template specs, purjo topics, and task suites."""
+
+from __future__ import annotations
+
+import tomllib
+from collections.abc import Iterable
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Any
+from typing import Protocol
+
+from OperatonContracts.templates import TaskTemplate
+
+MISSING_ROBOT = (
+    "Robot suite checks need Robot Framework: install operaton-contracts[robot]"
+)
+
+
+class _TaskSuites(Protocol):
+    def check(self, spec: TaskTemplate, task: str) -> list[str]: ...
+
+
+def _robot_suites(root: Path) -> _TaskSuites | None:
+    try:
+        from OperatonContracts.robotframework import RobotSuites
+    except ImportError:
+        return None
+    return RobotSuites(root)
+
+
+def _duplicates(values: Iterable[str]) -> list[str]:
+    seen: set[str] = set()
+    duplicates: list[str] = []
+    for value in values:
+        if value in seen:
+            duplicates.append(value)
+        seen.add(value)
+    return duplicates
+
+
+def check_package(
+    root: Path,
+    specs: Sequence[TaskTemplate],
+    *,
+    reserved_topics: Iterable[str] = (),
+) -> list[str]:
+    """Return mismatches between specs, external task topics, and task suites.
+
+    The suite checks need Robot Framework; without it, configured topics are
+    reported as unchecked instead of silently passing.
+    """
+    errors: list[str] = []
+    with (root / "pyproject.toml").open("rb") as stream:
+        tool = tomllib.load(stream).get("tool", {}).get("purjo", {})
+    topics: dict[str, dict[str, Any]] = tool.get("topics", {})
+
+    for label, values in (
+        ("topic", [spec.topic for spec in specs]),
+        ("template id", [spec.template_id for spec in specs]),
+        ("filename", [spec.filename for spec in specs]),
+    ):
+        errors.extend(f"Duplicate {label}: {value}" for value in _duplicates(values))
+    reserved = set(reserved_topics)
+    errors.extend(
+        f"Topic is reserved: {spec.topic}" for spec in specs if spec.topic in reserved
+    )
+    spec_topics = {spec.topic for spec in specs}
+    errors.extend(
+        f"Topic has no template spec: {topic}"
+        for topic in sorted(set(topics) - spec_topics)
+    )
+
+    suites = _robot_suites(root)
+    unchecked = False
+    for spec in specs:
+        config = topics.get(spec.topic)
+        if config is None:
+            errors.append(f"Topic missing from [tool.purjo.topics]: {spec.topic}")
+            continue
+        if config.get("process-variables") is not False:
+            errors.append(f"{spec.topic}: set process-variables = false")
+        if suites is None:
+            unchecked = True
+            continue
+        errors.extend(suites.check(spec, config.get("name", "")))
+    if unchecked:
+        errors.append(MISSING_ROBOT)
+    return errors

OperatonContracts/cli.py

@@ -0,0 +1,124 @@
+"""``operaton-contracts`` command: generate, check, and validate templates.
+
+Configured in the robot package's ``pyproject.toml``::
+
+    [tool.operaton-contracts]
+    specs = "scripts.element_templates:TEMPLATES"   # module:attribute
+    icon = "scripts/logo.svg"                       # optional
+    schema-url = "https://…?job=release"            # optional, pinned default
+    reserved-topics = ["legacy.topic"]              # optional
+"""
+
+from __future__ import annotations
+
+import argparse
+import importlib
+import sys
+import tomllib
+from collections.abc import Sequence
+from dataclasses import dataclass
+from pathlib import Path
+
+from OperatonContracts.templates import DEFAULT_SCHEMA_URL
+from OperatonContracts.templates import TEMPLATE_DIR
+from OperatonContracts.templates import TaskTemplate
+from OperatonContracts.checks import check_package
+from OperatonContracts.templates import drift
+from OperatonContracts.templates import render_all
+from OperatonContracts.templates import validate
+from OperatonContracts.templates import write_templates
+
+CONFIG_TABLE = "operaton-contracts"
+
+
+class ConfigError(ValueError):
+    """The ``[tool.operaton-contracts]`` configuration is missing or invalid."""
+
+
+@dataclass(frozen=True)
+class Config:
+    root: Path
+    specs: tuple[TaskTemplate, ...]
+    icon_svg: bytes
+    schema_url: str
+    reserved_topics: tuple[str, ...]
+
+    @property
+    def template_dir(self) -> Path:
+        return self.root / TEMPLATE_DIR
+
+
+def load_config(root: Path) -> Config:
+    """Load the configuration and import the specs relative to ``root``."""
+    pyproject = root / "pyproject.toml"
+    if not pyproject.exists():
+        raise ConfigError(f"{pyproject} not found")
+    with pyproject.open("rb") as stream:
+        table = tomllib.load(stream).get("tool", {}).get(CONFIG_TABLE)
+    if not isinstance(table, dict) or not isinstance(table.get("specs"), str):
+        raise ConfigError(
+            f'Set [tool.{CONFIG_TABLE}] specs = "module:ATTRIBUTE" in {pyproject}'
+        )
+    module_name, _, attribute = table["specs"].partition(":")
+    if str(root) not in sys.path:
+        sys.path.insert(0, str(root))
+    specs = getattr(importlib.import_module(module_name), attribute or "TEMPLATES")
+    if not all(isinstance(spec, TaskTemplate) for spec in specs):
+        raise ConfigError(f"{table['specs']} must be a sequence of TaskTemplate")
+    icon = table.get("icon")
+    return Config(
+        root=root,
+        specs=tuple(specs),
+        icon_svg=(root / icon).read_bytes() if icon else b"",
+        schema_url=str(table.get("schema-url", DEFAULT_SCHEMA_URL)),
+        reserved_topics=tuple(table.get("reserved-topics", ())),
+    )
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="operaton-contracts",
+        description="Generate, check, and validate Operaton element templates.",
+    )
+    parser.add_argument(
+        "command",
+        nargs="?",
+        default="check",
+        choices=("generate", "check", "validate"),
+        help="generate templates, check them offline (default), or validate "
+        "them against the pinned upstream schema",
+    )
+    parser.add_argument(
+        "--root",
+        type=Path,
+        default=Path.cwd(),
+        help="robot package directory (default: current directory)",
+    )
+    arguments = parser.parse_args(argv)
+    try:
+        config = load_config(arguments.root.resolve())
+    except ConfigError as error:
+        print(error, file=sys.stderr)
+        return 2
+
+    if arguments.command == "validate":
+        validate(sorted(config.template_dir.glob("*.json")), config.schema_url)
+        return 0
+    rendered = render_all(
+        config.specs, icon_svg=config.icon_svg, schema_url=config.schema_url
+    )
+    if arguments.command == "generate":
+        for message in write_templates(config.template_dir, rendered):
+            print(message)
+        return 0
+
+    errors = check_package(
+        config.root, config.specs, reserved_topics=config.reserved_topics
+    )
+    errors.extend(drift(config.template_dir, rendered))
+    for message in errors:
+        print(message, file=sys.stderr)
+    if errors:
+        return 1
+    print("Element templates are up to date")
+    return 0

OperatonContracts/contracts.py

@@ -0,0 +1,105 @@
+"""Task contracts and their runtime validation, independent of any task runner."""
+
+from __future__ import annotations
+
+import importlib
+import sys
+from collections.abc import Iterable
+from collections.abc import Mapping
+from types import ModuleType
+from typing import Any
+
+from pydantic import BaseModel
+from pydantic import ConfigDict
+from pydantic import JsonValue
+
+TEMPLATE_KEY = "x-element-template"
+HINT_KEYS = frozenset({"type", "value"})
+
+
+class TaskContract(BaseModel):
+    """Base for engine-facing task input and output contracts.
+
+    Every field needs an ``alias`` (the process variable name) and a
+    ``title`` (the template label). Field order is template property order.
+    Validation is strict: use ``Field(strict=False)`` for values the engine
+    sends as text, such as dates.
+    """
+
+    model_config = ConfigDict(
+        extra="forbid",
+        populate_by_name=True,
+        strict=True,
+        str_strip_whitespace=True,
+    )
+
+
+def template_hints(**hints: JsonValue) -> dict[str, JsonValue]:
+    """Return ``json_schema_extra`` with template-only property hints.
+
+    ``value`` overrides the template default value; ``type`` overrides the
+    template property type inferred from the JSON Schema. Required string
+    properties and non-empty strings or lists get ``notEmpty``.
+    """
+    unknown = sorted(set(hints) - HINT_KEYS)
+    if unknown:
+        raise ValueError(f"Unknown template hint(s): {', '.join(unknown)}")
+    return {TEMPLATE_KEY: hints}
+
+
+def aliases(contract: type[TaskContract]) -> list[str]:
+    """Return the contract's process variable names in field order."""
+    return [info.alias or name for name, info in contract.model_fields.items()]
+
+
+def validate_input(
+    contract: type[TaskContract], variables: Mapping[str, Any]
+) -> dict[str, Any]:
+    """Validate process variables against an input contract.
+
+    Only the contract's aliases are read from ``variables``, so a task's full
+    variable map can be passed; missing ones fall back to contract defaults.
+    Returns the values normalized and JSON-compatible (dates become
+    ``YYYY-MM-DD`` strings), keyed by alias.
+    """
+    data = {
+        alias: variables[alias] for alias in aliases(contract) if alias in variables
+    }
+    return contract.model_validate(data).model_dump(mode="json", by_alias=True)
+
+
+def validate_output(
+    contract: type[TaskContract], values: Mapping[str, Any]
+) -> dict[str, Any]:
+    """Validate a task's results against an output contract.
+
+    Unlike inputs, every value is checked: unknown keys are rejected. Returns
+    JSON-compatible values keyed by alias, ready to hand back to the engine.
+    """
+    return contract.model_validate(dict(values)).model_dump(mode="json", by_alias=True)
+
+
+def load_contract(module: ModuleType, name: str) -> type[TaskContract]:
+    """Return the ``TaskContract`` subclass called ``name`` from ``module``."""
+    contract = getattr(module, name, None)
+    if not (isinstance(contract, type) and issubclass(contract, TaskContract)):
+        raise ValueError(f"{name} is not a TaskContract in {module.__name__}")
+    return contract
+
+
+def import_contracts(name: str, fallback_dirs: Iterable[str] = ()) -> ModuleType:
+    """Import the contracts module, retrying from ``fallback_dirs``.
+
+    A directory is added to ``sys.path`` only when the module itself (not one
+    of its dependencies) is missing and the directory is not there already.
+    """
+    try:
+        return importlib.import_module(name)
+    except ModuleNotFoundError as error:
+        if error.name != name:
+            raise
+        for directory in fallback_dirs:
+            if directory not in sys.path:
+                sys.path.insert(0, directory)
+                return importlib.import_module(name)
+        raise

OperatonContracts/robotframework.py

@@ -0,0 +1,212 @@
+"""Robot Framework integration: the ``OperatonContracts`` library and suite checks.
+
+Requires the ``robot`` extra (``robotframework``). The rest of the package
+works without it.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from dataclasses import field
+from pathlib import Path
+from typing import Any
+
+from robot.api import get_model
+from robot.api.deco import keyword
+from robot.api.deco import library
+from robot.api.parsing import ModelVisitor
+from robot.libraries.BuiltIn import BuiltIn
+from robot.libraries.BuiltIn import RobotNotRunningError
+
+from OperatonContracts.contracts import aliases
+from OperatonContracts.contracts import import_contracts
+from OperatonContracts.contracts import load_contract
+from OperatonContracts.contracts import validate_input
+from OperatonContracts.templates import TaskTemplate
+from OperatonContracts.templates import contract_properties
+
+TASK_SCOPE = "${BPMN:TASK}"
+VALIDATE_KEYWORD = "Validate Task Input"
+# Directories never collected as task suites (purjo collects suites
+# recursively; tests and tooling are excluded from robot.zip by .wrapignore).
+SKIPPED_DIRS = frozenset({"tests", "lib", "examples", "node_modules", "__pycache__"})
+_MISSING = object()
+
+
+def _suite_directory() -> str | None:
+    """Return the directory of the running suite, if Robot is running."""
+    try:
+        source = BuiltIn().get_variable_value("${SUITE SOURCE}")
+    except RobotNotRunningError:
+        return None
+    if not source:
+        return None
+    path = Path(source)
+    return str(path if path.is_dir() else path.parent)
+
+
+@library(scope="GLOBAL", auto_keywords=False)
+class OperatonContracts:
+    """Validates Robot task variables against ``TaskContract`` models.
+
+    Import it with the name of the module that holds the contracts:
+    ``Library    OperatonContracts    OperatonTasks``. purjo and
+    ``python -m robot`` run with the robot package on ``sys.path``; otherwise
+    the module is imported from the running suite's directory.
+    """
+
+    def __init__(self, contracts: str = "OperatonTasks") -> None:
+        directory = _suite_directory()
+        self._module = import_contracts(contracts, [directory] if directory else [])
+
+    @keyword("Validate Task Input")
+    def validate_task_input(self, contract: str) -> dict[str, Any]:
+        """Validate the task's input variables against ``contract``.
+
+        Reads ``${alias}`` for every contract field, validates the values,
+        and returns them normalized and JSON-compatible (dates become
+        ``YYYY-MM-DD`` strings), keyed by alias. Unset variables are left out
+        so contract defaults apply; suites normally declare typed defaults
+        (``${False}``, ``${0}``, ``@{EMPTY}``) that match the contract's.
+        """
+        model = load_contract(self._module, contract)
+        builtin = BuiltIn()
+        variables: dict[str, Any] = {}
+        for alias in aliases(model):
+            value = builtin.get_variable_value(f"${{{alias}}}", _MISSING)
+            if value is not _MISSING:
+                variables[alias] = value
+        return validate_input(model, variables)
+
+
+def normalize(name: str) -> str:
+    """Normalize a name the way Robot Framework matches keywords, tasks, and
+    variables: ignoring case, spaces, and underscores."""
+    return "".join(name.split()).replace("_", "").casefold()
+
+
+def _unwrap(token: str) -> str:
+    """Return ``name`` from ``${name}``, ``@{name}``, ``&{name}``, or ``name``."""
+    if len(token) > 3 and token[1] == "{" and token.endswith("}"):
+        return token[2:-1]
+    return token
+
+
+def _variable_name(token: str) -> str:
+    """Return the bare name of ``${name}``, ``@{name: type}``, or ``name``."""
+    return _unwrap(token).split(":", 1)[0].strip()
+
+
+def _is_typed(declared: str, values: tuple[str, ...]) -> bool:
+    """Whether a suite default yields a non-string value at runtime."""
+    if declared[0] in "@&" or ":" in declared[2:-1]:
+        return True
+    return len(values) == 1 and values[0].startswith(("${", "@{", "&{"))
+
+
+@dataclass
+class _Suite:
+    path: Path
+    # normalized name -> (declared name, values)
+    variables: dict[str, tuple[str, tuple[str, ...]]] = field(default_factory=dict)
+    # normalized task name -> normalized output names / contract names
+    task_outputs: dict[str, set[str]] = field(default_factory=dict)
+    task_contracts: dict[str, set[str]] = field(default_factory=dict)
+
+
+class _SuiteVisitor(ModelVisitor):  # type: ignore[misc]
+    def __init__(self, suite: _Suite) -> None:
+        self.suite = suite
+        self.task: str | None = None
+
+    def visit_Variable(self, node: Any) -> None:
+        name = normalize(_variable_name(node.name))
+        self.suite.variables[name] = (node.name, tuple(node.value))
+
+    def visit_TestCase(self, node: Any) -> None:
+        self.task = normalize(node.name)
+        self.suite.task_outputs[self.task] = set()
+        self.suite.task_contracts[self.task] = set()
+        self.generic_visit(node)
+        self.task = None
+
+    def visit_Var(self, node: Any) -> None:
+        scope = normalize(_unwrap(node.scope or ""))
+        if self.task is not None and scope == normalize("BPMN:TASK"):
+            name = normalize(_variable_name(node.name))
+            self.suite.task_outputs[self.task].add(name)
+
+    def visit_KeywordCall(self, node: Any) -> None:
+        keyword_name = (node.keyword or "").rsplit(".", 1)[-1]
+        if (
+            self.task is not None
+            and normalize(keyword_name) == normalize(VALIDATE_KEYWORD)
+            and node.args
+        ):
+            self.suite.task_contracts[self.task].add(node.args[0])
+
+
+def _suite_paths(root: Path) -> list[Path]:
+    return [
+        path
+        for path in sorted(root.rglob("*.robot"))
+        if not path.name.startswith("test_")
+        and not any(
+            part.startswith(".") or part in SKIPPED_DIRS
+            for part in path.relative_to(root).parts[:-1]
+        )
+    ]
+
+
+class RobotSuites:
+    """The robot package's task suites, for checking them against contracts."""
+
+    def __init__(self, root: Path) -> None:
+        self.root = root
+        # normalized task name -> every suite defining it
+        self.tasks: dict[str, list[_Suite]] = {}
+        for path in _suite_paths(root):
+            suite = _Suite(path)
+            _SuiteVisitor(suite).visit(get_model(path))
+            for task in suite.task_outputs:
+                self.tasks.setdefault(task, []).append(suite)
+
+    def check(self, spec: TaskTemplate, task: str) -> list[str]:
+        """Return mismatches between the suite defining ``task`` and ``spec``."""
+        matches = self.tasks.get(normalize(task), [])
+        if not matches:
+            return [f"{spec.topic}: no Robot suite defines task {task!r}"]
+        if len(matches) > 1:
+            names = ", ".join(str(m.path.relative_to(self.root)) for m in matches)
+            return [
+                f"{spec.topic}: task {task!r} is defined in several suites "
+                f"({names}); purjo would run all of them"
+            ]
+        suite = matches[0]
+        key = normalize(task)
+        errors: list[str] = []
+        for alias, schema, _required in contract_properties(spec.inputs):
+            declared = suite.variables.get(normalize(alias))
+            if declared is None:
+                errors.append(
+                    f"{suite.path.name}: input {alias!r} needs a default "
+                    "in *** Variables ***"
+                )
+            elif schema.get("type", "string") != "string" and not _is_typed(*declared):
+                errors.append(
+                    f"{suite.path.name}: default of {declared[0]} is a string; "
+                    f"use a typed default such as ${{False}}, ${{0}}, or @{{EMPTY}}"
+                )
+        for alias, _schema, _required in contract_properties(spec.outputs):
+            if normalize(alias) not in suite.task_outputs[key]:
+                errors.append(
+                    f"{suite.path.name}: task {task!r} must set output "
+                    f"{alias!r} with VAR ... scope={TASK_SCOPE}"
+                )
+        contract = spec.inputs.__name__
+        if contract not in suite.task_contracts[key]:
+            errors.append(
+                f"{suite.path.name}: task {task!r} must call "
+                f"{VALIDATE_KEYWORD}    {contract}"
+            )
+        return errors

OperatonContracts/templates.py

@@ -0,0 +1,287 @@
+"""Render and validate Operaton element templates from task contracts.
+
+Element templates are rendered from ``TaskTemplate`` specs and the
+``TaskContract`` models they reference. Schema validation needs the
+``templates`` extra (``jsonschema``).
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import re
+from collections.abc import Iterable
+from collections.abc import Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+from urllib.request import urlopen
+
+from OperatonContracts.contracts import TEMPLATE_KEY
+from OperatonContracts.contracts import TaskContract
+
+TEMPLATE_DIR = Path(".operaton") / "element-templates"
+DEFAULT_SCHEMA_URL = (
+    "https://gitlab.com/vasara-bpm/vscode-operaton-bpmn-js-modeler/"
+    "-/jobs/artifacts/v0.8.3/raw/"
+    "operaton-element-templates-schema-v0.8.3.json?job=release"
+)
+ALIAS_PATTERN = re.compile(r"[A-Za-z_][A-Za-z0-9_]*")
+# Input property types the Camunda 7 element-template schema allows, and the
+# JSON type each one's ``value`` must have.
+VALUE_TYPES: dict[str, type] = {
+    "String": str,
+    "Text": str,
+    "Hidden": str,
+    "Dropdown": str,
+    "Boolean": bool,
+    "List": list,
+}
+
+
+class TemplateError(ValueError):
+    """A contract model cannot be rendered as an element template."""
+
+
+@dataclass(frozen=True)
+class TemplateGroup:
+    """One property group in the modeler's properties panel."""
+
+    id: str
+    label: str
+
+
+DEFAULT_GROUPS = (
+    TemplateGroup("inputs", "Inputs"),
+    TemplateGroup("outputs", "Results"),
+)
+
+
+@dataclass(frozen=True)
+class TaskTemplate:
+    """Template-level metadata for one external task topic.
+
+    ``input_group`` and ``output_group`` are group ids from ``groups``; use
+    the same id for both to show every property in one group.
+    """
+
+    topic: str
+    template_id: str
+    name: str
+    description: str
+    filename: str
+    inputs: type[TaskContract]
+    outputs: type[TaskContract]
+    groups: tuple[TemplateGroup, ...] = DEFAULT_GROUPS
+    input_group: str = "inputs"
+    output_group: str = "outputs"
+    version: int = 1
+
+
+def contract_properties(
+    model: type[TaskContract],
+) -> list[tuple[str, dict[str, Any], bool]]:
+    for name, info in model.model_fields.items():
+        if info.alias is None:
+            raise TemplateError(f"{model.__name__}.{name} needs an alias")
+        if not ALIAS_PATTERN.fullmatch(info.alias):
+            raise TemplateError(
+                f"{model.__name__}.{name}: alias {info.alias!r} must be a plain "
+                "identifier usable as a Robot variable name"
+            )
+        if info.title is None:
+            raise TemplateError(f"{model.__name__}.{name} needs a title")
+    schema = model.model_json_schema(by_alias=True)
+    required = set(schema.get("required", ()))
+    return [
+        (alias, prop, alias in required)
+        for alias, prop in schema.get("properties", {}).items()
+    ]
+
+
+def _choices(values: Iterable[Any]) -> list[dict[str, Any]]:
+    return [{"name": str(value), "value": value} for value in values]
+
+
+def _input_property(
+    alias: str, schema: dict[str, Any], required: bool, group: str
+) -> dict[str, Any]:
+    hints: dict[str, Any] = schema.get(TEMPLATE_KEY, {})
+    prop: dict[str, Any] = {"label": schema["title"]}
+    if "description" in schema:
+        prop["description"] = schema["description"]
+
+    json_type = schema.get("type")
+    items: dict[str, Any] = schema.get("items", {})
+    if json_type == "boolean":
+        prop["type"] = "Boolean"
+    elif json_type == "string" and "enum" in schema:
+        prop["type"] = "Dropdown"
+        prop["choices"] = _choices(schema["enum"])
+    elif json_type == "string":
+        prop["type"] = "String"
+    elif json_type == "array" and items.get("type") == "string":
+        prop["type"] = "List"
+        if "enum" in items:
+            prop["display"] = "taglist"
+            prop["choices"] = _choices(items["enum"])
+        else:
+            prop["itemType"] = "String"
+    elif "type" not in hints:
+        raise TemplateError(
+            f"{alias}: unsupported JSON Schema {_describe(schema)}; Enum, "
+            "Optional, and nested models produce $ref/anyOf schemas. Use "
+            "Literal, a plain type, or add a type hint"
+        )
+    if "type" in hints:
+        prop["type"] = hints["type"]
+    if prop["type"] not in VALUE_TYPES:
+        raise TemplateError(
+            f"{alias}: template type {prop['type']!r} is not one of "
+            f"{', '.join(VALUE_TYPES)}"
+        )
+    if prop["type"] == "Dropdown" and "choices" not in prop:
+        raise TemplateError(f"{alias}: a Dropdown needs Literal choices")
+
+    if "value" in hints:
+        prop["value"] = hints["value"]
+    elif "default" in schema:
+        prop["value"] = schema["default"]
+    elif prop["type"] == "List":
+        prop["value"] = []
+    else:
+        prop["value"] = f"${{{alias}}}"
+    if not isinstance(prop["value"], VALUE_TYPES[prop["type"]]):
+        raise TemplateError(
+            f"{alias}: value {prop['value']!r} does not fit template type "
+            f"{prop['type']}; add a value hint"
+        )
+    if (
+        schema.get("minLength", 0) >= 1
+        or schema.get("minItems", 0) >= 1
+        or (required and prop["type"] == "String")
+    ):
+        prop["constraints"] = {"notEmpty": True}
+    prop["group"] = group
+    prop["binding"] = {"type": "camunda:inputParameter", "name": alias}
+    return prop
+
+
+def _describe(schema: dict[str, Any]) -> str:
+    keys = [key for key in ("type", "$ref", "anyOf", "allOf") if key in schema]
+    return ", ".join(f"{key}={schema[key]!r}" for key in keys) or "without a type"
+
+
+def _output_property(alias: str, schema: dict[str, Any], group: str) -> dict[str, Any]:
+    prop: dict[str, Any] = {"label": schema["title"]}
+    if "description" in schema:
+        prop["description"] = schema["description"]
+    prop.update(
+        {
+            "type": "String",
+            "value": alias,
+            "group": group,
+            "binding": {"type": "camunda:outputParameter", "source": f"${{{alias}}}"},
+        }
+    )
+    return prop
+
+
+def render(spec: TaskTemplate, *, icon_svg: bytes, schema_url: str) -> dict[str, Any]:
+    """Render one element template from its spec and contract models."""
+    group_ids = [group.id for group in spec.groups]
+    for group_id in (spec.input_group, spec.output_group):
+        if group_id not in group_ids:
+            raise TemplateError(f"{spec.topic}: unknown group id {group_id!r}")
+    properties: list[dict[str, Any]] = [
+        {
+            "label": "Implementation",
+            "type": "Hidden",
+            "value": "external",
+            "binding": {"type": "property", "name": "camunda:type"},
+        },
+        {
+            "label": "External Task Topic",
+            "type": "Hidden",
+            "value": spec.topic,
+            "binding": {"type": "property", "name": "camunda:topic"},
+        },
+    ]
+    properties.extend(
+        _input_property(alias, schema, required, spec.input_group)
+        for alias, schema, required in contract_properties(spec.inputs)
+    )
+    properties.extend(
+        _output_property(alias, schema, spec.output_group)
+        for alias, schema, _required in contract_properties(spec.outputs)
+    )
+    icon = base64.b64encode(icon_svg).decode("ascii")
+    return {
+        "$schema": schema_url,
+        "name": spec.name,
+        "id": spec.template_id,
+        "description": spec.description,
+        "version": spec.version,
+        "appliesTo": ["bpmn:ServiceTask"],
+        "groups": [{"id": group.id, "label": group.label} for group in spec.groups],
+        "properties": properties,
+        "icon": {"contents": f"data:image/svg+xml;base64,{icon}"},
+    }
+
+
+def dumps(template: dict[str, Any]) -> str:
+    """Serialize a template in the committed file format."""
+    return json.dumps(template, indent=2, ensure_ascii=False) + "\n"
+
+
+def validate(paths: Sequence[Path], schema_url: str) -> None:
+    """Validate template files against the pinned upstream schema."""
+    if not paths:
+        raise TemplateError("No element templates were found")
+    from jsonschema import Draft7Validator  # the "templates" extra
+
+    with urlopen(schema_url, timeout=30) as response:
+        schema = json.load(response)
+    Draft7Validator.check_schema(schema)
+    validator = Draft7Validator(schema)
+    for path in paths:
+        validator.validate(json.loads(path.read_text(encoding="utf-8")))
+        print(f"Validated {path.name}")
+
+
+def render_all(
+    specs: Sequence[TaskTemplate], *, icon_svg: bytes, schema_url: str
+) -> dict[str, str]:
+    """Render every spec, keyed by template filename."""
+    return {
+        spec.filename: dumps(render(spec, icon_svg=icon_svg, schema_url=schema_url))
+        for spec in specs
+    }
+
+
+def write_templates(template_dir: Path, rendered: dict[str, str]) -> list[str]:
+    """Write rendered templates, remove stale ones, and describe the changes."""
+    template_dir.mkdir(parents=True, exist_ok=True)
+    messages: list[str] = []
+    for path in sorted(template_dir.glob("*.json")):
+        if path.name not in rendered:
+            path.unlink()
+            messages.append(f"Removed stale {path.name}")
+    for filename, text in rendered.items():
+        (template_dir / filename).write_text(text, encoding="utf-8")
+        messages.append(f"Wrote {filename}")
+    return messages
+
+
+def drift(template_dir: Path, rendered: dict[str, str]) -> list[str]:
+    """Return differences between committed and rendered templates."""
+    errors = [
+        f"Stray element template: {path.name}"
+        for path in sorted(template_dir.glob("*.json"))
+        if path.name not in rendered
+    ]
+    for filename, text in rendered.items():
+        path = template_dir / filename
+        if not path.exists() or path.read_text(encoding="utf-8") != text:
+            errors.append(f"Out of date: {filename}; run generate")
+    return errors

operaton_contracts-0.1.0.dist-info/METADATA

@@ -0,0 +1,174 @@
+Metadata-Version: 2.5
+Name: operaton-contracts
+Version: 0.1.0
+Summary: Pydantic task contracts, runtime validation, and generated element templates for Operaton external tasks, with optional Robot Framework support
+Project-URL: Homepage, https://datakurre.github.io/operaton-contracts/
+Project-URL: Documentation, https://datakurre.github.io/operaton-contracts/
+Project-URL: Repository, https://github.com/datakurre/operaton-contracts
+Project-URL: Issues, https://github.com/datakurre/operaton-contracts/issues
+Project-URL: Changelog, https://github.com/datakurre/operaton-contracts/blob/main/CHANGELOG.md
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: bpmn,camunda,element-templates,operaton,purjo,robotframework
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Pydantic :: 2
+Classifier: Framework :: Robot Framework
+Classifier: Framework :: Robot Framework :: Library
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: pydantic>=2.7
+Provides-Extra: robot
+Requires-Dist: robotframework>=7.3; extra == 'robot'
+Provides-Extra: templates
+Requires-Dist: jsonschema>=4; extra == 'templates'
+Description-Content-Type: text/markdown
+
+# operaton-contracts
+
+Pydantic task contracts for Robot Framework packages served as
+[Operaton](https://operaton.org/) (Camunda 7) external tasks, for example by
+[purjo](https://github.com/datakurre/purjo).
+
+Documentation: <https://datakurre.github.io/operaton-contracts/>
+
+One model per external task topic is the source of truth for what the task
+accepts and returns:
+
+- **At runtime** each Robot task validates and normalizes its process
+  variables with `Validate Task Input`.
+- **At build time** `operaton-contracts generate` renders one bpmn.io element
+  template per topic from the same models, and `operaton-contracts check`
+  verifies that the templates, `[tool.purjo.topics]`, and the Robot suites
+  agree.
+
+```console
+uv add operaton-contracts                   # runtime: pydantic + robotframework
+uv add --group dev "operaton-contracts[templates]"   # adds jsonschema for validate
+```
+
+## Contracts
+
+```python
+# OperatonTasks.py
+from datetime import date
+from typing import Any, Literal
+
+from pydantic import Field
+from OperatonContracts import TaskContract, template_hints
+
+
+class RescindStudyRightsInput(TaskContract):
+    study_right_ids: list[str] = Field(
+        alias="studyRightIds",
+        title="Study right IDs",
+        min_length=1,
+        json_schema_extra=template_hints(value=["${studyRightId}"]),
+    )
+    cancellation_date: date = Field(
+        alias="cancellationDate", title="Cancellation date", strict=False
+    )
+    dry_run: bool = Field(alias="dryRun", title="Dry run", default=False)
+
+
+class RescindStudyRightsOutput(TaskContract):
+    result: dict[str, Any] = Field(alias="result", title="Result variable")
+```
+
+`TaskContract` is strict, forbids extra fields, and strips strings. Every
+field needs an `alias` (the process variable name) and a `title` (the
+template label). Use `Literal[...]` for choices; `Enum`, `Optional`, and nested
+models are not supported in template inputs. `template_hints(value=...,
+type=...)` sets template-only defaults and property types.
+
+## Robot tasks
+
+```robotframework
+*** Settings ***
+Library     OperatonContracts    OperatonTasks
+
+*** Variables ***
+${BPMN:TASK}    local
+@{studyRightIds}    @{EMPTY}
+${cancellationDate}    ${EMPTY}
+${dryRun}    ${False}
+
+*** Tasks ***
+Rescind Study Rights
+    ${input}=    Validate Task Input    RescindStudyRightsInput
+    Log    ${input}[studyRightIds]
+    VAR    ${result}=    ${{{}}}    scope=${BPMN:TASK}
+```
+
+`Validate Task Input` reads `${alias}` for every field, validates, and returns
+the values JSON-compatible (dates as `YYYY-MM-DD`), keyed by alias. Declare
+typed suite defaults (`${False}`, `${0}`, `@{EMPTY}`): strict contracts reject
+the string `"0"` or `"false"`. The library imports the contracts module from
+`sys.path`, falling back to the running suite's directory.
+
+## Element templates
+
+```toml
+# pyproject.toml of the robot package
+[tool.operaton-contracts]
+specs = "scripts.element_templates:TEMPLATES"   # module:attribute
+icon = "scripts/logo.svg"                       # optional SVG icon
+reserved-topics = ["legacy.topic"]              # optional
+# schema-url = "…"                              # optional; pinned default
+```
+
+```python
+# scripts/element_templates.py
+from OperatonContracts.templates import TaskTemplate, TemplateGroup
+from OperatonTasks import RescindStudyRightsInput, RescindStudyRightsOutput
+
+TEMPLATES = (
+    TaskTemplate(
+        topic="study_rights.rescind",
+        template_id="org.example.study-rights-rescind",
+        name="Rescind Study Rights",
+        description="Rescind active study rights.",
+        filename="study-rights-rescind.json",
+        inputs=RescindStudyRightsInput,
+        outputs=RescindStudyRightsOutput,
+        groups=(TemplateGroup("main", "Rescission"),),
+        input_group="main",
+        output_group="main",
+    ),
+)
+```
+
+```console
+operaton-contracts generate   # write .operaton/element-templates/*.json
+operaton-contracts check      # offline: drift and package consistency
+operaton-contracts validate   # against the pinned upstream schema (network)
+```
+
+`check` fails when committed templates differ from the generated ones, when
+specs and `[tool.purjo.topics]` differ, when a topic is reserved or lacks
+`process-variables = false`, or when the suite defining a topic's task lacks a
+typed default for an input, the `Validate Task Input` call, or a
+`VAR … scope=${BPMN:TASK}` for an output. Names are matched the way Robot
+matches them, suites are collected recursively (skipping hidden directories,
+`tests/`, `lib/`, `examples/`, and `test_*.robot`), and a task name defined in
+more than one suite is an error.
+
+## Development
+
+```console
+uv run --group dev --group docs make test check docs   # with uv
+devenv shell -- make test check docs                   # or with devenv
+make build
+```
+
+`make docs-serve` previews the documentation site, which is published to
+GitHub Pages from `main` by `.github/workflows/docs.yml`.
+
+## License
+
+Apache License 2.0; see [LICENSE](LICENSE).
+
+Releases are published to PyPI by `.github/workflows/release.yml` with
+trusted publishing when a `v*` tag matching the project version is pushed.

operaton_contracts-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+OperatonContracts/__init__.py,sha256=2QDHQcgLds4cpD8zs6DtWDSWzbhv5uCw8ZGSBpmURxk,2091
+OperatonContracts/__main__.py,sha256=bB5XAld6e58Eup_58nRxD31pUXbJNqIMSbdxgyJXkyU,65
+OperatonContracts/checks.py,sha256=uSNkvMHepfaH8Vts0uEMVvdMJwxoFnV9ZN7sTPJvqBg,2772
+OperatonContracts/cli.py,sha256=c9dcJQcKPLtgYWcQ1ysEEOnqRXCAOowKs7jv-TPtRy8,4251
+OperatonContracts/contracts.py,sha256=b9Sw0ZTya9kR1F24q42arxAj8OU6ZdanDly-EUw9XJI,3769
+OperatonContracts/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+OperatonContracts/robotframework.py,sha256=9EvLmmljpTN7pCB1Bkfxc7_g6K_sZ4UbjcpsKD2Ou3Q,8372
+OperatonContracts/templates.py,sha256=UAeyNA-x5mlfHU8X4IqfpSB1tYIceKz9-S5j2dV6uGA,9934
+operaton_contracts-0.1.0.dist-info/METADATA,sha256=PYqBWjCvWU1npzPwea0_77i78jW6f1dcEEiXi91V51E,6466
+operaton_contracts-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+operaton_contracts-0.1.0.dist-info/entry_points.txt,sha256=cE_CUoKPQVwUjVO35fdt-Ra8qoiDQEh1kvHCsWGF-d8,66
+operaton_contracts-0.1.0.dist-info/licenses/LICENSE,sha256=DVQuDIgE45qn836wDaWnYhSdxoLXgpRRKH4RuTjpRZQ,10174
+operaton_contracts-0.1.0.dist-info/RECORD,,

operaton_contracts-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

operaton_contracts-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+operaton-contracts = OperatonContracts.cli:main

operaton_contracts-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,177 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS