pythsol 0.1.0__py3-none-any.whl

pythsol/cli/commands/check.py

@@ -0,0 +1,54 @@
+"""`pythsol check PROGRAM.py` — run the front-end and report diagnostics."""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+import click
+
+from pythsol.compiler.front import check_source
+from pythsol.compiler.modules import read_sibling_modules
+
+
+@click.command(name="check")
+@click.argument(
+    "program",
+    metavar="PROGRAM.py",
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+)
+@click.option(
+    "--json",
+    "as_json",
+    is_flag=True,
+    default=False,
+    help="Emit machine-readable JSON diagnostics.",
+)
+def check(program: Path, as_json: bool) -> None:
+    """Type-check a program with the PythSol front-end (no SBF toolchain)."""
+    try:
+        source = program.read_text(encoding="utf-8", errors="replace")
+        modules, module_files = read_sibling_modules(program)
+    except OSError as err:
+        click.echo(f"error: cannot read {program}: {err}", err=True)
+        sys.exit(2)
+    diagnostics = check_source(
+        source,
+        file=str(program),
+        modules=modules,
+        module_files=module_files,
+    )
+    diagnostics.sort(key=lambda d: (d.file, d.line, d.col, d.code))
+    if as_json:
+        payload = {
+            "ok": not diagnostics,
+            "diagnostics": [d.as_dict() for d in diagnostics],
+        }
+        click.echo(json.dumps(payload, indent=2))
+    elif diagnostics:
+        for diag in diagnostics:
+            click.echo(diag.render())
+    else:
+        click.echo(f"check: {program} - no problems found")
+    sys.exit(0 if not diagnostics else 1)

pythsol/cli/commands/client_cmd.py

