@swarmvaultai/cli 3.6.0 → 3.7.0

package/README.md

@@ -26,6 +26,7 @@ swarmvault init --obsidian --profile personal-research
 swarmvault init --obsidian --profile reader,timeline
 swarmvault demo
 swarmvault source add https://github.com/karpathy/micrograd
+swarmvault source add https://github.com/owner/repo --branch main --checkout-dir .swarmvault-checkouts/repo
 swarmvault source add https://example.com/docs/getting-started
 swarmvault source add ./exports/customer-call.srt --guide
 swarmvault source session file-customer-call-srt-12345678
@@ -56,6 +57,7 @@ swarmvault graph blast ./src/index.ts
 swarmvault graph status ./src
 swarmvault graph update .
 swarmvault graph cluster
+swarmvault graph tree --output ./exports/tree.html
 swarmvault graph query "Which nodes bridge the biggest clusters?"
 swarmvault graph explain "concept:drift"
 swarmvault watch status
@@ -65,6 +67,7 @@ swarmvault graph serve
 swarmvault graph export --report ./exports/report.html
 swarmvault graph export --html ./exports/graph.html
 swarmvault graph export --cypher ./exports/graph.cypher
+swarmvault graph merge ./exports/graph.json ./other-graph.json --out ./exports/merged-graph.json
 swarmvault graph push neo4j --dry-run
 ```
 
@@ -91,16 +94,17 @@ Set `SWARMVAULT_OUT=<dir>` when generated artifacts should be isolated from the
 
 `--profile` accepts `default`, `personal-research`, or a comma-separated preset list such as `reader,timeline`. For fully custom vault behavior, edit the `profile` block in `swarmvault.config.json`; that deterministic profile layer works alongside the human-written `swarmvault.schema.md`. The `personal-research` preset also sets `profile.guidedIngestDefault: true` and `profile.deepLintDefault: true`, so guided ingest/source and lint flows are on by default until you override them with `--no-guide` or `--no-deep`.
 
-### `swarmvault scan <directory> [--port <port>] [--no-serve]`
+### `swarmvault scan <directory|github-url> [--port <port>] [--no-serve] [--branch <name>] [--ref <ref>] [--checkout-dir <path>]`
 
-Quick-start a scratch vault from a local directory in one command.
+Quick-start a scratch vault from a local directory or public GitHub repo root URL in one command.
 
 - initializes the current directory as a SwarmVault workspace
-- ingests the supplied directory as local sources
+- ingests the supplied directory as local sources, or registers/syncs the supplied public GitHub repo root URL
 - compiles the vault immediately
 - writes `wiki/graph/share-card.md`, `wiki/graph/share-card.svg`, and `wiki/graph/share-kit/`, then prints the paths
 - starts `graph serve` unless you pass `--no-serve`
 - respects `--port` when you want a specific viewer port
+- for GitHub repo URLs, supports `--branch`, `--ref`, and `--checkout-dir`
 
 Use this when you want the fastest repo or docs-tree walkthrough without first deciding on managed-source registration.
 
@@ -139,6 +143,7 @@ Run a whole-vault health check before handing the workspace to an agent or openi
 Manage recurring source roots through a registry-backed workflow.
 
 - `source add <input>` supports local files, local directories, public GitHub repo root URLs such as `https://github.com/karpathy/micrograd`, and docs/wiki/help/reference/tutorial hubs
+- for public GitHub repo roots, `source add` supports `--branch <name>`, `--ref <ref>`, and `--checkout-dir <path>` so recurring sources can pin a branch, tag, commit, or reusable checkout directory
 - by default `source add` registers the source, syncs it into the vault, runs one compile, and writes a source brief to `wiki/outputs/source-briefs/<source-id>.md`
 - add `--guide` when you want a resumable source session, source brief, source review, source guide, and approval-bundled canonical page edits when `profile.guidedSessionMode` is `canonical_review`, with `wiki/insights/` fallback for `insights_only`
 - set `profile.guidedIngestDefault: true` when guided mode should be the default for `source add` and `source reload`, and use `--no-guide` for individual light-path runs
