@youtyan/code-viewer 0.1.52 → 0.1.53

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@youtyan/code-viewer",
-  "version": "0.1.52",
+  "version": "0.1.53",
   "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
+```