@@ -0,0 +1,97 @@
+"""`pythsol client` and `pythsol cpi` — write a solders client.
+
+A ``.py`` program is compiled with the front-end (no clang) and rendered from
+the model. A ``.json`` IDL is rendered from the document. Neither output
+imports the compiler.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+import click
+
+from pythsol.client.from_idl import IdlClientError, render_client_from_idl
+from pythsol.client.gen import render_client
+from pythsol.compiler.modules import read_sibling_modules
+from pythsol.compiler.pipeline import emit_program
+
+_CPI_BANNER = (
+    "# Off-chain instruction builders for CPI into this program.\n"
+    "# PythSol does not lower a generic on-chain invoke. Call these from a client.\n"
+)
+
+
+def render_client_source(source: Path, *, address: str | None, cpi: bool) -> str:
+    """Return client source for a program or an IDL file."""
+    if source.suffix.lower() == ".json":
+        try:
+            payload = json.loads(source.read_text(encoding="utf-8"))
+        except json.JSONDecodeError as exc:
+            raise click.ClickException(f"invalid JSON: {exc}") from exc
+        if not isinstance(payload, dict):
+            raise click.ClickException("IDL JSON must be an object")
+        try:
+            text = render_client_from_idl(payload, address=address)
+        except IdlClientError as exc:
+            raise click.ClickException(str(exc)) from exc
+    else:
+        try:
+            source_text = source.read_text(encoding="utf-8", errors="replace")
+            modules, module_files = read_sibling_modules(source)
+        except OSError as exc:
+            raise click.ClickException(f"cannot read {source}: {exc}") from exc
+        generated = emit_program(
+            source_text,
+            source,
+            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)
+            raise SystemExit(1)
+        text = render_client(generated.generated)
+        if address:
+            needle = f"PROGRAM_NAME = {generated.generated.snake_name!r}\n"
+            insert = needle + f"PROGRAM_ID = {address!r}\n"
+            if needle in text:
+                text = text.replace(needle, insert, 1)
+            else:
+                text = f"PROGRAM_ID = {address!r}\n" + text
+    if cpi:
+        text = _CPI_BANNER + text
+    return text
+
+
+def _write(text: str, out: Path | None) -> None:
+    if out is None:
+        click.echo(text, nl=False)
+        return
+    out.parent.mkdir(parents=True, exist_ok=True)
+    out.write_text(text, encoding="utf-8", newline="\n")
+    click.echo(f"wrote {out}")
+
+
+@click.command(name="client")
+@click.argument("source", 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", default=None, help="Optional program id constant.")
+def client_cmd(source: Path, out: Path | None, address: str | None) -> None:
+    """Generate a solders client from a program or an IDL JSON file."""
+    text = render_client_source(source, address=address, cpi=False)
+    _write(text, out)
+    sys.exit(0)
+
+
+@click.command(name="cpi")
+@click.argument("source", 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", default=None, help="Optional program id constant.")
+def cpi_cmd(source: Path, out: Path | None, address: str | None) -> None:
+    """Generate off-chain CPI builders from a program or an IDL JSON file."""
+    text = render_client_source(source, address=address, cpi=True)
+    _write(text, out)
+    sys.exit(0)

pythsol/cli/commands/deploy.py

@@ -0,0 +1,103 @@
+"""`pythsol deploy` — build, then `solana program deploy`.
+
+``--dry-run`` prints the command and does not run it. Mainnet requires
+``--yes``.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+
+import click
+
+from pythsol.cli.cluster import is_mainnet, resolve_url
+from pythsol.cli.commands.build import BuildFailed, build_program
+from pythsol.compiler.diagnostics import PysolError
+from pythsol.compiler.toolchain import default_solana_keypair
+
+#: Lamports per program-data byte, the figure the TRD cites for a rent estimate.
+_LAMPORTS_PER_BYTE = 6960
+
+
+def deploy_argv(
+    so: Path,
+    url: str,
+    *,
+    keypair: Path | None,
+    program_keypair: Path | None,
+) -> list[str]:
+    """The ``solana program deploy`` invocation for this artifact."""
+    argv = ["solana", "program", "deploy", str(so), "--url", url]
+    if keypair is not None:
+        argv.extend(["--keypair", str(keypair)])
+    if program_keypair is not None:
+        argv.extend(["--program-id", str(program_keypair)])
+    return argv
+
+
+@click.command(name="deploy")
+@click.argument(
+    "program",
+    required=False,
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+)
+@click.option("--so", "so_path", type=click.Path(exists=True, dir_okay=False, path_type=Path))
+@click.option("--url", default=None, help="Cluster name or RPC URL. Default: devnet.")
+@click.option("--keypair", type=click.Path(dir_okay=False, path_type=Path), default=None)
+@click.option("--program-keypair", type=click.Path(dir_okay=False, path_type=Path), default=None)
+@click.option("--dry-run", is_flag=True, help="Print the deploy command and do not run it.")
+@click.option("--yes", is_flag=True, help="Required for mainnet.")
+def deploy(
+    program: Path | None,
+    so_path: Path | None,
+    url: str | None,
+    keypair: Path | None,
+    program_keypair: Path | None,
+    dry_run: bool,
+    yes: bool,
+) -> None:
+    """Build (unless ``--so`` is set) and deploy with the Solana CLI."""
+    cluster = resolve_url(url)
+    if is_mainnet(cluster) and not yes:
+        click.echo("error: mainnet deploy requires --yes", err=True)
+        sys.exit(1)
+    if so_path is None:
+        if program is None:
+            click.echo("error: pass a program or --so", 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)
+        so_path = built.so_path
+    size = so_path.stat().st_size
+    rent = size * _LAMPORTS_PER_BYTE
+    payer = keypair or default_solana_keypair()
+    argv = deploy_argv(so_path, cluster, keypair=payer, program_keypair=program_keypair)
+    click.echo(f"program bytes: {size}")
+    click.echo(f"estimated rent: {rent / 1_000_000_000:.6f} SOL (program data only)")
+    click.echo(" ".join(argv))
+    if dry_run:
+        sys.exit(0)
+    if shutil_which("solana") is None:
+        click.echo("error: solana CLI not found", err=True)
+        sys.exit(1)
+    completed = subprocess.run(argv, check=False)
+    sys.exit(int(completed.returncode))
+
+
+def shutil_which(name: str) -> str | None:
+    """Indirection so tests can replace the lookup."""
+    import shutil
+
+    return shutil.which(name)

pythsol/cli/commands/docs_cmd.py

