bluera-knowledge 0.16.5 → 0.17.0

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 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.17.0](https://github.com/blueraai/bluera-knowledge/compare/v0.16.6...v0.17.0) (2026-01-18)
+
+
+### Features
+
+* **bootstrap:** add interrupted install recovery via lock file ([5bf4773](https://github.com/blueraai/bluera-knowledge/commit/5bf4773b59f27fe04fc6e8f7da0fe37cc4902ac7))
+
+
+### Bug Fixes
+
+* **settings:** narrow deny rules to block execution only ([daf758b](https://github.com/blueraai/bluera-knowledge/commit/daf758b211eb2e2179d198485f0a7705fb137759))
+
 ## [0.16.4](https://github.com/blueraai/bluera-knowledge/compare/v0.16.3...v0.16.4) (2026-01-17)
 
 

package/dist/mcp/bootstrap.js

@@ -2,7 +2,15 @@
 
 // src/mcp/bootstrap.ts
 import { execSync } from "child_process";
-import { appendFileSync, existsSync, mkdirSync, readFileSync } from "fs";
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  rmSync,
+  unlinkSync,
+  writeFileSync
+} from "fs";
 import { homedir } from "os";
 import { dirname, join } from "path";
 import { fileURLToPath } from "url";
@@ -26,6 +34,7 @@ var log = (level, msg, data) => {
 var __filename = fileURLToPath(import.meta.url);
 var __dirname = dirname(__filename);
 var pluginRoot = join(__dirname, "..", "..");
+var installLockFile = join(pluginRoot, ".node_modules_installing");
 var getVersion = () => {
   try {
     const pkg = JSON.parse(readFileSync(join(pluginRoot, "package.json"), "utf-8"));
@@ -52,11 +61,19 @@ function installWithPackageManager() {
   log("info", "Dependencies installed via package manager");
 }
 function ensureDependencies() {
-  if (existsSync(join(pluginRoot, "node_modules"))) {
+  const nodeModulesPath = join(pluginRoot, "node_modules");
+  if (existsSync(installLockFile)) {
+    log("info", "Detected interrupted install, cleaning up");
+    rmSync(nodeModulesPath, { recursive: true, force: true });
+    unlinkSync(installLockFile);
+  }
+  if (existsSync(nodeModulesPath)) {
     log("info", "Dependencies already installed");
     return;
   }
+  writeFileSync(installLockFile, (/* @__PURE__ */ new Date()).toISOString());
   installWithPackageManager();
+  unlinkSync(installLockFile);
 }
 var VERSION = getVersion();
 log("info", "Bootstrap starting", { pluginRoot, version: VERSION });

package/dist/mcp/bootstrap.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/mcp/bootstrap.ts"],"sourcesContent":["#!/usr/bin/env node\n/**\n * MCP Server Bootstrap - installs dependencies before starting server.\n *\n * Uses only Node.js built-ins (no external dependencies required).\n * Self-locates plugin root via import.meta.url (doesn't rely on CLAUDE_PLUGIN_ROOT).\n *\n * Dependency installation strategy:\n * 1. Fast path: node_modules already exists → skip\n * 2. Package manager: Run bun install or npm ci\n *\n * IMPORTANT: MCP servers must NOT log to stderr - Claude Code treats stderr output\n * as an error and may mark the MCP server as failed. All logging goes to file.\n */\nimport { execSync } from 'node:child_process';\nimport { appendFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';\nimport { homedir } from 'node:os';\nimport { dirname, join } from 'node:path';\nimport { fileURLToPath } from 'node:url';\n\n// Logging helper - writes to file since MCP servers must NOT use stderr\n// (Claude Code treats stderr as error and may fail the server)\n// JSON format matches pino output for consistency\nconst logDir = join(homedir(), '.bluera', 'bluera-knowledge', 'logs');\nconst logFile = join(logDir, 'app.log');\n\nconst log = (\n  level: 'info' | 'error' | 'debug',\n  msg: string,\n  data?: Record<string, unknown>\n): void => {\n  try {\n    mkdirSync(logDir, { recursive: true });\n    const entry = {\n      time: new Date().toISOString(),\n      level,\n      module: 'bootstrap',\n      msg,\n      ...data,\n    };\n    appendFileSync(logFile, `${JSON.stringify(entry)}\\n`);\n  } catch {\n    // Silently fail - we cannot use stderr for MCP servers\n  }\n};\n\n// Self-locate plugin root from this file's path\n// dist/mcp/bootstrap.js -> plugin root (two directories up)\nconst __filename = fileURLToPath(import.meta.url);\nconst __dirname = dirname(__filename);\nconst pluginRoot = join(__dirname, '..', '..');\n\n// Get version from package.json for logging\nconst getVersion = (): string => {\n  try {\n    const pkg: unknown = JSON.parse(readFileSync(join(pluginRoot, 'package.json'), 'utf-8'));\n    if (\n      typeof pkg === 'object' &&\n      pkg !== null &&\n      'version' in pkg &&\n      typeof pkg.version === 'string'\n    ) {\n      return `v${pkg.version}`;\n    }\n    return 'unknown';\n  } catch {\n    return 'unknown';\n  }\n};\n\n/**\n * Install dependencies using bun or npm.\n */\nfunction installWithPackageManager(): void {\n  const hasBun = ((): boolean => {\n    try {\n      execSync('which bun', { stdio: 'ignore' });\n      return true;\n    } catch {\n      return false;\n    }\n  })();\n\n  const cmd = hasBun ? 'bun install --frozen-lockfile' : 'npm ci --silent';\n  log('info', 'Installing dependencies with package manager', { hasBun, cmd });\n  execSync(cmd, { cwd: pluginRoot, stdio: 'inherit' });\n  log('info', 'Dependencies installed via package manager');\n}\n\n/**\n * Ensure dependencies are available.\n */\nfunction ensureDependencies(): void {\n  // Fast path: already installed\n  if (existsSync(join(pluginRoot, 'node_modules'))) {\n    log('info', 'Dependencies already installed');\n    return;\n  }\n\n  // Install via package manager\n  installWithPackageManager();\n}\n\n// Main entry point\nconst VERSION = getVersion();\nlog('info', 'Bootstrap starting', { pluginRoot, version: VERSION });\n\nensureDependencies();\n\n// Now that dependencies are installed, import and run the server\n// Dynamic import required because @modelcontextprotocol/sdk wouldn't be available before install\nlog('info', 'Loading server module');\nconst { runMCPServer } = await import('./server.js');\n\nconst projectRoot = process.env['PROJECT_ROOT'];\nif (projectRoot === undefined) {\n  throw new Error('PROJECT_ROOT environment variable is required');\n}\n\nlog('info', 'Starting MCP server', {\n  projectRoot,\n  dataDir: process.env['DATA_DIR'],\n});\n\nawait runMCPServer({\n  dataDir: process.env['DATA_DIR'],\n  config: process.env['CONFIG_PATH'],\n  projectRoot,\n});\n"],"mappings":";;;AAcA,SAAS,gBAAgB;AACzB,SAAS,gBAAgB,YAAY,WAAW,oBAAoB;AACpE,SAAS,eAAe;AACxB,SAAS,SAAS,YAAY;AAC9B,SAAS,qBAAqB;AAK9B,IAAM,SAAS,KAAK,QAAQ,GAAG,WAAW,oBAAoB,MAAM;AACpE,IAAM,UAAU,KAAK,QAAQ,SAAS;AAEtC,IAAM,MAAM,CACV,OACA,KACA,SACS;AACT,MAAI;AACF,cAAU,QAAQ,EAAE,WAAW,KAAK,CAAC;AACrC,UAAM,QAAQ;AAAA,MACZ,OAAM,oBAAI,KAAK,GAAE,YAAY;AAAA,MAC7B;AAAA,MACA,QAAQ;AAAA,MACR;AAAA,MACA,GAAG;AAAA,IACL;AACA,mBAAe,SAAS,GAAG,KAAK,UAAU,KAAK,CAAC;AAAA,CAAI;AAAA,EACtD,QAAQ;AAAA,EAER;AACF;AAIA,IAAM,aAAa,cAAc,YAAY,GAAG;AAChD,IAAM,YAAY,QAAQ,UAAU;AACpC,IAAM,aAAa,KAAK,WAAW,MAAM,IAAI;AAG7C,IAAM,aAAa,MAAc;AAC/B,MAAI;AACF,UAAM,MAAe,KAAK,MAAM,aAAa,KAAK,YAAY,cAAc,GAAG,OAAO,CAAC;AACvF,QACE,OAAO,QAAQ,YACf,QAAQ,QACR,aAAa,OACb,OAAO,IAAI,YAAY,UACvB;AACA,aAAO,IAAI,IAAI,OAAO;AAAA,IACxB;AACA,WAAO;AAAA,EACT,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAKA,SAAS,4BAAkC;AACzC,QAAM,UAAU,MAAe;AAC7B,QAAI;AACF,eAAS,aAAa,EAAE,OAAO,SAAS,CAAC;AACzC,aAAO;AAAA,IACT,QAAQ;AACN,aAAO;AAAA,IACT;AAAA,EACF,GAAG;AAEH,QAAM,MAAM,SAAS,kCAAkC;AACvD,MAAI,QAAQ,gDAAgD,EAAE,QAAQ,IAAI,CAAC;AAC3E,WAAS,KAAK,EAAE,KAAK,YAAY,OAAO,UAAU,CAAC;AACnD,MAAI,QAAQ,4CAA4C;AAC1D;AAKA,SAAS,qBAA2B;AAElC,MAAI,WAAW,KAAK,YAAY,cAAc,CAAC,GAAG;AAChD,QAAI,QAAQ,gCAAgC;AAC5C;AAAA,EACF;AAGA,4BAA0B;AAC5B;AAGA,IAAM,UAAU,WAAW;AAC3B,IAAI,QAAQ,sBAAsB,EAAE,YAAY,SAAS,QAAQ,CAAC;AAElE,mBAAmB;AAInB,IAAI,QAAQ,uBAAuB;AACnC,IAAM,EAAE,aAAa,IAAI,MAAM,OAAO,aAAa;AAEnD,IAAM,cAAc,QAAQ,IAAI,cAAc;AAC9C,IAAI,gBAAgB,QAAW;AAC7B,QAAM,IAAI,MAAM,+CAA+C;AACjE;AAEA,IAAI,QAAQ,uBAAuB;AAAA,EACjC;AAAA,EACA,SAAS,QAAQ,IAAI,UAAU;AACjC,CAAC;AAED,MAAM,aAAa;AAAA,EACjB,SAAS,QAAQ,IAAI,UAAU;AAAA,EAC/B,QAAQ,QAAQ,IAAI,aAAa;AAAA,EACjC;AACF,CAAC;","names":[]}
+{"version":3,"sources":["../../src/mcp/bootstrap.ts"],"sourcesContent":["#!/usr/bin/env node\n/**\n * MCP Server Bootstrap - installs dependencies before starting server.\n *\n * Uses only Node.js built-ins (no external dependencies required).\n * Self-locates plugin root via import.meta.url (doesn't rely on CLAUDE_PLUGIN_ROOT).\n *\n * Dependency installation strategy:\n * 1. Fast path: node_modules already exists → skip\n * 2. Package manager: Run bun install or npm ci\n *\n * IMPORTANT: MCP servers must NOT log to stderr - Claude Code treats stderr output\n * as an error and may mark the MCP server as failed. All logging goes to file.\n */\nimport { execSync } from 'node:child_process';\nimport {\n  appendFileSync,\n  existsSync,\n  mkdirSync,\n  readFileSync,\n  rmSync,\n  unlinkSync,\n  writeFileSync,\n} from 'node:fs';\nimport { homedir } from 'node:os';\nimport { dirname, join } from 'node:path';\nimport { fileURLToPath } from 'node:url';\n\n// Logging helper - writes to file since MCP servers must NOT use stderr\n// (Claude Code treats stderr as error and may fail the server)\n// JSON format matches pino output for consistency\nconst logDir = join(homedir(), '.bluera', 'bluera-knowledge', 'logs');\nconst logFile = join(logDir, 'app.log');\n\nconst log = (\n  level: 'info' | 'error' | 'debug',\n  msg: string,\n  data?: Record<string, unknown>\n): void => {\n  try {\n    mkdirSync(logDir, { recursive: true });\n    const entry = {\n      time: new Date().toISOString(),\n      level,\n      module: 'bootstrap',\n      msg,\n      ...data,\n    };\n    appendFileSync(logFile, `${JSON.stringify(entry)}\\n`);\n  } catch {\n    // Silently fail - we cannot use stderr for MCP servers\n  }\n};\n\n// Self-locate plugin root from this file's path\n// dist/mcp/bootstrap.js -> plugin root (two directories up)\nconst __filename = fileURLToPath(import.meta.url);\nconst __dirname = dirname(__filename);\nconst pluginRoot = join(__dirname, '..', '..');\n\n// Lock file to detect interrupted installs\nconst installLockFile = join(pluginRoot, '.node_modules_installing');\n\n// Get version from package.json for logging\nconst getVersion = (): string => {\n  try {\n    const pkg: unknown = JSON.parse(readFileSync(join(pluginRoot, 'package.json'), 'utf-8'));\n    if (\n      typeof pkg === 'object' &&\n      pkg !== null &&\n      'version' in pkg &&\n      typeof pkg.version === 'string'\n    ) {\n      return `v${pkg.version}`;\n    }\n    return 'unknown';\n  } catch {\n    return 'unknown';\n  }\n};\n\n/**\n * Install dependencies using bun or npm.\n */\nfunction installWithPackageManager(): void {\n  const hasBun = ((): boolean => {\n    try {\n      execSync('which bun', { stdio: 'ignore' });\n      return true;\n    } catch {\n      return false;\n    }\n  })();\n\n  const cmd = hasBun ? 'bun install --frozen-lockfile' : 'npm ci --silent';\n  log('info', 'Installing dependencies with package manager', { hasBun, cmd });\n  execSync(cmd, { cwd: pluginRoot, stdio: 'inherit' });\n  log('info', 'Dependencies installed via package manager');\n}\n\n/**\n * Ensure dependencies are available.\n * Uses a lock file to detect and recover from interrupted installs.\n */\nfunction ensureDependencies(): void {\n  const nodeModulesPath = join(pluginRoot, 'node_modules');\n\n  // Check for interrupted install - lock file exists means previous install was killed\n  if (existsSync(installLockFile)) {\n    log('info', 'Detected interrupted install, cleaning up');\n    rmSync(nodeModulesPath, { recursive: true, force: true });\n    unlinkSync(installLockFile);\n  }\n\n  // Fast path: already installed\n  if (existsSync(nodeModulesPath)) {\n    log('info', 'Dependencies already installed');\n    return;\n  }\n\n  // Create lock file before install (left behind if install interrupted/fails)\n  writeFileSync(installLockFile, new Date().toISOString());\n\n  installWithPackageManager();\n\n  // Remove lock file on success\n  unlinkSync(installLockFile);\n}\n\n// Main entry point\nconst VERSION = getVersion();\nlog('info', 'Bootstrap starting', { pluginRoot, version: VERSION });\n\nensureDependencies();\n\n// Now that dependencies are installed, import and run the server\n// Dynamic import required because @modelcontextprotocol/sdk wouldn't be available before install\nlog('info', 'Loading server module');\nconst { runMCPServer } = await import('./server.js');\n\nconst projectRoot = process.env['PROJECT_ROOT'];\nif (projectRoot === undefined) {\n  throw new Error('PROJECT_ROOT environment variable is required');\n}\n\nlog('info', 'Starting MCP server', {\n  projectRoot,\n  dataDir: process.env['DATA_DIR'],\n});\n\nawait runMCPServer({\n  dataDir: process.env['DATA_DIR'],\n  config: process.env['CONFIG_PATH'],\n  projectRoot,\n});\n"],"mappings":";;;AAcA,SAAS,gBAAgB;AACzB;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AACP,SAAS,eAAe;AACxB,SAAS,SAAS,YAAY;AAC9B,SAAS,qBAAqB;AAK9B,IAAM,SAAS,KAAK,QAAQ,GAAG,WAAW,oBAAoB,MAAM;AACpE,IAAM,UAAU,KAAK,QAAQ,SAAS;AAEtC,IAAM,MAAM,CACV,OACA,KACA,SACS;AACT,MAAI;AACF,cAAU,QAAQ,EAAE,WAAW,KAAK,CAAC;AACrC,UAAM,QAAQ;AAAA,MACZ,OAAM,oBAAI,KAAK,GAAE,YAAY;AAAA,MAC7B;AAAA,MACA,QAAQ;AAAA,MACR;AAAA,MACA,GAAG;AAAA,IACL;AACA,mBAAe,SAAS,GAAG,KAAK,UAAU,KAAK,CAAC;AAAA,CAAI;AAAA,EACtD,QAAQ;AAAA,EAER;AACF;AAIA,IAAM,aAAa,cAAc,YAAY,GAAG;AAChD,IAAM,YAAY,QAAQ,UAAU;AACpC,IAAM,aAAa,KAAK,WAAW,MAAM,IAAI;AAG7C,IAAM,kBAAkB,KAAK,YAAY,0BAA0B;AAGnE,IAAM,aAAa,MAAc;AAC/B,MAAI;AACF,UAAM,MAAe,KAAK,MAAM,aAAa,KAAK,YAAY,cAAc,GAAG,OAAO,CAAC;AACvF,QACE,OAAO,QAAQ,YACf,QAAQ,QACR,aAAa,OACb,OAAO,IAAI,YAAY,UACvB;AACA,aAAO,IAAI,IAAI,OAAO;AAAA,IACxB;AACA,WAAO;AAAA,EACT,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAKA,SAAS,4BAAkC;AACzC,QAAM,UAAU,MAAe;AAC7B,QAAI;AACF,eAAS,aAAa,EAAE,OAAO,SAAS,CAAC;AACzC,aAAO;AAAA,IACT,QAAQ;AACN,aAAO;AAAA,IACT;AAAA,EACF,GAAG;AAEH,QAAM,MAAM,SAAS,kCAAkC;AACvD,MAAI,QAAQ,gDAAgD,EAAE,QAAQ,IAAI,CAAC;AAC3E,WAAS,KAAK,EAAE,KAAK,YAAY,OAAO,UAAU,CAAC;AACnD,MAAI,QAAQ,4CAA4C;AAC1D;AAMA,SAAS,qBAA2B;AAClC,QAAM,kBAAkB,KAAK,YAAY,cAAc;AAGvD,MAAI,WAAW,eAAe,GAAG;AAC/B,QAAI,QAAQ,2CAA2C;AACvD,WAAO,iBAAiB,EAAE,WAAW,MAAM,OAAO,KAAK,CAAC;AACxD,eAAW,eAAe;AAAA,EAC5B;AAGA,MAAI,WAAW,eAAe,GAAG;AAC/B,QAAI,QAAQ,gCAAgC;AAC5C;AAAA,EACF;AAGA,gBAAc,kBAAiB,oBAAI,KAAK,GAAE,YAAY,CAAC;AAEvD,4BAA0B;AAG1B,aAAW,eAAe;AAC5B;AAGA,IAAM,UAAU,WAAW;AAC3B,IAAI,QAAQ,sBAAsB,EAAE,YAAY,SAAS,QAAQ,CAAC;AAElE,mBAAmB;AAInB,IAAI,QAAQ,uBAAuB;AACnC,IAAM,EAAE,aAAa,IAAI,MAAM,OAAO,aAAa;AAEnD,IAAM,cAAc,QAAQ,IAAI,cAAc;AAC9C,IAAI,gBAAgB,QAAW;AAC7B,QAAM,IAAI,MAAM,+CAA+C;AACjE;AAEA,IAAI,QAAQ,uBAAuB;AAAA,EACjC;AAAA,EACA,SAAS,QAAQ,IAAI,UAAU;AACjC,CAAC;AAED,MAAM,aAAa;AAAA,EACjB,SAAS,QAAQ,IAAI,UAAU;AAAA,EAC/B,QAAQ,QAAQ,IAAI,aAAa;AAAA,EACjC;AACF,CAAC;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bluera-knowledge",
-  "version": "0.16.5",
+  "version": "0.17.0",
   "description": "CLI tool for managing knowledge stores with semantic search",
   "type": "module",
   "bin": {
@@ -67,10 +67,6 @@
   "files": [
     "dist/",
     "python/",
-    "hooks/",
-    "commands/",
-    "skills/",
-    ".claude-plugin/",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"

package/.claude-plugin/plugin.json

@@ -1,9 +0,0 @@
-{
-  "name": "bluera-knowledge",
-  "version": "0.16.4",
-  "description": "Clone repos, crawl docs, search locally. Fast, authoritative answers for AI coding agents.",
-  "author": {
-    "name": "Bluera Inc",
-    "url": "https://bluera.ai"
-  }
-}

package/commands/add-folder.md

@@ -1,48 +0,0 @@
----
-description: Index a local folder of reference material
-argument-hint: "[path] [--name store-name]"
-allowed-tools: ["mcp__bluera-knowledge__execute"]
----
-
-# Add Local Folder to Knowledge Stores
-
-Index a local folder of reference material: **$ARGUMENTS**
-
-## Steps
-
-1. Parse arguments from $ARGUMENTS:
-   - Extract the folder path (required, first positional argument)
-   - Extract --name parameter (optional, defaults to folder name)
-
-2. Use mcp__bluera-knowledge__execute tool with command "store:create":
-   - args.name: Store name (from --name or folder basename)
-   - args.type: "file"
-   - args.source: The folder path
-
-3. Display results showing job ID for background indexing:
-
-```
-✓ Adding folder: /Users/me/my-docs...
-✓ Created store: my-docs (e5f6g7h8...)
-  Location: ~/.local/share/bluera-knowledge/stores/e5f6g7h8.../
-
-🔄 Indexing started in background
-   Job ID: job_xyz789abc123
-
-Check status with: /bluera-knowledge:check-status job_xyz789abc123
-Or view all jobs: /bluera-knowledge:check-status
-```
-
-## Error Handling
-
-If creation fails (e.g., path doesn't exist, permission denied):
-
-```
-✗ Failed to add folder: [error message]
-
-Common issues:
-- Check that the path exists
-- Ensure you have read permissions for the folder
-- Verify the path is a directory, not a file
-- Use absolute paths to avoid ambiguity
-```

package/commands/add-repo.md

@@ -1,50 +0,0 @@
----
-description: Clone and index a library source repository
-argument-hint: "[git-url] [--name store-name] [--branch branch-name]"
-allowed-tools: ["mcp__bluera-knowledge__execute"]
----
-
-# Add Repository to Knowledge Stores
-
-Clone and index a library source repository: **$ARGUMENTS**
-
-## Steps
-
-1. Parse arguments from $ARGUMENTS:
-   - Extract the git URL (required, first positional argument)
-   - Extract --name parameter (optional, defaults to repo name from URL)
-   - Extract --branch parameter (optional, defaults to default branch)
-
-2. Use mcp__bluera-knowledge__execute tool with command "store:create":
-   - args.name: Store name (from --name or extracted from URL)
-   - args.type: "repo"
-   - args.source: The git URL
-   - args.branch: Branch name (if --branch specified)
-
-3. Display results showing job ID for background indexing:
-
-```
-✓ Cloning https://github.com/facebook/react...
-✓ Created store: react (a1b2c3d4...)
-  Location: ~/.local/share/bluera-knowledge/stores/a1b2c3d4.../
-
-🔄 Indexing started in background
-   Job ID: job_abc123def456
-
-Check status with: /bluera-knowledge:check-status job_abc123def456
-Or view all jobs: /bluera-knowledge:check-status
-```
-
-## Error Handling
-
-If creation fails (e.g., invalid URL, network error, git not available):
-
-```
-✗ Failed to clone repository: [error message]
-
-Common issues:
-- Check that the git URL is valid and accessible
-- Ensure you have network connectivity
-- Verify git is installed on your system
-- For private repos, check your SSH keys or credentials
-```

package/commands/cancel.md

@@ -1,63 +0,0 @@
----
-description: Cancel a background job
-argument-hint: "[job-id]"
-allowed-tools: ["mcp__bluera-knowledge__execute"]
----
-
-# Cancel Background Job
-
-Cancel a running or pending background job: **$ARGUMENTS**
-
-## Steps
-
-1. Parse the job ID from $ARGUMENTS (required)
-   - If no job ID provided, show error and suggest using /bluera-knowledge:check-status to list active jobs
-
-2. Use mcp__bluera-knowledge__execute tool with command "job:cancel":
-   - args.jobId: The job ID from $ARGUMENTS
-
-3. Display cancellation result:
-
-```
-✓ Job job_abc123def456 cancelled
-  Type: clone
-  Progress: 45% (was indexing)
-
-The job has been stopped and will not continue.
-```
-
-## When to Cancel
-
-Cancel a job when:
-- You accidentally started indexing the wrong repository
-- The operation is taking too long and you want to try a different approach
-- You need to free up system resources
-- You want to stop an operation before it completes
-
-## Important Notes
-
-- Only jobs in 'pending' or 'running' status can be cancelled
-- Completed or failed jobs cannot be cancelled
-- Cancelled jobs are marked with status 'cancelled' and remain in the job list
-- Partial work may be saved (e.g., partially indexed files remain in the database)
-
-## Error Handling
-
-If job cannot be cancelled:
-
-```
-✗ Cannot cancel job job_abc123def456: Job has already completed
-
-Only pending or running jobs can be cancelled.
-```
-
-If job not found:
-
-```
-✗ Job not found: job_abc123def456
-
-Common issues:
-- Check the job ID is correct
-- Use /bluera-knowledge:check-status to see all active jobs
-- Job may have already completed and been cleaned up
-```

package/commands/check-status.md

@@ -1,78 +0,0 @@
----
-description: Check status of background operations
-argument-hint: "[job-id]"
-allowed-tools: ["mcp__bluera-knowledge__execute"]
----
-
-# Check Background Job Status
-
-Check the status of a background operation: **$ARGUMENTS**
-
-## Steps
-
-1. Parse $ARGUMENTS:
-   - If a job ID is provided, use it for specific job status
-   - If no arguments, show all active jobs
-
-2. If job ID provided:
-   - Use mcp__bluera-knowledge__execute tool with command "job:status":
-     - args.jobId: The job ID from $ARGUMENTS
-   - Display current status, progress, and details
-
-3. If no job ID provided:
-   - Use mcp__bluera-knowledge__execute tool with command "jobs":
-     - args.activeOnly: true
-   - Display a table of running/pending jobs
-
-## Display Format
-
-For a specific job:
-
-```
-Job Status: job_abc123def456
-───────────────────────────────────────
-Type:     clone
-Status:   running
-Progress: ███████████░░░░░░░░░ 45%
-Message:  Indexed 562/1,247 files
-Started:  2 minutes ago
-```
-
-For all active jobs:
-
-```
-Active Background Jobs
-───────────────────────────────────────────────────────────────
-| Job ID            | Type  | Status  | Progress | Started  |
-|-------------------|-------|---------|----------|----------|
-| job_abc123def456  | clone | running | 45%      | 2m ago   |
-| job_xyz789ghi012  | index | pending | 0%       | Just now |
-
-Use /bluera-knowledge:check-status <job-id> for details
-```
-
-If no active jobs:
-
-```
-No active background jobs.
-
-Recent completed jobs:
-| Job ID            | Type  | Status    | Completed |
-|-------------------|-------|-----------|-----------|
-| job_old123abc456  | clone | completed | 5m ago    |
-
-Use /bluera-knowledge:cancel <job-id> to cancel a running job
-```
-
-## Error Handling
-
-If job not found:
-
-```
-✗ Job not found: job_abc123def456
-
-Common issues:
-- Check the job ID is correct
-- Job may have been cleaned up (completed jobs are removed after 24 hours)
-- Use /bluera-knowledge:check-status to see all active jobs
-```

package/commands/crawl.md

@@ -1,54 +0,0 @@
----
-description: Crawl web pages with natural language control and add to knowledge store
-argument-hint: "[url] [store-name] [--crawl instruction] [--extract instruction] [--fast]"
-allowed-tools: ["Bash(node ${CLAUDE_PLUGIN_ROOT}/dist/index.js crawl:*)"]
-context: fork
----
-
-Crawling and indexing: $ARGUMENTS
-
-```bash
-node ${CLAUDE_PLUGIN_ROOT}/dist/index.js crawl $ARGUMENTS
-```
-
-The web pages will be crawled with intelligent link selection and optional natural language extraction, then indexed for searching.
-
-**Note:** The web store is auto-created if it doesn't exist. No need to create the store first.
-
-## Usage Examples
-
-**Intelligent crawl strategy:**
-```
-/bluera-knowledge:crawl https://code.claude.com/docs/en/ claude-docs --crawl "all Getting Started pages"
-```
-
-**With extraction:**
-```
-/bluera-knowledge:crawl https://example.com/pricing pricing-store --extract "extract pricing and features"
-```
-
-**Both strategy and extraction:**
-```
-/bluera-knowledge:crawl https://docs.example.com my-docs --crawl "API reference pages" --extract "API endpoints and parameters"
-```
-
-**Simple BFS mode:**
-```
-/bluera-knowledge:crawl https://example.com/docs docs-store --simple
-```
-
-**Fast mode (axios-only, no JavaScript rendering):**
-```
-/bluera-knowledge:crawl https://example.com/docs docs-store --fast --max-pages 20
-```
-
-## Options
-
-- `--crawl <instruction>` - Natural language instruction for which pages to crawl (e.g., "all Getting Started pages")
-- `--extract <instruction>` - Natural language instruction for what content to extract (e.g., "extract API references")
-- `--simple` - Use simple BFS (breadth-first search) mode instead of intelligent crawling
-- `--max-pages <number>` - Maximum number of pages to crawl (default: 50)
-- `--fast` - Use fast axios-only mode instead of headless browser
-  - Default behavior uses headless browser (Playwright via crawl4ai) for JavaScript-rendered sites
-  - Use `--fast` when the target site doesn't use client-side rendering
-  - Much faster than headless mode but may miss content from JavaScript-heavy sites

package/commands/index.md

@@ -1,48 +0,0 @@
----
-description: Re-index a knowledge store
-argument-hint: "[store-name-or-id]"
-allowed-tools: ["mcp__bluera-knowledge__execute"]
----
-
-# Re-index Knowledge Store
-
-Re-index a knowledge store: **$ARGUMENTS**
-
-## Steps
-
-1. Parse the store name or ID from $ARGUMENTS (required)
-
-2. Use mcp__bluera-knowledge__execute tool with command "store:index":
-   - args.store: The store name or ID from $ARGUMENTS
-
-3. Display results showing job ID for background indexing:
-
-```
-✓ Indexing store: react...
-🔄 Indexing started in background
-   Job ID: job_def456ghi789
-
-Check status with: /bluera-knowledge:check-status job_def456ghi789
-Or view all jobs: /bluera-knowledge:check-status
-```
-
-## When to Re-index
-
-Re-index a store when:
-- The source repository has been updated (for repo stores)
-- Files have been added or modified (for file stores)
-- You want to refresh embeddings with an updated model
-- Search results seem out of date
-
-## Error Handling
-
-If indexing fails:
-
-```
-✗ Failed to index store: [error message]
-
-Common issues:
-- Store name or ID not found - use /bluera-knowledge:stores to list available stores
-- Source directory no longer exists (for file stores)
-- Network issues pulling latest changes (for repo stores)
-```

package/commands/remove-store.md

@@ -1,52 +0,0 @@
----
-description: Delete a knowledge store and all associated data
-argument-hint: "[store-name-or-id]"
-allowed-tools: ["mcp__bluera-knowledge__execute"]
----
-
-# Remove Knowledge Store
-
-Delete a knowledge store and all associated data: **$ARGUMENTS**
-
-## Steps
-
-1. Parse the store name or ID from $ARGUMENTS (required)
-   - If no store provided, show error and suggest using /bluera-knowledge:stores to list available stores
-
-2. Use mcp__bluera-knowledge__execute tool with command "store:delete":
-   - args.store: The store name or ID from $ARGUMENTS
-
-3. Display deletion result:
-
-```
-Store "react" deleted successfully.
-
-Removed:
-- Store registry entry
-- LanceDB search index
-- Cloned repository files (for repo stores)
-```
-
-## What Gets Deleted
-
-When you remove a store:
-- **Registry entry** - Store is removed from the list
-- **Search index** - LanceDB vector embeddings are dropped
-- **Cloned files** - For repo stores created from URLs, the cloned repository is deleted
-
-## Warning
-
-This action is **permanent**. The store and all indexed data will be deleted.
-To re-create, you'll need to add and re-index the source again.
-
-## Error Handling
-
-If store not found:
-
-```
-Store not found: nonexistent-store
-
-Available stores:
-- Use /bluera-knowledge:stores to list all stores
-- Check spelling of store name or ID
-```

package/commands/search.md

@@ -1,86 +0,0 @@
----
-description: Search indexed library sources
-argument-hint: "[query] [--stores names] [--limit N] [--mode vector|fts|hybrid] [--detail minimal|contextual|full] [--threshold 0-1] [--min-relevance 0-1]"
-allowed-tools: ["mcp__bluera-knowledge__search"]
----
-
-# Search Knowledge Stores
-
-Search indexed library sources for: **$ARGUMENTS**
-
-## Steps
-
-1. Parse the query from $ARGUMENTS:
-   - Extract the search query (required)
-   - Extract --stores parameter (optional, comma-separated store names)
-   - Extract --limit parameter (optional, default 10)
-   - Extract --mode parameter (optional: vector, fts, hybrid; default hybrid)
-   - Extract --detail parameter (optional: minimal, contextual, full; default contextual)
-   - Extract --threshold parameter (optional, 0-1 range for normalized score filtering)
-   - Extract --min-relevance parameter (optional, 0-1 range for raw cosine similarity filtering)
-
-2. Call mcp__bluera-knowledge__search with:
-   - query: The search query string
-   - stores: Array of store names (if --stores specified)
-   - limit: Number of results (if --limit specified, default 10)
-   - mode: Search mode (if --mode specified, default "hybrid")
-   - detail: Detail level (if --detail specified, default "contextual")
-   - threshold: Minimum normalized score (if --threshold specified)
-   - minRelevance: Minimum raw cosine similarity (if --min-relevance specified)
-   - intent: "find-implementation"
-
-3. Format and display results with rich context:
-
-   ```
-   ## Search Results: "query" (hybrid search)
-
-   **1. [Score: 0.95] [Vector+FTS]**
-   Store: claude-code
-   File: 📄 path/to/file.ts
-   Purpose: → Purpose description here
-   Top Terms: 🔑 (in this chunk): concept1, concept2, concept3
-   Imports: 📦 (in this chunk): package1, package2
-
-   **2. [Score: 0.87] [Vector]**
-   Store: another-store
-   File: 📄 path/to/file.js
-   Purpose: → Another purpose here
-   Top Terms: 🔑 (in this chunk): other-concept
-
-   ---
-   **Found 10 results in 45ms**
-
-   💡 **Next Steps:**
-   - Read file: `Read /path/to/file.ts`
-   - Get full code: `mcp__bluera-knowledge__get_full_context("result-id")`
-   - Refine search: Use keywords above
-   ```
-
-   **Formatting rules:**
-   - Header: `## Search Results: "query" (mode search)` - Extract mode from response (vector/fts/hybrid)
-   - Each result on its own block with blank line between
-   - Result header: `**N. [Score: X.XX] {{method}}**` where method is:
-     - `[Vector+FTS]` if result.rankingMetadata has both vectorRank AND ftsRank (found by both methods)
-     - `[Vector]` if result.rankingMetadata has only vectorRank (semantic match only)
-     - `[Keyword]` if result.rankingMetadata has only ftsRank (keyword match only)
-   - Store: `Store: storeName` (on new line after header)
-   - File: `File: 📄 filename` (strip repoRoot prefix from location)
-   - Purpose: `Purpose: → purpose text` (keep concise)
-   - Top Terms: `Top Terms: 🔑 (in this chunk): ...` (top 5 most frequent words from this chunk, comma-separated)
-   - Imports: `Imports: 📦 (in this chunk): ...` (import statements from this chunk, first 3-4, comma-separated)
-   - Skip Top Terms/Imports lines if arrays are empty
-   - Footer: `**Found {{totalResults}} results in {{timeMs}}ms**` with separator line above
-
-4. For the footer next steps, include:
-   - First result's ID in the get_full_context example
-   - First result's actual file path in the Read example
-   - Use the actual keywords from top results
-
-5. If no results:
-   ```
-   No results found for "query"
-
-   Try:
-   - Broadening your search terms
-   - Checking indexed stores: /bluera-knowledge:stores
-   ```

package/commands/search.sh

@@ -1,63 +0,0 @@
-#!/bin/bash
-# Search command that uses Python formatter for deterministic table output
-
-set -euo pipefail
-
-# Parse arguments
-QUERY=""
-STORES=""
-LIMIT=10
-
-while [[ $# -gt 0 ]]; do
-  case $1 in
-    --stores)
-      STORES="$2"
-      shift 2
-      ;;
-    --limit)
-      LIMIT="$2"
-      shift 2
-      ;;
-    *)
-      # Everything else is the query
-      if [ -z "$QUERY" ]; then
-        QUERY="$1"
-      else
-        QUERY="$QUERY $1"
-      fi
-      shift
-      ;;
-  esac
-done
-
-# Remove quotes from query if present
-QUERY=$(echo "$QUERY" | sed 's/^["'\'']*//;s/["'\'']*$//')
-
-if [ -z "$QUERY" ]; then
-  echo "Error: No search query provided"
-  exit 1
-fi
-
-# Build MCP tool call JSON
-TOOL_INPUT=$(cat <<EOF
-{
-  "query": "$QUERY",
-  "limit": $LIMIT,
-  "detail": "contextual",
-  "intent": "find-implementation"
-}
-EOF
-)
-
-# Call MCP tool (this would need to be done via Claude)
-# For now, output instructions for Claude
-cat <<EOF
-Please call mcp__bluera-knowledge__search with these parameters and pipe the results through the formatter:
-
-Query: $QUERY
-Limit: $LIMIT
-Detail: contextual
-Intent: find-implementation
-
-Then execute: echo '<results_json>' | ${CLAUDE_PLUGIN_ROOT}/hooks/format-search-results.py
-EOF