npm - @swarmvaultai/cli - Versions diffs - 3.10.0 → 3.11.0 - Mend

@swarmvaultai/cli 3.10.0 → 3.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (3) hide show

package/README.md CHANGED Viewed

@@ -73,6 +73,7 @@ swarmvault update .
 swarmvault graph cluster
 swarmvault cluster-only
 swarmvault graph tree --output ./exports/tree.html
+swarmvault tree --output ./exports/tree.html
 swarmvault graph query "Which nodes bridge the biggest clusters?"
 swarmvault graph explain "concept:drift"
 swarmvault watch status
@@ -84,7 +85,9 @@ swarmvault graph export --html ./exports/graph.html
 swarmvault graph export --cypher ./exports/graph.cypher
 swarmvault graph export --neo4j ./exports/graph.cypher
 swarmvault graph merge ./exports/graph.json ./other-graph.json --out ./exports/merged-graph.json
+swarmvault merge-graphs ./exports/graph.json ./other-graph.json --out ./exports/merged-graph.json
 swarmvault graph push neo4j --dry-run
+swarmvault clone https://github.com/owner/repo --no-viz
 ```
 ## Commands
@@ -110,7 +113,7 @@ 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|github-url> [--port <port>] [--no-serve] [--branch <name>] [--ref <ref>] [--checkout-dir <path>]`
+### `swarmvault scan <directory|github-url> [--port <port>] [--no-serve] [--no-viz] [--mcp] [--branch <name>] [--ref <ref>] [--checkout-dir <path>]`
 Quick-start a scratch vault from a local directory or public GitHub repo root URL in one command.
