@swarmvaultai/cli 3.11.0 → 3.12.0

package/README.md

@@ -56,6 +56,9 @@ swarmvault graph share --svg ./share-card.svg
 swarmvault graph share --bundle ./share-kit
 swarmvault benchmark
 swarmvault query "What keeps recurring?" --commit
+swarmvault chat "What should the next agent know?"
+swarmvault chat --resume <session-id> "What changed?"
+swarmvault export ai --out ./exports/ai
 swarmvault context build "Ship this feature safely" --target ./src --budget 8000
 swarmvault task start "Ship this feature safely" --target ./src --agent codex
 swarmvault retrieval status
@@ -155,6 +158,28 @@ Compare the current `state/graph.json` against the last committed graph in git.
 - when no git baseline exists, falls back to a summary of the current graph state
 - supports `--json` for structured automation output
 
+### `swarmvault chat [question...] [--resume [id]] [--list] [--delete <id>]`
+
+Ask the compiled wiki in a persisted multi-turn session.
+
+- without a question, opens an interactive TTY chat loop with `/help`, `/sessions`, `/status`, `/clear`, and `/exit`
+- with a question, runs one turn and persists the transcript under `wiki/outputs/chat-sessions/`
+- stores structured session state under `state/chat-sessions/`
+- `--resume <id>` resumes by id or unique prefix; `--resume` alone resumes the most recent session
+- `--list` prints saved sessions and `--delete <id>` removes one
+- `--save-output` also writes each turn as a regular `wiki/outputs/` query page
+- supports `--format markdown|report|slides|chart|image`, `--gap-fill`, and global `--json`
+
+### `swarmvault export ai [--out <dir>] [--max-full-chars <n>] [--no-page-siblings]`
+
+Write a static AI handoff pack for agents, crawlers, and documentation systems.
+
+- defaults to `wiki/exports/ai/`
+- writes `llms.txt`, `llms-full.txt`, `graph.jsonld`, `manifest.json`, and `ai-readme.md`
+- writes per-page `.txt` and `.json` siblings under `pages/` unless `--no-page-siblings` is passed
+- caps `llms-full.txt` with `--max-full-chars` so huge vaults stay bounded
+- includes SHA-256 hashes and file metadata in `manifest.json`
+
 ### `swarmvault doctor [--repair]`
 
 Run a whole-vault health check before handing the workspace to an agent or opening the live viewer.

package/dist/index.js

