zigpeek 0.3.0__py3-none-any.whl

zigpeek/builtins.py

@@ -0,0 +1,148 @@
+"""Port of mcp/extract-builtin-functions.ts and the ranking from mcp/tools.ts.
+
+Parses Zig's langref HTML into a list of BuiltinFunction records, then ranks
+those records by relevance to a query string.
+"""
+
+import re
+from dataclasses import dataclass
+
+from bs4 import BeautifulSoup, NavigableString, Tag
+
+
+@dataclass
+class BuiltinFunction:
+    func: str
+    signature: str
+    docs: str
+
+
+_WS_RE = re.compile(r"\s+")
+_BLANK_LINES_RE = re.compile(r"\n{2,}")
+_TRAILING_NEWLINES_RE = re.compile(r"\n+$")
+
+
+def _rewrite_link(text: str, href: str, link_base_url: str | None) -> str:
+    if href.startswith("#") and link_base_url:
+        return f"[{text}]({link_base_url}{href})"
+    return f"[{text}]({href})"
+
+
+def _inline_text(tag: Tag, link_base_url: str | None) -> str:
+    cloned = BeautifulSoup(str(tag), "lxml").find()
+    if cloned is None:
+        return ""
+
+    for a in list(cloned.find_all("a")):
+        href = a.get("href", "")
+        text = a.get_text()
+        a.replace_with(NavigableString(_rewrite_link(text, href, link_base_url)))
+
+    for code in list(cloned.find_all("code")):
+        code.replace_with(NavigableString(f"`{code.get_text()}`"))
+
+    return _WS_RE.sub(" ", cloned.get_text()).strip()
+
+
+def _next_sibling_tag(tag: Tag) -> Tag | None:
+    sib = tag.next_sibling
+    while sib is not None and not isinstance(sib, Tag):
+        sib = sib.next_sibling
+    return sib
+
+
+def parse_builtin_functions_html(
+    html: str,
+    link_base_url: str | None,
+) -> list[BuiltinFunction]:
+    soup = BeautifulSoup(html, "lxml")
+    section = soup.find("h2", id="Builtin-Functions")
+    if section is None:
+        raise ValueError("Could not find Builtin Functions section in HTML")
+
+    builtins: list[BuiltinFunction] = []
+    current = _next_sibling_tag(section)
+
+    while current is not None and current.name != "h2":
+        if current.name == "h3" and current.has_attr("id"):
+            first_a = current.find("a")
+            func = first_a.get_text() if first_a is not None else ""
+            if func.startswith("@"):
+                pre = _next_sibling_tag(current)
+                signature = ""
+                desc_start = pre
+                if pre is not None and pre.name == "pre":
+                    signature = pre.get_text().strip()
+                    desc_start = _next_sibling_tag(pre)
+
+                description_parts: list[str] = []
+                desc_current = desc_start
+                while desc_current is not None and desc_current.name not in ("h2", "h3"):
+                    if desc_current.name == "p":
+                        description_parts.append(
+                            _inline_text(desc_current, link_base_url)
+                        )
+                    elif desc_current.name == "ul":
+                        for li in desc_current.find_all("li", recursive=False):
+                            li_text = _inline_text(li, link_base_url)
+                            if li_text:
+                                description_parts.append(f"* {li_text}")
+                    elif desc_current.name == "figure":
+                        figcaption = ""
+                        cap_el = desc_current.find("figcaption")
+                        if cap_el is not None:
+                            figcaption = cap_el.get_text().strip()
+                        pre_el = desc_current.find("pre")
+                        code = pre_el.get_text() if pre_el is not None else ""
+                        lang = ""
+                        label = ""
+                        if figcaption:
+                            label = f"**{figcaption}**\n"
+                            if figcaption.endswith(".zig"):
+                                lang = "zig"
+                            elif "shell" in figcaption.lower():
+                                lang = "sh"
+                        if code:
+                            block = f"{label}\n```{lang}\n{code.strip()}\n```"
+                            description_parts.append(block.strip())
+                    desc_current = _next_sibling_tag(desc_current)
+
+                docs = "\n".join(description_parts)
+                docs = _BLANK_LINES_RE.sub("\n", docs)
+                docs = _TRAILING_NEWLINES_RE.sub("", docs)
+                if docs.lower().endswith("see also:"):
+                    docs = docs[: -len("see also:")].strip()
+
+                builtins.append(
+                    BuiltinFunction(func=func, signature=signature, docs=docs)
+                )
+
+        current = _next_sibling_tag(current)
+
+    return builtins
+
+
+def rank_builtin_functions(
+    functions: list[BuiltinFunction],
+    query: str,
+) -> list[BuiltinFunction]:
+    q = query.lower().strip()
+    if not q:
+        return []
+
+    scored: list[tuple[int, BuiltinFunction]] = []
+    for fn in functions:
+        f_lower = fn.func.lower()
+        score = 0
+        if f_lower == q:
+            score += 1000
+        elif f_lower.startswith(q):
+            score += 500
+        elif q in f_lower:
+            score += 300
+        if score > 0:
+            score += max(0, 50 - len(fn.func))
+            scored.append((score, fn))
+
+    scored.sort(key=lambda pair: pair[0], reverse=True)
+    return [fn for _, fn in scored]

zigpeek/cli.py

