zigpeek 0.3.0__tar.gz

zigpeek-0.3.0/.github/workflows/release.yml

@@ -0,0 +1,72 @@
+name: release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    name: build distributions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build sdist + wheel
+        run: uv build
+
+      - name: Verify wheel ships main.wasm
+        run: |
+          set -euo pipefail
+          wheel=$(ls dist/zigpeek-*.whl)
+          python -m zipfile -l "$wheel" | grep -q "_vendor/main.wasm"
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  publish-pypi:
+    name: publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/zigpeek
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    name: attach artifacts to GitHub Release
+    needs: publish-pypi
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: ${{ github.repository }}
+          TAG: ${{ github.ref_name }}
+        run: |
+          gh release create "$TAG" \
+            --title "$TAG" \
+            --generate-notes \
+            dist/*

zigpeek-0.3.0/.github/workflows/test.yml

@@ -0,0 +1,34 @@
+name: test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: test-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  pytest:
+    name: pytest (${{ matrix.os }} / py${{ matrix.python }})
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python: ["3.12", "3.13"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python }}
+          enable-cache: true
+
+      - name: Sync dependencies
+        run: uv sync --dev
+
+      - name: Run unit tests
+        run: uv run pytest -q

zigpeek-0.3.0/.gitignore

@@ -0,0 +1,5 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+.venv/
+.DS_Store

zigpeek-0.3.0/.python-version

@@ -0,0 +1 @@
+3.12

zigpeek-0.3.0/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.

zigpeek-0.3.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,97 @@
+# zigpeek
+
+Fast CLI for Zig 0.16 stdlib + builtin docs lookups. Replaces the
+[`zig-docs` MCP server](https://github.com/loonghao/zig-mcp) in
+environments without MCP support — typically cloud agents.
+
+## Install
+
+```sh
+pipx install git+https://github.com/TanGentleman/zigpeek
+# or
+uv tool install git+https://github.com/TanGentleman/zigpeek
+```
+
+## Usage
+
+```sh
+zigpeek prefetch                                 # warm cache (once per session)
+zigpeek search ArrayList --limit 10              # fuzzy stdlib search
+zigpeek get std.ArrayList                        # full docs for an FQN
+zigpeek get std.ArrayList --source-file          # source file containing it
+zigpeek builtins list                            # all @-builtins
+zigpeek builtins get atomic                      # specific builtin
+zigpeek batch <<EOF                              # amortize startup
+search ArrayList
+get std.ArrayList
+EOF
+```
+
+Full agent-facing docs live in [`skills/zigpeek/SKILL.md`](skills/zigpeek/SKILL.md).
+
+## Use as a Claude Code skill
+
+Drop the `skills/zigpeek/` directory into your skills folder so Claude
+Code can discover it:
+
+```sh
+cp -r skills/zigpeek ~/.claude/skills/
+```
+
+The skill assumes `zigpeek` is on `$PATH` (see install above).
+
+## Architecture
+
+| File                              | Role                                                |
+| --------------------------------- | --------------------------------------------------- |
+| `src/zigpeek/cli.py`              | argparse entrypoint, exit-code contract             |
+| `src/zigpeek/stdlib.py`           | markdown rendering (port of `zig-mcp/mcp/std.ts`)   |
+| `src/zigpeek/wasm.py`             | wasmtime driver + typed wrapper around WASM exports |
+| `src/zigpeek/builtins.py`         | langref HTML parser + ranking                       |
+| `src/zigpeek/fetch.py`            | sources.tar / langref download + `/tmp` cache       |
+| `src/zigpeek/version.py`          | default Zig version + override resolution           |
+| `src/zigpeek/_vendor/main.wasm`   | autodoc WASM, shipped inside the package            |
+| `vendor/PROVENANCE.md`            | build instructions + SHA256 + upstream commit       |
+| `vendor/patches/`                 | local patches applied before rebuilding the WASM    |
+| `skills/zigpeek/SKILL.md`         | skill metadata for Claude Code                      |
+
+## Updating the vendored WASM
+
+Bumping the Zig version may need a fresh `main.wasm`. Build steps live in
+[`vendor/PROVENANCE.md`](vendor/PROVENANCE.md). Summary:
+
+```sh
+cd ~/Documents/GitHub/zig-mcp
+git pull
+zig build
+cp zig-out/main.wasm <repo>/src/zigpeek/_vendor/main.wasm
+shasum -a 256 <repo>/src/zigpeek/_vendor/main.wasm
+# update SHA256 + commit + date in vendor/PROVENANCE.md
+```
+
+Run smoke tests after updating:
+
+```sh
+ZIGPEEK_SMOKE=1 uv run pytest -v
+```
+
+## Testing
+
+```sh
+uv sync                              # install deps
+uv run pytest -q                     # unit tests (no network)
+ZIGPEEK_SMOKE=1 uv run pytest        # adds smoke tests (needs network + WASM)
+```
+
+## Why a port and not a wrapper?
+
+The autodoc renderer lives inside the WASM as HTML-emitting exports.
+Wrapping the upstream MCP would mean shipping Node.js to every cloud
+agent. Porting the ~700 lines of TS that drive the WASM gets us the same
+output with only Python + a vendored binary.
+
+## License
+
+MIT — see [`LICENSE`](LICENSE). Bundled `main.wasm` is also MIT (from
+[`zig-mcp`](https://github.com/loonghao/zig-mcp)); see
+[`vendor/PROVENANCE.md`](vendor/PROVENANCE.md).

zigpeek-0.3.0/pyproject.toml

@@ -0,0 +1,32 @@
+[project]
+name = "zigpeek"
+version = "0.3.0"
+description = "Fast CLI for Zig 0.16 stdlib + Skill for coding agents"
+requires-python = ">=3.12"
+dependencies = [
+    "wasmtime>=25.0.0",
+    "httpx>=0.27.0",
+    "beautifulsoup4>=4.12.0",
+    "lxml>=5.0.0",
+]
+
+[project.scripts]
+zigpeek = "zigpeek.cli:main"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/zigpeek"]
+
+# Be explicit: the vendored WASM is part of the package, not just incidental
+# files swept in by hatchling defaults. Keeps editable installs (`uv sync`),
+# wheel builds (`uv build`), and future tool installs in lockstep.
+[tool.hatch.build.targets.wheel.force-include]
+"src/zigpeek/_vendor/main.wasm" = "zigpeek/_vendor/main.wasm"

zigpeek-0.3.0/skills/zigpeek/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: zigpeek
+description: Look up Zig 0.16 standard library APIs and builtin functions via a local CLI (replaces the zig-docs MCP server in environments without MCP support, e.g. cloud agents). Use before writing or reviewing Zig code that touches stdlib — critical for std.Io filesystem APIs (std.Io.Dir, std.Io.File), Reader/Writer interfaces, and std.process.Init. Triggers when answering "how do I X in Zig" or writing Zig that touches files, dirs, env, or process state. If the zig-docs MCP server is already connected, prefer it over this CLI.
+---
+
+# zigpeek
+
+A Python+wasmtime port of the four `zig-docs` MCP tools. Loads the same
+autodoc WASM module the official Zig docs use, against the same
+`sources.tar` from `ziglang.org`. Output is markdown, byte-equivalent
+(modulo whitespace) to what the MCP returns.
+
+## Setup (run once per agent session/sandbox)
+
+Install the `zigpeek` CLI globally with either tool:
+
+```sh
+pipx install git+https://github.com/TanGentleman/zigpeek
+# or
+uv tool install git+https://github.com/TanGentleman/zigpeek
+```
+
+Then warm the cache so subsequent lookups are offline:
+
+```sh
+zigpeek prefetch
+```
+
+Requires outbound network access to `ziglang.org` on first use. Caches
+downloads under `/tmp/zigpeek-cache/<version>/`.
+
+## Usage
+
+```sh
+# Search the stdlib
+zigpeek search ArrayList --limit 10
+
+# Get full docs for a stdlib item
+zigpeek get std.ArrayList
+
+# Get the source file containing an item
+zigpeek get std.ArrayList --source-file
+
+# List all builtin functions
+zigpeek builtins list
+
+# Look up a builtin (by name or keyword)
+zigpeek builtins get atomic
+
+# Pre-populate the cache (so later commands don't need network)
+zigpeek prefetch
+```
+
+## When to use which command
+
+| Need                                              | Command                           |
+| ------------------------------------------------- | --------------------------------- |
+| Discover stdlib symbols matching a keyword        | `zigpeek search <q>`              |
+| Read full docs + signature for a known FQN        | `zigpeek get <fqn>`               |
+| Read the full source file (terse docstring; want invariants, internals, or per-field implementation) | `zigpeek get <fqn> --source-file` |
+| Browse all `@`-builtins                           | `zigpeek builtins list`           |
+| Look up a specific `@builtin` (accepts `atomic` or `@atomic`) | `zigpeek builtins get <q>` |
+| Warm cache before going offline                   | `zigpeek prefetch`                |
+| Run several lookups in one process (cheap)        | `zigpeek batch`                   |
+
+## Batching multiple lookups
+
+Each `zigpeek` invocation pays ~1 s of Python+wasmtime startup. If you
+plan more than two lookups, pipe them through `zigpeek batch` to share
+that cost across the whole sequence — the WASM instance and parsed
+sources are reused between commands.
+
+```sh
+zigpeek batch <<'EOF'
+search ArrayList --limit 5
+get std.ArrayList
+get std.ArrayList --source-file
+builtins get atomic
+EOF
+```
+
+Each command's output is framed with a `===> <command>` separator on its
+own line. Per-line failures (not-found, bad input) are reported inline
+and **do not abort the batch**; the process exit code is the worst code
+seen across all lines (`0` if every command succeeded). `prefetch` and
+nested `batch` are rejected — run them outside.
+
+Use `zigpeek batch -f commands.txt` to read from a file instead of
+stdin. Blank lines and lines starting with `#` are ignored.
+
+**Reach for `--source-file` early** when:
+
+- The docstring is one line or missing.
+- The page lists a method signature but elides the body (e.g.
+  `MultiArrayList.items` shows the prototype but the per-field pointer
+  math from `ptrs[@intFromEnum(field)]` only lives in the source).
+- You need invariants, error sets, or how a private field is computed.
+
+## Finding nested types
+
+Inner types live under the **defining module's path**, not the
+re-export. `std.MultiArrayList` is a re-export from
+`std.multi_array_list`; its inner `Slice` type only resolves at the
+defining path:
+
+```sh
+zigpeek get std.multi_array_list.MultiArrayList.Slice   # works
+zigpeek get std.MultiArrayList.Slice                    # not found
+```
+
+If `search` only surfaces a re-export and `get` 404s on the inner type,
+re-run `get` with the module path.
+
+## Version override
+
+Defaults to Zig `0.16.0`. Override with:
+
+```sh
+zigpeek search ArrayList --version 0.15.1
+ZIGPEEK_VERSION=master zigpeek search ArrayList
+```
+
+## Offline mode
+
+If the agent will run without internet, prefetch first while you still
+have network:
+
+```sh
+# Default cache (/tmp/zigpeek-cache/<version>/)
+zigpeek prefetch
+
+# Custom cache directory (persists outside /tmp)
+zigpeek prefetch --cache-dir ~/.cache/zigpeek
+```
+
+After prefetch, every `search` / `get` / `builtins` call reads from disk
+and never touches the network. Pass the same `--cache-dir` (or set
+`ZIGPEEK_CACHE_DIR`) on subsequent commands if you used a non-default
+location.
+
+If a bundled snapshot ships inside the package (`src/zigpeek/_data/<version>/`),
+the read path uses it automatically and prefetch becomes a no-op.
+
+## Exit codes
+
+- `0` — success (markdown on stdout)
+- `1` — bad input or "not found" (message on stderr)
+- `2` — network/cache failure (message on stderr)
+
+## Troubleshooting
+
+- **`zigpeek: command not found`** — install via `pipx install git+https://github.com/TanGentleman/zigpeek`
+  (or `uv tool install ...`). If neither tool is available, install uv:
+  `curl -LsSf https://astral.sh/uv/install.sh | sh`.
+- **`network/cache error`** — `ziglang.org` is blocked or unreachable.
+  Run `zigpeek prefetch` from a network-enabled host first, or check
+  your sandbox network policy.
+- **`Declaration "..." not found`** — the FQN is wrong. Two things to
+  try: (1) `zigpeek search` to discover the canonical name; (2) if you
+  searched a re-export (e.g. `std.MultiArrayList`), retry `get` against
+  the defining module path (e.g. `std.multi_array_list.MultiArrayList`).

zigpeek-0.3.0/src/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]