# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [5.0.2] - 2026-05-28

### Fixed
- **`smart_read` crashed with `Cannot read properties of undefined (reading 'map')`**
  - Root cause: `validateToolArgs` read `error.errors`, which zod v4 removed in
    favor of `error.issues`. Any failed validation (e.g. a wrong argument key)
    hit `undefined.map`.
  - Now reads `error.issues ?? error.errors ?? []`, so error formatting works on
    both zod v3 and v4 and can never crash on a malformed `ZodError`.
- **`smart_read` now validates its `path` argument**
  - Passing a missing/blank path (e.g. the wrong key `file_path`) returned an
    opaque downstream error. It now fails fast with
    `smart_read requires a non-empty "path" argument`.

### Docs
- Rewrote `docs/TESTING_INSTRUCTIONS.md` for the WSL2/Linux native port:
  correct `path` argument, daemon/`invoke-mcp.js` invocation, WSL paths
  (`dispatcher.log`, `~/.token-optimizer-cache/cache.db`), the dedup-based
  Read interception model, and a regression test for the `.map` crash.

## [2.20.0] - 2025-10-30

### Fixed
- **Fixed flaky performance tests in CI/CD pipeline**
  - Increased timeout from 200ms to 500ms in path-traversal.test.ts
  - Accounts for CI environment variability
  - Prevents intermittent release workflow failures
  - All performance benchmarks now stable across all Node.js versions

### Changed
- **Complete repository cleanup and organization**
  - Removed 75+ junk files (archive/, AGENT_*.md, *REPORT.md, fix scripts)
  - Moved 13 documentation files to docs/ folder for better organization
  - Moved utility files to proper locations (scripts/, examples/)
  - Removed duplicate documentation files
  - Clean, professional root directory structure

### Security
- **Removed committed secrets from repository**
  - Deleted .mcpregistry_registry_token (contained JWT token)
  - Enhanced .gitignore to prevent re-adding token files
  - Added comprehensive patterns for secrets and temporary files

### Improved
- **Enhanced .gitignore patterns**
  - Comprehensive patterns per CLAUDE.md policies
  - Prevents report/investigation files
  - Blocks temporary scripts and lock files
  - Excludes worktrees and ${HOME}/ artifacts

## [2.4.0] - 2025-10-20

### Fixed
- **CRITICAL: Enabled actual token savings by leveraging smart_read MCP tool's built-in caching**
  - **Previous implementation (v2.4.0-beta)** tried to manually manage cache via hooks but conflicted with user enforcers
  - **Root cause**: Redundant caching layers - hooks duplicated what smart_read already provides
  - **Correct architecture**: Use smart_read MCP tool in PreToolUse hook instead of plain Read
  - smart_read has sophisticated built-in caching with SQLite persistence, diffing, and truncation
  - All Read operations now automatically leverage smart_read's cache-aware intelligence
  - Removed redundant `Handle-CacheRetrieval` and `Handle-AutoCache` functions
  - Added `Handle-SmartRead` that calls smart_read MCP tool directly
  - Runs BEFORE user enforcers to ensure caching takes priority
  - Enables both multi-read savings (same session) and cross-session savings (SQLite persistence)

### Added
- `Handle-SmartRead` function in token-optimizer-orchestrator.ps1 (PreToolUse phase)
- `smart-read` action in orchestrator switch statement
- Comprehensive logging for cache hits/misses, diffs, and token savings
- PreToolUse smart_read intercept in dispatcher.ps1 for all Read operations
- Graceful fallback to plain Read if smart_read fails

### Technical Details
- **smart_read MCP tool** (src/tools/file-operations/smart-read.ts):
  - Built-in CacheEngine with SQLite persistence + in-memory LRU cache
  - Automatic cache key generation based on file path and options
  - Gzip compression for cached content
  - Diff mode: Returns only changes if file was previously read
  - Truncation: Intelligently limits large files to maxSize (default 100KB)
  - Chunking: Breaks very large files into manageable pieces
- **Hook architecture**:
  - PreToolUse: Calls smart_read instead of allowing plain Read
  - If smart_read succeeds: Blocks plain Read and returns cached/optimized content
  - If smart_read fails: Falls back to plain Read gracefully
  - No PostToolUse caching needed - smart_read handles it internally
- **Cache keys**: Use absolute file paths for cross-session persistence
- **Token savings**:
  - Cache hit: Returns compressed content (typical 85-95% reduction)
  - Diff mode: Returns only changes (typical 95-99% reduction for minor edits)
  - Truncation: Caps large files at 100KB (configurable)