@@ -0,0 +1,320 @@
+"""argparse entrypoint for `zigpeek`. Five subcommands matching the MCP tools
+plus a `prefetch` helper for offline-first workflows and a `batch` runner
+that amortizes Python+wasmtime startup across many lookups.
+
+Exit codes:
+  0 — success (markdown on stdout)
+  1 — bad input or "not found" (message on stderr)
+  2 — network or cache failure (message on stderr)
+
+For `batch`, the exit code is the maximum exit code seen across the
+input lines, so a single not-found does not mask a later cache error.
+"""
+
+import argparse
+import functools
+import io
+import shlex
+import sys
+from importlib.resources import files
+from pathlib import Path
+
+import httpx
+import wasmtime
+
+from zigpeek import builtins as builtins_mod
+from zigpeek.fetch import (
+    fetch_langref_html,
+    fetch_sources_tar,
+    langref_url,
+    prefetch as fetch_prefetch,
+)
+from zigpeek.stdlib import render_get_item, render_search
+from zigpeek.version import resolve_version
+from zigpeek.wasm import WasmStd
+
+_BATCH_DISALLOWED = frozenset({"batch", "prefetch"})
+
+
+def _err(msg: str, code: int) -> int:
+    print(msg, file=sys.stderr)
+    return code
+
+
+def _wrap_errors(fn):
+    """Translate the two exception families every command shares into the
+    documented exit codes. Keeps the per-command bodies focused on the
+    happy path."""
+
+    @functools.wraps(fn)
+    def inner(args: argparse.Namespace) -> int:
+        try:
+            return fn(args)
+        except (httpx.HTTPError, OSError) as e:
+            return _err(f"network/cache error: {e}", 2)
+        except (wasmtime.WasmtimeError, RuntimeError) as e:
+            return _err(
+                f"data error: {e}\n"
+                "The cached or bundled sources.tar may be corrupt. "
+                "Try `zigpeek prefetch --refresh`.",
+                2,
+            )
+
+    return inner
+
+
+def _vendor_wasm_bytes() -> bytes:
+    wasm = files("zigpeek").joinpath("_vendor", "main.wasm")
+    if not wasm.is_file():
+        raise FileNotFoundError(
+            "main.wasm not found inside the zigpeek package "
+            "(expected at zigpeek/_vendor/main.wasm). "
+            "See vendor/PROVENANCE.md for build instructions."
+        )
+    return wasm.read_bytes()
+
+
+@functools.lru_cache(maxsize=4)
+def _load_std(version: str, refresh: bool, cache_dir: str | None) -> WasmStd:
+    sources = fetch_sources_tar(version, refresh=refresh, cache_dir=cache_dir)
+    return WasmStd(_vendor_wasm_bytes(), sources)
+
+
+@functools.lru_cache(maxsize=4)
+def _load_builtins(
+    version: str, refresh: bool, cache_dir: str | None
+) -> tuple[list[builtins_mod.BuiltinFunction], str]:
+    html = fetch_langref_html(version, refresh=refresh, cache_dir=cache_dir)
+    base = langref_url(version)
+    return builtins_mod.parse_builtin_functions_html(html, link_base_url=base), base
+
+
+@_wrap_errors
+def _cmd_search(args: argparse.Namespace) -> int:
+    if not args.query:
+        return _err("query cannot be empty", 1)
+    version = resolve_version(args.version)
+    std = _load_std(version, args.refresh, args.cache_dir)
+    sys.stdout.write(render_search(std, args.query, limit=args.limit))
+    sys.stdout.write("\n")
+    return 0
+
+
+@_wrap_errors
+def _cmd_get(args: argparse.Namespace) -> int:
+    if not args.fqn:
+        return _err("fully-qualified name cannot be empty", 1)
+    version = resolve_version(args.version)
+    std = _load_std(version, args.refresh, args.cache_dir)
+    md = render_get_item(std, args.fqn, get_source_file=args.source_file)
+    if md.startswith("# Error"):
+        print(md, file=sys.stderr)
+        return 1
+    sys.stdout.write(md)
+    sys.stdout.write("\n")
+    return 0
+
+
+@_wrap_errors
+def _cmd_builtins_list(args: argparse.Namespace) -> int:
+    version = resolve_version(args.version)
+    fns, base = _load_builtins(version, args.refresh, args.cache_dir)
+    lines = "\n".join(f"- {fn.signature}" for fn in fns)
+    sys.stdout.write(
+        f"Available {len(fns)} builtin functions "
+        f"(full docs: {base}):\n\n{lines}\n"
+    )
+    return 0
+
+
+@_wrap_errors
+def _cmd_builtins_get(args: argparse.Namespace) -> int:
+    if not args.query:
+        return _err("query cannot be empty", 1)
+    version = resolve_version(args.version)
+    fns, _ = _load_builtins(version, args.refresh, args.cache_dir)
+    ranked = builtins_mod.rank_builtin_functions(fns, args.query)
+    if not ranked:
+        return _err(
+            f'No builtin functions found matching "{args.query}". '
+            "Try `zigpeek builtins list` to see all functions.",
+            1,
+        )
+    chunks = [
+        f"**{fn.func}**\n```zig\n{fn.signature}\n```\n\n{fn.docs}"
+        for fn in ranked
+    ]
+    body = "\n\n---\n\n".join(chunks)
+    if len(ranked) == 1:
+        sys.stdout.write(body + "\n")
+    else:
+        sys.stdout.write(f"Found {len(ranked)} matching functions:\n\n{body}\n")
+    return 0
+
+
+@_wrap_errors
+def _cmd_prefetch(args: argparse.Namespace) -> int:
+    version = resolve_version(args.version)
+    paths = fetch_prefetch(version, refresh=args.refresh, cache_dir=args.cache_dir)
+    sys.stdout.write(
+        f"Prefetched docs for Zig {version}:\n"
+        f"  sources.tar  → {paths['sources.tar']}\n"
+        f"  langref.html → {paths['langref.html']}\n"
+    )
+    return 0
+
+
+def _read_batch_lines(args: argparse.Namespace) -> list[str]:
+    if args.file:
+        text = args.file.read_text(encoding="utf-8")
+    else:
+        text = sys.stdin.read()
+    return text.splitlines()
+
+
+def _run_captured(parser: argparse.ArgumentParser, tokens: list[str]) -> tuple[
+    int, str, str
+]:
+    """Parse + dispatch a batch line, capturing its stdout/stderr so the
+    parent batch loop can frame each command's output."""
+    out, err = io.StringIO(), io.StringIO()
+    old_out, old_err = sys.stdout, sys.stderr
+    sys.stdout, sys.stderr = out, err
+    try:
+        try:
+            sub_args = parser.parse_args(tokens)
+        except SystemExit as se:
+            # argparse exits 2 for usage errors; map to 1 (bad input) so the
+            # batch exit code reserves 2 for real cache/network failures.
+            code = 0 if se.code == 0 else 1
+            return code, out.getvalue(), err.getvalue()
+        code = sub_args.func(sub_args)
+    finally:
+        sys.stdout, sys.stderr = old_out, old_err
+    return code, out.getvalue(), err.getvalue()
+
+
+def _cmd_batch(args: argparse.Namespace) -> int:
+    parser = build_parser()
+    worst = 0
+    first = True
+    for raw in _read_batch_lines(args):
+        line = raw.strip()
+        if not line or line.startswith("#"):
+            continue
+        try:
+            tokens = shlex.split(line)
+        except ValueError as e:
+            if not first:
+                sys.stdout.write("\n")
+            sys.stdout.write(f"===> {line}\n# Error\nunparseable line: {e}\n")
+            worst = max(worst, 1)
+            first = False
+            continue
+        if not tokens:
+            continue
+        if tokens[0] in _BATCH_DISALLOWED:
+            if not first:
+                sys.stdout.write("\n")
+            sys.stdout.write(
+                f"===> {line}\n# Error\n"
+                f"`{tokens[0]}` is not allowed inside batch.\n"
+            )
+            worst = max(worst, 1)
+            first = False
+            continue
+        code, out, err = _run_captured(parser, tokens)
+        if not first:
+            sys.stdout.write("\n")
+        sys.stdout.write(f"===> {line}\n")
+        sys.stdout.write(out)
+        if err:
+            sys.stdout.write(err)
+        worst = max(worst, code)
+        first = False
+    return worst
+
+
+def _add_common(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--version", default=None, help="Zig version (default: 0.16.0)")
+    p.add_argument(
+        "--refresh",
+        action="store_true",
+        help="Force re-download of cached resources",
+    )
+    p.add_argument(
+        "--cache-dir",
+        default=None,
+        help=(
+            "Cache directory root (overrides ZIGPEEK_CACHE_DIR; "
+            "default: /tmp/zigpeek-cache)"
+        ),
+    )
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="zigpeek", description="Zig 0.16 docs CLI")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    p_search = sub.add_parser("search", help="Search the standard library")
+    p_search.add_argument("query")
+    p_search.add_argument("--limit", type=int, default=20)
+    _add_common(p_search)
+    p_search.set_defaults(func=_cmd_search)
+
+    p_get = sub.add_parser("get", help="Get docs for a fully-qualified stdlib name")
+    p_get.add_argument("fqn")
+    p_get.add_argument(
+        "--source-file",
+        action="store_true",
+        help="Return the entire source file for the item",
+    )
+    _add_common(p_get)
+    p_get.set_defaults(func=_cmd_get)
+
+    p_builtins = sub.add_parser("builtins", help="Builtin function lookups")
+    builtins_sub = p_builtins.add_subparsers(dest="builtins_cmd", required=True)
+
+    p_blist = builtins_sub.add_parser("list", help="List all builtin functions")
+    _add_common(p_blist)
+    p_blist.set_defaults(func=_cmd_builtins_list)
+
+    p_bget = builtins_sub.add_parser("get", help="Look up a builtin by name/keyword")
+    p_bget.add_argument("query")
+    _add_common(p_bget)
+    p_bget.set_defaults(func=_cmd_builtins_get)
+
+    p_pre = sub.add_parser(
+        "prefetch",
+        help="Download sources.tar + langref.html so other commands run offline",
+    )
+    _add_common(p_pre)
+    p_pre.set_defaults(func=_cmd_prefetch)
+
+    p_batch = sub.add_parser(
+        "batch",
+        help=(
+            "Run many lookups in one process; reads one command per line "
+            "from stdin (or -f FILE) and frames each output with `===> <cmd>`"
+        ),
+    )
+    p_batch.add_argument(
+        "-f",
+        "--file",
+        type=Path,
+        default=None,
+        help="Read commands from FILE instead of stdin",
+    )
+    p_batch.set_defaults(func=_cmd_batch)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