@@ -118,12 +121,22 @@ Quick-start a scratch vault from a local directory or public GitHub repo root UR
 - 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`
+- starts `graph serve` unless you pass `--no-serve` or `--no-viz`
+- `--no-viz` is a compatibility alias for `--no-serve`
+- `--mcp` starts the MCP stdio server after compile instead of the graph viewer
 - 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.
+### `swarmvault clone <directory|github-url> [--no-viz] [--mcp] [--branch <name>] [--ref <ref>] [--checkout-dir <path>]`
+Compatibility alias for `swarmvault scan`.
+- initializes, ingests or registers the input, and compiles in one command
+- supports the same public GitHub repo checkout flags as `scan`
+- accepts `--no-serve`, `--no-viz`, `--mcp`, and `--port`
 ### `swarmvault demo [--port <port>] [--no-serve]`
 Create a temporary sample vault with bundled sources, compile it immediately, and launch the graph viewer unless you pass `--no-serve`.
@@ -440,6 +453,13 @@ Write a collapsible HTML source tree for the current `state/graph.json`.
 - `--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 tree [--output <html>] [--root <path>] [--label <name>] [--max-children <n>]`
+Compatibility alias for `swarmvault graph tree`.
+- writes the same source/module/symbol tree
+- returns the same JSON shape as `graph tree`
 ### `swarmvault graph merge <graph...> --out <path> [--label <name>]`
 Merge multiple graph JSON files into one namespaced graph artifact.
@@ -450,6 +470,13 @@ Merge multiple graph JSON files into one namespaced graph artifact.
 - maps explicit extracted/inferred/ambiguous edge evidence into SwarmVault edge semantics
 - `--json` returns the merged graph, input summaries, and warnings
+### `swarmvault merge-graphs <graph...> --out <path> [--label <name>]`
+Compatibility alias for `swarmvault graph merge`.
+- accepts the same SwarmVault and NetworkX/node-link graph inputs
+- returns the same JSON shape as `graph merge`
 ### `swarmvault graph status [path]`
 Read-only graph freshness check for tracked repo roots or one explicit repo path.
@@ -461,6 +488,15 @@ Read-only graph freshness check for tracked repo roots or one explicit repo path
 - recommends `swarmvault compile` when graph/report artifacts are missing, non-code files changed, or a semantic refresh is pending
 - supports global `--json` for automation
+### `swarmvault watch [path] [--once] [--code-only] [--lint]`
+Watch or refresh one explicit repo root without first writing `watch.repoRoots`.
+- positional `[path]` is treated as a repo-root override and turns on repo mode
+- `--once` runs one refresh cycle and exits
+- `--code-only` limits the refresh to parser-backed repo graph artifacts
+- repeated `--root <path>` remains available when you need multiple roots
 ### `swarmvault graph stats`
 Summarize the current compiled graph without opening the viewer.

package/dist/index.js CHANGED Viewed

@@ -315,9 +315,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.10.0";
+    return typeof packageJson.version === "string" && packageJson.version.trim() ? packageJson.version : "3.11.0";
   } catch {
-    return "3.10.0";
+    return "3.11.0";
   }
 }
 function parsePositiveInt(value, fallback) {
@@ -545,6 +545,110 @@ async function runGraphClusterCommand(options, rootDir = process2.cwd()) {
     `Refreshed ${result.communityCount} communities across ${result.nodeCount} nodes and ${result.edgeCount} edges. Report: ${result.reportPath}`
   );
 }
+async function runGraphTreeCommand(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}.`);
+}
+async function runGraphMergeCommand(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}`);
+  }
+}
+async function runScanCommand(input, options) {
+  const rootDir = process2.cwd();
+  await initVault(rootDir, {});
+  if (!isJson()) {
+    log("Initialized workspace.");
+  }
+  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()) {
+    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 = "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");
+  const shareKitPath = path2.join(paths.wikiDir, "graph", "share-kit");
+  if (!isJson()) {
+    log(`Compiled ${compiled.sourceCount} source(s), ${compiled.pageCount} page(s).`);
+    log(`Share card: ${shareCardPath}`);
+    log(`Visual card: ${shareCardSvgPath}`);
+    log(`Share kit: ${shareKitPath}`);
+    log("Post text: swarmvault graph share --post");
+  }
+  if (options.mcp) {
+    process2.stderr.write(`${JSON.stringify({ status: "running", transport: "stdio", compiled: compiled.sourceCount })}
+`);
+    const controller = await startMcpServer(rootDir);
+    process2.on("SIGINT", async () => {
+      try {
+        await controller.close();
+      } catch {
+      }
+      process2.exit(0);
+    });
+    return;
+  }
+  if (options.serve !== false && options.viz !== false) {
+    const port = options.port ? parsePositiveInt(options.port, 0) || void 0 : void 0;
+    const server = await startGraphServer(rootDir, port, { full: false });
+    if (isJson()) {
+      emitJson({
+        ...result,
+        compiled,
+        shareCardPath,
+        shareCardSvgPath,
+        shareKitPath,
+        port: server.port,
+        url: `http://localhost:${server.port}`
+      });
+    } else {
+      log(`Graph viewer running at http://localhost:${server.port}`);
+    }
+    process2.on("SIGINT", async () => {
+      try {
+        await server.close();
+      } catch {
+      }
+      process2.exit(0);
+    });
+  } else if (isJson()) {
+    emitJson({ ...result, compiled, shareCardPath, shareCardSvgPath, shareKitPath });
+  }
+}
 program.hook("postAction", async (_thisCommand, actionCommand) => {
   const notices = await collectCliNotices({
     commandPath: getCommandPath(actionCommand),
@@ -1215,36 +1319,8 @@ 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).option("--force", "Allow graph updates even when node or edge counts shrink sharply", false).action(runGraphUpdateCommand);
-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("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(runGraphTreeCommand);
+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(runGraphMergeCommand);
 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(showGraphStatusCommand);
 graph.command("stats").description("Summarize compiled graph counts, node types, evidence classes, and relation mix.").action(async () => {
   const stats = await graphStatsVault(process2.cwd());
@@ -1691,14 +1767,16 @@ 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, []).option("--force", "Allow graph updates even when node or edge counts shrink sharply", false).action(
-  async (options) => {
+var watch = program.command("watch").description("Watch the inbox directory and optionally tracked repos, or run one refresh cycle immediately.").argument("[path]", "Optional repo root to watch or refresh instead of config/auto-discovery").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 (targetPath, options) => {
     const debounceMs = parsePositiveInt(options.debounce, 900);
-    const overrideRoots = options.root && options.root.length > 0 ? options.root : void 0;
+    const rootOverrides = [...targetPath ? [targetPath] : [], ...options.root ?? []];
+    const overrideRoots = rootOverrides.length > 0 ? rootOverrides : void 0;
+    const repoMode = options.repo || Boolean(targetPath);
     if (options.once) {
       const result = await runWatchCycle(process2.cwd(), {
         lint: options.lint ?? false,
-        repo: options.repo ?? false,
+        repo: repoMode,
         codeOnly: options.codeOnly ?? false,
         debounceMs,
         force: options.force ?? false,
@@ -1708,7 +1786,7 @@ var watch = program.command("watch").description("Watch the inbox directory and
         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}.`
+          `Refreshed inbox${repoMode ? " and tracked repos" : ""}. Imported ${result.importedCount}, repo imported ${result.repoImportedCount}, repo updated ${result.repoUpdatedCount}, repo removed ${result.repoRemovedCount}.`
         );
       }
       return;
@@ -1716,16 +1794,16 @@ var watch = program.command("watch").description("Watch the inbox directory and
     const { paths } = await loadVaultConfig(process2.cwd());
     const controller = await watchVault(process2.cwd(), {
       lint: options.lint ?? false,
-      repo: options.repo ?? false,
+      repo: repoMode,
       codeOnly: options.codeOnly ?? false,
       debounceMs,
       force: options.force ?? false,
       overrideRoots
     });
     if (isJson()) {
-      emitJson({ status: "watching", inboxDir: paths.inboxDir, repo: options.repo ?? false });
+      emitJson({ status: "watching", inboxDir: paths.inboxDir, repo: repoMode });
     } else {
-      log(`Watching inbox${options.repo ? " and tracked repos" : ""} for changes. Press Ctrl+C to stop.`);
+      log(`Watching inbox${repoMode ? " and tracked repos" : ""} for changes. Press Ctrl+C to stop.`);
     }
     process2.on("SIGINT", async () => {
       try {
@@ -1785,6 +1863,8 @@ program.command("update").description("Compatibility alias for graph update: ref
 program.command("cluster-only").description("Compatibility alias for graph cluster: recompute graph communities and report artifacts without re-ingesting.").argument("[vault]", "Optional vault root to cluster instead of the current directory").option("--resolution <number>", "Override the Louvain community resolution for this run").action(
   (vaultPath, options) => runGraphClusterCommand(options, vaultPath ? path2.resolve(process2.cwd(), vaultPath) : process2.cwd())
 );
+program.command("tree").description("Compatibility alias for graph tree: 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(runGraphTreeCommand);
+program.command("merge-graphs").description("Compatibility alias for graph merge: combine graph JSON 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(runGraphMergeCommand);
 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(process2.cwd());
@@ -2265,67 +2345,8 @@ 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("<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 = 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()) {
-    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 = "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");
-  const shareKitPath = path2.join(paths.wikiDir, "graph", "share-kit");
-  if (!isJson()) {
-    log(`Compiled ${compiled.sourceCount} source(s), ${compiled.pageCount} page(s).`);
-    log(`Share card: ${shareCardPath}`);
-    log(`Visual card: ${shareCardSvgPath}`);
-    log(`Share kit: ${shareKitPath}`);
-    log("Post text: swarmvault graph share --post");
-  }
-  if (options.serve !== false) {
-    const port = options.port ? parsePositiveInt(options.port, 0) || void 0 : void 0;
-    const server = await startGraphServer(rootDir, port, { full: false });
-    if (isJson()) {
-      emitJson({
-        ...result,
-        compiled,
-        shareCardPath,
-        shareCardSvgPath,
-        shareKitPath,
-        port: server.port,
-        url: `http://localhost:${server.port}`
-      });
-    } else {
-      log(`Graph viewer running at http://localhost:${server.port}`);
-    }
-    process2.on("SIGINT", async () => {
-      try {
-        await server.close();
-      } catch {
-      }
-      process2.exit(0);
-    });
-  } else if (isJson()) {
-    emitJson({ ...result, compiled, shareCardPath, shareCardSvgPath, shareKitPath });
-  }
-});
+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("--no-viz", "Compatibility alias for --no-serve; skip launching the graph viewer after compile").option("--mcp", "Start the MCP stdio server after compile instead of launching the graph viewer", false).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(runScanCommand);
+program.command("clone").description("Compatibility alias for scan: initialize, clone/register a public repo URL, and compile it into the vault.").argument("<input>", "Public GitHub repo URL or local directory to scan").option("--port <port>", "Port for the graph viewer").option("--no-serve", "Skip launching the graph viewer after compile").option("--no-viz", "Compatibility alias for --no-serve; skip launching the graph viewer after compile").option("--mcp", "Start the MCP stdio server after compile instead of launching the graph viewer", false).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(runScanCommand);
 function enableStructuredJsonOnSubcommands(command) {
   for (const subcommand of command.commands) {
     const hasJsonOption = subcommand.options.some((option) => option.attributeName() === "json");

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@swarmvaultai/cli",
-  "version": "3.10.0",
+  "version": "3.11.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.10.0",
+    "@swarmvaultai/engine": "3.11.0",
     "commander": "^14.0.1"
   },
   "devDependencies": {