bluera-knowledge 0.9.21

package/.claude/commands/commit.md

@@ -0,0 +1,37 @@
+---
+description: Create atomic commits grouped by logical features with README.md and CLAUDE.md awareness.
+allowed-tools: Bash(git:*), Read, Glob, Grep
+---
+
+# Commit
+
+Create atomic, well-organized commits. See @.claude/skills/atomic-commits/SKILL.md for documentation check criteria.
+
+## Context
+
+!`git status && echo "---STAGED---" && git diff --cached --stat && echo "---UNSTAGED---" && git diff --stat && echo "---UNTRACKED---" && git ls-files --others --exclude-standard && echo "---HISTORY---" && git log --oneline -10`
+
+## Workflow
+
+1. **Analyze**: Run `git diff HEAD` to see all changes
+2. **Documentation Check**: Check if README.md or CLAUDE.md need updates (see skill)
+3. **Group**: Identify logical features (see skill for grouping rules)
+4. **Commit each group**:
+   ```bash
+   git add <files>
+   bun run precommit
+   git commit -m "<type>(<scope>): <description>"
+   ```
+5. **Handle untracked**: Categorize as commit/ignore/intentional
+6. **Report**: Show commits created and final `git status --short`
+
+## Validation
+
+- **Doc-only changes**: Skips all validation (instant)
+- **Code changes**: Runs lint + typecheck + tests + build
+
+## Safety
+
+- Never force push
+- Never amend commits from other sessions
+- Ask if unsure about grouping

package/.claude/hooks/post-edit-check.sh

@@ -0,0 +1,41 @@
+#!/bin/bash
+# Smart post-edit validation hook
+# Only runs relevant checks based on modified file types
+
+cd "$CLAUDE_PROJECT_DIR" || exit 0
+
+# Get modified files (uncommitted changes)
+MODIFIED_FILES=$(git diff --name-only HEAD 2>/dev/null || echo '')
+
+# If no git repo or no changes, skip
+if [ -z "$MODIFIED_FILES" ]; then
+  exit 0
+fi
+
+# Check for TypeScript/JavaScript changes
+HAS_TS_CHANGES=$(echo "$MODIFIED_FILES" | grep -E '\.(ts|tsx|js|jsx)$' || true)
+
+# If only docs/config changed (no TS/JS), skip all checks
+if [ -z "$HAS_TS_CHANGES" ]; then
+  exit 0
+fi
+
+# Run lint and typecheck for TS/JS changes
+bun run lint:quiet 2>&1
+LINT_EXIT=$?
+
+bun run typecheck:quiet 2>&1
+TYPE_EXIT=$?
+
+# Check for anti-patterns in code files (not just docs/json)
+if git diff -- ':!.claude/' | grep -E '\b(fallback|deprecated|backward compatibility)\b' | grep -v '^-' | grep -qE '^\+'; then
+  echo 'Anti-pattern detected (fallback/deprecated/backward compatibility). Review CLAUDE.md: never use fallback code, deprecated implementations, or backward compatibility shims.' >&2
+  exit 2
+fi
+
+# Exit with error if lint or typecheck failed
+if [ $LINT_EXIT -ne 0 ] || [ $TYPE_EXIT -ne 0 ]; then
+  exit 1
+fi
+
+exit 0

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

@@ -0,0 +1,40 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(osascript:*)",
+      "Bash(bun run lint:*)",
+      "Bash(bun run typecheck:*)",
+      "Bash(npm run lint:*)",
+      "Bash(npm run typecheck:*)",
+      "Bash(bun run precommit:*)"
+    ]
+  },
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/post-edit-check.sh\"",
+            "statusMessage": "Validating changes..."
+          }
+        ]
+      }
+    ],
+    "Notification": [
+      {
+        "matcher": "permission_prompt|idle_prompt|elicitation_dialog",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "osascript -e 'display notification \"Claude needs your input\" with title \"Claude Code\" sound name \"Glass\"' 2>/dev/null || true"
+          }
+        ]
+      }
+    ]
+  },
+  "enabledPlugins": {
+    "bluera-knowledge@bluera": true
+  }
+}

