@swarmvaultai/cli 1.0.1 → 1.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SwarmVault
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -39,6 +39,7 @@ swarmvault ingest ./repo
 swarmvault add https://arxiv.org/abs/2401.12345
 swarmvault compile --max-tokens 120000
 swarmvault diff
+swarmvault graph share --post
 swarmvault benchmark
 swarmvault query "What keeps recurring?" --commit
 swarmvault query "Turn this into slides" --format slides
@@ -85,6 +86,7 @@ Quick-start a scratch vault from a local directory in one command.
 - initializes the current directory as a SwarmVault workspace
 - ingests the supplied directory as local sources
 - compiles the vault immediately
+- writes `wiki/graph/share-card.md` and prints the path
 - starts `graph serve` unless you pass `--no-serve`
 - respects `--port` when you want a specific viewer port
 
@@ -97,6 +99,7 @@ Create a temporary sample vault with bundled sources, compile it immediately, an
 - writes the demo vault under the system temp directory
 - requires no API keys or extra setup
 - is the fastest way to inspect the full init + ingest + compile + graph workflow on a clean machine
+- writes `wiki/graph/share-card.md` inside the demo vault
 - respects `--port` when you want a specific viewer port
 
 ### `swarmvault diff`
@@ -207,6 +210,7 @@ Compile the current manifests into:
 - generated markdown in `wiki/`
 - structured graph data in `state/graph.json`
 - local search data in `state/search.sqlite`
+- a share card at `wiki/graph/share-card.md`
 
 The compiler also reads `swarmvault.schema.md` and records a `schema_hash` plus lifecycle metadata such as `status`, `created_at`, `updated_at`, `compiled_from`, and `managed_by` in generated pages so schema edits can mark pages stale without losing lifecycle state.
 
@@ -366,6 +370,15 @@ Inspect graph metadata, community membership, neighbors, provenance, and group-p
 
 List the most connected bridge-heavy nodes in the current graph.
 
+### `swarmvault graph share [--post]`
+
+Print a shareable summary of the compiled graph.
+
+- default output is the same markdown shape written to `wiki/graph/share-card.md`
+- `--post` prints only the concise social-post text
+- `--json` emits the structured share artifact for automation
+- useful immediately after `swarmvault scan`, `swarmvault demo`, or a normal compile
+
 ### `swarmvault graph blast <target> [--depth <n>]`
 
 Trace the reverse-import blast radius of changing a file or module.

package/dist/index.js

@@ -3,6 +3,7 @@
 // src/index.ts
 import { readFileSync } from "fs";
 import { readFile as readFile2 } from "fs/promises";
+import path2 from "path";
 import process2 from "process";
 import { createInterface } from "readline/promises";
 import {
@@ -14,10 +15,12 @@ import {
   autoCommitWikiChanges,
   benchmarkVault,
   blastRadiusVault,
+  buildGraphShareArtifact,
   compileVault,
   consolidateVault,
   createSupersessionEdge,
   deleteManagedSource,
+  downloadWhisperModel,
   explainGraphVault,
   exploreVault,
   exportGraphFormat,
@@ -52,9 +55,12 @@ import {
   queryGraphVault,
   queryVault,
   readApproval,
+  readGraphReport,
+  registerLocalWhisperProvider,
   rejectApproval,
   reloadManagedSources,
   removeWatchedRoot,
+  renderGraphShareMarkdown,
   resumeSourceSession,
   reviewManagedSource,
   reviewSourceScope,
@@ -65,6 +71,7 @@ import {
   serveSchedules,
   startGraphServer,
   startMcpServer,
+  summarizeLocalWhisperSetup,
   uninstallGitHooks,
   watchVault
 } from "@swarmvaultai/engine";
@@ -284,9 +291,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 : "1.0.1";
+    return typeof packageJson.version === "string" && packageJson.version.trim() ? packageJson.version : "1.2.0";
   } catch {
-    return "1.0.1";
+    return "1.2.0";
   }
 }
 function parsePositiveInt(value, fallback) {
@@ -968,6 +975,22 @@ graph.command("export").description(
     }
   }
 );