@@ -0,0 +1,62 @@
+"""`pythsol docs` — print the offline reference."""
+
+from __future__ import annotations
+
+import sys
+import webbrowser
+from pathlib import Path
+
+import click
+
+_REFERENCE = """\
+PythSol offline reference
+
+  pythsol check PROGRAM.py     type-check (no clang)
+  pythsol build PROGRAM.py     native SBF .so, IDL, client, manifest
+  pythsol test                 build, then pytest on LiteSVM
+  pythsol init DIR --template counter|ledger|vault|escrow
+  pythsol idl PROGRAM.py       IDL only
+  pythsol client PROGRAM.py -o client.py
+  pythsol client program.json -o client.py
+  pythsol port program.json -o sketch.py
+  pythsol deploy --dry-run     print `solana program deploy` (mainnet needs --yes)
+  pythsol faucet --amount 1    devnet airdrop (mainnet refused)
+  pythsol wallet new --outfile id.json
+  pythsol verify --left a.so --right b.so
+  pythsol profile --logs run.log
+  pythsol idl-publish --address <ID> --dry-run
+  pythsol cpi PROGRAM.py -o cpi.py
+  pythsol serve                local playground on 127.0.0.1:8765
+                               check, emit, and compile (.so if clang is installed)
+
+A second build of the same program prints `cache hit (skipped clang)`.
+Tests use the fixtures svm, program, payer, accounts, and send.
+Vec[T, N] is a fixed capacity. A data enum is `Name: u64` with the payload reserved.
+Vec[T] without N is rejected. The hosted Pyodide playground is not in this
+build; `pythsol serve` checks, emits, and compiles on your machine.
+"""
+
+
+def _repo_doc() -> Path | None:
+    cwd = Path.cwd() / "docs" / "architecture.md"
+    if cwd.is_file():
+        return cwd
+    here = Path(__file__).resolve()
+    for parent in here.parents:
+        candidate = parent / "docs" / "architecture.md"
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+@click.command(name="docs")
+@click.option("--open", "open_browser", is_flag=True, help="Open architecture.md if it is on disk.")
+def docs(open_browser: bool) -> None:
+    """Print the offline command reference."""
+    click.echo(_REFERENCE, nl=False)
+    found = _repo_doc()
+    if found is not None:
+        click.echo(f"architecture: {found}")
+        if open_browser:
+            webbrowser.open(found.as_uri())
+    sys.exit(0)

pythsol/cli/commands/doctor.py

