deadzone

Documentation

Overview

Command deadzone is the single CLI entry point for the deadzone toolchain. It dispatches a leading verb to one of five subcommand runners living alongside this file:

deadzone server        run the MCP stdio server against a deadzone.db
deadzone scrape        index libraries_sources.yaml into ./artifacts
deadzone consolidate   merge ./artifacts/<slug>/artifact.db into a single deadzone.db
deadzone fetch-db      download/refresh the cached deadzone.db from the latest GH Release
deadzone dbrelease     upload ./deadzone.db to a tagged GitHub Release

Top-level `--version` short-circuits before any embedder/DB load so the smoke test in release.yml can call it on a stock runner with no model cache and no DB on disk. Per-subcommand `--version` is not supported — the single top-level banner is enough for the smoke test and keeps each subcommand's flag surface focused on its own knobs.

Routing is a `spf13/cobra` rootCmd with one child `*cobra.Command` per sibling file, wired in that file's init(). See issue #134 for the migration rationale: sub-subcommand ergonomics and built-in shell completion outgrew the stdlib `flag` + `os.Args` switch.

Parallelism model for `deadzone scrape` (see #93). The outer loop over resolved libraries runs concurrently, bounded per kind by two independent semaphores:

• github-md and github-rst libs are pure HTTP and safe to run N-wide in parallel. Both kinds share the --parallel-github-md bound (default 4; env DEADZONE_SCRAPE_PARALLEL_GITHUB_MD) since they have identical I/O characteristics — see #95 for the choice to reuse the existing flag rather than introduce a per-kind one.
• scrape-via-agent libs share one LLM endpoint that is usually single-threaded on consumer hardware (oMLX, Ollama). Default concurrency is 1 to preserve today's behavior; raise it with --parallel-scrape-via-agent or DEADZONE_SCRAPE_PARALLEL_SCRAPE_VIA_AGENT when pointed at a concurrent backend (vLLM, OpenAI).

Per-URL semantics (soft-skip + skipped_ceiling, see #63) are unchanged; only the lib-level orchestration is parallel. Errors are aggregated continue-on-error style: one lib's failure no longer aborts the rest, and the process exits 1 iff at least one lib failed.