v0.2.5821 — 7 issue bundle (#501, #502, #503, #504, #505, #506, #507, #508)

CHANGELOG.md

@@ -1,6 +1,30 @@
 # Changelog
 
 
+## 0.2.5821 - 2026-05-28
+
+Bundle of seven fixes from the open-issue triage on 2026-05-28.
+
+### MCP server fixes
+
+- **#502 + #503 — arg parser overhaul.** `codedb mcp <path>` no longer hangs forever in deferred mode (it now honors the path as root). `codedb mcp --help` prints usage instead of starting the server. Unknown post-`mcp` flags (e.g. `codedb mcp --snapshot`) are now rejected with a listed-valid-flags error. `codedb mcp` from a git-repo subdirectory walks up to the repo root. The deferred-scan path can no longer hang in `loading_snapshot` forever when the cwd isn't indexable — gives up after 13 s and unblocks `scan_done`.
+- **#505 + #506 — MCP protocol version negotiation.** The server previously hardcoded `protocolVersion: "2025-06-18"`, which older Zed and certain opencode versions rejected with a startup timeout / "No MCP tools". Now echoes the client's version when it's one we've verified against (`2024-11-05`, `2025-03-26`, `2025-06-18`); for newer-than-known clients we return our latest known version.
+- **#507 — search misses content after snapshot rebuild.** Files routed through `indexFileOutlineOnly` (snapshot load fallback, watcher incremental updates, WASM fast-path) were registered in `outlines` and `contents` but not in any search index. They were invisible to every search tier — including the tier-5 full-scan fallback, which short-circuited because the trigram index returned a non-null empty candidate set. Fixed by registering outline-only files in `skip_trigram_files` so tier 3 substring-scans them.
+- **#508 — actionable `codedb_remote` errors.** The remote tool now distinguishes Cloudflare 530 / 1033 origin-unreachable from 404 (repo not indexed), 429 (rate limited), and 5xx (upstream error) with retry / local-fallback hints. The server-side outage at `api.wiki.codes` is not fixed by this change; the UX is.
+
+### Startup / platform
+
+- **#504 — macOS Intel x64 segfault on bare `codedb`.** Bisected via Rosetta: Zig 0.16's runtime wrapper around `pub fn main(...) !void` crashes at startup on signed x86_64-macos binaries. The user saw `codedb` segfault before any output reached the terminal. Fix: `pub fn main(...) void` (infallible) + `mainTrampoline()` for the fallible work + a `handleFastPath` short-circuit for bare/`--version` invocations that writes via raw `std.c.write` and bypasses the worker-thread trampoline entirely. Also fixes a related "output silently lost on early exit" bug where `std.process.exit(_)` skipped the deferred `Out.flush()`; `Out.exitWithFlush` now handles the common usage / error-message exit paths.
+
+### Distribution
+
+- **#501 — npm/npx distribution.** Published [`codedeebee`](https://www.npmjs.com/package/codedeebee) as the npx-friendly sibling of `codedb`. `npx -y codedeebee mcp` does a one-shot install: thin Node launcher + `postinstall` that downloads the matching native binary from this GitHub release and SHA256-verifies against `checksums.sha256`. The bare `codedb` name is restricted on npm; the package is `codedeebee` but the CLI it installs is still called `codedb`.
+
+### Installer
+
+- **Hook-priority race.** `install/install.sh` now detects competing legacy-tools hooks (`block-legacy-tools.sh`, muonry, zigrep, zigread) and inserts codedb's hook at index 0 instead of appending. Re-runs reshuffle an already-registered codedb hook to the front if a competitor has appeared since the previous install.
+
+
 ## 0.2.5813 - 2026-05-12
 
 `0.2.5813` ships three structural improvements: a Tier 0 search-quality rewrite, a 4-6x faster regex matcher, and a bounded-memory content cache.

README.md

@@ -46,7 +46,7 @@
 
 | What works today                                       | What's in progress                       |
 |--------------------------------------------------------|------------------------------------------|
-| 16 MCP tools for full codebase intelligence            | Deeper parser coverage and edge-case handling |
+| 21 MCP tools for full codebase intelligence            | Deeper parser coverage and edge-case handling |
 | Trigram v2: integer doc IDs, batch-accumulate, merge intersect | Incremental segment-based indexing |
 | 538x faster than ripgrep on pre-indexed queries        | WASM target for Cloudflare Workers       |
 | O(1) inverted word index for identifier lookup         | Multi-project support                    |
@@ -72,37 +72,43 @@ curl -fsSL https://codedb.codegraff.com/install.sh | bash
 
 Downloads the binary for your platform and auto-registers codedb as an MCP server in **Claude Code**, **Codex**, **Gemini CLI**, and **Cursor**. The installer prints the exact `codedb mcp` command it registered plus hook setup pointers for Codex and Claude Code.
 
-### Updating or repairing an older install
+### Or via npm/npx (zero-install for MCP clients)
 
-If `codedb update` fails on an older release, rerun the installer:
+```bash
+npx -y codedeebee mcp
+```
+
+Or install globally:
 
 ```bash
-curl -fsSL https://codedb.codegraff.com/install.sh | bash
+npm install -g codedeebee
+codedb mcp
 ```
 
-This replaces the `codedb` binary with the latest GitHub Release and keeps your existing MCP registrations, config, caches, and snapshots. Use this path for any release whose built-in updater cannot fetch release checksums.
+The npm package is named [`codedeebee`](https://www.npmjs.com/package/codedeebee) (the bare `codedb` name is restricted on npm); it ships a thin launcher that downloads the matching native binary from GitHub Releases on `postinstall` and verifies the SHA256 checksum. The installed CLI is still called `codedb`.
+
+Useful for MCP clients (Claude Code, Cursor, opencode, Claude Desktop) that already use `npx`:
 
-### v0.2.579 MCP hotfix and release checksums
+```json
+{
+  "codedb": {
+    "type": "local",
+    "command": ["npx", "-y", "codedeebee"],
+    "args": ["mcp"],
+    "enabled": true
+  }
+}
+```
 
-This note applies to `v0.2.579` only. Earlier `v0.2.579` binaries were rebuilt
-and re-uploaded on May 2, 2026 because they passed the normal Zig test suite but
-missed an MCP end-to-end regression: after `codedb_index` reported success,
-follow-up MCP queries could still see an empty in-memory project (`files: 0`,
-`scan: loading_snapshot`, empty `tree`/`find`/`search`, or `file not indexed`).
+### Updating or repairing an older install
 
-The fixed `v0.2.579` release assets were rebuilt from source commit
-`1b634f0ba5cd1072e9ca54cabf442b573e034f53`. The values below are SHA256
-checksums for the uploaded binaries, not Git commit SHAs:
+If `codedb update` fails on an older release, rerun the installer:
 
-| Binary | SHA256 |
-|--------|--------|
-| `codedb-darwin-arm64` | `b5bddba01767e38e9723f28c7b3ff55370c4eda5f9e0e84172aaec1ff5094cb2` |
-| `codedb-darwin-x86_64` | `cf2a9ec511f99fd839d2349cc17e671cd9566260cf601b8b23dd649665c22999` |
-| `codedb-linux-arm64` | `955b0288c5cfb5c360f7b814cd3cc288ecc42c63a569f65fac358bd9454d788b` |
-| `codedb-linux-x86_64` | `201dfe26bec33b3569c44a3d4893c51822bc793e06fab69fd93e81c0354232ee` |
+```bash
+curl -fsSL https://codedb.codegraff.com/install.sh | bash
+```
 
-If you installed `v0.2.579` before this hotfix, rerun the installer above so the
-binary matches the final uploaded checksum for your platform.
+This replaces the `codedb` binary with the latest GitHub Release and keeps your existing MCP registrations, config, caches, and snapshots. Use this path for any release whose built-in updater cannot fetch release checksums.
 
 ## Documentation
 
@@ -127,7 +133,7 @@ Or install manually from [GitHub Releases](https://github.com/justrach/codedb/re
 
 ### As an MCP server (recommended)
 
-After installing, codedb is automatically registered. Just open a project and the 16 MCP tools are available to your AI agent.
+After installing, codedb is automatically registered. Just open a project and the 21 MCP tools are available to your AI agent.
 
 ```bash
 # Manual MCP start (auto-configured by install script)
@@ -156,7 +162,7 @@ codedb hot                            # recently modified files
 
 ## 🔧 MCP Tools
 
-16 tools over the Model Context Protocol (JSON-RPC 2.0 over stdio):
+21 tools over the Model Context Protocol (JSON-RPC 2.0 over stdio):
 
 | Tool | Description |
 |------|-------------|
@@ -165,18 +171,22 @@ codedb hot                            # recently modified files
 | `codedb_symbol` | Find where a symbol is defined across the codebase |
 | `codedb_search` | Trigram-accelerated full-text search (supports regex, scoped results) |
 | `codedb_word` | O(1) inverted index word lookup |
+| `codedb_callers` | Every call site of a symbol — word index ∩ outline scope, in one round-trip |
+| `codedb_context` | Task-shaped composer — pass a NL task, get keywords + symbol defs + ranked files + top snippets in one block (replaces 3–5 sequential calls) |
 | `codedb_hot` | Most recently modified files |
-| `codedb_deps` | Reverse dependency graph (which files import this file) |
-| `codedb_read` | Read file content (supports line ranges, hash-based caching) |
-| `codedb_edit` | Apply line-range edits (replace, insert, delete — atomic writes) |
+| `codedb_deps` | Dependency graph: `imported_by` (default) or `depends_on`; `transitive=true` for full BFS |
+| `codedb_read` | Read file content (line ranges, `if_hash` skip-unchanged, `compact` mode) |
+| `codedb_edit` | Apply line-range edits (replace, insert, delete — atomic writes, optional `if_hash` guard) |
 | `codedb_changes` | Changed files since a sequence number |
-| `codedb_status` | Index status (file count, current sequence) |
+| `codedb_status` | Index status (file count, current sequence, scan phase) |
 | `codedb_snapshot` | Full pre-rendered JSON snapshot of the codebase |
-| `codedb_bundle` | Batch multiple read-only queries in one call (max 20 ops) |
 | `codedb_remote` | Query indexed public repos via api.wiki.codes — no local clone needed |
 | `codedb_projects` | List all locally indexed projects on this machine |
-| `codedb_index` | Index a local folder and create a codedb.snapshot |
-
+| `codedb_index` | Index a local folder and write `codedb.snapshot` |
+| `codedb_find` | Fuzzy **file-name** search (typo-tolerant subsequence match against indexed paths — not a content/symbol search) |
+| `codedb_glob` | Match indexed paths against a glob pattern (`src/**/*.zig`, `*.md`, …) |
+| `codedb_ls` | List immediate children of a directory — dirs first, then files with language + counts |
+| `codedb_query` | Composable pipeline — chain `find`, `search`, `filter`, `deps`, `outline`, `read`, `sort`, `limit` in one request |
 
 ### `codedb_remote` — Cloud Intelligence
 
@@ -224,6 +234,7 @@ For Codex and Claude Code hook examples around `codedb_remote`, see [`docs/hooks
 | `codedb search <query>` | Full-text search (trigram, case-insensitive) |
 | `codedb search --regex <pattern>` | Regex search |
 | `codedb word <identifier>` | Exact word lookup via inverted index |
+| `codedb read <path>` | Read file contents (supports `-L FROM-TO`, `--compact`) |
 | `codedb hot` | Recently modified files |
 | `codedb snapshot` | Write codedb.snapshot to project root |
 | `codedb serve` | HTTP daemon on :7719 |

install/install.sh

@@ -220,14 +220,37 @@ except (FileNotFoundError, json.JSONDecodeError):
 
 hooks = data.setdefault("hooks", {})
 
-# Merge codedb hooks without clobbering existing hooks from other tools
+# Merge codedb hooks without clobbering existing hooks from other tools.
+# If a competing legacy-tools hook is already registered for the same
+# event/matcher (e.g. muonry's block-legacy-tools.sh), insert codedb's
+# entry at the FRONT of the list so its redirect wins the race; otherwise
+# append. Re-runs will also reshuffle an already-registered codedb hook
+# to the front if a competitor has appeared since the previous install.
+COMPETITOR_MARKERS = ("block-legacy-tools", "muonry", "zigrep", "zigread")
+
 def merge_hook(event, new_entry):
     existing = hooks.get(event, [])
     cmd = new_entry["hooks"][0]["command"]
-    for e in existing:
+    matcher = new_entry.get("matcher", "")
+    competes = any(
+        e.get("matcher", "") == matcher
+        and any(any(m in h.get("command", "") for m in COMPETITOR_MARKERS) for h in e.get("hooks", []))
+        for e in existing
+    )
+    idx = None
+    for i, e in enumerate(existing):
         if any(cmd in h.get("command", "") for h in e.get("hooks", [])):
-            return
-    existing.append(new_entry)
+            idx = i
+            break
+    if idx is not None:
+        if competes and idx != 0:
+            existing.insert(0, existing.pop(idx))
+            hooks[event] = existing
+        return
+    if competes:
+        existing.insert(0, new_entry)
+    else:
+        existing.append(new_entry)
     hooks[event] = existing
 
 merge_hook("PreToolUse", {"matcher": "Bash", "hooks": [{"type": "command", "command": "$HOME/.claude/hooks/codedb-block-legacy.sh"}]})

npm/.npmignore

@@ -0,0 +1,4 @@
+vendor/
+*.tgz
+.DS_Store
+node_modules/

npm/README.md

@@ -0,0 +1,69 @@
+# codedeebee
+
+npm/npx launcher for [**codedb**](https://github.com/justrach/codedb) — a Zig code intelligence MCP server.
+
+The package name is `codedeebee` (the bare `codedb` name is restricted on npm). The CLI it installs is named `codedb`.
+
+## Quick start
+
+```sh
+npx -y codedeebee mcp
+```
+
+Or install once:
+
+```sh
+npm install -g codedeebee
+codedb mcp
+```
+
+## MCP client config
+
+### Claude Code / Cursor / opencode
+
+```json
+{
+  "codedb": {
+    "type": "local",
+    "command": ["npx", "-y", "codedeebee"],
+    "args": ["mcp"],
+    "enabled": true
+  }
+}
+```
+
+### Claude Desktop
+
+```json
+{
+  "mcpServers": {
+    "codedb": {
+      "command": "npx",
+      "args": ["-y", "codedeebee", "mcp"]
+    }
+  }
+}
+```
+
+## How it works
+
+`postinstall` downloads the matching native binary from the corresponding [GitHub Release](https://github.com/justrach/codedb/releases) and verifies it against `checksums.sha256`. The `codedb` command is a thin Node launcher that execs the native binary, preserving `cwd`, stdio, args, and environment.
+
+## Supported platforms
+
+| OS     | Arch                 |
+|--------|----------------------|
+| macOS  | arm64, x64 (Intel)   |
+| Linux  | arm64, x64           |
+
+Windows is not yet supported. Comment on [issue #501](https://github.com/justrach/codedb/issues/501) if you need it.
+
+## Skipping the binary download
+
+For sandboxed installs (or environments without GitHub access), set `CODEDEEBEE_SKIP_POSTINSTALL=1`. The package will install successfully but `codedb` will exit until a binary is placed at `node_modules/codedeebee/vendor/codedb`.
+
+## Links
+
+- Source: https://github.com/justrach/codedb
+- Issues: https://github.com/justrach/codedb/issues
+- Releases: https://github.com/justrach/codedb/releases

npm/bin/codedb.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+"use strict";
+
+const { spawnSync } = require("node:child_process");
+const fs = require("node:fs");
+const path = require("node:path");
+
+const exeName = process.platform === "win32" ? "codedb.exe" : "codedb";
+const binPath = path.join(__dirname, "..", "vendor", exeName);
+
+if (!fs.existsSync(binPath)) {
+  process.stderr.write(
+    `codedb: native binary not found at ${binPath}\n` +
+      `       the postinstall step may have failed. Re-run:\n` +
+      `         npm rebuild codedeebee\n` +
+      `       or reinstall:\n` +
+      `         npm install -g codedeebee\n`
+  );
+  process.exit(1);
+}
+
+const result = spawnSync(binPath, process.argv.slice(2), {
+  stdio: "inherit",
+  cwd: process.cwd(),
+  env: process.env,
+});
+
+if (result.error) {
+  process.stderr.write(`codedb: failed to spawn ${binPath}: ${result.error.message}\n`);
+  process.exit(1);
+}
+
+process.exit(result.status ?? 1);

npm/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "codedeebee",
+  "version": "0.2.5821",
+  "description": "Zig code intelligence MCP server — npx launcher for the codedb native binary",
+  "license": "MIT",
+  "author": "justrach",
+  "homepage": "https://github.com/justrach/codedb",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/justrach/codedb.git"
+  },
+  "bugs": {
+    "url": "https://github.com/justrach/codedb/issues"
+  },
+  "bin": {
+    "codedb": "bin/codedb.js"
+  },
+  "files": [
+    "bin/",
+    "scripts/",
+    "README.md"
+  ],
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "codedb",
+    "mcp",
+    "code-intelligence",
+    "zig",
+    "code-search"
+  ],
+  "os": [
+    "darwin",
+    "linux"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ]
+}