sql-dev-inspector 0.0.0-stage → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,3 @@
+# Changelog
+
+

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nhu Duy Thin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.VI.md

@@ -0,0 +1,341 @@
+# sql-dev-inspector
+
+> 🇬🇧 [English README](README.md) — bản chung chung cho cộng đồng. File này (`README.VI.md`) là bản tiếng Việt chi tiết, dành cho tác giả / người bảo trì.
+
+> Công cụ **chỉ dùng khi dev** cho mọi ứng dụng Node.js nói chuyện với MySQL qua [`mysql2`](https://github.com/sidorares/node-mysql2).
+> Khi client gọi một API, bạn thấy ngay backend đã chạy **những câu SQL nào, theo thứ tự nào, nằm trong transaction / savepoint nào, subquery lồng mấy tầng, mỗi câu mất bao lâu, trả về bao nhiêu dòng** — kèm cảnh báo N+1, query lặp, query chậm.
+
+```
+GET /api/orders/42 → 200  163ms total · 12 queries · 148ms in SQL
+├─ SELECT order_items 3.86ms · 2 rows
+│  select `id`, `sku` from `order_items` where `order_id` = 11
+├─ SELECT customers, orders ⤷subquery×3 (depth 3) 1.50ms · 2 rows
+├─ TRANSACTION [conn 101] committed 10.2ms
+│  ├─ INSERT orders 1.39ms · 1 affected
+│  ├─ SAVEPOINT sp1 [conn 101] rolled-back 4.30ms
+│  │  └─ SELECT 0.18ms ✖ You have an error in your SQL syntax …
+│  └─ SELECT orders 1.33ms · 2 rows
+⚠ Nghi N+1: 4 lần, tổng 8.4ms — select `id`, `sku` from `order_items` where `order_id` = ?
+✖ Lỗi SQL: You have an error in your SQL syntax …
+```
+
+## Mục lục
+
+1. [Tính năng](#tính-năng)
+2. [Yêu cầu](#yêu-cầu)
+3. [Cài đặt](#cài-đặt)
+4. [Bắt đầu nhanh](#bắt-đầu-nhanh) — Nuxt · Nitro · Express/Connect · `http` thuần · job/cron
+5. [Cách xem kết quả](#cách-xem-kết-quả) — terminal · trang web · nút nổi trong app
+6. [Cảnh báo tự động](#cảnh-báo-tự-động)
+7. [Cấu hình (biến môi trường)](#cấu-hình-biến-môi-trường)
+8. [API](#api)
+9. [Cách hoạt động](#cách-hoạt-động)
+10. [An toàn & quyền riêng tư](#an-toàn--quyền-riêng-tư)
+11. [Giới hạn đã biết](#giới-hạn-đã-biết)
+12. [Xử lý sự cố](#xử-lý-sự-cố)
+13. [Phát triển & test](#phát-triển--test)
+14. [Giấy phép](#giấy-phép)
+
+Hướng dẫn đưa lên git public, publish npm và cài vào dự án khác: [docs/PUBLISH-AND-INSTALL.md](docs/PUBLISH-AND-INSTALL.md).
+
+## Tính năng
+
+- **Gắn câu SQL vào đúng request** (kể cả khi chạy song song, kể cả khi pool connection bị bão hòa) bằng `AsyncLocalStorage`.
+- **Cây lồng nhau**: `begin … commit` thành node transaction, `savepoint … release / rollback to` thành node con, trạng thái committed / rolled-back / open. Hai transaction chạy song song trong cùng request không bị trộn.
+- **Subquery**: đo độ sâu `(SELECT …)` và số subquery; SQL được format theo cấp lồng để đọc như một cái cây.
+- **Cảnh báo**: N+1, query lặp y hệt, query chậm, lỗi SQL, `SELECT *`, subquery sâu, quá nhiều query (và tuỳ chọn: quy ước "SELECT ngoài transaction").
+- **Đa ngôn ngữ**: English, Tiếng Việt, 日本語 — terminal, trang web và nút nổi — thêm ngôn ngữ mới chỉ cần thêm một khối văn bản (xem [Ngôn ngữ](#ngôn-ngữ-i18n)).
+- **Giao diện chuyên nghiệp**: sáng / tối / theo hệ thống, responsive tới cả panel dock hẹp, điều hướng bằng bàn phím, SQL có tô màu cú pháp, biểu đồ waterfall cho từng câu.
+- **Ba cách xem**: cây in ra terminal · trang web live (`/__sql-inspector/`) · **nút nổi** trong chính ứng dụng của bạn (Nuxt tự gắn; ứng dụng khác gắn bằng 1 dòng).
+- **Không sửa code truy vấn**: hoạt động với mọi thứ đi qua `mysql2` — mysql2 thuần, Drizzle (đã kiểm chứng), và về nguyên lý cả Knex / Sequelize / TypeORM… (xem [Giới hạn](#giới-hạn-đã-biết)).
+- **Không phụ thuộc runtime nào** ngoài `mysql2` (peer). Trang web một file, không tải gì từ CDN.
+- **An toàn mặc định**: không bao giờ chạy khi `NODE_ENV=production`; production là no-op hoàn toàn.
+
+## Yêu cầu
+
+- Node.js **≥ 20**
+- `mysql2` **≥ 3** (peer dependency; đã kiểm chứng với 3.20)
+- Ứng dụng của bạn phải gửi SQL qua `mysql2` (pool, connection, hoặc ORM dùng mysql2 bên dưới)
+
+## Cài đặt
+
+```bash
+npm  install --save-dev sql-dev-inspector
+# hoặc
+pnpm add -D sql-dev-inspector
+yarn add -D sql-dev-inspector
+```
+
+> Tên package và các cách cài khác (từ GitHub, từ file `.tgz`) xem [docs/PUBLISH-AND-INSTALL.md](docs/PUBLISH-AND-INSTALL.md).
+> Nếu ứng dụng của bạn import tool trong code chạy cả ở production (ví dụ Express), hãy cài vào `dependencies` thay vì `devDependencies` — tool tự thành no-op khi `NODE_ENV=production`.
+
+## Bắt đầu nhanh
+
+Trong mọi trường hợp, tool chỉ bật khi `NODE_ENV=development` (hoặc `SQL_INSPECTOR=1`) — xem [Cấu hình](#cấu-hình-biến-môi-trường).
+
+### Nuxt 3 / 4
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ["sql-dev-inspector/nuxt"]
+})
+```
+
+Xong. Module chỉ đăng ký trong `nuxt dev` (không có gì trong `build` / `generate`): plugin Nitro phía server, và nút nổi phía client. Mở `http://localhost:3000/__sql-inspector/`, hoặc bấm nút **SQL** ở góc phải dưới.
+
+Nếu app dùng `app.baseURL` (ví dụ `/alps`), đường dẫn là `/alps/__sql-inspector/`.
+
+### Nitro thuần (không Nuxt)
+
+```ts
+// nitro.config.ts
+export default defineNitroConfig({
+  plugins: ["sql-dev-inspector/nitro"]
+})
+```
+
+### Express / Connect (và framework nhận middleware kiểu Connect)
+
+```ts
+import express from "express"
+import { createSqlInspector } from "sql-dev-inspector"
+
+const app = express()
+const sqlInspector = createSqlInspector()
+
+app.use(sqlInspector.middleware) // đặt TRƯỚC mọi route / middleware có chạy SQL
+
+app.get("/orders/:id", async (req, res) => {
+  const [rows] = await pool.query("select * from orders where id = ?", [req.params.id])
+  res.json(rows)
+})
+
+app.listen(3000)
+// mở http://localhost:3000/__sql-inspector/
+```
+
+### Node `http` thuần (hoặc framework khác)
+
+```ts
+import http from "node:http"
+import { createSqlInspector } from "sql-dev-inspector"
+
+const sqlInspector = createSqlInspector()
+
+http.createServer((req, res) => {
+  if (sqlInspector.handle(req, res)) return        // trang /__sql-inspector do tool phục vụ
+  sqlInspector.track(req, res, () => myApp(req, res)) // mọi await bên trong thuộc về request này
+}).listen(3000)
+```
+
+### Job / cron / script (không phải HTTP request)
+
+```ts
+await sqlInspector.task("nightly-sync", async () => {
+  await syncCustomers()
+})
+// hiện trong danh sách với method TASK, tên "nightly-sync"
+```
+
+### Nút nổi cho ứng dụng không phải Nuxt
+
+Ở phía trình duyệt (cùng origin với server), gọi một lần trong entry của frontend:
+
+```ts
+if (import.meta.env.DEV) {
+  const { mountSqlInspectorWidget } = await import("sql-dev-inspector/client")
+  mountSqlInspectorWidget({ baseURL: "/" }) // baseURL = tiền tố đường dẫn của server
+}
+```
+
+Nếu frontend chạy ở origin khác server (ví dụ Vite :5173, API :3000) thì dùng trang `http://localhost:3000/__sql-inspector/` trực tiếp, hoặc proxy `/__sql-inspector` qua dev server của frontend.
+
+## Cách xem kết quả
+
+### 1. Terminal
+
+Mỗi request có chạy SQL in một cây ngay khi response kết thúc (không in request không chạy SQL). Tắt bằng `SQL_INSPECTOR_LOG=0`.
+
+### 2. Trang web `/__sql-inspector/`
+
+Danh sách request cập nhật live (SSE), có ô tìm kiếm và bộ lọc *Tất cả / Có vấn đề / Lỗi*. Bấm vào request để xem KPI (tổng thời gian, số query, thời gian SQL và tỉ lệ, số transaction, độ sâu subquery), các cảnh báo, và dòng thời gian các câu SQL kèm thanh waterfall. Bấm vào từng câu để xem SQL đã tô màu + format, SQL gốc, parameters, nút copy; bấm vào một cảnh báo để highlight các câu liên quan; đóng/mở từng transaction. "Theo dõi mới nhất" tự nhảy sang request mới. Bàn phím: `/` tìm kiếm, `↑` `↓` (hoặc `j` `k`) request trước/sau, `e` mở/đóng tất cả. Ngôn ngữ và giao diện (hệ thống / sáng / tối) nằm ở thanh trên.
+
+### 3. Nút nổi trong app
+
+Nút **SQL** nổi ở góc phải dưới. Số trên nút = số query của request gần nhất; vàng khi có cảnh báo, đỏ khi có lỗi.
+
+| Thao tác | Cách làm |
+|---|---|
+| Mở / đóng panel | Bấm nút, hoặc `Alt+Shift+S`; `Esc` đóng khi đang focus trong panel |
+| Ẩn / hiện nút | `Alt+Shift+D` (phím mở panel vẫn dùng được khi nút đã ẩn) |
+| Đổi chỗ nút | Kéo nút |
+| Đổi kích thước panel | Kéo mép panel |
+| Dock đáy / dock phải | Hai biểu tượng dock ở đầu panel |
+| Tự mở khi có cảnh báo / lỗi | Menu "⚙ Tuỳ chỉnh" (mặc định tắt) |
+| Mở tab riêng · xoá lịch sử | Biểu tượng ↗ ở đầu panel · "Xoá lịch sử" trong menu tuỳ chỉnh |
+| Tắt hẳn | Menu "⚙ Tuỳ chỉnh" → "Tắt SQL Inspector" (`Alt+Shift+S` bật lại) |
+
+Cài đặt lưu trong `localStorage` (`sqlDevInspector.widget`). Panel chỉ tải khi mở lần đầu. Nút dựng bằng DOM thuần trong Shadow DOM: không phụ thuộc Vue/React và không bị CSS của app ảnh hưởng.
+
+## Cảnh báo tự động
+
+| Loại | Điều kiện | Mức |
+|---|---|---|
+| `n-plus-one` | ≥ 3 câu SELECT cùng "hình dạng" (khác giá trị) trong một request | warn |
+| `duplicate` | cùng một câu SQL y hệt chạy ≥ 2 lần | warn |
+| `slow` | ≥ 100ms (`SQL_INSPECTOR_SLOW_MS`) | warn |
+| `error` | câu bị MySQL từ chối | error |
+| `many-queries` | ≥ 30 câu trong một request | warn |
+| `select-star` | `SELECT *` | info |
+| `deep-subquery` | subquery lồng ≥ 3 tầng | info |
+| `select-in-transaction`, `write-outside-transaction` | **tuỳ chọn** `SQL_INSPECTOR_TX_CONVENTION=1`: quy ước "SELECT ngoài transaction, transaction chỉ cho câu ghi" | info |
+
+N+1 so sánh "fingerprint": SQL đã che giá trị literal và gộp `IN (…)` / `VALUES (…)`.
+
+## Cấu hình (biến môi trường)
+
+| Biến | Mặc định | Ý nghĩa |
+|---|---|---|
+| `NODE_ENV` | — | `production` ⇒ **luôn tắt** (kể cả `SQL_INSPECTOR=1`). `development` ⇒ bật |
+| `SQL_INSPECTOR` | — | `1` bật cả khi `NODE_ENV` không phải development (ví dụ `test`); `0` tắt hẳn |
+| `SQL_INSPECTOR_LANG` | `en` | Ngôn ngữ của terminal (`en`, `vi`, `ja`) và ngôn ngữ khởi đầu của trang web. Chỉ biến này có tác dụng — `LANG` của máy cố ý bị bỏ qua |
+| `SQL_INSPECTOR_LOG` | bật | `0`: không in cây ra terminal |
+| `SQL_INSPECTOR_SLOW_MS` | `100` | Ngưỡng cảnh báo chậm |
+| `SQL_INSPECTOR_MAX_REQUESTS` | `200` | Số request giữ trong bộ nhớ |
+| `SQL_INSPECTOR_MAX_QUERIES` | `1000` | Số câu tối đa giữ cho mỗi request |
+| `SQL_INSPECTOR_TX_CONVENTION` | tắt | `1`: bật 2 cảnh báo quy ước transaction |
+| `NO_COLOR` | — | Tắt màu ở terminal |
+
+## API
+
+Entry chính `sql-dev-inspector`:
+
+```ts
+createSqlInspector(): SqlInspector
+interface SqlInspector {
+  enabled: boolean                                  // false ở production / khi tắt: mọi thứ dưới đây là no-op
+  middleware(req, res, next): void                  // Connect/Express
+  handle(req, res): boolean                         // true nếu là URL của tool (đã phục vụ)
+  track<T>(req, res, fn: () => T): T                // chạy fn như một request được theo dõi
+  task<T>(name: string, fn: () => T | Promise<T>): Promise<T> // đơn vị công việc không phải HTTP
+}
+```
+
+Mức thấp (cho tích hợp riêng): `startInspector()`, `getInspector()`, `isInspectorEnabled()`, `installTracer(store)`, `runInRequest(trace, fn)`, `TraceStore`, `buildReport(trace, options)`, `buildTree(queries)`, `analyzeSql(sql)`, `fingerprintOf(sql)`, `formatSql(sql)` và toàn bộ kiểu (`QueryEvent`, `RequestTrace`, `RequestReport`, `Insight`…).
+
+Các entry khác:
+
+| Import | Dùng cho |
+|---|---|
+| `sql-dev-inspector/nuxt` | Nuxt module (`modules: [...]`) |
+| `sql-dev-inspector/nitro` | Nitro plugin (`plugins: [...]`) |
+| `sql-dev-inspector/client` | `mountSqlInspectorWidget({ baseURL })` — nút nổi cho frontend bất kỳ |
+
+Các route của tool (đều dưới `/__sql-inspector/`): `GET /` trang web · `GET /api/requests` · `GET /api/requests/:id` · `GET /api/stream` (SSE) · `POST /api/clear`.
+
+## Cách hoạt động
+
+Mọi câu SQL — dù đến từ `pool.query`, transaction, hay ORM — đều đi qua `Connection.prototype.query/execute` của mysql2. Tool patch đúng điểm đó (một lần, gỡ được) để ghi lại SQL, parameters, thời gian, số dòng, lỗi và **connection nào đã chạy câu lệnh**.
+
+Vì sao không dùng cách khác:
+
+| Phương án | Hạn chế |
+|---|---|
+| `logger` của ORM (ví dụ Drizzle) | Chỉ có SQL + params; không có thời gian, kết quả, connection ⇒ không dựng được cây transaction/savepoint, không biết request nào |
+| `diagnostics_channel` của mysql2 ≥ 3.20 | Có thời gian nhưng **không cho biết connection** ⇒ hai transaction song song trong một request bị trộn |
+| `general_log` của MySQL | Không biết request nào, không có thời gian/cây lồng, cần quyền trên DB |
+
+Gắn query vào request:
+
+1. Adapter bọc request handler bằng `AsyncLocalStorage`, nên mọi `await` bên dưới đều thuộc request đó.
+2. `pool.query()` đưa câu lệnh cho connection qua callback; khi mọi connection bận, callback chạy từ context của *request khác*. Tool bọc callback của `Pool.getConnection` bằng `AsyncLocalStorage.bind` để không gán nhầm.
+3. Cây transaction gom theo connection; "subquery lồng" đo bằng độ sâu `(SELECT …)` trên SQL đã che literal (không đếm ngoặc thường).
+
+## Ngôn ngữ (i18n)
+
+Có sẵn English, Tiếng Việt (`vi`), 日本語 (`ja`).
+
+- **Trang web**: ưu tiên lựa chọn đã lưu → `SQL_INSPECTOR_LANG` (nếu đặt) → ngôn ngữ trình duyệt → English. Đổi bất cứ lúc nào ở thanh trên; `?lang=ja` trên URL ghi đè cho lần xem đó.
+- **Nút nổi**: theo ngôn ngữ trình duyệt, hoặc chọn trong menu tuỳ chỉnh (panel tải lại bằng ngôn ngữ đó).
+- **Terminal và trường `message` của API**: `SQL_INSPECTOR_LANG`, mặc định English.
+
+Cảnh báo (insight) được trả về dạng dữ liệu (`type` + `params`) cùng với `message` đã dịch sẵn, nên client nào cũng tự diễn đạt lại được.
+
+**Thêm ngôn ngữ mới**: sao chép khối `en` trong `src/i18n/messages.ts`, dịch các giá trị (giữ nguyên mọi `{placeholder}`; thêm biến thể `.one` khi số ít khác số nhiều, ví dụ `"term.queries.one"`), thêm mã vào kiểu `Locale` và `LOCALES` trong `src/i18n/index.ts`. `npm test` sẽ fail nếu thiếu key hoặc placeholder.
+
+## Style & cô lập
+
+Tool không bao giờ được làm giao diện của ứng dụng xấu đi, nên:
+
+- **Nút nổi và panel** nằm trong **shadow root**, reset bằng `all: initial`, host là custom element (không phải `<div>`), các reset có độ ưu tiên bằng 0 (`:where`). CSS toàn cục của app (`button { … }`, `* { … }`, `select`, `body > *`) không đụng được vào chúng, và chúng không thêm CSS nào vào trang. Chúng là `position: fixed`, không làm xô lệch layout, không cướp focus.
+- **Trang inspector** là một document riêng (nằm trong `<iframe>` khi dock) nên cũng không chạm được vào trang của bạn. Mọi control gốc (nút, switch, thanh cuộn) đều được vẽ lại, và bộ chọn ngôn ngữ là listbox tự vẽ — popup của `<select>` gốc do hệ điều hành vẽ, CSS không đụng được nên không dùng `<select>` ở bất kỳ đâu (có test kiểm tra), khai báo `color-scheme` để dark mode không rơi về giao diện mặc định của trình duyệt.
+- **Không gọi ra ngoài**: không web font, không CDN, không analytics — chỉ dùng font hệ thống (có cả tiếng Nhật, tiếng Việt).
+- Tôn trọng `prefers-color-scheme`, `prefers-reduced-motion`, focus bàn phím (`:focus-visible`).
+- Nếu app đặt Content-Security-Policy chặt, nút nổi cần `style-src 'unsafe-inline'` (nó chèn một `<style>` vào shadow root) và `frame-src 'self'`. Tool chỉ dùng khi dev; hãy nới chính sách chỉ cho môi trường dev.
+
+## An toàn & quyền riêng tư
+
+- `NODE_ENV=production` là **hard stop**: không patch gì, middleware chỉ gọi `next()`.
+- Nuxt module chỉ đăng ký trong `nuxt dev`; `build` / `generate` không chứa gì của tool.
+- Dữ liệu chỉ ở **bộ nhớ** của tiến trình dev, không ghi file, không gửi đi đâu, không gọi mạng.
+- ⚠️ **SQL hiển thị gồm cả giá trị thật** (kể cả dữ liệu cá nhân của DB bạn đang trỏ tới). Đừng chia sẻ màn hình / ảnh chụp khi trỏ vào DB staging hoặc production-like.
+- Trang `/__sql-inspector/` không có xác thực: chỉ để chạy ở `localhost`. Đừng mở cổng dev ra mạng chung khi đang bật tool (ví dụ `--host 0.0.0.0`).
+- Trong Nuxt/Nitro, trang được phục vụ trước mọi middleware (không cần đăng nhập, và query xác thực của app không làm nhiễu kết quả).
+
+## Giới hạn đã biết
+
+- **Chỉ MySQL qua `mysql2`.** PostgreSQL, SQLite, hoặc driver MySQL khác (ví dụ `mariadb`) không được hỗ trợ. ORM không dùng mysql2 bên dưới (ví dụ engine riêng của Prisma) không đi qua điểm patch.
+- **Đã kiểm chứng**: mysql2 thuần (pool, connection, transaction thủ công) và Drizzle ORM. Knex / Sequelize / TypeORM dùng mysql2 nên *về nguyên lý* chạy được, nhưng chưa có test riêng — nếu gặp vấn đề hãy mở issue.
+- **Không biết dòng code nào gọi query**: ORM như Drizzle trả builder dạng thenable nên khi query thật sự chạy, call stack không còn frame của code gọi. (Đã thử, nên không có tính năng "caller".)
+- Một builder tạo trong scope request nhưng `await` ở ngoài scope (ví dụ trả về rồi await sau khi response đóng) sẽ không gắn về request.
+- Câu lệnh chạy ngoài request/task (startup, timer) được gom vào mục `(ngoài request …)`.
+- Request không chạy SQL (asset, HMR) không được lưu.
+- Adapter Express/Connect đã được test với `req`/`res` giả đúng giao diện Connect (chưa có test chạy trên `express` thật); nút nổi ngoài Nuxt (`mountSqlInspectorWidget`) mới được test trong happy-dom.
+- Đã test với `mysql2` 3.20 và Node 24; Node 20+ theo `engines`.
+
+## Xử lý sự cố
+
+| Triệu chứng | Nguyên nhân thường gặp |
+|---|---|
+| Không thấy gì, không có dòng `[sql-inspector] bật` | `NODE_ENV` không phải `development`: chạy với `NODE_ENV=development` hoặc `SQL_INSPECTOR=1` (và không phải `production`) |
+| Có terminal log nhưng trang `/__sql-inspector/` 404 | Express: `sqlInspector.middleware` phải đặt trước router; Nitro/Nuxt: kiểm tra `app.baseURL` |
+| Query nằm hết trong `(ngoài request …)` | Middleware đặt sau route đã chạy SQL; hoặc SQL chạy trong scope không `await` từ handler (timer, queue) — bọc bằng `sqlInspector.task()` |
+| Nút nổi không hiện | Không phải Nuxt: chưa gọi `mountSqlInspectorWidget`. Nuxt: chỉ có trong `nuxt dev`. Thử `Alt+Shift+D` (có thể đã ẩn) hoặc xoá key `sqlDevInspector.widget` trong localStorage |
+| Query của ORM X không hiện | ORM đó không dùng `mysql2`. Kiểm tra driver bên dưới |
+| Hai bản `mysql2` trong `node_modules` | Tool patch bản mà nó `import` được. Đảm bảo app và tool dùng chung một bản (peer dependency được hoist) |
+
+## Phát triển & test
+
+```bash
+npm install
+npm run typecheck   # tsc --noEmit (src + test)
+npm test            # vitest: 131 test
+npm run build       # tsc -> dist/
+```
+
+Test tích hợp chạy **mysql2 thật + Drizzle thật** với một MySQL giả nói đúng wire protocol (`test/mock-mysql-server.ts`, nối bằng stream trong bộ nhớ nên không cần mở cổng hay cài MySQL): transaction, savepoint lồng, rollback, hai transaction song song, 8 request đồng thời trên pool 3 connection, lỗi SQL, N+1, SSE, gỡ patch, adapter Express/`http`, nút nổi và trang web (happy-dom).
+
+Cấu trúc:
+
+```
+src/
+├─ index.ts              # API công khai
+├─ node.ts               # createSqlInspector: Express / http / task
+├─ nitro-plugin.ts       # Nitro / Nuxt (server)
+├─ nuxt.ts               # Nuxt module (chỉ đăng ký trong dev)
+├─ setup.ts              # bật tracer + in terminal, một lần mỗi process
+├─ tracer.ts             # patch mysql2 + AsyncLocalStorage
+├─ store.ts              # ring buffer request/query + pub/sub
+├─ sql-analyzer.ts       # loại câu lệnh, bảng, subquery, fingerprint, format
+├─ report.ts             # cây transaction/savepoint + cảnh báo
+├─ terminal.ts           # in cây ra terminal
+├─ inspector-server.ts   # route /__sql-inspector (UI, JSON, SSE)
+├─ ui.ts                 # trang web một file
+├─ runtime.ts            # cờ môi trường + singleton
+└─ client/               # nút nổi (widget.ts) + plugin client của Nuxt
+```
+
+## Giấy phép
+
+MIT — xem [LICENSE](LICENSE).

package/README.md

@@ -1,3 +1,268 @@
-# Temporary Holding Version
+# sql-dev-inspector
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**See exactly which SQL your backend ran for each request — in development only.**
+
+When a client calls your API, `sql-dev-inspector` shows every statement your server sent to MySQL: in what order, inside which transaction or savepoint, how deeply subqueries nest, how long each one took and how many rows it returned. It also flags N+1 loops, repeated queries, slow queries and SQL errors.
+
+```
+GET /api/orders/42 → 200  163ms total · 12 queries · 148ms in SQL
+├─ SELECT order_items 3.86ms · 2 rows
+│  select `id`, `sku` from `order_items` where `order_id` = 11
+├─ SELECT customers, orders ⤷subquery×3 (depth 3) 1.50ms · 2 rows
+├─ TRANSACTION [conn 101] committed 10.2ms
+│  ├─ INSERT orders 1.39ms · 1 affected
+│  ├─ SAVEPOINT sp1 [conn 101] rolled-back 4.30ms
+│  │  └─ SELECT 0.18ms ✖ You have an error in your SQL syntax …
+│  └─ SELECT orders 1.33ms · 2 rows
+⚠ N+1 suspected: 4×, 8.4ms total — select `id`, `sku` from `order_items` where `order_id` = ?
+```
+
+## Features
+
+- **Per-request attribution** — every statement is tied to the request that caused it (concurrent requests and a saturated connection pool included), using `AsyncLocalStorage`.
+- **Nesting tree** — transactions and savepoints, with committed / rolled-back / open status. Two transactions running in parallel inside one request are kept apart.
+- **Subquery depth** and pretty-printed SQL.
+- **Multilingual**: English, Vietnamese and Japanese — terminal, web page and floating button — and adding a language is one block of text (see [Languages](#languages)).
+- **Professional UI**: light / dark / system theme, responsive down to a narrow docked panel, keyboard navigation, syntax-highlighted SQL, timeline waterfall per statement.
+- **Three ways to look**: a tree in the terminal, a live web page (`/__sql-inspector/`), and a floating in-app launcher button with keyboard shortcuts.
+- **No changes to your queries** — it works at the `mysql2` driver level, so it covers plain `mysql2` and Drizzle ORM (both tested), and in principle anything else built on `mysql2`.
+- **Zero runtime dependencies** besides the `mysql2` peer. The web UI is a single self-contained page; nothing is loaded from a CDN.
+- **Safe by default** — never active when `NODE_ENV=production`; there it is a complete no-op.
+
+## Requirements
+
+- Node.js **20+**
+- `mysql2` **3+** (peer dependency; tested with 3.20)
+- Your app must send SQL through `mysql2` (pool, connection, or an ORM that uses it)
+
+## Install
+
+```bash
+npm install --save-dev sql-dev-inspector
+# or
+pnpm add -D sql-dev-inspector
+yarn add -D sql-dev-inspector
+```
+
+Other ways to install (from GitHub, from a `.tgz` file): see [docs/PUBLISH-AND-INSTALL.md](docs/PUBLISH-AND-INSTALL.md) *(Vietnamese)*.
+
+## Quick start
+
+The inspector turns on when `NODE_ENV=development` (or `SQL_INSPECTOR=1`). Most dev servers (`nuxt dev`, `next dev`, `vite`) set `NODE_ENV` for you; for a plain Node script run `NODE_ENV=development node server.js`.
+
+### Nuxt 3 / 4
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ["sql-dev-inspector/nuxt"]
+})
+```
+
+That's it. The module registers itself in `nuxt dev` only (nothing is added to `build` / `generate`): a Nitro plugin on the server and a floating **SQL** button in the app. Open `http://localhost:3000/__sql-inspector/` or click the button. If you set `app.baseURL`, prefix the path with it.
+
+### Nitro (without Nuxt)
+
+```ts
+// nitro.config.ts
+export default defineNitroConfig({
+  plugins: ["sql-dev-inspector/nitro"]
+})
+```
+
+### Express / Connect
+
+```ts
+import express from "express"
+import { createSqlInspector } from "sql-dev-inspector"
+
+const app = express()
+const sqlInspector = createSqlInspector()
+
+app.use(sqlInspector.middleware) // mount BEFORE any route that runs SQL
+
+app.get("/orders/:id", async (req, res) => {
+  const [rows] = await pool.query("select * from orders where id = ?", [req.params.id])
+  res.json(rows)
+})
+
+app.listen(3000)
+// open http://localhost:3000/__sql-inspector/
+```
+
+### Plain Node `http` (or any other framework)
+
+```ts
+import http from "node:http"
+import { createSqlInspector } from "sql-dev-inspector"
+
+const sqlInspector = createSqlInspector()
+
+http.createServer((req, res) => {
+  if (sqlInspector.handle(req, res)) return           // serves the inspector's own pages
+  sqlInspector.track(req, res, () => myApp(req, res)) // everything awaited inside belongs to this request
+}).listen(3000)
+```
+
+### Jobs, cron, scripts (not HTTP requests)
+
+```ts
+await sqlInspector.task("nightly-sync", async () => {
+  await syncCustomers()
+})
+// shows up in the list as a TASK named "nightly-sync"
+```
+
+### Floating button in a non-Nuxt frontend
+
+In your browser entry point (same origin as the server):
+
+```ts
+if (import.meta.env.DEV) {
+  const { mountSqlInspectorWidget } = await import("sql-dev-inspector/client")
+  mountSqlInspectorWidget({ baseURL: "/" }) // baseURL = path prefix of your server
+}
+```
+
+If your frontend runs on a different origin than the API (e.g. Vite on :5173, API on :3000), open `http://localhost:3000/__sql-inspector/` directly, or proxy `/__sql-inspector` through the frontend dev server.
+
+## Viewing the results
+
+1. **Terminal** — each request that ran SQL prints a tree when its response finishes. Silence with `SQL_INSPECTOR_LOG=0`.
+2. **Web page** `/__sql-inspector/` — live list of requests with search and *All / Issues / Errors* filters; click one for KPIs (total time, queries, SQL time and its share, transactions, subquery depth), insights, and a timeline of statements with a waterfall bar each. Click a statement for highlighted + formatted SQL, raw SQL, parameters and a copy button; click an insight to highlight the statements it is about; collapse a transaction. *Follow latest* jumps to each new request. Keyboard: `/` search, `↑` `↓` (or `j` `k`) previous / next request, `e` expand / collapse all. Language and theme (system / light / dark) are in the top bar.
+3. **Floating button** — the number on it is the query count of the latest request (amber with warnings, red with errors).
+
+| Action | How |
+|---|---|
+| Open / close the panel | Click the button, or `Alt+Shift+S`; `Esc` closes it while focus is inside |
+| Hide / show the button | `Alt+Shift+D` (the panel shortcut keeps working while hidden) |
+| Move the button | Drag it |
+| Resize the panel | Drag its edge |
+| Dock bottom / right | the two dock icons in the panel header |
+| Auto-open on warnings or errors | Settings menu (off by default) |
+| Open in a new tab · clear history | the ↗ icon in the header · "Clear history" in the settings menu |
+| Turn it off completely | Settings menu → disable (`Alt+Shift+S` brings it back) |
+
+Settings (including language) are stored in `localStorage`. The panel loads only the first time it is opened.
+
+## Insights
+
+| Insight | Triggered by | Level |
+|---|---|---|
+| N+1 | ≥ 3 SELECTs with the same shape (different values) in one request | warn |
+| Duplicate | the exact same statement ≥ 2 times | warn |
+| Slow | ≥ 100 ms (`SQL_INSPECTOR_SLOW_MS`) | warn |
+| SQL error | the statement was rejected | error |
+| Many queries | ≥ 30 statements in one request | warn |
+| `SELECT *` · deep subquery (≥ 3 levels) | | info |
+| Transaction convention *(opt-in via `SQL_INSPECTOR_TX_CONVENTION=1`)* | reads inside a transaction; several writes outside one | info |
+
+
+## Configuration
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `NODE_ENV` | — | `production` ⇒ **always off** (even with `SQL_INSPECTOR=1`); `development` ⇒ on |
+| `SQL_INSPECTOR` | — | `1` forces on outside production (e.g. `test`); `0` forces off |
+| `SQL_INSPECTOR_LANG` | `en` | Language of terminal output (`en`, `vi`, `ja`) and the web page's starting language. Only this variable counts — your machine's `LANG` is deliberately ignored |
+| `SQL_INSPECTOR_LOG` | on | `0` disables the terminal output |
+| `SQL_INSPECTOR_SLOW_MS` | `100` | slow-query threshold |
+| `SQL_INSPECTOR_MAX_REQUESTS` | `200` | requests kept in memory |
+| `SQL_INSPECTOR_MAX_QUERIES` | `1000` | statements kept per request |
+| `SQL_INSPECTOR_TX_CONVENTION` | off | `1` enables the transaction-convention insights |
+| `NO_COLOR` | — | disables terminal colors |
+
+## API
+
+```ts
+createSqlInspector(): SqlInspector
+
+interface SqlInspector {
+  enabled: boolean                       // false in production / when switched off: everything below is a no-op
+  middleware(req, res, next): void       // Connect / Express
+  handle(req, res): boolean              // true if the URL belongs to the inspector (already served)
+  track<T>(req, res, fn: () => T): T     // run fn as one tracked request
+  task<T>(name: string, fn: () => T | Promise<T>): Promise<T> // a unit of work that is not HTTP
+}
+```
+
+Lower level, for custom integrations: `startInspector`, `getInspector`, `isInspectorEnabled`, `installTracer`, `runInRequest`, `TraceStore`, `buildReport`, `buildTree`, `analyzeSql`, `fingerprintOf`, `formatSql`, plus all types.
+
+| Import | For |
+|---|---|
+| `sql-dev-inspector` | main API above |
+| `sql-dev-inspector/nuxt` | Nuxt module |
+| `sql-dev-inspector/nitro` | Nitro plugin |
+| `sql-dev-inspector/client` | `mountSqlInspectorWidget({ baseURL })` — floating button for any frontend |
+
+HTTP routes, all under `/__sql-inspector/`: `GET /` (page), `GET /api/requests`, `GET /api/requests/:id`, `GET /api/stream` (SSE), `POST /api/clear`.
+
+## How it works
+
+Every statement — from `pool.query`, a transaction or an ORM — goes through `Connection.prototype.query/execute` in `mysql2`. The inspector patches exactly that point (once, reversibly) to record the SQL, parameters, duration, row count, error and **which connection ran it**. The connection is what lets it rebuild transaction and savepoint nesting, which neither an ORM logger nor mysql2's `diagnostics_channel` can do. Each adapter wraps your request handler in an `AsyncLocalStorage` scope; the pool's `getConnection` callback is bound to the caller's context so statements queued behind a busy pool are not attributed to the wrong request.
+
+## Languages
+
+English, Tiếng Việt (`vi`) and 日本語 (`ja`) are built in.
+
+- **Web page**: first the saved choice, then `SQL_INSPECTOR_LANG` if set, then the browser language, then English. Change it any time from the top bar; `?lang=ja` in the URL overrides for that visit.
+- **Floating button**: follows the browser language, or pick one in its settings menu (the panel reloads in that language).
+- **Terminal and API `message` fields**: `SQL_INSPECTOR_LANG`, default English.
+
+Insights are returned as data (`type` + `params`) next to the ready-made `message`, so any client can phrase them itself.
+
+**Adding a language**: copy the `en` block in `src/i18n/messages.ts`, translate the values (keep every `{placeholder}`; add a `.one` variant where the singular differs, e.g. `"term.queries.one"`), add the code to the `Locale` type and to `LOCALES` in `src/i18n/index.ts`. `npm test` fails if a key or placeholder is missing. Pull requests welcome.
+
+## Styling & isolation
+
+The tool must never make your app look worse, so:
+
+- **Floating button and panel** live in a **shadow root**, reset with `all: initial`, use a custom-element host (not a `<div>`) and zero-specificity resets. Your global CSS (`button { … }`, `* { … }`, `select`, `body > *`) cannot restyle them, and they add no CSS to your page. They are `position: fixed`, never shift your layout, and don't steal focus.
+- **Inspector page** is its own document (inside an `<iframe>` when docked), so it cannot touch your page either. Every native control (buttons, switch, scrollbars) is restyled, and the language picker is a custom listbox — a native `<select>` popup is drawn by the OS and cannot be styled, so none is used anywhere (a test enforces it), with `color-scheme` declared so nothing falls back to a browser-default look in dark mode.
+- **No external requests**: no web fonts, no CDN, no analytics — system font stacks only (Latin, Japanese and Vietnamese included).
+- Respects `prefers-color-scheme`, `prefers-reduced-motion`, and keyboard focus (`:focus-visible`).
+- If your app sets a strict Content-Security-Policy, the floating button needs `style-src 'unsafe-inline'` (it injects one `<style>` into its shadow root) and `frame-src 'self'`. This is a dev-only tool; relax the policy for development only.
+
+## Security & privacy
+
+- `NODE_ENV=production` is a hard stop: nothing is patched and the middleware only calls `next()`.
+- The Nuxt module registers only in `nuxt dev`; `build` / `generate` contain nothing of this tool.
+- Data lives in the memory of the dev process only: no files written, no network calls.
+- ⚠️ **Displayed SQL contains real values**, possibly personal data from the database you point at. Don't share your screen or screenshots while connected to staging or production-like data.
+- `/__sql-inspector/` has **no authentication** — it is meant for `localhost`. Don't expose your dev server to a shared network (e.g. `--host 0.0.0.0`) while it is on.
+
+## Limitations
+
+- **MySQL via `mysql2` only.** Not PostgreSQL, SQLite, or other MySQL drivers (e.g. `mariadb`). ORMs that don't use `mysql2` underneath (e.g. Prisma's own engine) bypass the patched point.
+- **Tested with**: plain `mysql2` (pool, connection, manual transactions) and Drizzle ORM. Knex / Sequelize / TypeORM use `mysql2` and should work, but have no dedicated tests — please open an issue if they don't.
+- The Express/Connect adapter is tested with a faithful fake `req`/`res`, not with `express` itself; the floating button outside Nuxt is tested in happy-dom only.
+- **No "caller" line**: ORMs like Drizzle return lazy thenables, so by the time the query runs the call stack no longer contains your code.
+- A lazy builder created inside a request scope but awaited outside it is not attributed to that request.
+- Statements outside any request or task are grouped under one "(outside request)" entry.
+- Requests that run no SQL (assets, HMR) are not kept.
+
+## Troubleshooting
+
+| Symptom | Likely cause |
+|---|---|
+| Nothing shows up | `NODE_ENV` isn't `development`; run with `NODE_ENV=development` or `SQL_INSPECTOR=1` (and never `production`) |
+| Terminal output but `/__sql-inspector/` is 404 | Express: mount the middleware before your router. Nuxt/Nitro: check `app.baseURL` |
+| All queries under "(outside request)" | middleware mounted after the route that ran SQL, or SQL ran outside an awaited handler (timers, queues) — wrap it in `sqlInspector.task()` |
+| Floating button missing | Non-Nuxt: you haven't called `mountSqlInspectorWidget`. Nuxt: it exists in `nuxt dev` only. Try `Alt+Shift+D`, or clear the `sqlDevInspector.widget` key in `localStorage` |
+| An ORM's queries are missing | It doesn't use `mysql2` underneath |
+| Two copies of `mysql2` in `node_modules` | The inspector patches the copy it can import; make sure app and inspector share one (hoisted peer) |
+
+## Development
+
+```bash
+npm install
+npm run typecheck
+npm test            # 131 tests: real mysql2 + Drizzle against an in-memory MySQL protocol server
+npm run build
+```
+
+Tests need no MySQL installation and open no ports: `test/mock-mysql-server.ts` speaks the real wire protocol over in-memory streams.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/dist/client/nuxt-plugin.client.d.ts

@@ -0,0 +1,2 @@
+declare const _default: unknown;
+export default _default;

package/dist/client/nuxt-plugin.client.js

@@ -0,0 +1,11 @@
+import { defineNuxtPlugin, useRuntimeConfig } from "#app";
+import { mountSqlInspectorWidget } from "./widget.js";
+// Dev only, twice over: the module registers this plugin in `nuxt dev` only, and the plugin
+// itself does nothing outside dev.
+export default defineNuxtPlugin(() => {
+    const config = useRuntimeConfig();
+    if (!import.meta.dev) {
+        return;
+    }
+    mountSqlInspectorWidget({ baseURL: config.app.baseURL });
+});