bluera-knowledge 0.11.6 → 0.11.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bluera-knowledge",
-  "version": "0.11.6",
+  "version": "0.11.8",
   "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,209 @@
+#!/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" 2>&1 | tee -a "$LOG_FILE"; then
+        pass "$name"
+        return 0
+    else
+        fail "$name (exit code: ${PIPESTATUS[0]})"
+        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
+    # Capture output while also showing it on terminal via tee
+    if output=$(eval "$cmd" 2>&1 | tee -a "$LOG_FILE"); then
+        if echo "$output" | grep -q "$expected"; then
+            pass "$name"
+            return 0
+        else
+            fail "$name (output missing: $expected)"
+            return 1
+        fi
+    else
+        fail "$name (command failed)"
+        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/plugin/commands.ts

@@ -4,6 +4,17 @@ import { DependencyUsageAnalyzer } from '../analysis/dependency-usage-analyzer.j
 import { RepoUrlResolver } from '../analysis/repo-url-resolver.js';
 import { createServices } from '../services/index.js';
 
+/**
+ * Options passed from CLI global options to plugin command handlers.
+ */
+export interface CommandOptions {
+  config?: string | undefined;
+  dataDir?: string | undefined;
+  projectRoot?: string | undefined;
+  format?: 'json' | 'table' | 'plain' | undefined;
+  quiet?: boolean | undefined;
+}
+
 export async function handleSearch(args: {
   query: string;
   stores?: string;
@@ -45,13 +56,19 @@ export async function handleSearch(args: {
   }
 }
 
-export async function handleAddRepo(args: {
-  url: string;
-  name?: string;
-  branch?: string;
-}): Promise<void> {
-  // PWD is set by Claude Code to user's project directory
-  const services = await createServices(undefined, undefined, process.env['PWD']);
+export async function handleAddRepo(
+  args: {
+    url: string;
+    name?: string;
+    branch?: string;
+  },
+  options: CommandOptions = {}
+): Promise<void> {
+  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}...`);
@@ -84,9 +101,15 @@ export async function handleAddRepo(args: {
   }
 }
 
-export async function handleAddFolder(args: { path: string; name?: string }): Promise<void> {
-  // PWD is set by Claude Code to user's project directory
-  const services = await createServices(undefined, undefined, process.env['PWD']);
+export async function handleAddFolder(
+  args: { path: string; name?: string },
+  options: CommandOptions = {}
+): Promise<void> {
+  const services = await createServices(
+    options.config,
+    options.dataDir,
+    options.projectRoot ?? process.env['PWD']
+  );
   const { basename } = await import('node:path');
   const storeName = args.name ?? basename(args.path);
 
@@ -142,9 +165,12 @@ export async function handleIndex(args: { store: string }): Promise<void> {
   }
 }
 
-export async function handleStores(): Promise<void> {
-  // PWD is set by Claude Code to user's project directory
-  const services = await createServices(undefined, undefined, process.env['PWD']);
+export async function handleStores(options: CommandOptions = {}): Promise<void> {
+  const services = await createServices(
+    options.config,
+    options.dataDir,
+    options.projectRoot ?? process.env['PWD']
+  );
   const stores = await services.store.list();
 
   if (stores.length === 0) {
@@ -176,14 +202,13 @@ export async function handleStores(): Promise<void> {
   }
 }
 
-export async function handleSuggest(): Promise<void> {
-  // PWD is set by Claude Code to user's project directory
-  const projectRoot = process.env['PWD'] ?? process.cwd();
+export async function handleSuggest(options: CommandOptions = {}): Promise<void> {
+  const projectRoot = options.projectRoot ?? process.env['PWD'] ?? process.cwd();
 
   console.log('Analyzing project dependencies...\n');
 
   // Create analyzer instance
-  const services = await createServices(undefined, undefined, projectRoot);
+  const services = await createServices(options.config, options.dataDir, projectRoot);
   const analyzer = new DependencyUsageAnalyzer();
   const resolver = new RepoUrlResolver();