sql-dev-inspector 1.0.0 → 1.0.1

package/CHANGELOG.md

@@ -1,3 +1,13 @@
 # Changelog
 
+## [1.0.1] - 2026-10-19
 
+### Changed
+
+- CI: publish to npm automatically through trusted publishing (OIDC) when a GitHub Release is published. Provenance is attached automatically.
+
+## [1.0.0] - 2026-10-19
+
+### Added
+
+- Initial release.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sql-dev-inspector",
   "type": "module",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Dev-only SQL inspector for Node apps that talk to MySQL through mysql2 (Drizzle, Knex, Sequelize, TypeORM…): see which SQL each request ran, how transactions and subqueries nest, N+1 and slow queries. Terminal tree, web UI and a floating in-app launcher.",
   "author": "Nhu Duy Thin",
   "license": "MIT",

package/README.VI.md

@@ -1,341 +0,0 @@
-# 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/docs/PUBLISH-AND-INSTALL.md

@@ -1,267 +0,0 @@
-# Đưa lên Git public & hướng dẫn cài đặt cho mọi người
-
-Tài liệu gồm 3 phần:
-
-- **Phần A** — chuẩn bị gói trước khi công khai, và **cái gì đẩy lên git / cái gì không** (A4)
-- **Phần B** — đưa mã nguồn lên Git public (GitHub) và (tuỳ chọn) publish lên npm
-- **Phần C** — hướng dẫn cho người khác cài vào dự án của họ
-
-> ⚠️ **Công khai là hành động khó thu hồi.** Mã đã public có thể bị clone, cache, index (kể cả sau khi xoá).
-> Các bước dưới đây **bạn tự thực hiện**; mỗi bước đều ghi rõ tác động. Đừng bỏ qua checklist ở A3.
-
----
-
-## Phần A. Chuẩn bị
-
-### A1. Thay các chỗ giữ chỗ (placeholder)
-
-Tìm và thay trong gói:
-
-| Nơi | Cần thay | Ghi chú |
-|---|---|---|
-| `package.json` → `name` | `sql-dev-inspector` | Tên mặc định. Có thể đổi (ví dụ `@your-scope/sql-dev-inspector`); nếu đổi, sửa cả README và mọi `import "sql-dev-inspector/..."` |
-| `package.json` → `author` | `<YOUR NAME OR ORGANIZATION>` | Tên cá nhân hoặc tổ chức hiển thị công khai |
-| `package.json` → `repository.url`, `homepage`, `bugs.url` | `<YOUR-ORG>` | URL repo GitHub sẽ tạo ở B1 |
-| `LICENSE` | `<YOUR NAME OR ORGANIZATION>` | Chủ bản quyền |
-
-Lệnh tìm chỗ còn sót:
-
-```bash
-grep -rn "YOUR" --exclude-dir=node_modules --exclude-dir=dist .
-```
-
-### A2. Chọn giấy phép
-
-Gói mặc định dùng **MIT** (cho phép dùng/sửa/phân phối tự do, kể cả thương mại). Nếu tổ chức của bạn yêu cầu giấy phép khác hoặc phải được pháp chế/quản lý duyệt trước khi mở mã nguồn, **hỏi trước khi công khai**, rồi sửa `LICENSE` và `"license"` trong `package.json` cho khớp.
-
-### A3. Checklist trước khi public
-
-- [ ] Không có bí mật trong mã: không `.env`, token, key, mật khẩu, URL nội bộ. (Gói này không chứa; vẫn nên chạy lại lệnh dưới.)
-- [ ] Không có tên dự án / khách hàng / hạ tầng nội bộ trong mã, test, README, lịch sử git.
-- [ ] Đã đồng ý với giấy phép (A2) và tên tác giả (A1).
-- [ ] `npm install && npm run typecheck && npm test && npm run build` đều thành công.
-
-```bash
-grep -rniE "password|secret|token|api[_-]?key|BEGIN (RSA|PRIVATE)" --exclude-dir=node_modules --exclude-dir=dist . | head
-```
-
-(Kết quả có thể có vài chữ "token" vô hại trong mã phân tích SQL; hãy đọc từng dòng.)
-
-### A4. Cái gì đẩy lên Git, cái gì không
-
-Có **ba nơi** khác nhau mà mã đi tới. Mỗi nơi nhận một phần khác nhau:
-
-| Nơi | Là gì | Ai thấy |
-|---|---|---|
-| **1. Repo public `sql-dev-inspector`** | Mã nguồn của tool (thư mục `sql-dev-inspector/` trong file zip) | Mọi người |
-| **2. npm registry** (tuỳ chọn, B4) | Bản đã build để cài | Mọi người |
-| **3. Repo nội bộ của dự án (ví dụ Alps)** | Dự án dùng tool | Chỉ nội bộ — **không bao giờ public** |
-
-#### 1. Repo public `sql-dev-inspector`
-
-| ✅ Đẩy lên (được `git add .` lấy) | Vì sao |
-|---|---|
-| `src/` | Mã nguồn |
-| `test/` | Test, kèm MySQL giả — người đóng góp cần để chạy test |
-| `docs/` | Tài liệu (file này) |
-| `README.md` (English), `README.VI.md` (tiếng Việt), `CHANGELOG.md`, `LICENSE` | Tài liệu và giấy phép |
-| `package.json` | Metadata, scripts, dependencies |
-| `package-lock.json` | Khoá phiên bản — sinh ra sau lần `npm install` đầu tiên, nên commit |
-| `tsconfig.json`, `tsconfig.build.json`, `vitest.config.ts` | Cấu hình build / test |
-| `.gitignore` | Để người khác không vô tình commit rác |
-| `.github/workflows/ci.yml` | CI chạy test mỗi lần push / PR |
-
-| ❌ KHÔNG đẩy lên | Vì sao | Đã được chặn bởi |
-|---|---|---|
-| `node_modules/` | Sinh lại bằng `npm install` | `.gitignore` |
-| `dist/` | Sản phẩm build; chỉ đi lên **npm**, không đi lên git | `.gitignore` |
-| `*.tgz`, file `.zip` | Gói phân phối. Muốn chia sẻ thì đính kèm vào *GitHub Release*, đừng commit | `.gitignore` (`*.tgz`) — zip không nằm trong repo |
-| `.env*`, token, key | Bí mật (gói này không có, giữ nguyên như vậy) | tự kiểm tra ở A3 |
-| `.claude/`, `.vite/`, `coverage/`, `.DS_Store`, `*.log` | File của công cụ / máy cá nhân | `.gitignore` |
-
-Kiểm tra trước khi commit:
-
-```bash
-git status                      # chỉ thấy các file ✅ ở bảng trên
-git ls-files                    # danh sách file sẽ nằm trong repo
-git check-ignore -v dist node_modules   # xác nhận 2 thư mục này bị bỏ qua
-```
-
-#### 2. Cái gì lên npm (khi `npm publish`)
-
-Do `files` trong `package.json` quyết định, **không phải** `.gitignore`: chỉ `dist/`, `docs/`, `README.md`, `README.VI.md`, `LICENSE`, `CHANGELOG.md` (+ `package.json`). `src/`, `test/`, cấu hình CI **không** lên npm. Xem trước bằng:
-
-```bash
-npm publish --dry-run     # hoặc: npm pack --dry-run
-```
-
-#### 3. Repo nội bộ của dự án dùng tool (ví dụ Alps)
-
-| ✅ Commit vào repo dự án | ❌ Không commit |
-|---|---|
-| Dòng cấu hình bật tool (`modules: ["sql-dev-inspector/nuxt"]` hoặc middleware) | File `.zip` / `.tgz` của tool (`tools/release/`) |
-| Dòng `sql-dev-inspector` trong `devDependencies` + lockfile | `node_modules/`, `dist/`, `.nuxt/` |
-| | Mọi thứ trong thư mục scratch / thử nghiệm |
-
-Hai giai đoạn:
-
-- **Trước khi tool có repo public / npm** (hiện tại): mã nguồn tool nằm tạm trong repo dự án ở `tools/sql-inspector/`, `nuxt.config.ts` trỏ tới `./tools/sql-inspector/src/nuxt`. Commit cả thư mục `tools/sql-inspector/` (trừ `dist/`, `node_modules/`) và thêm `tools/release/` vào `.gitignore` của dự án.
-- **Sau khi tool đã publish** (khuyến nghị): xoá thư mục `tools/sql-inspector/` khỏi repo dự án, `npm i -D sql-dev-inspector`, đổi `nuxt.config.ts` sang `"sql-dev-inspector/nuxt"`. Từ đó repo public là **nguồn duy nhất**; không giữ hai bản mã nguồn song song.
-
-> ⚠️ Không bao giờ đổi repo dự án nội bộ sang Public chỉ để chia sẻ tool. Tool có repo riêng (Phần B) chính là để làm việc này.
-
----
-
-## Phần B. Lên Git public
-
-### B1. Tạo repo trống trên GitHub
-
-1. Vào GitHub → **New repository**.
-2. Đặt tên (khuyến nghị trùng tên package), **không** tick "Add a README / .gitignore / license" (gói đã có sẵn).
-3. Chọn **Public** → *tác động: bất kỳ ai trên Internet đều xem và clone được mã này.* (Nếu chưa chắc, chọn **Private** trước; đổi sang Public sau ở *Settings → General → Danger Zone → Change visibility*.)
-4. Bấm **Create repository**, copy URL (ví dụ `https://github.com/<your-org>/sql-dev-inspector.git`).
-
-### B2. Đẩy mã lên
-
-Giải nén file zip (hoặc dùng thư mục `sql-dev-inspector/` trong gói), rồi:
-
-```bash
-cd sql-dev-inspector
-git init -b main
-git add .
-git status          # ← kiểm tra danh sách file: không có node_modules, dist, .env
-git commit -m "feat: initial release 1.0.0"
-git remote add origin https://github.com/<your-org>/sql-dev-inspector.git
-git push -u origin main
-```
-
-*Tác động của `git push`: mã nguồn được gửi lên GitHub; nếu repo là Public thì công khai ngay.*
-
-> **Đang ở trong monorepo và muốn giữ lịch sử commit riêng của thư mục này?** Dùng `git subtree split` thay vì copy:
-> ```bash
-> git subtree split --prefix=tools/sql-inspector -b sql-inspector-only
-> git push https://github.com/<your-org>/sql-dev-inspector.git sql-inspector-only:main
-> ```
-> Lưu ý: cách này đẩy **toàn bộ lịch sử** của thư mục đó; kiểm tra lịch sử không chứa thông tin nội bộ trước khi push.
-
-### B3. Thiết lập repo sau khi đẩy lên
-
-1. **CI**: file `.github/workflows/ci.yml` chạy typecheck + build + test trên Node 20/22/24 mỗi lần push / PR. Kiểm tra tab *Actions*.
-2. **Mô tả & topics** (*About* ở trang repo): `mysql`, `mysql2`, `sql`, `devtools`, `drizzle`, `nuxt`, `express`.
-3. **Bảo vệ nhánh `main`** (*Settings → Branches*): yêu cầu PR + CI xanh trước khi merge (khuyến nghị nếu có nhiều người đóng góp).
-4. **Tag phiên bản**:
-   ```bash
-   git tag v1.0.0
-   git push origin v1.0.0
-   ```
-   Rồi *Releases → Draft a new release* chọn tag `v1.0.0`, dán nội dung `CHANGELOG.md`.
-
-### B4. (Tuỳ chọn) Publish lên npm
-
-Chỉ làm khi muốn mọi người `npm install sql-dev-inspector` không cần trỏ vào GitHub.
-
-*Tác động: tên package bị chiếm công khai trên npm; mỗi phiên bản đã publish **không thể ghi đè** (chỉ có thể deprecate, và unpublish bị giới hạn).*
-
-```bash
-npm view sql-dev-inspector        # nếu trả về thông tin => tên đã bị chiếm, hãy đổi tên (A1)
-npm login                            # đăng nhập tài khoản npm (nên bật 2FA)
-npm publish --dry-run                # xem trước danh sách file sẽ lên npm (chỉ dist, docs, README.md, README.VI.md, LICENSE, CHANGELOG)
-npm publish --access public          # publish thật (chạy typecheck/build/test qua prepublishOnly)
-```
-
-Với package có scope (`@your-scope/...`) bắt buộc `--access public` thì mới public.
-
-Phát hành phiên bản mới:
-
-```bash
-# sửa CHANGELOG.md, rồi:
-npm version patch        # hoặc minor / major  (tự tạo commit + tag)
-git push && git push --tags
-npm publish --access public
-```
-
----
-
-## Phần C. Hướng dẫn cài đặt cho mọi người
-
-> Dán nguyên phần này vào wiki / Slack / README nội bộ nếu cần.
-
-### C1. Chọn cách cài
-
-| Cách | Khi nào dùng | Lệnh |
-|---|---|---|
-| **npm registry** | Đã publish (B4) | `npm i -D sql-dev-inspector` |
-| **Từ GitHub** | Chưa publish npm, repo đã public | `npm i -D github:<your-org>/sql-dev-inspector` |
-| **Từ GitHub, cố định phiên bản** | Nên dùng thay cho nhánh `main` | `npm i -D github:<your-org>/sql-dev-inspector#v1.0.0` |
-| **File `.tgz`** | Offline / chưa có repo | `npm i -D ./sql-dev-inspector-1.0.0.tgz` |
-| **Link thư mục local** | Đang sửa tool và thử trong dự án khác | `npm i -D ../sql-dev-inspector` (hoặc `pnpm add -D link:../sql-dev-inspector`) |
-
-Với pnpm / yarn thay `npm i -D` bằng `pnpm add -D` / `yarn add -D`.
-Cài từ GitHub sẽ tự chạy `prepare` (build `dist/`) nên cần mạng để tải `typescript`.
-
-Điều kiện: Node.js ≥ 20, dự án có `mysql2` ≥ 3 (`npm i mysql2` nếu chưa có).
-
-### C2. Bật trong dự án
-
-**Nuxt** — `nuxt.config.ts`:
-
-```ts
-export default defineNuxtConfig({
-  modules: ["sql-dev-inspector/nuxt"]
-})
-```
-
-**Nitro** — `nitro.config.ts`:
-
-```ts
-export default defineNitroConfig({ plugins: ["sql-dev-inspector/nitro"] })
-```
-
-**Express / Connect**:
-
-```ts
-import { createSqlInspector } from "sql-dev-inspector"
-const sqlInspector = createSqlInspector()
-app.use(sqlInspector.middleware)   // trước mọi route có chạy SQL
-```
-
-**Node `http` thuần**:
-
-```ts
-const sqlInspector = createSqlInspector()
-http.createServer((req, res) => {
-  if (sqlInspector.handle(req, res)) return
-  sqlInspector.track(req, res, () => app(req, res))
-})
-```
-
-**Job / cron**: `await sqlInspector.task("tên-job", async () => { … })`.
-
-### C3. Chạy và kiểm tra
-
-1. Chạy dev server với `NODE_ENV=development` (`nuxt dev`, `next dev`, `vite`… tự đặt; với script Node thuần: `NODE_ENV=development node server.js`).
-2. Terminal in dòng `[sql-inspector] bật …` (Nuxt/Nitro) — hoặc không in gì cho tới khi có request chạy SQL.
-3. Gọi một API, terminal in cây SQL; mở `http://localhost:<port>/__sql-inspector/`.
-4. Nuxt: nút **SQL** ở góc phải dưới; phím tắt `Alt+Shift+S` (mở/đóng), `Alt+Shift+D` (ẩn/hiện nút).
-
-Không thấy gì? Xem mục *Xử lý sự cố* trong [README](../README.VI.md#xử-lý-sự-cố).
-
-### C4. Tắt / gỡ
-
-- Tắt tạm: chạy với `SQL_INSPECTOR=0`.
-- Tắt từ nút nổi: menu *⚙ Tuỳ chỉnh → Tắt SQL Inspector*.
-- Gỡ hẳn: xoá dòng cấu hình (module / plugin / middleware) rồi `npm rm sql-dev-inspector`.
-
-### C5. An toàn
-
-- Tool **không chạy ở production** (`NODE_ENV=production` là hard stop), nhưng vẫn nên giữ ở `devDependencies` nếu dự án chỉ dùng cho Nuxt/Nitro dev.
-- SQL hiển thị gồm **giá trị thật** (có thể là dữ liệu cá nhân): đừng chia sẻ màn hình/ảnh chụp khi trỏ vào DB thật; đừng mở cổng dev ra mạng chung khi đang bật tool.
-
-### C6. Cập nhật phiên bản
-
-```bash
-npm update sql-dev-inspector                         # từ npm
-npm i -D github:<your-org>/sql-dev-inspector#v1.1.0  # từ GitHub: đổi tag
-```
-
-Xem thay đổi ở [CHANGELOG.md](../CHANGELOG.md).