bluera-knowledge 0.11.5 → 0.11.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bluera-knowledge",
-  "version": "0.11.5",
+  "version": "0.11.7",
   "description": "CLI tool for managing knowledge stores with semantic search",
   "type": "module",
   "bin": {
@@ -38,7 +38,8 @@
     "version:patch": "bun run prerelease && commit-and-tag-version --release-as patch --skip.commit --skip.tag",
     "release:patch": "commit-and-tag-version --release-as patch && git push --follow-tags",
     "release:minor": "commit-and-tag-version --release-as minor && git push --follow-tags",
-    "release:major": "commit-and-tag-version --release-as major && git push --follow-tags"
+    "release:major": "commit-and-tag-version --release-as major && git push --follow-tags",
+    "validate:npm": "./scripts/validate-npm-release.sh"
   },
   "keywords": [
     "knowledge",

package/scripts/validate-npm-release.sh

@@ -0,0 +1,211 @@
+#!/usr/bin/env bash
+#
+# validate-npm-release.sh
+#
+# Post-release validation script for bluera-knowledge npm module.
+# Installs the latest version from npm and exercises all CLI commands.
+#
+# Usage:
+#   ./scripts/validate-npm-release.sh
+#
+# Output:
+#   Logs written to: <repo>/logs/validation/npm-validation-YYYYMMDD-HHMMSS.log
+#   Exit code: 0 if all tests pass, 1 if any fail
+#
+
+set -euo pipefail
+
+# Configuration
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+RESULTS_DIR="$REPO_ROOT/logs/validation"
+TIMESTAMP="$(date +%Y%m%d-%H%M%S)"
+LOG_FILE="$RESULTS_DIR/npm-validation-$TIMESTAMP.log"
+
+# Test configuration
+TEST_STORE="npm-validation-test-$TIMESTAMP"
+TEST_FOLDER="$(mktemp -d)"
+DATA_DIR="$(mktemp -d)"
+
+# Counters
+TESTS_RUN=0
+TESTS_PASSED=0
+TESTS_FAILED=0
+
+# Setup
+mkdir -p "$RESULTS_DIR"
+echo "Test content for validation" > "$TEST_FOLDER/test.txt"
+echo "Another test file" > "$TEST_FOLDER/test2.md"
+
+# Logging functions
+log() {
+    echo "[$(date +%H:%M:%S)] $*" | tee -a "$LOG_FILE"
+}
+
+log_header() {
+    echo "" | tee -a "$LOG_FILE"
+    echo "========================================" | tee -a "$LOG_FILE"
+    echo "$*" | tee -a "$LOG_FILE"
+    echo "========================================" | tee -a "$LOG_FILE"
+}
+
+pass() {
+    TESTS_RUN=$((TESTS_RUN + 1))
+    TESTS_PASSED=$((TESTS_PASSED + 1))
+    log "✓ PASS: $*"
+}
+
+fail() {
+    TESTS_RUN=$((TESTS_RUN + 1))
+    TESTS_FAILED=$((TESTS_FAILED + 1))
+    log "✗ FAIL: $*"
+}
+
+# Run a command and check exit code
+run_test() {
+    local name="$1"
+    shift
+    local cmd="$*"
+
+    log "Running: $cmd"
+    if eval "$cmd" >> "$LOG_FILE" 2>&1; then
+        pass "$name"
+        return 0
+    else
+        fail "$name (exit code: $?)"
+        return 1
+    fi
+}
+
+# Run a command and check output contains expected string
+run_test_contains() {
+    local name="$1"
+    local expected="$2"
+    shift 2
+    local cmd="$*"
+
+    log "Running: $cmd"
+    local output
+    if output=$(eval "$cmd" 2>&1); then
+        if echo "$output" | grep -q "$expected"; then
+            pass "$name"
+            echo "$output" >> "$LOG_FILE"
+            return 0
+        else
+            fail "$name (output missing: $expected)"
+            echo "$output" >> "$LOG_FILE"
+            return 1
+        fi
+    else
+        fail "$name (command failed)"
+        echo "$output" >> "$LOG_FILE"
+        return 1
+    fi
+}
+
+# Cleanup function
+cleanup() {
+    log_header "Cleanup"
+
+    # Delete test store if it exists
+    log "Deleting test store: $TEST_STORE"
+    bluera-knowledge store delete "$TEST_STORE" --force -d "$DATA_DIR" 2>/dev/null || true
+
+    # Remove test folder
+    log "Removing test folder: $TEST_FOLDER"
+    rm -rf "$TEST_FOLDER"
+
+    # Remove data directory
+    log "Removing data directory: $DATA_DIR"
+    rm -rf "$DATA_DIR"
+
+    log "Cleanup complete"
+}
+
+# Set trap for cleanup on exit
+trap cleanup EXIT
+
+# Start validation
+log_header "NPM Module Validation - $TIMESTAMP"
+log "Log file: $LOG_FILE"
+log "Test store: $TEST_STORE"
+log "Test folder: $TEST_FOLDER"
+log "Data directory: $DATA_DIR"
+
+# Install latest from npm
+log_header "Installing Latest from npm"
+log "Installing bluera-knowledge@latest globally..."
+if npm install -g bluera-knowledge@latest >> "$LOG_FILE" 2>&1; then
+    pass "npm install -g bluera-knowledge@latest"
+else
+    fail "npm install -g bluera-knowledge@latest"
+    log "ERROR: Failed to install package. Aborting."
+    exit 1
+fi
+
+# Verify installation
+log_header "Verifying Installation"
+
+run_test_contains "bluera-knowledge --version" "0." "bluera-knowledge --version"
+
+run_test_contains "bluera-knowledge --help" "CLI tool for managing knowledge stores" "bluera-knowledge --help"
+
+# Test stores list (should work even if empty)
+log_header "Testing Store Operations"
+
+run_test "bluera-knowledge stores (initial list)" "bluera-knowledge stores -d '$DATA_DIR' -f json"
+
+# Create a store via add-folder
+log_header "Testing add-folder"
+
+run_test "bluera-knowledge add-folder" "bluera-knowledge add-folder '$TEST_FOLDER' --name '$TEST_STORE' -d '$DATA_DIR'"
+
+# Verify store was created
+run_test_contains "Store appears in list" "$TEST_STORE" "bluera-knowledge stores -d '$DATA_DIR'"
+
+# Test store info
+log_header "Testing store info"
+
+run_test_contains "bluera-knowledge store info" "$TEST_STORE" "bluera-knowledge store info '$TEST_STORE' -d '$DATA_DIR'"
+
+# Test search (may return no results, but should not error)
+log_header "Testing search"
+
+run_test "bluera-knowledge search" "bluera-knowledge search 'test content' --store '$TEST_STORE' -d '$DATA_DIR' -f json"
+
+# Test index command (re-index)
+log_header "Testing index"
+
+run_test "bluera-knowledge index" "bluera-knowledge index '$TEST_STORE' -d '$DATA_DIR'"
+
+# Test search again after re-indexing
+run_test "bluera-knowledge search (after reindex)" "bluera-knowledge search 'validation' --store '$TEST_STORE' -d '$DATA_DIR' -f json"
+
+# Test store delete
+log_header "Testing store delete"
+
+run_test "bluera-knowledge store delete" "bluera-knowledge store delete '$TEST_STORE' --force -d '$DATA_DIR'"
+
+# Verify store was deleted
+log "Verifying store was deleted..."
+if bluera-knowledge stores -d "$DATA_DIR" -f json 2>&1 | grep -q "$TEST_STORE"; then
+    fail "Store still exists after delete"
+else
+    pass "Store successfully deleted"
+fi
+
+# Summary
+log_header "Validation Summary"
+log "Tests run:    $TESTS_RUN"
+log "Tests passed: $TESTS_PASSED"
+log "Tests failed: $TESTS_FAILED"
+log ""
+log "Log file: $LOG_FILE"
+
+if [ "$TESTS_FAILED" -gt 0 ]; then
+    log "VALIDATION FAILED"
+    exit 1
+else
+    log "VALIDATION PASSED"
+    exit 0
+fi

package/src/cli/commands/plugin-api.test.ts

@@ -38,16 +38,25 @@ describe('Plugin API Commands - Execution Tests', () => {
   });
 
   describe('add-repo command', () => {
-    it('calls handleAddRepo with url', async () => {
+    const expectedGlobalOpts = {
+      config: undefined,
+      dataDir: '/tmp/test',
+      projectRoot: undefined,
+      format: undefined,
+      quiet: false,
+    };
+
+    it('calls handleAddRepo with url and global options', async () => {
       const { handleAddRepo } = await import('../../plugin/commands.js');
 
       const command = createAddRepoCommand(getOptions);
       const actionHandler = (command as any)._actionHandler;
       await actionHandler(['https://github.com/user/repo.git']);
 
-      expect(handleAddRepo).toHaveBeenCalledWith({
-        url: 'https://github.com/user/repo.git',
-      });
+      expect(handleAddRepo).toHaveBeenCalledWith(
+        { url: 'https://github.com/user/repo.git' },
+        expectedGlobalOpts
+      );
     });
 
     it('calls handleAddRepo with url and name option', async () => {
@@ -58,10 +67,10 @@ describe('Plugin API Commands - Execution Tests', () => {
       command.parseOptions(['--name', 'my-repo']);
       await actionHandler(['https://github.com/user/repo.git']);
 
-      expect(handleAddRepo).toHaveBeenCalledWith({
-        url: 'https://github.com/user/repo.git',
-        name: 'my-repo',
-      });
+      expect(handleAddRepo).toHaveBeenCalledWith(
+        { url: 'https://github.com/user/repo.git', name: 'my-repo' },
+        expectedGlobalOpts
+      );
     });
 
     it('calls handleAddRepo with url and branch option', async () => {
@@ -72,10 +81,10 @@ describe('Plugin API Commands - Execution Tests', () => {
       command.parseOptions(['--branch', 'develop']);
       await actionHandler(['https://github.com/user/repo.git']);
 
-      expect(handleAddRepo).toHaveBeenCalledWith({
-        url: 'https://github.com/user/repo.git',
-        branch: 'develop',
-      });
+      expect(handleAddRepo).toHaveBeenCalledWith(
+        { url: 'https://github.com/user/repo.git', branch: 'develop' },
+        expectedGlobalOpts
+      );
     });
 
     it('calls handleAddRepo with all options', async () => {
@@ -86,11 +95,10 @@ describe('Plugin API Commands - Execution Tests', () => {
       command.parseOptions(['--name', 'custom-name', '--branch', 'main']);
       await actionHandler(['https://github.com/user/repo.git']);
 
-      expect(handleAddRepo).toHaveBeenCalledWith({
-        url: 'https://github.com/user/repo.git',
-        name: 'custom-name',
-        branch: 'main',
-      });
+      expect(handleAddRepo).toHaveBeenCalledWith(
+        { url: 'https://github.com/user/repo.git', name: 'custom-name', branch: 'main' },
+        expectedGlobalOpts
+      );
     });
 
     it('handles errors from handleAddRepo', async () => {
@@ -108,16 +116,22 @@ describe('Plugin API Commands - Execution Tests', () => {
   });
 
   describe('add-folder command', () => {
-    it('calls handleAddFolder with path', async () => {
+    const expectedGlobalOpts = {
+      config: undefined,
+      dataDir: '/tmp/test',
+      projectRoot: undefined,
+      format: undefined,
+      quiet: false,
+    };
+
+    it('calls handleAddFolder with path and global options', async () => {
       const { handleAddFolder } = await import('../../plugin/commands.js');
 
       const command = createAddFolderCommand(getOptions);
       const actionHandler = (command as any)._actionHandler;
       await actionHandler(['/path/to/folder']);
 
-      expect(handleAddFolder).toHaveBeenCalledWith({
-        path: '/path/to/folder',
-      });
+      expect(handleAddFolder).toHaveBeenCalledWith({ path: '/path/to/folder' }, expectedGlobalOpts);
     });
 
     it('calls handleAddFolder with path and name option', async () => {
@@ -128,10 +142,10 @@ describe('Plugin API Commands - Execution Tests', () => {
       command.parseOptions(['--name', 'my-folder']);
       await actionHandler(['/path/to/folder']);
 
-      expect(handleAddFolder).toHaveBeenCalledWith({
-        path: '/path/to/folder',
-        name: 'my-folder',
-      });
+      expect(handleAddFolder).toHaveBeenCalledWith(
+        { path: '/path/to/folder', name: 'my-folder' },
+        expectedGlobalOpts
+      );
     });
 
     it('handles relative paths', async () => {
@@ -141,9 +155,7 @@ describe('Plugin API Commands - Execution Tests', () => {
       const actionHandler = (command as any)._actionHandler;
       await actionHandler(['./relative/path']);
 
-      expect(handleAddFolder).toHaveBeenCalledWith({
-        path: './relative/path',
-      });
+      expect(handleAddFolder).toHaveBeenCalledWith({ path: './relative/path' }, expectedGlobalOpts);
     });
 
     it('handles paths with spaces', async () => {
@@ -153,9 +165,10 @@ describe('Plugin API Commands - Execution Tests', () => {
       const actionHandler = (command as any)._actionHandler;
       await actionHandler(['/path/with spaces/folder']);
 
-      expect(handleAddFolder).toHaveBeenCalledWith({
-        path: '/path/with spaces/folder',
-      });
+      expect(handleAddFolder).toHaveBeenCalledWith(
+        { path: '/path/with spaces/folder' },
+        expectedGlobalOpts
+      );
     });
 
     it('handles errors from handleAddFolder', async () => {
@@ -171,14 +184,20 @@ describe('Plugin API Commands - Execution Tests', () => {
   });
 
   describe('stores command', () => {
-    it('calls handleStores with no arguments', async () => {
+    it('calls handleStores with global options', async () => {
       const { handleStores } = await import('../../plugin/commands.js');
 
       const command = createStoresCommand(getOptions);
       const actionHandler = (command as any)._actionHandler;
       await actionHandler([]);
 
-      expect(handleStores).toHaveBeenCalledWith();
+      expect(handleStores).toHaveBeenCalledWith({
+        config: undefined,
+        dataDir: '/tmp/test',
+        projectRoot: undefined,
+        format: undefined,
+        quiet: false,
+      });
     });
 
     it('calls handleStores exactly once', async () => {
@@ -204,14 +223,20 @@ describe('Plugin API Commands - Execution Tests', () => {
   });
 
   describe('suggest command', () => {
-    it('calls handleSuggest with no arguments', async () => {
+    it('calls handleSuggest with global options', async () => {
       const { handleSuggest } = await import('../../plugin/commands.js');
 
       const command = createSuggestCommand(getOptions);
       const actionHandler = (command as any)._actionHandler;
       await actionHandler([]);
 
-      expect(handleSuggest).toHaveBeenCalledWith();
+      expect(handleSuggest).toHaveBeenCalledWith({
+        config: undefined,
+        dataDir: '/tmp/test',
+        projectRoot: undefined,
+        format: undefined,
+        quiet: false,
+      });
     });
 
     it('calls handleSuggest exactly once', async () => {
@@ -283,28 +308,65 @@ describe('Plugin API Commands - Execution Tests', () => {
   });
 
   describe('global options handling', () => {
-    it('add-repo ignores global options', async () => {
+    it('add-repo passes global options', async () => {
       const { handleAddRepo } = await import('../../plugin/commands.js');
 
-      // Global options should not be passed to handlers
       const command = createAddRepoCommand(getOptions);
       const actionHandler = (command as any)._actionHandler;
       await actionHandler(['https://github.com/user/repo.git']);
 
-      expect(handleAddRepo).toHaveBeenCalledWith({
-        url: 'https://github.com/user/repo.git',
-      });
+      expect(handleAddRepo).toHaveBeenCalledWith(
+        { url: 'https://github.com/user/repo.git' },
+        {
+          config: undefined,
+          dataDir: '/tmp/test',
+          projectRoot: undefined,
+          format: undefined,
+          quiet: false,
+        }
+      );
     });
 
-    it('add-folder ignores global options', async () => {
+    it('add-folder passes global options', async () => {
       const { handleAddFolder } = await import('../../plugin/commands.js');
 
       const command = createAddFolderCommand(getOptions);
       const actionHandler = (command as any)._actionHandler;
       await actionHandler(['/path']);
 
-      expect(handleAddFolder).toHaveBeenCalledWith({
-        path: '/path',
+      expect(handleAddFolder).toHaveBeenCalledWith(
+        { path: '/path' },
+        {
+          config: undefined,
+          dataDir: '/tmp/test',
+          projectRoot: undefined,
+          format: undefined,
+          quiet: false,
+        }
+      );
+    });
+
+    it('stores passes dataDir from global options', async () => {
+      const { handleStores } = await import('../../plugin/commands.js');
+
+      const customGetOptions = (): GlobalOptions => ({
+        config: '/custom/config.json',
+        dataDir: '/custom/data',
+        quiet: true,
+        format: 'json',
+        projectRoot: '/my/project',
+      });
+
+      const command = createStoresCommand(customGetOptions);
+      const actionHandler = (command as any)._actionHandler;
+      await actionHandler([]);
+
+      expect(handleStores).toHaveBeenCalledWith({
+        config: '/custom/config.json',
+        dataDir: '/custom/data',
+        projectRoot: '/my/project',
+        format: 'json',
+        quiet: true,
       });
     });
   });

package/src/cli/commands/plugin-api.ts

@@ -12,37 +12,71 @@ import type { GlobalOptions } from '../program.js';
  * These commands provide a simpler interface that matches the plugin commands.
  */
 
-export function createAddRepoCommand(_getOptions: () => GlobalOptions): Command {
+export function createAddRepoCommand(getOptions: () => GlobalOptions): Command {
   return new Command('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: string, options: { name?: string; branch?: string }) => {
-      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,
+        }
+      );
     });
 }
 
-export function createAddFolderCommand(_getOptions: () => GlobalOptions): Command {
+export function createAddFolderCommand(getOptions: () => GlobalOptions): Command {
   return new Command('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: string, options: { name?: string }) => {
-      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,
+        }
+      );
     });
 }
 
-export function createStoresCommand(_getOptions: () => GlobalOptions): Command {
+export function createStoresCommand(getOptions: () => GlobalOptions): Command {
   return new Command('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,
+    });
   });
 }
 
-export function createSuggestCommand(_getOptions: () => GlobalOptions): Command {
+export function createSuggestCommand(getOptions: () => GlobalOptions): Command {
   return new Command('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,
+      });
     });
 }

package/src/mcp/plugin-mcp-config.test.ts

@@ -0,0 +1,64 @@
+import { describe, it, expect } from 'vitest';
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+
+/**
+ * Tests to verify plugin.json is correctly configured for MCP server.
+ * The MCP server must work when the plugin is installed via marketplace.
+ *
+ * Key requirements:
+ * - Must use ${CLAUDE_PLUGIN_ROOT} for server path (resolves to plugin cache)
+ * - Must set PROJECT_ROOT env var (required by server fail-fast check)
+ * - Must NOT use relative paths (would resolve to user's project, not plugin)
+ */
+describe('Plugin MCP Configuration (.claude-plugin/plugin.json)', () => {
+  const configPath = join(process.cwd(), '.claude-plugin/plugin.json');
+  const config = JSON.parse(readFileSync(configPath, 'utf-8'));
+
+  it('has mcpServers configuration inline', () => {
+    expect(config).toHaveProperty('mcpServers');
+    expect(config.mcpServers).toHaveProperty('bluera-knowledge');
+  });
+
+  it('uses ${CLAUDE_PLUGIN_ROOT} for server path (required for plugin mode)', () => {
+    const serverConfig = config.mcpServers['bluera-knowledge'];
+    const argsString = JSON.stringify(serverConfig.args);
+
+    // CLAUDE_PLUGIN_ROOT is set by Claude Code when plugin is installed
+    // This ensures the path resolves to the plugin cache, not user's project
+    expect(argsString).toContain('${CLAUDE_PLUGIN_ROOT}');
+    expect(argsString).toContain('dist/mcp/server.js');
+  });
+
+  it('does NOT use relative paths (would break in plugin mode)', () => {
+    const serverConfig = config.mcpServers['bluera-knowledge'];
+    const argsString = JSON.stringify(serverConfig.args);
+
+    // Relative paths like ./dist would resolve to user's project directory
+    // which doesn't have the plugin's dist folder
+    expect(argsString).not.toMatch(/"\.\//);
+  });
+
+  it('sets PROJECT_ROOT environment variable (required by fail-fast server)', () => {
+    const serverConfig = config.mcpServers['bluera-knowledge'];
+
+    // PROJECT_ROOT is required since b404cd6 (fail-fast change)
+    expect(serverConfig.env).toHaveProperty('PROJECT_ROOT');
+    expect(serverConfig.env['PROJECT_ROOT']).toBe('${PWD}');
+  });
+});
+
+/**
+ * Tests to ensure .mcp.json is NOT distributed with the plugin.
+ * .mcp.json at project root causes confusion between plugin and project config.
+ */
+describe('No conflicting .mcp.json in repo', () => {
+  it('does NOT have .mcp.json in repo root (prevents config confusion)', () => {
+    const mcpJsonPath = join(process.cwd(), '.mcp.json');
+
+    // .mcp.json should NOT exist in the repo
+    // - For plugin mode: use mcpServers in plugin.json
+    // - For development: use ~/.claude.json per README
+    expect(existsSync(mcpJsonPath)).toBe(false);
+  });
+});