@swarmvaultai/cli 0.6.6 → 0.6.7

package/dist/index.js

@@ -61,10 +61,23 @@ import { mkdir, readFile, writeFile } from "fs/promises";
 import os from "os";
 import path from "path";
 var NOTICE_CACHE_TTL_MS = 24 * 60 * 60 * 1e3;
+var HEURISTIC_NOTICE_TTL_MS = 7 * 24 * 60 * 60 * 1e3;
 var NOTICE_TIMEOUT_MS = 2e3;
 var STAR_URL = "https://github.com/swarmclawai/swarmvault";
 var NPM_PACKAGE = "@swarmvaultai/cli";
 var SUPPRESSED_COMMANDS = /* @__PURE__ */ new Set(["graph serve", "mcp", "schedule serve", "watch"]);
+var HEURISTIC_NOTICE_MESSAGE = [
+  "SwarmVault is using the heuristic analyzer for compile/query.",
+  "For much sharper concepts, entities, and summaries, configure an LLM provider.",
+  "Recommended local setup:",
+  "  ollama pull gemma4",
+  "then add to swarmvault.config.json:",
+  '  "providers": { "llm": { "type": "ollama", "model": "gemma4" } },',
+  '  "tasks": { "compileProvider": "llm", "queryProvider": "llm" }',
+  "You can also configure openai, anthropic, gemini, openrouter, groq, together, xai,",
+  "cerebras, or any openai-compatible endpoint as a provider.",
+  "Set SWARMVAULT_NO_NOTICES=1 to hide this notice."
+].join("\n");
 function resolveCliStatePath(env = process.env) {
   const override = env.SWARMVAULT_CLI_STATE_PATH?.trim();
   if (override) {
@@ -93,6 +106,33 @@ function shouldEmitCliNotices(options) {
   const commandKey = options.commandPath.join(" ").trim();
   return !SUPPRESSED_COMMANDS.has(commandKey);
 }
+async function collectHeuristicProviderNotice(options) {
+  if (!shouldEmitCliNotices({
+    commandPath: options.commandPath ?? ["compile"],
+    currentVersion: "",
+    json: options.json,
+    env: options.env,
+    stderrIsTTY: options.stderrIsTTY,
+    stdoutIsTTY: options.stdoutIsTTY
+  })) {
+    return null;
+  }
+  const env = options.env ?? process.env;
+  const statePath = options.statePath ?? resolveCliStatePath(env);
+  if (!statePath) {
+    return null;
+  }
+  const state = await readNoticeState(statePath);
+  const now = options.now ?? /* @__PURE__ */ new Date();
+  const lastMs = state.lastHeuristicNoticeAt ? Date.parse(state.lastHeuristicNoticeAt) : Number.NaN;
+  const dueForReminder = !Number.isFinite(lastMs) || now.getTime() - lastMs >= HEURISTIC_NOTICE_TTL_MS;
+  if (!dueForReminder) {
+    return null;
+  }
+  const nextState = { ...state, lastHeuristicNoticeAt: now.toISOString() };
+  await writeNoticeState(statePath, nextState);
+  return HEURISTIC_NOTICE_MESSAGE;
+}
 async function collectCliNotices(options) {
   if (!shouldEmitCliNotices(options)) {
     return [];
@@ -228,9 +268,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 : "0.6.6";
+    return typeof packageJson.version === "string" && packageJson.version.trim() ? packageJson.version : "0.6.7";
   } catch {
-    return "0.6.6";
+    return "0.6.7";
   }
 }
 function parsePositiveInt(value, fallback) {
@@ -273,6 +313,31 @@ function emitNotice(message) {
   process2.stderr.write(`[swarmvault] ${message}
 `);
 }
+async function maybeEmitHeuristicNotice(commandPath) {
+  if (isJson()) {
+    return;
+  }
+  try {
+    const { config } = await loadVaultConfig(process2.cwd());
+    const analysisTaskKeys = ["compileProvider", "queryProvider", "lintProvider"];
+    const usingHeuristic = analysisTaskKeys.every((task) => {
+      const providerId = config.tasks[task];
+      const providerConfig = config.providers[providerId];
+      return !providerConfig || providerConfig.type === "heuristic";
+    });
+    if (!usingHeuristic) {
+      return;
+    }
+    const notice = await collectHeuristicProviderNotice({
+      commandPath,
+      json: isJson()
+    });
+    if (notice) {
+      emitNotice(notice);
+    }
+  } catch {
+  }
+}
 function canPromptGuide() {
   return Boolean(process2.stdin.isTTY && process2.stdout.isTTY && !isJson());
 }
@@ -612,6 +677,7 @@ program.command("compile").description("Compile manifests into wiki pages, graph
       log(`Compiled ${result.sourceCount} source(s), ${result.pageCount} page(s). Changed: ${result.changedPages.length}.`);
     }
   }
+  await maybeEmitHeuristicNotice(["compile"]);
 });
 program.command("query").description("Query the compiled SwarmVault wiki.").argument("<question>", "Question to ask SwarmVault").option("--no-save", "Do not persist the answer to wiki/outputs").addOption(
   new Option("--format <format>", "Output format").choices(["markdown", "report", "slides", "chart", "image"]).default("markdown")
@@ -629,6 +695,7 @@ program.command("query").description("Query the compiled SwarmVault wiki.").argu
       log(`Saved to ${result.savedPath}`);
     }
   }
