@youtyan/code-viewer 0.5.4 → 0.6.0

package/package.json

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

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

@@ -1,13 +1,14 @@
 ---
 name: code-viewer-query
-description: Use when investigating database contents, checking schema, running SQL queries, or answering questions about data in SQLite/MySQL/PostgreSQL databases visible to code-viewer. Triggers on "query", "SQL", "database", "テーブル", "データベース", "クエリ", "スキーマ", "DB".
+description: Use when investigating database contents, checking schema, running SQL queries, locating a value across many tables, or answering questions about data in SQLite/MySQL/PostgreSQL databases visible to code-viewer. Triggers on "query", "SQL", "database", "search", "find value", "locate column", "テーブル", "データベース", "クエリ", "スキーマ", "DB", "全文検索", "横断検索", "どのテーブルに".
 ---
 
 # code-viewer query
 
-Execute read-only SQL queries against databases discovered by code-viewer.
-Results are saved to query history and appear in the browser's Database
-view, so the human can review what you queried.
+Execute read-only SQL queries — and run global table-wide searches —
+against databases discovered by code-viewer. Query results are saved to
+query history; search results are returned by the CLI and mirror the
+browser's Database > Search tab, so the human can review the same workflow.
 
 ## When to use
 
@@ -15,6 +16,15 @@ view, so the human can review what you queried.
 - Checking schema, row counts, sample data
 - Investigating data quality or anomalies
 - Exploring table relationships
+- Locating where a specific value (an email, an id, a free-text fragment)
+  appears when you do not yet know the table or column — use the global
+  search workflow below.
+
+## When NOT to use this skill
+
+- Capturing a database snapshot or diffing two snapshots before/after an
+  operation → use the `code-viewer-snapshot` skill instead. That skill owns
+  `snapshot create / list / note / delete` and `diff tables / diff rows`.
 
 ## Requirements
 
@@ -24,31 +34,166 @@ view, so the human can review what you queried.
 - If `code-viewer` is not on PATH, prefix every command with
   `npx -y @youtyan/code-viewer`.
 
-## Workflow
+## Workflow: Run a query
+
+1. Discover the datastore ids the running server has detected. This is the
+   AI-friendly equivalent of opening the browser's Database tab and reading
+   the sidebar — it lists every SQLite file plus PostgreSQL / MySQL / Redis
+   / Elasticsearch / S3 service that any nearby `docker-compose` exposes.
+   Use the printed `id` as `--db` on every other command. Credentials and
+   internal config are stripped server-side.
+
+   ```sh
+   code-viewer query sources --json
+   ```
+
+   Default (no `--json`) output is one source per line as
+   `<id>\t<kind>\t<name>`, with any `truncated` or `dockerError` notice
+   appended as `# ...` comment lines so the AI can copy ids without
+   stripping JSON.
+
+   To skip the per-SQL-source "what command should I run next?" step, use
+   `--commands`. For SQLite / PostgreSQL / MySQL sources it prints a small
+   block of shell-pasteable next-step commands (`schema --with-columns
+   --json`, an `exec` example with `SELECT 1 --no-save`, plus `schemas` for
+   PostgreSQL), followed by paste-safe `list --db <id> --json` and
+   `snapshot list --db <id> --json` so you can step into the existing query
+   history and snapshot store without rebuilding those commands. For Redis
+   sources it prints `redis databases / redis keys` lines, for Elasticsearch
+   sources it prints `elasticsearch indices / elasticsearch docs` lines,
+   and for S3 sources it prints `s3 buckets / s3 objects` lines with
+   `--bucket <bucket-name>` as a placeholder so you can step into a bucket
+   discovered via `buckets`. Every emitted SQL command line pins
+   `--server '<url>'` to the same server URL this invocation resolved, so
+   pasting them into a different shell never silently falls back to
+   auto-discovery. Every `--db` value and the server URL are wrapped in
+   POSIX single-quotes so paths or URLs with spaces or `'` paste safely.
+   Notice/comment metadata is collapsed to one line so copied command blocks
+   stay intact.
+   `--json` and `--commands` are mutually exclusive.
+
+   ```sh
+   code-viewer query sources --commands
+   ```
+
+2. Inspect tables, columns, and DDL without writing dialect-specific SQL.
+   These commands wrap the same schema endpoints as the browser, so use them
+   before guessing table names or engine-specific catalog queries.
+
+   ```sh
+   code-viewer query schemas --db docker:pg-svc --json
+   code-viewer query schema --db app.db --json
+   code-viewer query schema --db docker:pg-svc --schema analytics --with-columns --json
+   code-viewer query columns --db app.db --table users --json
+   code-viewer query ddl --db app.db --table users
+   ```
+
+   Default output is tab-separated and human-readable. Pass `--json` when the
+   next agent step should parse the full endpoint response. `query schema
+   --json` adds paste-safe `columnsCommand` and `ddlCommand` fields to every
+   `tables[]` element — each pins `--server '<url>'` and single-quotes the
+   `--db` / `--schema` / `--table` arguments — so you can step into a single
+   table without rebuilding the call. Default (non-JSON) mode prints only
+   `<table>\t<type>\t<rowCount>` lines, unchanged.
+
+3. To inspect saved query history (separate from source discovery), run:
+
+   ```sh
+   code-viewer query list --json
+   ```
 
