weavatrix 0.1.1 → 0.1.2

package/README.md

@@ -5,8 +5,8 @@
 Grep sees text. Weavatrix sees structure. It builds a dependency graph of any local repository —
 files, symbols, and the imports/calls/inheritance connecting them — and serves it to Claude Code,
 Codex, or any MCP client: change impact, transitive dependents, health audit, clone detection,
-coverage mapping. **23 tools. One server for every repo on your machine. Local-first: your code
-never leaves it.**
+coverage mapping. **23 tools available; 21 offline tools enabled by default, including one-call
+repository switching. Local-first: with the defaults, no repository data leaves your machine.**
 
 - Website: [weavatrix.com](https://weavatrix.com)
 - Source: [github.com/sergii-ziborov/weavatrix](https://github.com/sergii-ziborov/weavatrix)
@@ -32,7 +32,7 @@ answers grep can't produce:
 Requires Node ≥ 18. One command:
 
 ```sh
-# Claude Code — one user-level registration serves every repo on the machine:
+# Claude Code — offline default; open_repo can switch local repositories:
 claude mcp add -s user weavatrix -- npx -y weavatrix <repoRoot>
 ```
 
@@ -51,6 +51,20 @@ startup_timeout_sec = 20
 tool_timeout_sec = 60
 ```
 
+The default includes offline repository switching but excludes every network tool. Pass a final
+comma-separated capability list only to restrict or extend it:
+
+```sh
+# Pin the registration to one repository (hide open_repo/list_known_repos):
+claude mcp add -s user weavatrix -- npx -y weavatrix <repoRoot> graph,search,source,health,build
+
+# Add network tools while pinning one repository:
+claude mcp add -s user weavatrix -- npx -y weavatrix <repoRoot> graph,search,source,health,build,online
+
+# Add network tools and keep the default repository switching:
+claude mcp add -s user weavatrix -- npx -y weavatrix <repoRoot> graph,search,source,health,build,retarget,online
+```
+
 Or clone it:
 
 ```sh
@@ -63,9 +77,10 @@ claude mcp add -s user weavatrix -- node <path-to>/weavatrix/bin/weavatrix-mcp.m
   (`<repoRoot-parent>/weavatrix-graphs/<repoName>/graph.json`). Pass an explicit
   `<graph.json> <repoRoot>` pair instead if you keep graphs elsewhere.
 
-No graph yet? Just ask the agent to call `rebuild_graph` (or `open_repo`) — it builds missing
-graphs itself. From then on, `open_repo` retargets the same running server at **any** other local
-repository; never register a second copy.
+No graph yet? Ask the agent to call `rebuild_graph`; it builds the missing graph locally. When the
+`open_repo` can change the active repository and build its graph. Retargeting is offline but
+intentionally changes the filesystem boundary for subsequent tools; omit `retarget` from an explicit
+capability list when a registration must stay pinned to one repository.
 
 An agent skill with recipes ships in [skill/SKILL.md](skill/SKILL.md) — install as
 `~/.claude/skills/weavatrix/SKILL.md`.
@@ -74,7 +89,7 @@ An agent skill with recipes ships in [skill/SKILL.md](skill/SKILL.md) — instal
 
 **graph** — `graph_stats`, `get_node`, `get_neighbors`, `query_graph`, `god_nodes`,
 `shortest_path`, `get_community`, `list_communities`, `module_map`, `get_dependents`,
-`change_impact`, `graph_diff`, `list_known_repos`
+`change_impact`, `graph_diff`
 
 **search / source** — `search_code` (ripgrep-backed, pure-Node fallback), `read_source` (a
 symbol's actual code in one hop), `list_endpoints` (HTTP route inventory:
@@ -87,7 +102,10 @@ cycles, orphans, boundary rules, offline OSV vulnerabilities + typosquat + lockf
 connectivity — tests are never executed)
 
 **build** — `rebuild_graph` (reports the structural delta, keeps the prior state as
-`graph.prev.json`), `open_repo`
+`graph.prev.json`)
+
+**retarget** *(enabled by default, offline, explicit tool call)* — `open_repo`, `list_known_repos`;
+changes the active repository boundary
 
 **online** *(explicit opt-in — see Privacy)* — `refresh_advisories`, `sync_graph`
 
@@ -97,18 +115,41 @@ files under `src/mcp/` change — no reconnect needed.
 
 ## Privacy: local-first, offline by design
 
-Graph queries, audits and clone scans run in-process against local files. Exactly two tools can
-touch the network, both in the `online` capability group and both inert until explicitly invoked:
+Graph queries, audits, clone scans and repository switching run locally. The default capability set
+is `graph,search,source,health,build,retarget`: no Weavatrix HTTP requests. `open_repo` changes the
+active local boundary only when called. Weavatrix itself initiates outbound HTTP only from two
+tools; both require the explicit `online` group and a tool call:
 
 - `refresh_advisories` — queries [OSV.dev](https://osv.dev) with your lockfile's package
   **names + versions** (that is what an OSV query is; never source code) and caches the advisories
   in `~/.weavatrix/advisories.json`. `run_audit` then matches against that store fully offline.
-- `sync_graph` — pushes `graph.json` (file paths, symbol names, edges — never file contents) to an
-  endpoint **you** configure via `WEAVATRIX_SYNC_URL` / `WEAVATRIX_SYNC_TOKEN`. Off by default.
-
-Capability groups (`graph`, `search`, `source`, `health`, `build`, `online`) are selectable per
-registration via a fifth argument — a comma-separated list. Omit `online` from it and those tools
-don't exist for that client.
+- `sync_graph` — constructs a versioned, allowlisted payload from `graph.json`: relative paths,
+  symbol names and line ranges, import/dependency identifiers, edges and numeric metrics. Unknown
+  fields are discarded; source file bodies are never read for sync or included in the payload. The
+  endpoint is **yours**, configured via `WEAVATRIX_SYNC_URL` / `WEAVATRIX_SYNC_TOKEN`. Off by default.
+  Graphs built before `0.1.2` must be rebuilt once before syncing.
+
+Capability groups (`graph`, `search`, `source`, `health`, `build`, `retarget`, `online`) are
+selectable through the final positional argument. Omitted caps use the safe default above; an
+explicit list exposes exactly the named groups.
+
+## Security model
+
+Socket capability alerts describe expected powers of a local code-analysis tool; they are not
+vulnerability findings. This is where each capability comes from and how it is controlled:
+
+| Capability alert | Why it exists | Activation and boundary |
+|---|---|---|
+| Network access | `refresh_advisories` sends pinned package names and versions to OSV; `sync_graph` sends a versioned allowlist of graph metadata (relative paths, symbols and line ranges, import/dependency identifiers, edges and numeric metrics). It discards unknown graph fields and does not read source file bodies | `online` is disabled by default; each request requires a tool call, and sync additionally requires `WEAVATRIX_SYNC_URL` |
+| Shell access | Local `git` powers staleness/change impact; `rg` accelerates search; timed-out Windows child processes may be terminated | Used only by the corresponding local operation; it does not imply network access |
+| Debug / dynamic loading | Cache-busted `import()` hot-reloads local MCP tool modules; `createRequire` loads package metadata and parser dependencies | Loads files from the installed package; no `eval` |
+| Environment access | Reads `WEAVATRIX_*` configuration; local child processes inherit the normal host environment | `WEAVATRIX_SYNC_TOKEN` is removed from every child-process and worker environment and read only by `sync_graph` |
+| Filesystem access | Reads the active repository, graph, lockfiles and coverage reports; writes derived graphs and advisory cache | Realpath containment blocks traversal and symlink/junction escapes. `open_repo` is an explicit offline call that changes the active boundary; omit `retarget` in a custom capability list to pin one repository. The optional malware dependency scan may inspect installed dependency caches such as GOPATH |
+| URL strings | Fixed OSV/documentation URLs plus a user-configured sync URL | A URL string causes no request by itself; only the two `online` tools perform requests |
+
+`read_source` accepts repo-relative regular files only, caps a read at 2 MB, and refuses lexical or
+realpath escapes. Graph-derived paths pass through the same boundary before analysis tools read
+them. Report suspected vulnerabilities privately as described in [SECURITY.md](SECURITY.md).
 
 ## Languages
 

package/SECURITY.md

@@ -0,0 +1,31 @@
+# Security Policy
+
+## Supported versions
+
+Security fixes are provided for the latest published version of Weavatrix. Upgrade to the newest
+release before reporting an issue that may already be resolved.
+
+## Reporting a vulnerability
+
+Please do not open a public issue for a suspected vulnerability. Use GitHub's private vulnerability
+reporting flow:
+
+https://github.com/sergii-ziborov/weavatrix/security/advisories/new
+
+Include the affected Weavatrix version, operating system, MCP client, enabled capability groups,
+reproduction steps, expected boundary, observed behavior, and potential impact. Avoid including real
+credentials, private source code, or other sensitive data in the report.
+
+Reports will be investigated privately. Public disclosure should be coordinated after a fix or
+mitigation is available so users have a reasonable opportunity to update.
+
+## Security boundaries
+
+The default MCP registration is offline. Every standard source, manifest, configuration and coverage
+read is canonical-path-contained within the active repository and rejects traversal plus symlink or
+junction escapes. The optional malware dependency scan may inspect installed dependency caches such
+as GOPATH. The default `retarget` capability exposes `open_repo`, an explicit offline tool call that
+intentionally changes the active repository; omit that group in a custom capability list to pin one
+boundary. The optional `online` capability contains Weavatrix's HTTP tools; `sync_graph`
+additionally requires a user-configured endpoint and sends only a versioned metadata allowlist,
+discarding unknown fields from the local graph cache.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "weavatrix",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "type": "module",
   "description": "Weavatrix — code graph & blast-radius MCP server for AI coding agents: change impact, transitive dependents, health audit, duplicate detection, and coverage mapping over any local repository.",
   "author": "Sergii Ziborov <sergii@edgehawk.io>",
@@ -25,10 +25,16 @@
     "src",
     "skill",
     "README.md",
+    "SECURITY.md",
     "LICENSE"
   ],
   "scripts": {
-    "test": "node --test"
+    "test": "node --test",
+    "build:mcpb": "node scripts/build-mcpb.mjs",
+    "verify:release": "node scripts/verify-release.mjs"
+  },
+  "publishConfig": {
+    "access": "public"
   },
   "keywords": [
     "mcp",
@@ -44,7 +50,13 @@
     "ai-agents"
   ],
   "dependencies": {
-    "tree-sitter-wasms": "^0.1.13",
-    "web-tree-sitter": "^0.25.3"
+    "tree-sitter-wasms": "0.1.13",
+    "web-tree-sitter": "0.25.10"
+  },
+  "devDependencies": {
+    "@anthropic-ai/mcpb": "2.1.2"
+  },
+  "overrides": {
+    "tmp": "0.2.7"
   }
 }

