mcp-code-context 3.9.0 → 3.9.2

package/CHANGELOG.md

@@ -1,205 +1,227 @@
-# Changelog
-
-## [3.9.0] - 2026-07-17
-
-### Added
-
-- **`get_gemfile_context`** (R7) — parses `Gemfile` and returns known gems with their implicit Rails behavior. Uses `gemDescriptions.json` lookup table (updateable without recompile). Includes mtime-keyed cache for zero re-read cost.
-- **`find_metaprogramming`** (R3) — scans Ruby files for dynamic method generation entry points: `define_method`, `method_missing`, `class_eval/module_eval`, `instance_eval`, `send/public_send`, `ActiveSupport::Concern`, `included do`, `attr_accessor/reader/writer`, `delegate :to =>`, `has_many :through`. Accepts single file or full directory scan.
-- **`get_rails_routes`** (R2) — parses `config/routes.rb` and returns a structured route map (method, path, controller, action). Supports `resources`, `resource`, explicit HTTP verbs (`get/post/patch/put/delete`), `namespace/scope` prefixing, `root`, and `do`-block nesting warnings. mtime-keyed cache.
-- **Concern Resolution in `analyze_impact`** (R5) — `rubyModuleResolvesToFile()` now checks `app/models/concerns` and `app/controllers/concerns` via `findRailsConcerns()` before falling back to file system candidates. Prevents false positives for stdlib mixins.
-- **`findRailsConcerns()`** utility — scans both concern directories and returns a `Map<moduleName, filePaths[]>` for use by impact analysis and future tools.
-
-### Changed
-
-- `gemDescriptions.json` — new data file for gem behavior descriptions (bundled in `src/utils/`)
-
----
-
-## [3.8.1] - 2026-07-16
-
-### Added
-
-- **`insertCode` fix for brace-less languages (Ruby, Python)** — `inside_start`/`inside_end` positions now use AST-aware methods instead of `indexOf("{")` / `lastIndexOf("}")`. Added `getInsideStartIndex()` and `getInsideEndIndex()` to `BaseParser` with language-specific overrides in `RubyParser` and `PythonParser`.
-- **Ruby import analysis** — `extractImports` in `compress.ts` now detects `require` and `require_relative` patterns. `analyzeImpact` adds Ruby patterns with file-resolution guard (prevents false positives from stdlib mixins like `include Comparable`).
-- **ActiveRecord schema injection in `get_semantic_repo_map`** — repo map now includes `db_column` symbols for AR models, showing database columns alongside methods in the XML/Markdown output.
-
-### Fixed
-
-- **`insert_symbol inside_start/inside_end` for Ruby** — previously returned wrong position (`-1`) for any Ruby class or method. Now inserts correctly after the opening header line (`inside_start`) and before the closing `end` keyword (`inside_end`).
-- **`insert_symbol inside_start/inside_end` for Python** — previously searched for `{`/`}` that don't exist. Now uses colon+newline and indentation-aware end position.
-
----
-
-## [3.8.0] - 2026-07-15
-
-### Added
-
-- **Ruby full support** — `RubyParser` now complete with `search()` method for `search_code_pattern` tool compatibility
-- **ActiveRecord Virtual Schema Extractor** — new `src/utils/railsSchema.ts` utility:
-  - Parses `db/schema.rb` via O(n) line-by-line state machine (no backtracking risk)
-  - mtime-keyed in-memory cache — zero I/O on repeated reads of unchanged schema
-  - `modelToTable()` — Rails CoC PascalCase → snake_case → pluralize (`AdminUser → admin_users`, `Category → categories`)
-  - `formatSchemaAnnotation()` — emits XML comment block with column names and types
-- **AR schema injection in `read_file_surgical`** — when reading `.rb` files inheriting from `ApplicationRecord` or `ActiveRecord::Base`, virtual schema columns are prepended as XML comments
-  - Context-aware: when `symbolName` is set, reads full file to detect AR inheritance before injecting
-  - Graceful: no-op when `db/schema.rb` is absent or table not found
-
-### Fixed
-
-- **`RubyParser.extractSymbol` off-by-one** — `tree.rootNode.text` omits leading whitespace on Windows/WASM, causing `startIndex` drift. Fixed by adjusting indices relative to `tree.rootNode.startIndex`.
-
-### Tests
-
-- Added `tests/unit/parsers/ruby.spec.ts` — 5 vitest specs: symbol discovery, surgical replace, `extractSymbol` scoping, `parseSchemaRb` column extraction, `modelToTable` CoC mapping
-- All 115 WASM parser tests passing (100%)
-
----
-
-## [3.7.1] - 2026-06-18
-
-### Fixed
-
-- **`ast_transform` wrap_with_try_catch**: Missing closing `}` for method body caused unbalanced braces and syntax errors in all TypeScript class methods
-- **`ast_transform` wrap_with_try_catch**: Missing newline after `try {` caused parse failure on all function types
-
----
-
-## [3.7.0] - 2026-06-18
-
-### 🚀 Production Readiness Release — Adversarial Audit Hardening
-
-This release fixes **critical architectural issues** identified through three rounds of adversarial analysis and AST-based code review. All stoppers resolved. Ready for multi-agent production deployments.
-
-### Fixed — Critical (Production Blockers)
-
-1. **Session State Leakage / Memory Leak**
-   - Global state (`globalLockManager`, `globalConfirmationStore`, `rateLimiter`) accumulated across client sessions with no cleanup.
-   - **Fix**: `SessionManager` per-client state isolation with LRU eviction and 30-min timeout cleanup.
-
-2. **No Phase 1 Crash Recovery**
-   - Pending operations stored in memory only. Server crash between Phase 1 → Phase 2 lost all work.
-   - **Fix**: SQLite-backed `PendingOperationStore` — operations persist across restarts.
-
-3. **TOCTOU in Multi-File Writes**
-   - Phase 2 only verified hash of the primary file, not dependent files in `pendingWrites`.
-   - **Fix**: Hash verified on all files in the write set before applying.
-
-4. **Symlink Boundary Escape**
-   - `path.resolve()` used for boundary validation — does not follow symlinks.
-   - **Fix**: `fs.realpath()` in `SecurityValidator.validateFilePath()`.
-
-5. **`new Promise(async ...)` Anti-pattern in Worker**
-   - `runInWorker` used `new Promise(async (resolve) => ...)` — swallowed async errors.
-   - **Fix**: Refactored to standard async/await pattern.
-
-6. **`WORKER_FILE` Resolved at Import-Time**
-   - Worker path calculated before `dist/` exists — crashes on fresh install.
-   - **Fix**: Lazy `getWorkerFile()` evaluated at runtime.
-
-7. **ReDoS in `impactAnalysis`, `rename`, `readCore`**
-   - Dynamic `new RegExp()` constructed in main thread without timeout.
-   - **Fix**: All operation-level regex routed through `safeRegex` worker pool.
-
-8. **Rate Limiter Shared Globally**
-   - Single `'global'` bucket shared across all MCP clients.
-   - **Fix**: Per-session `SESSION_ID` (pid-based) rate limiting.
-
-9. **`configure_file_watcher` Without `rootDir` Validation**
-   - Watcher path not validated through `SecurityValidator`.
-   - **Fix**: Watcher uses only validated `projectRoot`.
-
-10. **Confirmation Token Leak Without Cleanup**
-    - Expired tokens accumulated in memory indefinitely.
-    - **Fix**: `setInterval` 60s cleanup in `ConfirmationStore`.
-
-11. **Windows Path Case Sensitivity in Boundary Check**
-    - `fs.realpath()` returns `C:\` (uppercase), `path.resolve()` returns `c:\` (lowercase).
-    - **Fix**: `.toLowerCase()` normalization on both sides before comparison.
-
-12. **`ast_transform` try/catch Indentation Bug**
-    - `applyWrapTryCatch` added extra indent on top of existing indentation.
-    - **Fix**: Correct base-indent detection using last line of rawBody as closing-indent anchor.
-
-### Added
-
-#### 25 Tools (up from 13 in v3.6.x)
-
-New tools added in this release:
-
-| Tool | Purpose |
-|------|---------|
-| `ast_transform` | Declarative AST transforms: add_parameter, wrap_with_try_catch, add_decorator, change_return_type, extract_variable |
-| `search_symbols` | AST-aware symbol search by name (fuzzy-capable), not text grep |
-| `explain_symbol` | Signature + location + callers in one call |
-| `batch_read` | Read N symbols from N files in 1 round-trip |
-| `get_rate_limit_status` | Token balance + `canAfford` map per operation |
-| `get_session_stats` | Per-session diagnostics (pending ops, locks, tokens) |
-| `clear_session_cache` | Invalidate cache for current session only |
-| `list_pending_operations` | Recovery listing after crash |
-
-#### Architecture Improvements
-
-- `SessionManager`: Per-client isolated state (locks, confirmations, rate limiter, cache pool)
-- `safeRegexPool.ts` + `safeRegexApi.ts`: Worker pool split from monolithic `safeRegex.ts`
-- `toctou.ts`: TOCTOU hash helpers extracted to own module
-- `pendingStore.ts` + `pendingStoreInit.ts`: SQLite crash-recovery layer
-- `toolDefinitionsAdmin.ts` + `toolDefinitionsCore.ts`: Tool definitions split from 1000-line index
-- All `src/` files under 300 lines (from 1000-line monolith)
-
-#### DX / Ergonomics
-
-- `diffFormat` param on all write tools: `unified` | `compact` | `summary` | `none`
-- Phase 2 does NOT require re-sending `newContent`/`code` (server stores from Phase 1)
-- `aroundPattern` output includes `"Match found at line N (showing lines X-Y):"`
-- `get_cache_stats` includes `hits`, `misses`, `hitRate`
-- `get_file_watcher_status` includes `paths[]` (capped at 50)
-- `get_server_stats` includes `rateLimiter.tokensAvailable` and `operationCosts`
-- `MAX_FILES_REPO_MAP` = 2000 (was 500)
-
-### Test Results
-
-- **83/83 tests passing** (100%)
-- Security tests: ✅
-- File lock tests: ✅
-- Rate limiter tests: ✅
-- WASM parser tests (TS/PHP/Python/Dart): ✅
-- Backup manager, diff, TOCTOU, cache, confirmation store: ✅
-- Multi-process concurrency tests: ✅
-- Performance tests: ✅
-
-### Migration from v3.6.x
-
-- **Zero breaking changes** in the public tool API.
-- `parse_file` now returns `startLine`/`endLine` per symbol — additive, no breakage.
-- New tools are purely additive.
-- Session isolation is automatic — no configuration needed.
-
----
-
-## [3.6.4] - 2026-05-14
-
-### Added
-- Language parsers: C#, Go, Java, Kotlin, Ruby, Rust (Tree-sitter WASM)
-- `parse_file` returns `startLine`/`endLine` per symbol
-- Fuzzy search with `fuzzyMatch` + `fuzzyThreshold` parameters
-- Pagination via `startIndex` on `search_code_pattern`
-- `diffFormat` parameter on write tools
-
-### Fixed
-- `parse_file` symbols missing line numbers
-- CVE in `@modelcontextprotocol/sdk` (updated to 1.29.0)
-- Incorrect TypeScript version `5.7.0` → `5.7.2`
-
----
-
-## [3.6.1] - 2026-04-28
-
-### Added
-- Persistent WASM SQLite cache (`CacheManager`)
-- Structured logging via pino (stderr-safe for MCP)
-- File watcher via chokidar
-- Multi-process file locking via proper-lockfile
-- Rolling 5-version backup system
-- `rollback_file` and `clean_backups` tools
-- 74 tests (unit + integration + performance + stress)
+# Changelog
+
+## [3.9.2] - 2026-10-12
+
+### Fixed
+
+- **Project Root Fallback & Boundary Resolution** — fixed critical issue where omitted or `undefined` `projectRoot` arguments were coerced to the literal string `"undefined"`, resolving to `<cwd>/undefined` and causing spurious `outside project boundary` security errors when accessing valid files.
+- **Smart Root Discovery** — introduced `resolveProjectRoot` and `findProjectRoot` in `src/utils/projectRoot.ts`, which automatically walks up the directory tree to discover root markers (`.git`, `package.json`, `composer.json`, `pyproject.toml`, `requirements.txt`, `Cargo.toml`, `go.mod`, `Gemfile`, `pom.xml`, `build.gradle`), falling back cleanly to `process.cwd()`.
+- **SecurityValidator Hardening** — `SecurityValidator` constructor now safely handles `undefined`, `null`, or blank inputs without generating an invalid boundary path.
+- **Optional Schema Requirements** — made `projectRoot` optional in tool definitions across both `CORE_TOOLS` and `ADMIN_TOOLS`, allowing LLM agents to execute surgical reads, writes, and symbol lookups with only `filePath` or `rootDir`.
+- **Startup Diagnostics** — added clear banner signature on stdio initialization: `[mcp-code-context] v3.9.2 running on stdio`.
+
+---
+
+## [3.9.1] - 2026-07-17
+
+### Fixed
+
+- **`get_rails_routes` namespace bug** — routes inside `namespace :admin do` / `namespace :api do` now correctly produce prefixed paths (`/admin/users`, `/api/v1/orders`) and namespaced controllers (`admin/users`, `api/v1/orders`). Root cause: the original regex `/^(?:namespace|scope)\s+[:'"]([^'"]+)['"]/` captured `admin do` instead of `admin` when using symbol syntax (`:admin`). Rewrote parser to handle symbol (`:admin`) and string (`'admin'`) syntax separately.
+- **`get_rails_routes` depth tracking** — replaced fragile `do/end` counter with indentation-based namespace stack. Parser now correctly handles nested namespaces (`api > v1`), `resources` blocks with `member do`, and `scope` blocks without false prefix leakage.
+- **`get_semantic_repo_map` Gemfile + Concerns injection** — repo map XML now appends `<gem>` blocks and `<concern>` entries when a Gemfile and concerns directory are present.
+
+---
+
+## [3.9.0] - 2026-07-17
+
+### Added
+
+- **`get_gemfile_context`** (R7) — parses `Gemfile` and returns known gems with their implicit Rails behavior. Uses `gemDescriptions.json` lookup table (updateable without recompile). Includes mtime-keyed cache for zero re-read cost.
+- **`find_metaprogramming`** (R3) — scans Ruby files for dynamic method generation entry points: `define_method`, `method_missing`, `class_eval/module_eval`, `instance_eval`, `send/public_send`, `ActiveSupport::Concern`, `included do`, `attr_accessor/reader/writer`, `delegate :to =>`, `has_many :through`. Accepts single file or full directory scan.
+- **`get_rails_routes`** (R2) — parses `config/routes.rb` and returns a structured route map (method, path, controller, action). Supports `resources`, `resource`, explicit HTTP verbs (`get/post/patch/put/delete`), `namespace/scope` prefixing, `root`, and `do`-block nesting warnings. mtime-keyed cache.
+- **Concern Resolution in `analyze_impact`** (R5) — `rubyModuleResolvesToFile()` now checks `app/models/concerns` and `app/controllers/concerns` via `findRailsConcerns()` before falling back to file system candidates. Prevents false positives for stdlib mixins.
+- **`findRailsConcerns()`** utility — scans both concern directories and returns a `Map<moduleName, filePaths[]>` for use by impact analysis and future tools.
+
+### Changed
+
+- `gemDescriptions.json` — new data file for gem behavior descriptions (bundled in `src/utils/`)
+
+---
+
+## [3.8.1] - 2026-07-16
+
+### Added
+
+- **`insertCode` fix for brace-less languages (Ruby, Python)** — `inside_start`/`inside_end` positions now use AST-aware methods instead of `indexOf("{")` / `lastIndexOf("}")`. Added `getInsideStartIndex()` and `getInsideEndIndex()` to `BaseParser` with language-specific overrides in `RubyParser` and `PythonParser`.
+- **Ruby import analysis** — `extractImports` in `compress.ts` now detects `require` and `require_relative` patterns. `analyzeImpact` adds Ruby patterns with file-resolution guard (prevents false positives from stdlib mixins like `include Comparable`).
+- **ActiveRecord schema injection in `get_semantic_repo_map`** — repo map now includes `db_column` symbols for AR models, showing database columns alongside methods in the XML/Markdown output.
+
+### Fixed
+
+- **`insert_symbol inside_start/inside_end` for Ruby** — previously returned wrong position (`-1`) for any Ruby class or method. Now inserts correctly after the opening header line (`inside_start`) and before the closing `end` keyword (`inside_end`).
+- **`insert_symbol inside_start/inside_end` for Python** — previously searched for `{`/`}` that don't exist. Now uses colon+newline and indentation-aware end position.
+
+---
+
+## [3.8.0] - 2026-07-15
+
+### Added
+
+- **Ruby full support** — `RubyParser` now complete with `search()` method for `search_code_pattern` tool compatibility
+- **ActiveRecord Virtual Schema Extractor** — new `src/utils/railsSchema.ts` utility:
+  - Parses `db/schema.rb` via O(n) line-by-line state machine (no backtracking risk)
+  - mtime-keyed in-memory cache — zero I/O on repeated reads of unchanged schema
+  - `modelToTable()` — Rails CoC PascalCase → snake_case → pluralize (`AdminUser → admin_users`, `Category → categories`)
+  - `formatSchemaAnnotation()` — emits XML comment block with column names and types
+- **AR schema injection in `read_file_surgical`** — when reading `.rb` files inheriting from `ApplicationRecord` or `ActiveRecord::Base`, virtual schema columns are prepended as XML comments
+  - Context-aware: when `symbolName` is set, reads full file to detect AR inheritance before injecting
+  - Graceful: no-op when `db/schema.rb` is absent or table not found
+
+### Fixed
+
+- **`RubyParser.extractSymbol` off-by-one** — `tree.rootNode.text` omits leading whitespace on Windows/WASM, causing `startIndex` drift. Fixed by adjusting indices relative to `tree.rootNode.startIndex`.
+
+### Tests
+
+- Added `tests/unit/parsers/ruby.spec.ts` — 5 vitest specs: symbol discovery, surgical replace, `extractSymbol` scoping, `parseSchemaRb` column extraction, `modelToTable` CoC mapping
+- All 115 WASM parser tests passing (100%)
+
+---
+
+## [3.7.1] - 2026-06-18
+
+### Fixed
+
+- **`ast_transform` wrap_with_try_catch**: Missing closing `}` for method body caused unbalanced braces and syntax errors in all TypeScript class methods
+- **`ast_transform` wrap_with_try_catch**: Missing newline after `try {` caused parse failure on all function types
+
+---
+
+## [3.7.0] - 2026-06-18
+
+### 🚀 Production Readiness Release — Adversarial Audit Hardening
+
+This release fixes **critical architectural issues** identified through three rounds of adversarial analysis and AST-based code review. All stoppers resolved. Ready for multi-agent production deployments.
+
+### Fixed — Critical (Production Blockers)
+
+1. **Session State Leakage / Memory Leak**
+   - Global state (`globalLockManager`, `globalConfirmationStore`, `rateLimiter`) accumulated across client sessions with no cleanup.
+   - **Fix**: `SessionManager` per-client state isolation with LRU eviction and 30-min timeout cleanup.
+
+2. **No Phase 1 Crash Recovery**
+   - Pending operations stored in memory only. Server crash between Phase 1 → Phase 2 lost all work.
+   - **Fix**: SQLite-backed `PendingOperationStore` — operations persist across restarts.
+
+3. **TOCTOU in Multi-File Writes**
+   - Phase 2 only verified hash of the primary file, not dependent files in `pendingWrites`.
+   - **Fix**: Hash verified on all files in the write set before applying.
+
+4. **Symlink Boundary Escape**
+   - `path.resolve()` used for boundary validation — does not follow symlinks.
+   - **Fix**: `fs.realpath()` in `SecurityValidator.validateFilePath()`.
+
+5. **`new Promise(async ...)` Anti-pattern in Worker**
+   - `runInWorker` used `new Promise(async (resolve) => ...)` — swallowed async errors.
+   - **Fix**: Refactored to standard async/await pattern.
+
+6. **`WORKER_FILE` Resolved at Import-Time**
+   - Worker path calculated before `dist/` exists — crashes on fresh install.
+   - **Fix**: Lazy `getWorkerFile()` evaluated at runtime.
+
+7. **ReDoS in `impactAnalysis`, `rename`, `readCore`**
+   - Dynamic `new RegExp()` constructed in main thread without timeout.
+   - **Fix**: All operation-level regex routed through `safeRegex` worker pool.
+
+8. **Rate Limiter Shared Globally**
+   - Single `'global'` bucket shared across all MCP clients.
+   - **Fix**: Per-session `SESSION_ID` (pid-based) rate limiting.
+
+9. **`configure_file_watcher` Without `rootDir` Validation**
+   - Watcher path not validated through `SecurityValidator`.
+   - **Fix**: Watcher uses only validated `projectRoot`.
+
+10. **Confirmation Token Leak Without Cleanup**
+    - Expired tokens accumulated in memory indefinitely.
+    - **Fix**: `setInterval` 60s cleanup in `ConfirmationStore`.
+
+11. **Windows Path Case Sensitivity in Boundary Check**
+    - `fs.realpath()` returns `C:\` (uppercase), `path.resolve()` returns `c:\` (lowercase).
+    - **Fix**: `.toLowerCase()` normalization on both sides before comparison.
+
+12. **`ast_transform` try/catch Indentation Bug**
+    - `applyWrapTryCatch` added extra indent on top of existing indentation.
+    - **Fix**: Correct base-indent detection using last line of rawBody as closing-indent anchor.
+
+### Added
+
+#### 25 Tools (up from 13 in v3.6.x)
+
+New tools added in this release:
+
+| Tool | Purpose |
+|------|---------|
+| `ast_transform` | Declarative AST transforms: add_parameter, wrap_with_try_catch, add_decorator, change_return_type, extract_variable |
+| `search_symbols` | AST-aware symbol search by name (fuzzy-capable), not text grep |
+| `explain_symbol` | Signature + location + callers in one call |
+| `batch_read` | Read N symbols from N files in 1 round-trip |
+| `get_rate_limit_status` | Token balance + `canAfford` map per operation |
+| `get_session_stats` | Per-session diagnostics (pending ops, locks, tokens) |
+| `clear_session_cache` | Invalidate cache for current session only |
+| `list_pending_operations` | Recovery listing after crash |
+
+#### Architecture Improvements
+
+- `SessionManager`: Per-client isolated state (locks, confirmations, rate limiter, cache pool)
+- `safeRegexPool.ts` + `safeRegexApi.ts`: Worker pool split from monolithic `safeRegex.ts`
+- `toctou.ts`: TOCTOU hash helpers extracted to own module
+- `pendingStore.ts` + `pendingStoreInit.ts`: SQLite crash-recovery layer
+- `toolDefinitionsAdmin.ts` + `toolDefinitionsCore.ts`: Tool definitions split from 1000-line index
+- All `src/` files under 300 lines (from 1000-line monolith)
+
+#### DX / Ergonomics
+
+- `diffFormat` param on all write tools: `unified` | `compact` | `summary` | `none`
+- Phase 2 does NOT require re-sending `newContent`/`code` (server stores from Phase 1)
+- `aroundPattern` output includes `"Match found at line N (showing lines X-Y):"`
+- `get_cache_stats` includes `hits`, `misses`, `hitRate`
+- `get_file_watcher_status` includes `paths[]` (capped at 50)
+- `get_server_stats` includes `rateLimiter.tokensAvailable` and `operationCosts`
+- `MAX_FILES_REPO_MAP` = 2000 (was 500)
+
+### Test Results
+
+- **83/83 tests passing** (100%)
+- Security tests: ✅
+- File lock tests: ✅
+- Rate limiter tests: ✅
+- WASM parser tests (TS/PHP/Python/Dart): ✅
+- Backup manager, diff, TOCTOU, cache, confirmation store: ✅
+- Multi-process concurrency tests: ✅
+- Performance tests: ✅
+
+### Migration from v3.6.x
+
+- **Zero breaking changes** in the public tool API.
+- `parse_file` now returns `startLine`/`endLine` per symbol — additive, no breakage.
+- New tools are purely additive.
+- Session isolation is automatic — no configuration needed.
+
+---
+
+## [3.6.4] - 2026-05-14
+
+### Added
+- Language parsers: C#, Go, Java, Kotlin, Ruby, Rust (Tree-sitter WASM)
+- `parse_file` returns `startLine`/`endLine` per symbol
+- Fuzzy search with `fuzzyMatch` + `fuzzyThreshold` parameters
+- Pagination via `startIndex` on `search_code_pattern`
+- `diffFormat` parameter on write tools
+
+### Fixed
+- `parse_file` symbols missing line numbers
+- CVE in `@modelcontextprotocol/sdk` (updated to 1.29.0)
+- Incorrect TypeScript version `5.7.0` → `5.7.2`
+
+---
+
+## [3.6.1] - 2026-04-28
+
+### Added
+- Persistent WASM SQLite cache (`CacheManager`)
+- Structured logging via pino (stderr-safe for MCP)
+- File watcher via chokidar
+- Multi-process file locking via proper-lockfile
+- Rolling 5-version backup system
+- `rollback_file` and `clean_backups` tools
+- 74 tests (unit + integration + performance + stress)

package/INSTRUCTIONS.md

@@ -71,8 +71,8 @@ This MCP server provides **surgical code editing** with Tree-sitter AST parsing.
 
 ## 🚨 Critical Rules
 
-### 1. **ALWAYS Use projectRoot**
-Every tool requires `projectRoot` for security. Use the project's root directory.
+### 1. **Project Root (Auto-Resolved in v3.9.2)**
+While `projectRoot` is supported for explicit boundary locking, in v3.9.2 it is optional and automatically resolved from `filePath` or `rootDir` by walking up to the nearest project marker (`.git`, `package.json`, etc.). You can omit it without fear of boundary errors.
 
 ### 2. **NEVER Skip Phase 1**
 Always preview diffs before applying. Tokens are stored in memory and expire on server restart.
@@ -253,14 +253,20 @@ newContent: "{ return 42; }"
 
 ---
 
-## 🚀 v3.9.0 Features
+## 🚀 v3.9.2 Features
 
-### New Tools
-- **`get_session_stats`**: Session-scoped stats (pending ops, locks held, rate limiter tokens)
-- **`clear_session_cache`**: Clear cache for current session only (no impact on other clients)
-- **`list_pending_operations`**: List all pending operations (for recovery after crash)
+### Core Improvements
+- ✅ **Smart Project Root Discovery**: `resolveProjectRoot` & `findProjectRoot` automatically detect project markers (`.git`, `package.json`, `composer.json`, `pyproject.toml`, etc.), preventing boundary errors when `projectRoot` is omitted or undefined.
+- ✅ **Optional Schema Requirements**: `projectRoot` is now optional across all tools in `CORE_TOOLS` and `ADMIN_TOOLS`, allowing LLM agents to execute surgical operations with just `filePath` or `rootDir`.
+- ✅ **SecurityValidator Guard**: Robust handling of undefined/null boundaries, safely defaulting to `process.cwd()`.
+- ✅ **Startup Diagnostics**: Stdio initialization signature `[mcp-code-context] v3.9.2 running on stdio`.
 
-### Improvements
+### Previously Added in v3.9.0 - v3.9.1
+- ✅ **Ruby Intelligence**: `get_gemfile_context`, `find_metaprogramming`, `get_rails_routes`, and Rails concerns resolution in `analyze_impact`.
+- ✅ **Semantic Repo Map Enhancements**: Injects `<gem>` behavior blocks and `<concern>` entries when Gemfile and concerns directories exist.
+
+### Previously Added in v3.8.x
+- ✅ **New Tools**: `get_session_stats`, `clear_session_cache`, `list_pending_operations`
 - ✅ **Session-scoped state**: No state leakage between MCP clients
 - ✅ **Crash recovery**: SQLite-backed pending operations store
 - ✅ **Expanded ReDoS protection**: 15+ patterns (was 6)
@@ -288,6 +294,6 @@ See `llms.txt` for complete API reference and technical details.
 
 ---
 
-**Version**: 3.9.0  
-**Last Updated**: June 8, 2026  
-**Status**: Production-ready with session-scoped state and crash recovery
+**Version**: 3.9.2  
+**Last Updated**: October 12, 2026  
+**Status**: Production-ready with smart project root discovery and session-scoped state

package/README.md

@@ -75,7 +75,7 @@ Built to be robust and precise. Both read and write engines are tested against r
 
 ### Production-Ready Features
 
-| Feature | v3.6.x | v3.9.0 | Benefit |
+| Feature | v3.6.x | v3.8.0+ | Benefit |
 |---------|--------|--------|---------|
 | Multi-process safety | ✅ | ✅ | No file corruption |
 | Persistent cache | ✅ | ✅ | <100ms cache hits |
@@ -88,13 +88,31 @@ Built to be robust and precise. Both read and write engines are tested against r
 
 ## Features
 
-### What's New in v3.9.0
+### What's New in v3.9.2
 
 | Feature | Description |
 |---------|-------------|
-| 🔧 **`insert_symbol` fix Ruby/Python** | `inside_start`/`inside_end` now uses AST positions — no more broken insertion for `end`-based or indentation-based languages |
-| 🗄️ **Schema in `get_semantic_repo_map`** | Repo map now shows `db_column` symbols for all ActiveRecord models alongside their methods |
-| 🔗 **Ruby import analysis** | `analyze_impact` and dependency index now track `require`/`require_relative` in Ruby files with false-positive guard for stdlib mixins |
+| 🛡️ **Smart Project Root Discovery** | `resolveProjectRoot` & `findProjectRoot` walk up directory trees finding `.git`, `package.json`, `composer.json`, etc. No more `outside project boundary ".../undefined"` security errors. |
+| 🔓 **Optional Schema Requirements** | `projectRoot` is now optional across all tools in `CORE_TOOLS` and `ADMIN_TOOLS`. LLM agents can perform surgical reads, writes, and searches with just `filePath` or `rootDir`. |
+| 🛡️ **SecurityValidator Fallback Guard** | `SecurityValidator` safely handles `undefined`/`null` inputs by falling back to `process.cwd()` instead of normalizing to literal `undefined`. |
+| 📡 **Startup Diagnostics Signature** | Startup diagnostics banner prints `[mcp-code-context] v3.9.2 running on stdio` on stdio initialization. |
+
+### Previous: v3.9.1
+
+| Feature | Description |
+|---------|-------------|
+| 🐛 **`get_rails_routes` namespace fix** | Routes inside `namespace :admin do` now correctly produce `/admin/users` paths and `admin/users` controllers. Rewrote parser with indentation-based stack (was fragile do/end counter). |
+| 🗺️ **Repo map: Gems + Concerns** | `get_semantic_repo_map` now appends `<gem>` behavior blocks and `<concern>` entries when Gemfile and concerns directories are present. |
+| 🔧 **`get_rails_routes` nested scopes** | Supports `namespace :api do / namespace :v1 do` double-nesting, `member do` blocks, and `scope` (URL-only prefix). |
+
+### Previous: v3.9.0
+
+| Feature | Description |
+|---------|-------------|
+| 💎 **`get_gemfile_context`** | Parses Gemfile and returns implicit gem behaviors (devise adds `current_user`, sidekiq adds `perform_async`, etc.) |
+| 🔍 **`find_metaprogramming`** | Scans Ruby files for `define_method`, `method_missing`, `class_eval`, `ActiveSupport::Concern`, `delegate`, `has_many :through` etc. |
+| 🗺️ **`get_rails_routes`** | Parses `config/routes.rb` into structured route map (method, path, controller, action) |
+| 🔗 **Concern resolution in `analyze_impact`** | `rubyModuleResolvesToFile()` checks concerns directories — no more false positives from `include Comparable` |
 
 ### Previous: v3.8.0
 
@@ -172,7 +190,7 @@ Built to be robust and precise. Both read and write engines are tested against r
 
 ### `get_semantic_repo_map` Tool
 
-- **Max files**: Limited to 2000 files to prevent timeouts (increased from 500 in v3.9.0)
+- **Max files**: Limited to 2000 files to prevent timeouts (increased from 500 in v3.8.0)
 - **Performance**: Synchronous I/O may take 10-30 seconds on large repositories
 - **Recommendation**: Use `@folder` syntax to target specific directories
 
@@ -199,13 +217,13 @@ npx -y mcp-code-context
 
 ---
 
-## Session State (v3.9.0+)
+## Session State (v3.8.0+)
 
-**Important**: v3.9.0 introduces **session-scoped state** for each MCP client connection. This prevents state leakage when multiple agents (Amazon Q, Kiro, Cursor, etc.) use the same server instance.
+**Important**: v3.8.0 introduced **session-scoped state** for each MCP client connection. This prevents state leakage when multiple agents (Amazon Q, Kiro, Cursor, etc.) use the same server instance.
 
 ### What Changed
 
-| Before (v3.6.x) | After (v3.9.0) |
+| Before (v3.6.x) | After (v3.8.0+) |
 |----------------|----------------|
 | Global `LockManager` (shared by all clients) | Session-scoped `sessionStates` Map |
 | Global `ConfirmationStore` (in-memory Map) | Session-scoped confirmation store + SQLite persistence |
@@ -233,8 +251,11 @@ npx -y mcp-code-context
 }
 ```
 
-### New Tools (v3.9.0)
+### Ruby Intelligence Tools (v3.9.x)
 
+- `get_gemfile_context` — Parse Gemfile, get implicit gem behaviors (devise, sidekiq, pundit, etc.)
+- `find_metaprogramming` — Scan for `define_method`, `method_missing`, `class_eval`, concerns, `has_many :through`
+- `get_rails_routes` — Parse `config/routes.rb` into structured route map with namespace support
 - `get_session_stats` — Get stats for current session only
 - `clear_session_cache` — Clear cache for current session only
 - `list_pending_operations` — List pending operations for recovery
@@ -537,7 +558,7 @@ npm run dev
 - **Portability:** 100% WASM - no native dependencies, works on all platforms
 - **Tests:** 83 passing (unit + integration + performance + stress)
 
-### v3.9.0 Key Changes
+### Architectural Evolution (v3.8.0+)
 
 | Component | Change | Benefit |
 |-----------|--------|---------|

package/dist/src/core/engine.d.ts

@@ -1,5 +1,5 @@
 /**
- * Core Engine - v3.9.0
+ * Core Engine - v3.9.2
  * ASYNC I/O: Migrated to fs.promises
  */
 import { Parser, Language } from "web-tree-sitter";

package/dist/src/core/engine.js

@@ -1,5 +1,5 @@
 /**
- * Core Engine - v3.9.0
+ * Core Engine - v3.9.2
  * ASYNC I/O: Migrated to fs.promises
  */
 import { Parser, Language } from "web-tree-sitter";

package/dist/src/core/indexManager.d.ts

@@ -1,5 +1,5 @@
 /**
- * Index Manager - v3.9.0
+ * Index Manager - v3.9.2
  * Persistent symbol index and dependency graph in ~/.mcp-code-context/index/
  * Enables O(1) search_symbols and analyze_impact queries.
  */