@swarmvaultai/cli 0.1.28 → 0.1.30

package/README.md

@@ -2,7 +2,7 @@
 
 `@swarmvaultai/cli` is the global command-line entry point for SwarmVault.
 
-It gives you the `swarmvault` command for building a local-first knowledge vault from files, URLs, browser clips, saved query outputs, and guided exploration runs.
+It gives you the `swarmvault` command for building a local-first knowledge vault from files, DOCX documents, URLs, browser clips, saved query outputs, and guided exploration runs.
 
 ## Install
 
@@ -41,6 +41,7 @@ swarmvault hook install
 swarmvault graph serve
 swarmvault graph export --html ./exports/graph.html
 swarmvault graph export --cypher ./exports/graph.cypher
+swarmvault graph push neo4j --dry-run
 ```
 
 ## Commands
@@ -70,6 +71,7 @@ Ingest a local file path, directory path, or URL into immutable source storage a
 - directory ingest respects `.gitignore` unless you pass `--no-gitignore`
 - repo-aware directory ingest records `repoRelativePath` and later compile writes `state/code-index.json`
 - URL ingest still localizes remote image references by default
+- local file ingest supports markdown, text, HTML, PDF, DOCX, images, and code
 - code-aware directory ingest currently covers JavaScript, TypeScript, Python, Go, Rust, Java, C#, C, C++, PHP, Ruby, and PowerShell
 
 Useful flags:
@@ -101,7 +103,7 @@ Capture supported URLs through a normalized markdown layer before ingesting them
 
 ### `swarmvault inbox import [dir]`
 
-Import supported files from the configured inbox directory. This is meant for browser-clipper style markdown bundles and other capture workflows. Local image and asset references are preserved and copied into canonical storage under `raw/assets/`.
+Import supported files from the configured inbox directory. This is meant for browser-clipper style markdown bundles, HTML clip bundles, and other capture workflows. Local image and asset references are preserved and copied into canonical storage under `raw/assets/`.
 
 ### `swarmvault compile [--approve]`
 
@@ -255,6 +257,29 @@ Export the current graph as one of four formats:
 - `--graphml` for graph-tool interoperability
 - `--cypher` for Neo4j-style import scripts
 
+### `swarmvault graph push neo4j`
+
+Push the compiled graph directly into Neo4j over Bolt/Aura instead of writing an intermediate file.
+
+Useful flags:
+
+- `--uri <bolt-uri>`
+- `--username <user>`
+- `--password-env <env-var>`
+- `--database <name>`
+- `--vault-id <id>`
+- `--include-third-party`
+- `--include-resources`
+- `--include-generated`
+- `--dry-run`
+
+Defaults:
+
+- reads `graphSinks.neo4j` from `swarmvault.config.json` when present
+- includes only `first_party` graph material unless you opt into more source classes
+- namespaces every remote record by `vaultId` so multiple vaults can safely share one Neo4j database
+- upserts current graph records and does not prune stale remote data yet
+
 ### `swarmvault install --agent <codex|claude|cursor|goose|pi|gemini|opencode|aider|copilot>`
 
 Install agent-specific rules into the current project so an agent understands the SwarmVault workspace contract and workflow.
@@ -277,6 +302,13 @@ Agent target mapping:
 - `copilot` writes `.github/copilot-instructions.md` plus `AGENTS.md`
 - `cursor` writes `.cursor/rules/swarmvault.mdc`
 
+Hook semantics:
+
+- `claude --hook` writes `.claude/settings.json` plus `.claude/hooks/swarmvault-graph-first.js` and adds model-visible advisory context through structured hook JSON
+- `gemini --hook` writes `.gemini/settings.json` plus `.gemini/hooks/swarmvault-graph-first.js` and stays advisory/model-visible
+- `opencode --hook` writes `.opencode/plugins/swarmvault-graph-first.js` and stays advisory/log-only
+- `copilot --hook` writes `.github/hooks/swarmvault-graph-first.json` plus `.github/hooks/swarmvault-graph-first.js` and remains decision-based rather than advisory
+
 `aider` is intentionally file/config-based in this release rather than hook-based.
 
 ## Provider Configuration

package/dist/index.js

@@ -29,6 +29,7 @@ import {
   loadVaultConfig,
   pathGraphVault,
   promoteCandidate,
+  pushGraphNeo4j,
   queryGraphVault,
   queryVault,
   readApproval,
@@ -216,11 +217,16 @@ program.name("swarmvault").description("SwarmVault is a local-first LLM wiki com
 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.1.28";
+    return typeof packageJson.version === "string" && packageJson.version.trim() ? packageJson.version : "0.1.30";
   } catch {
-    return "0.1.28";
+    return "0.1.30";
   }
 }
+function parsePositiveInt(value, fallback) {
+  if (value === void 0) return fallback;
+  const parsed = Number.parseInt(value, 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
 function isJson() {
   return program.opts().json === true;
 }
@@ -273,8 +279,8 @@ program.command("init").description("Initialize a SwarmVault workspace in the cu
 });
 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(
   async (input, options) => {
-    const maxAssetSize = typeof options.maxAssetSize === "string" && options.maxAssetSize.trim() ? Number.parseInt(options.maxAssetSize, 10) : void 0;
-    const maxFiles = typeof options.maxFiles === "string" && options.maxFiles.trim() ? Number.parseInt(options.maxFiles, 10) : void 0;
+    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 = [
       "first_party",
       ...options.includeThirdParty ? ["third_party"] : [],
@@ -283,11 +289,11 @@ program.command("ingest").description("Ingest a local file path, directory path,
     ];
     const commonOptions = {
       includeAssets: options.includeAssets,
-      maxAssetSize: Number.isFinite(maxAssetSize) ? maxAssetSize : void 0,
+      maxAssetSize,
       repoRoot: options.repoRoot,
       include: options.include,
       exclude: options.exclude,
-      maxFiles: Number.isFinite(maxFiles) ? maxFiles : void 0,
+      maxFiles,
       gitignore: options.gitignore,
       extractClasses
     };
@@ -366,10 +372,10 @@ program.command("query").description("Query the compiled SwarmVault wiki.").argu
 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")
 ).action(async (question, options) => {
-  const stepCount = Number.parseInt(options.steps ?? "3", 10);
+  const stepCount = parsePositiveInt(options.steps, 3);
   const result = await exploreVault(process2.cwd(), {
     question,
-    steps: Number.isFinite(stepCount) ? stepCount : 3,
+    steps: stepCount,
     format: options.format
   });
   if (isJson()) {
@@ -409,8 +415,45 @@ program.command("lint").description("Run anti-drift and wiki-health checks.").op
   }
 });
 var graph = program.command("graph").description("Graph-related commands.");
+var graphPush = graph.command("push").description("Push the compiled graph into external sinks.");
+graphPush.command("neo4j").description("Push the compiled graph directly into Neo4j over Bolt/Aura.").option("--uri <bolt-uri>", "Neo4j Bolt or Aura URI").option("--username <user>", "Neo4j username").option("--password-env <env-var>", "Environment variable containing the Neo4j password").option("--database <name>", "Neo4j database name").option("--vault-id <id>", "Stable vault identifier used for shared-database namespacing").option("--batch-size <n>", "Maximum rows to write per Neo4j transaction batch").option("--include-third-party", "Also push third-party repo material", false).option("--include-resources", "Also push resource-like content", false).option("--include-generated", "Also push generated output", false).option("--dry-run", "Show what would be pushed without writing to Neo4j", false).action(
+  async (options) => {
+    const batchSize = typeof options.batchSize === "string" && options.batchSize.trim() ? parsePositiveInt(options.batchSize, 0) || void 0 : void 0;
+    const includeClasses = [
+      "first_party",
+      ...options.includeThirdParty ? ["third_party"] : [],
+      ...options.includeResources ? ["resource"] : [],
+      ...options.includeGenerated ? ["generated"] : []
+    ];
+    const result = await pushGraphNeo4j(process2.cwd(), {
+      uri: options.uri,
+      username: options.username,
+      passwordEnv: options.passwordEnv,
+      database: options.database,
+      vaultId: options.vaultId,
+      batchSize,
+      includeClasses,
+      dryRun: options.dryRun ?? false
+    });
+    if (isJson()) {
+      emitJson(result);
+    } else {
+      log(
+        `${result.dryRun ? "Planned" : "Pushed"} ${result.counts.nodes} nodes, ${result.counts.relationships} relationships, ${result.counts.hyperedges} hyperedges, and ${result.counts.groupMembers} group-member links to ${result.uri}/${result.database} as ${result.vaultId}.`
+      );
+      if (result.skipped.nodes || result.skipped.relationships || result.skipped.hyperedges) {
+        log(
+          `Skipped ${result.skipped.nodes} node(s), ${result.skipped.relationships} relationship(s), and ${result.skipped.hyperedges} hyperedge(s) outside the selected source classes.`
+        );
+      }
+      for (const warning of result.warnings) {
+        log(`Warning: ${warning}`);
+      }
+    }
+  }
+);
 graph.command("serve").description("Serve the local graph viewer.").option("--port <port>", "Port override").action(async (options) => {
-  const port = options.port ? Number.parseInt(options.port, 10) : void 0;
+  const port = options.port ? parsePositiveInt(options.port, 0) || void 0 : void 0;
   const server = await startGraphServer(process2.cwd(), port);
   if (isJson()) {
     emitJson({ port: server.port, url: `http://localhost:${server.port}` });
