@youtyan/code-viewer 0.1.52 → 0.1.54

package/README.md

@@ -14,6 +14,7 @@ Requires Node.js 20 or newer when installed from npm. Development uses
 - Preview Markdown with a table of contents, task lists, Mermaid diagrams, and Shiki code highlighting.
 - Preview browser-safe media and show metadata for binary files that cannot be rendered.
 - Switch the viewer UI between English and Japanese from Viewer Settings.
+- Browse SQLite, PostgreSQL, and MySQL databases with a built-in database viewer.
 - Read the built-in Help page for repository browsing, diffs, annotations, agent skills, and shortcuts.
 - Open repository folders in the OS file manager from localhost-only actions.
 - Upload files into worktree folders when upload is explicitly enabled.
@@ -111,6 +112,75 @@ Use `scope.omitDirs` for directories that should stay visible as skipped, and
 `scope.excludeNames` for file or directory names that should be hidden entirely.
 `.DS_Store` is hidden by default.
 
+## Database Viewer
+
+code-viewer auto-discovers databases in your repository and provides a
+browser-based viewer for exploring their contents.
+
+**SQLite** files (`.db`, `.sqlite`, `.sqlite3`, `.s3db`) are detected
+automatically by scanning the repository tree. **PostgreSQL** and **MySQL**
+databases are detected from `docker-compose.yml` and connected through
+Docker.
+
+### Browser UI
+
+Open the database icon in the sidebar to access:
+
+- **Table browser** — paginated data grid with column sorting, text
+  filtering, and CSV/JSON export.
+- **Query editor** — execute read-only SQL with syntax highlighting.
+  Results and history are saved and shared across tabs.
+- **ER diagram** — auto-generated entity-relationship diagram showing
+  foreign key relationships between tables.
+- **Global search** — full-text search across all tables and text columns.
+- **Snapshots & diffs** — take point-in-time snapshots of selected tables
+  and compare any two snapshots to see inserted, updated, and deleted rows
+  with full before/after values.
+
+### CLI
+
+AI agents can query databases and manage snapshots from the command line:
+
+```sh
+code-viewer query exec --db data.db --sql "SELECT * FROM users LIMIT 10" \
+    --title "Sample users" --body "Checking user data shape."
+
+code-viewer query search --db app.db --term "john@example.com"
+
+code-viewer query snapshot create --db app.db --tables users,orders \
+    --note "Before migration"
+```
+
+`code-viewer query --help` shows all commands. `code-viewer query agent-help`
+prints a detailed guide for AI agents covering queries, search, snapshots,
+and diffs.
+
+### Snapshot & Diff Workflow
+
+Snapshots capture the state of selected tables at a point in time. Diff any
+two snapshots to verify that a migration, test, or operation changed exactly
+what you expected:
+
+```sh
+# 1. Snapshot before the operation
+code-viewer query snapshot create --db app.db --tables users --note "Before"
+
+# 2. (run the migration / test / script)
+
+# 3. Snapshot after
+code-viewer query snapshot create --db app.db --tables users --note "After"
+
+# 4. List snapshots to get IDs
+code-viewer query snapshot list --db app.db
+
+# 5. Compare
+code-viewer query diff tables --before snap-abc123 --after snap-def456
+code-viewer query diff rows --before snap-abc123 --after snap-def456 --table users
+```
+
+Diffs are computed on demand — no pre-computation needed. The browser's
+Snapshot tab provides a visual interface for the same workflow.
+
 ## AI Code Annotations
 
 AI coding agents (Claude Code, Codex, and similar CLI agents) can walk you
@@ -163,9 +233,9 @@ write concise Markdown explanations, and how to install the bundled agent skill.
 
 ### Agent Skill
 
