levain-cli 0.1.0__py3-none-any.whl

levain_recipe/integrations_check.py

@@ -0,0 +1,218 @@
+"""Validate ``@mcp_servers`` names resolve to mapped tools.
+
+Run after the profile + graph stages produce the annotation
+list.  For each node's ``@mcp_servers`` declaration, every name
+must resolve to either:
+
+- A platform-provided MCP server (today: ``knead-review``), or
+- A customer-attached integration mapped to the target agent —
+  surfaced via ``LEVAIN_TARGET_INTEGRATIONS_B64`` and decoded by
+  :mod:`levain_sdk.integrations`.  Only MCP-callable kinds
+  count (see ``_MCP_CALLABLE_KINDS``).
+
+The check is **deterministic over its inputs**: it consumes the
+annotation list (from the spec source) and the target-integration
+list (from an explicit parameter or the env var).  When neither
+the parameter nor the env var supplies any context, the check is
+skipped — a clean checkout / manual CLI invocation has no source
+of truth to validate against, and rejecting valid recipes for
+lack of context would be worse than letting runtime resolution
+catch the error.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+from .models import NodeAnnotation, ValidationError
+
+# Structural stand-in for ``levain_sdk.integrations.TargetIntegration``
+# (a TypedDict, so ``.get()`` is all we need). Typed locally to keep
+# the agent runtime out of this package's dependencies.
+TargetIntegration = Mapping[str, Any]
+
+# Platform-provided MCP servers, mirroring
+# ``levain_sdk.mcp_registry._PLATFORM_SERVERS``. Vendored for the
+# same reason as ``known_recipes.CALLABLE_RECIPES``: this package
+# validates recipes without installing the runtime. Includes the
+# platform-agent-only servers (``levain-build``, ``levain-issues``),
+# which the runtime registers by side-effect import — so the live
+# set differs by process, and this copy is the union. A drift test
+# in Levain's CI keeps the two equal; a stale copy only affects
+# local lint, since the platform re-validates every push.
+PLATFORM_MCP_SERVERS = frozenset(
+    {
+        "google_ads",
+        "knead-review",
+        "levain-agents",
+        "levain-app-data",
+        "levain-artifacts",
+        "levain-build",
+        "levain-image",
+        "levain-issues",
+        "levain-memory",
+        "levain-progress",
+        "levain-sessions",
+        "levain-wiki",
+        "meta_ads",
+        "shopify",
+        "slack",
+        "stripe",
+    }
+)
+
+
+def platform_server_names() -> set[str]:
+    """Names an ``@mcp_servers`` entry can bind to platform-side."""
+    return set(PLATFORM_MCP_SERVERS)
+
+
+def _load_env_targets() -> list[TargetIntegration]:
+    """Attached integrations from the sandbox env, when available.
+
+    Only resolvable inside a sandbox, where the runtime is installed
+    and the harness has injected the env var. Everywhere else this
+    is empty and the caller skips the check.
+    """
+    try:
+        from levain_sdk.integrations import load_target
+    except ImportError:
+        return []
+    return list(load_target())
+
+
+# Integration kinds the runtime resolver can wire as @mcp_servers:
+# OAuth-protected remote MCP servers, and GitHub App integrations
+# (resolved to the SDK's bundled GitHub tools server).  Mirror of
+# the dispatch in ``levain_sdk.mcp_registry.resolve_mcp_servers``.
+_MCP_CALLABLE_KINDS = frozenset({"mcp_url", "github_app"})
+
+
+def check_mcp_names(
+    annotations: list[NodeAnnotation],
+    *,
+    attached_mcp_names: list[str] | None = None,
+) -> list[ValidationError]:
+    """Return one ``ValidationError`` per unresolved ``@mcp_servers`` name.
+
+    ``attached_mcp_names``:
+        - ``None`` (default): read the target list from the env
+          var.  When the env is unset / empty, the check is
+          skipped (allowing platform names) so a clean-checkout
+          run on a recipe declaring ``["knead-review"]`` still
+          passes.
+        - explicit list (incl. ``[]``): enforce against the given
+          list union with platform server names.  Pass ``[]`` to enforce
+          "platform-only" behaviour in tests.
+    """
+    targets: list[TargetIntegration]
+    if attached_mcp_names is None:
+        targets = _load_env_targets()
+        if not targets:
+            # No source of truth; skip the check rather than
+            # rejecting recipes that legitimately reference tools
+            # we just can't see from here.
+            return []
+        explicit_names: list[str] = []
+    else:
+        targets = []
+        explicit_names = list(attached_mcp_names)
+
+    platform = platform_server_names()
+
+    errors: list[ValidationError] = []
+    for ann in annotations:
+        servers = ann.args.get("mcp_servers")
+        if not isinstance(servers, list):
+            continue
+        for s in servers:
+            if not isinstance(s, str):
+                continue
+            if _resolves(s, platform, targets, explicit_names):
+                continue
+            errors.append(
+                ValidationError(
+                    stage="mcp_servers",
+                    message=_unresolved_message(
+                        s, platform, targets, explicit_names
+                    ),
+                )
+            )
+    return errors
+
+
+def unresolved_mcp_names(
+    names: list[str],
+    *,
+    attached_mcp_names: list[str],
+) -> list[str]:
+    """Subset of ``names`` that resolve to nothing.
+
+    The per-name resolution primitive behind :func:`check_mcp_names`,
+    exposed for callers that carry their own integration context (the
+    API's graph annotation) — sharing ``_resolves`` keeps every
+    consumer on one definition of "this name binds at run time".
+    """
+    platform = platform_server_names()
+    explicit = list(attached_mcp_names)
+    return [n for n in names if not _resolves(n, platform, [], explicit)]
+
+
+def _resolves(
+    name: str,
+    platform: set[str],
+    targets: list[TargetIntegration],
+    explicit_names: list[str],
+) -> bool:
+    """Mirror the runtime resolver's matching rules."""
+    needle = name.strip().casefold()
+    if any(p.casefold() == needle for p in platform):
+        return True
+    if any(
+        _matches(name, t)
+        for t in targets
+        if t.get("kind") in _MCP_CALLABLE_KINDS
+    ):
+        return True
+    return any(e.strip().casefold() == needle for e in explicit_names)
+
+
+def _matches(name: str, target: TargetIntegration) -> bool:
+    """Mirror of ``platform_sdk.integrations.matches``.
+
+    Duplicated (not imported) because ``platform_sdk`` isn't a
+    dependency of the open ``levain-cli`` package — see
+    ``known_recipes.CALLABLE_RECIPES`` for the same pattern.
+    """
+    if not name:
+        return False
+    needle = name.strip().casefold()
+    display = target.get("display_name", "").strip().casefold()
+    if display and display == needle:
+        return True
+    provider = target.get("provider", "").strip().casefold()
+    return bool(provider and provider == needle)
+
+
+def _unresolved_message(
+    name: str,
+    platform: set[str],
+    targets: list[TargetIntegration],
+    explicit_names: list[str],
+) -> str:
+    """Build a helpful error listing what *is* available."""
+    available_target_names = [
+        t["display_name"]
+        for t in targets
+        if t.get("display_name") and t.get("kind") in _MCP_CALLABLE_KINDS
+    ]
+    available = sorted({*platform, *available_target_names, *explicit_names})
+    if available:
+        listing = ", ".join(available)
+    else:
+        listing = "(none)"
+    return (
+        f"@mcp_servers name {name!r} does not resolve to a "
+        f"mapped integration. Available: {listing}."
+    )

levain_recipe/known_recipes.py

@@ -0,0 +1,21 @@
+"""Recipes a ``call_agent`` node may target.
+
+Mirrors the platform's trusted-recipe set
+(``platform_sdk.recipe.names.RECIPE_NAMES``); a drift-guard test
+in Levain's CI keeps the two equal.  The server re-validates
+every push with its own copy, so a stale local set only affects
+local lint output.
+"""
+
+CALLABLE_RECIPES = frozenset(
+    {
+        "build",
+        "commit",
+        "crawler",
+        "issue_maintainer",
+        "observer",
+        "plan",
+        "review",
+        "wiki_maintainer",
+    }
+)

levain_recipe/mcp.py

@@ -0,0 +1,85 @@
+"""Stdio MCP server exposing the recipe toolchain.
+
+For MCP clients that cannot run shell commands (e.g. Claude
+Desktop): the tools mirror the CLI commands and operate on the
+local filesystem.  Requires the ``[mcp]`` extra.
+"""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+from fastmcp import FastMCP
+
+from ._format import format_errors, format_success
+from ._java import ensure_jar
+from .codegen import generate_state_module
+from .validate import validate, validate_fast, validate_package
+
+server = FastMCP("levain-recipe")
+
+_NO_JAVA_NOTE = (
+    "Note: Java not found — stages 4-5 (TLC model checking) "
+    "skipped; they still run server-side on push.\n\n"
+)
+
+
+@server.tool()
+def validate_recipe(path: str) -> str:
+    """Validate a PlusCal recipe spec (graph.tla) file."""
+    file = Path(path)
+    if not file.is_file():
+        return f"Error: file not found: {path}"
+    source = file.read_text(encoding="utf-8")
+
+    note = ""
+    if shutil.which("java"):
+        ensure_jar()
+        result = validate(source)
+    else:
+        note = _NO_JAVA_NOTE
+        result = validate_fast(source)
+
+    if isinstance(result, list):
+        return note + format_errors(result)
+    return note + format_success(result)
+
+
+@server.tool()
+def validate_recipe_package(recipe_dir: str) -> str:
+    """Validate a full recipe package (graph.tla + Python source)."""
+    if not Path(recipe_dir).is_dir():
+        return f"Error: not a directory: {recipe_dir}"
+
+    note = ""
+    if shutil.which("java"):
+        ensure_jar()
+    else:
+        note = _NO_JAVA_NOTE
+    result = validate_package(recipe_dir)
+    if isinstance(result, list):
+        return note + format_errors(result)
+    return note + format_success(result)
+
+
+@server.tool()
+def generate_state(recipe_dir: str) -> str:
+    """Regenerate the recipe's ``_state.py`` GraphState TypedDict."""
+    root = Path(recipe_dir)
+    if not root.is_dir():
+        return f"Error: not a directory: {recipe_dir}"
+
+    if shutil.which("java"):
+        ensure_jar()
+    result = validate_package(recipe_dir)
+    if isinstance(result, list):
+        return format_errors(result)
+
+    src_dir = root / "src" / result.module_name
+    if not src_dir.is_dir():
+        return f"Error: expected src dir at {src_dir}"
+
+    state_path = src_dir / "_state.py"
+    state_path.write_text(generate_state_module(result), encoding="utf-8")
+    return f"Wrote {state_path}"

levain_recipe/models.py

@@ -0,0 +1,146 @@
+"""Data models for validated PlusCal specs.
+
+Canonical definitions shared by the spec validator, compiler,
+and sandbox modules.  Other modules should import from here
+rather than defining their own copies.
+"""
+
+from dataclasses import dataclass, field
+from typing import Any
+
+# Canonical mapping from spec type names to Python types.
+# The single source of truth consumed by both the compiler
+# (runtime TypedDict) and the codegen (generated ``_state.py``).
+SPEC_TYPES: dict[str, type] = {
+    "bool": bool,
+    "string": str,
+    "int": int,
+    "list": list,
+}
+
+# Built-in node function name for the langgraph interrupt
+# primitive.  Recognised by the validator (terminal label),
+# compiler (graph-native node), and user-input projector
+# (``interrupting`` flag).
+INTERRUPT_BUILTIN = "interrupt"
+
+# Built-in node function name for an agent-to-agent call. Like
+# ``interrupt`` it runs in the langgraph runtime (harness side, not
+# the sandbox) — it needs DB + dispatch access to run another agent.
+# Args: ``agent`` (target slug), ``input`` (B-field → A-state-field
+# mapping), ``output`` (A-state-field → B-output-field mapping).
+CALL_AGENT_BUILTIN = "call_agent"
+
+# Mid-run steering policy for a node, set via the optional
+# ``interruptible`` key on a ``@node`` annotation.  Controls when a
+# user message that arrives while this node is the live node is folded
+# into the graph:
+#   * ``enqueue`` — let the node finish, fold in at the next boundary.
+#   * ``interrupt`` — cut the node mid-flight and re-route now.
+#   * ``none`` — never cut here (atomic/critical section, e.g. a git
+#     commit/push); the steer is deferred until the graph leaves it.
+# The default is deliberately ``enqueue``: never silently un-steerable,
+# never cuts a critical section.
+INTERRUPTIBLE_KEY = "interruptible"
+INTERRUPTIBLE_CLASSES = ("enqueue", "interrupt", "none")
+DEFAULT_INTERRUPTIBLE = "enqueue"
+
+
+@dataclass(frozen=True)
+class StateField:
+    """A variable declared in the PlusCal variables block.
+
+    ``reducer`` names a blessed reducer from
+    :mod:`levain_recipe.reducers`.  List-typed fields
+    must declare one; scalar fields may not.  The default "last
+    write wins" behaviour is rarely correct for a list, so we
+    require an explicit choice.
+    """
+
+    name: str
+    type: str  # key into SPEC_TYPES
+    default: Any = ""
+    reducer: str | None = None
+    # Free-form description collected from non-annotation comment
+    # lines above the variable declaration in graph.tla. Surfaced
+    # in the generated ``_state.py`` (as ``Annotated[T, "..."]``)
+    # and on the API's state-schema endpoint so the FE can render
+    # a per-field helper in the State tab.
+    description: str | None = None
+
+
+@dataclass(frozen=True)
+class NodeAnnotation:
+    """Metadata for a labeled node.
+
+    Every node is a function call.  Built-in functions
+    (``claude_agent``, ``shell``) are provided by the
+    platform; user functions use ``module:function`` syntax
+    and are resolved by the sandbox via importlib.
+
+    The ``@prompt``, ``@allowed_tools``, and
+    ``@permission_mode`` comment annotations are sugar —
+    the profile checker merges them into ``args``.
+    """
+
+    label: str
+    function: str  # "claude_agent", "shell", "my_mod:score"
+    args: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class Condition:
+    """A single boolean predicate on a state field."""
+
+    field: str
+    op: str  # "eq", "neq", "gt", "gte", "lt", "lte"
+    value: Any  # True, False, 0, "pass", etc.
+
+
+@dataclass(frozen=True)
+class Route:
+    """One arm of a routing decision.
+
+    All conditions are ANDed.  If ``send_field`` is set,
+    the harness fans out: one Send per item in that list
+    field, each dispatched to ``target``.
+    """
+
+    target: str
+    conditions: list[Condition] = field(default_factory=list)
+    send_field: str | None = None
+
+
+@dataclass(frozen=True)
+class RoutingTable:
+    """Ordered routing rules for a single source node.
+
+    Routes are evaluated in order; first match wins.
+    The last route typically has no conditions (default).
+    """
+
+    source: str
+    routes: list[Route]
+
+
+@dataclass(frozen=True)
+class ValidatedSpec:
+    """Result of successful validation."""
+
+    source: str
+    module_name: str
+    variables: list[StateField]
+    nodes: list[NodeAnnotation]
+    routing: list[RoutingTable]
+    invariants: list[str] = field(default_factory=list)
+    constants: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class ValidationError:
+    """A validation failure with context."""
+
+    stage: str  # "parse", "profile", "graph", "translate", "tlc"
+    message: str
+    line: int | None = None
+    counterexample: list[dict[str, Any]] | None = None