bluera-knowledge 0.11.5 → 0.11.7

package/.claude/settings.local.json.example

@@ -7,6 +7,11 @@
       "Bash(npm run lint:*)",
       "Bash(npm run typecheck:*)",
       "Bash(bun run precommit:*)"
+    ],
+    "deny": [
+      "Bash(*validate-npm-release*)",
+      "Bash(bun run validate:*)",
+      "Bash(npm run validate:*)"
     ]
   },
   "hooks": {

package/.claude-plugin/plugin.json

@@ -1,5 +1,18 @@
 {
   "name": "bluera-knowledge",
-  "version": "0.11.5",
-  "description": "Clone repos, crawl docs, search locally. Fast, authoritative answers for AI coding agents."
+  "version": "0.11.7",
+  "description": "Clone repos, crawl docs, search locally. Fast, authoritative answers for AI coding agents.",
+  "mcpServers": {
+    "bluera-knowledge": {
+      "command": "node",
+      "args": [
+        "${CLAUDE_PLUGIN_ROOT}/dist/mcp/server.js"
+      ],
+      "env": {
+        "PROJECT_ROOT": "${PWD}",
+        "DATA_DIR": ".bluera/bluera-knowledge/data",
+        "CONFIG_PATH": ".bluera/bluera-knowledge/config.json"
+      }
+    }
+  }
 }

package/CHANGELOG.md

@@ -2,6 +2,36 @@
 
 All notable changes to this project will be documented in this file. See [commit-and-tag-version](https://github.com/absolute-version/commit-and-tag-version) for commit guidelines.
 
+## [0.11.7](https://github.com/blueraai/bluera-knowledge/compare/v0.11.6...v0.11.7) (2026-01-10)
+
+
+### Features
+
+* **scripts:** add post-release npm validation script ([e4c29a0](https://github.com/blueraai/bluera-knowledge/commit/e4c29a0c83907de4bc293a69a58412629457fb22))
+
+
+### Bug Fixes
+
+* **cli:** plugin-api commands now respect global options ([d3cca02](https://github.com/blueraai/bluera-knowledge/commit/d3cca02ffc679ffc187b76c7682f3cc177eabdea))
+* **scripts:** use mktemp for temp directories in validation script ([3107861](https://github.com/blueraai/bluera-knowledge/commit/3107861bd7a966016fde2a121469dd84756f39be))
+
+## [0.11.6](https://github.com/blueraai/bluera-knowledge/compare/v0.10.0...v0.11.6) (2026-01-10)
+
+
+### Features
+
+* add file logging to background worker for visibility ([6d7a751](https://github.com/blueraai/bluera-knowledge/commit/6d7a751de59a566c34b03b434c772ecde3770b2c))
+* **analysis:** add custom language extensibility framework with ZIL adapter ([c4dc526](https://github.com/blueraai/bluera-knowledge/commit/c4dc526467c70dbc3fb28e7e5d7620a90cc3bf95))
+* require env vars with no defaults (fail fast) ([b404cd6](https://github.com/blueraai/bluera-knowledge/commit/b404cd60374e0a7c5ace89f1ef0235bfc5c799fa))
+* **sync:** add git-committable store definitions with sync command ([5cfa925](https://github.com/blueraai/bluera-knowledge/commit/5cfa92580397f193fda75ea61197fb4c9d9d4b0a))
+
+
+### Bug Fixes
+
+* **crawl:** handle Claude CLI structured_output wrapper in intelligent crawl ([54ea74b](https://github.com/blueraai/bluera-knowledge/commit/54ea74bca6d4b7263ef11a8290416e0d66b8d37f))
+* **test:** add timeout to flaky search test ([5848b76](https://github.com/blueraai/bluera-knowledge/commit/5848b7648a547510fc2333f283ae835a6ca9efef))
+* use relative path in .mcp.json for project-level MCP config ([6d7a55e](https://github.com/blueraai/bluera-knowledge/commit/6d7a55ef86dd5ac5d568feafa3ab207faa843d46))
+
 ## [0.11.5](https://github.com/blueraai/bluera-knowledge/compare/v0.10.0...v0.11.5) (2026-01-10)
 
 

package/README.md

@@ -1147,7 +1147,7 @@ playwright install chromium
 
 ## 🔌 MCP Integration
 
-The plugin includes a Model Context Protocol server that exposes search tools. This is configured in `mcp.plugin.json`:
+The plugin includes a Model Context Protocol server that exposes search tools. This is configured inline in `.claude-plugin/plugin.json`:
 
 > [!IMPORTANT]
 > **Commands vs MCP Tools**: You interact with the plugin using `/bluera-knowledge:` slash commands. Behind the scenes, these commands instruct Claude Code to use MCP tools (`mcp__bluera-knowledge__*`) which handle the actual operations. Commands provide the user interface, while MCP tools are the backend that AI agents use to access your knowledge stores.
@@ -1159,6 +1159,7 @@ The plugin includes a Model Context Protocol server that exposes search tools. T
       "command": "node",
       "args": ["${CLAUDE_PLUGIN_ROOT}/dist/mcp/server.js"],
       "env": {
+        "PROJECT_ROOT": "${PWD}",
         "DATA_DIR": ".bluera/bluera-knowledge/data",
         "CONFIG_PATH": ".bluera/bluera-knowledge/config.json"
       }
@@ -1600,6 +1601,22 @@ Note: The version command runs full quality checks (format, lint, deadcode, type
 
 > 💡 **That's it!** No manual tagging needed. Just push to `main` and the release happens automatically when CI passes.
 
+### 🔍 Post-Release Validation
+
+After a release, validate the npm package works correctly:
+
+```bash
+bun run validate:npm
+```
+
+This script:
+- Installs the latest `bluera-knowledge` from npm globally
+- Exercises all CLI commands (stores, add-folder, search, index, delete)
+- Writes detailed logs to `logs/validation/npm-validation-*.log`
+- Returns exit code 0 on success, 1 on failure
+
+Use this to catch any packaging or runtime issues after npm publish.
+
 ### 🧪 Testing Locally
 
 **Option 1: Development MCP Server (Recommended)**
@@ -1618,7 +1635,7 @@ cd /path/to/bluera-knowledge
 claude --plugin-dir .
 ```
 
-The MCP config in `mcp.plugin.json` is only loaded when the directory is loaded as a plugin (via `--plugin-dir` or marketplace install), so there's no conflict with project-level MCP config.
+The MCP config in `plugin.json` is only loaded when the directory is loaded as a plugin (via `--plugin-dir` or marketplace install), so there's no conflict with project-level MCP config.
 
 **Option 3: CLI Tool Testing**
 

package/dist/index.js

@@ -773,8 +773,12 @@ var RepoUrlResolver = class {
 };
 
 // src/plugin/commands.ts
-async function handleAddRepo(args) {
-  const services = await createServices(void 0, void 0, process.env["PWD"]);
+async function handleAddRepo(args, options = {}) {
+  const services = await createServices(
+    options.config,
+    options.dataDir,
+    options.projectRoot ?? process.env["PWD"]
+  );
   const storeName = args.name ?? extractRepoName(args.url);
   console.log(`Cloning ${args.url}...`);
   const result = await services.store.create({
@@ -799,8 +803,12 @@ async function handleAddRepo(args) {
     console.error(`Indexing failed: ${indexResult.error.message}`);
   }
 }
-async function handleAddFolder(args) {
-  const services = await createServices(void 0, void 0, process.env["PWD"]);
+async function handleAddFolder(args, options = {}) {
+  const services = await createServices(
+    options.config,
+    options.dataDir,
+    options.projectRoot ?? process.env["PWD"]
+  );
   const { basename } = await import("path");
   const storeName = args.name ?? basename(args.path);
   console.log(`Adding folder: ${args.path}...`);
@@ -825,8 +833,12 @@ async function handleAddFolder(args) {
     console.error(`Indexing failed: ${indexResult.error.message}`);
   }
 }
-async function handleStores() {
-  const services = await createServices(void 0, void 0, process.env["PWD"]);
+async function handleStores(options = {}) {
+  const services = await createServices(
+    options.config,
+    options.dataDir,
+    options.projectRoot ?? process.env["PWD"]
+  );
   const stores = await services.store.list();
   if (stores.length === 0) {
     console.log("No stores found.");
@@ -850,10 +862,10 @@ async function handleStores() {
     console.log(`| ${name} | ${type} | ${id.substring(0, 8)}... | ${source} |`);
   }
 }
-async function handleSuggest() {
-  const projectRoot = process.env["PWD"] ?? process.cwd();
+async function handleSuggest(options = {}) {
+  const projectRoot = options.projectRoot ?? process.env["PWD"] ?? process.cwd();
   console.log("Analyzing project dependencies...\n");
-  const services = await createServices(void 0, void 0, projectRoot);
+  const services = await createServices(options.config, options.dataDir, projectRoot);
   const analyzer = new DependencyUsageAnalyzer();
   const resolver = new RepoUrlResolver();
   const spinner = ora3("Scanning source files...").start();
@@ -910,24 +922,58 @@ async function handleSuggest() {
 }
 
 // src/cli/commands/plugin-api.ts
-function createAddRepoCommand(_getOptions) {
+function createAddRepoCommand(getOptions) {
   return new Command4("add-repo").description("Clone and index a library source repository").argument("<url>", "Git repository URL").option("--name <name>", "Store name (defaults to repo name)").option("--branch <branch>", "Git branch to clone").action(async (url, options) => {
-    await handleAddRepo({ url, ...options });
+    const globalOpts = getOptions();
+    await handleAddRepo(
+      { url, ...options },
+      {
+        config: globalOpts.config,
+        dataDir: globalOpts.dataDir,
+        projectRoot: globalOpts.projectRoot,
+        format: globalOpts.format,
+        quiet: globalOpts.quiet
+      }
+    );
   });
 }
-function createAddFolderCommand(_getOptions) {
+function createAddFolderCommand(getOptions) {
   return new Command4("add-folder").description("Index a local folder of reference material").argument("<path>", "Folder path to index").option("--name <name>", "Store name (defaults to folder name)").action(async (path, options) => {
-    await handleAddFolder({ path, ...options });
+    const globalOpts = getOptions();
+    await handleAddFolder(
+      { path, ...options },
+      {
+        config: globalOpts.config,
+        dataDir: globalOpts.dataDir,
+        projectRoot: globalOpts.projectRoot,
+        format: globalOpts.format,
+        quiet: globalOpts.quiet
+      }
+    );
   });
 }
-function createStoresCommand(_getOptions) {
+function createStoresCommand(getOptions) {
   return new Command4("stores").description("List all indexed library stores").action(async () => {
-    await handleStores();
+    const globalOpts = getOptions();
+    await handleStores({
+      config: globalOpts.config,
+      dataDir: globalOpts.dataDir,
+      projectRoot: globalOpts.projectRoot,
+      format: globalOpts.format,
+      quiet: globalOpts.quiet
+    });
   });
 }
-function createSuggestCommand(_getOptions) {
+function createSuggestCommand(getOptions) {
   return new Command4("suggest").description("Suggest important dependencies to add to knowledge stores").action(async () => {
-    await handleSuggest();
+    const globalOpts = getOptions();
+    await handleSuggest({
+      config: globalOpts.config,
+      dataDir: globalOpts.dataDir,
+      projectRoot: globalOpts.projectRoot,
+      format: globalOpts.format,
+      quiet: globalOpts.quiet
+    });
   });
 }