@swarmvaultai/cli 0.1.18 → 0.1.21

package/README.md

@@ -26,13 +26,21 @@ swarmvault init --obsidian
 sed -n '1,120p' swarmvault.schema.md
 swarmvault ingest ./notes.md
 swarmvault ingest ./repo
+swarmvault add https://arxiv.org/abs/2401.12345
 swarmvault compile
+swarmvault benchmark
 swarmvault query "What keeps recurring?"
 swarmvault query "Turn this into slides" --format slides
 swarmvault explore "What should I research next?" --steps 3
 swarmvault lint --deep
+swarmvault graph query "Which nodes bridge the biggest clusters?"
+swarmvault graph explain "concept:drift"
+swarmvault watch status
+swarmvault watch --repo --once
+swarmvault hook install
 swarmvault graph serve
 swarmvault graph export --html ./exports/graph.html
+swarmvault graph export --cypher ./exports/graph.cypher
 ```
 
 ## Commands
@@ -62,6 +70,7 @@ Ingest a local file path, directory path, or URL into immutable source storage a
 - directory ingest respects `.gitignore` unless you pass `--no-gitignore`
 - repo-aware directory ingest records `repoRelativePath` and later compile writes `state/code-index.json`
 - URL ingest still localizes remote image references by default
+- code-aware directory ingest currently covers JavaScript, TypeScript, Python, Go, Rust, Java, C#, C, C++, PHP, Ruby, and PowerShell
 
 Useful flags:
 
@@ -73,6 +82,15 @@ Useful flags:
 - `--no-include-assets`
 - `--max-asset-size <bytes>`
 
+### `swarmvault add <url>`
+
+Capture supported URLs through a normalized markdown layer before ingesting them into the vault.
+
+- arXiv abstract URLs and bare arXiv ids become durable markdown captures
+- X/Twitter URLs use a graceful public capture path
+- unsupported URLs fall back to generic URL ingest instead of failing
+- optional metadata: `--author <name>` and `--contributor <name>`
+
 ### `swarmvault inbox import [dir]`
 
 Import supported files from the configured inbox directory. This is meant for browser-clipper style markdown bundles and other capture workflows. Local image and asset references are preserved and copied into canonical storage under `raw/assets/`.
@@ -93,6 +111,14 @@ New concept and entity pages are staged into `wiki/candidates/` first. A later m
 
 With `--approve`, compile writes a staged review bundle into `state/approvals/` without applying active wiki changes.
 
+### `swarmvault benchmark [--question "<text>" ...]`
+
+Measure graph-guided context reduction against a naive full-corpus read.
+
+- writes the latest result to `state/benchmark.json`
+- updates `wiki/graph/report.md` with the current benchmark summary
+- accepts repeatable `--question` inputs for vault-specific benchmarks
+
 ### `swarmvault review list|show|accept|reject`
 
 Inspect and resolve staged approval bundles created by `swarmvault compile --approve`.
@@ -156,9 +182,25 @@ Run anti-drift and vault health checks such as stale pages, missing graph artifa
 
 `--web` can only be used with `--deep`. It enriches deep-lint findings with external evidence snippets and URLs from a configured web-search provider.
 
-### `swarmvault watch [--lint] [--debounce <ms>]`
+### `swarmvault watch [--lint] [--repo] [--once] [--debounce <ms>]`
+
+Watch the inbox directory and trigger import and compile cycles when files change. With `--repo`, each cycle also refreshes tracked repo roots that were previously ingested through directory ingest. With `--once`, SwarmVault runs one refresh cycle immediately instead of starting a long-running watcher. With `--lint`, each cycle also runs linting. Each cycle writes a canonical session artifact to `state/sessions/`, and compatibility run metadata is still appended to `state/jobs.ndjson`.
+
+When `--repo` sees non-code changes under tracked repo roots, SwarmVault records those files under `state/watch/pending-semantic-refresh.json`, marks affected compiled pages stale, and exposes the pending set through `watch status` and the local graph workspace instead of silently re-ingesting them.
+
+### `swarmvault watch status`
+
+Show watched repo roots, the latest watch run, and any pending semantic refresh entries for tracked non-code repo changes.
+
+### `swarmvault hook install|uninstall|status`
+
+Manage SwarmVault's local git hook blocks for the nearest git repository.
+
+- `hook install` writes marker-based `post-commit` and `post-checkout` hooks
+- `hook uninstall` removes only the SwarmVault-managed hook block
+- `hook status` reports whether those managed hook blocks are installed
 
-Watch the inbox directory and trigger import and compile cycles when files change. With `--lint`, each cycle also runs linting. Each cycle writes a canonical session artifact to `state/sessions/`, and compatibility run metadata is still appended to `state/jobs.ndjson`.
+The installed hooks run `swarmvault watch --repo --once` from the vault root so repo-aware source changes are re-ingested and recompiled after commit and checkout.
 
 ### `swarmvault mcp`
 
@@ -177,16 +219,43 @@ The MCP surface also exposes `swarmvault://schema`, `swarmvault://sessions`, `sw
 
 ### `swarmvault graph serve`
 
