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

@swarmvaultai/cli 3.8.0 → 3.10.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

@@ -17,6 +17,16 @@ Installed commands:
 - `swarmvault`
 - `vault` as a compatibility alias
+## Maintainer Validation
+Release preflight includes a direct CLI surface smoke before tarball smoke:
+```bash
+pnpm live:cli-surface
+```
+The smoke parses `packages/cli/src/index.ts` with the TypeScript compiler API, checks that every stable Commander command path and alias is classified in the surface manifest, runs `--help` across the full command tree, and exercises direct JSON behavior checks for the core local workflows.
 ## First Run
 ```bash
@@ -55,8 +65,13 @@ swarmvault explore "What should I research next?" --steps 3
 swarmvault lint --deep
 swarmvault graph blast ./src/index.ts
 swarmvault graph status ./src
+swarmvault check-update ./src
+swarmvault graph stats
+swarmvault graph validate --strict
 swarmvault graph update .
+swarmvault update .
 swarmvault graph cluster
+swarmvault cluster-only
 swarmvault graph tree --output ./exports/tree.html
 swarmvault graph query "Which nodes bridge the biggest clusters?"
 swarmvault graph explain "concept:drift"
@@ -67,6 +82,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 export --neo4j ./exports/graph.cypher
 swarmvault graph merge ./exports/graph.json ./other-graph.json --out ./exports/merged-graph.json
 swarmvault graph push neo4j --dry-run
 ```
@@ -398,6 +414,22 @@ Refresh code-derived graph artifacts from tracked repo roots or one explicit rep
 - 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 check-update [path]`
+Compatibility alias for `swarmvault graph status [path]`.
+- performs the same read-only graph/report freshness check
+- keeps automation-friendly JSON output for cron or hook wrappers
+- recommends `swarmvault update`/`swarmvault graph update` for code-only drift and `swarmvault compile` when semantic refresh is required
+### `swarmvault update [path]`
+Compatibility alias for `swarmvault graph update [path]`.
+- runs the same code-only repo refresh path
+- accepts `--lint` and `--force`
+- returns the same JSON shape as `graph update`
 ### `swarmvault graph tree [--output <html>] [--root <path>] [--label <name>] [--max-children <n>]`
 Write a collapsible HTML source tree for the current `state/graph.json`.
@@ -429,6 +461,25 @@ 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 graph stats`
+Summarize the current compiled graph without opening the viewer.
+- reports source, page, node, edge, hyperedge, and community counts
+- breaks down node types, evidence classes, source classes, edge relations, and hyperedge relations
+- keeps the same lightweight shape as the MCP `graph_stats` tool
+- supports global `--json` for automation
+### `swarmvault graph validate [graph] [--strict]`
+Validate graph artifact integrity before exporting, merging, pushing, or publishing generated graph evidence.
+- defaults to the current vault's compiled `state/graph.json`
+- accepts an explicit graph JSON path for exported or merged graph artifacts
+- checks duplicate ids, dangling node/page/community/hyperedge references, confidence bounds, empty critical fields, and conflicted-edge evidence consistency
+- exits non-zero when errors are present; with `--strict`, warnings also fail the command
+- supports global `--json` for automation
 ### `swarmvault graph cluster [--resolution <n>]`
 Recompute communities, node degrees, bridge scores, god-node flags, and graph report artifacts from the existing `state/graph.json` without re-ingesting or re-analyzing sources.
@@ -439,6 +490,21 @@ Recompute communities, node degrees, bridge scores, god-node flags, and graph re
 - splits oversized or low-cohesion communities after the initial Louvain pass so large-repo reports stay scannable
 - `--json` returns counts plus the graph/report paths
+### `swarmvault cluster-only [vault] [--resolution <n>]`
+Compatibility alias for `swarmvault graph cluster`.
+- recomputes communities and graph report artifacts without ingest or semantic analysis
+- accepts an optional vault root when the command is run from outside the vault
+- returns the same JSON shape as `graph cluster`
+### `swarmvault graph export --neo4j <path>`
+Compatibility alias for `swarmvault graph export --cypher <path>`.
+- writes a Neo4j-ready Cypher import file
+- can be combined with other `graph export` formats in the same run
 ### `swarmvault hook install|uninstall|status`
 Manage SwarmVault's local git hook blocks for the nearest git repository.