zigpeek/fetch.py

@@ -0,0 +1,103 @@
+import os
+from importlib.resources import files
+from pathlib import Path
+
+import httpx
+
+_CACHE_ENV = "ZIGPEEK_CACHE_DIR"
+_DEFAULT_CACHE_ROOT = Path("/tmp/zigpeek-cache")
+
+
+def sources_tar_url(zig_version: str) -> str:
+    return f"https://ziglang.org/documentation/{zig_version}/std/sources.tar"
+
+
+def langref_url(zig_version: str) -> str:
+    return f"https://ziglang.org/documentation/{zig_version}/"
+
+
+def cache_dir_for(zig_version: str, override: Path | str | None = None) -> Path:
+    if override is not None:
+        return Path(override) / zig_version
+    root = os.environ.get(_CACHE_ENV)
+    base = Path(root) if root else _DEFAULT_CACHE_ROOT
+    return base / zig_version
+
+
+def bundled_path_for(zig_version: str, filename: str) -> Path:
+    """Where a pre-bundled snapshot would live for a given version."""
+    return Path(str(files("zigpeek").joinpath("_data", zig_version, filename)))
+
+
+def _http_get_bytes(url: str) -> bytes:
+    with httpx.Client(follow_redirects=True, timeout=60.0) as client:
+        r = client.get(url)
+        r.raise_for_status()
+        return r.content
+
+
+def _read_or_fetch(
+    url: str,
+    cache_path: Path,
+    refresh: bool,
+    bundled: Path | None = None,
+) -> bytes:
+    if not refresh and bundled is not None and bundled.exists():
+        return bundled.read_bytes()
+    if not refresh and cache_path.exists():
+        return cache_path.read_bytes()
+    data = _http_get_bytes(url)
+    cache_path.parent.mkdir(parents=True, exist_ok=True)
+    cache_path.write_bytes(data)
+    return data
+
+
+def fetch_sources_tar(
+    zig_version: str,
+    refresh: bool = False,
+    cache_dir: Path | str | None = None,
+) -> bytes:
+    return _read_or_fetch(
+        sources_tar_url(zig_version),
+        cache_dir_for(zig_version, cache_dir) / "sources.tar",
+        refresh,
+        bundled=bundled_path_for(zig_version, "sources.tar"),
+    )
+
+
+def fetch_langref_html(
+    zig_version: str,
+    refresh: bool = False,
+    cache_dir: Path | str | None = None,
+) -> str:
+    data = _read_or_fetch(
+        langref_url(zig_version),
+        cache_dir_for(zig_version, cache_dir) / "langref.html",
+        refresh,
+        bundled=bundled_path_for(zig_version, "langref.html"),
+    )
+    return data.decode("utf-8")
+
+
+def prefetch(
+    zig_version: str,
+    refresh: bool = False,
+    cache_dir: Path | str | None = None,
+) -> dict[str, Path]:
+    """Populate the cache so subsequent reads are network-free.
+
+    Returns a mapping of {"sources.tar": path, "langref.html": path}
+    pointing at whichever location the read path will resolve to next
+    (bundled snapshot if present, otherwise cache).
+    """
+    fetch_sources_tar(zig_version, refresh=refresh, cache_dir=cache_dir)
+    fetch_langref_html(zig_version, refresh=refresh, cache_dir=cache_dir)
+    bundled_src = bundled_path_for(zig_version, "sources.tar")
+    bundled_lang = bundled_path_for(zig_version, "langref.html")
+    cache = cache_dir_for(zig_version, cache_dir)
+    return {
+        "sources.tar": bundled_src if bundled_src.exists() else cache / "sources.tar",
+        "langref.html": (
+            bundled_lang if bundled_lang.exists() else cache / "langref.html"
+        ),
+    }