-Start the local graph workspace backed by `state/graph.json`, `/api/search`, and `/api/page`.
+Start the local graph workspace backed by `state/graph.json`, `/api/search`, `/api/page`, and local graph query/path/explain endpoints.
 
-### `swarmvault graph export --html <output>`
+### `swarmvault graph query "<question>" [--dfs] [--budget <n>]`
 
-Export the graph workspace as a standalone HTML file with embedded graph and page data for offline sharing.
+Run a deterministic local graph traversal seeded from local search and graph labels.
+
+### `swarmvault graph path <from> <to>`
+
+Return the shortest high-confidence path between two graph targets.
+
+### `swarmvault graph explain <target>`
+
+Inspect graph metadata, community membership, neighbors, and provenance for a node or page.
+
+### `swarmvault graph god-nodes [--limit <n>]`
+
+List the most connected bridge-heavy nodes in the current graph.
+
+### `swarmvault graph export --html|--svg|--graphml|--cypher <output>`
+
+Export the current graph as one of four formats:
+
+- `--html` for the standalone read-only graph workspace
+- `--svg` for a static shareable diagram
+- `--graphml` for graph-tool interoperability
+- `--cypher` for Neo4j-style import scripts
 
 ### `swarmvault install --agent <codex|claude|cursor|goose|pi|gemini|opencode>`
 
 Install agent-specific rules into the current project so an agent understands the SwarmVault workspace contract and workflow.
 
+For Claude Code, you can also install the recommended graph-first pre-search hook:
+
+```bash
+swarmvault install --agent claude --hook
+```
+
 ## Provider Configuration
 
 SwarmVault defaults to a local `heuristic` provider so the CLI works without API keys, but real vaults will usually point at an actual model provider.

package/dist/index.js

@@ -5,28 +5,40 @@ import { readFileSync } from "fs";
 import process from "process";
 import {
   acceptApproval,
+  addInput,
   archiveCandidate,
+  benchmarkVault,
   compileVault,
+  explainGraphVault,
   exploreVault,
+  exportGraphFormat,
   exportGraphHtml,
+  getGitHookStatus,
+  getWatchStatus,
   importInbox,
   ingestDirectory,
   ingestInput,
   initVault,
   installAgent,
+  installGitHooks,
   lintVault,
   listApprovals,
   listCandidates,
+  listGodNodes,
   listSchedules,
   loadVaultConfig,
+  pathGraphVault,
   promoteCandidate,
+  queryGraphVault,
   queryVault,
   readApproval,
   rejectApproval,
   runSchedule,
+  runWatchCycle,
   serveSchedules,
   startGraphServer,
   startMcpServer,
+  uninstallGitHooks,
   watchVault
 } from "@swarmvaultai/engine";
 import { Command, Option } from "commander";
@@ -36,9 +48,9 @@ program.name("swarmvault").description("SwarmVault is a local-first LLM wiki com
 function readCliVersion() {
   try {
     const packageJson = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
-    return typeof packageJson.version === "string" && packageJson.version.trim() ? packageJson.version : "0.1.18";
+    return typeof packageJson.version === "string" && packageJson.version.trim() ? packageJson.version : "0.1.21";
   } catch {
-    return "0.1.18";
+    return "0.1.21";
   }
 }
 function isJson() {
@@ -99,6 +111,17 @@ program.command("ingest").description("Ingest a local file path, directory path,
     }
   }
 );