package/skill/SKILL.md

@@ -5,9 +5,9 @@ description: Drive the weavatrix MCP — code graph, blast-radius (get_dependent
 
 # weavatrix MCP
 
-Structure-analysis tools over a prebuilt code graph plus the weavatrix analysis engines. One running
-server handles ANY local repository via `open_repo` — never register a second weavatrix server for a
-sibling repo.
+Structure-analysis tools over a prebuilt code graph plus the weavatrix analysis engines. The default
+is offline and includes `open_repo` for one-call switching between local Git repositories. A custom
+capability list that omits `retarget` pins the registration to its initial repository.
 
 ## Step 0 — if the tools are missing
 
@@ -24,13 +24,18 @@ Tools are named `mcp__weavatrix__…`. If none are available, ask the user to re
 - **Offline by design**: scans and graph queries run in-process against local files; coverage tools
   read existing reports and never run tests. The ONLY network-touching tools live in the `online`
   capability group and run solely when explicitly called: `refresh_advisories` (queries OSV.dev with
-  package names + versions so `run_audit` has fresh vulnerability data) and `sync_graph` (pushes
-  graph.json to a user-configured endpoint; disabled until `WEAVATRIX_SYNC_URL` is set). Registering
-  the server with a caps list that omits `online` removes both.
+  package names + versions so `run_audit` has fresh vulnerability data) and `sync_graph` (pushes a
+  versioned allowlist of graph metadata, discarding unknown fields and never reading source file
+  bodies for sync, to a user-configured endpoint; disabled until
+  `WEAVATRIX_SYNC_URL` is set). `online` is
+  absent from the default capability set and must be enabled explicitly.
+- **Repository boundary**: source reads and graph-derived paths are realpath-contained. `open_repo`
+  intentionally changes the active boundary through an explicit offline tool call. It is available
+  by default; omit `retarget` from a custom capability list to hide it.
 
 ## Recipes
 
