sqlew 4.3.1 → 5.0.0

package/docs/cli/DATA_EXPORT_IMPORT.md

@@ -30,26 +30,26 @@ solutions including schema + data using SQL dumps.
 
 ```bash
 # Export all projects (no installation required!)
-npx sqlew db:export backup.json
+sqlew db:export backup.json
 
 # Export specific project to file
-npx sqlew db:export backup.json project=my-project
+sqlew db:export backup.json project=my-project
 
 # Export to stdout (pipe to another command)
-npx sqlew db:export project=visualizer
+sqlew db:export project=visualizer
 ```
 
 ### Import a Project
 
 ```bash
 # Import from JSON export
-npx sqlew db:import backup.json
+sqlew db:import backup.json
 
 # Import with custom project name
-npx sqlew db:import backup.json project-name=new-name
+sqlew db:import backup.json project-name=new-name
 
 # Dry-run validation (no actual import)
-npx sqlew db:import backup.json dry-run=true
+sqlew db:import backup.json dry-run=true
 ```
 
 ## Export Command
@@ -57,16 +57,16 @@ npx sqlew db:import backup.json dry-run=true
 ### Syntax
 
 ```bash
-npx sqlew db:export [output-file] [key=value ...]
+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       |
+| 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
 
@@ -95,19 +95,19 @@ npx sqlew db:export [output-file] [key=value ...]
 ### Syntax
 
 ```bash
-npx sqlew db:import <source-file> [key=value ...]
+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        |
+| 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
 
@@ -152,16 +152,17 @@ npx sqlew db:import <source-file> [key=value ...]
 
 ```bash
 # Export data
-npx sqlew db:export backup.json
+sqlew db:export backup.json
 
 # Import data
-npx sqlew db:import backup.json
+sqlew db:import backup.json
 
 # SQL dump (same-database backup)
-npx sqlew db:dump sqlite backup.sql
+sqlew db:dump sqlite backup.sql
 ```
 
 **Note**: Both MCP server mode and CLI commands use the same `sqlew` entry point. The first argument determines the mode:
+
 - `db:export`, `db:import`, `db:dump`, `query` → CLI mode
 - No argument or MCP-related args → MCP server mode
 
@@ -177,13 +178,13 @@ consolidate all project contexts into one shared database.
 ```bash
 # Step 1: Export from each project's SQLite database
 cd ~/project-a
-npx sqlew db:export /tmp/project-a.json project=project-a
+sqlew db:export /tmp/project-a.json project=project-a
 
 cd ~/project-b
-npx sqlew db:export /tmp/project-b.json project=project-b
+sqlew db:export /tmp/project-b.json project=project-b
 
 cd ~/project-c
-npx sqlew db:export /tmp/project-c.json project=project-c
+sqlew db:export /tmp/project-c.json project=project-c
 
 # Step 2: Create shared database and import all projects
 cd ~/shared-database
@@ -197,9 +198,9 @@ cd ~/shared-database
 # password = "mypassword"
 # database = "shared_sqlew_db"
 
-npx sqlew db:import /tmp/project-a.json
-npx sqlew db:import /tmp/project-b.json
-npx sqlew db:import /tmp/project-c.json
+sqlew db:import /tmp/project-a.json
+sqlew db:import /tmp/project-b.json
+sqlew db:import /tmp/project-c.json
 
 # Step 3: Configure each project to use shared database
 # In each project's .mcp.json:
@@ -230,11 +231,11 @@ npx sqlew db:import /tmp/project-c.json
 
 ```bash
 # Export from source database
-npx sqlew db:export main-export.json project=main
+sqlew db:export main-export.json project=main
 
 # Import to different database (different machine or different database type)
 # This works because the project doesn't exist in the target database yet
-npx sqlew db:import main-export.json db-path=/path/to/new/database.db
+sqlew db:import main-export.json db-path=/path/to/new/database.db
 ```
 
 **Note**: Import skips if project name exists.
@@ -243,44 +244,44 @@ npx sqlew db:import main-export.json db-path=/path/to/new/database.db
 
 ```bash
 # Backup with SQL dump (preserves schema + data)
-npx sqlew db:dump sqlite backup-$(date +%Y%m%d).sql
+sqlew 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
 ```
 
-See `npx sqlew db:dump --help` for full backup options.
+See `sqlew db:dump --help` for full backup options.
 
 ### Project Sharing
 
 ```bash
 # Developer A: Export project