@@ -185,7 +190,7 @@ Ingest a local file path, directory path, or URL into immutable source storage a
 - local file and archive ingest supports markdown, text, reStructuredText, HTML, PDF, Word, RTF, OpenDocument, EPUB, CSV/TSV, Excel, PowerPoint, Jupyter notebooks, BibTeX, Org-mode, AsciiDoc, transcripts, Slack exports, email, calendar, audio, video, structured config/data, developer manifests, images, and code
 - add `--guide` when you want a resumable source session, source brief, source review, source guide, and approval-bundled canonical page edits when `profile.guidedSessionMode` is `canonical_review`, with `wiki/insights/` fallback for `insights_only`
 - set `profile.guidedIngestDefault: true` when guided mode should be the default for `ingest`, and use `--no-guide` to force a plain ingest for one run
-- code-aware directory ingest currently covers JavaScript, JSX, TypeScript, TSX, Bash/shell scripts, Python, Go, Rust, Java, Kotlin, Scala, Dart, Lua, Zig, C#, C, C++, PHP, Ruby, PowerShell, Elixir, OCaml, Objective-C, ReScript, Solidity, HTML, CSS, Vue single-file components, and SQL files with table/view graph relations
+- code-aware directory ingest currently covers JavaScript, JSX, TypeScript, TSX, Bash/shell scripts, Python, Go, Rust, Java, Kotlin, Scala, Dart, Lua, Zig, C#, C, C++, PHP, Ruby, PowerShell, Elixir, OCaml, Objective-C, ReScript, Solidity, HTML, CSS, Vue single-file components, Svelte single-file components, and SQL files with table/view graph relations. Julia, Verilog/SystemVerilog, and R files are detected as code sources and emit explicit parser-asset diagnostics until packaged WASM grammars are available.
 
 Useful flags:
 
@@ -390,8 +395,29 @@ Refresh code-derived graph artifacts from tracked repo roots or one explicit rep
 - runs the same code-only repo refresh path as `swarmvault watch --repo --code-only --once`
 - without `path`, uses configured or auto-discovered watched repo roots
 - with `path`, refreshes that repo root instead of the tracked set
+- aborts if nodes or edges drop by more than 25% compared with the existing graph; pass `--force` or set `SWARMVAULT_FORCE_UPDATE=1` when the shrink is expected
 - `--json` returns the same one-shot watch result shape, including repo import/update/remove counts and pending semantic refresh entries
 
+### `swarmvault graph tree [--output <html>] [--root <path>] [--label <name>] [--max-children <n>]`
+
+Write a collapsible HTML source tree for the current `state/graph.json`.
+
+- groups sources by path, then shows module, symbol, and rationale nodes underneath each source
+- defaults to `wiki/graph/tree.html`
+- `--root` reads a different vault root without changing directories
+- `--max-children` caps very wide folders or modules with a `+N more` row
+- `--json` returns the output path, source count, node count, and tree payload
+
+### `swarmvault graph merge <graph...> --out <path> [--label <name>]`
+
+Merge multiple graph JSON files into one namespaced graph artifact.
+
+- accepts native SwarmVault `state/graph.json` payloads
+- accepts NetworkX/node-link style JSON with `nodes` plus `links` or `edges`
+- prefixes ids from every input to avoid collisions
+- maps explicit extracted/inferred/ambiguous edge evidence into SwarmVault edge semantics
+- `--json` returns the merged graph, input summaries, and warnings
+
 ### `swarmvault graph status [path]`
 
 Read-only graph freshness check for tracked repo roots or one explicit repo path.

package/dist/index.js