+  await maybeEmitHeuristicNotice(["query"]);
 });
 program.command("explore").description("Run a save-first multi-step exploration loop against the vault.").argument("<question>", "Root question to explore").option("--steps <n>", "Maximum number of exploration steps", "3").addOption(
   new Option("--format <format>", "Output format for step pages").choices(["markdown", "report", "slides", "chart", "image"]).default("markdown")
@@ -645,6 +712,7 @@ program.command("explore").description("Run a save-first multi-step exploration
     log(`Exploration hub saved to ${result.hubPath}`);
     log(`Completed ${result.stepCount} step(s).`);
   }
+  await maybeEmitHeuristicNotice(["explore"]);
 });
 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(process2.cwd(), {
@@ -655,7 +723,13 @@ program.command("benchmark").description("Measure graph-guided context reduction
   } else {
     log(`Corpus tokens: ${result.corpusTokens}`);
     log(`Average query tokens: ${result.avgQueryTokens}`);
-    log(`Reduction ratio: ${(result.reductionRatio * 100).toFixed(1)}%`);
+    const ratioPercent = (result.reductionRatio * 100).toFixed(1);
+    log(`Reduction ratio: ${ratioPercent}%`);
+    if (result.reductionRatio < 0) {
+      log(
+        "Note: graph-guided context is larger than the full corpus on this vault. The benchmark is only meaningful once the corpus exceeds the graph traversal budget."
+      );
+    }
   }
 });
 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).option("--conflicts", "Filter to contradiction findings only", false).action(async (options) => {
@@ -730,22 +804,27 @@ graph.command("serve").description("Serve the local graph viewer.").option("--po
     process2.exit(0);
   });
 });
-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").option("--full", "Disable overview sampling for HTML export", false).action(async (options) => {
+graph.command("export").description("Export the graph as HTML, SVG, GraphML, or Cypher. Combine flags to write multiple formats in one run.").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").option("--full", "Disable overview sampling for HTML export", false).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.");
+  ].filter((target) => Boolean(target));
+  if (targets.length === 0) {
+    throw new Error("Pass at least one of --html, --svg, --graphml, or --cypher.");
+  }
+  const results = [];
+  for (const target of targets) {
+    const outputPath = target.format === "html" ? await exportGraphHtml(process2.cwd(), target.outputPath, { full: options.full ?? false }) : (await exportGraphFormat(process2.cwd(), target.format, target.outputPath)).outputPath;
+    results.push({ format: target.format, outputPath });
   }
-  const target = targets[0];
-  const outputPath = target.format === "html" ? await exportGraphHtml(process2.cwd(), target.outputPath, { full: options.full ?? false }) : (await exportGraphFormat(process2.cwd(), target.format, target.outputPath)).outputPath;
   if (isJson()) {
-    emitJson({ format: target.format, outputPath });
+    emitJson(results.length === 1 ? results[0] : { exports: results });
   } else {
-    log(`Exported graph ${target.format} to ${outputPath}`);
+    for (const result of results) {
+      log(`Exported graph ${result.format} to ${result.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) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarmvaultai/cli",
-  "version": "0.6.6",
+  "version": "0.6.7",
   "description": "Global CLI for SwarmVault.",
   "type": "module",
   "main": "dist/index.js",
@@ -38,7 +38,7 @@
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "@swarmvaultai/engine": "0.6.6",
+    "@swarmvaultai/engine": "0.6.7",
     "commander": "^14.0.1"
   },
   "devDependencies": {