pythsol 0.1.0__py3-none-any.whl

pythsol/cli/commands/idl_cmd.py

@@ -0,0 +1,69 @@
+"""`pythsol idl PROGRAM.py` — write the Anchor-style IDL (no SBF toolchain)."""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+import click
+
+from pythsol.compiler.idl import idl_json
+from pythsol.compiler.modules import read_sibling_modules
+from pythsol.compiler.pipeline import emit_program
+
+
+@click.command(name="idl")
+@click.argument(
+    "program",
+    metavar="PROGRAM.py",
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+)
+@click.option(
+    "--out",
+    "-o",
+    type=click.Path(dir_okay=False, writable=True, path_type=Path),
+    default=None,
+    help="Write the IDL here instead of printing it.",
+)
+@click.option(
+    "--json",
+    "as_json",
+    is_flag=True,
+    default=False,
+    help="Emit machine-readable diagnostics on stdout when the program fails.",
+)
+def idl(program: Path, out: Path | None, as_json: bool) -> None:
+    """Generate the legacy IDL for a PythSol program."""
+    try:
+        source_text = program.read_text(encoding="utf-8", errors="replace")
+        modules, module_files = read_sibling_modules(program)
+    except OSError as os_error:
+        click.echo(f"error: cannot read {program}: {os_error}", err=True)
+        sys.exit(2)
+
+    generated = emit_program(
+        source_text,
+        program,
+        modules=modules,
+        module_files=module_files,
+    )
+    if not generated.ok or generated.generated is None:
+        for diagnostic in generated.diagnostics:
+            click.echo(diagnostic.render(), err=True)
+        if as_json:
+            payload = {
+                "ok": False,
+                "diagnostics": [item.as_dict() for item in generated.diagnostics],
+            }
+            click.echo(json.dumps(payload, indent=2))
+        sys.exit(1)
+
+    text = idl_json(generated.generated)
+    if out is None:
+        click.echo(text, nl=False)
+    else:
+        out.parent.mkdir(parents=True, exist_ok=True)
+        out.write_text(text, encoding="utf-8", newline="\n")
+        click.echo(f"idl: wrote {out}")
+    sys.exit(0)

pythsol/cli/commands/idl_publish.py

