sql-dev-inspector 0.0.0-stage → 1.0.0

package/dist/ui/styles.js

@@ -0,0 +1,207 @@
+/**
+ * Styles of the inspector page. The page runs on its own document (served by the inspector,
+ * shown standalone or inside the floating panel's iframe), so nothing here can reach the host
+ * application. Everything is still scoped to our own elements and every native control is
+ * restyled, so no browser-default widget shows through.
+ */
+const DARK = `
+  --bg: #0d1117; --surface: #151b23; --surface-2: #1b232d; --surface-3: #242e3a;
+  --border: #283241; --border-strong: #3a4757;
+  --text: #e6edf3; --text-2: #aab5c3; --text-3: #7d8896;
+  --accent: #5aa2ff; --accent-weak: rgba(90, 162, 255, .14); --accent-text: #0d1117;
+  --ok: #4ac26b; --ok-weak: rgba(74, 194, 107, .14);
+  --warn: #e3a008; --warn-weak: rgba(227, 160, 8, .14);
+  --err: #ff6b6b; --err-weak: rgba(255, 107, 107, .15);
+  --shadow: 0 8px 24px rgba(0, 0, 0, .45);
+  --syn-kw: #c792ea; --syn-str: #8bd49c; --syn-num: #f2a65e; --syn-id: #7cb7ff; --syn-fn: #e6c07b; --syn-com: #7d8896;
+`;
+export const STYLES = `
+:root {
+  --font: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, "Noto Sans", "Hiragino Sans", "Yu Gothic UI", "Apple SD Gothic Neo", sans-serif;
+  --mono: ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, "Liberation Mono", monospace;
+  --radius: 8px; --radius-sm: 6px;
+  --bg: #f5f7fa; --surface: #ffffff; --surface-2: #f1f4f8; --surface-3: #e6ebf1;
+  --border: #e2e7ee; --border-strong: #cdd5df;
+  --text: #121821; --text-2: #4a5666; --text-3: #6e7a8a;
+  --accent: #1f6feb; --accent-weak: #e7f0ff; --accent-text: #ffffff;
+  --ok: #1a7f37; --ok-weak: #e6f5ea;
+  --warn: #9a6700; --warn-weak: #fff4d6;
+  --err: #cf222e; --err-weak: #ffebe9;
+  --shadow: 0 8px 24px rgba(20, 30, 50, .14);
+  --syn-kw: #8250df; --syn-str: #0a7a3d; --syn-num: #b35900; --syn-id: #0550ae; --syn-fn: #8a5a00; --syn-com: #6e7a8a;
+  color-scheme: light;
+}
+@media (prefers-color-scheme: dark) { :root:not([data-theme="light"]) { ${DARK} color-scheme: dark; } }
+:root[data-theme="dark"] { ${DARK} color-scheme: dark; }
+
+*, *::before, *::after { box-sizing: border-box; }
+html, body { height: 100%; }
+body { margin: 0; background: var(--bg); color: var(--text); font: 13px/1.5 var(--font); -webkit-font-smoothing: antialiased; text-rendering: optimizeLegibility; overflow: hidden; }
+[hidden] { display: none !important; }
+button, input, select { font: inherit; color: inherit; }
+button { appearance: none; background: none; border: 0; padding: 0; cursor: pointer; }
+svg { width: 16px; height: 16px; flex: none; stroke: currentColor; fill: none; stroke-width: 1.8; stroke-linecap: round; stroke-linejoin: round; }
+:focus { outline: none; }
+:focus-visible { outline: 2px solid var(--accent); outline-offset: 1px; border-radius: 4px; }
+.sr-only { position: absolute; width: 1px; height: 1px; overflow: hidden; clip: rect(0 0 0 0); white-space: nowrap; }
+* { scrollbar-width: thin; scrollbar-color: var(--border-strong) transparent; }
+::-webkit-scrollbar { width: 10px; height: 10px; }
+::-webkit-scrollbar-thumb { background: var(--border-strong); border-radius: 8px; border: 2px solid transparent; background-clip: content-box; }
+::-webkit-scrollbar-track { background: transparent; }
+
+/* ── Shell ─────────────────────────────────────────────────────────── */
+.app { display: flex; flex-direction: column; height: 100%; }
+.topbar { display: flex; align-items: center; gap: 12px; height: 52px; padding: 0 16px; background: var(--surface); border-bottom: 1px solid var(--border); flex: none; }
+.brand { display: flex; align-items: center; gap: 10px; font-weight: 650; font-size: 14px; letter-spacing: -.01em; white-space: nowrap; }
+.brand-mark { display: grid; place-items: center; width: 28px; height: 28px; border-radius: 8px; background: linear-gradient(135deg, #1f6feb, #7a5af8); color: #fff; }
+.brand-mark svg { width: 16px; height: 16px; stroke: #fff; }
+.live { display: inline-flex; align-items: center; gap: 6px; padding: 2px 9px 2px 8px; border-radius: 999px; font-size: 11.5px; font-weight: 600; color: var(--text-2); background: var(--surface-2); border: 1px solid var(--border); white-space: nowrap; }
+.live i { width: 7px; height: 7px; border-radius: 50%; background: var(--err); }
+.live.on i { background: var(--ok); box-shadow: 0 0 0 3px var(--ok-weak); }
+.spacer { flex: 1; }
+.field { position: relative; display: flex; align-items: center; }
+.field > svg { position: absolute; left: 10px; color: var(--text-3); pointer-events: none; }
+.input { height: 32px; width: 260px; padding: 0 34px 0 32px; border: 1px solid var(--border); border-radius: var(--radius-sm); background: var(--surface-2); color: var(--text); transition: border-color .15s, background .15s, box-shadow .15s; }
+.input::placeholder { color: var(--text-3); }
+.input:hover { border-color: var(--border-strong); }
+.input:focus { border-color: var(--accent); background: var(--surface); box-shadow: 0 0 0 3px var(--accent-weak); outline: none; }
+.kbd { font: 600 11px/1 var(--mono); min-width: 18px; padding: 3px 5px; text-align: center; border: 1px solid var(--border-strong); border-bottom-width: 2px; border-radius: 4px; background: var(--surface); color: var(--text-2); }
+.field .kbd { position: absolute; right: 8px; }
+.btn { display: inline-flex; align-items: center; gap: 6px; height: 32px; padding: 0 12px; border: 1px solid var(--border); border-radius: var(--radius-sm); background: var(--surface); color: var(--text); font-weight: 550; white-space: nowrap; transition: background .15s, border-color .15s; }
+.btn:hover { background: var(--surface-2); border-color: var(--border-strong); }
+.btn:active { background: var(--surface-3); }
+.btn.icon { width: 32px; padding: 0; justify-content: center; }
+.btn.ghost { border-color: transparent; background: transparent; }
+.btn.ghost:hover { background: var(--surface-2); }
+.btn.sm { height: 26px; padding: 0 9px; font-size: 12px; }
+.dd { position: relative; display: inline-flex; }
+.dd-btn { display: inline-flex; align-items: center; gap: 8px; height: 32px; padding: 0 10px; border: 1px solid var(--border); border-radius: var(--radius-sm); background: var(--surface); color: var(--text); font-weight: 550; white-space: nowrap; transition: background .15s, border-color .15s; }
+.dd-btn:hover { background: var(--surface-2); border-color: var(--border-strong); }
+.dd-btn[aria-expanded="true"] { border-color: var(--accent); box-shadow: 0 0 0 3px var(--accent-weak); }
+.dd-btn svg { color: var(--text-3); } .dd-btn svg:last-child { width: 12px; height: 12px; }
+.dd-menu { position: absolute; z-index: 40; right: 0; top: calc(100% + 6px); min-width: 188px; margin: 0; padding: 4px; list-style: none; border: 1px solid var(--border); border-radius: 10px; background: var(--surface); box-shadow: var(--shadow); }
+.dd-item { display: flex; align-items: center; gap: 10px; height: 34px; padding: 0 10px; border-radius: 6px; color: var(--text); cursor: pointer; user-select: none; }
+.dd-item:hover, .dd-item:focus-visible { background: var(--surface-2); outline: none; }
+.dd-item .check { width: 14px; height: 14px; color: var(--accent); visibility: hidden; }
+.dd-item[aria-selected="true"] { font-weight: 650; }
+.dd-item[aria-selected="true"] .check { visibility: visible; }
+.dd-item .code { margin-left: auto; color: var(--text-3); font: 600 11px var(--mono); text-transform: uppercase; }
+.seg { display: inline-flex; padding: 2px; gap: 2px; border-radius: var(--radius-sm); background: var(--surface-2); border: 1px solid var(--border); }
+.seg button { height: 26px; padding: 0 10px; border-radius: 4px; color: var(--text-2); font-weight: 550; font-size: 12px; }
+.seg button:hover { color: var(--text); }
+.seg button[aria-pressed="true"] { background: var(--surface); color: var(--text); box-shadow: 0 1px 2px rgba(0, 0, 0, .12); }
+.switch { display: inline-flex; align-items: center; gap: 8px; color: var(--text-2); font-weight: 550; font-size: 12px; cursor: pointer; }
+.switch .track { position: relative; width: 28px; height: 16px; border-radius: 999px; background: var(--border-strong); transition: background .15s; }
+.switch .track::after { content: ""; position: absolute; top: 2px; left: 2px; width: 12px; height: 12px; border-radius: 50%; background: #fff; box-shadow: 0 1px 2px rgba(0, 0, 0, .3); transition: transform .15s; }
+.switch[aria-checked="true"] .track { background: var(--accent); }
+.switch[aria-checked="true"] .track::after { transform: translateX(12px); }
+
+.layout { flex: 1; display: grid; grid-template-columns: minmax(280px, 360px) 1fr; min-height: 0; }
+.list { display: flex; flex-direction: column; min-height: 0; background: var(--surface); border-right: 1px solid var(--border); }
+.list-head { display: flex; align-items: center; gap: 8px; padding: 10px 12px; border-bottom: 1px solid var(--border); }
+.list-head h2 { margin: 0; font-size: 12px; text-transform: uppercase; letter-spacing: .06em; color: var(--text-3); font-weight: 650; }
+.count { padding: 0 7px; border-radius: 999px; background: var(--surface-3); color: var(--text-2); font-size: 11px; font-weight: 650; line-height: 18px; }
+.list-body { flex: 1; overflow: auto; }
+.req { position: relative; display: block; width: 100%; text-align: left; padding: 10px 12px 10px 15px; border-bottom: 1px solid var(--border); }
+.req::before { content: ""; position: absolute; left: 0; top: 0; bottom: 0; width: 3px; background: transparent; }
+.req.has-warn::before { background: var(--warn); } .req.has-err::before { background: var(--err); }
+.req:hover { background: var(--surface-2); }
+.req[aria-selected="true"] { background: var(--accent-weak); }
+.req-top { display: flex; align-items: center; gap: 8px; min-width: 0; }
+.req-url { flex: 1; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; font-family: var(--mono); font-size: 12px; }
+.req-meta { display: flex; align-items: center; gap: 10px; margin-top: 3px; color: var(--text-3); font-size: 11.5px; }
+.req-meta .dot { width: 3px; height: 3px; border-radius: 50%; background: var(--border-strong); }
+
+.method { font: 700 10.5px/1 var(--mono); letter-spacing: .02em; padding: 3px 6px; border-radius: 4px; background: var(--surface-3); color: var(--text-2); }
+.method.GET { background: var(--ok-weak); color: var(--ok); } .method.POST { background: var(--accent-weak); color: var(--accent); }
+.method.PUT, .method.PATCH { background: var(--warn-weak); color: var(--warn); } .method.DELETE { background: var(--err-weak); color: var(--err); }
+.status { font: 650 11.5px/1 var(--mono); color: var(--text-2); }
+.status.s2 { color: var(--ok); } .status.s3 { color: var(--accent); } .status.s4 { color: var(--warn); } .status.s5 { color: var(--err); }
+.chip { display: inline-flex; align-items: center; gap: 4px; height: 20px; padding: 0 8px; border-radius: 999px; font-size: 11px; font-weight: 650; background: var(--surface-3); color: var(--text-2); white-space: nowrap; }
+.chip.ok { background: var(--ok-weak); color: var(--ok); } .chip.warn { background: var(--warn-weak); color: var(--warn); } .chip.err { background: var(--err-weak); color: var(--err); } .chip.accent { background: var(--accent-weak); color: var(--accent); }
+.chip svg { width: 12px; height: 12px; }
+
+.detail { overflow: auto; min-width: 0; }
+.detail-inner { max-width: 1180px; margin: 0 auto; padding: 20px 24px 40px; }
+.detail-head { display: flex; align-items: center; gap: 10px; flex-wrap: wrap; margin-bottom: 14px; }
+.detail-head h1 { margin: 0; font: 600 15px/1.4 var(--mono); word-break: break-all; flex: 1; min-width: 200px; }
+.back { display: none; }
+.kpis { display: grid; grid-template-columns: repeat(auto-fit, minmax(150px, 1fr)); gap: 12px; margin-bottom: 20px; }
+.kpi { padding: 12px 14px; background: var(--surface); border: 1px solid var(--border); border-radius: var(--radius); }
+.kpi-label { color: var(--text-3); font-size: 11.5px; font-weight: 600; }
+.kpi-value { margin-top: 2px; font-size: 22px; font-weight: 650; letter-spacing: -.02em; font-variant-numeric: tabular-nums; }
+.kpi-sub { color: var(--text-3); font-size: 11.5px; }
+.section { margin-bottom: 22px; }
+.section-head { display: flex; align-items: center; gap: 8px; margin-bottom: 8px; }
+.section-head h2 { margin: 0; font-size: 12px; text-transform: uppercase; letter-spacing: .06em; color: var(--text-3); font-weight: 650; }
+.card { background: var(--surface); border: 1px solid var(--border); border-radius: var(--radius); overflow: hidden; }
+.insight { display: flex; gap: 10px; width: 100%; text-align: left; padding: 10px 14px; border-bottom: 1px solid var(--border); }
+.insight:last-child { border-bottom: 0; }
+.insight:hover { background: var(--surface-2); }
+.insight .ico { margin-top: 1px; }
+.insight.warn .ico { color: var(--warn); } .insight.error .ico { color: var(--err); } .insight.info .ico { color: var(--text-3); }
+.insight-title { font-weight: 650; }
+.insight-msg { color: var(--text-2); font-size: 12.5px; word-break: break-word; }
+.insight-msg code { font: 12px var(--mono); }
+.empty-ok { padding: 14px; color: var(--text-2); display: flex; gap: 8px; align-items: center; }
+.empty-ok svg { color: var(--ok); }
+.empty { display: grid; place-items: center; align-content: center; gap: 6px; height: 100%; min-height: 240px; padding: 32px; text-align: center; color: var(--text-2); }
+.empty svg.big { width: 44px; height: 44px; stroke-width: 1.3; color: var(--text-3); }
+.empty h3 { margin: 6px 0 0; font-size: 14px; color: var(--text); }
+.empty p { margin: 0; max-width: 340px; color: var(--text-3); }
+
+/* ── Query tree ───────────────────────────────────────────────────── */
+.tree-bar { display: flex; align-items: center; gap: 8px; margin-bottom: 8px; }
+.axis { display: flex; justify-content: space-between; margin: 0 12px 4px auto; width: var(--wf, 220px); color: var(--text-3); font: 11px var(--mono); }
+.tx { margin: 6px 0; border: 1px solid var(--border); border-left: 3px solid var(--accent); border-radius: var(--radius); background: color-mix(in srgb, var(--accent-weak) 35%, var(--surface)); }
+.tx.rolled-back { border-left-color: var(--err); } .tx.committed { border-left-color: var(--ok); } .tx.open { border-left-color: var(--warn); }
+.tx > .tx-head { display: flex; align-items: center; gap: 8px; width: 100%; padding: 7px 10px; text-align: left; font-weight: 650; }
+.tx-head .dim { font-weight: 500; }
+.tx-children { padding: 0 8px 8px; }
+.q { margin: 4px 0; border: 1px solid var(--border); border-radius: var(--radius); background: var(--surface); }
+.q.hl { box-shadow: 0 0 0 2px var(--accent); border-color: var(--accent); }
+.q.err { border-color: var(--err); }
+.q-head { display: grid; grid-template-columns: 1fr var(--wf, 220px); align-items: center; gap: 12px; width: 100%; padding: 7px 12px; text-align: left; }
+.q-main { min-width: 0; }
+.q-line { display: flex; align-items: center; gap: 8px; min-width: 0; }
+.chev { transition: transform .15s; color: var(--text-3); }
+.q.open .chev, .tx.expanded > .tx-head .chev { transform: rotate(90deg); }
+.kind { font: 700 10.5px/1 var(--mono); padding: 3px 6px; border-radius: 4px; background: var(--surface-3); color: var(--text-2); min-width: 54px; text-align: center; }
+.kind.select { background: var(--accent-weak); color: var(--accent); } .kind.insert { background: var(--ok-weak); color: var(--ok); }
+.kind.update { background: var(--warn-weak); color: var(--warn); } .kind.delete { background: var(--err-weak); color: var(--err); }
+.tables { font-weight: 600; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; min-width: 0; }
+.dim { color: var(--text-3); }
+.num { font: 12px var(--mono); font-variant-numeric: tabular-nums; color: var(--text-2); white-space: nowrap; }
+.preview { margin-top: 3px; font: 11.5px/1.4 var(--mono); color: var(--text-3); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.wf { position: relative; height: 8px; border-radius: 4px; background: var(--surface-3); }
+.wf i { position: absolute; top: 0; bottom: 0; min-width: 2px; border-radius: 4px; background: var(--accent); }
+.wf i.slow { background: var(--warn); } .wf i.err { background: var(--err); }
+.q-body { display: none; padding: 10px 12px 12px; border-top: 1px solid var(--border); background: var(--surface-2); border-radius: 0 0 var(--radius) var(--radius); }
+.q.open .q-body { display: block; }
+.q-tools { display: flex; align-items: center; gap: 8px; flex-wrap: wrap; margin-bottom: 8px; color: var(--text-3); font-size: 12px; }
+.q-tools .spacer { flex: 1; }
+.sql { margin: 0; padding: 12px 14px; max-height: 380px; overflow: auto; border: 1px solid var(--border); border-radius: var(--radius-sm); background: var(--surface); font: 12px/1.6 var(--mono); white-space: pre-wrap; word-break: break-word; tab-size: 2; }
+.sql .kw { color: var(--syn-kw); font-weight: 600; } .sql .str { color: var(--syn-str); } .sql .num { color: var(--syn-num); font: inherit; }
+.sql .id { color: var(--syn-id); } .sql .fn { color: var(--syn-fn); } .sql .com { color: var(--syn-com); font-style: italic; }
+.params { margin-top: 8px; font: 12px var(--mono); color: var(--text-2); word-break: break-all; }
+.error-box { margin-top: 8px; padding: 8px 10px; border-radius: var(--radius-sm); background: var(--err-weak); color: var(--err); font: 12px var(--mono); }
+
+.toast { position: fixed; left: 50%; bottom: 20px; transform: translate(-50%, 12px); padding: 8px 14px; border-radius: 999px; background: var(--text); color: var(--bg); font-weight: 600; font-size: 12.5px; box-shadow: var(--shadow); opacity: 0; pointer-events: none; transition: opacity .18s, transform .18s; }
+.toast.show { opacity: 1; transform: translate(-50%, 0); }
+.footer { display: flex; align-items: center; gap: 14px; height: 28px; padding: 0 16px; border-top: 1px solid var(--border); background: var(--surface); color: var(--text-3); font-size: 11.5px; flex: none; overflow: hidden; white-space: nowrap; }
+.footer span { display: inline-flex; align-items: center; gap: 5px; }
+
+/* Narrow (the docked panel can be ~400px wide): one pane at a time */
+.narrow .topbar { gap: 8px; padding: 0 10px; }
+.narrow .brand span.name, .narrow .footer, .narrow .live span, .narrow .btn .label { display: none; }
+.narrow .input { width: 150px; }
+.narrow .layout { display: block; }
+.narrow .list, .narrow .detail { height: 100%; border: 0; }
+.narrow[data-view="detail"] .list { display: none; } .narrow[data-view="list"] .detail { display: none; }
+.narrow .back { display: inline-flex; }
+.narrow .detail-inner { padding: 14px 12px 28px; }
+.narrow .kpis { grid-template-columns: repeat(2, 1fr); }
+.narrow .q-head { grid-template-columns: 1fr; } .narrow .wf, .narrow .axis { display: none; }
+
+@media (prefers-reduced-motion: reduce) { * { transition: none !important; animation: none !important; } }
+`;