+program.command("add").description("Capture supported URLs into normalized markdown before ingesting them.").argument("<input>", "Supported URL or bare arXiv id").option("--author <name>", "Human author or curator for this capture").option("--contributor <name>", "Additional contributor metadata for this capture").action(async (input, options) => {
+  const result = await addInput(process.cwd(), input, {
+    author: options.author,
+    contributor: options.contributor
+  });
+  if (isJson()) {
+    emitJson(result);
+  } else {
+    log(`${result.captureType}${result.fallback ? " (fallback)" : ""}: ${result.manifest.sourceId}`);
+  }
+});
 var inbox = program.command("inbox").description("Inbox and capture workflows.");
 inbox.command("import").description("Import supported files from the configured inbox directory.").argument("[dir]", "Optional inbox directory override").action(async (dir) => {
   const result = await importInbox(process.cwd(), dir);
@@ -155,6 +178,18 @@ program.command("explore").description("Run a save-first multi-step exploration
     log(`Completed ${result.stepCount} step(s).`);
   }
 });
+program.command("benchmark").description("Measure graph-guided context reduction against a naive full-corpus read.").option("--question <text...>", "Optional custom benchmark question(s)").action(async (options) => {
+  const result = await benchmarkVault(process.cwd(), {
+    questions: options.question
+  });
+  if (isJson()) {
+    emitJson(result);
+  } else {
+    log(`Corpus tokens: ${result.corpusTokens}`);
+    log(`Average query tokens: ${result.avgQueryTokens}`);
+    log(`Reduction ratio: ${(result.reductionRatio * 100).toFixed(1)}%`);
+  }
+});
 program.command("lint").description("Run anti-drift and wiki-health checks.").option("--deep", "Run LLM-powered advisory lint", false).option("--web", "Augment deep lint with configured web search", false).action(async (options) => {
   const findings = await lintVault(process.cwd(), {
     deep: options.deep ?? false,
@@ -186,12 +221,61 @@ graph.command("serve").description("Serve the local graph viewer.").option("--po
     process.exit(0);
   });
 });
-graph.command("export").description("Export the graph viewer as a single self-contained HTML file.").requiredOption("--html <output>", "Output HTML file path").action(async (options) => {
-  const outputPath = await exportGraphHtml(process.cwd(), options.html);
+graph.command("export").description("Export the graph as HTML, SVG, GraphML, or Cypher.").option("--html <output>", "Output HTML file path").option("--svg <output>", "Output SVG file path").option("--graphml <output>", "Output GraphML file path").option("--cypher <output>", "Output Cypher file path").action(async (options) => {
+  const targets = [
+    options.html ? { format: "html", outputPath: options.html } : null,
+    options.svg ? { format: "svg", outputPath: options.svg } : null,
+    options.graphml ? { format: "graphml", outputPath: options.graphml } : null,
+    options.cypher ? { format: "cypher", outputPath: options.cypher } : null
+  ].filter((target2) => Boolean(target2));
+  if (targets.length !== 1) {
+    throw new Error("Pass exactly one of --html, --svg, --graphml, or --cypher.");
+  }
+  const target = targets[0];
+  const outputPath = target.format === "html" ? await exportGraphHtml(process.cwd(), target.outputPath) : (await exportGraphFormat(process.cwd(), target.format, target.outputPath)).outputPath;
   if (isJson()) {
-    emitJson({ outputPath });
+    emitJson({ format: target.format, outputPath });
   } else {
-    log(`Exported graph HTML to ${outputPath}`);
+    log(`Exported graph ${target.format} to ${outputPath}`);
+  }
+});
+graph.command("query").description("Traverse the compiled graph deterministically from local search seeds.").argument("<question>", "Question or graph search seed").option("--dfs", "Prefer a depth-first traversal instead of breadth-first", false).option("--budget <n>", "Maximum number of graph nodes to summarize").action(async (question, options) => {
+  const budget = options.budget ? Number.parseInt(options.budget, 10) : void 0;
+  const result = await queryGraphVault(process.cwd(), question, {
+    traversal: options.dfs ? "dfs" : "bfs",
+    budget: Number.isFinite(budget) ? budget : void 0
+  });
+  if (isJson()) {
+    emitJson(result);
+    return;
+  }
+  log(result.summary);
+});
+graph.command("path").description("Find the shortest graph path between two nodes or pages.").argument("<from>", "Source node/page label or id").argument("<to>", "Target node/page label or id").action(async (from, to) => {
+  const result = await pathGraphVault(process.cwd(), from, to);
+  if (isJson()) {
+    emitJson(result);
+    return;
+  }
+  log(result.summary);
+});
+graph.command("explain").description("Explain a graph node, its page, community, and neighbors.").argument("<target>", "Node/page label or id").action(async (target) => {
+  const result = await explainGraphVault(process.cwd(), target);
+  if (isJson()) {
+    emitJson(result);
+    return;
+  }
+  log(result.summary);
+});
+graph.command("god-nodes").description("List the highest-connectivity non-source graph nodes.").option("--limit <n>", "Maximum number of nodes to return", "10").action(async (options) => {
+  const limit = Number.parseInt(options.limit ?? "10", 10);
+  const result = await listGodNodes(process.cwd(), Number.isFinite(limit) ? limit : 10);
+  if (isJson()) {
+    emitJson(result);
+    return;
+  }
+  for (const node of result) {
+    log(`${node.label} degree=${node.degree ?? 0} bridge=${node.bridgeScore ?? 0}`);
   }
 });
 var review = program.command("review").description("Review staged compile approval bundles.");
@@ -269,23 +353,94 @@ candidate.command("archive").description("Archive a candidate by removing it fro
     log(`Archived ${result.pageId}`);
   }
 });
-program.command("watch").description("Watch the inbox directory and run import/compile cycles on changes.").option("--lint", "Run lint after each compile cycle", false).option("--debounce <ms>", "Debounce window in milliseconds", "900").action(async (options) => {
+var watch = program.command("watch").description("Watch the inbox directory and optionally tracked repos, or run one refresh cycle immediately.").option("--lint", "Run lint after each compile cycle", false).option("--repo", "Also refresh tracked repo sources and watch their repo roots", false).option("--once", "Run one import/refresh cycle immediately instead of starting a watcher", false).option("--debounce <ms>", "Debounce window in milliseconds", "900").action(async (options) => {
   const debounceMs = Number.parseInt(options.debounce ?? "900", 10);
+  if (options.once) {
+    const result = await runWatchCycle(process.cwd(), {
+      lint: options.lint ?? false,
+      repo: options.repo ?? false,
+      debounceMs: Number.isFinite(debounceMs) ? debounceMs : 900
+    });
+    if (isJson()) {
+      emitJson(result);
+    } else {
+      log(
+        `Refreshed inbox${options.repo ? " and tracked repos" : ""}. Imported ${result.importedCount}, repo imported ${result.repoImportedCount}, repo updated ${result.repoUpdatedCount}, repo removed ${result.repoRemovedCount}.`
+      );
+    }
+    return;
+  }
   const { paths } = await loadVaultConfig(process.cwd());
   const controller = await watchVault(process.cwd(), {
     lint: options.lint ?? false,
+    repo: options.repo ?? false,
     debounceMs: Number.isFinite(debounceMs) ? debounceMs : 900
   });
   if (isJson()) {
-    emitJson({ status: "watching", inboxDir: paths.inboxDir });
+    emitJson({ status: "watching", inboxDir: paths.inboxDir, repo: options.repo ?? false });
   } else {
-    log("Watching inbox for changes. Press Ctrl+C to stop.");
+    log(`Watching inbox${options.repo ? " and tracked repos" : ""} for changes. Press Ctrl+C to stop.`);
   }
   process.on("SIGINT", async () => {
     await controller.close();
     process.exit(0);
   });
 });
+watch.command("status").description("Show the latest watch run plus pending semantic refresh entries.").action(async () => {
+  const result = await getWatchStatus(process.cwd());
+  if (isJson()) {
+    emitJson(result);
+    return;
+  }
+  log(`Watched repo roots: ${result.watchedRepoRoots.length}`);
+  log(`Pending semantic refresh: ${result.pendingSemanticRefresh.length}`);
+  for (const entry of result.pendingSemanticRefresh.slice(0, 8)) {
+    log(`- ${entry.changeType} ${entry.path}`);
+  }
+});
+program.command("watch-status").description("Show the latest watch run plus pending semantic refresh entries.").action(async () => {
+  const result = await getWatchStatus(process.cwd());
+  if (isJson()) {
+    emitJson(result);
+    return;
+  }
+  log(`Watched repo roots: ${result.watchedRepoRoots.length}`);
+  log(`Pending semantic refresh: ${result.pendingSemanticRefresh.length}`);
+  for (const entry of result.pendingSemanticRefresh.slice(0, 8)) {
+    log(`- ${entry.changeType} ${entry.path}`);
+  }
+});
+var hook = program.command("hook").description("Install local git hooks that keep tracked repos and the vault in sync.");
+hook.command("install").description("Install post-commit and post-checkout hooks for the nearest git repository.").action(async () => {
+  const status = await installGitHooks(process.cwd());
+  if (isJson()) {
+    emitJson(status);
+    return;
+  }
+  log(`Installed hooks in ${status.repoRoot}`);
+});
+hook.command("uninstall").description("Remove the SwarmVault-managed git hook blocks from the nearest git repository.").action(async () => {
+  const status = await uninstallGitHooks(process.cwd());
+  if (isJson()) {
+    emitJson(status);
+    return;
+  }
+  log(`Removed SwarmVault hook blocks from ${status.repoRoot ?? "the current workspace"}`);
+});
+hook.command("status").description("Show whether SwarmVault-managed git hooks are installed.").action(async () => {
+  const status = await getGitHookStatus(process.cwd());
+  if (isJson()) {
+    emitJson(status);
+    return;
+  }
+  if (!status.repoRoot) {
+    log("No git repository found.");
+    return;
+  }
+  log(`repo=${status.repoRoot}`);
+  log(`post-commit=${status.postCommit}`);
+  log(`post-checkout=${status.postCheckout}`);
+});
 var schedule = program.command("schedule").description("Run scheduled vault maintenance jobs.");
 schedule.command("list").description("List configured schedule jobs and their next run state.").action(async () => {
   const schedules = await listSchedules(process.cwd());
@@ -337,10 +492,13 @@ program.command("mcp").description("Run SwarmVault as a local MCP server over st
     process.exit(0);
   });
 });
-program.command("install").description("Install SwarmVault instructions for an agent in the current project.").requiredOption("--agent <agent>", "codex, claude, cursor, goose, pi, gemini, or opencode").action(async (options) => {
-  const target = await installAgent(process.cwd(), options.agent);
+program.command("install").description("Install SwarmVault instructions for an agent in the current project.").requiredOption("--agent <agent>", "codex, claude, cursor, goose, pi, gemini, or opencode").option("--hook", "Also install the recommended Claude pre-search hook when agent=claude", false).action(async (options) => {
+  if (options.hook && options.agent !== "claude") {
+    throw new Error("--hook is only supported for --agent claude");
+  }
+  const target = await installAgent(process.cwd(), options.agent, { claudeHook: options.hook ?? false });
   if (isJson()) {
-    emitJson({ agent: options.agent, target });
+    emitJson({ agent: options.agent, target, hook: options.hook ?? false });
   } else {
     log(`Installed rules into ${target}`);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarmvaultai/cli",
-  "version": "0.1.18",
+  "version": "0.1.21",
   "description": "Global CLI for SwarmVault.",
   "type": "module",
   "main": "dist/index.js",
@@ -39,7 +39,7 @@
   },
   "dependencies": {
     "commander": "^14.0.1",
-    "@swarmvaultai/engine": "0.1.18"
+    "@swarmvaultai/engine": "0.1.21"
   },
   "devDependencies": {
     "@types/node": "^24.6.0",