package/dist/index.js CHANGED Viewed

@@ -39,6 +39,7 @@ import {
   getRetrievalStatus,
   getWatchStatus,
   graphDiff,
+  graphStatsVault,
   guideManagedSource,
   guideSourceScope,
   importInbox,
@@ -95,6 +96,7 @@ import {
   summarizeLocalWhisperSetup,
   uninstallGitHooks,
   updateMemoryTask,
+  validateGraphVault,
   watchVault
 } from "@swarmvaultai/engine";
 import { Command, Option } from "commander";
@@ -313,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.8.0";
+    return typeof packageJson.version === "string" && packageJson.version.trim() ? packageJson.version : "3.10.0";
   } catch {
-    return "3.8.0";
+    return "3.10.0";
   }
 }
 function parsePositiveInt(value, fallback) {
@@ -364,6 +366,9 @@ function summarizeRedactions(redactions) {
   const sourceLabel = redactions.length === 1 ? "source" : "sources";
   return `Redacted ${totalMatches} ${secretsLabel} across ${redactions.length} ${sourceLabel} (run --no-redact to disable).`;
 }
+function topCountEntries(record, limit = 8) {
+  return Object.entries(record).filter(([, count]) => count > 0).sort((left, right) => right[1] - left[1] || left[0].localeCompare(right[0])).slice(0, limit);
+}
 function emitJson(data) {
   process2.stdout.write(`${JSON.stringify(data)}
 `);
@@ -483,6 +488,63 @@ function getCommandPath(command) {
   }
   return names;
 }
+async function runGraphUpdateCommand(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()) {
+    emitJson(result);
+    return;
+  }
+  log(
+    `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}.`
+  );
+}
+async function showGraphStatusCommand(targetPath) {
+  const overrideRoots = targetPath ? [path2.resolve(process2.cwd(), targetPath)] : void 0;
+  const status = await getGraphStatus(process2.cwd(), { repoRoots: overrideRoots });
+  if (isJson()) {
+    emitJson(status);
+    return;
+  }
+  log(`Graph: ${status.graphExists ? status.graphPath : `missing (${status.graphPath})`}`);
+  log(`Report: ${status.reportExists ? status.reportPath : `missing (${status.reportPath})`}`);
+  log(`Tracked repo roots: ${status.trackedRepoRoots.length ? status.trackedRepoRoots.join(", ") : "none"}`);
+  log(`Code changes: ${status.codeChangeCount}`);
+  log(`Semantic changes: ${status.semanticChangeCount}`);
+  log(`Pending semantic refresh: ${status.pendingSemanticRefresh.length}`);
+  if (status.changes.length) {
+    for (const change of status.changes.slice(0, 20)) {
+      log(`- ${change.refreshType} ${change.changeType} ${change.path}`);
+    }
+    if (status.changes.length > 20) {
+      log(`... and ${status.changes.length - 20} more`);
+    }
+  }
+  log(`State: ${status.stale ? "stale" : "fresh"}`);
+  if (status.recommendedCommand) {
+    log(`Recommended: ${status.recommendedCommand}`);
+  }
+}
+async function runGraphClusterCommand(options, rootDir = process2.cwd()) {
+  const resolution = parsePositiveNumber(options.resolution);
+  if (options.resolution && resolution === void 0) {
+    throw new Error("--resolution must be a positive number.");
+  }
+  const result = await refreshGraphClusters(rootDir, { resolution });
+  if (isJson()) {
+    emitJson(result);
+    return;
+  }
+  log(
+    `Refreshed ${result.communityCount} communities across ${result.nodeCount} nodes and ${result.edgeCount} edges. Report: ${result.reportPath}`
+  );
+}
 program.hook("postAction", async (_thisCommand, actionCommand) => {
   const notices = await collectCliNotices({
     commandPath: getCommandPath(actionCommand),
@@ -1152,23 +1214,7 @@ 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(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()) {
-    emitJson(result);
-    return;
-  }
-  log(
-    `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("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, {
@@ -1199,46 +1245,48 @@ graph.command("merge").description("Merge SwarmVault or node-link JSON graph fil
     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 });
+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());
   if (isJson()) {
-    emitJson(status);
+    emitJson(stats);
     return;
   }
-  log(`Graph: ${status.graphExists ? status.graphPath : `missing (${status.graphPath})`}`);
-  log(`Report: ${status.reportExists ? status.reportPath : `missing (${status.reportPath})`}`);
-  log(`Tracked repo roots: ${status.trackedRepoRoots.length ? status.trackedRepoRoots.join(", ") : "none"}`);
-  log(`Code changes: ${status.codeChangeCount}`);
-  log(`Semantic changes: ${status.semanticChangeCount}`);
-  log(`Pending semantic refresh: ${status.pendingSemanticRefresh.length}`);
-  if (status.changes.length) {
-    for (const change of status.changes.slice(0, 20)) {
-      log(`- ${change.refreshType} ${change.changeType} ${change.path}`);
-    }
-    if (status.changes.length > 20) {
-      log(`... and ${status.changes.length - 20} more`);
-    }
+  log(
+    `Graph stats: ${stats.counts.nodes} nodes, ${stats.counts.edges} edges, ${stats.counts.pages} pages, ${stats.counts.hyperedges} hyperedges, ${stats.counts.communities} communities.`
+  );
+  const nodeTypes = topCountEntries(stats.nodeTypes);
+  if (nodeTypes.length) {
+    log(`Node types: ${nodeTypes.map(([name, count]) => `${name}=${count}`).join(", ")}`);
   }
-  log(`State: ${status.stale ? "stale" : "fresh"}`);
-  if (status.recommendedCommand) {
-    log(`Recommended: ${status.recommendedCommand}`);
+  const evidence = topCountEntries(stats.evidenceClasses);
+  if (evidence.length) {
+    log(`Evidence: ${evidence.map(([name, count]) => `${name}=${count}`).join(", ")}`);
   }
-});
-graph.command("cluster").alias("clusters").description("Recompute graph communities, degrees, god-node flags, and graph report artifacts without re-ingesting sources.").option("--resolution <number>", "Override the Louvain community resolution for this run").action(async (options) => {
-  const resolution = parsePositiveNumber(options.resolution);
-  if (options.resolution && resolution === void 0) {
-    throw new Error("--resolution must be a positive number.");
+  const relations = topCountEntries(stats.edgeRelations);
+  if (relations.length) {
+    log(`Top relations: ${relations.map(([name, count]) => `${name}=${count}`).join(", ")}`);
   }
-  const result = await refreshGraphClusters(process2.cwd(), { resolution });
+});
+graph.command("validate").description("Validate a compiled graph artifact for dangling references, duplicate ids, and confidence bounds.").argument("[graph]", "Optional graph JSON path; defaults to the current vault graph").option("--strict", "Treat warnings as failures", false).action(async (graphPath, options) => {
+  const result = await validateGraphVault(process2.cwd(), {
+    graphPath,
+    strict: options.strict ?? false
+  });
   if (isJson()) {
     emitJson(result);
-    return;
+  } else {
+    log(result.summary);
+    for (const issue of result.issues) {
+      const location = issue.path ? ` ${issue.path}` : "";
+      log(`[${issue.severity}] ${issue.code}${location}: ${issue.message}`);
+    }
+  }
+  if (!result.ok) {
+    process2.exitCode = 1;
   }
-  log(
-    `Refreshed ${result.communityCount} communities across ${result.nodeCount} nodes and ${result.edgeCount} edges. Report: ${result.reportPath}`
-  );
 });
+graph.command("cluster").alias("clusters").description("Recompute graph communities, degrees, god-node flags, and graph report artifacts without re-ingesting sources.").option("--resolution <number>", "Override the Louvain community resolution for this run").action((options) => runGraphClusterCommand(options));
 graphPush.command("neo4j").description("Push the compiled graph directly into Neo4j over Bolt/Aura.").option("--uri <bolt-uri>", "Neo4j Bolt or Aura URI").option("--username <user>", "Neo4j username").option("--password-env <env-var>", "Environment variable containing the Neo4j password").option("--database <name>", "Neo4j database name").option("--vault-id <id>", "Stable vault identifier used for shared-database namespacing").option("--batch-size <n>", "Maximum rows to write per Neo4j transaction batch").option("--include-third-party", "Also push third-party repo material", false).option("--include-resources", "Also push resource-like content", false).option("--include-generated", "Also push generated output", false).option("--dry-run", "Show what would be pushed without writing to Neo4j", false).action(
   async (options) => {
     const batchSize = typeof options.batchSize === "string" && options.batchSize.trim() ? parsePositiveInt(options.batchSize, 0) || void 0 : void 0;
@@ -1294,7 +1342,7 @@ graph.command("serve").description("Serve the local graph viewer.").option("--po
 });
 graph.command("export").description(
   "Export the graph as HTML, report, SVG, GraphML, Cypher, JSON, Obsidian vault, or Obsidian canvas. Combine flags to write multiple formats in one run."
-).option("--html <output>", "Output HTML file path").option("--html-standalone <output>", "Output lightweight standalone HTML file path (vis.js, no build tooling)").option("--report <output>", "Output self-contained HTML report (graph stats, key nodes, communities)").option("--svg <output>", "Output SVG file path").option("--graphml <output>", "Output GraphML file path").option("--cypher <output>", "Output Cypher file path").option("--json <output>", "Output JSON file path").option("--obsidian <output>", "Output Obsidian vault directory path").option("--canvas <output>", "Output Obsidian canvas file path").option("--full", "Include the full graph in HTML export (default; queries traverse complete graph)", true).option("--overview", "Use overview sampling for HTML export (smaller file, queries limited to sampled nodes)", false).action(
+).option("--html <output>", "Output HTML file path").option("--html-standalone <output>", "Output lightweight standalone HTML file path (vis.js, no build tooling)").option("--report <output>", "Output self-contained HTML report (graph stats, key nodes, communities)").option("--svg <output>", "Output SVG file path").option("--graphml <output>", "Output GraphML file path").option("--cypher <output>", "Output Cypher file path").option("--neo4j <output>", "Compatibility alias for --cypher, writing a Neo4j Cypher import file").option("--json <output>", "Output JSON file path").option("--obsidian <output>", "Output Obsidian vault directory path").option("--canvas <output>", "Output Obsidian canvas file path").option("--full", "Include the full graph in HTML export (default; queries traverse complete graph)", true).option("--overview", "Use overview sampling for HTML export (smaller file, queries limited to sampled nodes)", false).action(
   async (options) => {
     const useFullGraph = options.overview ? false : options.full ?? true;
     const targets = [
@@ -1304,13 +1352,14 @@ graph.command("export").description(
       options.svg ? { format: "svg", outputPath: options.svg } : null,
       options.graphml ? { format: "graphml", outputPath: options.graphml } : null,
       options.cypher ? { format: "cypher", outputPath: options.cypher } : null,
+      options.neo4j ? { format: "cypher", outputPath: options.neo4j } : null,
       options.json ? { format: "json", outputPath: options.json } : null,
       options.obsidian ? { format: "obsidian", outputPath: options.obsidian } : null,
       options.canvas ? { format: "canvas", outputPath: options.canvas } : null
     ].filter((target) => Boolean(target));
     if (targets.length === 0) {
       throw new Error(
-        "Pass at least one of --html, --html-standalone, --report, --svg, --graphml, --cypher, --json, --obsidian, or --canvas."
+        "Pass at least one of --html, --html-standalone, --report, --svg, --graphml, --cypher, --neo4j, --json, --obsidian, or --canvas."
       );
     }
     const results = [];
@@ -1731,6 +1780,11 @@ async function showWatchStatus() {
 }
 watch.command("status").description("Show the latest watch run plus pending semantic refresh entries.").action(showWatchStatus);
 program.command("watch-status").description("Show the latest watch run plus pending semantic refresh entries.").action(showWatchStatus);
+program.command("check-update").description("Compatibility alias for graph status: read-only graph/report freshness and tracked repo change check.").argument("[path]", "Optional repo root to check instead of configured/tracked roots").action(showGraphStatusCommand);
+program.command("update").description("Compatibility alias for graph update: refresh code-derived graph artifacts from tracked repo roots.").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);
+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())
+);
 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());

package/package.json CHANGED Viewed

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