zigpeek/stdlib.py

@@ -0,0 +1,324 @@
+"""Markdown rendering — port of ~/Documents/GitHub/zig-mcp/mcp/std.ts.
+
+Each function below mirrors a renderer in std.ts. Smoke tests catch
+structural drift; cosmetic whitespace differences are acceptable.
+"""
+
+from zigpeek.wasm import WasmStd
+
+CAT_NAMESPACE = 0
+CAT_CONTAINER = 1
+CAT_GLOBAL_VARIABLE = 2
+CAT_FUNCTION = 3
+CAT_PRIMITIVE = 4
+CAT_ERROR_SET = 5
+CAT_GLOBAL_CONST = 6
+CAT_ALIAS = 7
+CAT_TYPE = 8
+CAT_TYPE_TYPE = 9
+CAT_TYPE_FUNCTION = 10
+
+
+def render_search(std: WasmStd, query: str, limit: int = 20) -> str:
+    ignore_case = query.lower() == query
+    results = std.execute_query(query, ignore_case)
+
+    md = f'# Search Results\n\nQuery: "{query}"\n\n'
+    if results:
+        limited = results[:limit]
+        md += f"Found {len(results)} results (showing {len(limited)}):\n\n"
+        for match in limited:
+            md += f"- {std.fully_qualified_name(match)}\n"
+    else:
+        md += "No results found."
+    return md
+
+
+def render_get_item(std: WasmStd, name: str, get_source_file: bool = False) -> str:
+    decl_index = std.find_decl(name)
+    if decl_index is None:
+        return f'# Error\n\nDeclaration "{name}" not found.'
+
+    if get_source_file:
+        cur = decl_index
+        seen: set[int] = set()
+        while True:
+            cat = std.categorize_decl(cur, 0)
+            if cat != CAT_ALIAS or cur in seen:
+                break
+            seen.add(cur)
+            nxt = std.get_aliasee()
+            if nxt is None or nxt == cur:
+                break
+            cur = nxt
+
+        file_path = std.decl_file_path(cur)
+        if file_path:
+            file_decl = std.find_file_root(file_path)
+            if file_decl is not None:
+                return f"# {file_path}\n\n{std.decl_source_html(file_decl)}"
+        return f'# Error\n\nCould not find source file for "{name}".'
+
+    return _render_decl(std, decl_index)
+
+
+def _render_decl(std: WasmStd, decl_index: int) -> str:
+    current = decl_index
+    seen: set[int] = set()
+    while True:
+        category = std.categorize_decl(current, 0)
+        if category in (CAT_NAMESPACE, CAT_CONTAINER):
+            return _render_namespace(std, current)
+        if category in (
+            CAT_GLOBAL_VARIABLE,
+            CAT_PRIMITIVE,
+            CAT_GLOBAL_CONST,
+            CAT_TYPE,
+            CAT_TYPE_TYPE,
+        ):
+            return _render_global(std, current)
+        if category == CAT_FUNCTION:
+            return _render_function(std, current)
+        if category == CAT_TYPE_FUNCTION:
+            return _render_type_function(std, current)
+        if category == CAT_ERROR_SET:
+            return _render_error_set(std, current)
+        if category == CAT_ALIAS:
+            if current in seen:
+                return _render_not_found()
+            seen.add(current)
+            aliasee = std.get_aliasee()
+            if aliasee is None:
+                return _render_not_found()
+            current = aliasee
+            continue
+        raise RuntimeError(f"unrecognized category {category}")
+
+
+def _render_namespace(std: WasmStd, decl_index: int) -> str:
+    name = std.decl_category_name(decl_index)
+    md = f"# {name}\n\n"
+
+    docs = std.decl_docs_html(decl_index, False)
+    if docs:
+        md += docs + "\n\n"
+
+    members = std.namespace_members(decl_index, False)
+    fields = std.decl_fields(decl_index)
+    md += _render_namespace_md(std, decl_index, members, fields)
+    return md
+
+
+def _render_function(std: WasmStd, decl_index: int) -> str:
+    name = std.decl_category_name(decl_index)
+    md = f"# {name}\n"
+
+    docs = std.decl_docs_html(decl_index, False)
+    if docs:
+        md += "\n" + docs
+
+    proto = std.decl_fn_proto_html(decl_index, False)
+    if proto:
+        md += "\n\n## Function Signature\n\n" + proto
+
+    params = std.decl_params(decl_index)
+    if params:
+        md += "\n\n## Parameters\n"
+        for p in params:
+            md += "\n" + std.decl_param_html(decl_index, p)
+
+    err_set_node = std.fn_error_set(decl_index)
+    if err_set_node is not None:
+        base_decl = std.fn_error_set_decl(decl_index, err_set_node)
+        error_list = std.error_set_node_list(decl_index, err_set_node)
+        if error_list:
+            md += "\n\n## Errors\n"
+            for e in error_list:
+                md += "\n" + std.error_html(base_decl, e)
+
+    doctest = std.decl_doctest_html(decl_index)
+    if doctest:
+        md += "\n\n## Example Usage\n\n" + doctest
+
+    source = std.decl_source_html(decl_index)
+    if source:
+        md += "\n\n## Source Code\n\n" + source
+
+    return md
+
+
+def _render_global(std: WasmStd, decl_index: int) -> str:
+    name = std.decl_category_name(decl_index)
+    md = f"# {name}\n\n"
+
+    docs = std.decl_docs_html(decl_index, True)
+    if docs:
+        md += docs + "\n\n"
+
+    source = std.decl_source_html(decl_index)
+    if source:
+        md += "## Source Code\n\n" + source + "\n\n"
+
+    return md
+
+
+def _render_type_function(std: WasmStd, decl_index: int) -> str:
+    name = std.decl_category_name(decl_index)
+    md = f"# {name}\n\n"
+
+    docs = std.decl_docs_html(decl_index, False)
+    if docs:
+        md += docs + "\n\n"
+
+    params = std.decl_params(decl_index)
+    if params:
+        md += "## Parameters\n\n"
+        for p in params:
+            md += std.decl_param_html(decl_index, p) + "\n\n"
+
+    doctest = std.decl_doctest_html(decl_index)
+    if doctest:
+        md += "## Example Usage\n\n" + doctest + "\n\n"
+
+    members = std.type_fn_members(decl_index, False)
+    fields = std.type_fn_fields(decl_index)
+    if members or fields:
+        md += _render_namespace_md(std, decl_index, members, fields)
+    else:
+        source = std.decl_source_html(decl_index)
+        if source:
+            md += "## Source Code\n\n" + source + "\n\n"
+
+    return md
+
+
+def _render_error_set(std: WasmStd, decl_index: int) -> str:
+    name = std.decl_category_name(decl_index)
+    md = f"# {name}\n\n"
+
+    docs = std.decl_docs_html(decl_index, False)
+    if docs:
+        md += docs + "\n\n"
+
+    error_list = std.decl_error_set(decl_index)
+    if error_list:
+        md += "## Errors\n\n"
+        for e in error_list:
+            md += std.error_html(decl_index, e) + "\n\n"
+
+    return md
+
+
+def _render_not_found() -> str:
+    return "# Error\n\nDeclaration not found."
+
+
+def _render_namespace_md(
+    std: WasmStd,
+    base_decl: int,
+    members: list[int],
+    fields: list[int],
+) -> str:
+    types_list: list[tuple[int, int]] = []
+    namespaces_list: list[tuple[int, int]] = []
+    err_sets_list: list[tuple[int, int]] = []
+    fns_list: list[int] = []
+    vars_list: list[int] = []
+    vals_list: list[tuple[int, int]] = []
+
+    for original in members:
+        member = original
+        seen: set[int] = set()
+        while True:
+            cat = std.categorize_decl(member, 0)
+            if cat == CAT_NAMESPACE:
+                namespaces_list.append((original, member))
+            elif cat == CAT_CONTAINER:
+                types_list.append((original, member))
+            elif cat == CAT_GLOBAL_VARIABLE:
+                vars_list.append(member)
+            elif cat == CAT_FUNCTION:
+                fns_list.append(member)
+            elif cat in (CAT_TYPE, CAT_TYPE_TYPE, CAT_TYPE_FUNCTION):
+                types_list.append((original, member))
+            elif cat == CAT_ERROR_SET:
+                err_sets_list.append((original, member))
+            elif cat in (CAT_GLOBAL_CONST, CAT_PRIMITIVE):
+                vals_list.append((original, member))
+            elif cat == CAT_ALIAS:
+                if member in seen:
+                    vals_list.append((original, member))
+                    break
+                seen.add(member)
+                nxt = std.get_aliasee()
+                if nxt is None:
+                    vals_list.append((original, member))
+                    break
+                member = nxt
+                continue
+            else:
+                raise RuntimeError(f"unknown category: {cat}")
+            break
+
+    md = ""
+
+    if types_list:
+        md += "## Types\n\n"
+        for original, _ in types_list:
+            md += f"- {std.decl_name(original)}\n"
+        md += "\n"
+
+    if namespaces_list:
+        md += "## Namespaces\n\n"
+        for original, _ in namespaces_list:
+            md += f"- {std.decl_name(original)}\n"
+        md += "\n"
+
+    if err_sets_list:
+        md += "## Error Sets\n\n"
+        for original, _ in err_sets_list:
+            md += f"- {std.decl_name(original)}\n"
+        md += "\n"
+
+    if fns_list:
+        md += "## Functions\n\n"
+        for decl in fns_list:
+            name = std.decl_name(decl)
+            proto = std.decl_fn_proto_html(decl, True)
+            docs = std.decl_docs_html(decl, True)
+            md += f"### {name}\n\n"
+            if proto:
+                md += proto + "\n\n"
+            if docs:
+                md += docs + "\n\n"
+
+    if fields:
+        md += "## Fields\n\n"
+        for f in fields:
+            md += std.decl_field_html(base_decl, f) + "\n\n"
+
+    if vars_list:
+        md += "## Global Variables\n\n"
+        for decl in vars_list:
+            name = std.decl_name(decl)
+            type_html = std.decl_type_html(decl)
+            docs = std.decl_docs_html(decl, True)
+            md += f"### {name}\n\n"
+            if type_html:
+                md += f"Type: {type_html}\n\n"
+            if docs:
+                md += docs + "\n\n"
+
+    if vals_list:
+        md += "## Values\n\n"
+        for original, member in vals_list:
+            name = std.decl_name(original)
+            type_html = std.decl_type_html(member)
+            docs = std.decl_docs_html(member, True)
+            md += f"### {name}\n\n"
+            if type_html:
+                md += f"Type: {type_html}\n\n"
+            if docs:
+                md += docs + "\n\n"
+
+    return md

