fix: resolve all ESLint errors in ast-search-service.ts

- Convert require() style imports to ESM default imports for @ast-grep/lang-* packages
- Import SgNode type from @ast-grep/napi and replace all 'any' types
- Change DynamicLanguagePackage from type to interface per lint rule
- Remove async keyword from isAvailable() (no await expression)
- Fix template literal number type warnings with String() conversions
- Replace || with ?? for nullish coalescing throughout
- Remove non-null assertions by using local variables
- Restructure stopBy validation to avoid type narrowing warnings
- Add CLAUDE.md with project instructions for Claude Code
- Fix security.ts regex to use startsWith() for UNC path check
- Add GITHUB_TOKEN to GitHub workflow for npm authentication

Author: GhostTypes

.github/workflows/test.yml

@@ -61,6 +61,7 @@ jobs:
         env:
           NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           NPM_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Build project
         run: npm run build
@@ -110,6 +111,7 @@ jobs:
         env:
           NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           NPM_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Build project
         run: npm run build

CLAUDE.md

@@ -0,0 +1,137 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Pre-Commit Checklist
+
+**ALWAYS run the following before committing:**
+```bash
+npm run build      # TypeScript compilation + asset copy
+npm run typecheck  # Strict type checking (tsc --noEmit)
+npm run lint        # ESLint on src/
+npm test           # Full test suite
+```
+
+**Quick single-test command:**
+```bash
+npm test -- <path-to-test-file>  # Run specific test file
+```
+
+## Development Commands
+
+| Command | Purpose |
+|---------|---------|
+| `npm run build` | Compile TypeScript and copy assets to `dist/` |
+| `npm run dev` | Watch mode compilation (tsc --watch) |
+| `npm run lint` | Run ESLint on TypeScript files |
+| `npm run lint:fix` | Auto-fix ESLint issues |
+| `npm run typecheck` | Type check without emitting files (`tsc --noEmit`) |
+| `npm test` | Run all tests (Jest with ts-jest preset) |
+| `npm run test:integration` | Run integration tests only |
+
+## Architecture Overview
+
+**Code Search MCP** is a Model Context Protocol (MCP) server that provides intelligent code search capabilities across 12+ programming languages. It integrates universal-ctags, ripgrep, and ast-grep to deliver:
+
+- **Symbol Search** - Indexed lookup of classes, functions, methods, variables
+- **AST Search** - Structural code pattern matching with metavariables and relational rules
+- **Text Search** - Fast regex-based code search via ripgrep
+- **File Search** - Glob-based file navigation
+- **Stack Detection** - Technology stack identification
+- **Dependency Analysis** - Multi-ecosystem package analysis
+- **Index Caching** - Persistent symbol indices (80%+ faster startup)
+
+## Core Components
+
+### MCP Server (`src/mcp/server.ts`)
+- Entry point for all MCP tool calls
+- Routes requests to appropriate services
+- Enforces workspace security via `allowedWorkspaces` configuration
+- Exposes 10 tools: `detect_stacks`, `search_symbols`, `search_text`, `search_files`, `refresh_index`, `cache_stats`, `clear_cache`, `analyze_dependencies`, `search_ast_pattern`, `search_ast_rule`, `check_ast_grep`
+
+### Symbol Search (`src/symbol-search/`)
+- **SymbolIndexer** - Manages ctags integration and cache orchestration
+- **SymbolSearchService** - Handles symbol search with match modes (exact, prefix, substring, regex)
+- **TextSearchService** - Ripgrep wrapper for text/code pattern search
+- **ctags-integration.ts** - Spawns universal-ctags in temp directory (security hardening)
+
+### AST Search (`src/ast-search/`)
+- **ASTSearchService** - Bundled ast-grep NAPI for structural code search
+- Supports 15 languages with dynamic language registration
+- Provides pattern matching with metavariables (`$VAR`, `$$VAR`, `$$$VAR`)
+- Supports complex rules with relational operators (`inside`, `has`, `precedes`, `follows`)
+
+### Cache System (`src/cache/`)
+- **CacheManager** - Persistent symbol index caching in `~/.code-search-mcp-cache/`
+- Automatic invalidation based on file modification times
+- Workspace isolation via hash-based IDs
+
+### Security (`src/utils/security.ts`)
+- **ReDoS prevention** - Regex complexity validation to prevent catastrophic backtracking
+- **Path validation** - UNC extended-length path blocking, traversal prevention
+- **Resource limits** - Max file sizes (100MB), recursion depths (100), timeouts (30s)
+- Created during security audit - always validate user inputs
+
+## Project Structure
+
+```
+src/
+├── mcp/                    # MCP server implementation, tool handlers
+├── symbol-search/          # Symbol indexing, text search
+├── ast-search/             # AST pattern matching (ast-grep NAPI)
+├── file-search/            # File system navigation (fast-glob)
+├── stack-detection/       # Technology stack detection engine
+├── dependency-analysis/    # Multi-ecosystem dependency parsing
+├── cache/                  # Persistent index caching
+├── types/                  # TypeScript type definitions
+├── utils/                  # Utilities: security, workspace validation
+└── stacks.json             # Stack definitions for detection
+```
+
+## Important Conventions
+
+### TypeScript Configuration
+- **Strict mode enabled** - `noUnusedLocals`, `noUnusedParameters`, `noImplicitReturns`
+- **ESM modules** - `module: "NodeNext"`, `moduleResolution: "NodeNext"`
+- **Compilation target** - `ES2022`, Node.js 18+ required
+
+### Import Convention
+- Always use `.js` extensions in imports (ESM requirement): `import { foo } from './foo.js'`
+- Type-only imports: `import type { Foo } from './types/foo.js'`
+
+### Security Model
+- **Workspace validation** - All paths validated against `allowedWorkspaces` list
+- **Path traversal blocking** - Checks for `..` and absolute paths before resolution
+- **UNC path blocking** - Windows `\\?\` and `\\.\` paths rejected explicitly
+- **Symlink hardening** - Temp files use system temp directory, symlink checks before writes
+
+### Testing
+- Unit tests in `tests/unit/`, integration tests in `tests/integration/`
+- Uses `ts-jest` with ESM preset: `--experimental-vm-modules`
+- Tests include 61 security-specific tests across 3 test files
+
+## MCP Tools Reference
+
+| Tool | Purpose |
+|------|---------|
+| `detect_stacks` | Auto-detect technology stacks in a directory |
+| `search_symbols` | Find classes, functions, methods by name/pattern |
+| `search_text` | Regex code search using ripgrep |
+| `search_files` | Find files by name, extension, or glob pattern |
+| `refresh_index` | Rebuild symbol index for a workspace |
+| `cache_stats` | Get cache statistics for workspaces |
+| `clear_cache` | Clear cached indices |
+| `analyze_dependencies` | Analyze project dependencies |
+| `search_ast_pattern` | AST pattern matching with metavariables |
+| `search_ast_rule` | Complex AST rules with relational/composite operators |
+| `check_ast_grep` | Verify ast-grep availability |
+
+## External Dependencies
+
+- **@ast-grep/napi** - Bundled native binaries (no installation required)
+- **@vscode/ripgrep** - Bundled ripgrep binary
+- **@LLMTooling/universal-ctags-node** - Bundled universal-ctags binary
+- **fast-glob** - Fast glob pattern matching
+- **@modelcontextprotocol/sdk** - MCP SDK for server implementation
+
+All external binaries are bundled - no external ctags/ripgrep installation needed by end users.