@swarmvaultai/cli 0.5.0 → 0.6.0

package/README.md

@@ -26,6 +26,7 @@ swarmvault init --obsidian --profile personal-research
 swarmvault source add https://github.com/karpathy/micrograd
 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
 swarmvault source list
 swarmvault source reload --all
 sed -n '1,120p' swarmvault.schema.md
@@ -68,29 +69,31 @@ Create a workspace with:
 
 The schema file is the vault-specific instruction layer. Edit it to define naming rules, categories, grounding expectations, and exclusions before a serious compile.
 
-### `swarmvault source add|list|reload|review|guide|delete`
+### `swarmvault source add|list|reload|review|guide|session|delete`
 
 Manage recurring source roots through a registry-backed workflow.
 
-- `source add <input>` supports local directories, public GitHub repo root URLs such as `https://github.com/karpathy/micrograd`, and docs/wiki/help/reference/tutorial hubs
+- `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
 - 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 source brief, source review, source guide, and approval bundle for one-source-at-a-time integration
+- add `--guide` when you want a resumable source session, source brief, source review, source guide, and approval-bundled `wiki/insights/` updates for one-source-at-a-time integration
 - `source list` shows every managed source with its kind, status, and current brief path
 - `source reload [id]` re-syncs one source, or use `--all` to refresh everything in the registry and compile once
 - `source review <id>` stages a lighter source-scoped review artifact
-- `source guide <id>` stages the stronger guided-ingest bundle for that source scope
+- `source guide <id>` remains a compatibility alias for the guided session flow
+- `source session <id>` resumes the latest guided session for a managed source id, raw source id, source scope id, or session id
 - `source delete <id>` unregisters the source and removes transient sync state under `state/sources/<id>/`, but leaves canonical `raw/`, `wiki/`, and saved output artifacts intact
 
 Useful flags:
 
 - `--all`
 - `--guide`
+- `--answers-file <path>`
 - `--no-compile`
 - `--no-brief`
 - `--max-pages <n>`
 - `--max-depth <n>`
 
-Managed sources write registry state to `state/sources.json`. Local directory entries remain compatible with `watch --repo`; remote GitHub and docs-crawl sources are manual `source reload` sources in this release.
+Managed sources write registry state to `state/sources.json`. Guided sessions write durable anchors to `wiki/outputs/source-sessions/` and session state to `state/source-sessions/`. In an interactive TTY, `--guide` can ask the session questions immediately; otherwise use `source session <id>` or `--answers-file <path>` to resume and stage the approval bundle later. Local directory entries remain compatible with `watch --repo`; remote GitHub and docs-crawl sources are manual `source reload` sources in this release.
 
 ### `swarmvault ingest <path-or-url>`
 
@@ -102,12 +105,13 @@ Ingest a local file path, directory path, or URL into immutable source storage a
 - use `source add` instead when the same local directory, public GitHub repo root, or docs hub should stay registered and reloadable
 - URL ingest still localizes remote image references by default
 - local file ingest supports markdown, text, reStructuredText, HTML, PDF, DOCX, images, and code
-- add `--guide` when you want a source brief, source review, source guide, and approval bundle after ingest
+- add `--guide` when you want a resumable source session, source brief, source review, source guide, and approval-bundled `wiki/insights/` updates after ingest
 - code-aware directory ingest currently covers JavaScript, JSX, TypeScript, TSX, Python, Go, Rust, Java, Kotlin, Scala, Lua, Zig, C#, C, C++, PHP, Ruby, and PowerShell
 
 Useful flags:
 
 - `--repo-root <path>`
+- `--answers-file <path>`
 - `--include <glob...>`
 - `--exclude <glob...>`
 - `--max-files <n>`

package/dist/index.js

@@ -3,6 +3,7 @@
 // src/index.ts
 import { readFileSync } from "fs";
 import process2 from "process";
+import { createInterface } from "readline/promises";
 import {
   acceptApproval,
   addInput,
@@ -41,6 +42,7 @@ import {
   readApproval,
   rejectApproval,
   reloadManagedSources,
+  resumeSourceSession,
   reviewManagedSource,
   reviewSourceScope,
   runSchedule,
@@ -226,9 +228,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.5.0";
+    return typeof packageJson.version === "string" && packageJson.version.trim() ? packageJson.version : "0.6.0";
   } catch {
-    return "0.5.0";
+    return "0.6.0";
   }
 }
 function parsePositiveInt(value, fallback) {
@@ -271,6 +273,57 @@ function emitNotice(message) {
   process2.stderr.write(`[swarmvault] ${message}
 `);
 }
+function canPromptGuide() {
+  return Boolean(process2.stdin.isTTY && process2.stdout.isTTY && !isJson());
+}
+function readGuideAnswersFile(filePath) {
+  if (!filePath) {
+    return void 0;
+  }
+  const raw = JSON.parse(readFileSync(filePath, "utf8"));
+  if (Array.isArray(raw)) {
+    return raw.filter((value) => typeof value === "string");
+  }
+  if (raw && typeof raw === "object") {
+    return Object.fromEntries(
+      Object.entries(raw).filter((entry) => typeof entry[0] === "string" && typeof entry[1] === "string")
+    );
+  }
+  throw new Error("Guide answers files must contain either a JSON object keyed by question id or a JSON array of answers.");
+}
+async function promptGuideAnswers(questions) {
+  const rl = createInterface({
+    input: process2.stdin,
+    output: process2.stdout
+  });
+  try {
+    const answers = {};
+    for (const question of questions) {
+      const promptLines = [question.prompt];
+      if (question.answer) {
+        promptLines.push(`Current: ${question.answer}`);
+        promptLines.push("Press Enter to keep the current answer.");
+      }
+      const answer = (await rl.question(`${promptLines.join("\n")}
+> `)).trim();
+      if (answer) {
+        answers[question.id] = answer;
+      } else if (question.answer) {
+        answers[question.id] = question.answer;
+      }
+    }
+    return answers;
+  } finally {
+    rl.close();
+  }
+}
+async function completeGuideInteractively(guide, fallbackTarget) {
+  if (!guide.awaitingInput || !canPromptGuide()) {
+    return guide;
+  }
+  const answers = await promptGuideAnswers(guide.questions);
+  return await resumeSourceSession(process2.cwd(), guide.sessionId || fallbackTarget, { answers });
+}
 function getCommandPath(command) {
   const names = [];
   let current = command;
@@ -306,8 +359,9 @@ program.command("init").description("Initialize a SwarmVault workspace in the cu
     log("Initialized SwarmVault workspace.");
   }
 });
-program.command("ingest").description("Ingest a local file path, directory path, or URL into the raw SwarmVault workspace.").argument("<input>", "Local file path, directory path, or URL").option("--review", "Stage a source review artifact after ingest and compile", false).option("--guide", "Stage a guided source integration bundle after ingest and compile", false).option("--include-assets", "Download remote image assets when ingesting URLs", true).option("--no-include-assets", "Skip downloading remote image assets when ingesting URLs").option("--max-asset-size <bytes>", "Maximum number of bytes to fetch for a single remote image asset").option("--repo-root <path>", "Override the detected repo root when ingesting a directory").option("--include <glob...>", "Only ingest files matching one or more glob patterns").option("--exclude <glob...>", "Skip files matching one or more glob patterns").option("--max-files <n>", "Maximum number of files to ingest from a directory").option("--include-third-party", "Also ingest repo files classified as third-party", false).option("--include-resources", "Also ingest repo files classified as resources", false).option("--include-generated", "Also ingest repo files classified as generated output", false).option("--no-gitignore", "Ignore .gitignore rules when ingesting a directory").action(
+program.command("ingest").description("Ingest a local file path, directory path, or URL into the raw SwarmVault workspace.").argument("<input>", "Local file path, directory path, or URL").option("--review", "Stage a source review artifact after ingest and compile", false).option("--guide", "Stage a guided source integration bundle after ingest and compile", false).option("--answers-file <path>", "JSON file with guided-session answers keyed by question id or listed in prompt order").option("--include-assets", "Download remote image assets when ingesting URLs", true).option("--no-include-assets", "Skip downloading remote image assets when ingesting URLs").option("--max-asset-size <bytes>", "Maximum number of bytes to fetch for a single remote image asset").option("--repo-root <path>", "Override the detected repo root when ingesting a directory").option("--include <glob...>", "Only ingest files matching one or more glob patterns").option("--exclude <glob...>", "Skip files matching one or more glob patterns").option("--max-files <n>", "Maximum number of files to ingest from a directory").option("--include-third-party", "Also ingest repo files classified as third-party", false).option("--include-resources", "Also ingest repo files classified as resources", false).option("--include-generated", "Also ingest repo files classified as generated output", false).option("--no-gitignore", "Ignore .gitignore rules when ingesting a directory").action(
   async (input, options) => {
+    const guideAnswers = readGuideAnswersFile(options.answersFile);
     const maxAssetSize = typeof options.maxAssetSize === "string" && options.maxAssetSize.trim() ? parsePositiveInt(options.maxAssetSize, 0) || void 0 : void 0;
     const maxFiles = typeof options.maxFiles === "string" && options.maxFiles.trim() ? parsePositiveInt(options.maxFiles, 0) || void 0 : void 0;
     const extractClasses = [
@@ -354,10 +408,13 @@ program.command("ingest").description("Ingest a local file path, directory path,
       })() : void 0;
       const guide2 = shouldStage && options.guide ? await (async () => {
         await compileVault(process2.cwd(), {});
-        return await guideSourceScope(process2.cwd(), scope2);
+        return await guideSourceScope(process2.cwd(), scope2, { answers: guideAnswers });
       })() : void 0;
+      const completedGuide2 = guide2 && !options.answersFile ? await completeGuideInteractively(guide2, scope2?.id ?? input) : guide2;
       if (isJson()) {
-        emitJson(guide2 ? { ingest: directoryResult, guide: guide2 } : review3 ? { ingest: directoryResult, review: review3 } : directoryResult);
+        emitJson(
+          completedGuide2 ? { ingest: directoryResult, guide: completedGuide2 } : review3 ? { ingest: directoryResult, review: review3 } : directoryResult
+        );
       } else {
         log(
           `Imported ${directoryResult.imported.length} file(s), updated ${directoryResult.updated.length}, skipped ${directoryResult.skipped.length}.`
@@ -365,8 +422,12 @@ program.command("ingest").description("Ingest a local file path, directory path,
         if (review3) {
           log(`Staged source review at ${review3.reviewPath}.`);
         }
-        if (guide2) {
-          log(`Staged source guide at ${guide2.guidePath}.`);
+        if (completedGuide2?.awaitingInput) {
+          log(
+            `Created guided session at ${completedGuide2.sessionPath}. Resume with \`swarmvault source session ${completedGuide2.sessionId}\`.`
+          );
+        } else if (completedGuide2?.guidePath) {
+          log(`Staged guided session at ${completedGuide2.guidePath}.`);
         }
       }
       return;