@@ -0,0 +1,80 @@
+"""`pythsol idl-publish` — write the IDL and optionally hand it to Anchor.
+
+On-chain publish runs ``anchor idl init`` only when the Anchor CLI is on
+``PATH``. ``--dry-run`` prints that command and does not look for Anchor.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+
+import click
+
+from pythsol.cli.cluster import resolve_url
+from pythsol.compiler.idl import idl_json
+from pythsol.compiler.modules import read_sibling_modules
+from pythsol.compiler.pipeline import emit_program
+
+
+def anchor_idl_argv(idl_path: Path, address: str, url: str) -> list[str]:
+    """The Anchor CLI invocation that would publish this IDL."""
+    return [
+        "anchor",
+        "idl",
+        "init",
+        "--filepath",
+        str(idl_path),
+        "--provider.cluster",
+        url,
+        address,
+    ]
+
+
+@click.command(name="idl-publish")
+@click.argument("program", type=click.Path(exists=True, dir_okay=False, path_type=Path))
+@click.option("--out", "-o", type=click.Path(dir_okay=False, path_type=Path), default=None)
+@click.option("--address", required=True, help="Program id the IDL is published for.")
+@click.option("--url", default=None, help="Cluster name or RPC URL. Default: devnet.")
+@click.option("--dry-run", is_flag=True, help="Write the IDL and print the anchor command.")
+def idl_publish(
+    program: Path,
+    out: Path | None,
+    address: str,
+    url: str | None,
+    dry_run: bool,
+) -> None:
+    """Write an IDL file. Publish it only when the Anchor CLI is installed."""
+    try:
+        source_text = program.read_text(encoding="utf-8", errors="replace")
+        modules, module_files = read_sibling_modules(program)
+    except OSError as os_error:
+        click.echo(f"error: cannot read {program}: {os_error}", err=True)
+        sys.exit(2)
+    generated = emit_program(
+        source_text,
+        program,
+        modules=modules,
+        module_files=module_files,
+    )
+    if not generated.ok or generated.generated is None:
+        for diagnostic in generated.diagnostics:
+            click.echo(diagnostic.render(), err=True)
+        sys.exit(1)
+    dest = out or Path("target/pythsol") / generated.name / f"{generated.name}.json"
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    dest.write_text(idl_json(generated.generated, address=address), encoding="utf-8", newline="\n")
+    cluster = resolve_url(url)
+    argv = anchor_idl_argv(dest, address, cluster)
+    click.echo(f"idl: wrote {dest}")
+    click.echo(" ".join(argv))
+    if dry_run:
+        sys.exit(0)
+    import shutil
+
+    if shutil.which("anchor") is None:
+        click.echo("error: anchor CLI not found; IDL file was written", err=True)
+        sys.exit(1)
+    completed = subprocess.run(argv, check=False)
+    sys.exit(int(completed.returncode))

pythsol/cli/commands/init.py

@@ -0,0 +1,65 @@
+"""`pythsol init DIR` — scaffold a counter, ledger, vault, or escrow program."""
+
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+import click
+
+from pythsol.cli.templates import TEMPLATES, project_files
+
+_NAME = re.compile(r"^[a-z][a-z0-9_-]{0,62}$")
+
+
+@click.command(name="init")
+@click.argument(
+    "directory",
+    metavar="DIR",
+    type=click.Path(file_okay=False, path_type=Path),
+)
+@click.option(
+    "--template",
+    type=click.Choice(TEMPLATES),
+    default="counter",
+    show_default=True,
+    help="Program to write into programs/.",
+)
+@click.option(
+    "--name",
+    default=None,
+    help="Project name (default: the directory name).",
+)
+def init(directory: Path, template: str, name: str | None) -> None:
+    """Create a PythSol project (pysol.toml, program, README).
+
+    Refuses to write into a directory that already has files.
+    """
+    project = name or directory.name
+    if _NAME.fullmatch(project) is None:
+        click.echo(
+            f"error: name `{project}` must match {_NAME.pattern}",
+            err=True,
+        )
+        sys.exit(2)
+    if directory.exists() and not directory.is_dir():
+        click.echo(f"error: {directory} is not a directory", err=True)
+        sys.exit(2)
+    if directory.exists() and any(directory.iterdir()):
+        click.echo(f"error: {directory} is not empty", err=True)
+        sys.exit(2)
+
+    directory.mkdir(parents=True, exist_ok=True)
+    written: list[Path] = []
+    for relative, text in project_files(project, template).items():
+        path = directory / relative
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(text, encoding="utf-8", newline="\n")
+        written.append(path)
+
+    click.echo(f"Created {directory} (template: {template})")
+    for path in written:
+        click.echo(f"  {path.relative_to(directory).as_posix()}")
+    click.echo(f"Next: cd {directory} && pythsol check programs/{project}.py && pythsol test")
+    sys.exit(0)

pythsol/cli/commands/port_cmd.py

@@ -0,0 +1,42 @@
+"""`pythsol port` — sketch a PythSol program from an Anchor-legacy IDL."""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+import click
+
+from pythsol.client.port import PortError, render_port
+
+
+@click.command(name="port")
+@click.argument("idl", type=click.Path(exists=True, dir_okay=False, path_type=Path))
+@click.option("--out", "-o", type=click.Path(dir_okay=False, path_type=Path), default=None)
+def port_cmd(idl: Path, out: Path | None) -> None:
+    """Write a skeleton program. Instruction bodies are ``pass``."""
+    try:
+        payload = json.loads(idl.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        click.echo(f"error: invalid JSON: {exc}", err=True)
+        sys.exit(1)
+    except OSError as exc:
+        click.echo(f"error: cannot read {idl}: {exc}", err=True)
+        sys.exit(2)
+    if not isinstance(payload, dict):
+        click.echo("error: IDL JSON must be an object", err=True)
+        sys.exit(1)
+    try:
+        text = render_port(payload)
+    except PortError as exc:
+        click.echo(f"error: {exc}", err=True)
+        sys.exit(1)
+    if out is None:
+        click.echo(text, nl=False)
+    else:
+        out.parent.mkdir(parents=True, exist_ok=True)
+        out.write_text(text, encoding="utf-8", newline="\n")
+        click.echo(f"wrote {out}")
+        click.echo("TODO: replace each `pass` with the instruction body")
+    sys.exit(0)

pythsol/cli/commands/profile.py

@@ -0,0 +1,57 @@
+"""`pythsol profile` — read compute units and source locations from logs.
+
+The runtime already logs ``(file.py:line)`` on failure and the loader logs
+``consumed N of M compute units`` for the whole instruction. This command
+prints those. It does not invent a per-line CU split.
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+import click
+
+_CU = re.compile(r"consumed (\d+) of (\d+)")
+_LOC = re.compile(r"\(([^():]+\.py):(\d+)\)")
+
+
+def profile_rows(text: str) -> list[tuple[str, str]]:
+    """``(location, detail)`` rows from program logs."""
+    rows: list[tuple[str, str]] = []
+    seen: set[tuple[str, str]] = set()
+    for line in text.splitlines():
+        for match in _LOC.finditer(line):
+            key = (f"{match.group(1)}:{match.group(2)}", "logged")
+            if key not in seen:
+                seen.add(key)
+                rows.append(key)
+        consumed = _CU.search(line)
+        if consumed:
+            rows.append(("(program)", f"{consumed.group(1)} of {consumed.group(2)} CU"))
+    return rows
+
+
+@click.command(name="profile")
+@click.option(
+    "--logs",
+    "logs_path",
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+    default=None,
+    help="File of program logs. Default: stdin.",
+)
+def profile(logs_path: Path | None) -> None:
+    """Print source locations and the program compute-unit total from logs."""
+    if logs_path is None:
+        text = sys.stdin.read()
+    else:
+        text = logs_path.read_text(encoding="utf-8", errors="replace")
+    rows = profile_rows(text)
+    if not rows:
+        click.echo("profile: no source locations or compute-unit lines")
+        sys.exit(1)
+    click.echo(f"{'location':<24} detail")
+    for location, detail in rows:
+        click.echo(f"{location:<24} {detail}")
+    sys.exit(0)

