sqlew 3.7.3 → 3.7.4

package/docs/cli/README.md

@@ -0,0 +1,227 @@
+# sqlew CLI Mode
+
+> Command-line tools for database migration and project data export/import
+
+## Overview
+
+sqlew provides CLI commands for advanced database operations that complement the main MCP server functionality. These
+commands are useful for database administration, backup/restore, and cross-project data migration.
+
+## What is CLI Mode?
+
+While the primary use of sqlew is as an **MCP server** (integrated with Claude Code via `.mcp.json`), it also provides
+standalone **CLI commands** for:
+
+- **Database Migration** - Generate SQL dumps for SQLite, MySQL, PostgresSQL migration
+- **Project Export/Import** - Share project data across databases or team members
+- **Backup/Restore** - Create SQL backups with schema and data
+
+## MCP Server vs CLI Mode
+
+| Feature         | MCP Server (`npx sqlew`)               | CLI Mode                                     |
+|-----------------|----------------------------------------|----------------------------------------------|
+| **Primary Use** | AI agent context management            | Database administration                      |
+| **Setup**       | `.mcp.json` configuration              | Per-project npm install                      |
+| **Commands**    | MCP tools (decision, task, file, etc.) | CLI commands (db:dump, db:export, db:import) |
+| **When to Use** | Daily AI development workflow          | Database migration, backup, data sharing     |
+
+## Installation
+
+### Install sqlew in Your Project
+
+```bash
+cd /path/to/your/project
+npm install sqlew
+```
+
+### Add npm Script Shortcut (Recommended)
+
+Add to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "sqlew": "node node_modules/sqlew/dist/cli.js"
+  }
+}
+```
+
+Then you can use shorter commands:
+
+```bash
+npm run sqlew db:dump --format=mysql --output=backup.sql
+```
+
+### Direct Command (Without Shortcut)
+
+```bash
+node node_modules/sqlew/dist/cli.js db:dump --format=mysql --output=backup.sql
+```
+
+## Available Commands
+
+### 1. `db:dump` - SQL Database Migration
+
+Generate complete SQL dumps (schema + data) for database migration or backup.
+
+**Use Cases**:
+
+- Full database backup with schema
+- Cross-database migration (SQLite → MySQL/PostgresSQL)
+- Development → Production deployment
+
+**Quick Example**:
+
+```bash
+# Backup SQLite to MySQL dump
+node node_modules/sqlew/dist/cli.js db:dump --format=mysql --output=backup.sql
+
+# Backup to PostgresSQL dump
+node node_modules/sqlew/dist/cli.js db:dump --format=postgresql --output=backup.sql
+```
+
+**📖 Full Documentation**: [DATABASE_MIGRATION.md](DATABASE_MIGRATION.md)
+
+---
+
+### 2. `db:export` - Project Data Export
+
+Export project data to JSON format for sharing or multi-project consolidation.
+
+**Use Cases**:
+
+- Share context with team members
+- Move projects between different databases
+- Consolidate multiple projects into one database
+
+**Quick Example**:
+
+```bash
+# Export specific project
+node node_modules/sqlew/dist/cli.js db:export --project=my-project --output=project.json
+
+# Export all projects
+node node_modules/sqlew/dist/cli.js db:export --output=all-projects.json
+```
+
+**📖 Full Documentation**: [DATA_EXPORT_IMPORT.md](DATA_EXPORT_IMPORT.md#export-command)
+
+---
+
+### 3. `db:import` - Project Data Import
+
+Import project data from JSON export files.
+
+**Use Cases**:
+
+- Import shared project context
+- Merge multiple projects into one database
+- Migrate projects to a new database (different machine or DB type)
+
+**Quick Example**:
+
+```bash
+# Import from JSON export
+node node_modules/sqlew/dist/cli.js db:import --source=project.json
+
+# Import with custom name
+node node_modules/sqlew/dist/cli.js db:import --source=project.json --project-name=new-name
+
+# Dry-run validation
+node node_modules/sqlew/dist/cli.js db:import --source=project.json --dry-run
+```
+
+**📖 Full Documentation**: [DATA_EXPORT_IMPORT.md](DATA_EXPORT_IMPORT.md#import-command)
+
+---
+
+## Quick Comparison: When to Use Which Command
+
+| Scenario                                      | Use Command               | Restore Capability         |
+|-----------------------------------------------|---------------------------|----------------------------|
+| **Full database backup**                      | `db:dump`                 | ✅ Full restore             |
+| **Cross-database migration** (SQLite → MySQL) | `db:dump`                 | ✅ Full restore             |
+| **Share project with team**                   | `db:export` / `db:import` | ⚠️ Skips if project exists |
+| **Consolidate multiple projects**             | `db:export` / `db:import` | ⚠️ Skips if project exists |
+| **Backup/restore same database**              | `db:dump`                 | ✅ Full restore             |
+
+**⚠️ Important**: `db:export`/`db:import` uses `--skip-if-exists=true` by default, so it's NOT suitable for
+backup/restore to the same database. Use `db:dump` for proper backup/restore.
+
+## Common Workflows
+
+### Workflow 1: Full Database Backup
+
+```bash
+# Create SQL backup with schema + data
+node node_modules/sqlew/dist/cli.js db:dump --format=sqlite --output=backup-$(date +%Y%m%d).sql
+
+# Or simple SQLite file copy
+cp .sqlew/sqlew.db .sqlew/backup-$(date +%Y%m%d).db
+```
+
+### Workflow 2: Share the Project with a Team Member
+
+```bash
+# Developer A: Export project
+node node_modules/sqlew/dist/cli.js db:export --project=feature-x --output=feature-x.json
+
+# Developer B: Import project (in their own database)
+node node_modules/sqlew/dist/cli.js db:import --source=feature-x.json
+```
+
+### Workflow 3: Migrate to MySQL from SQLite
+
+```bash
+# Step 1: Generate MySQL dump
+node node_modules/sqlew/dist/cli.js db:dump --format=mysql --output=migrate-to-mysql.sql
+
+# Step 2: Create MySQL database
+mysql -e "CREATE DATABASE sqlew_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
+
+# Step 3: Import dump
+mysql sqlew_db < migrate-to-mysql.sql
+```
+
+### Workflow 4: Consolidate Multiple Projects (Permission-Constrained)
+
+```bash
+# Export from each project
+cd ~/project-a && node node_modules/sqlew/dist/cli.js db:export --project=project-a --output=/tmp/a.json
+cd ~/project-b && node node_modules/sqlew/dist/cli.js db:export --project=project-b --output=/tmp/b.json
+
+# Import all to shared database
+cd ~/shared-db
+node node_modules/sqlew/dist/cli.js db:import --source=/tmp/a.json
+node node_modules/sqlew/dist/cli.js db:import --source=/tmp/b.json
+```
+
+## Getting Help
+
+Show command-specific help:
+
+```bash
+node node_modules/sqlew/dist/cli.js db:dump --help
+node node_modules/sqlew/dist/cli.js db:export --help
+node node_modules/sqlew/dist/cli.js db:import --help
+```
+
+## Detailed Documentation
+
+- **[DATABASE_MIGRATION.md](DATABASE_MIGRATION.md)** - Complete `db:dump` reference
+    - SQL dump generation for all database types
+    - Data type mappings
+    - Transaction safety
+    - Conflict resolution
+
+- **[DATA_EXPORT_IMPORT.md](DATA_EXPORT_IMPORT.md)** - Complete `db:export`/`db:import` reference
+    - JSON export/import system
+    - ID remapping strategy
+    - Multi-project consolidation
+    - Use cases and examples
+
+## See Also
+
+- [Main README](../../README.md) - MCP server setup and usage
+- [Configuration Guide](../CONFIGURATION.md) - Database configuration options
+- [Architecture](../ARCHITECTURE.md) - Technical architecture overview

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "sqlew",
-    "version": "3.7.3",
+    "version": "3.7.4",
     "description": "MCP server for efficient context sharing between Claude Code sub-agents (60-70% token reduction), Kanban Task Watcher, Decision or Constraint Context, and streamlined documentation",
     "main": "dist/index.js",
     "type": "module",
@@ -45,7 +45,8 @@
         "migrate:status": "npm run knex migrate:status",
         "seed:make": "npm run knex seed:make",
         "seed:run": "npm run knex seed:run",
-        "db:dump": "node dist/cli.js db:dump"
+        "db:dump": "node dist/cli.js db:dump",
+        "db:export": "node dist/cli.js db:export"
     },
     "engines": {
         "node": ">=18.0.0"

package/docs/BASEADAPTER_IMPLEMENTATION.md

@@ -1,399 +0,0 @@
-# BaseAdapter Implementation Summary
-
-## Overview
-
-The `BaseAdapter` abstract class has been successfully implemented as part of the multi-RDBMS adapter system (Issue #20, Task #67). This implementation integrates authentication providers with database adapters, providing a unified foundation for all database connections.
-
-## Implementation Details
-
-### File Structure
-
-```
-src/adapters/
-├── base-adapter.ts           # NEW: Abstract base class with auth integration
-├── sqlite-adapter.ts         # UPDATED: Now extends BaseAdapter
-├── postgresql-adapter.ts     # UPDATED: Now extends BaseAdapter (stub)
-├── mysql-adapter.ts          # UPDATED: Now extends BaseAdapter (stub)
-├── types.ts                  # UNCHANGED: DatabaseAdapter interface
-├── index.ts                  # UPDATED: Exports BaseAdapter, updated factory
-└── auth/
-    ├── base-auth-provider.ts  # Authentication provider base (completed)
-    ├── direct-auth-provider.ts # Direct connection auth (completed)
-    ├── auth-factory.ts        # Provider factory (completed)
-    └── auth-types.ts          # Type definitions (deprecated shim)
-```
-
-**Note**: SSH tunneling support was removed as of 2025-10-28. Users must set up SSH tunnels manually using the `ssh -L` command.
-
-### Key Features
-
-#### 1. **Authentication Integration**
-
-The BaseAdapter integrates with authentication providers through a factory pattern:
-
-```typescript
-export abstract class BaseAdapter implements DatabaseAdapter {
-  protected readonly config: DatabaseConfig;
-  protected authProvider: BaseAuthProvider | null = null;
-  protected knexInstance: Knex | null = null;
-
-  async connect(): Promise<Knex> {
-    // Create authentication provider
-    this.authProvider = createAuthProvider(this.config);
-
-    // Authenticate and get connection parameters
-    if (this.authProvider !== null) {
-      this.authProvider.validate();
-      const connParams = await this.authProvider.authenticate();
-      const knexConfig = this.buildKnexConfig(connParams);
-      this.knexInstance = knex(knexConfig);
-    }
-
-    // Initialize adapter-specific settings
-    await this.initialize();
-
-    return this.knexInstance;
-  }
-}
-```
-
-#### 2. **Connection Lifecycle Management**
-
-Complete lifecycle management with proper resource cleanup:
-
-- **connect()**: Authenticate → Create Knex instance → Initialize
-- **disconnect()**: Close Knex connection pool
-- **cleanup()**: Release auth provider resources (SSH tunnels, tokens)
-
-#### 3. **Abstract Methods**
-
-Subclasses must implement:
-
-- `initialize()`: Adapter-specific setup (pragmas, session settings)
-- `getDialect()`: Knex dialect identifier ('sqlite3', 'pg', 'mysql2')
-- Query adaptation methods (insertReturning, upsert, jsonExtract, etc.)
-
-#### 4. **Backward Compatibility**
-
-The implementation maintains full backward compatibility:
-
-- Existing `DatabaseAdapter` interface unchanged
-- Factory function supports both old and new signatures
-- SQLite adapter works exactly as before (bypasses auth flow)
-
-### Updated Adapters
-
-#### SQLite Adapter
-
-```typescript
-export class SQLiteAdapter extends BaseAdapter {
-  constructor(config: DatabaseConfig) {
-    super(config);
-  }
-
-  getDialect(): string {
-    return 'better-sqlite3';
-  }
-
-  async initialize(): Promise<void> {
-    const knex = this.getKnex();
-    // Configure SQLite pragmas
-    await knex.raw('PRAGMA journal_mode = WAL');
-    await knex.raw('PRAGMA foreign_keys = ON');
-    await knex.raw('PRAGMA synchronous = NORMAL');
-    await knex.raw('PRAGMA busy_timeout = 5000');
-  }
-
-  // Overrides connect() to bypass authentication
-  async connect(config?: Knex.Config): Promise<Knex> {
-    // SQLite doesn't need auth provider
-    this.knexInstance = knex(config || this.buildDefaultConfig());
-    this.rawConnection = await this.acquireRawConnection();
-    await this.initialize();
-    return this.knexInstance;
-  }
-}
-```
-
-#### PostgreSQL & MySQL Adapters (Stubs)
-
-Both adapters now extend BaseAdapter with proper constructors, but throw "not implemented" errors for Phase 3:
-
-```typescript
-export class PostgreSQLAdapter extends BaseAdapter {
-  constructor(config: DatabaseConfig) {
-    super(config);
-  }
-
-  getDialect(): string {
-    return 'pg';
-  }
-
-  async initialize(): Promise<void> {
-    throw new Error('PostgreSQL adapter not implemented yet. Planned for Phase 3.');
-  }
-}
-```
-
-### Factory Function Updates
-
-```typescript
-export function createDatabaseAdapter(
-  databaseType: 'sqlite' | 'postgresql' | 'mysql',
-  config?: DatabaseConfig
-): DatabaseAdapter {
-  // Build default config if not provided (backward compatibility)
-  const defaultConfig: DatabaseConfig = config || {
-    type: databaseType === 'postgresql' ? 'postgres' : databaseType,
-    connection: { host: '', port: 0, database: '' },
-    auth: { type: 'direct' },
-  };
-
-  switch (databaseType) {
-    case 'sqlite':
-      return new SQLiteAdapter(defaultConfig);
-    case 'postgresql':
-      return new PostgreSQLAdapter(defaultConfig);
-    case 'mysql':
-      return new MySQLAdapter(defaultConfig);
-  }
-}
-```
-
-## Usage Examples
-
-### Direct Database Connection
-
-```typescript
-import { PostgreSQLAdapter } from './adapters';
-import type { DatabaseConfig } from './config/types';
-
-const config: DatabaseConfig = {
-  type: 'postgres',
-  connection: {
-    host: 'localhost',
-    port: 5432,
-    database: 'mydb'
-  },
-  auth: {
-    type: 'direct',
-    user: 'postgres',
-    password: 'postgres'
-  }
-};
-
-const adapter = new PostgreSQLAdapter(config);
-
-try {
-  // Connect with authentication
-  await adapter.connect();
-
-  // Use Knex instance
-  const knex = adapter.getKnex();
-  const users = await knex('users').select('*');
-
-  console.log(users);
-} finally {
-  // Clean up resources
-  await adapter.disconnect();
-  await adapter.cleanup();
-}
-```
-
-### Manual SSH Tunnel Connection
-
-**Note**: SSH tunneling is NOT supported by this software. Users must set up SSH tunnels manually.
-
-**Step 1**: Set up SSH tunnel manually:
-```bash
-ssh -L 5433:db.internal:5432 deploy@bastion.example.com
-```
-
-**Step 2**: Configure adapter to use localhost:
-```typescript
-const config: DatabaseConfig = {
-  type: 'postgres',
-  connection: {
-    host: 'localhost',  // Tunnel endpoint
-    port: 5433,         // Forwarded port (not 5432!)
-    database: 'production'
-  },
-  auth: {
-    type: 'direct',
-    user: 'postgres',
-    password: 'dbpass'
-  }
-};
-
-const adapter = new PostgreSQLAdapter(config);
-
-try {
-  await adapter.connect(); // Connects through manual SSH tunnel
-  const knex = adapter.getKnex();
-  // ... use connection (tunneled through bastion host)
-} finally {
-  await adapter.disconnect(); // Close DB connection
-  await adapter.cleanup();    // Release auth resources
-}
-```
-
-### Transaction Support
-
-```typescript
-await adapter.transaction(async (trx) => {
-  await trx('accounts').where({ id: 1 }).decrement('balance', 100);
-  await trx('accounts').where({ id: 2 }).increment('balance', 100);
-  await trx('transfers').insert({ from: 1, to: 2, amount: 100 });
-});
-```
-
-## Testing
-
-### Test Results
-
-All existing tests pass with the new BaseAdapter implementation:
-
-```
-# tests 19
-# suites 11
-# pass 19
-# fail 0
-# cancelled 0
-# skipped 0
-```
-
-### Test Updates
-
-Two test files were updated to provide DatabaseConfig to SQLiteAdapter constructor:
-
-1. `src/tests/tasks.link-file-backward-compat.test.ts`
-2. `src/tests/tasks.watch-files-action.test.ts`
-
-Both tests now create SQLiteAdapter with proper configuration:
-
-```typescript
-const adapter = new SQLiteAdapter({
-  type: 'sqlite',
-  connection: { host: '', port: 0, database: ':memory:' },
-  auth: { type: 'direct' },
-});
-```
-
-## Design Principles
-
-### 1. **Separation of Concerns**
-
-- Authentication providers handle credentials and tokens (SSH tunnels removed - manual setup required)
-- Adapters handle database-specific operations
-- Clean interfaces between layers
-
-### 2. **Resource Safety**
-
-- Explicit cleanup methods for both DB and auth resources
-- Idempotent operations (safe to call connect/disconnect multiple times)
-- Error handling prevents resource leaks
-
-### 3. **Fail-Fast Validation**
-
-- Auth provider validates config before connection attempt
-- Clear error messages for misconfiguration
-- TypeScript type safety throughout
-
-### 4. **Extensibility**
-
-- Easy to add new authentication methods (AWS IAM, GCP IAM - SSH removed)
-- Easy to add new database adapters
-- Factory pattern abstracts provider selection
-
-## Implementation Statistics
-
-### AI Time & Token Estimates
-
-- **AI Time**: 25-30 minutes
-- **Token Usage**: ~76,500 tokens
-- **Complexity**: Medium (requires understanding of adapter pattern, auth integration, and backward compatibility)
-
-### Breakdown
-
-- Code reading and analysis: 5 minutes (~10k tokens)
-- BaseAdapter implementation: 8 minutes (~20k tokens)
-- Adapter updates (SQLite, PostgreSQL, MySQL): 7 minutes (~15k tokens)
-- Test updates and compilation fixes: 5 minutes (~15k tokens)
-- Testing and verification: 5 minutes (~16k tokens)
-
-## Next Steps
-
-### Phase 2: Database-Specific Adapters (Planned)
-
-1. **PostgreSQL Adapter Implementation** (Task #68)
-   - Full PostgreSQL query adaptations
-   - Connection pool configuration
-   - PostgreSQL-specific features (JSONB, arrays, etc.)
-
-2. **MySQL Adapter Implementation** (Task #69)
-   - Full MySQL query adaptations
-   - Connection pool configuration
-   - MySQL-specific features
-
-### Phase 3: Advanced Features (Future)
-
-1. **AWS IAM Authentication** (v3.8.0+)
-   - RDS IAM authentication provider
-   - Temporary token generation
-   - SSL/TLS certificate management
-
-2. **GCP IAM Authentication** (v3.8.0+)
-   - Cloud SQL IAM authentication provider
-   - OAuth token handling
-   - Cloud SQL proxy integration
-
-## Files Modified
-
-### New Files
-
-- `/home/kitayama/TypeScriptProject/mcp-sqlew/src/adapters/base-adapter.ts` (690 lines)
-
-### Modified Files
-
-- `/home/kitayama/TypeScriptProject/mcp-sqlew/src/adapters/sqlite-adapter.ts`
-- `/home/kitayama/TypeScriptProject/mcp-sqlew/src/adapters/postgresql-adapter.ts`
-- `/home/kitayama/TypeScriptProject/mcp-sqlew/src/adapters/mysql-adapter.ts`
-- `/home/kitayama/TypeScriptProject/mcp-sqlew/src/adapters/index.ts`
-- `/home/kitayama/TypeScriptProject/mcp-sqlew/src/adapters/auth/auth-factory.ts` (JSDoc fix)
-- `/home/kitayama/TypeScriptProject/mcp-sqlew/src/tests/tasks.link-file-backward-compat.test.ts`
-- `/home/kitayama/TypeScriptProject/mcp-sqlew/src/tests/tasks.watch-files-action.test.ts`
-
-## Documentation
-
-### Comprehensive JSDoc
-
-The BaseAdapter includes extensive documentation:
-
-- Class-level documentation with usage examples
-- Method-level documentation with parameter descriptions
-- Example code for common patterns
-- Error handling guidance
-- Resource management best practices
-
-### Key Documentation Sections
-
-1. **Connection Flow**: Step-by-step explanation of connection establishment
-2. **Authentication Integration**: How auth providers are used
-3. **Resource Lifecycle**: When to call connect/disconnect/cleanup
-4. **Transaction Support**: How to use transactions safely
-5. **Abstract Methods**: What subclasses must implement
-
-## Conclusion
-
-The BaseAdapter implementation successfully integrates authentication providers with database adapters while maintaining full backward compatibility. The design is extensible, well-documented, and type-safe, providing a solid foundation for the multi-RDBMS migration.
-
-### Key Achievements
-
-✅ Authentication provider integration via factory pattern
-✅ Complete connection lifecycle management
-✅ Backward compatibility with existing code
-✅ Comprehensive error handling
-✅ Full test coverage (all tests pass)
-✅ Extensive documentation and examples
-✅ Type-safe implementation throughout
-✅ Prepared for Phase 2 (PostgreSQL/MySQL) and Phase 3 (Cloud IAM)