-1. List available databases:
+   `list --json` enriches each `entries[]` element with a paste-safe
+   `replayCommand` field — `code-viewer query --server '<url>' exec --db
+   '<dbId>' [--schema '<schema>'] --sql '<sql>' [--title '<title>']
+   --no-save` — so you can re-run any past query without rebuilding the
+   call. `server URL / dbId / schema / sql / title` are POSIX single-quoted;
+   `--title` is included only when the entry has one. `body` and
+   `--max-rows` are intentionally omitted (re-author `body` per replay,
+   and override `--max-rows` based on the entry's `truncated` flag).
+   `--no-save` is fixed so replay does not re-pollute history; drop it
+   manually if you want the replay saved. Default (non-JSON) mode prints
+   only the existing summary lines.
+
+   For PostgreSQL multi-schema query history, pass `--schema <name>` with
+   `--db` so list/clear stays scoped to that schema:
 
    ```sh
-   code-viewer query list
+   code-viewer query list --db docker:pg-svc --schema analytics --json
+   code-viewer query clear --db docker:pg-svc --schema analytics
    ```
 
-2. Execute a query:
+4. Execute a query against an id picked from step 1:
 
    ```sh
    code-viewer query exec --db data.db --sql "SELECT * FROM users LIMIT 10" \
        --title "Sample user data" --body "Checking what user records look like."
+   code-viewer query exec --db docker:pg-svc --schema analytics \
+       --sql "SELECT * FROM events LIMIT 10"
    ```
 
-3. The human sees results in the browser's Database > Query History panel.
+   `exec` prints pretty JSON with `dbId`, `columns`, `columnTypes`, `rows`,
+   `rowCount`, `truncated`, `elapsedMs`, and optional `schema` /
+   `executedSql`. Check `truncated` before treating the result as complete.
+
+5. The human sees results in the browser's Database > Query History panel.
+
+## Workflow: Find a value across all tables (global search)
+
+Use this when you have a value (an email, a foreign key, a free-text
+fragment) and do not yet know which table or column holds it. The CLI
+mirrors the browser's Database > Search tab and blocks until the scan
+finishes or `--timeout` expires.
+
+```sh
+code-viewer query search --db app.db --term "needle@example.com" --json
+```
+
+Narrow the scan when you already know the tables to look at, and bound the
+hit set with `--max-hits` (per table):
+
+```sh
+code-viewer query search --db app.db --term "needle@example.com" \
+    --tables users,orders --max-hits 20 --json
+```
+
+By default only text-like columns (TEXT/VARCHAR/CLOB/JSON/UUID/...) are
+scanned. Add `--include-non-text` to also scan non-BLOB columns such as
+numeric ids. BLOB/BYTEA columns are always skipped. Leave it off unless
+the value might live outside text-like columns — the default is faster and
+avoids noisy hits.
+
+Each hit names the `table`, `column`, a `valuePreview`, and (for SQL stores
+with a primary key) a JSON-serialized `rowKeyJson` you can feed into a
+follow-up `query exec` with a matching `WHERE` clause.
+
+The default output prints hit lines plus a summary; pass `--json` to get
+the full status payload (hits + scan counts) for programmatic use. An
+empty result is a clean exit 0 — `no hits (scanned N tables)` on stdout.
+
+Tune `--timeout <sec>` (default 60) when scanning a large database.
+On timeout the running job is cancelled and the CLI exits 1 with a
+"search timed out after Ns" message.
+
+PostgreSQL: pass `--schema <name>` to pin the search to one schema; without
+it the server uses `public` (or the first available schema).
 
 ## Guidelines
 
-- Always use LIMIT. The server caps rows but be explicit.
-- Write --title for the human, not for yourself.
-- Use --body to explain why the query matters.
+- Always use LIMIT in `--sql`. The server caps rows but be explicit.
+- Before writing schema-discovery SQL, prefer `query schema`, `query columns`,
+  or `query ddl`; they work across SQLite, PostgreSQL, and MySQL through the
+  server's existing introspection endpoints.
+- When using PostgreSQL schemas, pass the same `--schema` to `query exec` that
+  you used for introspection.
+- Write `--title` for the human, not for yourself.
+- Use `--body` to explain why the query matters.
 - Do not query broad PII or secrets unless explicitly asked.
-- Use --no-save for exploratory queries that should not remain in history.
-- Prefer specific columns over SELECT *.
+- Use `--no-save` for exploratory queries that should not remain in history.
+- Prefer specific columns over `SELECT *`.
+- For `search`, prefer `--tables` when you already know which tables to scan,
+  and `--max-hits` to keep large hit sets bounded.
+- For `search`, leave `--include-non-text` off unless the value can live in
+  a non-text column such as a numeric id. BLOB/BYTEA are always skipped.
 
 ## Full reference
 

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

@@ -32,12 +32,24 @@ operation that should modify the database in a predictable way.
 Specify which database and tables to capture. Always use `--tables` to
 avoid scanning unnecessary tables.
 
+Add `--wait --json` so the CLI blocks until the snapshot finishes and
+returns the final metadata as JSON. This lets an AI agent grab the
+snapshot id from the `id` field without a separate
+`snapshot list` poll. Default `--timeout` is 120 seconds; on timeout the
+running snapshot is cancelled and the CLI exits 1.
+
 ```sh
 code-viewer query snapshot create --db app.db \
     --tables users,orders \
-    --note "Before running user registration test"
+    --note "Before running user registration test" \
+    --wait --json
 ```
 
+The ack-only form (no `--wait`) returns immediately with
+`{ ok, message, snapshotId, pollCommand }` and the scan runs in the
+background; use `snapshot list` (or paste `pollCommand` verbatim) to
+confirm completion before diffing.
+
 ### 2. Perform the operation
 
 The human (or a test runner, migration script, etc.) modifies the database.
@@ -47,15 +59,30 @@ The human (or a test runner, migration script, etc.) modifies the database.
 ```sh
 code-viewer query snapshot create --db app.db \
     --tables users,orders \
-    --note "After running user registration test"
+    --note "After running user registration test" \
+    --wait --json
 ```
 
 ### 4. Get snapshot IDs
 
+`--wait --json` already prints the `id` for each created snapshot. If you
+took the snapshots without `--wait`, list them to find the IDs:
+
 ```sh
 code-viewer query snapshot list --db app.db
 ```
 
+`snapshot create` (no-wait) also prints a paste-safe poll command that
+pins `--server '<url>'` and single-quotes db/schema, so copying it never
+silently falls back to auto-discovery. The same string is available as
+the `pollCommand` field in `--json` ack output.
+
+`snapshot list --json` enriches each `snapshots[]` element with paste-safe
+`deleteCommand` and `noteCommand` fields. Each pins `--server '<url>'` and
+single-quotes the snapshot id; `noteCommand` also quotes the current note
+as-is so you can paste the line and edit the value to update. Use these
+when you want to drop or re-label snapshots without rebuilding the call.
+
 ### 5. View the diff
 
 Compare table-level summary (which tables changed and how many rows):
@@ -64,6 +91,12 @@ Compare table-level summary (which tables changed and how many rows):
 code-viewer query diff tables --before snap-abc123 --after snap-def456
 ```
 
+Each table summary line is followed by a paste-safe
+`# diff rows: code-viewer query --server '<url>' diff rows --before '<id>'
+--after '<id>' --table '<table>' --json` comment line, so you can copy the
+exact next command per table without rebuilding it. With `--json`, the same
+literal is exposed as a `diffRowsCommand` field on each `tables[]` element.
+
 Drill into row-level changes for a specific table:
 
 ```sh
@@ -74,6 +107,27 @@ code-viewer query diff rows --before snap-abc123 --after snap-def456 \
 The human can also view all snapshots and diffs in the browser's
 Database > Snapshot tab.
 
+## PostgreSQL (multi-schema)
+
+For PostgreSQL with multiple schemas, pass `--schema <name>` to BOTH
+`snapshot create` and the matching `snapshot list`. Snapshot create binds
+the snapshot to that schema, the polling lookup performed during `--wait`
+re-uses it, and `snapshot list --schema` filters to the same scope so the
+before/after pair stays consistent. Without `--schema`, snapshot create
+infers the schema (`public` or the first available) and `snapshot list`
+returns every snapshot for the database id.
+
+```sh
+code-viewer query snapshot create --db docker:pg-svc --schema analytics \
+    --tables events \
+    --note "Before backfill" \
+    --wait --json
+
+code-viewer query snapshot list --db docker:pg-svc --schema analytics --json
+```
+
+SQLite / MySQL / Redis / S3 do not need `--schema` (single namespace).
+
 ## Managing snapshots
 
 ```sh
@@ -94,6 +148,9 @@ code-viewer query snapshot delete --id snap-abc123
   database size.
 - The diff is computed on demand, not stored — you can diff any two
   snapshots of the same database.
+- Prefer `--wait --json` when you want to chain the next command on the
+  resulting snapshot id. Tune `--timeout <sec>` (default 120) for very
+  large tables.
 
 ## Full reference