pythsol/cli/commands/serve.py

@@ -0,0 +1,52 @@
+"""`pythsol serve` — local playground on 127.0.0.1."""
+
+from __future__ import annotations
+
+import sys
+
+import click
+
+from pythsol.playground.server import bind
+
+_LOOPBACK = {"127.0.0.1", "localhost", "::1"}
+
+
+@click.command(name="serve")
+@click.option("--host", default="127.0.0.1", show_default=True)
+@click.option("--port", default=8765, show_default=True, type=int)
+@click.option(
+    "--public",
+    is_flag=True,
+    help="Allow a non-loopback host. Check and emit only; compile stays off.",
+)
+@click.option(
+    "--allow-compile",
+    is_flag=True,
+    help="With --public, also serve POST /v1/compile. Clang sees only "
+    "compiler-generated C, never visitor source. Off by default.",
+)
+def serve(host: str, port: int, public: bool, allow_compile: bool) -> None:
+    """Serve the playground. Check and emit parse source. They do not run it.
+
+    Without ``--public`` the process accepts only loopback and can compile.
+    ``--public`` is the hostable mode: any host, no clang until you also
+    pass ``--allow-compile``.
+    """
+    if host not in _LOOPBACK and not public:
+        click.echo(
+            "error: --host must be 127.0.0.1, localhost, or ::1 (or pass --public)",
+            err=True,
+        )
+        sys.exit(2)
+    try:
+        httpd = bind(host, port, public=public, allow_compile=allow_compile)
+    except OSError as exc:
+        click.echo(f"error: {exc}", err=True)
+        sys.exit(1)
+    mode = "check+emit+compile" if ((not public) or allow_compile) else "check+emit"
+    click.echo(f"playground: http://{host}:{port}/ ({mode})")
+    try:
+        httpd.serve_forever()
+    except KeyboardInterrupt:
+        httpd.shutdown()
+    sys.exit(0)