-- **Orient in an unfamiliar repo**: `open_repo` → `module_map` → `list_communities` → `god_nodes`.
+- **Orient in the configured repo**: `module_map` → `list_communities` → `god_nodes`.
 - **Refactor safety for one symbol**: `get_dependents` → `coverage_map` (low coverage × many
   dependents ⇒ write tests first) → `read_source`.
 - **Pre-PR review of your current changes**: `change_impact` (auto merge-base; includes uncommitted
@@ -44,12 +49,13 @@ Tools are named `mcp__weavatrix__…`. If none are available, ask the user to re
   `coverage_map`.
 - **API inventory**: `list_endpoints`.
 - **Find code**: `search_code` (regex + glob) → `get_node` → `read_source`.
-- **Another repo**: `list_known_repos` → `open_repo <path>` (builds the graph when missing — minutes
-  on large repos; `build:false` probes without building).
+- **Another repo**: `list_known_repos` → `open_repo <path>`
+  (builds the graph when missing; `build:false` probes without building).
 
 ## Troubleshooting
 
-- `Graph unavailable` → `open_repo` with a valid repo path.
+- `Graph unavailable` → `rebuild_graph`; `open_repo` can select another valid repository path unless
+  the registration deliberately omitted `retarget`.
 - `No coverage report` → run the repo's own tests with coverage (`vitest run --coverage`,
   `jest --coverage`, `pytest --cov --cov-report=json`, `go test -coverprofile=coverage.out`),
   then re-call.

