sqlew 4.3.1 → 5.0.0

package/docs/MIGRATION_CLEANUP_GUIDE.md

@@ -0,0 +1,212 @@
+# v4 to v5 Migration Cleanup Guide
+
+This guide lists the **specific files** that were auto-generated by sqlew v4 (`sqlew --init`, `sqlew --hooks`). Delete only these files - other files in the same directories may have been created by you or other tools.
+
+## What Changed in v5
+
+| Feature | v4 (Legacy) | v5 (Plugin) |
+|---------|-------------|-------------|
+| Installation | `sqlew --init` per project | `sqlew-plugin` via Claude Plugin marketplace |
+| Skills/Hooks | `.claude/hooks/`, `.claude/skills/` | Managed by plugin |
+| Agents | `.claude/agents/` | Removed (Agent system deprecated) |
+| Rules | `.claude/rules/` | Global `~/.claude/rules/sqlew/` |
+| Commands | `.claude/commands/` | Global `~/.claude/commands/` |
+
+---
+
+## Files to Delete (v4 Auto-Generated)
+
+### Agents (Added by sqlew v3.x, deprecated in v4.0.0)
+
+These agent definition files were created by early sqlew versions:
+
+| File | Description |
+|------|-------------|
+| `.claude/agents/parallel-orchestrator.md` | Parallel task orchestration agent |
+| `.claude/agents/sqlew-architect.md` | Architecture decision agent |
+| `.claude/agents/sqlew-researcher.md` | Context research agent |
+| `.claude/agents/sqlew-scrum-master.md` | Task management agent |
+
+### Commands (Added by `sqlew --init`)
+
+| File | Description |
+|------|-------------|
+| `.claude/commands/sqlew.md` | `/sqlew` slash command definition |
+
+**Note**: Now managed globally at `~/.claude/commands/sqlew.md` by the plugin.
+
+### Hooks (Added by `sqlew --hooks`)
+
+| File | Description |
+|------|-------------|
+| `.claude/hooks/check-ast-grep.mjs` | AST pattern validation hook |
+| `.claude/hooks/check-db-path.mjs` | Database path guardrail hook |
+| `.claude/hooks/check-migration.mjs` | Migration file protection hook |
+| `.claude/hooks/check-prod-db.mjs` | Production DB protection hook |
+
+**Note**: Now managed by sqlew-plugin.
+
+### Rules (Added by `sqlew --init`)
+
+| File | Description |
+|------|-------------|
+| `.claude/rules/plan-mode-integration.md` | Plan mode decision format guide |
+
+**Note**: Now managed globally at `~/.claude/rules/sqlew/plan-mode-integration.md`.
+
+### Skills (Added by `sqlew --init`)
+
+| Directory | Description |
+|-----------|-------------|
+| `.claude/skills/sqlew-plan-guidance/` | Plan mode quick reference |
+| `.claude/skills/sqlew-decision-format/` | Decision format guide |
+
+**Note**: Now managed globally:
+- `~/.claude/skills/sqlew-plan-guidance/`
+- `~/.claude/skills/plan-decision-format/`
+
+---
+
+## settings.json Modification
+
+Remove hook entries that reference the deleted `.claude/hooks/*.mjs` files.
+
+**Before (v4):**
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          { "command": "node .claude/hooks/check-migration.mjs" },
+          { "command": "node .claude/hooks/check-ast-grep.mjs" }
+        ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          { "command": "node .claude/hooks/check-db-path.mjs" },
+          { "command": "node .claude/hooks/check-prod-db.mjs" }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**After (v5):**
+Remove the PreToolUse entries that reference `.claude/hooks/`. The plugin handles these automatically.
+
+---
+
+## Complete File List
+
+Copy-paste ready deletion commands for v4 auto-generated files:
+
+```bash
+# Windows (PowerShell)
+Remove-Item .claude\agents\parallel-orchestrator.md -ErrorAction SilentlyContinue
+Remove-Item .claude\agents\sqlew-architect.md -ErrorAction SilentlyContinue
+Remove-Item .claude\agents\sqlew-researcher.md -ErrorAction SilentlyContinue
+Remove-Item .claude\agents\sqlew-scrum-master.md -ErrorAction SilentlyContinue
+Remove-Item .claude\commands\sqlew.md -ErrorAction SilentlyContinue
+Remove-Item .claude\hooks\check-ast-grep.mjs -ErrorAction SilentlyContinue
+Remove-Item .claude\hooks\check-db-path.mjs -ErrorAction SilentlyContinue
+Remove-Item .claude\hooks\check-migration.mjs -ErrorAction SilentlyContinue
+Remove-Item .claude\hooks\check-prod-db.mjs -ErrorAction SilentlyContinue
+Remove-Item .claude\rules\plan-mode-integration.md -ErrorAction SilentlyContinue
+Remove-Item -Recurse .claude\skills\sqlew-plan-guidance -ErrorAction SilentlyContinue
+Remove-Item -Recurse .claude\skills\sqlew-decision-format -ErrorAction SilentlyContinue
+```
+
+```bash
+# Unix/macOS/Linux
+rm -f .claude/agents/parallel-orchestrator.md
+rm -f .claude/agents/sqlew-architect.md
+rm -f .claude/agents/sqlew-researcher.md
+rm -f .claude/agents/sqlew-scrum-master.md
+rm -f .claude/commands/sqlew.md
+rm -f .claude/hooks/check-ast-grep.mjs
+rm -f .claude/hooks/check-db-path.mjs
+rm -f .claude/hooks/check-migration.mjs
+rm -f .claude/hooks/check-prod-db.mjs
+rm -f .claude/rules/plan-mode-integration.md
+rm -rf .claude/skills/sqlew-plan-guidance
+rm -rf .claude/skills/sqlew-decision-format
+```
+
+---
+
+## Verification
+
+After cleanup, verify your setup:
+
+1. **Check plugin is installed:**
+   ```bash
+   # In Claude Code
+   /plugin list
+   # Should show: sqlew-plugin@sqlew-plugin
+   ```
+
+2. **Check global rules exist:**
+   ```bash
+   # Windows
+   dir %USERPROFILE%\.claude\rules\sqlew\
+
+   # Unix/macOS
+   ls ~/.claude/rules/sqlew/
+   ```
+
+3. **Test /sqlew command:**
+   ```bash
+   # In Claude Code
+   /sqlew
+   # Should show status without errors
+   ```
+
+4. **Verify no duplicate hooks:**
+   - Open `.claude/settings.json`
+   - Ensure no references to `.claude/hooks/*.mjs`
+
+---
+
+## Troubleshooting
+
+### Error: "Cannot find module '.claude/hooks/check-*.mjs'"
+
+**Cause**: `settings.json` still references deleted hook files.
+
+**Solution**: Remove the PreToolUse hooks section from `.claude/settings.json`.
+
+### /sqlew command not found
+
+**Cause**: Plugin not installed or global command not registered.
+
+**Solution**:
+```bash
+/plugin install sqlew-plugin
+# Restart Claude Code
+```
+
+### Decisions not being captured automatically
+
+**Cause**: Plugin hooks not active.
+
+**Solution**:
+1. Ensure plugin is installed at user level (not project level)
+2. Restart Claude Code
+3. Check `~/.claude/settings.json` for `enabledPlugins`
+
+---
+
+## Summary
+
+| Category | Files to Delete |
+|----------|-----------------|
+| **Agents** | `parallel-orchestrator.md`, `sqlew-architect.md`, `sqlew-researcher.md`, `sqlew-scrum-master.md` |
+| **Commands** | `sqlew.md` |
+| **Hooks** | `check-ast-grep.mjs`, `check-db-path.mjs`, `check-migration.mjs`, `check-prod-db.mjs` |
+| **Rules** | `plan-mode-integration.md` |
+| **Skills** | `sqlew-plan-guidance/`, `sqlew-decision-format/` |
+| **settings.json** | Remove PreToolUse entries referencing `.claude/hooks/` |

