sqlew 4.0.0 → 4.0.2

package/docs/cli/README.md

@@ -7,55 +7,62 @@
 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.
 
+> **⚠️ Important**: Database CLI commands must be run via `npm run` from the project directory.
+> `npx` is not supported for database operations.
+
 ## 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
+- **Database Migration** - Generate SQL dumps for SQLite, MySQL, PostgreSQL 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                                     |
+| Feature         | MCP Server (via `.mcp.json`)           | 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
+## Usage
+
+### Within mcp-sqlew Project (Development)
 
-### Install sqlew in Your Project
+Use npm scripts with `--` to pass arguments:
 
 ```bash
-cd /path/to/your/project
-npm install sqlew
+# Generate MySQL dump
+npm run db:dump -- mysql backup.sql
+
+# Export project to JSON
+npm run db:export -- data.json project=myproject
+
+# Import from JSON
+npm run db:import -- data.json
 ```
 
-### Add npm Script Shortcut (Recommended)
+### In Projects with sqlew as Dependency
 
 Add to your `package.json`:
 
 ```json
 {
   "scripts": {
-    "sqlew": "node node_modules/sqlew/dist/cli.js"
+    "db:dump": "node node_modules/sqlew/dist/cli.js db:dump",
+    "db:export": "node node_modules/sqlew/dist/cli.js db:export",
+    "db:import": "node node_modules/sqlew/dist/cli.js db:import"
   }
 }
 ```
 
-Then you can use shorter commands:
-
-```bash
-npm run sqlew db:dump --format=mysql --output=backup.sql
-```
-
-### Direct Command (Without Shortcut)
+Then use:
 
 ```bash
-node node_modules/sqlew/dist/cli.js db:dump --format=mysql --output=backup.sql
+npm run db:dump -- mysql backup.sql
 ```
 
 ## Available Commands
@@ -67,17 +74,20 @@ Generate complete SQL dumps (schema + data) for database migration or backup.
 **Use Cases**:
 
 - Full database backup with schema
-- Cross-database migration (SQLite → MySQL/PostgresSQL)
+- Cross-database migration (SQLite → MySQL/PostgreSQL)
 - 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
+# Generate MySQL dump (positional format argument)
+npm run db:dump -- mysql backup.sql
+
+# Generate PostgreSQL dump
+npm run db:dump -- postgresql backup.sql
 
-# Backup to PostgresSQL dump
-node node_modules/sqlew/dist/cli.js db:dump --format=postgresql --output=backup.sql
+# MySQL from PostgreSQL source
+npm run db:dump -- mysql backup.sql from=postgresql
 ```
 
 **📖 Full Documentation**: [DATABASE_MIGRATION.md](DATABASE_MIGRATION.md)
@@ -98,10 +108,10 @@ Export project data to JSON format for sharing or multi-project consolidation.
 
 ```bash
 # Export specific project
-node node_modules/sqlew/dist/cli.js db:export --project=my-project --output=project.json
+npm run db:export -- project.json project=my-project
 
 # Export all projects
-node node_modules/sqlew/dist/cli.js db:export --output=all-projects.json
+npm run db:export -- all-projects.json
 ```
 
 **📖 Full Documentation**: [DATA_EXPORT_IMPORT.md](DATA_EXPORT_IMPORT.md#export-command)
@@ -122,28 +132,69 @@ Import project data from JSON export files.
 
 ```bash
 # Import from JSON export
-node node_modules/sqlew/dist/cli.js db:import --source=project.json
+npm run db:import -- project.json
 
 # Import with custom name
-node node_modules/sqlew/dist/cli.js db:import --source=project.json --project-name=new-name
+npm run db:import -- project.json project-name=new-name
 
 # Dry-run validation
