sqlew 1.1.1 → 2.0.0

package/CHANGELOG.md

@@ -5,6 +5,94 @@ All notable changes to sqlew 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).
 
+## [2.0.0] - 2025-10-11
+
+### 🚨 BREAKING CHANGES
+
+**This is a major release with breaking API changes. Migration required for all v1.x users.**
+
+#### Tool Consolidation
+- **20 individual tools** → **6 action-based tools** (70% reduction)
+- All tools now use action-based routing with `action` parameter
+- Tool names completely changed (see migration guide below)
+
+#### Old vs New Tool Names
+
+| Old (v1.x) | New (v2.0) | Actions |
+|------------|------------|---------|
+| `set_decision`, `get_decision`, `get_context`, `search_by_tags`, `search_by_layer`, `get_versions` | `decision` | `set`, `get`, `list`, `search_tags`, `search_layer`, `versions`, `help` |
+| `send_message`, `get_messages`, `mark_read` | `message` | `send`, `get`, `mark_read`, `help` |
+| `record_file_change`, `get_file_changes`, `check_file_lock` | `file` | `record`, `get`, `check_lock`, `help` |
+| `add_constraint`, `get_constraints`, `deactivate_constraint` | `constraint` | `add`, `get`, `deactivate`, `help` |
+| `get_layer_summary`, `get_stats`, `clear_old_data` | `stats` | `layer_summary`, `db_stats`, `clear`, `help` |
+| `get_config`, `update_config` | `config` | `get`, `update`, `help` |
+
+### Added
+
+- **Help Actions:** All 6 tools now support `action: "help"` for comprehensive on-demand documentation
+  - Returns detailed usage, parameters, and examples
+  - Zero token cost until explicitly called
+- **Action Hints:** Tool descriptions now include available actions for better discoverability
+- **Improved Token Efficiency:** 96% token reduction vs traditional JSON approach
+  - Tool definition tokens: ~12,848 → ~481 tokens (96.3% reduction)
+  - MCP context usage: ~13,730 → ~4,482 tokens (67% reduction)
+
+### Changed
+
+- **API Surface:** Complete redesign to action-based routing
+  - All tools require `action` parameter
+  - Parameters consolidated into single input schema per tool
+  - Nested switch statement routing for better maintainability
+- **Tool Descriptions:** Simplified with action hints in parentheses
+- **File Size:** Source reduced 27.4% (25,373 → 18,410 bytes) while adding help docs
+
+### Technical Details
+
+- Action-based routing with two-level switch statements
+- Shared parameter schemas across actions within each tool
+- Enum deduplication (layer, status, priority defined once per tool)
+- On-demand documentation via help actions
+- 100% backward compatible database schema (no DB changes)
+
+### Migration Required
+
+**v1.x users must update their tool calls:**
+
+```javascript
+// OLD (v1.x)
+await callTool('set_decision', { key: 'auth', value: 'jwt' });
+await callTool('get_messages', { unread_only: true });
+
+// NEW (v2.0)
+await callTool('decision', { action: 'set', key: 'auth', value: 'jwt' });
+await callTool('message', { action: 'get', unread_only: true });
+```
+
+See `MIGRATION_v2.md` for complete migration guide.
+
+### Performance
+
+- 96% token reduction in tool definitions
+- 67% reduction in MCP context consumption
+- Same database performance (no schema changes)
+- Same query response times
+
+## [1.1.2] - 2025-10-11
+
+### Fixed
+- **Schema Validation Bug:** Fixed validation checking for old unprefixed table names instead of new prefixed names
+  - Updated `requiredTables` to check for `m_*` and `t_*` prefixed names
+  - Updated `requiredViews` to check for `v_*` prefixed names
+  - Updated `requiredTriggers` to check for `trg_*` prefixed names
+- **Migration Missing Views/Triggers:** After migration, views and triggers are now created automatically
+  - Added `initializeSchema()` call after successful migration
+  - Ensures v1.0.0 → v1.1.x migration creates all required database objects
+
+### Technical Details
+- Migration now runs schema initialization after table renaming to create views/triggers
+- Schema validation properly detects v1.1.x databases with prefixed names
+- Full backward compatibility maintained with v1.0.0 databases
+
 ## [1.1.1] - 2025-10-11
 
 ### Fixed
@@ -164,6 +252,8 @@ First production release of sqlew - MCP server for efficient context sharing bet
 - Full type safety
 - Comprehensive error handling
 
