mycelium-cli 0.1.0__tar.gz → 0.3.0__tar.gz

{mycelium_cli-0.1.0 → mycelium_cli-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mycelium-cli
-Version: 0.1.0
+Version: 0.3.0
 Summary: Mycelium CLI — init, newwallet, compile, deploy, register
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown

mycelium_cli-0.3.0/mycelium_cli/commands/compile.py

@@ -0,0 +1,137 @@
+"""
+`mycelium compile` — compile the project's contract to Soroban WASM.
+
+Two paths:
+  - **remote** (default when no local toolchain is detected): POST the source to
+    the hosted `/compile` endpoint (constants.COMPILE_URL, runs the compiler in
+    Docker server-side) and write back the returned WASM. Needs zero local Rust
+    or stellar-cli install — the zero-toolchain default for new users.
+  - **local** (`--local`, or auto when a toolchain is present): run the compiler
+    pipeline (parse → validate → generate_wasm) on this machine via the pinned
+    stellar-cli 27.0.0 toolchain. For users who already have Rust + stellar-cli.
+"""
+
+import base64
+import os
+import shutil
+import sys
+
+from mycelium_sdk.constants import COMPILE_URL
+
+from mycelium_cli.config import get_value
+
+
+def _has_local_toolchain() -> bool:
+    """True if both a Rust compiler and the stellar binary are on PATH."""
+    return shutil.which("rustc") is not None and shutil.which("stellar") is not None
+
+
+def _compile_local(source_code: str, optimize: bool) -> bytes:
+    """Compile in-process via the bundled compiler (needs Rust + stellar-cli)."""
+    from mycelium_compiler.parser import parse_source
+    from mycelium_compiler.validator import validate_ast
+    from mycelium_compiler.codegen import generate_wasm
+
+    visitor = parse_source(source_code)
+    validate_ast(visitor)
+    return generate_wasm(visitor)
+
+
+def _compile_remote(filename: str, source_code: str) -> bytes:
+    """Compile via the hosted `/compile` endpoint; returns the WASM bytes."""
+    import requests
+
+    print(f"[compile] No local toolchain in use — compiling remotely via {COMPILE_URL}...")
+    try:
+        res = requests.post(
+            COMPILE_URL,
+            json={"filename": filename, "source_code": source_code},
+            timeout=120,
+        )
+    except requests.RequestException as e:
+        print(f"❌ Remote compile request failed: {e}")
+        print(f"   Set MYCELIUM_COMPILE_URL to point at a reachable backend, or "
+              f"install a local toolchain and use `--local`.")
+        sys.exit(1)
+
+    if not res.ok:
+        print(f"❌ Remote compile failed: HTTP {res.status_code}\n{res.text}")
+        sys.exit(1)
+
+    payload = res.json()
+    if not payload.get("success"):
+        print(f"❌ Compilation failed:\n{payload.get('logs', '(no logs returned)')}")
+        sys.exit(1)
+
+    wasm_b64 = payload.get("wasm_base64")
+    if not wasm_b64:
+        print("❌ Remote compile returned success but no WASM payload.")
+        sys.exit(1)
+    return base64.b64decode(wasm_b64)
+
+
+def run_compile(
+    file_path: str | None = None,
+    output_path: str | None = None,
+    optimize: bool = False,
+    remote: bool | None = None,
+    local: bool = False,
+) -> str:
+    """
+    Compile `file_path` to `output_path`. When omitted, both are read from
+    mycelium.toml ([onchain].source_contract / [onchain].target_wasm).
+
+    Path selection:
+      - `local=True`  → force the local toolchain.
+      - `remote=True` → force the hosted endpoint.
+      - neither       → local iff a toolchain is detected, else remote.
+    Returns the output path.
+    """
+    file_path = file_path or get_value("onchain", "source_contract", "contract.py")
+    output_path = output_path or get_value("onchain", "target_wasm", "build/contract.wasm")
+
+    if not os.path.exists(file_path):
+        print(f"Error: File {file_path} not found.")
+        sys.exit(1)
+
+    with open(file_path, "r") as f:
+        source_code = f.read()
+
+    # Decide the path. Explicit flags win; otherwise auto-detect.
+    if local and remote:
+        print("Error: pass at most one of --local / --remote.")
+        sys.exit(1)
+    if local:
+        use_remote = False
+    elif remote:
+        use_remote = True
+    else:
+        use_remote = not _has_local_toolchain()
+
+    where = "remotely" if use_remote else "locally"
+    print(f"Compiling contract {file_path} -> {output_path} ({where})...")
+
+    try:
+        if use_remote:
+            wasm_bytes = _compile_remote(os.path.basename(file_path), source_code)
+        else:
+            wasm_bytes = _compile_local(source_code, optimize)
+    except SystemExit:
+        raise
+    except Exception as e:
+        print(f"❌ Compilation failed: {e}")
+        sys.exit(1)
+
+    out_dir = os.path.dirname(output_path)
+    if out_dir:
+        os.makedirs(out_dir, exist_ok=True)
+    with open(output_path, "wb") as f_out:
+        f_out.write(wasm_bytes)
+
+    size = len(wasm_bytes)
+    print(f"✓ Compilation successful! Output: {output_path}")
+    print(f"  WASM size: {size:,} bytes ({size / 1024:.2f} KiB)")
+    # The release profile already optimizes for size (opt-level "z", LTO).
+    if optimize and not use_remote:
+        print("  (--optimize: size-optimized release profile is always applied)")
+    return output_path

mycelium_cli-0.3.0/mycelium_cli/commands/deal.py

@@ -0,0 +1,186 @@
+"""
+`mycelium deal …` — wire two agents into an agent-to-agent (A2A) commerce deal.
+
+Where `mycelium pay` is an *unconditional* transfer, a deal is *conditional*
+x402 commerce between two agents: the payer locks funds into a fresh escrow
+payable to a provider (resolved by Hive Registry unique name or raw address),
+and the provider only collects once it publishes a proof of the agreed task.
+If the provider never delivers, the payer reclaims the funds after the timeout.
+
+This is the CLI front door to what `a2a_demo.py` / `EscrowPaymentRouter` do by
+hand — two sovereign agents transacting purely through on-chain state:
+
+  open    payer locks `amount` XLM to a provider against a task hash → escrow id
+  release provider (or payer) publishes the proof preimage → funds disburse
+  refund  payer reclaims the locked funds after the deadline passes
+  status  read the escrow's current state (amount, provider, deadline, settled)
+
+The escrow contract enforces the proof (SHA-256(proof) == task_hash) and the
+deadline on-chain, so neither side has to trust the other. The board/registry
+default from `mycelium.toml`, mirroring `deploy` / `register` / `job`.
+
+Commands: open, release, refund, status.
+"""
+
+import hashlib
+import os
+from decimal import Decimal
+from typing import Optional
+
+import typer
+
+from mycelium_cli.config import get_value
+
+DEFAULT_WALLET_PATH = os.path.join(".mycelium", "wallet.json")
+PASSPHRASE_ENV_VAR = "MYCELIUM_DECRYPT_KEY"
+# Default escrow timeout (seconds) after which the payer may refund. Mirrors
+# mycelium_sdk.x402.settlement.DEFAULT_ESCROW_TIMEOUT_SECONDS (24h).
+DEFAULT_TIMEOUT_SECONDS = 24 * 60 * 60
+
+deal_app = typer.Typer(help="Conditional agent-to-agent (A2A) commerce via x402 escrow.")
+
+
+def _resolve_passphrase(label: str = "Wallet passphrase") -> str:
+    """MYCELIUM_DECRYPT_KEY if set, else prompt — matches the rest of the CLI."""
+    env_value = os.environ.get(PASSPHRASE_ENV_VAR)
+    if env_value:
+        return env_value
+    return typer.prompt(label, hide_input=True)
+
+
+def _context(network: Optional[str], wallet: str, *, signing: bool):
+    """Build an AgentContext. Read-only commands skip wallet + passphrase."""
+    from mycelium_sdk import AgentContext
+
+    network = network or get_value("onchain", "network", "testnet")
+    if signing:
+        if not os.path.exists(wallet):
+            typer.echo(f"Error: wallet {wallet} not found. Run `mycelium newwallet` first.")
+            raise typer.Exit(code=1)
+        return AgentContext(keypair_path=wallet, network_type=network, passphrase=_resolve_passphrase())
+    return AgentContext.read_only(network_type=network)
+
+
+def _resolve_agent_address(context, agent: str, registry: Optional[str]) -> str:
+    """Pass through a G/C address; otherwise resolve a Hive Registry unique name."""
+    from stellar_sdk import StrKey
+
+    if StrKey.is_valid_ed25519_public_key(agent) or StrKey.is_valid_contract(agent):
+        return agent
+    from mycelium_sdk import HiveClient
+
+    entry = HiveClient(context, registry_address=registry).resolve_agent(agent)
+    addr = entry.get("public_key")
+    if not addr:
+        typer.echo(f"Error: could not resolve agent '{agent}' to an address.")
+        raise typer.Exit(code=1)
+    return addr
+
+
+def _task_bytes(task: str) -> bytes:
+    """A task file's raw bytes, or the UTF-8 bytes of a literal string."""
+    if os.path.isfile(task):
+        with open(task, "rb") as f:
+            return f.read()
+    return task.encode("utf-8")
+
+
+@deal_app.command("open")
+def open_deal(
+    to: str = typer.Option(..., "--to", help="Provider: Hive Registry unique name or G/C address to pay"),
+    amount: str = typer.Option(..., "--amount", help="Amount in XLM to lock for the provider"),
+    task: str = typer.Option(..., "--task", help="Task spec file or string; its SHA-256 is the release condition"),
+    token: str = typer.Option(None, "--token", help="Payment token contract (defaults to native XLM SAC)"),
+    timeout: int = typer.Option(DEFAULT_TIMEOUT_SECONDS, "--timeout", help="Refund deadline in seconds"),
+    network: str = typer.Option(None, help="testnet or mainnet (defaults to mycelium.toml)"),
+    wallet: str = typer.Option(DEFAULT_WALLET_PATH, help="Wallet path"),
+    registry: str = typer.Option(None, "--registry", help="Hive Registry id override (for name resolution)"),
+):
+    """Payer locks `amount` XLM to a provider against a task hash; prints the escrow id."""
+    from mycelium_sdk.x402.settlement import EscrowPaymentRouter
+
+    context = _context(network, wallet, signing=True)
+    provider = _resolve_agent_address(context, to, registry)
+    task_hash = hashlib.sha256(_task_bytes(task)).digest()
+
+    typer.echo(f"[deal] Locking {amount} XLM to provider {to} ({provider[:8]}…) for {timeout}s...")
+    try:
+        escrow_id = EscrowPaymentRouter(context).create_locked_escrow(
+            provider_id=provider,
+            amount_xlm=Decimal(amount),
+            task_hash=task_hash,
+            token=token,
+            timeout_seconds=timeout,
+        )
+    except Exception as e:  # noqa: BLE001
+        typer.echo(f"❌ deal open failed: {e}")
+        raise typer.Exit(code=1)
+    typer.echo(f"✓ Deal opened. Escrow {escrow_id}")
+    typer.echo(f"  Provider releases with: mycelium deal release {escrow_id} --proof <task>")
+    typer.echo(f"  Payer refunds after {timeout}s with: mycelium deal refund {escrow_id}")
+
+
+@deal_app.command("release")
+def release(
+    escrow_id: str = typer.Argument(..., help="Escrow contract id from `deal open`"),
+    proof: str = typer.Option(..., "--proof", help="Proof file or string (must SHA-256 to the task hash)"),
+    network: str = typer.Option(None, help="testnet or mainnet (defaults to mycelium.toml)"),
+    wallet: str = typer.Option(DEFAULT_WALLET_PATH, help="Wallet path"),
+):
+    """Disburse the locked funds to the provider by publishing the task proof."""
+    from mycelium_sdk.x402.settlement import EscrowPaymentRouter
+
+    context = _context(network, wallet, signing=True)
+    try:
+        EscrowPaymentRouter(context).release_funds(escrow_id, _task_bytes(proof))
+    except Exception as e:  # noqa: BLE001
+        typer.echo(f"❌ deal release failed: {e}")
+        raise typer.Exit(code=1)
+    typer.echo(f"✓ Released escrow {escrow_id} — funds disbursed to the provider.")
+
+
+@deal_app.command("refund")
+def refund(
+    escrow_id: str = typer.Argument(..., help="Escrow contract id from `deal open`"),
+    network: str = typer.Option(None, help="testnet or mainnet (defaults to mycelium.toml)"),
+    wallet: str = typer.Option(DEFAULT_WALLET_PATH, help="Wallet path"),
+):
+    """Payer reclaims the locked funds after the deadline passes."""
+    from mycelium_sdk.x402.settlement import EscrowPaymentRouter
+
+    context = _context(network, wallet, signing=True)
+    try:
+        EscrowPaymentRouter(context).refund(escrow_id)
+    except Exception as e:  # noqa: BLE001
+        typer.echo(f"❌ deal refund failed: {e}")
+        raise typer.Exit(code=1)
+    typer.echo(f"✓ Refunded escrow {escrow_id} — funds returned to the payer.")
+
+
+@deal_app.command("status")
+def status(
+    escrow_id: str = typer.Argument(..., help="Escrow contract id from `deal open`"),
+    network: str = typer.Option(None, help="testnet or mainnet (defaults to mycelium.toml)"),
+):
+    """Show an escrow deal's current state (read-only, no wallet)."""
+    context = _context(network, DEFAULT_WALLET_PATH, signing=False)
+    try:
+        details = context.call_contract(escrow_id, "get_details", [], read_only=True)
+    except Exception as e:  # noqa: BLE001
+        typer.echo(f"❌ deal status failed: {e}")
+        raise typer.Exit(code=1)
+
+    def _get(key):
+        if isinstance(details, dict):
+            return details.get(key)
+        return None
+
+    amount = _get("amount")
+    provider = _get("provider")
+    deadline = _get("deadline")
+    settled = _get("settled")
+    typer.echo(f"Deal escrow {escrow_id}")
+    typer.echo(f"  amount   : {int(amount) / 10_000_000:.7f} XLM" if amount is not None else "  amount   : —")
+    typer.echo(f"  provider : {getattr(provider, 'address', provider)}")
+    typer.echo(f"  deadline : {int(deadline)} (unix)" if deadline is not None else "  deadline : —")
+    typer.echo(f"  settled  : {bool(settled)}")

{mycelium_cli-0.1.0 → mycelium_cli-0.3.0}/mycelium_cli/commands/deploy.py

@@ -4,23 +4,19 @@
 Mirrors the proven flow in the IDE backend's /api/deploy:
   - testnet: if the wallet has 0 XLM, fund it via Friendbot and poll.
   - mainnet: refuse to deploy unless the wallet holds >= 5 XLM (no Friendbot).
-  - deploy via the pinned stellar-cli 27.0.0 binary (ensure_stellar_cli()).
+  - deploy via pure-Python signed Soroban transactions (no stellar-cli / Rust).
   - write the resulting contract_id + wallet public key back to mycelium.toml.
 """
 
 import os
-import subprocess
 import sys
 import time
 
-from mycelium_compiler.codegen import ensure_stellar_cli
 from mycelium_sdk import crypto
 from mycelium_sdk.constants import (
     FRIENDBOT_URL,
     HORIZON_URLS,
     MAINNET_MIN_XLM,
-    NETWORK_PASSPHRASES,
-    SOROBAN_RPC_URLS,
     normalize_network,
 )
 
@@ -97,7 +93,7 @@ def run_deploy(
         print(f"Error: wallet {wallet_path} not found. Run `mycelium newwallet` first.")
         sys.exit(1)
 
-    secret, public_key = _load_secret(wallet_path, passphrase)
+    _, public_key = _load_secret(wallet_path, passphrase)
     print(f"[deploy] Deploying {wasm_path} to {network} as {public_key}...")
 
     balance = _native_balance(network, public_key)
@@ -113,20 +109,22 @@ def run_deploy(
             )
             sys.exit(1)
 
-    stellar_bin = ensure_stellar_cli()
-    cmd = [
-        stellar_bin, "contract", "deploy",
-        "--wasm", wasm_path,
-        "--source-account", secret,
-        "--rpc-url", SOROBAN_RPC_URLS[network],
-        "--network-passphrase", NETWORK_PASSPHRASES[network],
-    ]
-    res = subprocess.run(cmd, capture_output=True, text=True, timeout=90)
-    if res.returncode != 0:
-        print(f"❌ Deployment failed:\n{res.stdout}\n{res.stderr}")
+    with open(wasm_path, "rb") as f:
+        wasm_bytes = f.read()
+
+    from mycelium_sdk.context import AgentContext
+
+    try:
+        ctx = AgentContext(
+            keypair_path=wallet_path,
+            network_type=network,
+            passphrase=passphrase,
+        )
+        contract_id = ctx.deploy_contract(wasm_bytes)
+    except Exception as e:  # noqa: BLE001 - surface a clean CLI error
+        print(f"❌ Deployment failed: {e}")
         sys.exit(1)
 
-    contract_id = res.stdout.strip().splitlines()[-1].strip()
     print(f"✓ Deployment successful! Contract ID: {contract_id}")
 
     if write_config:

{mycelium_cli-0.1.0 → mycelium_cli-0.3.0}/mycelium_cli/commands/discover.py

@@ -31,9 +31,18 @@ def run_discover(
     context = AgentContext.read_only(network_type=network)
     hive = HiveClient(context, registry_address=registry)
 
-    print(f"[discover] Scanning Hive Registry {registry} on {network}...")
+    # Hosted indexer first (instant, full history); falls back to the on-chain
+    # event-scan automatically when unreachable. An explicit --start-ledger means
+    # the caller wants the chain scan, so skip the indexer in that case.
+    prefer_indexer = start_ledger is None
+    if prefer_indexer:
+        print(f"[discover] Querying indexer (falls back to chain scan of {registry})...")
+    else:
+        print(f"[discover] Scanning Hive Registry {registry} on {network}...")
     try:
-        agents = hive.discover_agents(start_ledger=start_ledger, resolve=resolve)
+        agents = hive.discover_agents(
+            start_ledger=start_ledger, resolve=resolve, prefer_indexer=prefer_indexer
+        )
     except Exception as e:
         print(f"❌ Discovery failed: {e}")
         sys.exit(1)

mycelium_cli-0.3.0/mycelium_cli/commands/doctor.py

@@ -0,0 +1,132 @@
+"""
+`mycelium doctor` — verify connectivity and print fixes.
+
+Mycelium's default happy path is **zero-toolchain**: compile runs on the hosted
+backend and deploy is pure-Python signed transactions, so neither Rust nor
+stellar-cli is required. doctor's hard checks reflect that:
+  - the hosted compile endpoint is reachable,
+  - the Soroban RPC for the configured network is reachable.
+
+stellar-cli and a local Rust/wasm32 toolchain are reported as **optional**
+"local compile" capabilities — their absence is informational, never a failure.
+
+Each failed check prints the exact command that fixes it. Exit code is non-zero
+only if a *required* check fails, so it can gate CI.
+"""
+
+import re
+import shutil
+import subprocess
+import sys
+from typing import Optional
+
+from mycelium_sdk.constants import COMPILE_URL, SOROBAN_RPC_URLS, normalize_network
+
+from mycelium_cli.config import get_value
+
+# Must track compiler/.../core.py::ensure_stellar_cli (the version we bundle).
+PINNED_STELLAR_VERSION = "27.0.0"
+WASM_TARGET = "wasm32-unknown-unknown"
+
+_OK = "✓"
+_NO = "✗"
+_WARN = "⚠"
+
+
+def _run(cmd: list[str]) -> Optional[str]:
+    """Run `cmd`, returning stripped stdout, or None if it isn't runnable."""
+    try:
+        res = subprocess.run(cmd, capture_output=True, text=True, timeout=20)
+    except (FileNotFoundError, subprocess.SubprocessError):
+        return None
+    if res.returncode != 0:
+        return None
+    return (res.stdout or res.stderr).strip()
+
+
+def _check_stellar_cli() -> None:
+    """Optional: report local stellar-cli (only needed for `compile --local`)."""
+    binary = shutil.which("stellar")
+    if not binary:
+        print(f"  {_WARN} stellar-cli   not installed (optional — only for `compile --local`)")
+        print(f"       install: cargo install --locked stellar-cli@{PINNED_STELLAR_VERSION}")
+        return
+    out = _run(["stellar", "--version"]) or ""
+    m = re.search(r"(\d+)\.(\d+)\.(\d+)", out)
+    version = m.group(0) if m else "unknown"
+    major = int(m.group(1)) if m else 0
+    pinned_major = int(PINNED_STELLAR_VERSION.split(".")[0])
+    if major == pinned_major:
+        print(f"  {_OK} stellar-cli   {version} ({binary}) — local compile available")
+    else:
+        print(f"  {_WARN} stellar-cli   {version} — Mycelium pins v{PINNED_STELLAR_VERSION} for local compile")
+        print(f"       fix: cargo install --locked stellar-cli@{PINNED_STELLAR_VERSION}")
+
+
+def _check_rust() -> None:
+    """Optional: report local Rust + wasm32 target (only for `compile --local`)."""
+    rustc = _run(["rustc", "--version"])
+    if not rustc:
+        print(f"  {_WARN} rust          not installed (optional — only for `compile --local`)")
+        print("       install: curl https://sh.rustup.rs -sSf | sh")
+        return
+    print(f"  {_OK} rust          {rustc}")
+
+    installed = _run(["rustup", "target", "list", "--installed"]) or ""
+    if WASM_TARGET in installed:
+        print(f"  {_OK} wasm target   {WASM_TARGET} installed — local compile available")
+    else:
+        print(f"  {_WARN} wasm target   {WASM_TARGET} missing (optional)")
+        print(f"       fix: rustup target add {WASM_TARGET}")
+
+
+def _check_compile_endpoint() -> bool:
+    """Required: the hosted compile endpoint must be reachable (default path)."""
+    import requests
+
+    # GET the backend root — the /compile route only accepts POST, but a
+    # reachable host returning any HTTP response proves connectivity.
+    base = COMPILE_URL.rsplit("/compile", 1)[0] or COMPILE_URL
+    try:
+        requests.get(base, timeout=15)
+        print(f"  {_OK} compile       hosted endpoint reachable ({COMPILE_URL})")
+        return True
+    except Exception as e:
+        print(f"  {_NO} compile       hosted endpoint unreachable: {e}")
+        print(f"       fix: check connectivity to {COMPILE_URL}, set MYCELIUM_COMPILE_URL, "
+              f"or install a local toolchain and use `compile --local`")
+        return False
+
+
+def _check_rpc(network: str) -> bool:
+    url = SOROBAN_RPC_URLS[network]
+    try:
+        from stellar_sdk import SorobanServer
+
+        seq = SorobanServer(url).get_latest_ledger().sequence
+        print(f"  {_OK} rpc           {network} reachable (ledger {seq})")
+        return True
+    except Exception as e:
+        print(f"  {_NO} rpc           {network} unreachable: {e}")
+        print(f"       fix: check connectivity to {url}")
+        return False
+
+
+def run_doctor(network: Optional[str] = None) -> bool:
+    network = normalize_network(network or get_value("onchain", "network", "testnet"))
+    print("\nMycelium doctor — connectivity check\n")
+
+    # Required checks gate the exit code; optional ones are informational only.
+    required = [
+        _check_compile_endpoint(),
+        _check_rpc(network),
+    ]
+    print("\n  optional — local compile (not needed for the default workflow):")
+    _check_stellar_cli()
+    _check_rust()
+
+    ok = all(required)
+    print(f"\n{'✓ All required checks passed.' if ok else '✗ Some required checks failed — see fixes above.'}\n")
+    if not ok:
+        sys.exit(1)
+    return ok

mycelium_cli-0.3.0/mycelium_cli/commands/init.py

@@ -0,0 +1,73 @@
+"""
+`mycelium init` — scaffold a new agent project per sdk.md section 1.1:
+
+    <project>/
+    ├── mycelium.toml      # project / agent / onchain / registry config
+    ├── agent.py           # outer LLM-orchestration logic
+    ├── contract.py        # inner Soroban contract (Mycelium DSL)
+    └── .mycelium/         # protected dir for the encrypted wallet (gitignored)
+
+The file templates live in `mycelium_sdk.scaffold` (shared with the IDE backend's
+in-IDE agent creation so the two scaffolders never drift).
+"""
+
+import os
+
+import tomli_w
+
+from mycelium_sdk.scaffold import (
+    CONTRACT_TEMPLATE,
+    GITIGNORE,
+    VALID_FRAMEWORKS,
+    API_KEY_ENV as _API_KEY_ENV,
+    agent_template,
+    build_config,
+    validate_unique_name,
+)
+
+
+def run_init(
+    project_name: str,
+    framework: str = "custom",
+    model: str = "custom",
+    unique_name: str | None = None,
+    api_key: str | None = None,
+) -> str:
+    """
+    Scaffold a project directory. Prompting for framework/model/unique_name is
+    handled by the CLI layer; this function takes resolved values so it can be
+    driven non-interactively (tests/CI). When `api_key` is given it is written
+    to a gitignored `.env` so the agent can authenticate without re-prompting.
+    Returns the project path.
+    """
+    if framework not in VALID_FRAMEWORKS:
+        raise ValueError(f"framework must be one of {VALID_FRAMEWORKS}, got {framework!r}")
+    unique_name = unique_name or project_name
+    if not validate_unique_name(unique_name):
+        raise ValueError(
+            f"unique_name {unique_name!r} must match ^[a-zA-Z0-9_]{{3,30}}$"
+        )
+
+    os.makedirs(project_name, exist_ok=True)
+    os.makedirs(os.path.join(project_name, ".mycelium"), exist_ok=True)
+
+    with open(os.path.join(project_name, "mycelium.toml"), "wb") as f:
+        tomli_w.dump(build_config(project_name, framework, model, unique_name), f)
+    with open(os.path.join(project_name, "contract.py"), "w") as f:
+        f.write(CONTRACT_TEMPLATE)
+    with open(os.path.join(project_name, "agent.py"), "w") as f:
+        f.write(agent_template(framework, model, unique_name))
+    with open(os.path.join(project_name, ".gitignore"), "w") as f:
+        f.write(GITIGNORE)
+
+    if api_key:
+        env_var = _API_KEY_ENV.get(framework, "API_KEY")
+        env_path = os.path.join(project_name, ".env")
+        with open(env_path, "w") as f:
+            f.write(f"{env_var}={api_key}\n")
+        try:
+            os.chmod(env_path, 0o600)
+        except OSError:
+            pass
+
+    return project_name