-node node_modules/sqlew/dist/cli.js db:import --source=project.json --dry-run
+npm run db:import -- project.json dry-run=true
 ```
 
 **📖 Full Documentation**: [DATA_EXPORT_IMPORT.md](DATA_EXPORT_IMPORT.md#import-command)
 
 ---
 
+## Recommended Data Migration Workflow
+
+### Cross-Database Migration (Recommended: JSON)
+
+For migrations between different database systems (e.g., SQLite to MySQL, PostgreSQL to MySQL), **use JSON format**:
+
+```bash
+# Step 1: Export from source database
+npm run db:export -- backup.json
+
+# Step 2: Configure target database connection
+# (Update your .sqlew/config.toml or environment variables)
+
+# Step 3: Import to target database
+npm run db:import -- backup.json
+```
+
+**Why JSON for cross-database migration?**
+- Database-agnostic format - no SQL syntax differences
+- Automatic ID remapping handles foreign key relationships
+- Preserves all data integrity across different RDBMS
+
+### SQL Dump (Same-RDBMS Only)
+
+SQL dump (`db:dump`) is designed for **same-database-type operations only**:
+
+```bash
+# SQLite backup (restore to SQLite)
+npm run db:dump -- sqlite backup.sql
+
+# MySQL backup (restore to MySQL)
+npm run db:dump -- mysql backup.sql
+
+# PostgreSQL backup (restore to PostgreSQL)
+npm run db:dump -- postgresql backup.sql
+```
+
+**Note**: SQL dump does NOT support cross-database migrations (e.g., SQLite to MySQL). The generated SQL contains database-specific syntax that may not be compatible with other RDBMS.
+
+---
+
 ## 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             |
+| **Full database backup (same RDBMS)**         | `db:dump`                 | Full restore               |
+| **Cross-database migration** (SQLite -> MySQL)| `db:export` / `db:import` | Full restore via JSON      |
+| **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.
@@ -154,7 +205,7 @@ backup/restore to the same database. Use `db:dump` for proper backup/restore.
 
 ```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
+npm run db:dump -- sqlite backup-$(date +%Y%m%d).sql
 
 # Or simple SQLite file copy
 cp .sqlew/sqlew.db .sqlew/backup-$(date +%Y%m%d).db
@@ -164,36 +215,35 @@ cp .sqlew/sqlew.db .sqlew/backup-$(date +%Y%m%d).db
 
 ```bash
 # Developer A: Export project
-node node_modules/sqlew/dist/cli.js db:export --project=feature-x --output=feature-x.json
+npm run db:export -- feature-x.json project=feature-x
 
 # Developer B: Import project (in their own database)
-node node_modules/sqlew/dist/cli.js db:import --source=feature-x.json
+npm run db:import -- 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
+npm run db:dump -- mysql 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
+mysql -u user -p sqlew_db < migrate-to-mysql.sql
 ```
 
-### Workflow 4: Consolidate Multiple Projects (Permission-Constrained)
+### Workflow 4: Consolidate Multiple Projects
 
 ```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
+npm run db:export -- /tmp/a.json project=project-a
+npm run db:export -- /tmp/b.json project=project-b
 
 # 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
+npm run db:import -- /tmp/a.json
+npm run db:import -- /tmp/b.json
 ```
 
 ## Getting Help
@@ -201,9 +251,9 @@ node node_modules/sqlew/dist/cli.js db:import --source=/tmp/b.json
 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
+npm run db:dump -- --help
+npm run db:export -- --help
+npm run db:import -- --help
 ```
 
 ## Detailed Documentation

package/package.json

@@ -1,13 +1,11 @@
 {
   "name": "sqlew",
-  "version": "4.0.0",
+  "version": "4.0.2",
   "description": "MCP server that gives AI agents a shared SQL-backed context repository for decisions, constraints, and tasks",
   "main": "dist/index.js",
   "type": "module",
   "bin": {
     "sqlew": "dist/index.js",
-    "sqlew-cli": "dist/cli.js",
-    "sqlew-init-agents": "dist/init-agents.js",
     "sqlew-init-commands": "dist/init-commands.js"
   },
   "files": [
@@ -54,7 +52,6 @@
     "test:sql-dump:verbose": "node --test --test-force-exit --import tsx \"src/tests/database/sql-dump/**/*.test.ts\"",
     "test:all-features": "npm run build && node dist/tests/integration/all-features.standalone.js",
     "test:docker": "npm run build && node --test --test-force-exit dist/tests/docker/**/*.test.js",
-    "test:cross-db": "npm run build && node --test dist/tests/docker/cross-database.test.js",
     "test:native": "npm run build && node --test --test-concurrency=1 --test-force-exit dist/tests/docker/native/**/*.test.js | node scripts/filter-test-output.js",
     "test:native:verbose": "npm run build && node --test --test-concurrency=1 --test-force-exit dist/tests/docker/native/**/*.test.js",
     "test:migration-upgrade-paths": "echo 'v3 migration tests moved to v3 subdirectory - use test:native for v4 RDBMS tests'",
@@ -72,10 +69,11 @@
     "seed:make": "npm run knex seed:make",
     "seed:run": "npm run knex seed:run",
     "db:dump": "node dist/cli.js db:dump",
-    "db:export": "node dist/cli.js db:export"
+    "db:export": "node dist/cli.js db:export",
+    "db:import": "node dist/cli.js db:import"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=20.0.0"
   },
   "repository": {
     "type": "git",