sqlew 5.0.7 → 5.0.8

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/docs/ADR_CONCEPTS.md

@@ -1,12 +1,46 @@
-# ADR (Architecture Decision Record) Concepts
+# Decisions & Constraints for AI Development
 
-**Architecture Decision Records (ADR)** document the architectural decisions made on a project, including context, consequences, and alternatives considered. sqlew extends this proven pattern to AI agents.
+Persistent design context — decisions and constraints recorded as structured data — gives AI agents architectural memory across sessions. sqlew makes this zero-effort: plan normally, and hooks capture your decisions automatically.
 
-## Plan-to-ADR (v4.3.0+)
+## Why Persistent Design Context Matters
 
-**Plan-to-ADR** is sqlew's automatic ADR generation feature. Write decisions in your plan files using Markdown patterns (`📌 Decision` / `🚫 Constraint`), and they're automatically extracted and registered as structured ADR entries.
+Research shows that recording design intent dramatically improves LLM code generation:
 
-## How It Works
+- **22.4% reduction** in overall development time
+- **80% of tasks** completed faster with design intent available
+- **50%+ improvement** in feature-addition and architectural-change tasks
+- **137% increase** in design decision references by final tasks — AI learns to leverage past context more over time
+
+> Kitayama, S. (2026). *Rediscovering Architectural Decision Records: How Persistent Design Context Improves LLM Code Generation*. [DOI](https://doi.org/10.36227/techrxiv.177205025.54351571/v1)
+>
+> Blog post: [Recording Design Intent for AI Efficiency](https://blog.sqlew.io/recording-design-intent-for-ai-efficiency)
+
+## Key Benefits for AI-Driven Development
+
+### Persistent Architectural Memory
+- **Zero context loss** – AI agents remember every architectural decision across sessions
+- **Rationale preservation** – Never forget WHY a decision was made, not just WHAT
+- **Alternative tracking** – Document rejected options to prevent circular debates
+- **Evolution history** – See how decisions changed over time with full version history
+
+### Prevent Architectural Drift
+- **Constraint enforcement** – Define architectural rules once, AI follows them forever
+- **Pattern consistency** – AI generates code matching established patterns automatically
+- **Anti-pattern prevention** – Document "what NOT to do" as enforceable constraints
+- **Regression prevention** – AI won't reintroduce previously rejected approaches
+
+### Intelligent Decision Discovery
+- **Three-tier duplicate detection** – Gentle nudge (35-44), hard block (45-59), or auto-update (60+) based on similarity score
+- **Similarity detection** – AI identifies duplicate or related decisions before creating new ones
+- **Context-aware search** – Query by layer, tags, or relationships to find relevant decisions
+- **Conflict detection** – Find decisions that contradict or supersede each other
+
+### Extreme Efficiency
+- **60-75% token reduction** – Query only relevant decisions instead of reading full files
+- **Millisecond queries** – 2-50ms response times even with thousands of decisions
+- **Scalable architecture** – Perform well with large decision histories
+
+## How sqlew Works
 
 ```mermaid
 flowchart LR
@@ -31,7 +65,7 @@ flowchart LR
 2. Hooks automatically capture decisions
 3. Next session, AI queries past decisions via SQL
 
-## Core ADR Concepts in sqlew
+## Core Concepts
 
 **Decisions** capture architectural choices with full context:
 - **What** was decided (the decision itself)
@@ -45,15 +79,13 @@ flowchart LR
 - **Coding standards** ("async/await only", "no any types")
 - **Security policies** (authentication patterns, data handling rules)
 
-**Implementation tracking** connects decisions to reality:
-- **File tracking** shows which code was affected by decisions
+**Lifecycle tracking:**
 - **Status evolution** tracks decision lifecycle (draft → active → deprecated)
 - **Auto-capture via Hooks** records decisions automatically from Plan Mode
 
 ```mermaid
 erDiagram
     DECISION ||--o{ TAG : has
-    DECISION ||--o{ FILE : affects
     DECISION {
         string key
         string value
@@ -70,75 +102,51 @@ erDiagram
     TAG {
         string name
     }
-    FILE {
-        string path
-        string action
-    }
 ```
 
-## Why SQL for ADR?
+## SQL vs Markdown
 
-Traditional text-based ADR forces AI to:
+| Traditional approach (Markdown) | sqlew approach (SQL) |
+|--------------------------------|---------------------|
+| Read entire files | Query specific decisions |
+| Manual duplicate checking | Automatic similarity detection |
+| Text parsing required | Structured, typed data |
+| Linear token scaling | Constant-time lookups |
+| File-based organization | Relational queries with JOINs |
+
+### Why SQL?
+
+Traditional text-based records force AI to:
 - Read complete files even for simple queries
 - Parse unstructured text to find relationships
 - Manually detect duplicate or conflicting decisions
 
-sqlew's **SQL-backed ADR repository** enables AI to:
+sqlew's **SQL-backed decision repository** enables AI to:
 - Query by layer, tags, status in milliseconds (2-50ms)
-- Join decisions with constraints and files
+- Join decisions with constraints
 - Leverage similarity algorithms to prevent duplicates
 - Scale to thousands of decisions without context explosion
 
-**Token efficiency**: 60-75% reduction compared to reading Markdown ADRs
+**Token efficiency**: 60-75% reduction compared to reading Markdown files
 
-## Why RDBMS + MCP for ADR?
+### Why RDBMS + MCP?
 
 **RDBMS (Relational Database)** provides efficient structured queries:
 - **Indexed searches** – Find decisions by tags/layers in milliseconds, not seconds
 - **JOIN operations** – Query related decisions and constraints in a single operation
 - **Transaction support** – ACID guarantees ensure data integrity across concurrent AI agents
-- **Scalability** – Handle thousands of ADRs without performance degradation
+- **Scalability** – Handle thousands of decisions without performance degradation
 
 **MCP (Model Context Protocol)** enables seamless AI integration:
-- **Direct tool access** – AI agents call ADR operations as native functions
-- **Token efficiency** – Retrieve only required data, avoiding full-file reads
+- **Seamless DB connection** – AI agents access the database through a standardized protocol without direct DB setup
+- **Self-documenting tools** – Tool descriptions teach AI how to use each operation, no manual onboarding needed
 - **Type safety** – Structured parameters prevent errors and guide correct usage
-- **Cross-session persistence** – ADRs survive beyond individual chat sessions
-
-**Together**: AI agents gain SQL-powered ADR capabilities without managing databases directly.
-
-## Traditional vs sqlew ADR
+- **Cross-session persistence** – Decisions survive beyond individual chat sessions
 
-| Traditional ADR (Markdown) | sqlew ADR (SQL) |
-|---------------------------|-----------------|
-| Read entire files | Query specific decisions |
-| Manual duplicate checking | Automatic similarity detection |
-| Text parsing required | Structured, typed data |
-| Linear token scaling | Constant-time lookups |
-| File-based organization | Relational queries with JOINs |
+**Together**: AI agents gain SQL-powered decision capabilities without managing databases directly.
 
-## Key Benefits for AI-Driven Development
+## References
 
-### 📚 Persistent Architectural Memory
-- **Zero context loss** – AI agents remember every architectural decision across sessions
-- **Rationale preservation** – Never forget WHY a decision was made, not just WHAT
-- **Alternative tracking** – Document rejected options to prevent circular debates
-- **Evolution history** – See how decisions changed over time with full version history
-
-### 🛡️ Prevent Architectural Drift
-- **Constraint enforcement** – Define architectural rules once, AI follows them forever
-- **Pattern consistency** – AI generates code matching established patterns automatically
-- **Anti-pattern prevention** – Document "what NOT to do" as enforceable constraints
-- **Regression prevention** – AI won't reintroduce previously rejected approaches
-
-### 🔍 Intelligent Decision Discovery
-- **Three-tier duplicate detection** – Gentle nudge (35-44), hard block (45-59), or auto-update (60+) based on similarity score
-- **Similarity detection** – AI identifies duplicate or related decisions before creating new ones
-- **Context-aware search** – Query by layer, tags, or relationships to find relevant decisions
-- **Impact analysis** – Trace which files are affected by each decision
-- **Conflict detection** – Find decisions that contradict or supersede each other
-
-### ⚡ Extreme Efficiency
-- **60-75% token reduction** – Query only relevant decisions instead of reading all ADRs
-- **Millisecond queries** – 2-50ms response times even with thousands of decisions
-- **Scalable architecture** – Perform well with large decision histories
+- Kitayama, S. (2026). *Rediscovering Architectural Decision Records: How Persistent Design Context Improves LLM Code Generation*. [DOI](https://doi.org/10.36227/techrxiv.177205025.54351571/v1)
+- Blog: [Recording Design Intent for AI Efficiency](https://blog.sqlew.io/recording-design-intent-for-ai-efficiency)
+- The concept of Architecture Decision Records was originally proposed by Michael Nygard in 2011.

package/docs/CLI_USAGE.md

@@ -0,0 +1,472 @@
+# CLI Usage Guide
+
+> Command-line tools for database backup, export/import, and cross-database migration
+
+## Overview
+
+sqlew provides CLI commands for database operations that complement the main MCP server. The primary use of sqlew is as an **MCP server** (integrated via `.mcp.json`), but these CLI commands handle:
+
+- **Data Export/Import** — JSON-based project data migration (cross-database supported)
+- **SQL Dump** — Full database backup with schema (same-database-type only)
+
+## Commands
+
+| Command | Purpose | Cross-DB |
+|---------|---------|----------|
+| `db:export` | JSON export (recommended for migration) | ✅ |
+| `db:import` | JSON import (recommended for migration) | ✅ |
+| `db:dump` | SQL dump (backup/restore) | ❌ Same-DB only |
+
+### Running CLI Commands
+
+```bash
+# Direct use (global install or npx)
+sqlew db:export backup.json
+sqlew db:import backup.json
+sqlew db:dump sqlite backup.sql
+
+# Via npm scripts (within mcp-sqlew project)
+npm run db:export -- backup.json
+npm run db:import -- backup.json
+npm run db:dump -- sqlite backup.sql
+```
+
+**Note**: The first argument determines the mode — `db:export`, `db:import`, `db:dump` enter CLI mode; no argument starts the MCP server.
+
+---
+
+## JSON Export (`db:export`)
+
+### Syntax
+
+```bash
+sqlew db:export [output-file] [key=value ...]
+```
+
+### Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `project=<name>` | Export specific project by name | All projects |
+| `db-path=<path>` | Database file path | `.sqlew/sqlew.db` |
+| `config=<path>` | Config file path | Auto-detect |
+
+### What Gets Exported
+
+- **Master Tables** (filtered to used entries): m_context_keys, m_tags, m_scopes, m_layers, m_projects
+- **Transaction Tables** (all data for selected project): t_decisions, t_decision_context, t_constraints
+- **Junction Tables** (relationships): t_decision_tags, t_decision_scopes, t_constraint_tags
+
+### Examples
+
+```bash
+# Export all projects
+sqlew db:export backup.json
+
+# Export specific project
+sqlew db:export backup.json project=my-project
+
+# Export to stdout
+sqlew db:export project=my-project
+```
+
+---
+
+## JSON Import (`db:import`)
+
+### Syntax
+
+```bash
+sqlew db:import <source-file> [key=value ...]
+```
+
+### Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `<source-file>` | JSON export file path | **Required** |
+| `project-name=<name>` | Target project name | Use name from JSON |
+| `skip-if-exists=true` | Skip import if project exists | `true` |
+| `dry-run=true` | Validate only, don't import | `false` |
+| `db-path=<path>` | Database file path | `.sqlew/sqlew.db` |
+| `config=<path>` | Config file path | Auto-detect |
+
+### Import Process
+
+1. **Validation** — Checks JSON format, required fields, data types
+2. **Conflict Detection** — Checks if project name already exists
+3. **ID Remapping** — Creates new IDs for all imported data
+4. **Master Table Merge** — Reuses existing tags/scopes by name
+5. **Transaction Import** — Imports with fresh IDs and translated foreign keys
+6. **Junction Table Import** — Restores all relationships
+
+### Smart Features
+
+- **ID Remapping**: All imported data gets fresh auto-incremented IDs with automatic foreign key updates
+- **Master Table Deduplication**: Tags, scopes reused if they already exist (by name)
+- **Transaction Safety**: All-or-nothing semantics (full rollback on any error)
+
+### Examples
+
+```bash
+# Import from JSON
+sqlew db:import backup.json
+
+# Import with custom project name
+sqlew db:import backup.json project-name=new-name
+
+# Dry-run validation (no actual import)
+sqlew db:import backup.json dry-run=true
+```
+
+**⚠️ Important**: Import uses `skip-if-exists=true` by default — it skips if the project name already exists. This is **NOT a backup/restore solution**. Use `db:dump` for backup/restore.
+
+---
+
+## Cross-Database Migration
+
+> **v4.0.2+**: JSON export/import is the **ONLY** supported method for cross-database migrations.
+
+### Pre-Migration Checklist
+
+- [ ] Backup your current database
+- [ ] Target database is created and accessible
+- [ ] Database credentials are available
+- [ ] Required privileges: SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, INDEX, DROP, REFERENCES
+
+### SQLite → MySQL
+
+**Step 1: Export from SQLite**
+
+```bash
+sqlew db:export migration-backup.json
+```
+
+**Step 2: Prepare MySQL**
+
+```sql
+CREATE DATABASE sqlew_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+CREATE USER 'sqlew_user'@'localhost' IDENTIFIED BY 'your-secure-password';
+GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, INDEX, DROP, REFERENCES
+  ON sqlew_db.* TO 'sqlew_user'@'localhost';
+FLUSH PRIVILEGES;
+```
+
+**Step 3: Configure `.sqlew/config.toml`**
+
+```toml
+[database]
+type = "mysql"
+
+[database.connection]
+host = "localhost"
+port = 3306
+database = "sqlew_db"
+
+[database.auth]
+type = "direct"
+user = "sqlew_user"
+password = "your-secure-password"
+
+[project]
+name = "your-project-name"
+```
+
+**Step 4: Import**
+
+```bash
+sqlew db:import migration-backup.json
+```
+
+### SQLite → PostgreSQL
+
+**Step 1: Export from SQLite**
+
+```bash
+sqlew db:export migration-backup.json
+```
+
+**Step 2: Prepare PostgreSQL**
+
+```sql
+CREATE DATABASE sqlew_db WITH ENCODING 'UTF8';
+CREATE USER sqlew_user WITH PASSWORD 'your-secure-password';
+GRANT ALL PRIVILEGES ON DATABASE sqlew_db TO sqlew_user;
+\c sqlew_db
+GRANT ALL ON SCHEMA public TO sqlew_user;
+```
+
+**Step 3: Configure `.sqlew/config.toml`**
+
+```toml
+[database]
+type = "postgres"
+
+[database.connection]
+host = "localhost"
+port = 5432
+database = "sqlew_db"
+
+[database.auth]
+type = "direct"
+user = "sqlew_user"
+password = "your-secure-password"
+
+[project]
+name = "your-project-name"
+```
+
+**Step 4: Import**
+
+```bash
+sqlew db:import migration-backup.json
+```
+
+### MySQL → PostgreSQL
+
+**Step 1: Export from MySQL**
+
+Configure `.sqlew/config.toml` for MySQL, then:
+
+```bash
+sqlew db:export migration-backup.json
+```
+
+**Step 2: Prepare PostgreSQL**
+
+```sql
+CREATE DATABASE sqlew_db WITH ENCODING 'UTF8';
+CREATE USER sqlew_user WITH PASSWORD 'postgres-password';
+GRANT ALL PRIVILEGES ON DATABASE sqlew_db TO sqlew_user;
+\c sqlew_db
+GRANT ALL ON SCHEMA public TO sqlew_user;
+```
+
+**Step 3: Update `.sqlew/config.toml` for PostgreSQL**
+
+```toml
+[database]
+type = "postgres"
+
+[database.connection]
+host = "localhost"
+port = 5432
+database = "sqlew_db"
+
+[database.auth]
+type = "direct"
+user = "sqlew_user"
+password = "postgres-password"
+
+[project]
+name = "your-project-name"
+```
+
+**Step 4: Import**
+
+```bash
+sqlew db:import migration-backup.json
+```
+
+### Post-Migration Verification
+
+```bash
+# Test MCP server connection
+sqlew --config-path=.sqlew/config.toml
+
+# Or use MCP Inspector
+npx @modelcontextprotocol/inspector sqlew
+```
+
+Update `.mcp.json` to use the new database:
+
+```json
+{
+    "mcpServers": {
+        "sqlew": {
+            "command": "npx",
+            "args": ["sqlew", "--config-path", "/path/to/.sqlew/config.toml"]
+        }
+    }
+}
+```
+
+---
+
+## SQL Dump (`db:dump`) — Same-Database Only
+
+> **v4.0.2+**: `db:dump` supports **same-database-type backup/restore only**. For cross-database migration, use JSON export/import above.
+
+### Syntax
+
+```bash
+sqlew db:dump <format> [output-file] [key=value ...]
+```
+
+### Options
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `<format>` | Target SQL format: sqlite, mysql, postgresql | **Required** |
+| `[output-file]` | Output file path | stdout |
+| `from=<source>` | Source database type | sqlite |
+| `tables=<list>` | Comma-separated table names | All tables |
+| `chunk-size=<n>` | Rows per INSERT statement | 100 |
+| `on-conflict=<mode>` | error, ignore, replace | error |
+| `exclude-schema=true` | Data-only dump (no CREATE TABLE) | false |
+| `db-path=<path>` | SQLite database path | .sqlew/sqlew.db |
+
+### Supported Operations
+
+| Source | Target | Supported |
+|--------|--------|-----------|
+| SQLite | SQLite | ✅ |
+| MySQL | MySQL | ✅ |
+| PostgreSQL | PostgreSQL | ✅ |
+| Cross-database | Any | ❌ Use JSON |
+
+### Examples
+
+```bash
+# SQLite backup
+sqlew db:dump sqlite backup.sql
+
+# MySQL backup
+sqlew db:dump mysql backup.sql from=mysql
+
+# PostgreSQL backup
+sqlew db:dump postgresql backup.sql from=postgresql
+
+# Selective table export
+sqlew db:dump sqlite partial.sql tables=m_projects,t_decisions
+
+# Ignore duplicates on import
+sqlew db:dump sqlite dump.sql on-conflict=ignore
+```
+
+### Importing SQL Dumps
+
+```bash
+# SQLite
+sqlite3 your-database.db < dump-sqlite.sql
+
+# MySQL
+mysql -e "CREATE DATABASE mydb CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
+mysql mydb < dump-mysql.sql
+
+# PostgreSQL
+createdb mydb
+psql -d mydb -f dump-pg.sql
+```
+
+### Conflict Resolution
+
+| Mode | Behavior |
+|------|----------|
+| `error` (default) | Fails on duplicate keys |
+| `ignore` | Skips duplicate rows |
+| `replace` | Updates existing rows with new values |
+
+---
+
+## Comparison: JSON vs SQL Dump
+
+| Feature | db:export (JSON) | db:dump (SQL) |
+|---------|-----------------|---------------|
+| Format | JSON data only | SQL DDL + data |
+| Schema | Not included | Full schema |
+| Cross-DB | ✅ Yes | ❌ Same-DB only |
+| Use Case | Migration, sharing | Backup/restore |
+| Size | Smaller (~40% reduction) | Larger |
+| Conflict Handling | Smart deduplication | Overwrite or fail |
+| Restore | Skips if exists | Full restore |
+
+---
+
+## Use Cases
+
+### Project Sharing
+
+```bash
+# Developer A: Export
+sqlew db:export feature-x.json project=feature-x
+
+# Developer B: Import
+sqlew db:import feature-x.json
+```
+
+### Multi-Project Consolidation
+
+```bash
+# Export from each project
+sqlew db:export /tmp/a.json project=project-a
+sqlew db:export /tmp/b.json project=project-b
+
+# Import all to shared database
+sqlew db:import /tmp/a.json
+sqlew db:import /tmp/b.json
+```
+
+### Full Database Backup
+
+```bash
+# SQL dump (same-DB restore)
+sqlew db:dump sqlite backup-$(date +%Y%m%d).sql
+
+# Or simple file copy (SQLite only)
+cp .sqlew/sqlew.db .sqlew/backup-$(date +%Y%m%d).db
+```
+
+---
+
+## Troubleshooting
+
+### Connection Refused
+
+```
+Error: connect ECONNREFUSED 127.0.0.1:3306
+```
+
+Ensure the database server is running and accepting connections on the specified port.
+
+### Authentication Failed
+
+```
+Error: Access denied for user 'sqlew_user'@'localhost'
+```
+
+Verify username and password in config.toml. Check that the user has proper privileges.
+
+### Database Does Not Exist
+
+```
+Error: Unknown database 'sqlew_db'
+```
+
+Create the database first (see migration steps above).
+
+### Permission Denied (PostgreSQL)
+
+```
+Error: permission denied for schema public
+```
+
+Grant schema privileges: `GRANT ALL ON SCHEMA public TO sqlew_user;`
+
+### Import Skipped (Project Exists)
+
+```
+Project "my-project" already exists in target database
+```
+
+Use `project-name=<new-name>` to specify a different name, or remove the existing project from the target database.
+
+### Dry-Run Validation
+
+Always test imports with dry-run first:
+
+```bash
+sqlew db:import data.json dry-run=true
+```
+
+Validates JSON format, project name conflicts, foreign key references, and data type correctness.