package/docs/MIGRATION_TO_SAAS.md

@@ -0,0 +1,176 @@
+# Migrating Local Data to SaaS
+
+This guide explains how to migrate your existing local sqlew data to [sqlew.io](https://sqlew.io) cloud backend.
+
+## Overview
+
+```
+┌─────────────────────────────────────────────────┐
+│  Migration Flow                                 │
+├─────────────────────────────────────────────────┤
+│                                                 │
+│  [Local v3.x/v4.x DB]                          │
+│       │                                         │
+│       ▼ npm install -g sqlew@latest            │
+│       │                                         │
+│       ▼ sqlew (auto-migration to v5.0+)        │
+│       │                                         │
+│  [Local v5.0+ DB]                              │
+│       │                                         │
+│       ▼ npm run db:export -- backup.json       │
+│       │                                         │
+│  [JSON file]                                    │
+│       │                                         │
+│       ▼ Upload to sqlew.io                     │
+│       │                                         │
+│  [SaaS v5.0+]                                  │
+│                                                 │
+└─────────────────────────────────────────────────┘
+```
+
+## Step-by-Step Guide
+
+### 1. Update to v5.0+
+
+If you're on an older version (v3.x or v4.x), update first:
+
+```bash
+npm install -g sqlew@latest
+```
+
+### 2. Run Auto-Migration
+
+Start the MCP server once. This automatically migrates your database schema:
+
+```bash
+sqlew
+```
+
+The migration system:
+- Detects your current schema version
+- Applies all necessary migrations (v3→v4→v5)
+- Preserves your decisions and constraints
+
+### 3. Export Your Data
+
+Export your local database to JSON format:
+
+```bash
+# From your project directory
+cd your-project
+
+# Export to JSON
+npx sqlew db:export backup.json
+```
+
+The exported JSON includes:
+- All decisions with full metadata
+- Decision history (version tracking)
+- Decision context (rationale, alternatives, tradeoffs)
+- Constraints with categories and priorities
+- Tags and scopes
+
+### 4. Import to SaaS
+
+Upload your JSON file via the sqlew.io dashboard:
+
+1. Go to [sqlew.io/dashboard/import](https://sqlew.io/dashboard/import)
+2. Select your project (or create a new one)
+3. Upload `backup.json`
+4. Review and confirm the import
+
+## Version Compatibility
+
+| Source Version | Support | Notes |
+|----------------|---------|-------|
+| **v5.0+** | ✅ Full | Direct export/import |
+| **v4.x** | ✅ Full | Auto-migrated on startup |
+| **v3.7+** | ✅ Full | Auto-migrated on startup |
+| **v3.0-v3.6** | ⚠️ Untested | May work, but not guaranteed |
+
+## What Gets Migrated
+
+### Preserved Data
+
+| Data Type | Migrated | Notes |
+|-----------|----------|-------|
+| Decisions | ✅ Yes | All metadata preserved |
+| Decision History | ✅ Yes | Full version tracking |
+| Decision Context | ✅ Yes | Rationale, alternatives, tradeoffs |
+| Constraints | ✅ Yes | Categories, priorities |
+| Tags | ✅ Yes | Project-scoped |
+| Scopes | ✅ Yes | Project-scoped |
+| Layers | ✅ Yes | 9 predefined layers |
+
+### Not Migrated (Removed Features)
+
+| Data Type | Version Removed | Reason |
+|-----------|-----------------|--------|
+| Agent references | v4.0 | Agent system simplified |
+| Tasks | v5.0 | Replaced by Claude Code TodoWrite |
+| Task dependencies | v5.0 | Replaced by Claude Code TodoWrite |
+| Files/File changes | v5.0 | No longer tracked |
+
+> **Note:** These features were removed from sqlew itself. The data is not lost during migration—these systems simply no longer exist in v5.0+.
+
+## Troubleshooting
+
+### Migration Fails
+
+If auto-migration fails:
+
+1. Check your Node.js version (requires 20.0.0+)
+2. Ensure `.sqlew/sqlew.db` exists and is readable
+3. Check for disk space issues
+
+### Export Fails
+
+If export fails:
+
+1. Verify the database was migrated successfully
+2. Check write permissions for the output directory
+3. Try with absolute path: `npx sqlew db:export /full/path/to/backup.json`
+
+### Import Fails on SaaS
+
+If SaaS import fails:
+
+1. Verify JSON file is valid (not corrupted)
+2. Check schema_version in JSON metadata is 5.0+
+3. Contact support if the issue persists
+
+## FAQ
+
+### Can I migrate v3.0-v3.6 data?
+
+These versions are untested. The migration may work, but we recommend:
+
+1. Backup your database first
+2. Try the migration
+3. Report any issues to [GitHub Issues](https://github.com/sqlew-io/sqlew/issues)
+
+### Will I lose any decisions?
+
+No. All decisions and constraints are fully preserved. Only deprecated features (agents, tasks, files) are not migrated because they no longer exist in v5.0+.
+
+### Can I migrate multiple projects?
+
+Yes. Export each project separately:
+
+```bash
+# Export all projects
+npx sqlew db:export --all backup-all.json
+
+# Or export specific project
+npx sqlew db:export --project my-project backup.json
+```
+
+### What about constraint tags?
+
+There's a known limitation where constraint-to-tag relationships may not be fully preserved. After import, you may need to re-tag some constraints manually.
+
+## See Also
+
+- [Configuration Guide](CONFIGURATION.md) - SaaS connection setup
+- [CLI Reference](cli/README.md) - All export/import commands
+- [Upgrade from v4 to v5](MIGRATION_CLEANUP_GUIDE.md) - Plugin migration guide

package/docs/SLASH_COMMANDS.md

@@ -326,4 +326,4 @@ The `/sqlew` command is designed for token efficiency:
 ## Contributing
 
 Found a bug or have a suggestion? Please report at:
-https://github.com/sin5ddd/mcp-sqlew/issues
+https://github.com/sqlew-io/sqlew/issues

package/docs/cli/DATABASE_MIGRATION.md

@@ -15,8 +15,8 @@ Starting from v4.0.2, `db:dump` generates SQL for the **same database type only*
 
 **For cross-database migrations**, use JSON export/import:
 ```bash
-npx sqlew db:export backup.json      # Export to JSON
-npx sqlew db:import backup.json      # Import to target database
+sqlew db:export backup.json      # Export to JSON
+sqlew db:import backup.json      # Import to target database
 ```
 
 See [DATA_EXPORT_IMPORT.md](DATA_EXPORT_IMPORT.md) for complete cross-database migration guide.
@@ -32,7 +32,7 @@ The `db:dump` CLI tool generates complete SQL dumps (CREATE TABLE + INSERT state
 **No installation required!** Use directly via npx:
 
 ```bash
-npx sqlew db:dump <format> [output-file] [key=value ...]
+sqlew db:dump <format> [output-file] [key=value ...]
 ```
 
 **Parameters:**
@@ -56,7 +56,7 @@ npx sqlew db:dump <format> [output-file] [key=value ...]
 
 ```bash
 # Backup SQLite database (default)
-npx sqlew db:dump sqlite backup-sqlite.sql
+sqlew db:dump sqlite backup-sqlite.sql
 ```
 
 **MySQL Backup:**
@@ -70,7 +70,7 @@ export MYSQL_PASSWORD=yourpass
 export MYSQL_DATABASE=mcp_context
 
 # Backup MySQL database
-npx sqlew db:dump mysql backup-mysql.sql from=mysql
+sqlew db:dump mysql backup-mysql.sql from=mysql
 ```
 
 **PostgreSQL Backup:**
@@ -84,7 +84,7 @@ export PG_PASSWORD=yourpass
 export PG_DATABASE=mcp_context
 
 # Backup PostgreSQL database
-npx sqlew db:dump postgresql backup-pg.sql from=postgresql
+sqlew db:dump postgresql backup-pg.sql from=postgresql
 ```
 
 > **Note**: For cross-database migrations (e.g., SQLite → MySQL), use JSON export/import instead.
@@ -95,7 +95,7 @@ npx sqlew db:dump postgresql backup-pg.sql from=postgresql
 Export only specific tables:
 
 ```bash
-npx sqlew db:dump mysql partial.sql tables=v4_decisions,v4_tasks,v4_files
+sqlew db:dump mysql partial.sql tables=v4_decisions,v4_tasks,v4_files
 ```
 
 ### Custom Chunk Size
@@ -103,7 +103,7 @@ npx sqlew db:dump mysql partial.sql tables=v4_decisions,v4_tasks,v4_files
 For large tables, adjust INSERT batch size:
 
 ```bash
-npx sqlew db:dump mysql dump.sql chunk-size=500
+sqlew db:dump mysql dump.sql chunk-size=500
 ```
 
 ### Data-Only Dumps
@@ -111,7 +111,7 @@ npx sqlew db:dump mysql dump.sql chunk-size=500
 For advanced use cases where you manage schema separately:
 
 ```bash
-npx sqlew db:dump mysql data-only.sql exclude-schema=true
+sqlew db:dump mysql data-only.sql exclude-schema=true
 ```
 
 This generates INSERT statements without CREATE TABLE, useful for:
@@ -126,13 +126,13 @@ Handle duplicate keys when importing into existing databases:
 
 ```bash
 # Ignore duplicates (safe for adding new data)
-npx sqlew db:dump mysql dump.sql on-conflict=ignore
+sqlew db:dump mysql dump.sql on-conflict=ignore
 
 # Update existing rows (sync/overwrite mode)
-npx sqlew db:dump mysql dump.sql on-conflict=replace
+sqlew db:dump mysql dump.sql on-conflict=replace
 
 # Fail on duplicates (default, strict mode)
-npx sqlew db:dump mysql dump.sql on-conflict=error
+sqlew db:dump mysql dump.sql on-conflict=error
 ```
 
 **Modes:**
@@ -286,5 +286,5 @@ PG_DATABASE=mcp_context     # Default: mcp_context
 
 For issues or questions:
 
-- GitHub Issues: https://github.com/sin5ddd/mcp-sqlew/issues
+- GitHub Issues: https://github.com/sqlew-io/sqlew/issues
 - Documentation: `/docs` directory in repository