bluera-knowledge 0.14.0 → 0.14.2

package/.husky/pre-push

@@ -1,39 +0,0 @@
-#!/bin/sh
-set -o pipefail
-
-# Get list of files changed in commits being pushed (compared to remote)
-# If remote doesn't exist yet, compare to HEAD~1
-REMOTE_BRANCH=$(git rev-parse --abbrev-ref --symbolic-full-name @{u} 2>/dev/null || echo "")
-
-if [ -n "$REMOTE_BRANCH" ]; then
-  CHANGED_FILES=$(git diff --name-only "$REMOTE_BRANCH"...HEAD)
-else
-  # No remote tracking branch, check commits that would be pushed
-  CHANGED_FILES=$(git diff --name-only HEAD~1...HEAD 2>/dev/null || git diff --name-only --cached)
-fi
-
-# Categorize changes
-HAS_SRC_CHANGES=$(echo "$CHANGED_FILES" | grep -E '^src/.*\.(ts|js)$' || true)
-HAS_TEST_CHANGES=$(echo "$CHANGED_FILES" | grep -E '\.(test|spec)\.(ts|js)$' || true)
-HAS_CONFIG_CHANGES=$(echo "$CHANGED_FILES" | grep -E '^(package\.json|tsconfig\.json|tsup\.config\.ts|vitest\.config\.ts)' || true)
-
-# Skip coverage if no source or test files changed
-if [ -z "$HAS_SRC_CHANGES" ] && [ -z "$HAS_TEST_CHANGES" ]; then
-  echo "ℹ️  No source/test changes detected, skipping coverage tests"
-  exit 0
-fi
-
-# Run coverage tests - capture exit code before filtering output
-echo "🧪 Running coverage tests..."
-COVERAGE_OUTPUT=$(bun run test:coverage 2>&1)
-COVERAGE_EXIT=$?
-
-# Show filtered summary
-echo "$COVERAGE_OUTPUT" | grep -E '(FAIL|Test Files|passed|Coverage|threshold|ERROR)' | tail -15
-
-if [ $COVERAGE_EXIT -ne 0 ]; then
-  echo "❌ Coverage tests failed"
-  exit 1
-fi
-
-echo "✅ Coverage tests passed"

package/.mcp.json

