@swarmvaultai/cli 0.3.0 → 0.5.0

package/README.md

@@ -22,9 +22,10 @@ Installed commands:
 ```bash
 mkdir my-vault
 cd my-vault
-swarmvault init --obsidian
+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 list
 swarmvault source reload --all
 sed -n '1,120p' swarmvault.schema.md
@@ -50,7 +51,7 @@ swarmvault graph push neo4j --dry-run
 
 ## Commands
 
-### `swarmvault init [--obsidian]`
+### `swarmvault init [--obsidian] [--profile personal-research]`
 
 Create a workspace with:
 
@@ -67,19 +68,23 @@ 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|delete`
+### `swarmvault source add|list|reload|review|guide|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
 - 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
 - `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 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`
 - `--no-compile`
 - `--no-brief`
 - `--max-pages <n>`
@@ -97,6 +102,7 @@ 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
 - 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:

package/dist/index.js

@@ -17,6 +17,8 @@ import {
   exportGraphHtml,
   getGitHookStatus,
   getWatchStatus,
+  guideManagedSource,
+  guideSourceScope,
   importInbox,
   ingestDirectory,
   ingestInputDetailed,
@@ -28,6 +30,7 @@ import {
   listCandidates,
   listGodNodes,
   listManagedSourceRecords,
+  listManifests,
   listSchedules,
   loadVaultConfig,
   pathGraphVault,
@@ -38,6 +41,8 @@ import {
   readApproval,
   rejectApproval,
   reloadManagedSources,
+  reviewManagedSource,
+  reviewSourceScope,
   runSchedule,
   runWatchCycle,
   serveSchedules,
@@ -221,9 +226,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.3.0";
+    return typeof packageJson.version === "string" && packageJson.version.trim() ? packageJson.version : "0.5.0";
   } catch {
-    return "0.3.0";
+    return "0.5.0";
   }
 }
 function parsePositiveInt(value, fallback) {
@@ -231,6 +236,21 @@ function parsePositiveInt(value, fallback) {
   const parsed = Number.parseInt(value, 10);
   return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
 }
+function sourceScopeFromManifests(input, manifests) {
+  if (!manifests.length) {
+    return null;
+  }
+  const primary = manifests[0];
+  return {
+    id: primary?.sourceGroupId ?? primary?.sourceId ?? slugForCli(input),
+    title: primary?.sourceGroupTitle ?? primary?.title ?? input,
+    sourceIds: manifests.map((manifest) => manifest.sourceId),
+    kind: primary?.sourceKind
+  };
+}
+function slugForCli(value) {
+  return value.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "source";
+}
 function isJson() {
   return program.opts().json === true;
 }
@@ -273,15 +293,20 @@ program.hook("postAction", async (_thisCommand, actionCommand) => {
     emitNotice(notice);
   }
 });
-program.command("init").description("Initialize a SwarmVault workspace in the current directory.").option("--obsidian", "Generate a minimal .obsidian workspace alongside the vault", false).action(async (options) => {
-  await initVault(process2.cwd(), { obsidian: options.obsidian ?? false });
+program.command("init").description("Initialize a SwarmVault workspace in the current directory.").option("--obsidian", "Generate a minimal .obsidian workspace alongside the vault", false).addOption(new Option("--profile <profile>", "Starter workspace profile").choices(["default", "personal-research"])).action(async (options) => {
+  await initVault(process2.cwd(), { obsidian: options.obsidian ?? false, profile: options.profile });
   if (isJson()) {
-    emitJson({ status: "initialized", rootDir: process2.cwd(), obsidian: options.obsidian ?? false });
+    emitJson({
+      status: "initialized",
+      rootDir: process2.cwd(),
+      obsidian: options.obsidian ?? false,
+      profile: options.profile ?? "default"
+    });
   } else {
     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("--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("--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 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;
@@ -305,18 +330,59 @@ program.command("ingest").description("Ingest a local file path, directory path,
       (fs) => fs.stat(input).then((stat) => stat.isDirectory() ? ingestDirectory(process2.cwd(), input, commonOptions) : null).catch(() => null)
     ) : null;
     if (directoryResult) {
+      const scope2 = options.review || options.guide ? await (async () => {
+        const pathModule = await import("path");
+        const absoluteInput = pathModule.resolve(process2.cwd(), input);
+        const sourceIds = (await listManifests(process2.cwd())).filter((manifest) => {
+          if (!manifest.originalPath) {
+            return false;
+          }
+          const relative = pathModule.relative(absoluteInput, pathModule.resolve(manifest.originalPath));
+          return relative === "" || !relative.startsWith("..") && !pathModule.isAbsolute(relative);
+        }).map((manifest) => manifest.sourceId);
+        return sourceIds.length ? {
+          id: `directory-${absoluteInput.split(pathModule.sep).pop() ?? "source"}`,
+          title: absoluteInput.split(pathModule.sep).pop() ?? absoluteInput,
+          sourceIds,
+          kind: "directory"
+        } : void 0;
+      })() : void 0;
+      const shouldStage = Boolean(scope2 && (directoryResult.imported.length || directoryResult.updated.length));
+      const review3 = shouldStage && options.review && !options.guide ? await (async () => {
+        await compileVault(process2.cwd(), {});
+        return await reviewSourceScope(process2.cwd(), scope2);
+      })() : void 0;
+      const guide2 = shouldStage && options.guide ? await (async () => {
+        await compileVault(process2.cwd(), {});
+        return await guideSourceScope(process2.cwd(), scope2);
+      })() : void 0;
       if (isJson()) {
-        emitJson(directoryResult);
+        emitJson(guide2 ? { ingest: directoryResult, guide: guide2 } : review3 ? { ingest: directoryResult, review: review3 } : directoryResult);
       } else {
         log(
           `Imported ${directoryResult.imported.length} file(s), updated ${directoryResult.updated.length}, skipped ${directoryResult.skipped.length}.`
         );
+        if (review3) {
+          log(`Staged source review at ${review3.reviewPath}.`);
+        }
+        if (guide2) {
+          log(`Staged source guide at ${guide2.guidePath}.`);
+        }
       }
       return;
     }
     const ingest = await ingestInputDetailed(process2.cwd(), input, commonOptions);
+    const scope = sourceScopeFromManifests(input, [...ingest.created, ...ingest.updated, ...ingest.unchanged]);
+    const review2 = options.review && !options.guide && scope && (ingest.created.length || ingest.updated.length || ingest.unchanged.length) ? await (async () => {
+      await compileVault(process2.cwd(), {});
+      return await reviewSourceScope(process2.cwd(), scope);
+    })() : 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);
+    })() : void 0;
     if (isJson()) {
-      emitJson(ingest);
+      emitJson(guide ? { ingest, guide } : 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) {
@@ -326,6 +392,12 @@ program.command("ingest").description("Ingest a local file path, directory path,
           `Created ${ingest.created.length}, updated ${ingest.updated.length}, unchanged ${ingest.unchanged.length}, removed ${ingest.removed.length}.`
         );
       }
+      if (review2) {
+        log(`Staged source review at ${review2.reviewPath}.`);
+      }
+      if (guide) {
+        log(`Staged source guide at ${guide.guidePath}.`);
+      }
     }
   }
 );
@@ -340,22 +412,26 @@ program.command("add").description("Capture supported URLs into normalized markd
     log(`${result.captureType}${result.fallback ? " (fallback)" : ""}: ${result.manifest.sourceId}`);
   }
 });