-The package bundles an [Agent Skill](https://agentskills.io) (the SKILL.md
-open standard) that teaches AI coding agents when and how to use
-`annotate`. Install it into the current project:
+The package bundles [Agent Skills](https://agentskills.io) (the SKILL.md
+open standard) that teach AI coding agents when and how to use
+`annotate`, `query`, and `snapshot`. Install them into the current project:
 
 ```sh
 npx -y @youtyan/code-viewer skill install                       # Claude Code (.claude/skills/)

package/dist/code-viewer.js

@@ -3337,6 +3337,15 @@ function openDockerAdapter(serviceName, kind, env, cwd, overrideDatabase) {
 var init_docker = () => {};
 
 // web-src/server/database/adapters/sqlite.ts
+function safePrepare(db, sql) {
+  const stmt = db.prepare(sql);
+  if (typeof stmt.safeIntegers === "function") {
+    try {
+      stmt.safeIntegers(true);
+    } catch {}
+  }
+  return stmt;
+}
 async function getSqliteClass() {
   if (cachedDbClass)
     return cachedDbClass;
@@ -3450,7 +3459,7 @@ function createSqliteAdapter(db) {
     getTablePage(table, options) {
       const order = buildOrderClause2(options.orderBy);
       const sql = `SELECT * FROM ${sanitizeIdentifier2(table)}${order} LIMIT ? OFFSET ?`;
-      const rows = db.prepare(sql).all(options.limit, options.offset);
+      const rows = safePrepare(db, sql).all(options.limit, options.offset);
       const cols = queryColumns(db, table);
       if (rows.length === 0) {
         return {
@@ -3484,11 +3493,11 @@ function createSqliteAdapter(db) {
       const wrappedSql = `SELECT * FROM (${limited}) LIMIT ${maxRows + 1}`;
       let rows;
       try {
-        rows = db.prepare(wrappedSql).all(...params || []);
+        rows = safePrepare(db, wrappedSql).all(...params || []);
       } catch (wrapErr) {
         const fallbackSql = `${limited} LIMIT ${maxRows + 1}`;
         try {
-          rows = db.prepare(fallbackSql).all(...params || []);
+          rows = safePrepare(db, fallbackSql).all(...params || []);
         } catch {
           throw wrapErr;
         }
@@ -3839,6 +3848,37 @@ var init_discovery = __esm(() => {
   ];
 });
 
+// web-src/server/database/serialize.ts
+function serializeDbValue(value) {
+  if (value === null || value === undefined)
+    return null;
+  if (typeof value === "bigint") {
+    return value >= MIN_SAFE && value <= MAX_SAFE ? Number(value) : value.toString();
+  }
+  if (value instanceof Uint8Array) {
+    return `<blob ${value.byteLength} bytes>`;
+  }
+  if (typeof value === "object") {
+    try {
+      return JSON.stringify(value);
+    } catch {
+      return String(value);
+    }
+  }
+  return value;
+}
+function serializeDbRow(row) {
+  return row.map(serializeDbValue);
+}
+function serializeDbRows(rows) {
+  return rows.map(serializeDbRow);
+}
+var MIN_SAFE, MAX_SAFE;
+var init_serialize = __esm(() => {
+  MIN_SAFE = BigInt(Number.MIN_SAFE_INTEGER);
+  MAX_SAFE = BigInt(Number.MAX_SAFE_INTEGER);
+});
+
 // web-src/server/database/global-search.ts
 function sanitizeIdentifier3(name, kind) {
   if (kind === "mysql")
@@ -3880,7 +3920,7 @@ function searchTable(adapter, table, columns, term, maxHits, includeNonText, pkC
       const result = kind === "sqlite" ? adapter.executeReadonlyQuery(sql, [`%${escapedTerm}%`], remaining) : adapter.executeReadonlyQuery(sql, undefined, remaining);
       for (const row of result.rows) {
         const colIdx = result.columns.indexOf(col.name);
-        const valueRaw = colIdx >= 0 ? row[colIdx] : null;
+        const valueRaw = colIdx >= 0 ? serializeDbValue(row[colIdx]) : null;
         const valueStr = valueRaw == null ? "" : String(valueRaw);
         const preview = valueStr.length > 200 ? `${valueStr.slice(0, 200)}...` : valueStr;
         let rowKeyJson;
@@ -3889,7 +3929,7 @@ function searchTable(adapter, table, columns, term, maxHits, includeNonText, pkC
           for (const pk of pkColumns) {
             const pkIdx = result.columns.indexOf(pk);
             if (pkIdx >= 0)
-              keyObj[pk] = row[pkIdx];
+              keyObj[pk] = serializeDbValue(row[pkIdx]);
           }
           rowKeyJson = JSON.stringify(keyObj);
         }
@@ -3898,7 +3938,7 @@ function searchTable(adapter, table, columns, term, maxHits, includeNonText, pkC
           column: col.name,
           rowKeyJson,
           valuePreview: preview,
-          rowPreview: row
+          rowPreview: serializeDbRow(row)
         });
       }
     } catch {}
@@ -3909,6 +3949,9 @@ function getPrimaryKeyColumns(adapter, table) {
   const columns = adapter.getColumns(table);
   return columns.filter((c) => c.primaryKey).map((c) => c.name);
 }
+var init_global_search = __esm(() => {
+  init_serialize();
+});
 
 // web-src/server/database/query-history.ts
 import {
@@ -4283,6 +4326,8 @@ import { createHash as createHash3 } from "node:crypto";
 function normalizeValue(v) {
   if (v === null)
     return "\\N";
+  if (typeof v === "bigint")
+    return v.toString();
   if (v instanceof Uint8Array) {
     return `\\x${Buffer.from(v).toString("hex")}`;
   }
@@ -4291,7 +4336,7 @@ function normalizeValue(v) {
 function rowToPayloadJson(columns, row) {
   const obj = {};
   for (let i = 0;i < columns.length; i++) {
-    obj[columns[i]] = row[i] instanceof Uint8Array ? `<blob ${row[i].byteLength} bytes>` : row[i];
+    obj[columns[i]] = serializeDbValue(row[i]);
   }
   return JSON.stringify(obj);
 }
@@ -4307,7 +4352,7 @@ function buildRowKeyJson(pkColumns, allColumns, row, rowIndex) {
   for (const pk of pkColumns) {
     const idx = allColumns.indexOf(pk);
     if (idx >= 0)
-      keyObj[pk] = row[idx];
+      keyObj[pk] = serializeDbValue(row[idx]);
   }
   return JSON.stringify(keyObj);
 }
@@ -4353,6 +4398,7 @@ async function runSnapshot(cwd, adapter, dbId, tables, note, onProgress) {
 }
 var BATCH_SIZE = 500;
 var init_snapshot_runner = __esm(() => {
+  init_serialize();
   init_snapshot_store();
 });
 
@@ -4606,7 +4652,7 @@ async function handleTable(cwd, url) {
           dbId: r.dbId,
           table,
           columns,
-          rows: dataResult.rows,
+          rows: serializeDbRows(dataResult.rows),
           totalRows: totalRows2,
           offset,
           limit,
@@ -4621,7 +4667,7 @@ async function handleTable(cwd, url) {
       dbId: r.dbId,
       table,
       columns,
-      rows: result.rows,
+      rows: serializeDbRows(result.rows),
       totalRows,
       offset,
       limit,
@@ -4656,11 +4702,12 @@ async function handleQuery(cwd, req, sendSse) {
     const adapter = await getAdapter(r, cwd);
     const result = adapter.executeReadonlyQuery(body.sql, undefined, maxRows);
     const elapsed = Date.now() - start;
+    const serializedRows = serializeDbRows(result.rows);
     const response = {
       dbId: body.db,
       columns: result.columns,
       columnTypes: result.columnTypes,
-      rows: result.rows,
+      rows: serializedRows,
       rowCount: result.rowCount,
       truncated: result.rowCount >= maxRows,
       elapsedMs: elapsed
@@ -4673,9 +4720,9 @@ async function handleQuery(cwd, req, sendSse) {
         title: body.title,
         body: body.body,
         columns: result.columns,
-        rowsPreview: result.rows,
+        rowsPreview: serializedRows,
         rowCount: result.rowCount,
-        savedRows: result.rows.length,
+        savedRows: serializedRows.length,
         truncated: result.rowCount >= maxRows,
         elapsedMs: elapsed,
         executedAt: new Date().toISOString(),
@@ -4750,6 +4797,8 @@ async function handleHistoryClear(cwd, req, sendSse) {
 function formatCsvField(value) {
   if (value === null || value === undefined)
     return "";
+  if (typeof value === "bigint")
+    return value.toString();
   if (value instanceof Uint8Array)
     return `<blob ${value.byteLength} bytes>`;
   const str = typeof value === "object" ? JSON.stringify(value) : String(value);
@@ -4789,7 +4838,7 @@ async function handleExport(cwd, url) {
     if (sortCol && !colNameSet.has(sortCol)) {
       return textError(`invalid sort column: ${sortCol}`, 400);
     }
-    let rows;
+    let rawRows;
     if (filters.length > 0) {
       const validFilters = filters.filter((f) => colNameSet.has(f.column));
       if (validFilters.length > 0) {
@@ -4806,14 +4855,14 @@ async function handleExport(cwd, url) {
         const limitOffset = filter.useParams ? "LIMIT ? OFFSET ?" : `LIMIT ${EXPORT_MAX_ROWS} OFFSET 0`;
         const dataSql = `SELECT * FROM ${tbl} WHERE ${filter.where}${order} ${limitOffset}`;
         const result = adapter.executeReadonlyQuery(dataSql, filter.useParams ? [...filter.params, EXPORT_MAX_ROWS, 0] : undefined);
-        rows = result.rows;
+        rawRows = result.rows;
       } else {
         const result = adapter.getTablePage(table, {
           offset: 0,
           limit: EXPORT_MAX_ROWS,
           orderBy
         });
-        rows = result.rows;
+        rawRows = result.rows;
       }
     } else {
       const result = adapter.getTablePage(table, {
@@ -4821,8 +4870,9 @@ async function handleExport(cwd, url) {
         limit: EXPORT_MAX_ROWS,
         orderBy
       });
-      rows = result.rows;
+      rawRows = result.rows;
     }
+    const rows = serializeDbRows(rawRows);
     if (format === "csv") {
       const lines = [colNames.map(formatCsvField).join(",")];
       for (const row of rows) {
@@ -4842,8 +4892,7 @@ async function handleExport(cwd, url) {
     const objects = rows.map((row) => {
       const obj = {};
       for (let i = 0;i < colNames.length; i++) {
-        const val = row[i];
-        obj[colNames[i]] = val instanceof Uint8Array ? `<blob ${val.byteLength} bytes>` : val;
+        obj[colNames[i]] = row[i];
       }
       return obj;
     });
@@ -5232,7 +5281,9 @@ var init_handle = __esm(() => {
   init_sqlite();
   init_connection_pool();
   init_discovery();
+  init_global_search();
   init_query_history();
+  init_serialize();
   init_snapshot_runner();
   init_snapshot_store();
   dockerAdapterCache = new Map;
@@ -7194,6 +7245,14 @@ data: ok
 });
 
 // web-src/server/cli.ts
+var REQUIRED_NODE_MAJOR = 20;
+var nodeMajor = Number.parseInt((process.versions.node || "0").split(".")[0] || "0", 10);
+if (!Number.isFinite(nodeMajor) || nodeMajor < REQUIRED_NODE_MAJOR) {
+  process.stderr.write(`code-viewer requires Node.js >= ${REQUIRED_NODE_MAJOR}.0.0, but found ${process.versions.node}.
+` + `Please upgrade Node.js (e.g. via nvm, volta, or your package manager) and retry.
+`);
+  process.exit(1);
+}
 if (process.argv[2] === "annotate") {
   const { runAnnotateCli: runAnnotateCli2 } = await Promise.resolve().then(() => (init_annotate_cli(), exports_annotate_cli));
   await runAnnotateCli2(process.argv.slice(3));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@youtyan/code-viewer",
-  "version": "0.1.52",
+  "version": "0.1.54",
   "description": "Local browser-based code and git diff viewer",
   "type": "module",
   "bin": {

package/skills/code-viewer-snapshot/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: code-viewer-snapshot
+description: Use when taking database snapshots before/after an operation to verify what changed, diffing two points in time, or confirming a migration/test/feature modified the expected tables and rows. Triggers on "snapshot", "diff", "スナップショット", "差分", "before/after", "DBの変更を確認", "マイグレーション検証", "テスト前後の比較".
+---
+
+# code-viewer snapshot
+
+Take point-in-time snapshots of database tables and diff them to see
+exactly what changed — inserted, updated, and deleted rows with full
+before/after values. Use it to verify migrations, test runs, or any
+operation that should modify the database in a predictable way.
+
+## When to use
+
+- Verifying a migration added/removed the expected rows
+- Confirming a test correctly modifies the database
+- Debugging "what did that operation actually change?"
+- Auditing data changes before and after a deploy or script
+
+## Requirements
+
+- A code-viewer server must already be running for the repository
+  (the human starts it with: `code-viewer`). The CLI never starts one.
+- Run from inside the repository, or pass `--cwd <repo>`.
+- If `code-viewer` is not on PATH, prefix every command with
+  `npx -y @youtyan/code-viewer`.
+
+## Workflow
+
+### 1. Take a "before" snapshot
+
+Specify which database and tables to capture. Always use `--tables` to
+avoid scanning unnecessary tables.
+
+```sh
+code-viewer query snapshot create --db app.db \
+    --tables users,orders \
+    --note "Before running user registration test"
+```
+
+### 2. Perform the operation
+
+The human (or a test runner, migration script, etc.) modifies the database.
+
+### 3. Take an "after" snapshot
+
+```sh
+code-viewer query snapshot create --db app.db \
+    --tables users,orders \
+    --note "After running user registration test"
+```
+
+### 4. Get snapshot IDs
+
+```sh
+code-viewer query snapshot list --db app.db
+```
+
+### 5. View the diff
+
+Compare table-level summary (which tables changed and how many rows):
+
+```sh
+code-viewer query diff tables --before snap-abc123 --after snap-def456
+```
+
+Drill into row-level changes for a specific table:
+
+```sh
+code-viewer query diff rows --before snap-abc123 --after snap-def456 \
+    --table users
+```
+
+The human can also view all snapshots and diffs in the browser's
+Database > Snapshot tab.
+
+## Managing snapshots
+
+```sh
+# Update a snapshot's note
+code-viewer query snapshot note --id snap-abc123 --note "Updated note"
+
+# Delete a snapshot
+code-viewer query snapshot delete --id snap-abc123
+```
+
+## Guidelines
+
+- Always specify `--tables` — snapshotting every table wastes time.
+- Write meaningful `--note` values — the human uses them to tell
+  snapshots apart.
+- Take both snapshots against the same `--db` and `--tables`.
+- For large tables, the snapshot captures all rows — be mindful of
+  database size.
+- The diff is computed on demand, not stored — you can diff any two
+  snapshots of the same database.
+
+## Full reference
+
+```sh
+code-viewer query agent-help
+```

package/web/app.js

@@ -9415,6 +9415,7 @@ ${frontmatter.yaml}
   var PAGE_SIZE = 200;
   var FILTER_DEBOUNCE_MS = 300;
   var DEFAULT_COL_WIDTH = 180;
+  var CELL_PREVIEW_MAX_CHARS = 4000;
   function createTableGrid(callbacks) {
     const el = document.createElement("div");
     el.className = "db-grid";
@@ -9557,11 +9558,17 @@ ${frontmatter.yaml}
       }
       return filters;
     }
+    function resetSelectionAndDetail() {
+      selectedRowIndex = -1;
+      detailPanel.hidden = true;
+      detailPanel.innerHTML = "";
+    }
     function invalidateData() {
       pageCache = new Map;
       pendingPages = new Set;
       loadGeneration++;
       viewport.scrollTop = 0;
+      resetSelectionAndDetail();
       ensurePage(0);
     }
     function clear() {
@@ -9600,6 +9607,22 @@ ${frontmatter.yaml}
       const title = document.createElement("span");
       title.className = "db-grid-detail-title";
       title.textContent = `${colName} (${colType})`;
+      const copyBtn = document.createElement("button");
+      copyBtn.type = "button";
+      copyBtn.className = "db-btn db-grid-detail-copy";
+      copyBtn.textContent = "Copy";
+      const copyText = formatValueForCopy(value);
+      copyBtn.addEventListener("click", () => {
+        navigator.clipboard.writeText(copyText).then(() => {
+          const original = copyBtn.textContent;
+          copyBtn.textContent = "Copied";
+          setTimeout(() => {
+            copyBtn.textContent = original;
+          }, 800);
+        }, () => {
+          copyBtn.textContent = "Copy failed";
+        });
+      });
       const closeBtn = document.createElement("button");
       closeBtn.type = "button";
       closeBtn.className = "db-btn db-btn-icon db-grid-detail-close";
@@ -9607,7 +9630,7 @@ ${frontmatter.yaml}
       closeBtn.addEventListener("click", () => {
         detailPanel.hidden = true;
       });
-      header.append(title, closeBtn);
+      header.append(title, copyBtn, closeBtn);
       const content = document.createElement("div");
       content.className = "db-grid-detail-content";
       if (value === null) {
@@ -9769,6 +9792,7 @@ ${frontmatter.yaml}
       }
       pageCache = new Map;
       pendingPages = new Set;
+      resetSelectionAndDetail();
       renderHeader();
       renderViewport();
     }
@@ -9852,11 +9876,6 @@ ${frontmatter.yaml}
                 });
                 row.classList.add("selected");
                 showCellDetail(cellColIndex, cellValue);
-                const text2 = formatValueForCopy(cellValue);
-                navigator.clipboard.writeText(text2).then(() => {
-                  cell.classList.add("copied");
-                  setTimeout(() => cell.classList.remove("copied"), 600);
-                }, () => {});
               });
               row.appendChild(cell);
             }
@@ -9994,6 +10013,10 @@ ${frontmatter.yaml}
     const s2 = String(value);
     if (s2 === "")
       return "<empty>";
+    if (s2.length > CELL_PREVIEW_MAX_CHARS) {
+      const truncated = s2.slice(0, CELL_PREVIEW_MAX_CHARS);
+      return `${truncated} … (+${s2.length - CELL_PREVIEW_MAX_CHARS} chars)`;
+    }
     return s2;
   }
   function formatValueForCopy(value) {

package/web/style.css

@@ -6116,6 +6116,16 @@ html[data-theme="dark"] .db-query-highlight span[style] {
   color: var(--danger);
   background: none;
 }
+.db-grid-detail-copy {
+  font-size: 11px;
+  padding: 2px 8px;
+  margin-left: auto;
+  margin-right: 8px;
+  color: var(--fg-muted);
+}
+.db-grid-detail-copy:hover {
+  color: var(--fg);
+}
 
 .db-grid-detail-content {
   padding: 8px 12px;