@@ -1,11 +0,0 @@
-{
-  "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/.prettierrc

@@ -1,9 +0,0 @@
-{
-  "semi": true,
-  "singleQuote": true,
-  "trailingComma": "es5",
-  "tabWidth": 2,
-  "useTabs": false,
-  "printWidth": 100,
-  "endOfLine": "lf"
-}

package/.versionrc.json

@@ -1,24 +0,0 @@
-{
-  "packageFiles": [
-    {
-      "filename": "package.json",
-      "type": "json"
-    }
-  ],
-  "bumpFiles": [
-    {
-      "filename": "package.json",
-      "type": "json"
-    },
-    {
-      "filename": ".claude-plugin/plugin.json",
-      "type": "json"
-    }
-  ],
-  "tagPrefix": "v",
-  "commitAll": true,
-  "sign": false,
-  "scripts": {
-    "postbump": "npm run build"
-  }
-}

package/CLAUDE.md

@@ -1,110 +0,0 @@
-# THIS IS CLAUDE.md - YOUR MEMORY FILE
-
-**STOP. READ THIS FIRST.**
-
-This file is YOUR (Claude's) project memory. It is NOT user documentation. It is NOT a README.
-
-| File | Purpose | Audience |
-|------|---------|----------|
-| **CLAUDE.md** (this file) | Claude Code's memory - scripts, workflows, coding rules | YOU (Claude) |
-| **README.md** | User-facing documentation - features, installation, API | HUMANS (users) |
-
-**When to update this file:** When scripts, CI/CD workflows, build processes, or coding conventions change.
-
-**Keep this file LEAN.** This entire file loads into your context every session. Be concise. No prose. No redundancy. Every line must earn its place.
-
-**CLAUDE.md is hierarchical.** Any subdirectory can have its own CLAUDE.md that auto-loads when you work in that directory. Use this pattern:
-- **Root CLAUDE.md** (this file): Project-wide info - scripts, CI/CD, general conventions
-- **Subdirectory CLAUDE.md**: Directory-specific context scoped to files below it
-- Nest as deep as needed - each level inherits from parents
-
-**Stay DRY with includes.** Use `@path/to/file` syntax to import content instead of duplicating. Not evaluated inside code blocks.
-
----
-
-## Package Manager
-
-**Use `bun`** - not npm or yarn. All scripts should be run with `bun run <script>`.
-
----
-
-## Scripts
-
-**Development:**
-- `bun run build` - Compile TypeScript
-- `bun run test:run` - Run tests once
-- `bun run precommit` - Full validation (lint, typecheck, tests, build)
-- `bun run prerelease` - Full quality checks (format, lint, deadcode, typecheck, coverage, build)
-
-**Versioning (after code changes):**
-- `bun run version:patch` - Runs `prerelease` checks, then bumps patch version
-- `bun run version:minor` - Runs `prerelease` checks, then bumps minor version
-- `bun run version:major` - Runs `prerelease` checks, then bumps major version
-
-Note: Version scripts run full quality checks BEFORE bumping to prevent broken releases.
-
-**Releasing (Fully Automated):**
-1. Bump version: `bun run version:patch` (or minor/major)
-2. Commit: `git commit -am "chore: bump version to X.Y.Z"`
-3. Push: `git push`
-4. **Done!** GitHub Actions handles the rest automatically
-
-**What happens automatically:**
-- `CI` workflow runs (lint, typecheck, tests, build)
-- `Auto Release` workflow waits for CI, then creates & pushes tag
-- `Release` workflow creates GitHub release
-- `Update Marketplace` workflow updates `blueraai/bluera-marketplace`
-
-**Manual release scripts (legacy, not needed):**
-- `bun run release:patch` - Bump + commit + tag + push
-- `bun run release:minor` - Same for minor version
-- `bun run release:major` - Same for major version
-
-## GitHub Actions Workflows
-
-**CI Workflow** (`.github/workflows/ci.yml`)
-- Triggers: Push to main, pull requests, tag pushes
-- Runs: Lint, typecheck, tests, build
-- Required to pass before auto-release creates tag
-
-**Auto Release Workflow** (`.github/workflows/auto-release.yml`) **← NEW!**
-- Triggers: Push to main
-- Waits for: CI workflow to pass
-- Checks: If version in package.json has no matching tag
-- Creates: Tag and pushes it (triggers Release workflow)
-- Uses: `MARKETPLACE_PAT` for checkout/push (GITHUB_TOKEN can't trigger other workflows)
-- **This is what makes releases fully automated**
-- **Important:** Must use PAT, not GITHUB_TOKEN, to allow tag push to trigger Release workflow
-
-**Release Workflow** (`.github/workflows/release.yml`)
-- Triggers: Tag push (v*)
-- Creates: GitHub release with auto-generated notes
-
-**Update Marketplace Workflow** (`.github/workflows/update-marketplace.yml`)
-- Triggers: After Release workflow completes (via `workflow_run`)
-- Waits for: CI workflow success (via `wait-on-check-action`)
-- Updates: `blueraai/bluera-marketplace` plugin version automatically
-- Requires: `MARKETPLACE_PAT` secret (repo-scoped PAT with write access to marketplace repo)
-- Note: Uses `workflow_run` trigger because GitHub prevents `GITHUB_TOKEN` workflows from triggering other workflows
-
-## Distribution Requirements
-
-**`dist/` MUST be committed to git** - This is intentional, not an oversight:
-
-1. **Claude Code plugins are copied to a cache during installation** - no build step runs
-   - Plugins need pre-built files ready to execute immediately
-   - Source: https://code.claude.com/docs/en/discover-plugins
-
-2. **npm publishing also uses committed dist/** - No `files` array in package.json, so npm includes whatever isn't in `.gitignore`
-
-**After any code change:**
-1. Run `bun run build` (or `bun run precommit` which includes build)
-2. Commit both source AND dist/ changes together
-
-## Project Rules
-
-Modular rules are in `.claude/rules/` and auto-load:
-
-- `code-quality.md` - Fail early/fast, strict typing, no fallback code
-- `git.md` - No --no-verify on commits
-- `versioning.md` - Use version:* commands, push to main for releases

package/CONTRIBUTING.md

@@ -1,307 +0,0 @@
-# Contributing to Bluera Knowledge
-
-Contributions welcome! This guide covers development setup, testing, and the release process.
-
-## Setup
-
-```bash
-git clone https://github.com/blueraai/bluera-knowledge.git
-cd bluera-knowledge
-bun install
-bun run build
-bun test
-```
-
-> **Note:** This project uses [Bun](https://bun.sh) for development. Install it via `curl -fsSL https://bun.sh/install | bash`
-
----
-
-## Claude Code Settings (Recommended)
-
-For the best development experience with Claude Code, copy the example settings file:
-
-```bash
-cp .claude/settings.local.json.example .claude/settings.local.json
-```
-
-**This provides:**
-- **Smart validation** - Automatically runs lint/typecheck after editing code (file-type aware)
-- **No permission prompts** - Pre-approves common commands (lint, typecheck, precommit)
-- **Desktop notifications** - macOS notifications when Claude needs your input
-- **Plugin auto-enabled** - Automatically enables the bluera-knowledge plugin
-- **Faster workflow** - Catch issues immediately without manual validation
-
-The validation is intelligent—it only runs checks for TypeScript/JavaScript files, skipping docs/config to save time.
-
-> **Note:** The `.claude/settings.local.json` file is gitignored (local to your machine). The example file is checked in for reference.
-
----
-
-## Dogfooding
-
-Develop this plugin while using it with Claude Code:
-
-```bash
-claude --plugin-dir /path/to/bluera-knowledge
-```
-
-This loads the plugin directly from source. Changes take effect on Claude Code restart (no reinstall needed).
-
-| What to test | Approach |
-|--------------|----------|
-| **Commands** (`/search`, `/add-repo`) | `--plugin-dir` (changes need restart) |
-| **Hooks** (job status, dependencies) | `--plugin-dir` (changes need restart) |
-| **MCP tools** (compiled) | `--plugin-dir` (run `bun run build` first) |
-| **MCP tools** (live TypeScript) | `~/.claude.json` dev server (see below) |
-
----
-
-## MCP Server Development
-
-**Production mode** (`mcp.plugin.json`):
-- Uses `${CLAUDE_PLUGIN_ROOT}/dist/mcp/server.js` (compiled)
-- Distributed with plugin, no extra setup needed
-
-**Development mode** (live TypeScript):
-
-For instant feedback when editing MCP server code, add a dev server to `~/.claude.json`:
-
-```json
-{
-  "mcpServers": {
-    "bluera-knowledge-dev": {
-      "command": "npx",
-      "args": ["tsx", "/path/to/bluera-knowledge/src/mcp/server.ts"],
-      "env": {
-        "PWD": "${PWD}",
-        "DATA_DIR": "${PWD}/.bluera/bluera-knowledge/data",
-        "CONFIG_PATH": "${PWD}/.bluera/bluera-knowledge/config.json"
-      }
-    }
-  }
-}
-```
-
-This creates a separate `bluera-knowledge-dev` MCP server that runs source TypeScript directly via `tsx`—no rebuild needed for MCP changes.
-
----
-
-## Commands
-
-### Development
-
-| Command | Description | When to Use |
-|---------|-------------|-------------|
-| `bun run build` | Compile TypeScript to dist/ | Before testing CLI, after code changes |
-| `bun run dev` | Watch mode compilation | During active development |
-| `bun start` | Run the CLI | Execute CLI commands directly |
-
-### Testing
-
-| Command | Description | When to Use |
-|---------|-------------|-------------|
-| `bun test` | Run tests in watch mode | During TDD/active development |
-| `bun run test:run` | Run tests once | Quick verification |
-| `bun run test:coverage` | Run tests with coverage | Before committing, CI checks |
-
-### Validation
-
-| Command | Description | When to Use |
-|---------|-------------|-------------|
-| `bun run lint` | Run ESLint (quiet by default) | Check code style issues |
-| `bun run typecheck` | Run TypeScript type checking (quiet by default) | Verify type safety |
-| `bun run precommit` | Smart validation (file-type aware) | Runs only relevant checks based on changed files |
-| `bun run prepush` | Smart coverage (skips for docs/config) | Runs coverage only when src/tests changed |
-
-### Verbose Variants
-
-| Command | Description |
-|---------|-------------|
-| `bun run lint:verbose` | ESLint (full output) |
-| `bun run typecheck:verbose` | Type check (full output) |
-| `bun run test:changed:verbose` | Test changed files (full output) |
-| `bun run test:coverage:verbose` | Coverage (full output) |
-| `bun run build:verbose` | Build (full output) |
-
-### GitHub Actions
-
-| Command | Description |
-|---------|-------------|
-| `bun run gh:status` | List recent GitHub Actions runs |
-| `bun run gh:watch` | Watch latest workflow (quiet, shows result + failures) |
-| `bun run gh:watch:verbose` | Watch with live status updates |
-| `bun run gh:releases` | List recent GitHub releases |
-
----
-
-## Automatic Build & Dist Commit
-
-The `dist/` directory **must be committed** because Claude Code plugins are installed by copying files—there's no build step during installation.
-
-**Good news: This is fully automatic!**
-
-1. **On every commit**, the pre-commit hook intelligently validates based on file types
-2. **If source/config changed**, it runs build and automatically stages `dist/` via `git add dist/`
-3. **You never need to manually build or stage dist**—just commit your source changes
-
-**For live rebuilding during development:**
-
-```bash
-bun run dev  # Watches for changes and rebuilds instantly
-```
-
-This is useful when testing CLI commands locally, but not required for committing—the hook handles everything.
-
----
-
-## Versioning
-
-| Command | Description | When to Use |
-|---------|-------------|-------------|
-| `bun run version:patch` | Run quality checks, then bump patch version (0.0.x) | Bug fixes, minor updates |
-| `bun run version:minor` | Run quality checks, then bump minor version (0.x.0) | New features, backwards compatible |
-| `bun run version:major` | Run quality checks, then bump major version (x.0.0) | Breaking changes |
-
-Note: Version commands run full quality checks (format, lint, deadcode, typecheck, coverage, build) BEFORE bumping to catch issues early.
-
----
-
-## Releasing
-
-**Workflow (Fully Automated):**
-
-1. Make changes and commit
-2. Bump version: `bun run version:patch` (runs quality checks first, then updates package.json, plugin.json, README, CHANGELOG)
-3. Commit version bump: `git commit -am "chore: bump version to X.Y.Z"`
-4. Push to main: `git push`
-5. **GitHub Actions automatically:**
-   - Runs CI (lint, typecheck, tests, build)
-   - Creates release tag when CI passes
-   - Creates GitHub release
-   - Updates marketplace
-
-> **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.
-
----
-
-## Plugin Self-Test
-
-Test all plugin functionality from within Claude Code:
-
-```
-/test-plugin
-```
-
-This command runs comprehensive tests covering:
-- **MCP Tools**: execute (help, stores, create, info, index), search, get_full_context
-- **Slash Commands**: /stores, /search, /suggest
-- **Cleanup**: Store deletion, artifact removal, verification
-
-The test creates temporary content, exercises all features, and cleans up automatically. Use this to verify the plugin is working correctly after installation or updates.
-
----
-
-## Testing Locally
-
-### Option 1: Development MCP Server (Recommended)
-
-Use the local development MCP server (see "MCP Server Development" section above) which runs your source code directly via `tsx`:
-
-1. Set up dev MCP server in `~/.claude.json`
-2. Test your changes—MCP server updates automatically as you edit code
-
-### Option 2: Test Plugin from Working Directory
-
-Load the plugin directly from your development directory:
-
-```bash
-cd /path/to/bluera-knowledge
-claude --plugin-dir .
-```
-
-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
-
-```bash
-# Build and link
-cd /path/to/bluera-knowledge
-bun run build
-bun link
-
-# Now 'bluera-knowledge' command is available globally
-cd ~/your-project
-bluera-knowledge search "test query" my-store
-```
-
-**For testing as an installed plugin:**
-This requires publishing a new version to the marketplace.
-
----
-
-## Project Structure
-
-```
-.claude-plugin/
-└── plugin.json          # Plugin metadata (references mcp.plugin.json)
-
-mcp.plugin.json          # MCP server configuration (plugin-scoped)
-commands/                # Slash commands (auto-discovered)
-skills/                  # Agent Skills (auto-discovered)
-├── knowledge-search/    # How to access dependency sources
-│   └── SKILL.md
-├── when-to-query/       # When to query BK vs project files
-│   └── SKILL.md
-├── advanced-workflows/  # Multi-tool orchestration patterns
-│   └── SKILL.md
-├── search-optimization/ # Search parameter optimization
-│   └── SKILL.md
-└── store-lifecycle/     # Store management best practices
-    └── SKILL.md
-dist/                    # Built MCP server (committed for distribution)
-
-src/
-├── analysis/            # Dependency analysis & URL resolution
-├── crawl/               # Web crawling with Python bridge
-├── services/            # Index, store, and search services
-├── mcp/                 # MCP server source
-└── cli/                 # CLI entry point
-
-tests/
-├── integration/         # Integration tests
-└── fixtures/            # Test infrastructure
-```
-
----
-
-## Pull Request Process
-
-1. Fork the repository
-2. Create a feature branch
-3. Add tests for new functionality
-4. Run `bun run precommit` to validate
-5. Submit a pull request
-
-Please ensure:
-- All tests pass
-- Code follows existing style
-- Commit messages are descriptive
-- Documentation is updated if needed

package/NOTICE

@@ -1,47 +0,0 @@
-Bluera Knowledge
-Copyright (c) 2024-2025 Bluera Inc
-
-This product includes software developed by third parties:
-
----
-
-Crawl4AI
-https://github.com/unclecode/crawl4ai
-Licensed under Apache License 2.0
-
-This product includes software developed by UncleCode
-(https://x.com/unclecode) as part of the Crawl4AI project
-(https://github.com/unclecode/crawl4ai).
-
----
-
-Playwright
-https://github.com/microsoft/playwright-python
-Licensed under Apache License 2.0
-Copyright (c) Microsoft Corporation
-
----
-
-sharp / libvips
-https://github.com/lovell/sharp
-https://github.com/libvips/libvips
-sharp is licensed under Apache License 2.0
-libvips is licensed under LGPL-3.0-or-later
-
----
-
-@huggingface/transformers
-https://github.com/huggingface/transformers.js
-Licensed under Apache License 2.0
-Copyright (c) Hugging Face
-
----
-
-LanceDB
-https://github.com/lancedb/lancedb
-Licensed under Apache License 2.0
-Copyright (c) LanceDB Inc
-
----
-
-For complete license texts, see the respective project repositories.

package/SECURITY.md

@@ -1,65 +0,0 @@
-# Security
-
-## Reporting Vulnerabilities
-
-If you discover a security vulnerability, please report it by opening a GitHub issue or contacting the maintainers directly.
-
-## Security Configuration
-
-### HTTP Server Binding
-
-By default, the HTTP server binds to `127.0.0.1:3847` (localhost only). This means:
-
-- The server is only accessible from the local machine
-- External network access is blocked by default
-
-To expose the server to the network (not recommended for untrusted environments):
-
-```bash
-bluera-knowledge serve --host 0.0.0.0 --port 3847
-```
-
-**Warning:** When binding to `0.0.0.0`, the API is accessible to any device on the network. Only use this in trusted environments.
-
-### CORS Configuration
-
-The HTTP API allows requests from any origin by default. This is appropriate for local development but should be restricted in production deployments.
-
-### Setup Command
-
-The `setup repos` command clones repositories from a hardcoded list of trusted Anthropic/Claude repositories. The URLs are defined in `src/defaults/repos.ts` and are not user-configurable.
-
-## Security Practices
-
-### Input Validation
-
-- All MCP tool inputs are validated using Zod schemas
-- HTTP API endpoints validate request bodies before processing
-- Store IDs use branded types with regex validation (`/^[a-zA-Z0-9_-]+$/`)
-
-### Subprocess Execution
-
-- Git operations use `spawn()` with argument arrays (not shell strings)
-- Python bridge uses JSON-RPC over stdin/stdout
-- No shell command string interpolation
-
-### Path Handling
-
-- File store paths are normalized to absolute paths using `path.resolve()`
-- Directory existence is validated before creating file stores
-- Symlinks are resolved where security-relevant
-
-### External Communications
-
-- All external API calls (npm, PyPI, crates.io, Go proxy) use HTTPS
-- No API keys or credentials are stored in the codebase
-- Claude CLI integration uses the CLI's own authentication
-
-## Dependencies
-
-Run regular security audits on dependencies:
-
-```bash
-npm audit
-pip-audit  # For Python dependencies
-```