pythsol/cli/commands/test_cmd.py

@@ -0,0 +1,217 @@
+"""`pythsol test` — build the program, then run pytest against LiteSVM."""
+
+from __future__ import annotations
+
+import importlib.util
+import os
+import shutil
+import socket
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+import click
+
+from pythsol.cli.commands.build import BuildFailed, build_program
+from pythsol.cli.config import ConfigError, find_config, load_config
+from pythsol.compiler.diagnostics import PysolError
+
+_VALUE_FLAGS = {"-k", "-m", "--tb", "-p", "-c", "--override-ini", "-o", "--rootdir"}
+
+
+def _has_node(args: tuple[str, ...]) -> bool:
+    """True when the user already named a file or directory for pytest."""
+    skip = False
+    for arg in args:
+        if skip:
+            skip = False
+            continue
+        if arg in _VALUE_FLAGS:
+            skip = True
+            continue
+        if arg.startswith("-"):
+            continue
+        return True
+    return False
+
+
+def _project_root(program: Path) -> Path:
+    if program.parent.name == "programs":
+        return program.parent.parent
+    return program.parent
+
+
+def _pytest_cmd(paths: list[str]) -> list[str]:
+    return [
+        sys.executable,
+        "-m",
+        "pytest",
+        "-p",
+        "pythsol.testing.plugin",
+        "-q",
+        "--tb=short",
+        *paths,
+    ]
+
+
+def _wait_rpc(url: str, timeout_s: float) -> bool:
+    import time
+
+    from pythsol.cli.rpc import post_json
+
+    deadline = time.monotonic() + timeout_s
+    while time.monotonic() < deadline:
+        try:
+            post_json(url, "getHealth", [])
+            return True
+        except Exception:
+            time.sleep(0.4)
+    return False
+
+
+def _free_port() -> int:
+    with socket.socket() as sock:
+        sock.bind(("127.0.0.1", 0))
+        return int(sock.getsockname()[1])
+
+
+def _run_localnet(so: Path, cmd: list[str], env: dict[str, str], cwd: Path) -> int:
+    """Start a test validator, deploy ``so``, run pytest, then stop the validator."""
+    port = _free_port()
+    ledger = Path(tempfile.mkdtemp(prefix="pythsol-ledger-"))
+    url = f"http://127.0.0.1:{port}"
+    validator = [
+        "solana-test-validator",
+        "--ledger",
+        str(ledger),
+        "--rpc-port",
+        str(port),
+        "--bind-address",
+        "127.0.0.1",
+        "--reset",
+        "--quiet",
+    ]
+    proc = subprocess.Popen(validator, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+    try:
+        if not _wait_rpc(url, 90):
+            click.echo("error: solana-test-validator did not open an RPC port", err=True)
+            return 1
+        deploy = ["solana", "program", "deploy", str(so), "--url", url]
+        completed = subprocess.run(deploy, capture_output=True, text=True, check=False)
+        if completed.returncode != 0:
+            click.echo(completed.stderr or completed.stdout or "deploy failed", err=True)
+            return 1
+        child_env = dict(env)
+        child_env["PYSOL_RPC_URL"] = url
+        child_env["PYTHSOL_TEST_RPC"] = url
+        click.echo(f"localnet: {url}")
+        result = subprocess.run(cmd, cwd=cwd, env=child_env, check=False)
+        return int(result.returncode)
+    finally:
+        proc.terminate()
+        try:
+            proc.wait(timeout=10)
+        except subprocess.TimeoutExpired:
+            proc.kill()
+        shutil.rmtree(ledger, ignore_errors=True)
+
+
+@click.command(
+    name="test",
+    context_settings={"ignore_unknown_options": True, "allow_interspersed_args": False},
+)
+@click.option(
+    "--program",
+    "program_path",
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+    default=None,
+    help="Program entry. Default: the first [[programs]] entry in pysol.toml.",
+)
+@click.option("--localnet", is_flag=True, help="Also deploy onto solana-test-validator.")
+@click.argument("pytest_args", nargs=-1, type=click.UNPROCESSED)
+def test_cmd(program_path: Path | None, localnet: bool, pytest_args: tuple[str, ...]) -> None:
+    """Build the program and run pytest.
+
+    Tests use the ``program``, ``payer``, ``svm``, ``accounts``, and ``send``
+    fixtures. The runner is LiteSVM. ``--localnet`` also starts
+    ``solana-test-validator`` and deploys the ``.so`` when that CLI is installed.
+    The fixtures stay on LiteSVM either way.
+    """
+    if localnet and (
+        shutil.which("solana-test-validator") is None or shutil.which("solana") is None
+    ):
+        click.echo("error: solana-test-validator not found", err=True)
+        click.echo(
+            '  fix: sh -c "$(curl -sSfL https://release.anza.xyz/stable/install)"',
+            err=True,
+        )
+        sys.exit(1)
+    if importlib.util.find_spec("pytest") is None:
+        click.echo("error: pytest is not installed. pip install 'pythsol[test]'", err=True)
+        sys.exit(1)
+
+    config_path = None if program_path is not None else find_config(Path.cwd())
+    out: Path | None = None
+    name: str | None = None
+    root: Path
+    if program_path is None:
+        if config_path is None:
+            click.echo("error: pass a program or run from a directory with pysol.toml", err=True)
+            sys.exit(2)
+        try:
+            config = load_config(config_path)
+        except ConfigError as exc:
+            click.echo(f"error: {exc}", err=True)
+            sys.exit(2)
+        entry = config.programs[0]
+        program_path = entry.entry
+        name = entry.name
+        out = config.out_dir / entry.name
+        root = config_path.parent
+    else:
+        root = _project_root(program_path)
+
+    if not program_path.is_file():
+        click.echo(f"error: program not found: {program_path}", err=True)
+        sys.exit(2)
+
+    try:
+        built = build_program(program_path, out=out, name=name)
+    except OSError as os_error:
+        click.echo(f"error: cannot read {program_path}: {os_error}", err=True)
+        sys.exit(2)
+    except BuildFailed as failed:
+        for diagnostic in failed.diagnostics:
+            click.echo(diagnostic.render(), err=True)
+        sys.exit(1)
+    except PysolError as error:
+        click.echo(error.render(), err=True)
+        sys.exit(1)
+
+    if built.cache == "hit":
+        click.echo("build: cache hit (skipped clang)")
+    click.echo(f"test: {built.so_path}")
+
+    if _has_node(pytest_args):
+        nodes = list(pytest_args)
+    else:
+        tests = root / "tests"
+        if not tests.is_dir():
+            click.echo(f"error: no tests directory at {tests}", err=True)
+            sys.exit(1)
+        nodes = [str(tests), *pytest_args]
+
+    env = os.environ.copy()
+    env["PYTHSOL_TEST_SO"] = str(built.so_path)
+    env["PYTHSOL_TEST_CLIENT"] = str(built.client_path)
+    env["PYTHSOL_TEST_SOURCE"] = str(program_path)
+    env["PYTHSOL_TEST_IDL"] = str(built.idl_path)
+    env["PYTEST_DISABLE_PLUGIN_AUTOLOAD"] = "1"
+    cmd = _pytest_cmd(nodes)
+    if localnet:
+        code = _run_localnet(built.so_path, cmd, env, root)
+    else:
+        completed = subprocess.run(cmd, cwd=root, env=env, check=False)
+        code = int(completed.returncode)
+    sys.exit(code)

pythsol/cli/commands/verify.py

@@ -0,0 +1,96 @@
+"""`pythsol verify` — compare two program binaries, or a build against a dump.
+
+Exit ``0`` when the sha256 matches. Exit ``3`` when it does not.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+import click
+
+from pythsol.cli.cluster import resolve_url
+from pythsol.cli.commands.build import BuildFailed, build_program
+from pythsol.compiler.diagnostics import PysolError
+
+
+def file_sha256(path: Path) -> str:
+    """sha256 hex of ``path``."""
+    return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def dump_argv(address: str, url: str, dest: Path) -> list[str]:
+    """``solana program dump`` invocation."""
+    return ["solana", "program", "dump", "--url", url, address, str(dest)]
+
+
+def _emit(left: Path, right: Path) -> None:
+    left_hash = file_sha256(left)
+    right_hash = file_sha256(right)
+    if left_hash == right_hash:
+        click.echo(f"MATCH sha256:{left_hash}")
+        sys.exit(0)
+    click.echo(f"MISMATCH {left} sha256:{left_hash} ({left.stat().st_size} bytes)", err=True)
+    click.echo(f"MISMATCH {right} sha256:{right_hash} ({right.stat().st_size} bytes)", err=True)
+    sys.exit(3)
+
+
+@click.command(name="verify")
+@click.argument("program", required=False, type=click.Path(dir_okay=False, path_type=Path))
+@click.option("--left", type=click.Path(exists=True, dir_okay=False, path_type=Path), default=None)
+@click.option("--right", type=click.Path(exists=True, dir_okay=False, path_type=Path), default=None)
+@click.option("--dump", "dump_path", type=click.Path(exists=True, dir_okay=False, path_type=Path))
+@click.option("--address", default=None, help="On-chain program id to dump and compare.")
+@click.option("--url", default=None, help="Cluster name or RPC URL for --address.")
+def verify(
+    program: Path | None,
+    left: Path | None,
+    right: Path | None,
+    dump_path: Path | None,
+    address: str | None,
+    url: str | None,
+) -> None:
+    """Compare sha256 hashes. Exit 3 on a mismatch."""
+    if left is not None and right is not None:
+        _emit(left, right)
+    if left is not None or right is not None:
+        click.echo("error: pass both --left and --right", err=True)
+        sys.exit(2)
+    if program is None or not program.is_file():
+        click.echo("error: pass two files, or a program plus --dump or --address", err=True)
+        sys.exit(2)
+    try:
+        built = build_program(program)
+    except OSError as os_error:
+        click.echo(f"error: cannot read {program}: {os_error}", err=True)
+        sys.exit(2)
+    except BuildFailed as failed:
+        for diagnostic in failed.diagnostics:
+            click.echo(diagnostic.render(), err=True)
+        sys.exit(1)
+    except PysolError as error:
+        click.echo(error.render(), err=True)
+        sys.exit(1)
+    if dump_path is not None:
+        _emit(built.so_path, dump_path)
+    if address is None:
+        click.echo("error: pass --dump or --address to compare a build", err=True)
+        sys.exit(2)
+    import shutil
+
+    if shutil.which("solana") is None:
+        click.echo("error: solana CLI not found", err=True)
+        sys.exit(1)
+    with tempfile.TemporaryDirectory(prefix="pythsol-verify-") as tmp:
+        dest = Path(tmp) / "chain.so"
+        argv = dump_argv(address, resolve_url(url), dest)
+        click.echo(" ".join(argv))
+        completed = subprocess.run(argv, check=False)
+        if completed.returncode != 0 or not dest.is_file():
+            click.echo("error: solana program dump failed", err=True)
+            sys.exit(1)
+        _emit(built.so_path, dest)