@swarmvaultai/cli 0.1.27 → 0.1.29

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
 
@@ -70,6 +70,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 +102,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,16 +256,37 @@ Export the current graph as one of four formats:
 - `--graphml` for graph-tool interoperability
 - `--cypher` for Neo4j-style import scripts
 
-### `swarmvault install --agent <codex|claude|cursor|goose|pi|gemini|opencode>`
+### `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.
 
-For Claude Code, you can also install the recommended graph-first pre-search hook:
+Hook-capable installs:
 
 ```bash
 swarmvault install --agent claude --hook
+swarmvault install --agent gemini --hook
+swarmvault install --agent opencode --hook
+swarmvault install --agent copilot --hook
 ```
 
+Agent target mapping:
+
+- `codex`, `goose`, `pi`, and `opencode` share `AGENTS.md`
+- `claude` writes `CLAUDE.md`
+- `gemini` writes `GEMINI.md`
+- `aider` writes `CONVENTIONS.md` and merges `.aider.conf.yml`
+- `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
 
 SwarmVault defaults to a local `heuristic` provider so the CLI works without API keys, but real vaults will usually point at an actual model provider.

package/dist/index.js

@@ -216,11 +216,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.27";
+    return typeof packageJson.version === "string" && packageJson.version.trim() ? packageJson.version : "0.1.29";
   } catch {
-    return "0.1.27";
+    return "0.1.29";
   }
 }
+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 +278,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 +288,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 +371,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()) {
@@ -410,7 +415,7 @@ program.command("lint").description("Run anti-drift and wiki-health checks.").op
 });
 var graph = program.command("graph").description("Graph-related commands.");
 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 +423,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 +449,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 +477,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 +563,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 +583,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,11 +591,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 () => {
+async function showWatchStatus() {
   const result = await getWatchStatus(process2.cwd());
   if (isJson()) {
     emitJson(result);
@@ -598,19 +609,9 @@ watch.command("status").description("Show the latest watch run plus pending sema
   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 () => {
-  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}`);
-  }
-});
+}
+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 +671,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,21 +693,33 @@ 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);
   });
 });
-program.command("install").description("Install SwarmVault instructions for an agent in the current project.").requiredOption("--agent <agent>", "codex, claude, cursor, goose, pi, gemini, or opencode").option("--hook", "Also install the recommended Claude pre-search hook when agent=claude", false).action(async (options) => {
-  if (options.hook && options.agent !== "claude") {
-    throw new Error("--hook is only supported for --agent claude");
-  }
-  const target = await installAgent(process2.cwd(), options.agent, { claudeHook: options.hook ?? false });
-  if (isJson()) {
-    emitJson({ agent: options.agent, target, hook: options.hook ?? false });
-  } else {
-    log(`Installed rules into ${target}`);
+program.command("install").description("Install SwarmVault instructions for an agent in the current project.").requiredOption("--agent <agent>", "codex, claude, cursor, goose, pi, gemini, opencode, aider, or copilot").option("--hook", "Also install hook/plugin guidance when the target agent supports it", false).action(
+  async (options) => {
+    const hookCapableAgents = /* @__PURE__ */ new Set(["claude", "opencode", "gemini", "copilot"]);
+    if (options.hook && !hookCapableAgents.has(options.agent)) {
+      throw new Error("--hook is only supported for --agent claude, opencode, gemini, or copilot");
+    }
+    const result = await installAgent(process2.cwd(), options.agent, { hook: options.hook ?? false });
+    if (isJson()) {
+      emitJson({ ...result, hook: options.hook ?? false });
+    } else {
+      log(`Installed rules into ${result.target}`);
+      if (result.targets.length > 1) {
+        log(`Also wrote: ${result.targets.filter((entry) => entry !== result.target).join(", ")}`);
+      }
+      for (const warning of result.warnings ?? []) {
+        emitNotice(warning);
+      }
+    }
   }
-});
+);
 program.parseAsync(process2.argv).catch((error) => {
   const message = error instanceof Error ? error.message : String(error);
   if (isJson()) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarmvaultai/cli",
-  "version": "0.1.27",
+  "version": "0.1.29",
   "description": "Global CLI for SwarmVault.",
   "type": "module",
   "main": "dist/index.js",
@@ -37,18 +37,18 @@
   "engines": {
     "node": ">=24.0.0"
   },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
   "dependencies": {
-    "@swarmvaultai/engine": "0.1.27",
+    "@swarmvaultai/engine": "0.1.29",
     "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"
   }
-}
+}

package/LICENSE

@@ -1,21 +0,0 @@
-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.