@@ -30,6 +30,7 @@ import {
   exportGraphFormat,
   exportGraphHtml,
   exportGraphReportHtml,
+  exportGraphTree,
   exportObsidianCanvas,
   exportObsidianVault,
   finishMemoryTask,
@@ -57,6 +58,7 @@ import {
   listSchedules,
   listWatchedRoots,
   loadVaultConfig,
+  mergeGraphFiles,
   pathGraphVault,
   previewCandidatePromotions,
   promoteCandidate,
@@ -311,9 +313,9 @@ program.name("swarmvault").description("SwarmVault is a local-first knowledge co
 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 : "3.6.0";
+    return typeof packageJson.version === "string" && packageJson.version.trim() ? packageJson.version : "3.7.0";
   } catch {
-    return "3.6.0";
+    return "3.7.0";
   }
 }
 function parsePositiveInt(value, fallback) {
@@ -329,6 +331,9 @@ function parsePositiveNumber(value) {
 function collectRepeated(value, previous) {
   return [...previous, value];
 }
+function isHttpUrlInput(input) {
+  return input.startsWith("http://") || input.startsWith("https://");
+}
 function sourceScopeFromManifests(input, manifests) {
   if (!manifests.length) {
     return null;
@@ -666,7 +671,7 @@ program.command("add").description("Capture supported URLs into normalized markd
   }
 });
 var source = program.command("source").description("Manage recurring local files, directories, public repos, and docs sources.");
-source.command("add").description("Register and sync a managed source from a local file, directory, public GitHub repo root URL, or docs hub URL.").argument("<input>", "Local file path, directory path, public GitHub repo root URL, or docs hub URL").option("--no-compile", "Register and sync without compiling the vault").option("--no-brief", "Skip source brief generation after sync").option("--review", "Stage a source review artifact after sync and compile", false).option("--guide", "Stage a guided source integration bundle after sync and compile (default: from config)").option("--no-guide", "Skip guided mode even if enabled in config").option("--answers-file <path>", "JSON file with guided-session answers keyed by question id or listed in prompt order").option("--max-pages <n>", "Maximum number of pages to crawl for docs sources").option("--max-depth <n>", "Maximum crawl depth for docs sources").action(
+source.command("add").description("Register and sync a managed source from a local file, directory, public GitHub repo root URL, or docs hub URL.").argument("<input>", "Local file path, directory path, public GitHub repo root URL, or docs hub URL").option("--no-compile", "Register and sync without compiling the vault").option("--no-brief", "Skip source brief generation after sync").option("--review", "Stage a source review artifact after sync and compile", false).option("--guide", "Stage a guided source integration bundle after sync and compile (default: from config)").option("--no-guide", "Skip guided mode even if enabled in config").option("--answers-file <path>", "JSON file with guided-session answers keyed by question id or listed in prompt order").option("--max-pages <n>", "Maximum number of pages to crawl for docs sources").option("--max-depth <n>", "Maximum crawl depth for docs sources").option("--branch <name>", "GitHub branch to clone for public repo sources").option("--ref <ref>", "Git ref, tag, or commit to check out after cloning a public repo source").option("--checkout-dir <path>", "Persistent checkout directory for a public GitHub repo source").action(
   async (input, options) => {
     const guideAnswers = readGuideAnswersFile(options.answersFile);
     const addConfig = await loadVaultConfig(process2.cwd()).catch(() => null);
@@ -678,7 +683,10 @@ source.command("add").description("Register and sync a managed source from a loc
       guide: guideEnabled,
       guideAnswers,
       maxPages: options.maxPages ? parsePositiveInt(options.maxPages, 0) || void 0 : void 0,
-      maxDepth: options.maxDepth ? parsePositiveInt(options.maxDepth, 0) || void 0 : void 0
+      maxDepth: options.maxDepth ? parsePositiveInt(options.maxDepth, 0) || void 0 : void 0,
+      branch: options.branch,
+      ref: options.ref,
+      checkoutDir: options.checkoutDir
     });
     if (result.guide && !options.answersFile) {
       result.guide = await completeGuideInteractively(result.guide, result.source.id);
@@ -1144,12 +1152,13 @@ program.command("lint").description("Run anti-drift and wiki-health checks.").op
 });
 var graph = program.command("graph").description("Graph-related commands.").enablePositionalOptions();
 var graphPush = graph.command("push").description("Push the compiled graph into external sinks.");
-graph.command("update").alias("refresh").description("Refresh code-derived graph artifacts from tracked repo roots or one explicit repo path.").argument("[path]", "Optional repo root to refresh instead of configured/tracked roots").option("--lint", "Run lint after the refresh cycle", false).action(async (targetPath, options) => {
+graph.command("update").alias("refresh").description("Refresh code-derived graph artifacts from tracked repo roots or one explicit repo path.").argument("[path]", "Optional repo root to refresh instead of configured/tracked roots").option("--lint", "Run lint after the refresh cycle", false).option("--force", "Allow graph updates even when node or edge counts shrink sharply", false).action(async (targetPath, options) => {
   const overrideRoots = targetPath ? [path2.resolve(process2.cwd(), targetPath)] : void 0;
   const result = await runWatchCycle(process2.cwd(), {
     repo: true,
     codeOnly: true,
     lint: options.lint ?? false,
+    force: options.force ?? false,
     overrideRoots
   });
   if (isJson()) {
@@ -1160,6 +1169,36 @@ graph.command("update").alias("refresh").description("Refresh code-derived graph
     `Updated graph from ${result.watchedRepoRoots.length} repo root${result.watchedRepoRoots.length === 1 ? "" : "s"}. Imported ${result.repoImportedCount}, updated ${result.repoUpdatedCount}, removed ${result.repoRemovedCount}, pending semantic refresh ${result.pendingSemanticRefreshCount}.`
   );
 });
+graph.command("tree").description("Write a collapsible source/module/symbol tree for the compiled graph.").option("--output <html>", "Output HTML path (default: wiki/graph/tree.html)").option("--root <path>", "Vault root to read instead of the current directory").option("--label <name>", "Tree title").option("--max-children <n>", "Maximum children to render per tree node", "250").action(async (options) => {
+  const rootDir = options.root ? path2.resolve(process2.cwd(), options.root) : process2.cwd();
+  const result = await exportGraphTree(rootDir, options.output, {
+    label: options.label,
+    maxChildren: parsePositiveInt(options.maxChildren, 250)
+  });
+  if (isJson()) {
+    emitJson(result);
+    return;
+  }
+  log(`Graph tree: ${result.outputPath}`);
+  log(`Sources: ${result.sourceCount}; nodes: ${result.nodeCount}.`);
+});
+graph.command("merge").description("Merge SwarmVault or node-link JSON graph files into one namespaced graph artifact.").argument("<graphs...>", "Graph JSON files to merge").requiredOption("--out <path>", "Output graph JSON path").option("--label <name>", "Label/prefix to use when merging one graph").action(async (graphPaths, options) => {
+  const result = await mergeGraphFiles(
+    graphPaths.map((inputPath) => path2.resolve(process2.cwd(), inputPath)),
+    path2.resolve(process2.cwd(), options.out),
+    { label: options.label }
+  );
+  if (isJson()) {
+    emitJson(result);
+    return;
+  }
+  log(
+    `Merged ${result.inputGraphs.length} graph${result.inputGraphs.length === 1 ? "" : "s"} into ${result.outputPath}. Nodes ${result.graph.nodes.length}, edges ${result.graph.edges.length}.`
+  );
+  for (const warning of result.warnings) {
+    log(`Warning: ${warning}`);
+  }
+});
 graph.command("status").description("Read-only check for graph/report presence and tracked repo changes.").argument("[path]", "Optional repo root to check instead of configured/tracked roots").action(async (targetPath) => {
   const overrideRoots = targetPath ? [path2.resolve(process2.cwd(), targetPath)] : void 0;
   const status = await getGraphStatus(process2.cwd(), { repoRoots: overrideRoots });
@@ -1588,47 +1627,51 @@ async function confirmInteractive(message) {
     rl.close();
   }
 }
-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("--code-only", "Only re-extract code sources (AST-only, no LLM re-analysis)", false).option("--debounce <ms>", "Debounce window in milliseconds", "900").option("--root <path>", "Watch this repo root instead of config/auto-discovery (repeat for multiple)", collectRepeated, []).action(async (options) => {
-  const debounceMs = parsePositiveInt(options.debounce, 900);
-  const overrideRoots = options.root && options.root.length > 0 ? options.root : void 0;
-  if (options.once) {
-    const result = await runWatchCycle(process2.cwd(), {
+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("--code-only", "Only re-extract code sources (AST-only, no LLM re-analysis)", false).option("--debounce <ms>", "Debounce window in milliseconds", "900").option("--root <path>", "Watch this repo root instead of config/auto-discovery (repeat for multiple)", collectRepeated, []).option("--force", "Allow graph updates even when node or edge counts shrink sharply", false).action(
+  async (options) => {
+    const debounceMs = parsePositiveInt(options.debounce, 900);
+    const overrideRoots = options.root && options.root.length > 0 ? options.root : void 0;
+    if (options.once) {
+      const result = await runWatchCycle(process2.cwd(), {
+        lint: options.lint ?? false,
+        repo: options.repo ?? false,
+        codeOnly: options.codeOnly ?? false,
+        debounceMs,
+        force: options.force ?? false,
+        overrideRoots
+      });
+      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(process2.cwd());
+    const controller = await watchVault(process2.cwd(), {
       lint: options.lint ?? false,
       repo: options.repo ?? false,
       codeOnly: options.codeOnly ?? false,
       debounceMs,
+      force: options.force ?? false,
       overrideRoots
     });
     if (isJson()) {
-      emitJson(result);
+      emitJson({ status: "watching", inboxDir: paths.inboxDir, repo: options.repo ?? false });
     } else {
-      log(
-        `Refreshed inbox${options.repo ? " and tracked repos" : ""}. Imported ${result.importedCount}, repo imported ${result.repoImportedCount}, repo updated ${result.repoUpdatedCount}, repo removed ${result.repoRemovedCount}.`
-      );
+      log(`Watching inbox${options.repo ? " and tracked repos" : ""} for changes. Press Ctrl+C to stop.`);
     }
-    return;
-  }
-  const { paths } = await loadVaultConfig(process2.cwd());
-  const controller = await watchVault(process2.cwd(), {
-    lint: options.lint ?? false,
-    repo: options.repo ?? false,
-    codeOnly: options.codeOnly ?? false,
-    debounceMs,
-    overrideRoots
-  });
-  if (isJson()) {
-    emitJson({ status: "watching", inboxDir: paths.inboxDir, repo: options.repo ?? false });
-  } else {
-    log(`Watching inbox${options.repo ? " and tracked repos" : ""} for changes. Press Ctrl+C to stop.`);
+    process2.on("SIGINT", async () => {
+      try {
+        await controller.close();
+      } catch {
+      }
+      process2.exit(0);
+    });
   }
-  process2.on("SIGINT", async () => {
-    try {
-      await controller.close();
-    } catch {
-    }
-    process2.exit(0);
-  });
-});
+);
 watch.command("list-roots").description("Print the effective watched repo roots resolved from config and auto-discovery.").action(async () => {
   const roots = await listWatchedRoots(process2.cwd());
   if (isJson()) {
@@ -2153,17 +2196,29 @@ retrieval.command("doctor").description("Diagnose retrieval index problems and o
     log(`Warning: ${warning}`);
   }
 });
-program.command("scan").description("Quick-start: initialize, ingest, compile, and serve a graph viewer in one command.").argument("<directory>", "Directory to scan").option("--port <port>", "Port for the graph viewer").option("--no-serve", "Skip launching the graph viewer after compile").action(async (directory, options) => {
+program.command("scan").description("Quick-start: initialize, ingest, compile, and serve a graph viewer in one command.").argument("<input>", "Directory or public GitHub repo root URL to scan").option("--port <port>", "Port for the graph viewer").option("--no-serve", "Skip launching the graph viewer after compile").option("--branch <name>", "GitHub branch to clone when scanning a public repo URL").option("--ref <ref>", "Git ref, tag, or commit to check out when scanning a public repo URL").option("--checkout-dir <path>", "Persistent checkout directory for a public GitHub repo scan").action(async (input, options) => {
   const rootDir = process2.cwd();
   await initVault(rootDir, {});
   if (!isJson()) {
     log("Initialized workspace.");
   }
-  const result = await ingestDirectory(rootDir, directory, {});
+  const result = isHttpUrlInput(input) ? await addManagedSource(rootDir, input, {
+    compile: true,
+    brief: false,
+    branch: options.branch,
+    ref: options.ref,
+    checkoutDir: options.checkoutDir
+  }) : await ingestDirectory(rootDir, input, {});
   if (!isJson()) {
-    log(`Ingested ${result.imported.length} file(s).`);
+    if ("source" in result) {
+      log(
+        `Registered ${result.source.kind} source ${result.source.id}. Imported ${result.source.lastSyncCounts?.importedCount ?? 0}, updated ${result.source.lastSyncCounts?.updatedCount ?? 0}.`
+      );
+    } else {
+      log(`Ingested ${result.imported.length} file(s).`);
+    }
   }
-  const compiled = await compileVault(rootDir, {});
+  const compiled = "compile" in result && result.compile ? result.compile : await compileVault(rootDir, {});
   const { paths } = await loadVaultConfig(rootDir);
   const shareCardPath = path2.join(paths.wikiDir, "graph", "share-card.md");
   const shareCardSvgPath = path2.join(paths.wikiDir, "graph", "share-card.svg");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarmvaultai/cli",
-  "version": "3.6.0",
+  "version": "3.7.0",
   "description": "Global CLI for SwarmVault.",
   "type": "module",
   "main": "dist/index.js",
@@ -44,7 +44,7 @@
     "prepublishOnly": "node ../../scripts/check-release-sync.mjs && node ../../scripts/check-published-manifests.mjs"
   },
   "dependencies": {
-    "@swarmvaultai/engine": "3.6.0",
+    "@swarmvaultai/engine": "3.7.0",
     "commander": "^14.0.1"
   },
   "devDependencies": {