@@ -0,0 +1,211 @@
+"""`pythsol doctor` — diagnose the local environment.
+
+Checks are read-only and side-effect free. Private keys are never read or
+printed: we only stat the keypair file to see whether it exists (TR-SEC-01).
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+from urllib.request import Request, urlopen  # nosec B310 — only ever hits an opted-in RPC URL
+
+import click
+
+from pythsol.compiler import toolchain
+from pythsol.compiler.diagnostics import PysolError
+
+#: Default RPC endpoint; `doctor` only does a HEAD /
+DEFAULT_RPC_URL = "https://api.devnet.solana.com"
+
+#: Standard CLI fix command per missing check (TRD §7.2 doctor).
+SOLANA_API_INSTALL_CMD = 'sh -c "$(curl -sSfL https://release.anza.xyz/stable/install)"'
+PLATFORM_TOOLS_INSTALL_CMD = (
+    "solana-install update   # installs Agave + platform-tools (clang/lld) under ~/.cache/solana"
+)
+KEYPAIR_GEN_CMD = "solana-keygen new --no-bip39-passphrase"
+
+
+@dataclass(frozen=True)
+class CheckResult:
+    """One recorded ✓ / ✗ line of `pythsol doctor`."""
+
+    name: str
+    ok: bool
+    detail: str
+    fix_cmd: str | None = None
+
+    def render(self) -> str:
+        mark = "✓" if self.ok else "✗"
+        body = f"{mark} {self.name}"
+        if self.detail:
+            body = f"{body} {self.detail}" if self.ok else f"{body} ({self.detail})"
+        if not self.ok and self.fix_cmd:
+            body = f"{body}\n  → fix: {self.fix_cmd}"
+        return body
+
+    def to_json(self) -> dict[str, Any]:
+        return {"name": self.name, "ok": self.ok, "detail": self.detail, "fix_cmd": self.fix_cmd}
+
+
+@dataclass
+class DoctorReport:
+    checks: list[CheckResult] = field(default_factory=list)
+
+    def add(self, res: CheckResult) -> None:
+        self.checks.append(res)
+
+    @property
+    def ok(self) -> bool:
+        return all(r.ok for r in self.checks)
+
+    def render(self) -> str:
+        return "\n".join(r.render() for r in self.checks)
+
+    def to_json(self) -> dict[str, Any]:
+        return {"ok": self.ok, "checks": [r.to_json() for r in self.checks]}
+
+
+# ---------------------------------------------------------------------------
+# Individual checks (kept small so tests can stub each one)
+# ---------------------------------------------------------------------------
+
+
+def check_python_version() -> CheckResult:
+    version = f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}"
+    ok = sys.version_info >= (3, 11) and sys.version_info < (3, 14)
+    fix = None if ok else "pipx install pythsol  # needs Python 3.11-3.13"
+    return CheckResult("Python", ok, version, fix)
+
+
+def check_platform_tools(sdk: str | None = None) -> CheckResult:
+    try:
+        tc = toolchain.locate_platform_tools(sdk)
+    except PysolError as err:
+        return CheckResult("platform-tools", False, err.message, PLATFORM_TOOLS_INSTALL_CMD)
+    if tc is None:
+        return CheckResult(
+            "platform-tools",
+            False,
+            "no Agave/Anza platform-tools with `sbf` clang found",
+            PLATFORM_TOOLS_INSTALL_CMD,
+        )
+    return CheckResult("platform-tools", True, tc.describe(), None)
+
+
+def check_clang_lld(tc: toolchain.ToolchainPaths) -> CheckResult:
+    """Make sure the located clang/lld actually respond to `--version`."""
+    ok = _query_ok(str(tc.clang), ["--version"]) and _query_ok(str(tc.lld), ["--version"])
+    detail = "clang and ld.lld answer --version" if ok else "clang or ld.lld failed to run"
+    fix = None if ok else PLATFORM_TOOLS_INSTALL_CMD
+    return CheckResult("clang/lld sanity", ok, detail, fix)
+
+
+def _query_ok(binary: str, args: list[str], timeout_s: float = 30.0) -> bool:
+    try:
+        proc = subprocess.run(
+            [binary, *args],
+            capture_output=True,
+            text=True,
+            check=False,
+            timeout=timeout_s,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return False
+    return proc.returncode == 0
+
+
+def check_solana_cli() -> CheckResult:
+    path = toolchain.find_solana_cli()
+    ok = path is not None
+    detail = f"solana at {path}" if ok else "not found on PATH"
+    return CheckResult("solana CLI", ok, detail, None if ok else SOLANA_API_INSTALL_CMD)
+
+
+def check_cargo_build_sbf() -> CheckResult:
+    path = toolchain.find_cargo_build_sbf()
+    ok = path is not None
+    detail = f"cargo-build-sbf at {path}" if ok else "not found on PATH"
+    return CheckResult("cargo-build-sbf", ok, detail, None if ok else PLATFORM_TOOLS_INSTALL_CMD)
+
+
+def check_keypair(path: str | None = None) -> CheckResult:
+    """The keypair file must exist; we never read or log its contents."""
+    p = toolchain.default_solana_keypair() if path is None else Path(path).expanduser()
+    ok = p.is_file()
+    detail = str(p) if ok else f"not found at {p}"
+    fix = None if ok else KEYPAIR_GEN_CMD
+    return CheckResult("solana keypair file", ok, detail, fix)
+
+
+def check_rpc(
+    url: str | None = None,
+    *,
+    enabled: bool = True,
+    timeout_s: float = 5.0,
+) -> CheckResult:
+    """HEAD the RPC health endpoint. Never sends or stores a key."""
+    if not enabled:
+        return CheckResult("RPC reachable", True, "skipped (--no-rpc)", None)
+    target = (url or DEFAULT_RPC_URL).rstrip("/")
+    try:
+        with urlopen(
+            Request(target, method="HEAD", headers={"User-Agent": "pythsol-doctor/0.1"}),
+            timeout=timeout_s,
+        ) as resp:
+            status = getattr(resp, "status", resp.getcode())
+            ok = 200 <= int(status) < 500
+        detail = target
+    except Exception as err:
+        return CheckResult("RPC reachable", False, f"{target}: {err}", None)
+    return CheckResult("RPC reachable", ok, detail, None)
+
+
+def run_doctor(
+    *,
+    rpc: str | None = None,
+    do_rpc: bool = True,
+    sdk: str | None = None,
+) -> DoctorReport:
+    """Build the full report (pure, no I/O beyond what is stated)."""
+    report = DoctorReport()
+    report.add(check_python_version())
+    tc_ok = False
+    try:
+        tc = toolchain.locate_platform_tools(sdk)
+        tc_ok = tc is not None and tc.clang.is_file()
+    except PysolError:
+        tc_ok = False
+        tc = None
+    report.add(check_platform_tools(sdk))
+    if tc_ok and tc is not None:
+        report.add(check_clang_lld(tc))
+    report.add(check_solana_cli())
+    report.add(check_cargo_build_sbf())
+    report.add(check_keypair())
+    report.add(check_rpc(rpc, enabled=do_rpc))
+    return report
+
+
+@click.command(name="doctor")
+@click.option("--json", "as_json", is_flag=True, help="Emit machine-readable JSON.")
+@click.option("--rpc", default=None, metavar="URL", help="Override RPC URL.")
+@click.option("--no-rpc", is_flag=True, default=False, help="Skip the RPC network probe.")
+@click.option("--sdk", default=None, metavar="DIR", help="Override platform-tools discovery.")
+def doctor(
+    as_json: bool,
+    rpc: str | None,
+    no_rpc: bool,
+    sdk: str | None,
+) -> None:
+    """Diagnose the local environment (toolchain, solana CLI, keypair, RPC)."""
+    report = run_doctor(rpc=rpc, do_rpc=not no_rpc, sdk=sdk)
+    if as_json:
+        click.echo(json.dumps(report.to_json(), indent=2))
+    else:
+        click.echo(report.render())
+    sys.exit(0 if report.ok else 1)

pythsol/cli/commands/emit_c.py

@@ -0,0 +1,69 @@
+"""`pythsol emit-c PROGRAM.py` — print or write the generated C."""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+import click
+
+from pythsol.compiler.modules import read_sibling_modules
+from pythsol.compiler.pipeline import emit_program
+
+
+@click.command(name="emit-c")
+@click.argument(
+    "program",
+    metavar="PROGRAM.py",
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+)
+@click.option(
+    "--out",
+    type=click.Path(dir_okay=False, writable=True, path_type=Path),
+    default=None,
+    help="Write the C file here instead of printing it.",
+)
+@click.option(
+    "--json",
+    "as_json",
+    is_flag=True,
+    default=False,
+    help="Emit machine-readable diagnostics on stdout.",
+)
+def emit_c(program: Path, out: Path | None, as_json: bool) -> None:
+    """Generate C from a PythSol program (no SBF toolchain needed)."""
+    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:
+        for diagnostic in generated.diagnostics:
+            click.echo(diagnostic.render(), err=True)
+        if as_json:
+            payload = {
+                "ok": False,
+                "diagnostics": [d.as_dict() for d in generated.diagnostics],
+            }
+            click.echo(json.dumps(payload, indent=2))
+        sys.exit(1)
+
+    if as_json:
+        click.echo(json.dumps({"ok": True, "diagnostics": []}, indent=2))
+
+    if out is None:
+        click.echo(generated.c_text)
+    else:
+        out.parent.mkdir(parents=True, exist_ok=True)
+        out.write_text(generated.c_text, encoding="utf-8", newline="\n")
+        click.echo(f"emit-c: wrote {out}")
+    sys.exit(0)

pythsol/cli/commands/faucet.py

@@ -0,0 +1,66 @@
+"""`pythsol faucet` — request devnet SOL. Mainnet is refused."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import click
+
+from pythsol.cli.cluster import is_mainnet, resolve_url
+from pythsol.cli.rpc import RpcError, post_json
+from pythsol.compiler.toolchain import default_solana_keypair
+
+_LAMPORTS = 1_000_000_000
+_MAX_SOL = 5.0
+
+
+def _pubkey_from_file(path: Path) -> str:
+    try:
+        from solders.keypair import Keypair
+    except ImportError:
+        click.echo(
+            "error: solders is required to read a keypair. pip install 'pythsol[test]'",
+            err=True,
+        )
+        sys.exit(1)
+    return str(Keypair.from_json(path.read_text(encoding="utf-8")).pubkey())
+
+
+@click.command(name="faucet")
+@click.option("--amount", default=1.0, show_default=True, help="SOL to request (max 5).")
+@click.option("--url", default=None, help="Cluster name or RPC URL. Default: devnet.")
+@click.option("--pubkey", default=None, help="Base58 address. Default: the local keypair.")
+@click.option(
+    "--keypair",
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+    default=None,
+    help="Keypair file whose address receives the airdrop.",
+)
+def faucet(amount: float, url: str | None, pubkey: str | None, keypair: Path | None) -> None:
+    """Request an airdrop. Devnet rate limits return a faucet link."""
+    cluster = resolve_url(url)
+    if is_mainnet(cluster):
+        click.echo("error: faucet refuses mainnet", err=True)
+        sys.exit(1)
+    if amount <= 0 or amount > _MAX_SOL:
+        click.echo(f"error: --amount must be between 0 and {_MAX_SOL:g} SOL", err=True)
+        sys.exit(2)
+    if pubkey is None:
+        path = keypair or default_solana_keypair()
+        if not path.is_file():
+            click.echo(f"error: keypair not found at {path}", err=True)
+            sys.exit(1)
+        pubkey = _pubkey_from_file(path)
+    lamports = round(amount * _LAMPORTS)
+    try:
+        body = post_json(cluster, "requestAirdrop", [pubkey, lamports])
+    except RpcError as exc:
+        message = str(exc)
+        click.echo(f"error: {message}", err=True)
+        if "rate" in message.lower() or "429" in message or "limit" in message.lower():
+            click.echo("Rate-limited. Use https://faucet.solana.com", err=True)
+        sys.exit(1)
+    signature = body.get("result")
+    click.echo(f"Airdropped {amount:g} SOL (sig {signature}).")
+    sys.exit(0)