-var source = program.command("source").description("Manage recurring directory, public repo, and docs sources.");
-source.command("add").description("Register and sync a managed source from a directory, public GitHub repo root URL, or docs hub URL.").argument("<input>", "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("--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 result = await addManagedSource(process2.cwd(), input, {
-    compile: options.compile,
-    brief: options.brief,
-    maxPages: options.maxPages ? parsePositiveInt(options.maxPages, 0) || void 0 : void 0,
-    maxDepth: options.maxDepth ? parsePositiveInt(options.maxDepth, 0) || void 0 : void 0
-  });
-  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}` : ""}`
-    );
+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(
+  async (input, options) => {
+    const result = await addManagedSource(process2.cwd(), input, {
+      compile: options.compile,
+      brief: options.brief,
+      review: options.review,
+      guide: options.guide,
+      maxPages: options.maxPages ? parsePositiveInt(options.maxPages, 0) || void 0 : void 0,
+      maxDepth: options.maxDepth ? parsePositiveInt(options.maxDepth, 0) || void 0 : void 0
+    });
+    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}` : ""}`
+      );
+    }
   }
-});
+);
 source.command("list").description("List managed sources registered in this vault.").action(async () => {
   const sources = await listManagedSourceRecords(process2.cwd());
   if (isJson()) {
@@ -368,13 +444,15 @@ 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("--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("--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 result = await reloadManagedSources(process2.cwd(), {
       id,
       all: options.all ?? false,
       compile: options.compile,
       brief: options.brief,
+      review: options.review,
+      guide: options.guide,
       maxPages: options.maxPages ? parsePositiveInt(options.maxPages, 0) || void 0 : void 0,
       maxDepth: options.maxDepth ? parsePositiveInt(options.maxDepth, 0) || void 0 : void 0
     });
@@ -382,7 +460,7 @@ source.command("reload").description("Re-sync one managed source or all managed
       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}.` : ""}`
+        `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}.` : ""}`
       );
     }
   }
@@ -395,6 +473,22 @@ source.command("delete").description("Unregister a managed source and remove its
     log(`Deleted managed source ${result.removed.id}. Canonical vault content was left in place.`);
   }
 });
+source.command("review").description("Stage a source review artifact for a managed source id or raw source id.").argument("<id>", "Managed source id or raw source id").action(async (id) => {
+  const result = await reviewManagedSource(process2.cwd(), id);
+  if (isJson()) {
+    emitJson(result);
+  } else {
+    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);
+  if (isJson()) {
+    emitJson(result);
+  } else {
+    log(`Staged source guide at ${result.guidePath}.`);
+  }
+});
 var inbox = program.command("inbox").description("Inbox and capture workflows.");
 inbox.command("import").description("Import supported files from the configured inbox directory.").argument("[dir]", "Optional inbox directory override").action(async (dir) => {
   const result = await importInbox(process2.cwd(), dir);
@@ -605,7 +699,7 @@ review.command("list").description("List staged approval bundles and their resol
   }
   for (const approval of approvals) {
     log(
-      `${approval.approvalId} pending=${approval.pendingCount} accepted=${approval.acceptedCount} rejected=${approval.rejectedCount} created=${approval.createdAt}`
+      `${approval.approvalId}${approval.bundleType ? ` [${approval.bundleType}]` : ""}${approval.title ? ` ${approval.title}` : ""} pending=${approval.pendingCount} accepted=${approval.acceptedCount} rejected=${approval.rejectedCount} created=${approval.createdAt}`
     );
   }
 });
@@ -615,9 +709,13 @@ review.command("show").description("Show the entries inside a staged approval bu
     emitJson(approval);
     return;
   }
-  log(`${approval.approvalId} pending=${approval.pendingCount} accepted=${approval.acceptedCount} rejected=${approval.rejectedCount}`);
+  log(
+    `${approval.approvalId}${approval.bundleType ? ` [${approval.bundleType}]` : ""}${approval.title ? ` ${approval.title}` : ""} pending=${approval.pendingCount} accepted=${approval.acceptedCount} rejected=${approval.rejectedCount}`
+  );
   for (const entry of approval.entries) {
-    log(`- ${entry.status} ${entry.changeType} ${entry.pageId} ${entry.nextPath ?? entry.previousPath ?? ""}`.trim());
+    log(
+      `- ${entry.status} ${entry.changeType}${entry.label ? ` [${entry.label}]` : ""} ${entry.pageId} ${entry.nextPath ?? entry.previousPath ?? ""}`.trim()
+    );
     if (entry.changeSummary) log(`  Summary: ${entry.changeSummary}`);
     if (entry.diff) {
       log("");

package/package.json

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