@@ -12,6 +12,7 @@ import {
   addManagedSource,
   addWatchedRoot,
   archiveCandidate,
+  askChatSession,
   autoCommitWikiChanges,
   benchmarkVault,
   blastRadiusVault,
@@ -20,6 +21,7 @@ import {
   compileVault,
   consolidateVault,
   createSupersessionEdge,
+  deleteChatSession,
   deleteContextPack,
   deleteManagedSource,
   doctorRetrieval,
@@ -27,6 +29,7 @@ import {
   downloadWhisperModel,
   explainGraphVault,
   exploreVault,
+  exportAiPack,
   exportGraphFormat,
   exportGraphHtml,
   exportGraphReportHtml,
@@ -51,6 +54,7 @@ import {
   lintVault,
   listApprovals,
   listCandidates,
+  listChatSessions,
   listContextPacks,
   listGodNodes,
   listManagedSourceRecords,
@@ -315,9 +319,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.11.0";
+    return typeof packageJson.version === "string" && packageJson.version.trim() ? packageJson.version : "3.12.0";
   } catch {
-    return "3.11.0";
+    return "3.12.0";
   }
 }
 function parsePositiveInt(value, fallback) {
@@ -649,6 +653,105 @@ async function runScanCommand(input, options) {
     emitJson({ ...result, compiled, shareCardPath, shareCardSvgPath, shareKitPath });
   }
 }
+async function resolveChatResumeId(resume) {
+  if (!resume) {
+    return void 0;
+  }
+  if (typeof resume === "string") {
+    return resume;
+  }
+  const sessions = await listChatSessions(process2.cwd());
+  return sessions[0]?.id;
+}
+function logChatSessions(sessions) {
+  if (!sessions.length) {
+    log("No chat sessions yet.");
+    return;
+  }
+  for (const session of sessions) {
+    log(`${session.id}  ${session.turnCount} turn${session.turnCount === 1 ? "" : "s"}  ${session.title}`);
+    log(`  updated: ${session.updatedAt}`);
+    log(`  markdown: ${session.markdownPath}`);
+  }
+}
+async function runChatQuestion(question, options) {
+  const sessionId = await resolveChatResumeId(options.resume);
+  return askChatSession(process2.cwd(), {
+    question,
+    sessionId,
+    saveOutput: options.saveOutput ?? false,
+    gapFill: options.gapFill ?? false,
+    format: options.format,
+    maxHistoryTurns: parsePositiveInt(options.maxHistoryTurns, 6)
+  });
+}
+async function runInteractiveChat(options) {
+  if (isJson()) {
+    throw new Error("Interactive chat is not available with --json. Pass a question for one-shot JSON output.");
+  }
+  if (!process2.stdin.isTTY) {
+    throw new Error("Pass a chat question, or run `swarmvault chat` in an interactive terminal.");
+  }
+  let sessionId = await resolveChatResumeId(options.resume);
+  log(sessionId ? `Resuming chat session ${sessionId}.` : "Starting a new chat session.");
+  log("Type /help for commands or /exit to quit.");
+  const reader = createInterface({ input: process2.stdin, output: process2.stdout });
+  try {
+    while (true) {
+      const input = (await reader.question("swarmvault> ")).trim();
+      if (!input) {
+        continue;
+      }
+      if (input === "/exit" || input === "/quit") {
+        break;
+      }
+      if (input === "/help") {
+        log(
+          [
+            "/help              Show commands",
+            "/sessions          List chat sessions",
+            "/status            Show vault health summary",
+            "/clear             Start a fresh session",
+            "/exit              Quit"
+          ].join("\n")
+        );
+        continue;
+      }
+      if (input === "/sessions") {
+        logChatSessions(await listChatSessions(process2.cwd()));
+        continue;
+      }
+      if (input === "/status") {
+        const report = await doctorVault(process2.cwd(), {});
+        log(`Vault health: ${report.ok ? "ok" : "needs attention"} (${report.recommendations.length} recommendation(s))`);
+        for (const recommendation of report.recommendations.slice(0, 5)) {
+          log(`- ${recommendation.label}: ${recommendation.command ?? recommendation.summary}`);
+        }
+        continue;
+      }
+      if (input === "/clear") {
+        sessionId = void 0;
+        log("Started a fresh chat session.");
+        continue;
+      }
+      const result = await askChatSession(process2.cwd(), {
+        question: input,
+        sessionId,
+        saveOutput: options.saveOutput ?? false,
+        gapFill: options.gapFill ?? false,
+        format: options.format,
+        maxHistoryTurns: parsePositiveInt(options.maxHistoryTurns, 6)
+      });
+      sessionId = result.session.id;
+      log(result.answer);
+      log(`Session: ${result.session.id}`);
+      log(`Saved transcript: ${result.markdownPath}`);
+      await maybeEmitHeuristicNotice(["chat"]);
+    }
+  } finally {
+    reader.close();
+  }
+}
 program.hook("postAction", async (_thisCommand, actionCommand) => {
   const notices = await collectCliNotices({
     commandPath: getCommandPath(actionCommand),
@@ -1027,6 +1130,44 @@ program.command("query").description("Query the compiled SwarmVault wiki.").argu
     await maybeEmitHeuristicNotice(["query"]);
   }
 );
+program.command("chat").description("Ask the compiled wiki in a persisted multi-turn chat session.").argument("[question...]", "Question to ask in a chat session").option("--resume [id]", "Resume a chat session by id/prefix, or the most recent session when no id is supplied").option("--list", "List saved chat sessions", false).option("--delete <id>", "Delete a saved chat session by id/prefix").option("--save-output", "Also persist each answer as a regular wiki/outputs query page", false).option("--gap-fill", "Pull external web-search evidence when the local wiki has gaps (requires webSearch.tasks.queryProvider).").option("--max-history-turns <n>", "Number of prior turns to include as conversational context", "6").addOption(
+  new Option("--format <format>", "Answer format for generated turns").choices(["markdown", "report", "slides", "chart", "image"]).default("markdown")
+).action(
+  async (questionParts, options) => {
+    if (options.list) {
+      const sessions = await listChatSessions(process2.cwd());
+      if (isJson()) {
+        emitJson(sessions);
+      } else {
+        logChatSessions(sessions);
+      }
+      return;
+    }
+    if (options.delete) {
+      const deleted = await deleteChatSession(process2.cwd(), options.delete);
+      if (isJson()) {
+        emitJson(deleted);
+      } else {
+        log(`Deleted chat session ${deleted.id}`);
+      }
+      return;
+    }
+    const question = (questionParts ?? []).join(" ").trim();
+    if (!question) {
+      await runInteractiveChat(options);
+      return;
+    }
+    const result = await runChatQuestion(question, options);
+    if (isJson()) {
+      emitJson(result);
+    } else {
+      log(result.answer);
+      log(`Session: ${result.session.id}`);
+      log(`Saved transcript: ${result.markdownPath}`);
+    }
+    await maybeEmitHeuristicNotice(["chat"]);
+  }
+);
 var context = program.command("context").description("Build and manage token-bounded agent context packs.");
 context.command("build").description("Build a cited, token-bounded context pack for an agent task.").argument("<goal>", "Task, question, or goal the agent needs context for").option("--target <target>", "Optional page, node, path, project, or label to anchor the pack").option("--budget <tokens>", "Approximate token budget for included context", String(8e3)).option("--task <id>", "Attach the context pack to an agent task").option("--memory <id>", "Compatibility alias for --task").addOption(new Option("--format <format>", "Output format").choices(["markdown", "json", "llms"]).default("markdown")).action(
   async (goal, options) => {
@@ -1294,6 +1435,23 @@ program.command("benchmark").description("Measure graph-guided context reduction
     }
   }
 });
+var exportCommand = program.command("export").description("Export portable SwarmVault artifacts.");
+exportCommand.command("ai").description("Export static AI handoff files for agents, crawlers, and documentation systems.").option("--out <dir>", "Output directory", path2.join("wiki", "exports", "ai")).option("--max-full-chars <n>", "Maximum characters to include in llms-full.txt", "5000000").option("--no-page-siblings", "Skip per-page .txt and .json sibling files").action(async (options) => {
+  const result = await exportAiPack(process2.cwd(), {
+    outDir: options.out,
+    maxFullChars: parsePositiveInt(options.maxFullChars, 5e6),
+    pageSiblings: options.pageSiblings ?? true
+  });
+  if (isJson()) {
+    emitJson(result);
+    return;
+  }
+  log(`Exported AI handoff pack to ${result.outputDir}`);
+  log(`Files: ${result.files.length}; pages: ${result.pageCount}; nodes: ${result.nodeCount}; edges: ${result.edgeCount}`);
+  if (result.truncatedFullText) {
+    log("llms-full.txt was truncated; rerun with --max-full-chars for a larger export.");
+  }
+});
 program.command("lint").description("Run anti-drift and wiki-health checks.").option("--deep", "Run LLM-powered advisory lint (default: from config)").option("--no-deep", "Skip deep lint even if enabled in config").option("--web", "Augment deep lint with configured web search", false).option("--conflicts", "Filter to contradiction findings only", false).option("--decay", "Filter to decay-related findings only", false).option("--tiers", "Filter to consolidation-tier findings only", false).action(async (options) => {
   const lintConfig = await loadVaultConfig(process2.cwd()).catch(() => null);
   const deepEnabled = options.decay || options.tiers ? false : options.deep ?? lintConfig?.config.profile.deepLintDefault ?? false;

package/package.json

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