-npx sqlew db:export feature-x.json project=feature-x
+sqlew db:export feature-x.json project=feature-x
 
 # Developer B: Import project
-npx sqlew db:import feature-x.json
+sqlew db:import feature-x.json
 ```
 
 ### Multi-Project Consolidation
 
 ```bash
 # Export from different databases
-npx sqlew db:export vis.json project=visualizer
-npx sqlew db:export api.json project=api
+sqlew db:export vis.json project=visualizer
+sqlew db:export api.json project=api
 
 # Import to single database
-npx sqlew db:import vis.json
-npx sqlew db:import api.json
+sqlew db:import vis.json
+sqlew db:import api.json
 ```
 
 ### Cross-Database Migration
 
 ```bash
 # Export from SQLite
-npx sqlew db:export data.json db-path=.sqlew/sqlew.db
+sqlew db:export data.json db-path=.sqlew/sqlew.db
 
 # Import to MySQL (configure .sqlew/config.toml for MySQL first)
-npx sqlew db:import data.json
+sqlew db:import data.json
 ```
 
 ---
@@ -307,7 +308,7 @@ Before starting a migration, ensure you have:
 cd /path/to/your/project
 
 # Export all data to JSON
-npx sqlew db:export migration-backup.json
+sqlew db:export migration-backup.json
 ```
 
 #### Step 2: Prepare MySQL Database
@@ -352,17 +353,17 @@ name = "your-project-name"
 
 ```bash
 # Import data to MySQL (config.toml will be used automatically)
-npx sqlew db:import migration-backup.json
+sqlew db:import migration-backup.json
 ```
 
 #### Step 5: Verify Migration
 
 ```bash
 # Test MCP server connection
-npx sqlew --config-path=.sqlew/config.toml
+sqlew --config-path=.sqlew/config.toml
 
 # Or test with MCP Inspector
-npx @modelcontextprotocol/inspector npx sqlew
+npx @modelcontextprotocol/inspector sqlew
 ```
 
 ---
@@ -375,7 +376,7 @@ npx @modelcontextprotocol/inspector npx sqlew
 cd /path/to/your/project
 
 # Export all data to JSON
-npx sqlew db:export migration-backup.json
+sqlew db:export migration-backup.json
 ```
 
 #### Step 2: Prepare PostgreSQL Database
@@ -422,14 +423,14 @@ name = "your-project-name"
 
 ```bash
 # Import data to PostgreSQL
-npx sqlew db:import migration-backup.json
+sqlew db:import migration-backup.json
 ```
 
 #### Step 5: Verify Migration
 
 ```bash
 # Test MCP server connection
-npx sqlew --config-path=.sqlew/config.toml
+sqlew --config-path=.sqlew/config.toml
 ```
 
 ---
@@ -458,7 +459,7 @@ password = "mysql-password"
 Then export:
 
 ```bash
-npx sqlew db:export migration-backup.json
+sqlew db:export migration-backup.json
 ```
 
 #### Step 2: Prepare PostgreSQL Database
@@ -500,7 +501,7 @@ name = "your-project-name"
 #### Step 4: Import to PostgreSQL
 
 ```bash
-npx sqlew db:import migration-backup.json
+sqlew db:import migration-backup.json
 ```
 
 ---
@@ -528,10 +529,10 @@ SELECT COUNT(*) FROM v4_file_changes;
 
 ```bash
 # Start MCP server with new config
-npx sqlew
+sqlew
 
 # Or use MCP Inspector for interactive testing