package/.claude/skills/atomic-commits/SKILL.md

@@ -0,0 +1,53 @@
+# Atomic Commits with Documentation Awareness
+
+Guidelines for creating well-organized commits with README.md and CLAUDE.md awareness.
+
+## Documentation Check
+
+Before committing, evaluate if changes need documentation updates.
+
+### README.md (User-facing documentation)
+
+| Change Type | README Section to Update |
+|-------------|-------------------------|
+| MCP tools added/removed/renamed | MCP Tools table, MCP Integration section |
+| New commands or skills | Commands/Skills documentation |
+| CLI interface changes | Usage examples |
+| Configuration changes | Configuration/Environment sections |
+| Breaking API changes | Upgrade/migration notes |
+| New features | Feature documentation |
+| Installation changes | Installation section |
+
+**Trigger files → check README.md:**
+- `src/mcp/server.ts` - MCP tool surface
+- `plugin.json` - Plugin metadata
+- `commands/*.md` - Command documentation
+
+### CLAUDE.md (Claude Code memory - hierarchical)
+
+CLAUDE.md stores context that helps future sessions "do the right thing". Update when:
+- You struggled with something and the insight would prevent future mistakes
+- Important patterns or conventions that aren't obvious from code alone
+- Workflows or commands that are non-trivial to discover
+
+CLAUDE.md is hierarchical - use the directory level matching the changed files. Use `@path/to/file` includes to stay DRY.
+
+| Change Scope | Which CLAUDE.md |
+|--------------|-----------------|
+| Project-wide (scripts, CI/CD, build) | Root CLAUDE.md |
+| Directory-specific patterns | Subdirectory CLAUDE.md (create if needed) |
+
+## Grouping Rules
+
+Identify logical features by grouping related files:
+- Same feature = same commit
+- Infrastructure/config = separate commit
+- Tests = with their implementation OR separate if test-only
+
+## Commit Message Format
+
+```
+<type>(<scope>): <description>
+```
+
+Types: `feat`, `fix`, `docs`, `chore`, `refactor`, `test`, `style`

package/.claude-plugin/plugin.json

@@ -0,0 +1,13 @@
+{
+  "name": "bluera-knowledge",
+  "version": "0.9.21",
+  "description": "Clone repos, crawl docs, search locally. Fast, authoritative answers for AI coding agents without web lookups.",
+  "author": {
+    "name": "Bluera Inc",
+    "email": "contact@bluera.ai"
+  },
+  "homepage": "https://github.com/blueraai/bluera-knowledge",
+  "repository": "https://github.com/blueraai/bluera-knowledge",
+  "license": "MIT",
+  "mcpServers": "./mcp.plugin.json"
+}

package/.editorconfig

@@ -0,0 +1,15 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false
+
+[*.ts]
+indent_size = 2

package/.github/workflows/auto-release.yml

@@ -0,0 +1,59 @@
+name: Auto Release
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+# Prevent parallel tag creation - queue instead of cancel
+concurrency:
+  group: auto-release
+  cancel-in-progress: false
+
+jobs:
+  auto-release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write  # Required to push tags
+    # Only run after CI completes successfully
+    needs: []
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.MARKETPLACE_PAT }}  # Use PAT to trigger Release workflow
+
+      - name: Get version from package.json
+        id: package_version
+        run: |
+          VERSION=$(node -p "require('./package.json').version")
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+          echo "tag=v$VERSION" >> $GITHUB_OUTPUT
+
+      - name: Check if tag exists
+        id: check_tag
+        run: |
+          if git rev-parse "v${{ steps.package_version.outputs.version }}" >/dev/null 2>&1; then
+            echo "exists=true" >> $GITHUB_OUTPUT
+          else
+            echo "exists=false" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Wait for CI to complete
+        if: steps.check_tag.outputs.exists == 'false'
+        uses: lewagon/wait-on-check-action@v1.3.4
+        with:
+          ref: ${{ github.sha }}
+          check-regexp: '^(lint-and-typecheck|test|build)$'
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+          wait-interval: 10
+          allowed-conclusions: success
+
+      - name: Create and push tag
+        if: steps.check_tag.outputs.exists == 'false'
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git tag ${{ steps.package_version.outputs.tag }}
+          git push origin ${{ steps.package_version.outputs.tag }}

