levain-cli 0.1.0__tar.gz → 0.1.10__tar.gz

{levain_cli-0.1.0 → levain_cli-0.1.10}/.gitignore

@@ -117,3 +117,17 @@ kubeconfig
 
 # Local TLC toolchain drop-in (CI extracts it from the ghcr carrier)
 tools/tla2tools.jar
+
+# Box-substrate state left over from local backends: state carries secrets.
+infra/stage1-box/*.tfstate*
+infra/stage2-box/*.tfstate*
+# Terraform's crash dump of unwritten state — can contain secrets, never commit
+errored.tfstate
+
+# Saved plans embed resolved variable values, including secrets.
+*.tfplan
+
+# HyperFrames build artifacts — the shipped MP4 and poster live in
+# www/public/videos/; the render and proof frames are reproducible.
+assets/video/*/renders/
+assets/video/*/snapshots/

{levain_cli-0.1.0 → levain_cli-0.1.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: levain-cli
-Version: 0.1.0
+Version: 0.1.10
 Summary: Levain recipe toolchain: PlusCal validator, TLC model checking, and GraphState codegen for agent recipes
 License-Expression: Apache-2.0
 License-File: LICENSE
@@ -9,9 +9,9 @@ Requires-Dist: httpx==0.28.1
 Requires-Dist: pydantic==2.13.4
 Requires-Dist: tree-sitter-tlaplus==1.5.0
 Requires-Dist: tree-sitter==0.26.0
-Requires-Dist: typer==0.26.8
+Requires-Dist: typer==0.27.2
 Provides-Extra: mcp
-Requires-Dist: fastmcp==3.4.7; extra == 'mcp'
+Requires-Dist: fastmcp==4.0.5; extra == 'mcp'
 Description-Content-Type: text/markdown
 
 # levain-cli

{levain_cli-0.1.0 → levain_cli-0.1.10}/levain_recipe/cli.py

@@ -22,7 +22,7 @@ import typer
 from . import LANGUAGE_VERSION
 from ._format import format_errors, format_success
 from ._java import ensure_jar
-from .codegen import generate_state_module
+from .codegen import generate_state_module, state_module_signature
 from .validate import validate, validate_fast, validate_package
 
 app = typer.Typer(
@@ -125,6 +125,29 @@ def validate_package_cmd(
         print(format_errors(result))
         raise typer.Exit(1)
 
+    # ``_state.py`` is generated from the spec; validating a tree
+    # whose copy is stale would bless code the graph no longer
+    # matches. The comparison is structural (field names, types,
+    # reducers) so formatter rewraps and doc metadata don't trip
+    # it. Read-only on purpose — ``generate-state`` writes.
+    state_path = recipe_dir / "src" / result.module_name / "_state.py"
+    if state_path.parent.is_dir():
+        expected = state_module_signature(generate_state_module(result))
+        current = (
+            state_module_signature(state_path.read_text(encoding="utf-8"))
+            if state_path.is_file()
+            else None
+        )
+        if current != expected:
+            what = "missing" if current is None else "stale"
+            print(
+                f"Error: {state_path.relative_to(recipe_dir)} is {what} — "
+                f"run `levain generate-state {recipe_dir}` and commit "
+                f"the result.",
+                file=sys.stderr,
+            )
+            raise typer.Exit(1)
+
     print(format_success(result))
 
 
@@ -305,20 +328,21 @@ def git_credential_cmd(
 
     # git gives us the repo it wants, so the credential is scoped to
     # exactly that rather than to the whole workspace.
-    slug = _slug_from_git_path(fields.get("path", ""))
-    if not slug:
+    repo = _repo_from_git_path(fields.get("path", ""))
+    if repo is None:
         print(
             "levain git-credential: not a Levain recipe URL",
             file=sys.stderr,
         )
         raise typer.Exit(1)
+    scope, slug = repo
 
     api = api_base()
     try:
         with _client() as client:
             token = access_token(api, client)
             resp = client.post(
-                f"{api}/api/v1/agents/{slug}/git-credential",
+                f"{api}/api/v1/{scope}/{slug}/git-credential",
                 headers={"Authorization": f"Bearer {token}"},
             )
     except AuthError as exc:
@@ -336,9 +360,21 @@ def git_credential_cmd(
     print(f"password={body['password']}")
 
 
-def _slug_from_git_path(path: str) -> str:
-    """Agent slug from a recipe repo path (``ws-<hex>/<slug>.git``)."""
+def _repo_from_git_path(path: str) -> tuple[str, str] | None:
+    """``(api scope, slug)`` for a recipe repo path, or None.
+
+    Workspace agents live at ``ws-<hex>/<slug>.git`` and mint under
+    ``agents``; org agents at ``org-<hex>/<slug>.git`` under
+    ``org/agents``.
+    """
     parts = path.strip("/").split("/")
-    if len(parts) != 2 or not parts[0].startswith("ws-"):
-        return ""
-    return parts[1].removesuffix(".git")
+    if len(parts) != 2:
+        return None
+    owner, repo = parts
+    if owner.startswith("ws-"):
+        scope = "agents"
+    elif owner.startswith("org-"):
+        scope = "org/agents"
+    else:
+        return None
+    return scope, repo.removesuffix(".git")

{levain_cli-0.1.0 → levain_cli-0.1.10}/levain_recipe/codegen.py

@@ -112,3 +112,54 @@ def _py_type_for(var: StateField) -> str:
     if desc_literal is not None:
         return f"Annotated[{py_type.__name__}, {desc_literal}]"
     return py_type.__name__
+
+
+def state_module_signature(text: str) -> dict[str, str] | None:
+    """Structural signature of a ``_state.py`` module.
+
+    Maps field name -> normalized annotation, where ``Annotated``
+    is reduced to its base type plus any non-string metadata (the
+    reducer callables) — docstring metadata and formatting don't
+    affect the signature.  Lets ``validate-package`` compare an
+    on-disk ``_state.py`` against what codegen would emit without
+    tripping on ``ruff format`` rewraps.  Returns ``None`` when the
+    text isn't parseable or has no ``GraphState`` class.
+    """
+    import ast as _ast
+
+    try:
+        tree = _ast.parse(text)
+    except SyntaxError:
+        return None
+    for node in _ast.iter_child_nodes(tree):
+        if isinstance(node, _ast.ClassDef) and node.name == "GraphState":
+            fields: dict[str, str] = {}
+            for stmt in node.body:
+                if not isinstance(stmt, _ast.AnnAssign) or not isinstance(
+                    stmt.target, _ast.Name
+                ):
+                    continue
+                fields[stmt.target.id] = _normalize_annotation(stmt.annotation)
+            return fields
+    return None
+
+
+def _normalize_annotation(node: object) -> str:
+    """Reduce an annotation AST to base type + non-string metadata."""
+    import ast as _ast
+
+    if (
+        isinstance(node, _ast.Subscript)
+        and isinstance(node.value, _ast.Name)
+        and node.value.id == "Annotated"
+        and isinstance(node.slice, _ast.Tuple)
+        and node.slice.elts
+    ):
+        base = _ast.dump(node.slice.elts[0])
+        reducers = [
+            _ast.dump(e)
+            for e in node.slice.elts[1:]
+            if not (isinstance(e, _ast.Constant) and isinstance(e.value, str))
+        ]
+        return " | ".join([base, *reducers])
+    return _ast.dump(node) if isinstance(node, _ast.AST) else repr(node)

{levain_cli-0.1.0 → levain_cli-0.1.10}/levain_recipe/integrations_check.py

@@ -68,6 +68,20 @@ def platform_server_names() -> set[str]:
     return set(PLATFORM_MCP_SERVERS)
 
 
+# Platform servers named after an integration provider, mirroring
+# ``levain_sdk.mcp_registry._PROVIDER_NAMED_SERVERS``. Vendored for the
+# same reason as ``PLATFORM_MCP_SERVERS`` above; kept equal by the same
+# drift test in ``tests/spec/test_known_recipes.py``.
+PROVIDER_MCP_SERVERS = frozenset(
+    {"google_ads", "meta_ads", "shopify", "slack", "stripe"}
+)
+
+
+def provider_server_names() -> set[str]:
+    """Platform server names that double as an integration provider."""
+    return set(PROVIDER_MCP_SERVERS)
+
+
 def _load_env_targets() -> list[TargetIntegration]:
     """Attached integrations from the sandbox env, when available.
 

{levain_cli-0.1.0 → levain_cli-0.1.10}/levain_recipe/source_check.py

@@ -36,6 +36,14 @@ def check_python_sources(
        ``@node``, or be marked private with a leading underscore.
        Catches recipes that add Python functions for new behaviour
        but forget to wire them into ``graph.tla``.
+    6. ``load_prompt`` calls agree with their templates — every
+       kwarg is referenced as ``$var``/``${var}`` in the prompt
+       file (``{var}`` is str.format syntax and would raise at
+       run time), and the prompt file exists.
+    7. ``levain_sdk.claude`` calls that mean "no tools" say
+       ``tools=[]`` — an empty ``allowed_tools`` is only a
+       permission allowlist and does not withhold the built-in
+       toolset.
     """
     errors: list[ValidationError] = []
     src_dir = os.path.join(recipe_dir, "src")
@@ -43,6 +51,8 @@ def check_python_sources(
     errors.extend(_check_pyproject(recipe_dir))
     errors.extend(_check_function_refs(spec.nodes, src_dir))
     errors.extend(_check_orphan_node_functions(spec.nodes, src_dir))
+    errors.extend(_check_prompt_templates(src_dir))
+    errors.extend(_check_claude_tool_guards(src_dir))
 
     return errors
 
@@ -277,3 +287,158 @@ def _check_orphan_node_functions(
             )
 
     return errors
+
+
+def _iter_source_files(src_dir: str) -> list[Path]:
+    """Every ``.py`` file under ``src/`` except generated ``_state.py``."""
+    root = Path(src_dir)
+    if not root.is_dir():
+        return []
+    return [p for p in sorted(root.rglob("*.py")) if p.name != "_state.py"]
+
+
+def _parse_or_none(py_file: Path) -> ast.Module | None:
+    """Parse a file; syntax errors are reported elsewhere."""
+    try:
+        return ast.parse(py_file.read_text(encoding="utf-8"))
+    except (SyntaxError, OSError):
+        return None
+
+
+def _imported_names(
+    tree: ast.Module, module: str, names: set[str]
+) -> set[str]:
+    """Local aliases bound to ``names`` imported from ``module``."""
+    found: set[str] = set()
+    for node in ast.walk(tree):
+        if isinstance(node, ast.ImportFrom) and node.module == module:
+            for alias in node.names:
+                if alias.name in names:
+                    found.add(alias.asname or alias.name)
+    return found
+
+
+def _check_prompt_templates(src_dir: str) -> list[ValidationError]:
+    """Statically mirror ``load_prompt``'s template guard.
+
+    For every ``load_prompt(__package__, "name", var=...)`` call,
+    the prompt file must exist next to the module
+    (``prompts/name.md``) and reference each kwarg as ``$var`` or
+    ``${var}``.  A ``{var}`` placeholder is str.format syntax —
+    ``string.Template`` ignores it and the SDK raises at run time;
+    this surfaces the same failure at validate time.
+
+    Only calls whose first argument is the ``__package__`` name are
+    checked — that is the SDK's documented calling convention, and
+    a dynamic package expression can't be resolved statically.
+    """
+    from string import Template
+
+    errors: list[ValidationError] = []
+    for py_file in _iter_source_files(src_dir):
+        tree = _parse_or_none(py_file)
+        if tree is None:
+            continue
+        aliases = _imported_names(tree, "levain_sdk.prompts", {"load_prompt"})
+        if not aliases:
+            continue
+        for call in ast.walk(tree):
+            if not isinstance(call, ast.Call):
+                continue
+            if not (
+                isinstance(call.func, ast.Name) and call.func.id in aliases
+            ):
+                continue
+            if len(call.args) < 2 or not (
+                isinstance(call.args[1], ast.Constant)
+                and isinstance(call.args[1].value, str)
+            ):
+                continue
+            first = call.args[0]
+            if not (isinstance(first, ast.Name) and first.id == "__package__"):
+                continue
+            name = call.args[1].value
+            kwargs = sorted(
+                kw.arg for kw in call.keywords if kw.arg is not None
+            )
+            prompt_file = py_file.parent / "prompts" / f"{name}.md"
+            if not prompt_file.is_file():
+                errors.append(
+                    ValidationError(
+                        stage="source",
+                        message=(
+                            f"{py_file.name} loads prompt '{name}' but "
+                            f"prompts/{name}.md does not exist next to it."
+                        ),
+                    )
+                )
+                continue
+            if not kwargs:
+                continue
+            referenced = set(
+                Template(
+                    prompt_file.read_text(encoding="utf-8")
+                ).get_identifiers()
+            )
+            missing = [k for k in kwargs if k not in referenced]
+            if missing:
+                errors.append(
+                    ValidationError(
+                        stage="source",
+                        message=(
+                            f"{py_file.name} passes {missing} to prompt "
+                            f"'{name}' but prompts/{name}.md never "
+                            f"references them — use $var or ${{var}} "
+                            f"(templates are string.Template, not "
+                            f"str.format, so {{var}} is inert)."
+                        ),
+                    )
+                )
+    return errors
+
+
+def _check_claude_tool_guards(src_dir: str) -> list[ValidationError]:
+    """Flag ``allowed_tools=[]`` used as a no-tools switch.
+
+    ``levain_sdk.claude.run``/``run_stateless`` offer the built-in
+    toolset unless ``tools=[]`` is passed; ``allowed_tools`` is a
+    permission allowlist, and an empty one is silently ignored.
+    A call that passes an empty ``allowed_tools`` without any
+    ``tools`` kwarg almost certainly meant to withhold the tools.
+    """
+    errors: list[ValidationError] = []
+    for py_file in _iter_source_files(src_dir):
+        tree = _parse_or_none(py_file)
+        if tree is None:
+            continue
+        aliases = _imported_names(
+            tree, "levain_sdk.claude", {"run", "run_stateless"}
+        )
+        if not aliases:
+            continue
+        for call in ast.walk(tree):
+            if not isinstance(call, ast.Call):
+                continue
+            if not (
+                isinstance(call.func, ast.Name) and call.func.id in aliases
+            ):
+                continue
+            kwargs = {kw.arg: kw.value for kw in call.keywords if kw.arg}
+            allowed = kwargs.get("allowed_tools")
+            if (
+                isinstance(allowed, ast.List)
+                and not allowed.elts
+                and "tools" not in kwargs
+            ):
+                errors.append(
+                    ValidationError(
+                        stage="source",
+                        message=(
+                            f"{py_file.name} passes allowed_tools=[] "
+                            f"without tools=[] — an empty allowlist "
+                            f"does not withhold the built-in toolset; "
+                            f"pass tools=[] to run with no tools."
+                        ),
+                    )
+                )
+    return errors

{levain_cli-0.1.0 → levain_cli-0.1.10}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "levain-cli"
-version = "0.1.0"
+version = "0.1.10"
 description = "Levain recipe toolchain: PlusCal validator, TLC model checking, and GraphState codegen for agent recipes"
 readme = "README.md"
 license = "Apache-2.0"
@@ -27,14 +27,14 @@ dependencies = [
     "tree-sitter==0.26.0",
     "tree-sitter-tlaplus==1.5.0",
     "pydantic==2.13.4",
-    "typer==0.26.8",
+    "typer==0.27.2",
     # Sign-in and credential minting. Imported lazily so validation
     # never pays for it.
     "httpx==0.28.1",
 ]
 
 [project.optional-dependencies]
-mcp = ["fastmcp==3.4.7"]
+mcp = ["fastmcp==4.0.5"]
 
 [project.scripts]
 levain = "levain_recipe.cli:app"