@@ -418,7 +461,10 @@ graph.command("serve").description("Serve the local graph viewer.").option("--po
     log(`Graph viewer running at http://localhost:${server.port}`);
   }
   process2.on("SIGINT", async () => {
-    await server.close();
+    try {
+      await server.close();
+    } catch {
+    }
     process2.exit(0);
   });
 });
@@ -441,10 +487,10 @@ graph.command("export").description("Export the graph as HTML, SVG, GraphML, or
   }
 });
 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 ? Number.parseInt(options.budget, 10) : void 0;
+  const budget = options.budget ? parsePositiveInt(options.budget, 0) || void 0 : void 0;
   const result = await queryGraphVault(process2.cwd(), question, {
     traversal: options.dfs ? "dfs" : "bfs",
-    budget: Number.isFinite(budget) ? budget : void 0
+    budget
   });
   if (isJson()) {
     emitJson(result);
@@ -469,8 +515,8 @@ graph.command("explain").description("Explain a graph node, its page, community,
   log(result.summary);
 });
 graph.command("god-nodes").description("List the highest-connectivity non-source graph nodes.").option("--limit <n>", "Maximum number of nodes to return", "10").action(async (options) => {
-  const limit = Number.parseInt(options.limit ?? "10", 10);
-  const result = await listGodNodes(process2.cwd(), Number.isFinite(limit) ? limit : 10);
+  const limit = parsePositiveInt(options.limit, 10);
+  const result = await listGodNodes(process2.cwd(), limit);
   if (isJson()) {
     emitJson(result);
     return;
@@ -555,12 +601,12 @@ candidate.command("archive").description("Archive a candidate by removing it fro
   }
 });
 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("--debounce <ms>", "Debounce window in milliseconds", "900").action(async (options) => {
-  const debounceMs = Number.parseInt(options.debounce ?? "900", 10);
+  const debounceMs = parsePositiveInt(options.debounce, 900);
   if (options.once) {
     const result = await runWatchCycle(process2.cwd(), {
       lint: options.lint ?? false,
       repo: options.repo ?? false,
-      debounceMs: Number.isFinite(debounceMs) ? debounceMs : 900
+      debounceMs
     });
     if (isJson()) {
       emitJson(result);
@@ -575,7 +621,7 @@ var watch = program.command("watch").description("Watch the inbox directory and
   const controller = await watchVault(process2.cwd(), {
     lint: options.lint ?? false,
     repo: options.repo ?? false,
-    debounceMs: Number.isFinite(debounceMs) ? debounceMs : 900
+    debounceMs
   });
   if (isJson()) {
     emitJson({ status: "watching", inboxDir: paths.inboxDir, repo: options.repo ?? false });
@@ -583,23 +629,14 @@ var watch = program.command("watch").description("Watch the inbox directory and
     log(`Watching inbox${options.repo ? " and tracked repos" : ""} for changes. Press Ctrl+C to stop.`);
   }
   process2.on("SIGINT", async () => {
-    await controller.close();
+    try {
+      await controller.close();
+    } catch {
+    }
     process2.exit(0);
   });
 });
-watch.command("status").description("Show the latest watch run plus pending semantic refresh entries.").action(async () => {
-  const result = await getWatchStatus(process2.cwd());
-  if (isJson()) {
-    emitJson(result);
-    return;
-  }
-  log(`Watched repo roots: ${result.watchedRepoRoots.length}`);
-  log(`Pending semantic refresh: ${result.pendingSemanticRefresh.length}`);
-  for (const entry of result.pendingSemanticRefresh.slice(0, 8)) {
-    log(`- ${entry.changeType} ${entry.path}`);
-  }
-});
-program.command("watch-status").description("Show the latest watch run plus pending semantic refresh entries.").action(async () => {
+async function showWatchStatus() {
   const result = await getWatchStatus(process2.cwd());
   if (isJson()) {
     emitJson(result);
@@ -610,7 +647,9 @@ program.command("watch-status").description("Show the latest watch run plus pend
   for (const entry of result.pendingSemanticRefresh.slice(0, 8)) {
     log(`- ${entry.changeType} ${entry.path}`);
   }
-});
+}
+watch.command("status").description("Show the latest watch run plus pending semantic refresh entries.").action(showWatchStatus);
+program.command("watch-status").description("Show the latest watch run plus pending semantic refresh entries.").action(showWatchStatus);
 var hook = program.command("hook").description("Install local git hooks that keep tracked repos and the vault in sync.");
 hook.command("install").description("Install post-commit and post-checkout hooks for the nearest git repository.").action(async () => {
   const status = await installGitHooks(process2.cwd());
@@ -670,15 +709,18 @@ schedule.command("run").description("Run one configured schedule job immediately
   );
 });
 schedule.command("serve").description("Run the local schedule loop.").option("--poll <ms>", "Polling interval in milliseconds", "30000").action(async (options) => {
-  const pollMs = Number.parseInt(options.poll ?? "30000", 10);
-  const controller = await serveSchedules(process2.cwd(), Number.isFinite(pollMs) ? pollMs : 3e4);
+  const pollMs = parsePositiveInt(options.poll, 3e4);
+  const controller = await serveSchedules(process2.cwd(), pollMs);
   if (isJson()) {
-    emitJson({ status: "serving", pollMs: Number.isFinite(pollMs) ? pollMs : 3e4 });
+    emitJson({ status: "serving", pollMs });
   } else {
     log("Serving schedules. Press Ctrl+C to stop.");
   }
   process2.on("SIGINT", async () => {
-    await controller.close();
+    try {
+      await controller.close();
+    } catch {
+    }
     process2.exit(0);
   });
 });
@@ -689,7 +731,10 @@ program.command("mcp").description("Run SwarmVault as a local MCP server over st
   }
   const controller = await startMcpServer(process2.cwd());
   process2.on("SIGINT", async () => {
-    await controller.close();
+    try {
+      await controller.close();
+    } catch {
+    }
     process2.exit(0);
   });
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarmvaultai/cli",
-  "version": "0.1.28",
+  "version": "0.1.30",
   "description": "Global CLI for SwarmVault.",
   "type": "module",
   "main": "dist/index.js",
@@ -43,7 +43,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@swarmvaultai/engine": "0.1.28",
+    "@swarmvaultai/engine": "0.1.30",
     "commander": "^14.0.1"
   },
   "devDependencies": {