+graph.command("share").description("Print a shareable summary of the compiled graph.").option("--post", "Print only the short social post text", false).action(async (options) => {
+  const { paths } = await loadVaultConfig(process2.cwd());
+  const raw = await readFile2(paths.graphPath, "utf-8");
+  const graph2 = JSON.parse(raw);
+  const report = await readGraphReport(process2.cwd());
+  const artifact = buildGraphShareArtifact({
+    graph: graph2,
+    report,
+    vaultName: path2.basename(paths.rootDir)
+  });
+  if (isJson()) {
+    emitJson(artifact);
+    return;
+  }
+  log(options.post ? artifact.shortPost : renderGraphShareMarkdown(artifact));
+});
 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) => {
   const budget = options.budget ? parsePositiveInt(options.budget, 0) || void 0 : void 0;
   const result = await queryGraphVault(process2.cwd(), question, {
@@ -1141,6 +1164,77 @@ candidate.command("preview-scores").description("Show promotion scores for stage
     log(`${verdict} ${decision.pageId} score=${decision.score.toFixed(2)} ${decision.reasons.join("; ")}`);
   }
 });
+var provider = program.command("provider").description("Configure provider adapters.");
+provider.command("setup").description("Interactive setup for a provider (currently: local-whisper). Checks for required binaries and downloads models.").option("--local-whisper", "Set up the local Whisper (whisper.cpp) provider", false).option("--model <model>", "Whisper model to install (e.g. tiny.en, base.en, small.en)", "base.en").option("--apply", "Skip confirmation prompts and download/install automatically", false).option("--set-audio-provider", "Force tasks.audioProvider to local-whisper even if another provider is already configured", false).action(async (options) => {
+  if (!options.localWhisper) {
+    throw new Error("Specify a provider to set up (currently: --local-whisper).");
+  }
+  const modelName = (options.model ?? "base.en").trim();
+  if (!modelName) {
+    throw new Error("Model name cannot be empty.");
+  }
+  const status = await summarizeLocalWhisperSetup({ modelName });
+  if (isJson()) {
+    emitJson({ ...status, apply: Boolean(options.apply), configWrite: null });
+    return;
+  }
+  log(`whisper.cpp binary: ${status.binary.found ? status.binary.path : "NOT FOUND"}`);
+  if (!status.binary.found) {
+    log(status.binary.installHint);
+    log("Re-run once whisper.cpp is on $PATH.");
+    process2.exitCode = 1;
+    return;
+  }
+  log(`Model "${modelName}": ${status.model.exists ? status.model.expectedPath : "missing"}`);
+  if (!status.model.exists) {
+    const sizeHint = status.model.approximateSize ? ` (~${status.model.approximateSize})` : "";
+    log(`Download plan: ${status.model.downloadUrl}${sizeHint} -> ${status.model.expectedPath}`);
+    const proceed = options.apply === true || await confirmInteractive(`Download ggml-${modelName}.bin now?`);
+    if (!proceed) {
+      log("Skipped download. Run with --apply (or confirm y) to download.");
+      process2.exitCode = 1;
+      return;
+    }
+    const downloaded = await downloadWhisperModel({
+      modelName,
+      onProgress: (progress) => {
+        if (progress.totalBytes) {
+          const percent = Math.floor(progress.downloadedBytes / progress.totalBytes * 100);
+          process2.stderr.write(`\r[swarmvault] downloading ggml-${modelName}.bin: ${percent}%`);
+        }
+      }
+    });
+    process2.stderr.write("\n");
+    log(`Downloaded ${downloaded.bytes} bytes to ${downloaded.path}.`);
+  }
+  const registration = await registerLocalWhisperProvider({
+    rootDir: process2.cwd(),
+    model: modelName,
+    setAsAudioProvider: options.setAudioProvider ? true : void 0
+  });
+  if (registration.providerWasAdded) {
+    log(`Registered provider "local-whisper" in ${registration.configPath}.`);
+  } else if (registration.providerWasUpdated) {
+    log(`Updated existing "local-whisper" provider entry in ${registration.configPath}.`);
+  } else {
+    log(`Provider "local-whisper" already configured in ${registration.configPath}.`);
+  }
+  if (registration.audioProviderSet) {
+    log(`Set tasks.audioProvider = "local-whisper".`);
+  } else if (registration.previousAudioProvider && registration.previousAudioProvider !== "local-whisper") {
+    log(`Left tasks.audioProvider = "${registration.previousAudioProvider}" untouched (use --set-audio-provider to override).`);
+  }
+});
+async function confirmInteractive(message) {
+  if (!process2.stdin.isTTY) return false;
+  const rl = createInterface({ input: process2.stdin, output: process2.stderr });
+  try {
+    const answer = (await rl.question(`${message} [y/N] `)).trim().toLowerCase();
+    return answer === "y" || answer === "yes";
+  } finally {
+    rl.close();
+  }
+}
 var watch = program.command("watch").description("Watch the inbox directory and optionally tracked repos, or run one refresh cycle immediately.").option("--lint", "Run lint after each compile cycle", false).option("--repo", "Also refresh tracked repo sources and watch their repo roots", false).option("--once", "Run one import/refresh cycle immediately instead of starting a watcher", false).option("--code-only", "Only re-extract code sources (AST-only, no LLM re-analysis)", false).option("--debounce <ms>", "Debounce window in milliseconds", "900").option("--root <path>", "Watch this repo root instead of config/auto-discovery (repeat for multiple)", collectRepeated, []).action(async (options) => {
   const debounceMs = parsePositiveInt(options.debounce, 900);
   const overrideRoots = options.root && options.root.length > 0 ? options.root : void 0;
@@ -1357,15 +1451,15 @@ program.command("install").description("Install SwarmVault instructions for an a
 program.command("demo").description("Try SwarmVault with a bundled sample vault \u2014 zero config, zero API keys.").option("--port <port>", "Port for the graph viewer").option("--no-serve", "Skip launching the graph viewer after compile").action(async (options) => {
   const { mkdtemp, writeFile: writeFile2, mkdir: mkdir2 } = await import("fs/promises");
   const { tmpdir } = await import("os");
-  const path2 = await import("path");
-  const demoDir = await mkdtemp(path2.join(tmpdir(), "swarmvault-demo-"));
+  const path3 = await import("path");
+  const demoDir = await mkdtemp(path3.join(tmpdir(), "swarmvault-demo-"));
   if (!isJson()) {
     log(`Creating demo vault in ${demoDir}`);
   }
-  const rawDir = path2.join(demoDir, "raw", "sources");
+  const rawDir = path3.join(demoDir, "raw", "sources");
   await mkdir2(rawDir, { recursive: true });
   await writeFile2(
-    path2.join(rawDir, "llm-wiki-pattern.md"),
+    path3.join(rawDir, "llm-wiki-pattern.md"),
     [
       "# The LLM Wiki Pattern",
       "",
@@ -1394,7 +1488,7 @@ program.command("demo").description("Try SwarmVault with a bundled sample vault
     ].join("\n")
   );
   await writeFile2(
-    path2.join(rawDir, "knowledge-graphs.md"),
+    path3.join(rawDir, "knowledge-graphs.md"),
     [
       "# Knowledge Graphs for AI",
       "",
@@ -1427,7 +1521,7 @@ program.command("demo").description("Try SwarmVault with a bundled sample vault
     ].join("\n")
   );
   await writeFile2(
-    path2.join(rawDir, "local-first-tools.md"),
+    path3.join(rawDir, "local-first-tools.md"),
     [
       "# Local-First AI Tools",
       "",
@@ -1457,6 +1551,7 @@ program.command("demo").description("Try SwarmVault with a bundled sample vault
   await ingestDirectory(demoDir, rawDir, {});
   await compileVault(demoDir, {});
   const { paths } = await loadVaultConfig(demoDir);
+  const shareCardPath = path3.join(demoDir, "wiki", "graph", "share-card.md");
   let graphStats = "";
   try {
     const raw = await readFile2(paths.graphPath, "utf-8");
@@ -1474,17 +1569,19 @@ program.command("demo").description("Try SwarmVault with a bundled sample vault
     log("  3. Generated wiki pages with cross-references and a graph report");
     log("");
     log(`Vault location: ${demoDir}`);
+    log(`Share card: ${shareCardPath}`);
   }
   if (options.serve !== false) {
     const port = options.port ? parsePositiveInt(options.port, 0) || void 0 : void 0;
     const server = await startGraphServer(demoDir, port, { full: false });
     if (isJson()) {
-      emitJson({ demoDir, graphStats: graphStats.trim(), port: server.port, url: `http://localhost:${server.port}` });
+      emitJson({ demoDir, graphStats: graphStats.trim(), shareCardPath, port: server.port, url: `http://localhost:${server.port}` });
     } else {
       log(`Graph viewer running at http://localhost:${server.port}`);
       log("");
       log("Try next:");
       log(`  cd ${demoDir}`);
+      log("  swarmvault graph share --post");
       log('  swarmvault query "How does contradiction detection work?"');
       log("  swarmvault lint");
     }
@@ -1496,11 +1593,12 @@ program.command("demo").description("Try SwarmVault with a bundled sample vault
       process2.exit(0);
     });
   } else if (isJson()) {
-    emitJson({ demoDir, graphStats: graphStats.trim() });
+    emitJson({ demoDir, graphStats: graphStats.trim(), shareCardPath });
   } else {
     log("");
     log("Try next:");
     log(`  cd ${demoDir}`);
+    log("  swarmvault graph share --post");
     log("  swarmvault graph serve");
     log('  swarmvault query "How does contradiction detection work?"');
   }
@@ -1628,14 +1726,17 @@ program.command("scan").description("Quick-start: initialize, ingest, compile, a
     log(`Ingested ${result.imported.length} file(s).`);
   }
   const compiled = await compileVault(rootDir, {});
+  const shareCardPath = path2.join(rootDir, "wiki", "graph", "share-card.md");
   if (!isJson()) {
     log(`Compiled ${compiled.sourceCount} source(s), ${compiled.pageCount} page(s).`);
+    log(`Share card: ${shareCardPath}`);
+    log("Post text: swarmvault graph share --post");
   }
   if (options.serve !== false) {
     const port = options.port ? parsePositiveInt(options.port, 0) || void 0 : void 0;
     const server = await startGraphServer(rootDir, port, { full: false });
     if (isJson()) {
-      emitJson({ ...result, compiled, port: server.port, url: `http://localhost:${server.port}` });
+      emitJson({ ...result, compiled, shareCardPath, port: server.port, url: `http://localhost:${server.port}` });
     } else {
       log(`Graph viewer running at http://localhost:${server.port}`);
     }
@@ -1647,7 +1748,7 @@ program.command("scan").description("Quick-start: initialize, ingest, compile, a
       process2.exit(0);
     });
   } else if (isJson()) {
-    emitJson({ ...result, compiled });
+    emitJson({ ...result, compiled, shareCardPath });
   }
 });
 function enableStructuredJsonOnSubcommands(command) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarmvaultai/cli",
-  "version": "1.0.1",
+  "version": "1.2.0",
   "description": "Global CLI for SwarmVault.",
   "type": "module",
   "main": "dist/index.js",
@@ -37,19 +37,18 @@
   "engines": {
     "node": ">=24.0.0"
   },
-  "scripts": {
-    "build": "tsup src/index.ts --format esm --dts",
-    "test": "vitest run",
-    "typecheck": "tsc --noEmit",
-    "prepublishOnly": "node ../../scripts/check-release-sync.mjs && node ../../scripts/check-published-manifests.mjs"
-  },
   "dependencies": {
-    "@swarmvaultai/engine": "1.0.1",
+    "@swarmvaultai/engine": "1.2.0",
     "commander": "^14.0.1"
   },
   "devDependencies": {
     "@types/node": "^24.6.0",
     "tsup": "^8.5.0",
     "vitest": "^3.2.4"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
   }
-}
+}