package/.github/workflows/ci.yml

@@ -0,0 +1,142 @@
+name: CI
+
+on:
+  push:
+    branches: ['**']
+    tags: ['v*']
+  pull_request:
+    branches: [main]
+
+# Prevent duplicate runs: cancel in-progress runs for same branch
+# When a PR is open, only run the pull_request event (skip the push)
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  # Fast checks that don't need Python/models (runs in ~30s)
+  lint-and-typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Cache Bun dependencies
+        uses: actions/cache@v4
+        with:
+          path: ~/.bun/install/cache
+          key: bun-${{ runner.os }}-${{ hashFiles('**/bun.lock') }}
+          restore-keys: |
+            bun-${{ runner.os }}-
+
+      - name: Install dependencies
+        run: bun install
+
+      - name: Lint
+        run: bun run lint
+
+      - name: Type check
+        run: bun run typecheck
+
+  # Tests with Python dependencies (slower, runs in parallel)
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Cache pip dependencies
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/pip
+          key: pip-${{ runner.os }}-crawl4ai
+          restore-keys: |
+            pip-${{ runner.os }}-
+
+      - name: Install crawl4ai
+        run: |
+          pip install crawl4ai
+          crawl4ai-setup
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Cache Bun dependencies
+        uses: actions/cache@v4
+        with:
+          path: ~/.bun/install/cache
+          key: bun-${{ runner.os }}-${{ hashFiles('**/bun.lock') }}
+          restore-keys: |
+            bun-${{ runner.os }}-
+
+      - name: Cache Hugging Face models
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/huggingface-transformers
+          key: huggingface-transformers-${{ runner.os }}-all-MiniLM-L6-v2
+          restore-keys: |
+            huggingface-transformers-${{ runner.os }}-
+
+      - name: Install dependencies
+        run: bun install
+
+      - name: Warm up embedding model
+        run: |
+          # Download embedding model before tests to prevent race conditions
+          # Multiple test files use embeddings - this ensures model is fully cached
+          node -e "
+            import('@huggingface/transformers').then(async ({ pipeline, env }) => {
+              const { homedir } = await import('node:os');
+              const { join } = await import('node:path');
+              env.cacheDir = join(homedir(), '.cache', 'huggingface-transformers');
+              console.log('Downloading embedding model to:', env.cacheDir);
+              await pipeline('feature-extraction', 'Xenova/all-MiniLM-L6-v2', { dtype: 'fp32' });
+              console.log('Model downloaded successfully');
+            });
+          "
+
+      - name: Run tests with coverage
+        run: bun run test:coverage
+
+  # Build (lightweight, runs in parallel)
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Cache Bun dependencies
+        uses: actions/cache@v4
+        with:
+          path: ~/.bun/install/cache
+          key: bun-${{ runner.os }}-${{ hashFiles('**/bun.lock') }}
+          restore-keys: |
+            bun-${{ runner.os }}-
+
+      - name: Install dependencies
+        run: bun install
+
+      - name: Build
+        run: bun run build
+
+  # Success job - only runs if all parallel jobs pass
+  ci-success:
+    runs-on: ubuntu-latest
+    needs: [lint-and-typecheck, test, build]
+    steps:
+      - name: CI passed
+        run: echo "All CI checks passed!"