### Performance Impact
- **Multi-read scenario**: Second read of same file returns cached version (85-95% token savings)
- **Cross-session scenario**: Files cached in session 1 instantly available in session 2
- **Diff scenario**: File re-read after minor edits returns only diff (95-99% token savings)
- **Large files**: Auto-truncated to 100KB max, preventing token overflow
- **Estimated overall reduction**: 70-90% across typical coding sessions

## [2.3.0] - 2025-10-19

### Added
- **CLI Wrapper** (`cli-wrapper.mjs`) - One-shot execution for PowerShell hooks integration
  - Three input modes: stdin (recommended for PowerShell), file, and arguments
  - Zero JSON escaping issues using stdin piping
  - Production-ready error handling and validation
  - Fast execution: <200ms end-to-end
- **PowerShell Hooks Integration** - Complete hooks system in `hooks/` directory
  - `dispatcher.ps1` - Main orchestrator for all hook events
  - `token-optimizer-orchestrator.ps1` - Unified handler for optimization operations
  - `invoke-token-optimizer.ps1` - PowerShell helper using stdin approach
  - `invoke-mcp.ps1` - Generic MCP tool invocation helper
  - Automatic MCP enforcement (blocks git CLI, blocks Read/Grep on code files)
  - Context guard with intelligent optimization triggers
  - Session tracking and analytics
  - Cache warmup and periodic optimization
- **CLI Wrapper Documentation** (`CLI_WRAPPER_README.md`) - Comprehensive usage guide
- **Hooks Documentation** (`hooks/README.md`) - Setup and architecture guide

### Changed
- Package now includes `cli-wrapper.mjs` and `hooks/` directory in distribution
- Updated version from 0.2.0 to 0.3.0

### Technical Details
- Solution for PowerShell-to-Node.js JSON escaping recommended by Google Gemini 2.5 Flash
- Stdin piping avoids all shell escaping issues across Windows/Unix
- Hooks work seamlessly with Claude Code lifecycle events
- Zero manual intervention - fully automated token optimization

## [0.2.0] - 2025-10-19

### Added
- Complete npm package configuration for public publishing
- Comprehensive .npmignore for optimized package size
- Package validation and installation testing scripts
- Pre-publish checklist documentation
- Proper package.json metadata (keywords, author, engines)
- Binary entry point configuration for CLI usage
- Export maps for modern Node.js module resolution

### Changed
- Updated package version from 0.1.0 to 0.2.0
- Changed main entry point to dist/server/index.js (MCP server)
- Updated license from ISC to MIT
- Enhanced build and test scripts for CI/CD compatibility

### Fixed
- Package structure optimized for npm distribution
- Entry point validation and shebang verification

## [0.1.0] - 2025-01-XX

### Added
- Initial release of Token Optimizer MCP
- Core caching engine with SQLite persistence
- Token counting using tiktoken (GPT-4 tokenizer)
- Brotli compression for optimal token efficiency
- MCP server implementation with stdio transport
- Dashboard monitoring and visualization tools
- Intelligent caching strategies (predictive cache, cache warmup)
- Session log parsing and analysis
- Project-wide token optimization analysis
- Metrics collection and reporting
- Advanced file operations with caching
- Build system integration tools
- Code analysis and intelligence tools
- Smart output formatting with compression
- System operations with intelligent scheduling

### Core Features
- optimize_text - Compress and cache text to reduce token usage
- get_cached - Retrieve previously cached and optimized text
- count_tokens - Count tokens in text using tiktoken
- compress_text - Compress text using Brotli compression
- decompress_text - Decompress base64-encoded Brotli-compressed text
- get_cache_stats - Get cache statistics including hit rate and compression ratio
- clear_cache - Clear all cached data
- analyze_optimization - Analyze text and get optimization recommendations

### Technical Stack
- Node.js 18+ runtime
- TypeScript for type safety
- SQLite (better-sqlite3) for persistent storage
- tiktoken for accurate token counting
- Brotli compression (built-in)
- LRU caching for in-memory optimization
- MCP SDK for protocol implementation

[0.2.0]: https://github.com/ooples/token-optimizer-mcp/compare/v0.1.0...v0.2.0
[0.1.0]: https://github.com/ooples/token-optimizer-mcp/releases/tag/v0.1.0
