@swarmvaultai/cli 0.1.17 → 0.1.19

package/README.md

@@ -25,11 +25,14 @@ cd my-vault
 swarmvault init --obsidian
 sed -n '1,120p' swarmvault.schema.md
 swarmvault ingest ./notes.md
+swarmvault ingest ./repo
 swarmvault compile
 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 graph serve
 swarmvault graph export --html ./exports/graph.html
 ```
@@ -55,7 +58,22 @@ The schema file is the vault-specific instruction layer. Edit it to define namin
 
 ### `swarmvault ingest <path-or-url>`
 
-Ingest a local file path or URL into immutable source storage and write a manifest to `state/manifests/`.
+Ingest a local file path, directory path, or URL into immutable source storage and write manifests to `state/manifests/`.
+
+- local directories recurse by default
+- 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
+
+Useful flags:
+
+- `--repo-root <path>`
+- `--include <glob...>`
+- `--exclude <glob...>`
+- `--max-files <n>`
+- `--no-gitignore`
+- `--no-include-assets`
+- `--max-asset-size <bytes>`
 
 ### `swarmvault inbox import [dir]`
 
@@ -71,6 +89,8 @@ Compile the current manifests into:
 
 The compiler also reads `swarmvault.schema.md` and records a `schema_hash` plus lifecycle metadata such as `status`, `created_at`, `updated_at`, `compiled_from`, and `managed_by` in generated pages so schema edits can mark pages stale without losing lifecycle state.
 
+For ingested code trees, compile also writes `state/code-index.json` so local imports and module aliases can resolve across the repo-aware code graph.
+
 New concept and entity pages are staged into `wiki/candidates/` first. A later matching compile promotes them into `wiki/concepts/` or `wiki/entities/`.
 
 With `--approve`, compile writes a staged review bundle into `state/approvals/` without applying active wiki changes.
@@ -96,7 +116,7 @@ Inspect and resolve staged concept and entity candidates.
 
 Targets can be page ids or relative paths under `wiki/candidates/`.
 
-### `swarmvault query "<question>" [--no-save] [--format markdown|report|slides]`
+### `swarmvault query "<question>" [--no-save] [--format markdown|report|slides|chart|image]`
 
 Query the compiled vault. The query layer also reads `swarmvault.schema.md`, so answers follow the vault’s own structure and grounding rules.
 
@@ -111,7 +131,7 @@ Saved outputs also carry related page, node, and source metadata so SwarmVault c
 
 Human-authored pages in `wiki/insights/` are also indexed into search and query context, but SwarmVault does not rewrite them after initialization.
 
-### `swarmvault explore "<question>" [--steps <n>]`
+### `swarmvault explore "<question>" [--steps <n>] [--format markdown|report|slides|chart|image]`
 
 Run a save-first multi-step research loop.
 
@@ -159,11 +179,27 @@ 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 query "<question>" [--dfs] [--budget <n>]`
+
+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 <output>`
 
-Export the graph workspace as a standalone HTML file with embedded graph and page data for offline sharing.
+Export the graph workspace as a standalone HTML file with embedded graph and page data for offline sharing. The exported file keeps read-only graph browsing, search, and page preview. The live graph query/path/explain actions remain part of `graph serve` and the MCP surface.
 
 ### `swarmvault install --agent <codex|claude|cursor|goose|pi|gemini|opencode>`
 

package/dist/index.js

@@ -7,18 +7,23 @@ import {
   acceptApproval,
   archiveCandidate,
   compileVault,
+  explainGraphVault,
   exploreVault,
   exportGraphHtml,
   importInbox,
+  ingestDirectory,
   ingestInput,
   initVault,
   installAgent,
   lintVault,
   listApprovals,
   listCandidates,
+  listGodNodes,
   listSchedules,
   loadVaultConfig,
+  pathGraphVault,
   promoteCandidate,
+  queryGraphVault,
   queryVault,
   readApproval,
   rejectApproval,
@@ -35,9 +40,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.16";
+    return typeof packageJson.version === "string" && packageJson.version.trim() ? packageJson.version : "0.1.19";
   } catch {
-    return "0.1.16";
+    return "0.1.19";
   }
 }
 function isJson() {
@@ -64,18 +69,40 @@ program.command("init").description("Initialize a SwarmVault workspace in the cu
     log("Initialized SwarmVault workspace.");
   }
 });
-program.command("ingest").description("Ingest a local file path or URL into the raw SwarmVault workspace.").argument("<input>", "Local file path or URL").option("--include-assets", "Download remote image assets when ingesting URLs", true).option("--no-include-assets", "Skip downloading remote image assets when ingesting URLs").option("--max-asset-size <bytes>", "Maximum number of bytes to fetch for a single remote image asset").action(async (input, options) => {
-  const maxAssetSize = typeof options.maxAssetSize === "string" && options.maxAssetSize.trim() ? Number.parseInt(options.maxAssetSize, 10) : void 0;
-  const manifest = await ingestInput(process.cwd(), input, {
-    includeAssets: options.includeAssets,
-    maxAssetSize: Number.isFinite(maxAssetSize) ? maxAssetSize : void 0
-  });
-  if (isJson()) {
-    emitJson(manifest);
-  } else {
-    log(manifest.sourceId);
+program.command("ingest").description("Ingest a local file path, directory path, or URL into the raw SwarmVault workspace.").argument("<input>", "Local file path, directory path, or URL").option("--include-assets", "Download remote image assets when ingesting URLs", true).option("--no-include-assets", "Skip downloading remote image assets when ingesting URLs").option("--max-asset-size <bytes>", "Maximum number of bytes to fetch for a single remote image asset").option("--repo-root <path>", "Override the detected repo root when ingesting a directory").option("--include <glob...>", "Only ingest files matching one or more glob patterns").option("--exclude <glob...>", "Skip files matching one or more glob patterns").option("--max-files <n>", "Maximum number of files to ingest from a directory").option("--no-gitignore", "Ignore .gitignore rules when ingesting a directory").action(
+  async (input, options) => {
+    const maxAssetSize = typeof options.maxAssetSize === "string" && options.maxAssetSize.trim() ? Number.parseInt(options.maxAssetSize, 10) : void 0;
+    const maxFiles = typeof options.maxFiles === "string" && options.maxFiles.trim() ? Number.parseInt(options.maxFiles, 10) : void 0;
+    const commonOptions = {
+      includeAssets: options.includeAssets,
+      maxAssetSize: Number.isFinite(maxAssetSize) ? maxAssetSize : void 0,
+      repoRoot: options.repoRoot,
+      include: options.include,
+      exclude: options.exclude,
+      maxFiles: Number.isFinite(maxFiles) ? maxFiles : void 0,
+      gitignore: options.gitignore
+    };
+    const directoryResult = !/^https?:\/\//i.test(input) ? await import("fs/promises").then(
+      (fs) => fs.stat(input).then((stat) => stat.isDirectory() ? ingestDirectory(process.cwd(), input, commonOptions) : null).catch(() => null)
+    ) : null;
+    if (directoryResult) {
+      if (isJson()) {
+        emitJson(directoryResult);
+      } else {
+        log(
+          `Imported ${directoryResult.imported.length} file(s), updated ${directoryResult.updated.length}, skipped ${directoryResult.skipped.length}.`
+        );
+      }
+      return;
+    }
+    const manifest = await ingestInput(process.cwd(), input, commonOptions);
+    if (isJson()) {
+      emitJson(manifest);
+    } else {
+      log(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);
@@ -171,6 +198,45 @@ graph.command("export").description("Export the graph viewer as a single self-co
     log(`Exported graph HTML 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.");
 review.command("list").description("List staged approval bundles and their resolution status.").action(async () => {
   const approvals = await listApprovals(process.cwd());

package/package.json

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