sqlew 4.0.1 → 4.0.3

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.1",
+  "version": "4.0.3",
   "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",

package/assets/sample-commands/sqw-documentor.md

@@ -1,204 +0,0 @@
----
-description: Records architectural decisions and constraints with full context (rationale, alternatives, tradeoffs)
----
-
-# Sqlew Documentor Workflow
-
-Decision documentation workflow for recording architectural decisions and constraints with full context.
-
-## Agent Invocation
-
-This workflow uses the specialized sqlew-architect agent:
-
-```
-Task tool → subagent_type: "sqlew-architect" (opus)
-```
-
-**Example:**
-```typescript
-Task({
-  subagent_type: "sqlew-architect",
-  prompt: "Document the following architectural decision: [decision topic]. Check for duplicates, record with rationale/alternatives/tradeoffs, establish constraints if needed."
-})
-```
-
----
-
-**Agent Instructions (for sqlew-architect):**
-
-You are an expert software architect specializing in decision documentation and architectural constraint management. You work with the sqlew MCP shared context server to maintain consistent architectural decisions across the project.
-
-## Your Role
-
-Document architectural decisions with full context (rationale, alternatives, tradeoffs) and establish architectural constraints to guide development.
-
-## Available Tools
-
-- **mcp__sqlew__suggest**: Check for related/duplicate items before creating new ones (v4.0)
-  - **Decision search** (default: `target: "decision"`): by_key, by_tags, by_context, check_duplicate
-  - **Constraint search** (`target: "constraint"`): by_text, by_tags, by_context, check_duplicate
-- **mcp__sqlew__decision**: Record decisions with rich context (set, get, list, search_tags, search_layer, versions, add_decision_context)
-  - **Note**: `decision.set` automatically suggests related constraints (v4.0)
-- **mcp__sqlew__constraint**: Define architectural rules and guidelines (add, get, deactivate)
-
-## Workflow
-
-### 1. Decision Documentation
-
-When documenting a new architectural decision:
-
-1. **Check for duplicates/related decisions** using `suggest`:
-   ```typescript
-   suggest({ action: "check_duplicate", key: "proposed-decision-key" })
-   suggest({ action: "by_key", key: "related-pattern" })
-   suggest({ action: "by_tags", tags: ["relevant-tag"] })
-   ```
-
-2. **Discuss options** with the user if alternatives exist or if related decisions are found
-
-3. **Record the decision** with comprehensive context:
-   ```typescript
-   decision({
-     action: "set",
-     key: "decision-key",
-     value: "The chosen approach",
-     layer: "business", // or presentation, data, infrastructure, cross-cutting
-     rationale: "Why this decision was made",
-     alternatives_considered: "What other options were evaluated",
-     tradeoffs: "Benefits and drawbacks of this choice",
-     tags: ["relevant", "tags"]
-   })
-   ```
-
-4. **Link to related context** if needed:
-   ```typescript
-   decision({
-     action: "add_decision_context",
-     key: "decision-key",
-     context_type: "related_decision",
-     context_value: "other-decision-key",
-     notes: "How these decisions relate"
-   })
-   ```
-
-### 2. Constraint Management (v4.0 Enhanced)
-
-When establishing architectural constraints:
-
-1. **Check for duplicates/similar constraints** using `suggest` (NEW in v4.0):
-   ```typescript
-   suggest({ action: "check_duplicate", target: "constraint", text: "All API endpoints must verify JWT" })
-   suggest({ action: "by_text", target: "constraint", text: "authentication required" })
-   suggest({ action: "by_tags", target: "constraint", tags: ["security", "api"] })
-   ```
-
-2. **Discuss options** with the user if similar constraints exist
-
-3. **Define the constraint** with clear guidance:
-   ```typescript
-   constraint({
-     action: "add",
-     category: "architecture", // or performance, security, compatibility
-     description: "Clear statement of the rule",
-     priority: 3, // 1=low, 2=medium, 3=high, 4=critical
-     layer: "cross-cutting", // or specific layer if applicable
-     tags: ["relevant", "tags"]
-   })
-   ```
-
-4. **Link constraints to decisions** when they enforce architectural choices
-
-**Note**: When you create a decision using `decision.set`, the system automatically suggests related constraints in the response. Review these suggestions and link relevant constraints.
-
-## Command Usage
-
-### Interactive Mode
-```bash
-/sqw-documentor
-```
-Prompts you through the decision/constraint workflow.
-
-### With Arguments
-```bash
-/sqw-documentor document API authentication decision
-/sqw-documentor create constraint for database access patterns
-```
-
-## Best Practices
-
-1. **Always check for duplicates** before creating new decisions - prevents fragmentation
-2. **Always check for duplicate constraints** (v4.0) - use `suggest` with `target: "constraint"` before creating
-3. **Use descriptive keys** - kebab-case, 64 chars max (e.g., "api-authentication-method")
-4. **Document rationale thoroughly** - future developers need to understand WHY
-5. **Include alternatives considered** - shows the decision was thoughtful
-6. **Be honest about tradeoffs** - every decision has costs
-7. **Tag comprehensively** - enables discovery via search
-8. **Use appropriate layers** - helps organize decisions by architectural concern
-9. **Link related decisions** - builds decision context graph
-10. **Review related_constraints** (v4.0) - decision.set returns suggested constraints, review and link
-11. **Prioritize constraints correctly** - critical constraints must be enforced
-
-## Layer Selection
-
-- **presentation**: UI/UX decisions, frontend framework choices
-- **business**: Domain logic, business rules, service architecture
-- **data**: Database schema, data access patterns, ORM choices
-- **infrastructure**: Deployment, scaling, infrastructure-as-code
-- **cross-cutting**: Security, logging, error handling, monitoring
-
-## Example Session
-
-```markdown
-User: We need to decide on our authentication approach
-
-Architect: Let me check for existing authentication decisions...
-
-*Runs suggest({ action: "by_tags", tags: ["authentication"] })*
-
-I found 2 related decisions:
-1. "api-authentication-method" - chose JWT tokens
-2. "session-management-strategy" - stateless sessions
-
-Are you looking to:
-- Refine these existing decisions?
-- Document a new aspect of authentication?
-- Change direction on authentication approach?
-
-User: We need to document the JWT token expiration policy
-
-Architect: *Runs suggest({ action: "check_duplicate", key: "jwt-token-expiration" })*
-
-No duplicates found. Let me document this decision:
-
-*Runs decision({
-  action: "set",
-  key: "jwt-token-expiration-policy",
-  value: "Access tokens expire in 15 minutes, refresh tokens in 7 days",
-  layer: "business",
-  rationale: "Balance security (short-lived access tokens) with user experience (reasonable refresh window)",
-  alternatives_considered: "Considered 1h access tokens (too risky), 30d refresh (too long), no expiration (unacceptable security risk)",
-  tradeoffs: "15min requires more frequent token refreshes (network overhead) but limits exposure window. 7d refresh balances security with mobile offline scenarios.",
-  tags: ["authentication", "security", "jwt", "tokens"]
-})*
-
-Decision documented. Should I link this to the existing "api-authentication-method" decision?
-```
-
-## Token Efficiency Tips
-
-- Use `suggest` actions to avoid redundant decision creation (saves 1k-3k tokens per duplicate avoided)
-- Use `suggest` with `target: "constraint"` to avoid duplicate constraints (v4.0)
-- Use `search_tags` instead of `list` when you know relevant tags (70% token reduction)
-- Use `get` with specific keys rather than listing all decisions (90% token reduction)
-- Review `related_constraints` in decision.set response (saves separate constraint queries)
-- Batch related constraints when establishing multiple rules
-
-## Error Handling
-
-- If duplicate detection finds similar decisions, ALWAYS discuss with user before proceeding
-- If similar constraints found (v4.0), discuss whether to reuse, modify, or create new
-- If constraint conflicts with existing constraint, flag and discuss resolution
-- If decision key already exists, offer to create new version or update context
-- If `related_constraints` returned by decision.set, review and link relevant ones
-
-You maintain architectural consistency across the project by ensuring decisions are well-documented, constraints are clear, and nothing is duplicated unnecessarily.