@swarmvaultai/cli 0.1.25 → 0.1.27

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

@@ -78,10 +78,15 @@ Useful flags:
 - `--include <glob...>`
 - `--exclude <glob...>`
 - `--max-files <n>`
+- `--include-third-party`
+- `--include-resources`
+- `--include-generated`
 - `--no-gitignore`
 - `--no-include-assets`
 - `--max-asset-size <bytes>`
 
+Repo ingest defaults to `first_party` material. The extra `--include-*` flags opt dependency trees, resource bundles, and generated output back in when you actually want them in the vault.
+
 ### `swarmvault add <url>`
 
 Capture supported URLs through a normalized markdown layer before ingesting them into the vault.

package/dist/index.js

@@ -2,7 +2,7 @@
 
 // src/index.ts
 import { readFileSync } from "fs";
-import process from "process";
+import process2 from "process";
 import {
   acceptApproval,
   addInput,
@@ -42,45 +42,245 @@ import {
   watchVault
 } from "@swarmvaultai/engine";
 import { Command, Option } from "commander";
+
+// src/notices.ts
+import { spawn } from "child_process";
+import { mkdir, readFile, writeFile } from "fs/promises";
+import os from "os";
+import path from "path";
+var NOTICE_CACHE_TTL_MS = 24 * 60 * 60 * 1e3;
+var NOTICE_TIMEOUT_MS = 2e3;
+var STAR_URL = "https://github.com/swarmclawai/swarmvault";
+var NPM_PACKAGE = "@swarmvaultai/cli";
+var SUPPRESSED_COMMANDS = /* @__PURE__ */ new Set(["graph serve", "mcp", "schedule serve", "watch"]);
+function resolveCliStatePath(env = process.env) {
+  const override = env.SWARMVAULT_CLI_STATE_PATH?.trim();
+  if (override) {
+    return path.resolve(override);
+  }
+  const homeDir = os.homedir();
+  if (!homeDir) {
+    return null;
+  }
+  return path.join(homeDir, ".swarmvault", "cli-state.json");
+}
+function shouldEmitCliNotices(options) {
+  const env = options.env ?? process.env;
+  if (options.json) {
+    return false;
+  }
+  if (env.SWARMVAULT_NO_NOTICES === "1") {
+    return false;
+  }
+  if (Boolean(env.CI) && env.CI !== "0") {
+    return false;
+  }
+  if (!(options.stdoutIsTTY ?? process.stdout.isTTY) || !(options.stderrIsTTY ?? process.stderr.isTTY)) {
+    return false;
+  }
+  const commandKey = options.commandPath.join(" ").trim();
+  return !SUPPRESSED_COMMANDS.has(commandKey);
+}
+async function collectCliNotices(options) {
+  if (!shouldEmitCliNotices(options)) {
+    return [];
+  }
+  const env = options.env ?? process.env;
+  const statePath = options.statePath ?? resolveCliStatePath(env);
+  if (!statePath) {
+    return [];
+  }
+  const state = await readNoticeState(statePath);
+  const nextState = { ...state };
+  const notices = [];
+  const now = options.now ?? /* @__PURE__ */ new Date();
+  const nowMs = now.getTime();
+  if (!state.starPromptShown) {
+    notices.push(`If SwarmVault is useful, star the repo: ${STAR_URL}`);
+    nextState.starPromptShown = true;
+  }
+  const lastCheckMs = state.lastUpdateCheckAt ? Date.parse(state.lastUpdateCheckAt) : Number.NaN;
+  const shouldCheckUpdates = !Number.isFinite(lastCheckMs) || nowMs - lastCheckMs >= NOTICE_CACHE_TTL_MS;
+  if (shouldCheckUpdates) {
+    const fetchLatestVersion = options.fetchLatestVersion ?? (() => fetchLatestCliVersion(env));
+    const latestVersion = await fetchLatestVersion().catch(() => null);
+    nextState.lastUpdateCheckAt = now.toISOString();
+    if (latestVersion) {
+      nextState.lastSeenLatestVersion = latestVersion;
+      if (isVersionNewer(latestVersion, options.currentVersion)) {
+        notices.unshift(
+          `Update available: ${latestVersion} (current ${options.currentVersion}). Upgrade with: npm install -g ${NPM_PACKAGE}@latest`
+        );
+      }
+    }
+  }
+  await writeNoticeState(statePath, nextState);
+  return notices;
+}
+async function readNoticeState(statePath) {
+  try {
+    const raw = await readFile(statePath, "utf8");
+    const parsed = JSON.parse(raw);
+    return typeof parsed === "object" && parsed ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+async function writeNoticeState(statePath, state) {
+  try {
+    await mkdir(path.dirname(statePath), { recursive: true });
+    await writeFile(statePath, `${JSON.stringify(state, null, 2)}
+`, "utf8");
+  } catch {
+  }
+}
+async function fetchLatestCliVersion(env) {
+  return await new Promise((resolve) => {
+    const child = spawn("npm", ["view", NPM_PACKAGE, "version", "--json"], {
+      env: {
+        ...process.env,
+        ...env,
+        npm_config_audit: "false",
+        npm_config_fund: "false",
+        npm_config_update_notifier: "false"
+      },
+      stdio: ["ignore", "pipe", "ignore"]
+    });
+    const chunks = [];
+    let settled = false;
+    const finish = (value) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      clearTimeout(timeoutId);
+      resolve(value);
+    };
+    child.stdout.on("data", (chunk) => {
+      chunks.push(chunk);
+    });
+    child.on("error", () => {
+      finish(null);
+    });
+    child.on("exit", (code) => {
+      if (code !== 0) {
+        finish(null);
+        return;
+      }
+      const raw = Buffer.concat(chunks).toString("utf8").trim();
+      if (!raw) {
+        finish(null);
+        return;
+      }
+      try {
+        const parsed = JSON.parse(raw);
+        finish(typeof parsed === "string" && parsed.trim() ? parsed.trim() : null);
+      } catch {
+        finish(raw.replace(/^"+|"+$/g, "").trim() || null);
+      }
+    });
+    const timeoutId = setTimeout(() => {
+      child.kill("SIGKILL");
+      finish(null);
+    }, NOTICE_TIMEOUT_MS);
+  });
+}
+function isVersionNewer(candidate2, current) {
+  return compareVersions(candidate2, current) > 0;
+}
+function compareVersions(left, right) {
+  const leftParts = normalizeVersion(left);
+  const rightParts = normalizeVersion(right);
+  const maxLength = Math.max(leftParts.length, rightParts.length);
+  for (let index = 0; index < maxLength; index += 1) {
+    const leftValue = leftParts[index] ?? 0;
+    const rightValue = rightParts[index] ?? 0;
+    if (leftValue !== rightValue) {
+      return leftValue - rightValue;
+    }
+  }
+  return 0;
+}
+function normalizeVersion(version) {
+  const match = version.trim().match(/^(\d+)(?:\.(\d+))?(?:\.(\d+))?/);
+  if (!match) {
+    return [0];
+  }
+  return match.slice(1).map((segment) => Number.parseInt(segment ?? "0", 10) || 0);
+}
+
+// src/index.ts
 var program = new Command();
 var CLI_VERSION = readCliVersion();
 program.name("swarmvault").description("SwarmVault is a local-first LLM wiki compiler with graph outputs and pluggable providers.").version(CLI_VERSION).option("--json", "Emit structured JSON output", false);
 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.25";
+    return typeof packageJson.version === "string" && packageJson.version.trim() ? packageJson.version : "0.1.27";
   } catch {
-    return "0.1.25";
+    return "0.1.27";
   }
 }
 function isJson() {
   return program.opts().json === true;
 }
 function emitJson(data) {
-  process.stdout.write(`${JSON.stringify(data)}
+  process2.stdout.write(`${JSON.stringify(data)}
 `);
 }
 function log(message) {
   if (isJson()) {
-    process.stderr.write(`${message}
+    process2.stderr.write(`${message}
 `);
   } else {
-    process.stdout.write(`${message}
+    process2.stdout.write(`${message}
 `);
   }
 }
+function emitNotice(message) {
+  process2.stderr.write(`[swarmvault] ${message}
+`);
+}
+function getCommandPath(command) {
+  const names = [];
+  let current = command;
+  while (current) {
+    const name = current.name();
+    if (name && name !== "swarmvault") {
+      names.unshift(name);
+    }
+    current = current.parent ?? null;
+  }
+  return names;
+}
+program.hook("postAction", async (_thisCommand, actionCommand) => {
+  const notices = await collectCliNotices({
+    commandPath: getCommandPath(actionCommand),
+    currentVersion: CLI_VERSION,
+    json: isJson()
+  });
+  for (const notice of notices) {
+    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(process.cwd(), { obsidian: options.obsidian ?? false });
+  await initVault(process2.cwd(), { obsidian: options.obsidian ?? false });
   if (isJson()) {
-    emitJson({ status: "initialized", rootDir: process.cwd(), obsidian: options.obsidian ?? false });
+    emitJson({ status: "initialized", rootDir: process2.cwd(), obsidian: options.obsidian ?? false });
   } 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("--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("--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 extractClasses = [
+      "first_party",
+      ...options.includeThirdParty ? ["third_party"] : [],
+      ...options.includeResources ? ["resource"] : [],
+      ...options.includeGenerated ? ["generated"] : []
+    ];
     const commonOptions = {
       includeAssets: options.includeAssets,
       maxAssetSize: Number.isFinite(maxAssetSize) ? maxAssetSize : void 0,
@@ -88,10 +288,11 @@ program.command("ingest").description("Ingest a local file path, directory path,
       include: options.include,
       exclude: options.exclude,
       maxFiles: Number.isFinite(maxFiles) ? maxFiles : void 0,
-      gitignore: options.gitignore
+      gitignore: options.gitignore,
+      extractClasses
     };
     const directoryResult = !/^https?:\/\//i.test(input) ? await import("fs/promises").then(
-      (fs) => fs.stat(input).then((stat) => stat.isDirectory() ? ingestDirectory(process.cwd(), input, commonOptions) : null).catch(() => null)
+      (fs) => fs.stat(input).then((stat) => stat.isDirectory() ? ingestDirectory(process2.cwd(), input, commonOptions) : null).catch(() => null)
     ) : null;
     if (directoryResult) {
       if (isJson()) {
@@ -103,7 +304,7 @@ program.command("ingest").description("Ingest a local file path, directory path,
       }
       return;
     }
-    const manifest = await ingestInput(process.cwd(), input, commonOptions);
+    const manifest = await ingestInput(process2.cwd(), input, commonOptions);
     if (isJson()) {
       emitJson(manifest);
     } else {
@@ -112,7 +313,7 @@ program.command("ingest").description("Ingest a local file path, directory path,
   }
 );
 program.command("add").description("Capture supported URLs into normalized markdown before ingesting them.").argument("<input>", "Supported URL or bare arXiv id").option("--author <name>", "Human author or curator for this capture").option("--contributor <name>", "Additional contributor metadata for this capture").action(async (input, options) => {
-  const result = await addInput(process.cwd(), input, {
+  const result = await addInput(process2.cwd(), input, {
     author: options.author,
     contributor: options.contributor
   });
@@ -124,7 +325,7 @@ program.command("add").description("Capture supported URLs into normalized markd
 });
 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(process.cwd(), dir);
+  const result = await importInbox(process2.cwd(), dir);
   if (isJson()) {
     emitJson(result);
   } else {
@@ -134,7 +335,7 @@ inbox.command("import").description("Import supported files from the configured
   }
 });
 program.command("compile").description("Compile manifests into wiki pages, graph JSON, and search index.").option("--approve", "Stage a review bundle without applying active page changes", false).action(async (options) => {
-  const result = await compileVault(process.cwd(), { approve: options.approve ?? false });
+  const result = await compileVault(process2.cwd(), { approve: options.approve ?? false });
   if (isJson()) {
     emitJson(result);
   } else {
@@ -148,7 +349,7 @@ program.command("compile").description("Compile manifests into wiki pages, graph
 program.command("query").description("Query the compiled SwarmVault wiki.").argument("<question>", "Question to ask SwarmVault").option("--no-save", "Do not persist the answer to wiki/outputs").addOption(
   new Option("--format <format>", "Output format").choices(["markdown", "report", "slides", "chart", "image"]).default("markdown")
 ).action(async (question, options) => {
-  const result = await queryVault(process.cwd(), {
+  const result = await queryVault(process2.cwd(), {
     question,
     save: options.save ?? true,
     format: options.format
@@ -166,7 +367,7 @@ program.command("explore").description("Run a save-first multi-step exploration
   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 result = await exploreVault(process.cwd(), {
+  const result = await exploreVault(process2.cwd(), {
     question,
     steps: Number.isFinite(stepCount) ? stepCount : 3,
     format: options.format
@@ -179,7 +380,7 @@ program.command("explore").description("Run a save-first multi-step exploration
   }
 });
 program.command("benchmark").description("Measure graph-guided context reduction against a naive full-corpus read.").option("--question <text...>", "Optional custom benchmark question(s)").action(async (options) => {
-  const result = await benchmarkVault(process.cwd(), {
+  const result = await benchmarkVault(process2.cwd(), {
     questions: options.question
   });
   if (isJson()) {
@@ -191,7 +392,7 @@ program.command("benchmark").description("Measure graph-guided context reduction
   }
 });
 program.command("lint").description("Run anti-drift and wiki-health checks.").option("--deep", "Run LLM-powered advisory lint", false).option("--web", "Augment deep lint with configured web search", false).action(async (options) => {
-  const findings = await lintVault(process.cwd(), {
+  const findings = await lintVault(process2.cwd(), {
     deep: options.deep ?? false,
     web: options.web ?? false
   });
@@ -210,15 +411,15 @@ 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 server = await startGraphServer(process.cwd(), port);
+  const server = await startGraphServer(process2.cwd(), port);
   if (isJson()) {
     emitJson({ port: server.port, url: `http://localhost:${server.port}` });
   } else {
     log(`Graph viewer running at http://localhost:${server.port}`);
   }
-  process.on("SIGINT", async () => {
+  process2.on("SIGINT", async () => {
     await server.close();
-    process.exit(0);
+    process2.exit(0);
   });
 });
 graph.command("export").description("Export the graph as HTML, SVG, GraphML, or Cypher.").option("--html <output>", "Output HTML file path").option("--svg <output>", "Output SVG file path").option("--graphml <output>", "Output GraphML file path").option("--cypher <output>", "Output Cypher file path").action(async (options) => {
@@ -232,7 +433,7 @@ graph.command("export").description("Export the graph as HTML, SVG, GraphML, or
     throw new Error("Pass exactly one of --html, --svg, --graphml, or --cypher.");
   }
   const target = targets[0];
-  const outputPath = target.format === "html" ? await exportGraphHtml(process.cwd(), target.outputPath) : (await exportGraphFormat(process.cwd(), target.format, target.outputPath)).outputPath;
+  const outputPath = target.format === "html" ? await exportGraphHtml(process2.cwd(), target.outputPath) : (await exportGraphFormat(process2.cwd(), target.format, target.outputPath)).outputPath;
   if (isJson()) {
     emitJson({ format: target.format, outputPath });
   } else {
@@ -241,7 +442,7 @@ 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 result = await queryGraphVault(process.cwd(), question, {
+  const result = await queryGraphVault(process2.cwd(), question, {
     traversal: options.dfs ? "dfs" : "bfs",
     budget: Number.isFinite(budget) ? budget : void 0
   });
@@ -252,7 +453,7 @@ graph.command("query").description("Traverse the compiled graph deterministicall
   log(result.summary);
 });
 graph.command("path").description("Find the shortest graph path between two nodes or pages.").argument("<from>", "Source node/page label or id").argument("<to>", "Target node/page label or id").action(async (from, to) => {
-  const result = await pathGraphVault(process.cwd(), from, to);
+  const result = await pathGraphVault(process2.cwd(), from, to);
   if (isJson()) {
     emitJson(result);
     return;
@@ -260,7 +461,7 @@ graph.command("path").description("Find the shortest graph path between two node
   log(result.summary);
 });
 graph.command("explain").description("Explain a graph node, its page, community, and neighbors.").argument("<target>", "Node/page label or id").action(async (target) => {
-  const result = await explainGraphVault(process.cwd(), target);
+  const result = await explainGraphVault(process2.cwd(), target);
   if (isJson()) {
     emitJson(result);
     return;
@@ -269,7 +470,7 @@ graph.command("explain").description("Explain a graph node, its page, community,
 });
 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(process.cwd(), Number.isFinite(limit) ? limit : 10);
+  const result = await listGodNodes(process2.cwd(), Number.isFinite(limit) ? limit : 10);
   if (isJson()) {
     emitJson(result);
     return;
@@ -280,7 +481,7 @@ graph.command("god-nodes").description("List the highest-connectivity non-source
 });
 var review = program.command("review").description("Review staged compile approval bundles.");
 review.command("list").description("List staged approval bundles and their resolution status.").action(async () => {
-  const approvals = await listApprovals(process.cwd());
+  const approvals = await listApprovals(process2.cwd());
   if (isJson()) {
     emitJson(approvals);
     return;
@@ -296,7 +497,7 @@ review.command("list").description("List staged approval bundles and their resol
   }
 });
 review.command("show").description("Show the entries inside a staged approval bundle.").argument("<approvalId>", "Approval bundle identifier").action(async (approvalId) => {
-  const approval = await readApproval(process.cwd(), approvalId);
+  const approval = await readApproval(process2.cwd(), approvalId);
   if (isJson()) {
     emitJson(approval);
     return;
@@ -307,7 +508,7 @@ review.command("show").description("Show the entries inside a staged approval bu
   }
 });
 review.command("accept").description("Accept all pending entries, or selected entries, from a staged approval bundle.").argument("<approvalId>", "Approval bundle identifier").argument("[targets...]", "Optional page ids or paths to accept").action(async (approvalId, targets) => {
-  const result = await acceptApproval(process.cwd(), approvalId, targets);
+  const result = await acceptApproval(process2.cwd(), approvalId, targets);
   if (isJson()) {
     emitJson(result);
   } else {
@@ -315,7 +516,7 @@ review.command("accept").description("Accept all pending entries, or selected en
   }
 });
 review.command("reject").description("Reject all pending entries, or selected entries, from a staged approval bundle.").argument("<approvalId>", "Approval bundle identifier").argument("[targets...]", "Optional page ids or paths to reject").action(async (approvalId, targets) => {
-  const result = await rejectApproval(process.cwd(), approvalId, targets);
+  const result = await rejectApproval(process2.cwd(), approvalId, targets);
   if (isJson()) {
     emitJson(result);
   } else {
@@ -324,7 +525,7 @@ review.command("reject").description("Reject all pending entries, or selected en
 });
 var candidate = program.command("candidate").description("Candidate page workflows.");
 candidate.command("list").description("List staged concept and entity candidates.").action(async () => {
-  const candidates = await listCandidates(process.cwd());
+  const candidates = await listCandidates(process2.cwd());
   if (isJson()) {
     emitJson(candidates);
     return;
@@ -338,7 +539,7 @@ candidate.command("list").description("List staged concept and entity candidates
   }
 });
 candidate.command("promote").description("Promote a candidate into its active concept or entity path.").argument("<target>", "Candidate page id or path").action(async (target) => {
-  const result = await promoteCandidate(process.cwd(), target);
+  const result = await promoteCandidate(process2.cwd(), target);
   if (isJson()) {
     emitJson(result);
   } else {
@@ -346,7 +547,7 @@ candidate.command("promote").description("Promote a candidate into its active co
   }
 });
 candidate.command("archive").description("Archive a candidate by removing it from the active candidate set.").argument("<target>", "Candidate page id or path").action(async (target) => {
-  const result = await archiveCandidate(process.cwd(), target);
+  const result = await archiveCandidate(process2.cwd(), target);
   if (isJson()) {
     emitJson(result);
   } else {
@@ -356,7 +557,7 @@ 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);
   if (options.once) {
-    const result = await runWatchCycle(process.cwd(), {
+    const result = await runWatchCycle(process2.cwd(), {
       lint: options.lint ?? false,
       repo: options.repo ?? false,
       debounceMs: Number.isFinite(debounceMs) ? debounceMs : 900
@@ -370,8 +571,8 @@ var watch = program.command("watch").description("Watch the inbox directory and
     }
     return;
   }
-  const { paths } = await loadVaultConfig(process.cwd());
-  const controller = await watchVault(process.cwd(), {
+  const { paths } = await loadVaultConfig(process2.cwd());
+  const controller = await watchVault(process2.cwd(), {
     lint: options.lint ?? false,
     repo: options.repo ?? false,
     debounceMs: Number.isFinite(debounceMs) ? debounceMs : 900
@@ -381,13 +582,13 @@ var watch = program.command("watch").description("Watch the inbox directory and
   } else {
     log(`Watching inbox${options.repo ? " and tracked repos" : ""} for changes. Press Ctrl+C to stop.`);
   }
-  process.on("SIGINT", async () => {
+  process2.on("SIGINT", async () => {
     await controller.close();
-    process.exit(0);
+    process2.exit(0);
   });
 });
 watch.command("status").description("Show the latest watch run plus pending semantic refresh entries.").action(async () => {
-  const result = await getWatchStatus(process.cwd());
+  const result = await getWatchStatus(process2.cwd());
   if (isJson()) {
     emitJson(result);
     return;
@@ -399,7 +600,7 @@ watch.command("status").description("Show the latest watch run plus pending sema
   }
 });
 program.command("watch-status").description("Show the latest watch run plus pending semantic refresh entries.").action(async () => {
-  const result = await getWatchStatus(process.cwd());
+  const result = await getWatchStatus(process2.cwd());
   if (isJson()) {
     emitJson(result);
     return;
@@ -412,7 +613,7 @@ program.command("watch-status").description("Show the latest watch run plus pend
 });
 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(process.cwd());
+  const status = await installGitHooks(process2.cwd());
   if (isJson()) {
     emitJson(status);
     return;
@@ -420,7 +621,7 @@ hook.command("install").description("Install post-commit and post-checkout hooks
   log(`Installed hooks in ${status.repoRoot}`);
 });
 hook.command("uninstall").description("Remove the SwarmVault-managed git hook blocks from the nearest git repository.").action(async () => {
-  const status = await uninstallGitHooks(process.cwd());
+  const status = await uninstallGitHooks(process2.cwd());
   if (isJson()) {
     emitJson(status);
     return;
@@ -428,7 +629,7 @@ hook.command("uninstall").description("Remove the SwarmVault-managed git hook bl
   log(`Removed SwarmVault hook blocks from ${status.repoRoot ?? "the current workspace"}`);
 });
 hook.command("status").description("Show whether SwarmVault-managed git hooks are installed.").action(async () => {
-  const status = await getGitHookStatus(process.cwd());
+  const status = await getGitHookStatus(process2.cwd());
   if (isJson()) {
     emitJson(status);
     return;
@@ -443,7 +644,7 @@ hook.command("status").description("Show whether SwarmVault-managed git hooks ar
 });
 var schedule = program.command("schedule").description("Run scheduled vault maintenance jobs.");
 schedule.command("list").description("List configured schedule jobs and their next run state.").action(async () => {
-  const schedules = await listSchedules(process.cwd());
+  const schedules = await listSchedules(process2.cwd());
   if (isJson()) {
     emitJson(schedules);
     return;
@@ -459,7 +660,7 @@ schedule.command("list").description("List configured schedule jobs and their ne
   }
 });
 schedule.command("run").description("Run one configured schedule job immediately.").argument("<jobId>", "Schedule identifier").action(async (jobId) => {
-  const result = await runSchedule(process.cwd(), jobId);
+  const result = await runSchedule(process2.cwd(), jobId);
   if (isJson()) {
     emitJson(result);
     return;
@@ -470,46 +671,46 @@ 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(process.cwd(), Number.isFinite(pollMs) ? pollMs : 3e4);
+  const controller = await serveSchedules(process2.cwd(), Number.isFinite(pollMs) ? pollMs : 3e4);
   if (isJson()) {
     emitJson({ status: "serving", pollMs: Number.isFinite(pollMs) ? pollMs : 3e4 });
   } else {
     log("Serving schedules. Press Ctrl+C to stop.");
   }
-  process.on("SIGINT", async () => {
+  process2.on("SIGINT", async () => {
     await controller.close();
-    process.exit(0);
+    process2.exit(0);
   });
 });
 program.command("mcp").description("Run SwarmVault as a local MCP server over stdio.").action(async () => {
   if (isJson()) {
-    process.stderr.write(`${JSON.stringify({ status: "running", transport: "stdio" })}
+    process2.stderr.write(`${JSON.stringify({ status: "running", transport: "stdio" })}
 `);
   }
-  const controller = await startMcpServer(process.cwd());
-  process.on("SIGINT", async () => {
+  const controller = await startMcpServer(process2.cwd());
+  process2.on("SIGINT", async () => {
     await controller.close();
-    process.exit(0);
+    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(process.cwd(), options.agent, { claudeHook: options.hook ?? false });
+  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.parseAsync(process.argv).catch((error) => {
+program.parseAsync(process2.argv).catch((error) => {
   const message = error instanceof Error ? error.message : String(error);
   if (isJson()) {
     emitJson({ error: message });
   } else {
-    process.stderr.write(`${message}
+    process2.stderr.write(`${message}
 `);
   }
-  process.exit(1);
+  process2.exit(1);
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarmvaultai/cli",
-  "version": "0.1.25",
+  "version": "0.1.27",
   "description": "Global CLI for SwarmVault.",
   "type": "module",
   "main": "dist/index.js",
@@ -37,17 +37,18 @@
   "engines": {
     "node": ">=24.0.0"
   },
-  "scripts": {
-    "build": "tsup src/index.ts --format esm --dts",
-    "test": "node -e \"process.exit(0)\"",
-    "typecheck": "tsc --noEmit"
-  },
   "dependencies": {
-    "@swarmvaultai/engine": "0.1.25",
+    "@swarmvaultai/engine": "0.1.27",
     "commander": "^14.0.1"
   },
   "devDependencies": {
     "@types/node": "^24.6.0",
-    "tsup": "^8.5.0"
+    "tsup": "^8.5.0",
+    "vitest": "^3.2.4"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
   }
-}
+}