package/src/analysis/coverage-reports.js

@@ -3,6 +3,7 @@
 // graph's known files. Split out of graph-builder-analysis.js (pure except for reading the repo's coverage files).
 import { existsSync, readFileSync } from "node:fs";
 import { join, relative, resolve } from "node:path";
+import { createRepoBoundary } from "../repo-path.js";
 
 export function normRepoPath(value) {
   return String(value || "").replace(/\\/g, "/").replace(/^\.\//, "");
@@ -210,20 +211,22 @@ function parseGoCoverage(map, filePath, knownFiles, repoRoot) {
 export function readCoverageForRepo(repoRoot, knownFiles) {
   const out = new Map();
   if (!repoRoot) return out;
+  const boundary = createRepoBoundary(repoRoot);
   const candidates = [
-    [join(repoRoot, "coverage", "coverage-summary.json"), parseIstanbulSummary],
-    [join(repoRoot, "coverage", "coverage-final.json"), parseIstanbulFinal],
-    [join(repoRoot, "coverage", "lcov.info"), parseLcov],
-    [join(repoRoot, "lcov.info"), parseLcov],
-    [join(repoRoot, "coverage", "coverage.json"), parseCoveragePyJson],
-    [join(repoRoot, "coverage.json"), parseCoveragePyJson],
-    [join(repoRoot, "coverage.out"), parseGoCoverage],
-    [join(repoRoot, "cover.out"), parseGoCoverage]
+    ["coverage/coverage-summary.json", parseIstanbulSummary],
+    ["coverage/coverage-final.json", parseIstanbulFinal],
+    ["coverage/lcov.info", parseLcov],
+    ["lcov.info", parseLcov],
+    ["coverage/coverage.json", parseCoveragePyJson],
+    ["coverage.json", parseCoveragePyJson],
+    ["coverage.out", parseGoCoverage],
+    ["cover.out", parseGoCoverage]
   ];
-  for (const [path, parser] of candidates) {
-    if (!existsSync(path)) continue;
+  for (const [candidate, parser] of candidates) {
+    const resolved = boundary.resolve(candidate);
+    if (!resolved.ok || !existsSync(resolved.path)) continue;
     try {
-      parser(out, path, knownFiles, repoRoot);
+      parser(out, resolved.path, knownFiles, repoRoot);
     } catch {
       /* malformed/foreign coverage report: ignore */
     }

package/src/analysis/dead-check.js

@@ -6,7 +6,7 @@
 // `analyzeDeadCode(graph, repoRoot)` is the thin fs wrapper. Works on ANY graph-builder-schema graph (built-in OR
 // graph-builder) — it only needs {nodes, links} + the source text. See [[graph-builder-internalization]].
 import { readFileSync } from "node:fs";
-import { join } from "node:path";
+import { createRepoBoundary } from "../repo-path.js";
 
 const IDENT_RE = /[A-Za-z_$][\w$]*/g;
 const bareName = (label) => String(label || "").replace(/\s*\(.*$/, "").replace(/[()]/g, "").trim();
@@ -130,7 +130,12 @@ export function computeUnusedExports(graph, sources, { dynamicTargets = new Set(
 export function analyzeDeadCode(graph, repoRoot) {
   const sources = new Map();
   const files = new Set();
+  const boundary = createRepoBoundary(repoRoot);
   for (const n of graph.nodes || []) if (n.source_file) files.add(n.source_file);
-  for (const f of files) { try { sources.set(f, readFileSync(join(repoRoot, f), "utf8")); } catch { /* file gone */ } }
+  for (const f of files) {
+    const resolved = boundary.resolve(f);
+    if (!resolved.ok) continue;
+    try { sources.set(f, readFileSync(resolved.path, "utf8")); } catch { /* file gone */ }
+  }
   return computeDead(graph, sources);
 }