-npx @modelcontextprotocol/inspector npx sqlew
+npx @modelcontextprotocol/inspector sqlew
 ```
 
 #### 3. Verify in Claude Code
@@ -540,12 +541,12 @@ Update your `.mcp.json` to use the new database:
 
 ```json
 {
-  "mcpServers": {
-    "sqlew": {
-      "command": "npx",
-      "args": ["sqlew", "--config-path", "/path/to/.sqlew/config.toml"]
+    "mcpServers": {
+        "sqlew": {
+            "command": "npx",
+            "args": ["sqlew", "--config-path", "/path/to/.sqlew/config.toml"]
+        }
     }
-  }
 }
 ```
 
@@ -584,6 +585,7 @@ Error: permission denied for schema public
 ```
 
 **Solution**: Grant schema privileges to the user:
+
 ```sql
 -- PostgreSQL
 GRANT ALL ON SCHEMA public TO sqlew_user;
@@ -632,7 +634,7 @@ Solution: Ensure all referenced entities exist in export
 Always test imports with `dry-run=true` first:
 
 ```bash
-npx sqlew db:import data.json dry-run=true
+sqlew db:import data.json dry-run=true
 ```
 
 This validates:
@@ -666,16 +668,16 @@ This validates:
 
 ## Comparison with db:dump
 
-| Feature            | db:export (JSON)                     | db:dump (SQL)                         |
-|--------------------|--------------------------------------|---------------------------------------|
-| Format             | JSON data only                       | SQL DDL + data                        |
-| Schema             | Not included                         | Full schema included                  |
-| Use Case           | **Cross-DB migration**, sharing      | **Same-DB backup/restore**            |
-| Cross-DB           | ✅ **Yes (ONLY option for cross-DB)** | ❌ No (v4.0.2+ same-DB only)           |
-| Size               | Smaller (~40% reduction)             | Larger (includes schema)              |
-| Import Speed       | Slower (ID remapping)                | Faster (direct SQL execution)         |
-| Conflict Handling  | Smart deduplication                  | Overwrite or fail                     |
-| Restore Capability | ❌ Skips if exists                    | ✅ Full restore                        |
+| Feature            | db:export (JSON)                      | db:dump (SQL)                 |
+| ------------------ | ------------------------------------- | ----------------------------- |
+| Format             | JSON data only                        | SQL DDL + data                |
+| Schema             | Not included                          | Full schema included          |
+| Use Case           | **Cross-DB migration**, sharing       | **Same-DB backup/restore**    |
+| Cross-DB           | ✅ **Yes (ONLY option for cross-DB)** | ❌ No (v4.0.2+ same-DB only)  |
+| Size               | Smaller (~40% reduction)              | Larger (includes schema)      |
+| Import Speed       | Slower (ID remapping)                 | Faster (direct SQL execution) |
+| Conflict Handling  | Smart deduplication                   | Overwrite or fail             |
+| Restore Capability | ❌ Skips if exists                    | ✅ Full restore               |
 
 **When to use db:export (JSON)** - **REQUIRED FOR CROSS-DATABASE**:
 

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "sqlew",
   "description": "Automated ADR (Architecture Decision Records) for Claude Code - MCP server with SQL-backed decision repository",
-  "version": "4.3.1",
+  "version": "5.0.0",
   "main": "dist/index.js",
   "type": "module",
   "bin": {
-    "sqlew": "dist/index.js",
-    "sqlew-init-commands": "dist/init-commands.js"
+    "sqlew": "dist/index.js"
   },
   "files": [
     "dist/",
+    "saas-connector/",
     "scripts/",
     "assets/",
     "docs/",
@@ -20,7 +20,8 @@
     "MIGRATION_v2.md"
   ],
   "scripts": {
-    "build": "tsc",
+    "prebuild": "cd saas-connector && npm install && npm run build",
+    "build": "tsc && node scripts/copy-help-data.js",
     "start": "node dist/index.js",
     "dev": "tsc --watch",
     "clean": "rimraf dist",
@@ -41,12 +42,12 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/sin5ddd/mcp-sqlew.git"
+    "url": "git+https://github.com/sqlew-io/sqlew.git"
   },
   "bugs": {
-    "url": "https://github.com/sin5ddd/mcp-sqlew/issues"
+    "url": "https://github.com/sqlew-io/sqlew/issues"
   },
-  "homepage": "https://github.com/sin5ddd/mcp-sqlew#readme",
+  "homepage": "https://github.com/sqlew-io/sqlew#readme",
   "keywords": [
     "adr",
     "architecture-decision-record",
@@ -62,9 +63,10 @@
     "mysql",
     "token-efficiency"
   ],
-  "author": "sin5ddd",
+  "author": "sqlew-io",
   "license": "Apache-2.0",
   "dependencies": {
+    "@sqlew/saas-connector": "file:./saas-connector",
     "@modelcontextprotocol/sdk": "^1.21.1",
     "better-sqlite3": "^12.4.1",
     "chokidar": "^4.0.3",

package/saas-connector/LICENSE

@@ -0,0 +1,190 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2025 sqlew-io
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.