package/.github/workflows/release.yml

@@ -0,0 +1,66 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+
+# Prevent parallel releases - queue instead of cancel
+concurrency:
+  group: release
+  cancel-in-progress: false
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Generate release notes
+        id: notes
+        run: |
+          # Get commits since last tag
+          PREV_TAG=$(git describe --tags --abbrev=0 HEAD^ 2>/dev/null || echo "")
+          if [ -n "$PREV_TAG" ]; then
+            NOTES=$(git log --pretty=format:"- %s" $PREV_TAG..HEAD)
+          else
+            NOTES=$(git log --pretty=format:"- %s" -20)
+          fi
+          echo "notes<<EOF" >> $GITHUB_OUTPUT
+          echo "$NOTES" >> $GITHUB_OUTPUT
+          echo "EOF" >> $GITHUB_OUTPUT
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+          body: |
+            ## Changes
+            ${{ steps.notes.outputs.notes }}
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Setup Node.js (for npm publish)
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Install dependencies
+        run: bun install
+
+      - name: Build
+        run: bun run build
+
+      - name: Publish to npm
+        run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/.github/workflows/update-marketplace.yml

@@ -0,0 +1,96 @@
+name: Update Marketplace
+
+on:
+  workflow_run:
+    workflows: ["Release"]
+    types: [completed]
+
+# Prevent parallel marketplace updates - queue instead of cancel
+concurrency:
+  group: update-marketplace
+  cancel-in-progress: false
+
+jobs:
+  update-marketplace:
+    runs-on: ubuntu-latest
+    # Only run if Release workflow succeeded
+    if: ${{ github.event.workflow_run.conclusion == 'success' }}
+
+    steps:
+      # Wait for CI to complete successfully
+      - name: Wait for CI to complete
+        uses: lewagon/wait-on-check-action@v1.3.4
+        with:
+          ref: ${{ github.event.workflow_run.head_sha }}
+          check-regexp: '^(lint-and-typecheck|test|build)$'
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+          wait-interval: 10
+          allowed-conclusions: success
+
+      # Get the tag name from the workflow run
+      - name: Get tag name
+        id: get_tag
+        env:
+          HEAD_BRANCH: ${{ github.event.workflow_run.head_branch }}
+        run: |
+          # Get the tag that triggered the Release workflow
+          # head_branch could be "v0.9.15" or "refs/tags/v0.9.15"
+          TAG_NAME=$(echo "$HEAD_BRANCH" | grep -oE 'v[0-9]+\.[0-9]+\.[0-9]+' || echo "")
+          if [ -z "$TAG_NAME" ]; then
+            echo "::error::Could not extract tag from head_branch: $HEAD_BRANCH"
+            exit 1
+          fi
+          echo "tag=${TAG_NAME}" >> $GITHUB_OUTPUT
+          echo "Tag: ${TAG_NAME}"
+
+      # Extract version from tag (v0.9.9 -> 0.9.9)
+      - name: Extract version
+        id: version
+        run: |
+          TAG_NAME=${{ steps.get_tag.outputs.tag }}
+          VERSION=${TAG_NAME#v}
+          echo "version=${VERSION}" >> $GITHUB_OUTPUT
+          echo "Extracted version: ${VERSION}"
+
+      # Checkout marketplace repo
+      - name: Checkout marketplace repo
+        uses: actions/checkout@v4
+        with:
+          repository: blueraai/bluera-marketplace
+          token: ${{ secrets.MARKETPLACE_PAT }}
+          path: marketplace
+
+      # Update marketplace.json
+      - name: Update marketplace version
+        working-directory: marketplace
+        run: |
+          VERSION="${{ steps.version.outputs.version }}"
+
+          jq --arg version "$VERSION" \
+            '(.plugins[] | select(.name == "bluera-knowledge") | .version) = $version' \
+            .claude-plugin/marketplace.json > .claude-plugin/marketplace.json.tmp
+
+          mv .claude-plugin/marketplace.json.tmp .claude-plugin/marketplace.json
+
+          echo "Updated marketplace.json to version $VERSION"
+
+      # Commit and push
+      - name: Commit and push marketplace update
+        working-directory: marketplace
+        run: |
+          VERSION="${{ steps.version.outputs.version }}"
+
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+          git add .claude-plugin/marketplace.json
+
+          if git diff --staged --quiet; then
+            echo "No changes - marketplace already up to date"
+            exit 0
+          fi
+
+          git commit -m "chore: update bluera-knowledge to v$VERSION"
+          git push
+
+          echo "✅ Successfully updated marketplace to v$VERSION"

package/.husky/pre-commit

@@ -0,0 +1,47 @@
+#!/bin/sh
+
+# Get list of staged files
+STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACM)
+
+# Categorize changes
+HAS_SRC_CHANGES=$(echo "$STAGED_FILES" | grep -E '^src/.*\.(ts|js)$' || true)
+HAS_TEST_CHANGES=$(echo "$STAGED_FILES" | grep -E '\.(test|spec)\.(ts|js)$' || true)
+HAS_CONFIG_CHANGES=$(echo "$STAGED_FILES" | grep -E '^(package\.json|tsconfig\.json|tsup\.config\.ts|\.eslintrc|knip\.json)' || true)
+HAS_DOC_CHANGES=$(echo "$STAGED_FILES" | grep -E '\.(md|txt)$|^LICENSE|^NOTICE' || true)
+HAS_DIST_CHANGES=$(echo "$STAGED_FILES" | grep -E '^dist/' || true)
+
+# If only documentation changed (and no code/config), skip all checks
+if [ -n "$HAS_DOC_CHANGES" ] && [ -z "$HAS_SRC_CHANGES" ] && [ -z "$HAS_TEST_CHANGES" ] && [ -z "$HAS_CONFIG_CHANGES" ]; then
+  echo "ℹ️  Only documentation changed, skipping code validation"
+  exit 0
+fi
+
+# If only dist/ changed (shouldn't happen, but handle it), skip checks
+if [ -n "$HAS_DIST_CHANGES" ] && [ -z "$HAS_SRC_CHANGES" ] && [ -z "$HAS_TEST_CHANGES" ] && [ -z "$HAS_CONFIG_CHANGES" ]; then
+  echo "ℹ️  Only dist/ changed, skipping validation"
+  exit 0
+fi
+
+# Run checks based on what changed
+echo "🔍 Running validation checks..."
+
+# Always run lint and typecheck for code/config changes
+if [ -n "$HAS_SRC_CHANGES" ] || [ -n "$HAS_TEST_CHANGES" ] || [ -n "$HAS_CONFIG_CHANGES" ]; then
+  bun run lint:quiet || exit 1
+  bun run lint:deadcode:quiet || exit 1
+  bun run typecheck:quiet || exit 1
+fi
+
+# Run tests only if source or test files changed
+if [ -n "$HAS_SRC_CHANGES" ] || [ -n "$HAS_TEST_CHANGES" ]; then
+  bun run test:changed:quiet || exit 1
+fi
+
+# Build only if source or config changed
+if [ -n "$HAS_SRC_CHANGES" ] || [ -n "$HAS_CONFIG_CHANGES" ]; then
+  bun run build:quiet || exit 1
+  # Auto-stage dist/ after build (required for Claude Code plugin distribution)
+  git add dist/
+fi
+
+echo "✅ All checks passed"

package/.husky/pre-push

@@ -0,0 +1,29 @@
+#!/bin/sh
+
+# 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 only for source/test changes
+echo "🧪 Running coverage tests..."
+bun run test:coverage:quiet || exit 1
+
+echo "✅ Coverage tests passed"

package/.versionrc.json

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