strands-zero 0.1.0__tar.gz

strands_zero-0.1.0/.gitignore

@@ -0,0 +1,21 @@
+# Cloned upstream — not part of this package
+zero/
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.eggs/
+.pytest_cache/
+.venv/
+venv/
+.coverage
+
+# Zero artifacts
+.zero/
+
+# Runtime event dirs (not source)
+telegram_events/
+whatsapp_events/

strands_zero-0.1.0/LICENSE

@@ -0,0 +1,15 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

strands_zero-0.1.0/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: strands-zero
+Version: 0.1.0
+Summary: Strands Agents tools for the Zero programming language - write, check, build, run Zero code from Python agents
+Project-URL: Homepage, https://github.com/cagataycali/strands-zero
+Project-URL: Repository, https://github.com/cagataycali/strands-zero
+Project-URL: Zero Language, https://zerolang.ai
+Author-email: Cagatay Cali <cagataycali@icloud.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: agents,ai,compiler,llm,strands,tools,zero,zero-lang
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: Software Development :: Compilers
+Requires-Python: >=3.10
+Requires-Dist: strands-agents>=0.1.0
+Provides-Extra: dev
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# strands-zero
+
+[![PyPI](https://img.shields.io/pypi/v/strands-zero.svg)](https://pypi.org/project/strands-zero/)
+
+**Strands Agents tools for the [Zero programming language](https://zerolang.ai).**
+
+Wraps the official `zero` CLI as a set of `@tool`-decorated Python functions
+so AI agents (Claude, Strands, anything compatible) can write, type-check,
+compile, run, ship, and inspect Zero programs with structured JSON feedback.
+
+> Zero is the programming language for agents — small native tools, explicit
+> effects, predictable memory, and machine-readable compiler output.
+
+---
+
+## Install
+
+```bash
+pip install strands-zero
+```
+
+This installs the Python wrappers. You also need the Zero compiler binary:
+
+```bash
+# one-shot from the package
+strands-zero-install
+
+# or manually
+curl -fsSL https://zerolang.ai/install.sh | bash
+export PATH="$HOME/.zero/bin:$PATH"
+```
+
+`strands-zero` finds the binary in this order:
+1. `$ZERO_BIN` env var
+2. `zero` on `$PATH`
+3. `~/.zero/bin/zero`
+
+---
+
+## Quick start
+
+```python
+from strands import Agent
+from strands_zero import (
+    zero_write, zero_check, zero_run, zero_build,
+    zero_explain, zero_fix, zero_doctor, zero_skills,
+    zero_graph, zero_size, zero_test, zero_version,
+)
+
+agent = Agent(
+    tools=[
+        zero_write, zero_check, zero_run, zero_build,
+        zero_explain, zero_fix, zero_doctor, zero_skills,
+    ],
+    system_prompt="You are a Zero language expert. Use zero_skills('get','zero-language',full=True) when unsure of syntax.",
+)
+
+agent("Write a Zero program that prints the first 10 fibonacci numbers, type-check it, then run it.")
+```
+
+---
+
+## Tools
+
+| Tool                | Purpose                                                             |
+| ------------------- | ------------------------------------------------------------------- |
+| `zero_version`      | Compiler version + host info                                        |
+| `zero_install`      | Install/upgrade the Zero compiler                                   |
+| `zero_doctor`       | Diagnose the toolchain                                              |
+| `zero_skills`       | Access built-in language/diagnostics/builds/agent skill docs        |
+| `zero_targets`      | List supported compilation targets                                  |
+| `zero_write`        | Write `.0` source to disk (or temp file)                            |
+| `zero_new`          | Scaffold a new `cli` / `lib` / `package`                            |
+| `zero_check`        | Type-check; returns structured diagnostics JSON                     |
+| `zero_explain`      | Explain a diagnostic code                                           |
+| `zero_fix`          | Get a structured fix plan                                           |
+| `zero_run`          | Compile and run a program (with stdin/args)                         |
+| `zero_build`        | Build to `exe` / `obj` / `wasm`                                     |
+| `zero_ship`         | Release-grade build (`release-small` / `tiny` / `audit`)            |
+| `zero_test`         | Run `test` blocks                                                   |
+| `zero_fmt`          | Format source                                                       |
+| `zero_graph`        | Module / dep graph                                                  |
+| `zero_size`         | Binary size breakdown                                               |
+| `zero_mem`          | Static memory layout                                                |
+| `zero_routes`       | List declared web routes                                            |
+| `zero_clean`        | Clean `.zero/` cache                                                |
+
+All tools accept a `cwd` arg; build/run tools accept `timeout`.
+JSON-capable tools default to `json_output=True` and parse stdout into
+`result["json"]`.
+
+---
+
+## Manual usage (no agent)
+
+```python
+from strands_zero import zero_write, zero_run
+
+write = zero_write('''
+pub fun main(world: World) -> Void raises {
+    check world.out.write("hello\\n")
+}
+''')
+
+run = zero_run(write["path"])
+print(run["stdout"])  # hello
+```
+
+---
+
+## Why?
+
+Zero exposes everything an agent needs through `--json` flags
+(`check --json`, `fix --plan --json`, `graph --json`, `size --json`, `doctor --json`, ...).
+This package gives that surface area to a Strands agent verbatim, so an agent
+can iterate on Zero code with the same explicit, machine-readable feedback the
+language is designed for.
+
+---
+
+## License
+
+Apache-2.0

strands_zero-0.1.0/README.md

@@ -0,0 +1,123 @@
+# strands-zero
+
+[![PyPI](https://img.shields.io/pypi/v/strands-zero.svg)](https://pypi.org/project/strands-zero/)
+
+**Strands Agents tools for the [Zero programming language](https://zerolang.ai).**
+
+Wraps the official `zero` CLI as a set of `@tool`-decorated Python functions
+so AI agents (Claude, Strands, anything compatible) can write, type-check,
+compile, run, ship, and inspect Zero programs with structured JSON feedback.
+
+> Zero is the programming language for agents — small native tools, explicit
+> effects, predictable memory, and machine-readable compiler output.
+
+---
+
+## Install
+
+```bash
+pip install strands-zero
+```
+
+This installs the Python wrappers. You also need the Zero compiler binary:
+
+```bash
+# one-shot from the package
+strands-zero-install
+
+# or manually
+curl -fsSL https://zerolang.ai/install.sh | bash
+export PATH="$HOME/.zero/bin:$PATH"
+```
+
+`strands-zero` finds the binary in this order:
+1. `$ZERO_BIN` env var
+2. `zero` on `$PATH`
+3. `~/.zero/bin/zero`
+
+---
+
+## Quick start
+
+```python
+from strands import Agent
+from strands_zero import (
+    zero_write, zero_check, zero_run, zero_build,
+    zero_explain, zero_fix, zero_doctor, zero_skills,
+    zero_graph, zero_size, zero_test, zero_version,
+)
+
+agent = Agent(
+    tools=[
+        zero_write, zero_check, zero_run, zero_build,
+        zero_explain, zero_fix, zero_doctor, zero_skills,
+    ],
+    system_prompt="You are a Zero language expert. Use zero_skills('get','zero-language',full=True) when unsure of syntax.",
+)
+
+agent("Write a Zero program that prints the first 10 fibonacci numbers, type-check it, then run it.")
+```
+
+---
+
+## Tools
+
+| Tool                | Purpose                                                             |
+| ------------------- | ------------------------------------------------------------------- |
+| `zero_version`      | Compiler version + host info                                        |
+| `zero_install`      | Install/upgrade the Zero compiler                                   |
+| `zero_doctor`       | Diagnose the toolchain                                              |
+| `zero_skills`       | Access built-in language/diagnostics/builds/agent skill docs        |
+| `zero_targets`      | List supported compilation targets                                  |
+| `zero_write`        | Write `.0` source to disk (or temp file)                            |
+| `zero_new`          | Scaffold a new `cli` / `lib` / `package`                            |
+| `zero_check`        | Type-check; returns structured diagnostics JSON                     |
+| `zero_explain`      | Explain a diagnostic code                                           |
+| `zero_fix`          | Get a structured fix plan                                           |
+| `zero_run`          | Compile and run a program (with stdin/args)                         |
+| `zero_build`        | Build to `exe` / `obj` / `wasm`                                     |
+| `zero_ship`         | Release-grade build (`release-small` / `tiny` / `audit`)            |
+| `zero_test`         | Run `test` blocks                                                   |
+| `zero_fmt`          | Format source                                                       |
+| `zero_graph`        | Module / dep graph                                                  |
+| `zero_size`         | Binary size breakdown                                               |
+| `zero_mem`          | Static memory layout                                                |
+| `zero_routes`       | List declared web routes                                            |
+| `zero_clean`        | Clean `.zero/` cache                                                |
+
+All tools accept a `cwd` arg; build/run tools accept `timeout`.
+JSON-capable tools default to `json_output=True` and parse stdout into
+`result["json"]`.
+
+---
+
+## Manual usage (no agent)
+
+```python
+from strands_zero import zero_write, zero_run
+
+write = zero_write('''
+pub fun main(world: World) -> Void raises {
+    check world.out.write("hello\\n")
+}
+''')
+
+run = zero_run(write["path"])
+print(run["stdout"])  # hello
+```
+
+---
+
+## Why?
+
+Zero exposes everything an agent needs through `--json` flags
+(`check --json`, `fix --plan --json`, `graph --json`, `size --json`, `doctor --json`, ...).
+This package gives that surface area to a Strands agent verbatim, so an agent
+can iterate on Zero code with the same explicit, machine-readable feedback the
+language is designed for.
+
+---
+
+## License
+
+Apache-2.0

strands_zero-0.1.0/examples/agent_demo.py

@@ -0,0 +1,22 @@
+"""Minimal end-to-end demo: agent writes, checks, and runs Zero code."""
+from strands import Agent
+from strands_zero import (
+    zero_write, zero_check, zero_run, zero_explain,
+    zero_fix, zero_skills, zero_doctor, zero_version,
+)
+
+agent = Agent(
+    tools=[
+        zero_write, zero_check, zero_run, zero_explain,
+        zero_fix, zero_skills, zero_doctor, zero_version,
+    ],
+    system_prompt=(
+        "You are a Zero language expert. "
+        "Use zero_skills('get','zero-language',full=True) when unsure of syntax. "
+        "Always zero_check before zero_run. "
+        "On diagnostics: use zero_explain + zero_fix, then retry."
+    ),
+)
+
+if __name__ == "__main__":
+    agent("Write a Zero program that prints the first 5 squares, type-check it, then run it.")

strands_zero-0.1.0/examples/manual_usage.py

@@ -0,0 +1,11 @@
+"""Use the tools directly without an agent."""
+from strands_zero import zero_write, zero_check, zero_run, zero_version
+
+print(zero_version())
+w = zero_write('''
+pub fun main(world: World) -> Void raises {
+    check world.out.write("hello\\n")
+}
+''')
+print(zero_check(w["path"]))
+print(zero_run(w["path"])["stdout"])

strands_zero-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "strands-zero"
+version = "0.1.0"
+description = "Strands Agents tools for the Zero programming language - write, check, build, run Zero code from Python agents"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.10"
+authors = [{ name = "Cagatay Cali", email = "cagataycali@icloud.com" }]
+keywords = ["strands", "agents", "zero", "zero-lang", "compiler", "ai", "llm", "tools"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Compilers",
+    "Topic :: Software Development :: Code Generators",
+]
+dependencies = [
+    "strands-agents>=0.1.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0", "pytest-cov", "ruff"]
+
+[project.urls]
+Homepage = "https://github.com/cagataycali/strands-zero"
+Repository = "https://github.com/cagataycali/strands-zero"
+"Zero Language" = "https://zerolang.ai"
+
+[project.scripts]
+strands-zero-install = "strands_zero.installer:cli"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/strands_zero"]

strands_zero-0.1.0/src/strands_zero/__init__.py

@@ -0,0 +1,71 @@
+"""
+strands-zero: Strands Agents tools for the Zero programming language.
+
+Wraps the `zero` CLI (https://zerolang.ai) so AI agents can write, check,
+compile, and run Zero code with structured JSON feedback.
+
+Usage:
+    from strands import Agent
+    from strands_zero import (
+        zero_check, zero_run, zero_build, zero_doctor,
+        zero_explain, zero_fix, zero_write, zero_skills,
+        zero_graph, zero_size, zero_test, zero_new,
+        zero_version, zero_install,
+    )
+
+    agent = Agent(tools=[zero_check, zero_run, zero_build, zero_explain, zero_write])
+    agent("Write a Zero program that prints 'hello' and run it")
+"""
+
+from strands_zero._runner import find_zero_binary, run_zero
+from strands_zero.tools import (
+    zero_version,
+    zero_check,
+    zero_run,
+    zero_build,
+    zero_ship,
+    zero_test,
+    zero_fmt,
+    zero_doctor,
+    zero_explain,
+    zero_fix,
+    zero_skills,
+    zero_graph,
+    zero_size,
+    zero_mem,
+    zero_routes,
+    zero_targets,
+    zero_clean,
+    zero_new,
+    zero_write,
+    zero_install,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Core helpers
+    "find_zero_binary",
+    "run_zero",
+    # Tool functions
+    "zero_version",
+    "zero_check",
+    "zero_run",
+    "zero_build",
+    "zero_ship",
+    "zero_test",
+    "zero_fmt",
+    "zero_doctor",
+    "zero_explain",
+    "zero_fix",
+    "zero_skills",
+    "zero_graph",
+    "zero_size",
+    "zero_mem",
+    "zero_routes",
+    "zero_targets",
+    "zero_clean",
+    "zero_new",
+    "zero_write",
+    "zero_install",
+]

strands_zero-0.1.0/src/strands_zero/_runner.py

@@ -0,0 +1,130 @@
+"""Internal subprocess runner for the `zero` CLI."""
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+
+def find_zero_binary() -> Optional[str]:
+    """Locate the `zero` binary.
+
+    Search order:
+        1. ZERO_BIN env var (explicit override)
+        2. `zero` on PATH
+        3. ~/.zero/bin/zero (default install dir)
+    """
+    explicit = os.environ.get("ZERO_BIN")
+    if explicit and Path(explicit).exists() and os.access(explicit, os.X_OK):
+        return explicit
+
+    on_path = shutil.which("zero")
+    if on_path:
+        return on_path
+
+    home_bin = Path.home() / ".zero" / "bin" / "zero"
+    if home_bin.exists() and os.access(str(home_bin), os.X_OK):
+        return str(home_bin)
+
+    return None
+
+
+def run_zero(
+    args: List[str],
+    *,
+    cwd: Optional[str] = None,
+    timeout: int = 120,
+    input_text: Optional[str] = None,
+    parse_json: bool = False,
+) -> Dict[str, Any]:
+    """Execute the zero CLI and return a structured result.
+
+    Returns a dict with:
+        ok: bool
+        exit_code: int
+        stdout: str
+        stderr: str
+        command: list[str]
+        json: parsed JSON if parse_json=True and stdout is valid JSON
+        error: error message if zero binary missing or timeout
+    """
+    binary = find_zero_binary()
+    if not binary:
+        return {
+            "ok": False,
+            "exit_code": -1,
+            "stdout": "",
+            "stderr": "",
+            "command": ["zero"] + args,
+            "error": (
+                "zero binary not found. Install with: "
+                "curl -fsSL https://zerolang.ai/install.sh | bash "
+                "(then add ~/.zero/bin to PATH), or call zero_install()."
+            ),
+        }
+
+    cmd = [binary] + args
+    try:
+        proc = subprocess.run(
+            cmd,
+            cwd=cwd,
+            input=input_text,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+        )
+    except subprocess.TimeoutExpired as e:
+        return {
+            "ok": False,
+            "exit_code": -1,
+            "stdout": e.stdout or "",
+            "stderr": e.stderr or "",
+            "command": cmd,
+            "error": f"timeout after {timeout}s",
+        }
+    except Exception as e:
+        return {
+            "ok": False,
+            "exit_code": -1,
+            "stdout": "",
+            "stderr": "",
+            "command": cmd,
+            "error": f"{type(e).__name__}: {e}",
+        }
+
+    result: Dict[str, Any] = {
+        "ok": proc.returncode == 0,
+        "exit_code": proc.returncode,
+        "stdout": proc.stdout,
+        "stderr": proc.stderr,
+        "command": cmd,
+    }
+
+    if parse_json and proc.stdout.strip():
+        try:
+            result["json"] = json.loads(proc.stdout)
+        except json.JSONDecodeError:
+            # Some commands print non-JSON warnings before JSON; try last line.
+            for line in reversed(proc.stdout.splitlines()):
+                line = line.strip()
+                if line.startswith("{") or line.startswith("["):
+                    try:
+                        result["json"] = json.loads(line)
+                        break
+                    except json.JSONDecodeError:
+                        continue
+
+    return result
+
+
+def resolve_target(target: Optional[str]) -> Tuple[str, str]:
+    """Resolve a Zero source target. Returns (target_arg, label)."""
+    if target is None:
+        return ("", "(no target)")
+    p = Path(target).expanduser()
+    if p.exists():
+        return (str(p), str(p))
+    return (target, target)

strands_zero-0.1.0/src/strands_zero/installer.py

@@ -0,0 +1,71 @@
+"""Install/upgrade the Zero compiler binary."""
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+INSTALL_URL = "https://zerolang.ai/install.sh"
+
+
+def install_zero(install_dir: str | None = None) -> dict:
+    """Run the official Zero install script.
+
+    Args:
+        install_dir: Override install dir (defaults to ~/.zero/bin via the script).
+    """
+    env = os.environ.copy()
+    if install_dir:
+        env["ZERO_INSTALL_DIR"] = install_dir
+
+    try:
+        # Pipe curl into sh, but capture both for the agent.
+        curl = subprocess.run(
+            ["curl", "-fsSL", INSTALL_URL],
+            capture_output=True,
+            text=True,
+            timeout=60,
+        )
+        if curl.returncode != 0:
+            return {"ok": False, "error": f"curl failed: {curl.stderr}"}
+
+        sh = subprocess.run(
+            ["sh", "-s"],
+            input=curl.stdout,
+            capture_output=True,
+            text=True,
+            timeout=300,
+            env=env,
+        )
+        return {
+            "ok": sh.returncode == 0,
+            "exit_code": sh.returncode,
+            "stdout": sh.stdout,
+            "stderr": sh.stderr,
+            "install_dir": env.get("ZERO_INSTALL_DIR")
+            or str(Path.home() / ".zero" / "bin"),
+        }
+    except FileNotFoundError as e:
+        return {"ok": False, "error": f"missing required command: {e}"}
+    except subprocess.TimeoutExpired:
+        return {"ok": False, "error": "install timed out"}
+    except Exception as e:
+        return {"ok": False, "error": f"{type(e).__name__}: {e}"}
+
+
+def cli() -> int:
+    """Entry point for `strands-zero-install` script."""
+    install_dir = sys.argv[1] if len(sys.argv) > 1 else None
+    result = install_zero(install_dir)
+    if result["ok"]:
+        print(result.get("stdout", ""))
+        bin_dir = result.get("install_dir", "~/.zero/bin")
+        print(f"\n✓ Zero installed. Add to PATH:\n  export PATH=\"{bin_dir}:$PATH\"")
+        return 0
+    print(f"✗ Install failed: {result.get('error') or result.get('stderr')}", file=sys.stderr)
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(cli())

strands_zero-0.1.0/src/strands_zero/tools.py

@@ -0,0 +1,375 @@
+"""Strands @tool wrappers for the Zero CLI.
+
+Every tool returns a dict with keys: ok, stdout, stderr, exit_code, command,
+and (when --json was used) a parsed `json` field. Tools are deliberately thin
+wrappers — the agent decides what to do with the output.
+"""
+from __future__ import annotations
+
+import os
+import tempfile
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from strands import tool
+
+from strands_zero._runner import run_zero, find_zero_binary
+from strands_zero.installer import install_zero
+
+
+# ---------------------------------------------------------------------------
+# Meta / environment
+# ---------------------------------------------------------------------------
+
+@tool
+def zero_version(json_output: bool = True) -> Dict[str, Any]:
+    """Get the installed Zero compiler version and host info.
+
+    Args:
+        json_output: Return structured JSON (default True).
+    """
+    args = ["--version"] + (["--json"] if json_output else [])
+    return run_zero(args, parse_json=json_output)
+
+
+@tool
+def zero_install(install_dir: Optional[str] = None) -> Dict[str, Any]:
+    """Install (or reinstall) the Zero compiler from zerolang.ai.
+
+    Args:
+        install_dir: Optional install directory (defaults to ~/.zero/bin).
+    """
+    return install_zero(install_dir)
+
+
+@tool
+def zero_doctor(json_output: bool = True) -> Dict[str, Any]:
+    """Run `zero doctor` to check the toolchain and environment health."""
+    args = ["doctor"] + (["--json"] if json_output else [])
+    return run_zero(args, parse_json=json_output)
+
+
+@tool
+def zero_targets() -> Dict[str, Any]:
+    """List available compilation targets."""
+    return run_zero(["targets"])
+
+
+@tool
+def zero_skills(action: str = "list", name: Optional[str] = None,
+                full: bool = False) -> Dict[str, Any]:
+    """Access Zero's built-in skill docs (language, diagnostics, builds, etc).
+
+    Args:
+        action: One of "list", "get", "path".
+        name: Skill name when action="get" or action="path"
+              (e.g. "zero-language", "zero-diagnostics", "zero-agent").
+        full: When True with get, request full skill body.
+    """
+    if action == "list":
+        return run_zero(["skills", "list", "--json"], parse_json=True)
+    if action in ("get", "path"):
+        if not name:
+            return {"ok": False, "error": f"name required for action='{action}'"}
+        args = ["skills", action, name]
+        if action == "get" and full:
+            args.append("--full")
+        return run_zero(args)
+    return {"ok": False, "error": f"unknown action: {action}"}
+
+
+# ---------------------------------------------------------------------------
+# Authoring
+# ---------------------------------------------------------------------------
+
+@tool
+def zero_write(
+    code: str,
+    path: Optional[str] = None,
+    overwrite: bool = True,
+) -> Dict[str, Any]:
+    """Write Zero source code (`.0`) to disk.
+
+    Args:
+        code: The Zero source to write.
+        path: Destination path. If None, writes to a temp `.0` file.
+              If a path without `.0` extension is given, `.0` is appended.
+        overwrite: Overwrite existing file (default True).
+
+    Returns: dict with ok, path, bytes_written.
+    """
+    if path is None:
+        fd, tmp = tempfile.mkstemp(suffix=".0", prefix="zero_")
+        os.close(fd)
+        target = Path(tmp)
+    else:
+        target = Path(path).expanduser()
+        if target.suffix == "":
+            target = target.with_suffix(".0")
+        target.parent.mkdir(parents=True, exist_ok=True)
+        if target.exists() and not overwrite:
+            return {
+                "ok": False,
+                "error": f"file exists and overwrite=False: {target}",
+                "path": str(target),
+            }
+
+    target.write_text(code, encoding="utf-8")
+    return {
+        "ok": True,
+        "path": str(target),
+        "bytes_written": len(code.encode("utf-8")),
+    }
+
+
+@tool
+def zero_new(kind: str, name: str, cwd: Optional[str] = None) -> Dict[str, Any]:
+    """Scaffold a new Zero project: `zero new cli|lib|package <name>`.
+
+    Args:
+        kind: "cli", "lib", or "package".
+        name: Project name.
+        cwd: Working directory in which to create the project.
+    """
+    if kind not in ("cli", "lib", "package"):
+        return {"ok": False, "error": f"kind must be cli/lib/package, got: {kind}"}
+    return run_zero(["new", kind, name], cwd=cwd)
+
+
+# ---------------------------------------------------------------------------
+# Diagnostics
+# ---------------------------------------------------------------------------
+
+@tool
+def zero_check(target: str, json_output: bool = True,
+               cwd: Optional[str] = None) -> Dict[str, Any]:
+    """Type-check and validate Zero source without running.
+
+    Args:
+        target: Path to a `.0` file, project dir, or `zero.json`.
+        json_output: Return structured diagnostics JSON (preferred).
+        cwd: Working directory for the check.
+    """
+    args = ["check"]
+    if json_output:
+        args.append("--json")
+    args.append(target)
+    return run_zero(args, cwd=cwd, parse_json=json_output)
+
+
+@tool
+def zero_explain(code: str, json_output: bool = True) -> Dict[str, Any]:
+    """Explain a diagnostic code from `zero check`.
+
+    Args:
+        code: Diagnostic code (e.g. "E0123").
+        json_output: Return JSON.
+    """
+    args = ["explain"]
+    if json_output:
+        args.append("--json")
+    args.append(code)
+    return run_zero(args, parse_json=json_output)
+
+
+@tool
+def zero_fix(target: str, cwd: Optional[str] = None) -> Dict[str, Any]:
+    """Generate a structured fix plan for diagnostics in `target`.
+
+    Runs `zero fix --plan --json <target>`.
+    """
+    return run_zero(["fix", "--plan", "--json", target], cwd=cwd, parse_json=True)
+
+
+# ---------------------------------------------------------------------------
+# Build / run / test
+# ---------------------------------------------------------------------------
+
+@tool
+def zero_run(
+    target: str,
+    args: Optional[List[str]] = None,
+    profile: Optional[str] = None,
+    target_arch: Optional[str] = None,
+    out: Optional[str] = None,
+    cwd: Optional[str] = None,
+    timeout: int = 120,
+) -> Dict[str, Any]:
+    """Compile and run a Zero program.
+
+    Args:
+        target: Path to `.0` file, project dir, or `zero.json`.
+        args: Args to pass to the program (after `--`).
+        profile: debug | dev | release-fast | release-small | tiny | audit.
+        target_arch: e.g. "darwin-arm64", "linux-musl-x64", "wasm32-wasi".
+        out: Optional output binary path.
+        cwd: Working directory.
+        timeout: Seconds before killing the process (default 120).
+    """
+    cmd = ["run"]
+    if target_arch:
+        cmd += ["--target", target_arch]
+    if profile:
+        cmd += ["--profile", profile]
+    if out:
+        cmd += ["--out", out]
+    cmd.append(target)
+    if args:
+        cmd += ["--", *args]
+    return run_zero(cmd, cwd=cwd, timeout=timeout)
+
+
+@tool
+def zero_build(
+    target: str,
+    emit: str = "exe",
+    profile: Optional[str] = None,
+    target_arch: Optional[str] = None,
+    out: Optional[str] = None,
+    json_output: bool = False,
+    cwd: Optional[str] = None,
+    timeout: int = 300,
+) -> Dict[str, Any]:
+    """Compile a Zero program to an executable / object / wasm.
+
+    Args:
+        target: Source file, project dir, or `zero.json`.
+        emit: "exe" | "obj" | "wasm".
+        profile: debug | dev | release-fast | release-small | tiny | audit.
+        target_arch: Compilation target triple (e.g. "linux-musl-x64").
+        out: Output artifact path.
+        json_output: Emit JSON build report.
+        cwd: Working directory.
+        timeout: Seconds before killing the process.
+    """
+    if emit not in ("exe", "obj", "wasm"):
+        return {"ok": False, "error": f"emit must be exe/obj/wasm, got: {emit}"}
+    cmd = ["build"]
+    if json_output:
+        cmd.append("--json")
+    cmd += ["--emit", emit]
+    if target_arch:
+        cmd += ["--target", target_arch]
+    if profile:
+        cmd += ["--profile", profile]
+    if out:
+        cmd += ["--out", out]
+    cmd.append(target)
+    return run_zero(cmd, cwd=cwd, parse_json=json_output, timeout=timeout)
+
+
+@tool
+def zero_ship(
+    target: str,
+    target_arch: Optional[str] = None,
+    profile: str = "release-small",
+    out: Optional[str] = None,
+    json_output: bool = True,
+    cwd: Optional[str] = None,
+    timeout: int = 600,
+) -> Dict[str, Any]:
+    """Produce a release-grade artifact via `zero ship`.
+
+    Args:
+        target: Source / project / zero.json.
+        target_arch: e.g. "linux-musl-x64".
+        profile: release-small | tiny | audit (default release-small).
+        out: Output path.
+        json_output: Emit JSON ship report.
+        cwd: Working directory.
+        timeout: Seconds budget.
+    """
+    cmd = ["ship"]
+    if json_output:
+        cmd.append("--json")
+    if target_arch:
+        cmd += ["--target", target_arch]
+    cmd += ["--profile", profile]
+    if out:
+        cmd += ["--out", out]
+    cmd.append(target)
+    return run_zero(cmd, cwd=cwd, parse_json=json_output, timeout=timeout)
+
+
+@tool
+def zero_test(target: str, json_output: bool = True,
+              cwd: Optional[str] = None, timeout: int = 300) -> Dict[str, Any]:
+    """Run `test` blocks in Zero source / project."""
+    cmd = ["test"]
+    if json_output:
+        cmd.append("--json")
+    cmd.append(target)
+    return run_zero(cmd, cwd=cwd, parse_json=json_output, timeout=timeout)
+
+
+@tool
+def zero_fmt(target: str, cwd: Optional[str] = None) -> Dict[str, Any]:
+    """Format Zero source in-place."""
+    return run_zero(["fmt", target], cwd=cwd)
+
+
+# ---------------------------------------------------------------------------
+# Inspection
+# ---------------------------------------------------------------------------
+
+@tool
+def zero_graph(target: str, json_output: bool = True,
+               cwd: Optional[str] = None) -> Dict[str, Any]:
+    """Dump the module/package dependency graph."""
+    cmd = ["graph"]
+    if json_output:
+        cmd.append("--json")
+    cmd.append(target)
+    return run_zero(cmd, cwd=cwd, parse_json=json_output)
+
+
+@tool
+def zero_size(target: str, artifact: Optional[str] = None,
+              json_output: bool = True, cwd: Optional[str] = None) -> Dict[str, Any]:
+    """Report binary size breakdown for a built artifact or source target."""
+    cmd = ["size"]
+    if json_output:
+        cmd.append("--json")
+    if artifact:
+        cmd += ["--out", artifact]
+    cmd.append(target)
+    return run_zero(cmd, cwd=cwd, parse_json=json_output)
+
+
+@tool
+def zero_mem(target: str, target_arch: Optional[str] = None,
+             json_output: bool = True, cwd: Optional[str] = None) -> Dict[str, Any]:
+    """Report static memory layout / usage for a target."""
+    cmd = ["mem"]
+    if json_output:
+        cmd.append("--json")
+    if target_arch:
+        cmd += ["--target", target_arch]
+    cmd.append(target)
+    return run_zero(cmd, cwd=cwd, parse_json=json_output)
+
+
+@tool
+def zero_routes(target: str, json_output: bool = True,
+                cwd: Optional[str] = None) -> Dict[str, Any]:
+    """List HTTP/web routes declared in a Zero web project."""
+    cmd = ["routes"]
+    if json_output:
+        cmd.append("--json")
+    cmd.append(target)
+    return run_zero(cmd, cwd=cwd, parse_json=json_output)
+
+
+@tool
+def zero_clean(target_dir: Optional[str] = None, all_artifacts: bool = False,
+               cwd: Optional[str] = None) -> Dict[str, Any]:
+    """Clean compiled artifacts (`.zero/` cache).
+
+    Args:
+        target_dir: Project directory (default cwd).
+        all_artifacts: Pass --all to remove the entire `.zero/` cache.
+    """
+    cmd = ["clean"]
+    if all_artifacts:
+        cmd.append("--all")
+    return run_zero(cmd, cwd=target_dir or cwd)

strands_zero-0.1.0/tests/test_smoke.py

@@ -0,0 +1,150 @@
+"""Smoke tests — exercise every tool against the real `zero` binary.
+
+Skips gracefully if Zero isn't installed. Some tests tolerate upstream-binary
+quirks (skills CLI, dyld LC_UUID on macOS) since this is an external tool.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from strands_zero._runner import find_zero_binary, run_zero
+from strands_zero.tools import (
+    zero_version, zero_doctor, zero_skills, zero_write, zero_check,
+    zero_run, zero_build, zero_explain, zero_targets, zero_graph,
+    zero_size, zero_fmt, zero_clean,
+)
+
+
+HELLO = '''pub fun main(world: World) -> Void raises {
+    check world.out.write("hello from zero\\n")
+}
+'''
+
+
+@pytest.fixture(scope="session")
+def zero_available():
+    if not find_zero_binary():
+        pytest.skip("zero binary not installed")
+
+
+def _unwrap(t):
+    """Unwrap a Strands @tool to its underlying function for direct call."""
+    return getattr(t, "__wrapped__", None) or getattr(t, "func", None) or t
+
+
+def test_find_binary(zero_available):
+    assert find_zero_binary() is not None
+
+
+def test_version(zero_available):
+    r = _unwrap(zero_version)(json_output=True)
+    assert r["ok"], r
+    assert "0.1" in r["stdout"] or (r.get("json") and "version" in r["json"])
+
+
+def test_targets(zero_available):
+    r = _unwrap(zero_targets)()
+    assert r["ok"], r
+    assert "darwin" in r["stdout"] or "linux" in r["stdout"]
+
+
+def test_skills_runs(zero_available):
+    """skills CLI may require repo-local bin/zero; just check our wrapper invokes it."""
+    r = _unwrap(zero_skills)(action="list")
+    assert "command" in r
+    assert "skills" in r["command"]
+
+
+def test_doctor(zero_available):
+    r = _unwrap(zero_doctor)(json_output=True)
+    assert r["exit_code"] in (0, 1, 2), r
+
+
+def test_write_and_check(zero_available, tmp_path):
+    w = _unwrap(zero_write)(HELLO, path=str(tmp_path / "hello.0"))
+    assert w["ok"] and Path(w["path"]).exists()
+
+    c = _unwrap(zero_check)(w["path"], json_output=True)
+    assert c["ok"], c
+    # Successful check should produce JSON diagnostics surface
+    assert "json" in c or c["stdout"] != ""
+
+
+def test_run_attempt(zero_available, tmp_path):
+    """zero run may fail on macOS 26 due to dyld LC_UUID issue in prebuilt binary.
+    We assert the wrapper invocation is correct, not that the program executes.
+    """
+    src = tmp_path / "hello.0"
+    src.write_text(HELLO)
+    r = _unwrap(zero_run)(str(src))
+    assert "command" in r
+    # If it ran, it should print our message; otherwise stderr should mention dyld
+    if r["ok"]:
+        assert "hello from zero" in r["stdout"]
+
+
+def test_build_exe(zero_available, tmp_path):
+    src = tmp_path / "h.0"
+    src.write_text(HELLO)
+    out = tmp_path / "h"
+    b = _unwrap(zero_build)(str(src), emit="exe", out=str(out))
+    assert "command" in b
+
+
+def test_build_invalid_emit(zero_available):
+    r = _unwrap(zero_build)("dummy.0", emit="bogus")
+    assert not r["ok"]
+    assert "emit" in r["error"]
+
+
+def test_explain(zero_available):
+    r = _unwrap(zero_explain)("E0001", json_output=True)
+    assert "command" in r
+
+
+def test_graph(zero_available, tmp_path):
+    src = tmp_path / "g.0"
+    src.write_text(HELLO)
+    r = _unwrap(zero_graph)(str(src), json_output=True)
+    assert "command" in r
+
+
+def test_fmt(zero_available, tmp_path):
+    src = tmp_path / "f.0"
+    src.write_text(HELLO)
+    r = _unwrap(zero_fmt)(str(src))
+    assert "command" in r
+
+
+def test_clean(zero_available, tmp_path):
+    r = _unwrap(zero_clean)(target_dir=str(tmp_path), all_artifacts=True)
+    assert "command" in r
+
+
+def test_skills_get_requires_name():
+    """Pure unit test - no zero binary needed."""
+    r = _unwrap(zero_skills)(action="get")
+    assert not r["ok"]
+    assert "name required" in r["error"]
+
+
+def test_unknown_skills_action():
+    r = _unwrap(zero_skills)(action="bogus")
+    assert not r["ok"]
+
+
+def test_zero_new_invalid_kind():
+    r = _unwrap(__import__("strands_zero.tools", fromlist=["zero_new"]).zero_new)(
+        kind="bogus", name="x"
+    )
+    assert not r["ok"]
+
+
+def test_run_zero_returns_error_when_missing(monkeypatch):
+    """Wrapper handles missing binary gracefully."""
+    monkeypatch.setattr("strands_zero._runner.find_zero_binary", lambda: None)
+    r = run_zero(["--version"])
+    assert not r["ok"]
+    assert "not found" in r["error"]