+[2.0.0]: https://github.com/sin5ddd/mcp-sqlew/releases/tag/v2.0.0
+[1.1.2]: https://github.com/sin5ddd/mcp-sqlew/releases/tag/v1.1.2
 [1.1.1]: https://github.com/sin5ddd/mcp-sqlew/releases/tag/v1.1.1
 [1.1.0]: https://github.com/sin5ddd/mcp-sqlew/releases/tag/v1.1.0
 [1.0.1]: https://github.com/sin5ddd/mcp-sqlew/releases/tag/v1.0.1

package/MIGRATION_v2.md

@@ -0,0 +1,538 @@
+# Migration Guide: v1.x → v2.0.0
+
+This guide helps you migrate from sqlew v1.x to v2.0.0. The v2.0 release consolidates 20 individual tools into 6 action-based tools for 96% token reduction.
+
+## Breaking Changes Summary
+
+### What Changed
+- **Tool Names:** All 20 tool names changed
+- **API Structure:** All tools now use action-based routing with an `action` parameter
+- **Tool Count:** 20 → 6 tools
+
+### What Didn't Change
+- **Database Schema:** 100% compatible - no migration needed ✅
+- **Functionality:** All 20 original functions preserved
+- **Parameters:** Same parameter names and types (except `action` is now required)
+- **Return Values:** Identical response structures
+
+## Database Compatibility
+
+**Good news:** Your v1.x database works with v2.0 without any changes!
+
+- ✅ v1.x database → v2.0 server (works immediately)
+- ✅ v2.0 database → v1.x server (if you need to downgrade)
+- ✅ No data migration required
+- ✅ No schema changes
+
+The v2.0 consolidation is purely an MCP interface redesign - the database layer is unchanged.
+
+## Tool Mapping Reference
+
+| v1.x Tool | v2.0 Tool | Action |
+|-----------|-----------|--------|
+| `set_decision` | `decision` | `set` |
+| `get_decision` | `decision` | `get` |
+| `get_context` | `decision` | `list` |
+| `search_by_tags` | `decision` | `search_tags` |
+| `search_by_layer` | `decision` | `search_layer` |
+| `get_versions` | `decision` | `versions` |
+| `send_message` | `message` | `send` |
+| `get_messages` | `message` | `get` |
+| `mark_read` | `message` | `mark_read` |
+| `record_file_change` | `file` | `record` |
+| `get_file_changes` | `file` | `get` |
+| `check_file_lock` | `file` | `check_lock` |
+| `add_constraint` | `constraint` | `add` |
+| `get_constraints` | `constraint` | `get` |
+| `deactivate_constraint` | `constraint` | `deactivate` |
+| `get_layer_summary` | `stats` | `layer_summary` |
+| `get_stats` | `stats` | `db_stats` |
+| `clear_old_data` | `stats` | `clear` |
+| `get_config` | `config` | `get` |
+| `update_config` | `config` | `update` |
+
+## Migration Examples
+
+### Context Management
+
+**v1.x:**
+```typescript
+// Set decision
+await callTool('set_decision', {
+  key: 'auth_method',
+  value: 'JWT',
+  tags: ['security']
+});
+
+// Get decision
+await callTool('get_decision', {
+  key: 'auth_method'
+});
+
+// Search by tags
+await callTool('search_by_tags', {
+  tags: ['security', 'api'],
+  match_mode: 'AND'
+});
+```
+
+**v2.0:**
+```typescript
+// Set decision
+await callTool('decision', {
+  action: 'set',
+  key: 'auth_method',
+  value: 'JWT',
+  tags: ['security']
+});
+
+// Get decision
+await callTool('decision', {
+  action: 'get',
+  key: 'auth_method'
+});
+
+// Search by tags
+await callTool('decision', {
+  action: 'search_tags',
+  tags: ['security', 'api'],
+  tag_match: 'AND'  // Note: parameter renamed from match_mode
+});
+```
+
+### Messaging
+
+**v1.x:**
+```typescript
+// Send message
+await callTool('send_message', {
+  from_agent: 'agent1',
+  to_agent: 'agent2',
+  message: 'Task complete',
+  priority: 'high'
+});
+
+// Get messages
+await callTool('get_messages', {
+  unread_only: true
+});
+
+// Mark as read
+await callTool('mark_read', {
+  message_ids: [1, 2, 3]
+});
+```
+
+**v2.0:**
+```typescript
+// Send message
+await callTool('message', {
+  action: 'send',
+  from_agent: 'agent1',
+  to_agent: 'agent2',
+  message: 'Task complete',
+  priority: 'high'
+});
+
+// Get messages
+await callTool('message', {
+  action: 'get',
+  unread_only: true
+});
+
+// Mark as read
+await callTool('message', {
+  action: 'mark_read',
+  message_ids: [1, 2, 3]
+});
+```
+
+### File Tracking
+
+**v1.x:**
+```typescript
+// Record file change
+await callTool('record_file_change', {
+  file_path: '/src/auth.ts',
+  agent_name: 'auth-agent',
+  change_type: 'modified',
+  layer: 'business'
+});
+
+// Get file changes
+await callTool('get_file_changes', {
+  since: '2025-01-10T10:00:00Z'
+});
+
+// Check file lock
+await callTool('check_file_lock', {
+  file_path: '/src/auth.ts'
+});
+```
+
+**v2.0:**
+```typescript
+// Record file change
+await callTool('file', {
+  action: 'record',
+  file_path: '/src/auth.ts',
+  agent_name: 'auth-agent',
+  change_type: 'modified',
+  layer: 'business'
+});
+
+// Get file changes
+await callTool('file', {
+  action: 'get',
+  since: '2025-01-10T10:00:00Z'
+});
+
+// Check file lock
+await callTool('file', {
+  action: 'check_lock',
+  file_path: '/src/auth.ts'
+});
+```
+
+### Constraints
+
+**v1.x:**
+```typescript
+// Add constraint
+await callTool('add_constraint', {
+  category: 'performance',
+  constraint_text: 'Response time < 200ms',
+  priority: 'high'
+});
+
+// Get constraints
+await callTool('get_constraints', {
+  category: 'performance'
+});
+
+// Deactivate constraint
+await callTool('deactivate_constraint', {
+  constraint_id: 42
+});
+```
+
+**v2.0:**
+```typescript
+// Add constraint
+await callTool('constraint', {
+  action: 'add',
+  category: 'performance',
+  constraint_text: 'Response time < 200ms',
+  priority: 'high'
+});
+
+// Get constraints
+await callTool('constraint', {
+  action: 'get',
+  category: 'performance'
+});
+
+// Deactivate constraint
+await callTool('constraint', {
+  action: 'deactivate',
+  constraint_id: 42
+});
+```
+
+### Utilities
+
+**v1.x:**
+```typescript
+// Layer summary
+await callTool('get_layer_summary');
+
+// Database stats
+await callTool('get_stats');
+
+// Clear old data
+await callTool('clear_old_data', {
+  messages_older_than_hours: 48
+});
+```
+
+**v2.0:**
+```typescript
+// Layer summary
+await callTool('stats', {
+  action: 'layer_summary'
+});
+
+// Database stats
+await callTool('stats', {
+  action: 'db_stats'
+});
+
+// Clear old data
+await callTool('stats', {
+  action: 'clear',
+  messages_older_than_hours: 48
+});
+```
+
+### Configuration
+
+**v1.x:**
+```typescript
+// Get config
+await callTool('get_config');
+
+// Update config
+await callTool('update_config', {
+  ignoreWeekend: true,
+  messageRetentionHours: 48
+});
+```
+
+**v2.0:**
+```typescript
+// Get config
+await callTool('config', {
+  action: 'get'
+});
+
+// Update config
+await callTool('config', {
+  action: 'update',
+  ignoreWeekend: true,
+  messageRetentionHours: 48
+});
+```
+
+## New Feature: Help Actions
+
+v2.0 adds `action: "help"` to all tools for on-demand comprehensive documentation:
+
+```typescript
+// Get help for any tool
+await callTool('decision', { action: 'help' });
+await callTool('message', { action: 'help' });
+await callTool('file', { action: 'help' });
+await callTool('constraint', { action: 'help' });
+await callTool('stats', { action: 'help' });
+await callTool('config', { action: 'help' });
+```
+
+Each help action returns:
+- Tool description
+- Complete action list with parameters
+- Usage examples
+- Parameter requirements
+
+**Zero token cost** until explicitly called!
+
+## Migration Checklist
+
+### 1. Update Package
+```bash
+npm install sqlew@2.0.0
+# or
+npm update sqlew
+```
+
+### 2. Update Tool Calls
+
+Search your codebase for v1.x tool calls:
+
+```bash
+# Find all v1.x tool calls
+grep -r "set_decision\|get_decision\|get_context\|search_by_tags" .
+grep -r "send_message\|get_messages\|mark_read" .
+grep -r "record_file_change\|get_file_changes\|check_file_lock" .
+grep -r "add_constraint\|get_constraints\|deactivate_constraint" .
+grep -r "get_layer_summary\|get_stats\|clear_old_data" .
+grep -r "get_config\|update_config" .
+```
+
+Replace each with v2.0 equivalent using the mapping table above.
+
+### 3. Test Your Changes
+
+Use MCP Inspector to verify tool calls:
+
+```bash
+npx @modelcontextprotocol/inspector npx sqlew
+```
+
+Test each migrated tool call to ensure:
+- ✅ Correct tool name
+- ✅ `action` parameter included
+- ✅ All other parameters unchanged
+- ✅ Response structure matches expectations
+
+### 4. Verify Database Works
+
+Your existing database should work immediately with v2.0:
+
+```bash
+# Start v2.0 server with your existing database
+npx sqlew /path/to/your/existing/v1.db
+
+# Test a few operations
+# Your data should be intact
+```
+
+## Parameter Changes
+
+### search_by_tags
+
+**v1.x:** `match_mode` parameter
+**v2.0:** `tag_match` parameter
+
+```typescript
+// v1.x
+search_by_tags({ tags: ['api'], match_mode: 'AND' })
+
+// v2.0
+decision({ action: 'search_tags', tags: ['api'], tag_match: 'AND' })
+```
+
+All other parameters remain unchanged.
+
+## Common Pitfalls
+
+### ❌ Forgetting `action` Parameter
+
+```typescript
+// WRONG - will fail
+await callTool('decision', { key: 'auth_method' });
+
+// CORRECT
+await callTool('decision', { action: 'get', key: 'auth_method' });
+```
+
+### ❌ Using Old Tool Names
+
+```typescript
+// WRONG - tool doesn't exist
+await callTool('set_decision', { action: 'set', key: 'auth' });
+
+// CORRECT
+await callTool('decision', { action: 'set', key: 'auth' });
+```
+
+### ❌ Wrong Action Name
+
+```typescript
+// WRONG - action doesn't exist
+await callTool('decision', { action: 'search_tags', match_mode: 'AND' });
+
+// CORRECT - parameter also renamed
+await callTool('decision', { action: 'search_tags', tag_match: 'AND' });
+```
+
+## Rollback Plan
+
+If you need to rollback to v1.x:
+
+```bash
+# Downgrade package
+npm install sqlew@1.1.2
+
+# Your database will continue to work
+# No schema migration needed
+```
+
+Your v2.0 database is 100% compatible with v1.x servers.
+
+## Benefits of v2.0
+
+After migration, you'll enjoy:
+
+- **96% Token Reduction:** Tool definitions use 481 tokens instead of 12,848
+- **67% MCP Context Reduction:** From ~13,730 to ~4,482 tokens
+- **On-Demand Help:** Use `action: "help"` for comprehensive documentation
+- **Same Functionality:** All 20 original functions preserved
+- **Better Organization:** Related operations grouped into single tools
+
+## Support
+
+Need help with migration?
+
+- **Issues:** [GitHub Issues](https://github.com/sin5ddd/mcp-sqlew/issues)
+- **Changelog:** See [CHANGELOG.md](CHANGELOG.md) for complete v2.0 details
+- **Documentation:** Updated [README.md](README.md) with v2.0 examples
+
+## Example: Complete Migration
+
+Here's a complete before/after example showing typical usage:
+
+### Before (v1.x)
+
+```typescript
+// Set up authentication decision
+await callTool('set_decision', {
+  key: 'auth_method',
+  value: 'JWT',
+  tags: ['security', 'api'],
+  layer: 'business'
+});
+
+// Send notification
+await callTool('send_message', {
+  from_agent: 'auth-agent',
+  to_agent: 'api-agent',
+  message: 'Auth configured',
+  priority: 'high'
+});
+
+// Track file change
+await callTool('record_file_change', {
+  file_path: '/src/auth.ts',
+  agent_name: 'auth-agent',
+  change_type: 'created',
+  layer: 'business'
+});
+
+// Add constraint
+await callTool('add_constraint', {
+  category: 'security',
+  constraint_text: 'Use JWT with RS256',
+  priority: 'critical'
+});
+```
+
+### After (v2.0)
+
+```typescript
+// Set up authentication decision
+await callTool('decision', {
+  action: 'set',
+  key: 'auth_method',
+  value: 'JWT',
+  tags: ['security', 'api'],
+  layer: 'business'
+});
+
+// Send notification
+await callTool('message', {
+  action: 'send',
+  from_agent: 'auth-agent',
+  to_agent: 'api-agent',
+  message: 'Auth configured',
+  priority: 'high'
+});
+
+// Track file change
+await callTool('file', {
+  action: 'record',
+  file_path: '/src/auth.ts',
+  agent_name: 'auth-agent',
+  change_type: 'created',
+  layer: 'business'
+});
+
+// Add constraint
+await callTool('constraint', {
+  action: 'add',
+  category: 'security',
+  constraint_text: 'Use JWT with RS256',
+  priority: 'critical'
+});
+```
+
+Only changes: tool names and added `action` parameters. All other parameters identical!