verify

name	verify
description	How to run and observe the cave CLI and MCP server end-to-end when verifying a change in this repo — build-free launch, driving cave commands against a scratch store, and exercising the MCP stdio surface with raw JSON-RPC lines.

Verifying changes in this repo

No build is needed for source-level verification: pnpm install links workspace packages and puts cave on the workspace path (node_modules/.bin/cave runs TypeScript directly via Node ≥ 22.18 type stripping). Release and CI validation still run the emitting pnpm build described in IMPLEMENTATION.md. Everything here is driven through the real CLI against a scratch --db:

export PATH="$PWD/node_modules/.bin:$PATH"
cd "$(mktemp -d)"
cave version
printf 'api IS service\n' | cave add --db k.db
cave query --db k.db '?x IS service'
cave export --db k.db          # canonical text incl. BECAUSE/VIA lineage

Node's SQLite ExperimentalWarning on stderr is noise — filter it, don't chase it.

The MCP server is plain newline-delimited JSON-RPC on stdio, so it can be driven by piping lines — no client needed; it exits when stdin closes:

printf '%s\n' \
 '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"t","version":"0"}}}' \
 '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
 '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"cave_query","arguments":{"pattern":"?x IS service"}}}' \
 | cave mcp --db k.db 2>/dev/null

The read surface (cave serve, spec §30) is verifiable headlessly: start it on --port 0 in the background, scrape the printed URL from its log, then curl the page and the /api/* endpoints; the pre-installed Chromium (--headless --screenshot=out.png <url>) renders the page's client-side views for visual checks:

cave serve --db k.db --port 0 > serve.log 2>&1 &
url=$(until grep -qo 'http://[^ ]*/' serve.log; do sleep 0.1; done; grep -o 'http://[^ ]*/' serve.log | head -1)
curl -s "${url}api/overview"
kill %1

Gotchas:

• exit codes: check $? on the cave command directly — piping through grep to drop warnings clobbers it (use >out 2>err and inspect the files, or PIPESTATUS);
• hook/agent shell templates (cave act --hooks, cave ingest --agent, cave automate --hooks/--agent) can be observed with a node -e command that writes its argv and stdin to a file — portable, no shell quoting surprises;
• cave highlight, cave export colors, and the tree-sitter/VSCode packages need tree-sitter-cave.wasm, generated by the tree-sitter-cli binary that downloads from GitHub releases — in sandboxes that block those downloads the three grammar-adjacent surfaces (tree-sitter-cave, highlight, the cli highlight test) are unverifiable; say so rather than fighting it.