package/docs/PUBLISH-AND-INSTALL.md

@@ -0,0 +1,267 @@
+# Đư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).

package/package.json

@@ -1,6 +1,82 @@
 {
   "name": "sql-dev-inspector",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "type": "module",
+  "version": "1.0.0",
+  "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",
+  "homepage": "https://github.com/githubthinnd/sql-dev-inspector#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/githubthinnd/sql-dev-inspector.git"
+  },
+  "bugs": {
+    "url": "https://github.com/githubthinnd/sql-dev-inspector/issues"
+  },
+  "keywords": [
+    "mysql",
+    "mysql2",
+    "sql",
+    "inspector",
+    "debug",
+    "devtools",
+    "drizzle",
+    "nuxt",
+    "nitro",
+    "express",
+    "n+1",
+    "transaction"
+  ],
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./nuxt": {
+      "types": "./dist/nuxt.d.ts",
+      "import": "./dist/nuxt.js"
+    },
+    "./nitro": {
+      "types": "./dist/nitro-plugin.d.ts",
+      "import": "./dist/nitro-plugin.js"
+    },
+    "./client": {
+      "types": "./dist/client/widget.d.ts",
+      "import": "./dist/client/widget.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "CHANGELOG.md",
+    "LICENSE",
+    "README.VI.md",
+    "README.md",
+    "dist",
+    "docs"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepare": "tsc -p tsconfig.build.json",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "npm run clean && npm run build && npm test"
+  },
+  "peerDependencies": {
+    "mysql2": ">=3.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "drizzle-orm": "^0.45.4",
+    "happy-dom": "^20.8.4",
+    "mysql2": "^3.20.0",
+    "typescript": "^5.9.0",
+    "vitest": "^4.1.10"
+  }
+}