@@ -379,10 +440,11 @@ program.command("ingest").description("Ingest a local file path, directory path,
     })() : void 0;
     const guide = options.guide && scope && (ingest.created.length || ingest.updated.length || ingest.unchanged.length) ? await (async () => {
       await compileVault(process2.cwd(), {});
-      return await guideSourceScope(process2.cwd(), scope);
+      return await guideSourceScope(process2.cwd(), scope, { answers: guideAnswers });
     })() : void 0;
+    const completedGuide = guide && !options.answersFile ? await completeGuideInteractively(guide, scope?.id ?? input) : guide;
     if (isJson()) {
-      emitJson(guide ? { ingest, guide } : review2 ? { ingest, review: review2 } : ingest);
+      emitJson(completedGuide ? { ingest, guide: completedGuide } : review2 ? { ingest, review: review2 } : ingest);
     } else {
       const primary = [...ingest.created, ...ingest.updated, ...ingest.unchanged][0];
       if (ingest.created.length + ingest.updated.length + ingest.removed.length <= 1 && primary) {
@@ -395,8 +457,12 @@ program.command("ingest").description("Ingest a local file path, directory path,
       if (review2) {
         log(`Staged source review at ${review2.reviewPath}.`);
       }
-      if (guide) {
-        log(`Staged source guide at ${guide.guidePath}.`);
+      if (completedGuide?.awaitingInput) {
+        log(
+          `Created guided session at ${completedGuide.sessionPath}. Resume with \`swarmvault source session ${completedGuide.sessionId}\`.`
+        );
+      } else if (completedGuide?.guidePath) {
+        log(`Staged guided session at ${completedGuide.guidePath}.`);
       }
     }
   }
@@ -413,21 +479,26 @@ 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", false).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", false).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(
   async (input, options) => {
+    const guideAnswers = readGuideAnswersFile(options.answersFile);
     const result = await addManagedSource(process2.cwd(), input, {
       compile: options.compile,
       brief: options.brief,
       review: options.review,
       guide: options.guide,
+      guideAnswers,
       maxPages: options.maxPages ? parsePositiveInt(options.maxPages, 0) || void 0 : void 0,
       maxDepth: options.maxDepth ? parsePositiveInt(options.maxDepth, 0) || void 0 : void 0
     });
+    if (result.guide && !options.answersFile) {
+      result.guide = await completeGuideInteractively(result.guide, result.source.id);
+    }
     if (isJson()) {
       emitJson(result);
     } else {
       log(
-        `Registered ${result.source.kind} source ${result.source.id}. Status: ${result.source.status}.${result.compile ? ` Compiled ${result.compile.sourceCount} source(s).` : ""}${result.briefGenerated ? ` Brief: ${result.source.briefPath}` : ""}${result.review ? ` Review: ${result.review.reviewPath}` : ""}${result.guide ? ` Guide: ${result.guide.guidePath}` : ""}`
+        `Registered ${result.source.kind} source ${result.source.id}. Status: ${result.source.status}.${result.compile ? ` Compiled ${result.compile.sourceCount} source(s).` : ""}${result.briefGenerated ? ` Brief: ${result.source.briefPath}` : ""}${result.review ? ` Review: ${result.review.reviewPath}` : ""}${result.guide?.awaitingInput ? ` Session: ${result.guide.sessionPath}. Resume with \`swarmvault source session ${result.guide.sessionId}\`.` : result.guide?.guidePath ? ` Guide: ${result.guide.guidePath}` : ""}`
       );
     }
   }
@@ -444,8 +515,9 @@ source.command("list").description("List managed sources registered in this vaul
     }
   }
 });
-source.command("reload").description("Re-sync one managed source or all managed sources, then optionally compile and refresh briefs.").argument("[id]", "Managed source id").option("--all", "Reload all managed sources", false).option("--no-compile", "Re-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", false).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("reload").description("Re-sync one managed source or all managed sources, then optionally compile and refresh briefs.").argument("[id]", "Managed source id").option("--all", "Reload all managed sources", false).option("--no-compile", "Re-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", false).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(
   async (id, options) => {
+    const guideAnswers = readGuideAnswersFile(options.answersFile);
     const result = await reloadManagedSources(process2.cwd(), {
       id,
       all: options.all ?? false,
@@ -453,14 +525,18 @@ source.command("reload").description("Re-sync one managed source or all managed
       brief: options.brief,
       review: options.review,
       guide: options.guide,
+      guideAnswers,
       maxPages: options.maxPages ? parsePositiveInt(options.maxPages, 0) || void 0 : void 0,
       maxDepth: options.maxDepth ? parsePositiveInt(options.maxDepth, 0) || void 0 : void 0
     });
+    if (!options.answersFile && result.guides.length === 1) {
+      result.guides = [await completeGuideInteractively(result.guides[0], result.sources[0]?.id ?? id ?? "source")];
+    }
     if (isJson()) {
       emitJson(result);
     } else {
       log(
-        `Reloaded ${result.sources.length} source(s).${result.compile ? ` Compiled ${result.compile.sourceCount} source(s).` : ""}${result.briefPaths.length ? ` Briefs: ${result.briefPaths.length}.` : ""}${result.reviews.length ? ` Reviews: ${result.reviews.length}.` : ""}${result.guides.length ? ` Guides: ${result.guides.length}.` : ""}`
+        `Reloaded ${result.sources.length} source(s).${result.compile ? ` Compiled ${result.compile.sourceCount} source(s).` : ""}${result.briefPaths.length ? ` Briefs: ${result.briefPaths.length}.` : ""}${result.reviews.length ? ` Reviews: ${result.reviews.length}.` : ""}${result.guides.length ? ` Guides/Sessions: ${result.guides.length}.` : ""}`
       );
     }
   }
@@ -481,12 +557,34 @@ source.command("review").description("Stage a source review artifact for a manag
     log(`Staged source review at ${result.reviewPath}.`);
   }
 });
-source.command("guide").description("Stage a guided source integration bundle for a managed source id or raw source id.").argument("<id>", "Managed source id or raw source id").action(async (id) => {
-  const result = await guideManagedSource(process2.cwd(), id);
+source.command("guide").description("Create or resume a guided source session for a managed source id or raw source id.").argument("<id>", "Managed source id or raw source id").option("--answers-file <path>", "JSON file with guided-session answers keyed by question id or listed in prompt order").action(async (id, options) => {
+  const guideAnswers = readGuideAnswersFile(options.answersFile);
+  let result = await guideManagedSource(process2.cwd(), id, { answers: guideAnswers });
+  if (!options.answersFile) {
+    result = await completeGuideInteractively(result, id);
+  }
+  if (isJson()) {
+    emitJson(result);
+  } else {
+    if (result.awaitingInput) {
+      log(`Created guided session at ${result.sessionPath}. Resume with \`swarmvault source session ${result.sessionId}\`.`);
+    } else {
+      log(`Staged guided session at ${result.guidePath}.`);
+    }
+  }
+});
+source.command("session").description("Resume the latest guided source session for a managed source id, raw source id, source scope id, or session id.").argument("<id>", "Managed source id, raw source id, source scope id, or guided session id").option("--answers-file <path>", "JSON file with guided-session answers keyed by question id or listed in prompt order").action(async (id, options) => {
+  const guideAnswers = readGuideAnswersFile(options.answersFile);
+  let result = await resumeSourceSession(process2.cwd(), id, { answers: guideAnswers });
+  if (!options.answersFile) {
+    result = await completeGuideInteractively(result, id);
+  }
   if (isJson()) {
     emitJson(result);
+  } else if (result.awaitingInput) {
+    log(`Updated guided session at ${result.sessionPath}. Resume with \`swarmvault source session ${result.sessionId}\` when ready.`);
   } else {
-    log(`Staged source guide at ${result.guidePath}.`);
+    log(`Staged guided session at ${result.guidePath}.`);
   }
 });
 var inbox = program.command("inbox").description("Inbox and capture workflows.");

package/package.json

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