zigpeek/version.py

@@ -0,0 +1,15 @@
+import os
+
+DEFAULT_ZIG_VERSION = "0.16.0"
+_ENV_VAR = "ZIGPEEK_VERSION"
+
+
+def resolve_version(cli_value: str | None) -> str:
+    if cli_value is not None:
+        if cli_value == "":
+            raise ValueError("--version cannot be empty")
+        return cli_value
+    env_value = os.environ.get(_ENV_VAR)
+    if env_value:
+        return env_value
+    return DEFAULT_ZIG_VERSION

zigpeek/wasm.py

@@ -0,0 +1,210 @@
+import struct
+
+import wasmtime
+
+_INVALID_INDEX = 0xFFFF_FFFF
+
+
+def unpack_string(memory: bytes, ptr: int, length: int) -> str:
+    if length == 0:
+        return ""
+    return memory[ptr : ptr + length].decode("utf-8", errors="replace")
+
+
+def unpack_slice32(memory: bytes, ptr: int, length: int) -> list[int]:
+    if length == 0:
+        return []
+    return list(struct.unpack_from(f"<{length}I", memory, ptr))
+
+
+def unpack_slice64(memory: bytes, ptr: int, length: int) -> list[int]:
+    if length == 0:
+        return []
+    return list(struct.unpack_from(f"<{length}Q", memory, ptr))
+
+
+def split_packed(packed: int) -> tuple[int, int]:
+    """Decode the JS BigInt packing: low32 = ptr, high32 = length."""
+    return packed & 0xFFFFFFFF, packed >> 32
+
+
+class WasmStd:
+    """Drive the autodoc WASM module loaded from sources.tar.
+
+    Mirrors the JS interface in ~/Documents/GitHub/zig-mcp/mcp/std.ts.
+    The WASM imports a single js.log function (level, ptr, len) — we
+    forward errors as exceptions and discard the rest.
+    """
+
+    def __init__(self, wasm_bytes: bytes, sources_tar: bytes) -> None:
+        self._engine = wasmtime.Engine()
+        self._store = wasmtime.Store(self._engine)
+        module = wasmtime.Module(self._engine, wasm_bytes)
+
+        log_type = wasmtime.FuncType(
+            [wasmtime.ValType.i32(), wasmtime.ValType.i32(), wasmtime.ValType.i32()],
+            [],
+        )
+        log_func = wasmtime.Func(self._store, log_type, self._on_log)
+        instance = wasmtime.Instance(self._store, module, [log_func])
+
+        self._exports = instance.exports(self._store)
+        self._memory: wasmtime.Memory = self._exports["memory"]
+
+        ptr = self._call("alloc", len(sources_tar))
+        self._memory.write(self._store, sources_tar, ptr)
+        self._call("unpack", ptr, len(sources_tar))
+
+    def _on_log(self, level: int, ptr: int, length: int) -> None:
+        if level == 0:
+            raise RuntimeError(f"WASM log error: {self._read_string(ptr, length)}")
+
+    def _call(self, name: str, *args: int) -> int:
+        result = self._exports[name](self._store, *args)
+        return int(result) if result is not None else 0
+
+    def _call_optional(self, name: str, *args: int) -> int | None:
+        result = self._call(name, *args)
+        return None if result in (-1, _INVALID_INDEX) else result
+
+    def _read_string(self, ptr: int, length: int) -> str:
+        if length == 0:
+            return ""
+        return self._memory.read(self._store, ptr, ptr + length).decode(
+            "utf-8", errors="replace"
+        )
+
+    def _read_slice32(self, ptr: int, length: int) -> list[int]:
+        if length == 0:
+            return []
+        raw = self._memory.read(self._store, ptr, ptr + length * 4)
+        return list(struct.unpack_from(f"<{length}I", raw))
+
+    def _read_slice64(self, ptr: int, length: int) -> list[int]:
+        if length == 0:
+            return []
+        raw = self._memory.read(self._store, ptr, ptr + length * 8)
+        return list(struct.unpack_from(f"<{length}Q", raw))
+
+    def _packed_string(self, packed: int) -> str:
+        return self._read_string(*split_packed(packed))
+
+    def _packed_slice32(self, packed: int) -> list[int]:
+        return self._read_slice32(*split_packed(packed))
+
+    def _packed_slice64(self, packed: int) -> list[int]:
+        return self._read_slice64(*split_packed(packed))
+
+    def _set_string(self, export: str, s: str) -> None:
+        encoded = s.encode("utf-8")
+        ptr = self._call(export, len(encoded))
+        self._memory.write(self._store, encoded, ptr)
+
+    def list_modules(self) -> list[str]:
+        out: list[str] = []
+        i = 0
+        while True:
+            name = self._packed_string(self._call("module_name", i))
+            if not name:
+                break
+            out.append(name)
+            i += 1
+        return out
+
+    def find_decl(self, fqn: str) -> int | None:
+        self._set_string("set_input_string", fqn)
+        return self._call_optional("find_decl")
+
+    def find_file_root(self, path: str) -> int | None:
+        self._set_string("set_input_string", path)
+        return self._call_optional("find_file_root")
+
+    def find_module_root(self, pkg_index: int) -> int:
+        return self._call("find_module_root", pkg_index)
+
+    def categorize_decl(self, decl_index: int, resolve_alias_to: int = 0) -> int:
+        return self._call("categorize_decl", decl_index, resolve_alias_to)
+
+    def get_aliasee(self) -> int | None:
+        return self._call_optional("get_aliasee")
+
+    def decl_parent(self, decl_index: int) -> int | None:
+        return self._call_optional("decl_parent", decl_index)
+
+    def fully_qualified_name(self, decl_index: int) -> str:
+        return self._packed_string(self._call("decl_fqn", decl_index))
+
+    def decl_name(self, decl_index: int) -> str:
+        return self._packed_string(self._call("decl_name", decl_index))
+
+    def decl_category_name(self, decl_index: int) -> str:
+        return self._packed_string(self._call("decl_category_name", decl_index))
+
+    def decl_docs_html(self, decl_index: int, short: bool) -> str:
+        return self._packed_string(self._call("decl_docs_html", decl_index, int(short)))
+
+    def decl_fn_proto_html(self, decl_index: int, linkify: bool) -> str:
+        return self._packed_string(
+            self._call("decl_fn_proto_html", decl_index, int(linkify))
+        )
+
+    def decl_param_html(self, decl_index: int, param: int) -> str:
+        return self._packed_string(self._call("decl_param_html", decl_index, param))
+
+    def decl_doctest_html(self, decl_index: int) -> str:
+        return self._packed_string(self._call("decl_doctest_html", decl_index))
+
+    def decl_source_html(self, decl_index: int) -> str:
+        return self._packed_string(self._call("decl_source_html", decl_index))
+
+    def decl_field_html(self, base_decl: int, field: int) -> str:
+        return self._packed_string(self._call("decl_field_html", base_decl, field))
+
+    def decl_type_html(self, decl_index: int) -> str:
+        return self._packed_string(self._call("decl_type_html", decl_index))
+
+    def decl_file_path(self, decl_index: int) -> str:
+        return self._packed_string(self._call("decl_file_path", decl_index))
+
+    def decl_params(self, decl_index: int) -> list[int]:
+        return self._packed_slice32(self._call("decl_params", decl_index))
+
+    def decl_fields(self, decl_index: int) -> list[int]:
+        return self._packed_slice32(self._call("decl_fields", decl_index))
+
+    def decl_error_set(self, decl_index: int) -> list[int]:
+        return self._packed_slice64(self._call("decl_error_set", decl_index))
+
+    def namespace_members(self, decl_index: int, include_private: bool) -> list[int]:
+        return self._packed_slice32(
+            self._call("namespace_members", decl_index, int(include_private))
+        )
+
+    def type_fn_members(self, decl_index: int, include_private: bool) -> list[int]:
+        return self._packed_slice32(
+            self._call("type_fn_members", decl_index, int(include_private))
+        )
+
+    def type_fn_fields(self, decl_index: int) -> list[int]:
+        return self._packed_slice32(self._call("type_fn_fields", decl_index))
+
+    def fn_error_set(self, decl_index: int) -> int | None:
+        result = self._call("fn_error_set", decl_index)
+        return None if result == 0 else result
+
+    def fn_error_set_decl(self, decl_index: int, err_set_node: int) -> int:
+        return self._call("fn_error_set_decl", decl_index, err_set_node)
+
+    def error_set_node_list(self, base_decl: int, err_set_node: int) -> list[int]:
+        return self._packed_slice64(
+            self._call("error_set_node_list", base_decl, err_set_node)
+        )
+
+    def error_html(self, base_decl: int, err: int) -> str:
+        return self._packed_string(self._call("error_html", base_decl, err))
+
+    def execute_query(self, query: str, ignore_case: bool) -> list[int]:
+        self._set_string("query_begin", query)
+        ptr = self._call("query_exec", int(ignore_case))
+        length = self._read_slice32(ptr, 1)[0]
+        return self._read_slice32(ptr + 4, length)

zigpeek-0.3.0.dist-info/METADATA

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: zigpeek
+Version: 0.3.0
+Summary: Fast CLI for Zig 0.16 stdlib + Skill for coding agents
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: beautifulsoup4>=4.12.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: lxml>=5.0.0
+Requires-Dist: wasmtime>=25.0.0

zigpeek-0.3.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+zigpeek/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+zigpeek/builtins.py,sha256=bObngeM-ECoxYy6W_GK-gK0XddftRULZVoSyv5u9xvw,5209
+zigpeek/cli.py,sha256=d54AG3Zoc05ZT8K5G2Ov5biRSnyAruqtETWdCkpkaxg,10139
+zigpeek/fetch.py,sha256=NEv5Ro0y3rMebjsDUoLobFxRrcjkRLt3bIcwinmaQcg,3183
+zigpeek/stdlib.py,sha256=8--XHGvI-lt4aFQpEYMohUcW_siyZ1njIe9lzvjiZxw,9805
+zigpeek/version.py,sha256=Jgu1ea8iDxoaOuzFiloUfyKZyBZE-jXBSKyBNVALfCU,380
+zigpeek/wasm.py,sha256=YpdZqiXcbUCzfwarjXQ1hSPxl5C3Epe9ojL5YDpYvSo,8141
+zigpeek/_vendor/main.wasm,sha256=p0uEHkPeJKd_SaGAsxSObqX1HvOvg-zIRtqCV8xGBbU,198076
+zigpeek-0.3.0.dist-info/METADATA,sha256=yMS1-Xb_YoaXgH6IIzTvhDfNwhb7hnAPGLaZJW7CtWc,287
+zigpeek-0.3.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+zigpeek-0.3.0.dist-info/entry_points.txt,sha256=pgEKNRrTppa0T5zXRA9VYU_wKK1pe_hvCTdmQWf3Ivo,45
+zigpeek-0.3.0.dist-info/licenses/LICENSE,sha256=uNuWcR4sJ7681Zgk8CdW_6u2WLeeVqScvIOLuQoh8z8,1298
+zigpeek-0.3.0.dist-info/RECORD,,

zigpeek-0.3.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

zigpeek-0.3.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+zigpeek = zigpeek.cli:main

zigpeek-0.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,28 @@
+MIT License
+
+Copyright (c) 2026 Tanuj Vasudeva
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+This project bundles `src/zigpeek/_vendor/main.wasm`, built from the
+`zig-mcp` project (https://github.com/loonghao/zig-mcp), which is also
+distributed under the MIT License. See `vendor/PROVENANCE.md` for build
+details.