@carllee1983/dbcli 1.48.0 → 1.49.0

package/dist/cli.mjs

@@ -52,7 +52,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@carllee1983/dbcli",
-    version: "1.48.0",
+    version: "1.49.0",
     description: "Database CLI for AI agents",
     type: "module",
     publishConfig: {
@@ -133,8 +133,9 @@ var init_package = __esm(() => {
       typecheck: "tsc --noEmit --pretty false",
       "test:perf": "bun test ./tests/perf/*.bench.ts",
       lint: "eslint src tests scripts --ext .ts --max-warnings=0",
-      "lint:fix": "eslint src tests scripts --ext .ts --fix --max-warnings=0",
-      format: 'prettier --write "src/**/*.ts" "tests/**/*.ts"'
+      "format:check": "prettier --check .",
+      format: "prettier --write .",
+      "lint:fix": "eslint src tests scripts --ext .ts --fix --max-warnings=0"
     },
     dependencies: {
       "cli-table3": "^0.6.5",
@@ -30311,16 +30312,36 @@ function projectRows(rows, selection) {
   const columnNames = collectColumnNames(projectedRows);
   return { rows: normalizeRows(projectedRows, columnNames), columnNames };
 }
-function hasFieldPath(row, path5) {
-  return readPath(row, path5.split(".")).found;
+function hasFieldPath(row, segments) {
+  return readPath(row, segments).found;
 }
 function omitFieldPaths(rows, paths) {
-  return rows.map((row) => {
-    let projected = cloneRecord(row);
-    for (const path5 of paths)
-      projected = omitPath(projected, path5.split("."));
+  const topLevel = new Set(paths);
+  const dotted = paths.filter((path5) => path5.includes(".")).map((path5) => ({ head: path5.slice(0, path5.indexOf(".")), segments: path5.split(".") }));
+  const maskRecord = (row) => {
+    let projected = cloneRecord(row, topLevel);
+    for (const { head, segments } of dotted) {
+      const value = row[head];
+      if (value !== null && typeof value === "object")
+        projected = omitPath(projected, segments);
+    }
     return projected;
+  };
+  return rows.map((row) => {
+    if (row === null || typeof row !== "object")
+      return {};
+    if (Array.isArray(row))
+      return maskArrayRow(row, maskRecord);
+    return maskRecord(row);
+  });
+}
+function maskArrayRow(row, maskRecord) {
+  const out = {};
+  row.forEach((item, index) => {
+    const masked = Array.isArray(item) ? maskArrayRow(item, maskRecord) : item !== null && typeof item === "object" ? maskRecord(item) : item;
+    defineData(out, String(index), masked);
   });
+  return out;
 }
 function toMongoProjection(selection) {
   const projection = {};
@@ -30384,10 +30405,10 @@ function omitPath(value, segments) {
   }
   return out;
 }
-function cloneRecord(value, omittedKey) {
+function cloneRecord(value, omittedKeys) {
   const out = {};
   for (const [key, child] of Object.entries(value)) {
-    if (key !== omittedKey)
+    if (!omittedKeys.has(key))
       defineData(out, key, child);
   }
   return out;
@@ -30526,6 +30547,16 @@ var MAX_DECODE_PASSES = 4;
 var init_es_index_target = () => {};
 
 // src/core/blacklist-validator.ts
+function flattenArrayRow(row) {
+  const records = [];
+  for (const item of row) {
+    if (Array.isArray(item))
+      records.push(...flattenArrayRow(item));
+    else if (item !== null && typeof item === "object")
+      records.push(item);
+  }
+  return records;
+}
 function dedupe2(values) {
   const seen = new Set;
   const result = [];
@@ -30626,7 +30657,56 @@ class BlacklistValidator {
     if (blacklistedColumns.length === 0) {
       return { filteredRows: rows, omittedColumns: [] };
     }
-    const omittedColumns = blacklistedColumns.filter((path5) => columnList.includes(path5) || rows.some((row) => hasFieldPath(row, path5)));
+    const probeNested = blacklistedColumns.some((path5) => path5.includes("."));
+    const presentColumns = new Set(columnList);
+    const nestedHeads = new Set;
+    const collect2 = (record) => {
+      for (const key of Object.getOwnPropertyNames(record)) {
+        presentColumns.add(key);
+        if (!probeNested)
+          continue;
+        const value = record[key];
+        if (value !== null && typeof value === "object")
+          nestedHeads.add(key);
+      }
+    };
+    for (const row of rows) {
+      if (row === null || typeof row !== "object")
+        continue;
+      if (Array.isArray(row)) {
+        for (const item of flattenArrayRow(row))
+          collect2(item);
+        continue;
+      }
+      collect2(row);
+    }
+    const protectedPaths = new Set(blacklistedColumns);
+    const omitted = new Set;
+    for (const path5 of blacklistedColumns) {
+      if (presentColumns.has(path5)) {
+        omitted.add(path5);
+        continue;
+      }
+      const dot = path5.indexOf(".");
+      if (dot < 0)
+        continue;
+      if (!nestedHeads.has(path5.slice(0, dot)))
+        continue;
+      const segments = path5.split(".");
+      if (rows.some((row) => hasFieldPath(row, segments)))
+        omitted.add(path5);
+    }
+    for (const column of presentColumns) {
+      let dot = column.indexOf(".");
+      while (dot >= 0) {
+        if (dot > 0 && protectedPaths.has(column.slice(0, dot))) {
+          omitted.add(column);
+          break;
+        }
+        dot = column.indexOf(".", dot + 1);
+      }
+    }
+    const omittedColumns = Array.from(omitted);
     if (omittedColumns.length === 0) {
       return { filteredRows: rows, omittedColumns: [] };
     }
@@ -106230,6 +106310,10 @@ function fingerprintSql(sql) {
 function shellEscapeDq(s) {
   return s.replace(/\\/g, "\\\\").replace(/\$/g, "\\$").replace(/`/g, "\\`").replace(/"/g, "\\\"");
 }
+function explainSuggestions(sql) {
+  const esc = shellEscapeDq(sql);
+  return [`dbcli explain "${esc}"`, `dbcli guide missing-index-for "${esc}"`];
+}
 function buildByFingerprint(events, slowMs, top) {
   const errorByFp = new Map;
   for (const e of events.filter(isErrored)) {
@@ -106298,11 +106382,7 @@ function buildByFingerprint(events, slowMs, top) {
   stats.sort((a, b) => b.durationMs.total - a.durationMs.total);
   return stats.map((s, i) => {
     if (i < top && s.statement === "SELECT") {
-      const sql = shellEscapeDq(s.exampleSql);
-      return {
-        ...s,
-        suggestedCommands: [`dbcli explain "${sql}"`, `dbcli guide missing-index-for "${sql}"`]
-      };
+      return { ...s, suggestedCommands: explainSuggestions(s.exampleSql) };
     }
     return s;
   });
@@ -106329,13 +106409,27 @@ function buildErrors(events) {
         message: e.error.message,
         count: 0,
         fingerprint: fingerprintSql(e.sql),
-        exampleSql: e.sql
+        exampleSql: e.sql,
+        tables: e.tables
       };
       groups.set(key, g);
     }
     g.count += 1;
   }
-  return [...groups.values()].sort((a, b) => b.count - a.count);
+  return [...groups.values()].sort((a, b) => b.count - a.count).map((g) => {
+    const schemaCmds = g.tables.slice(0, MAX_ERROR_SCHEMA_TABLES).map((t2) => `dbcli schema ${t2}`);
+    const hint = `failed ${g.count}\xD7: verify the involved table/column names against the live schema ` + `before fixing the SQL \u2014 never guess column names`;
+    return {
+      code: g.code,
+      message: g.message,
+      count: g.count,
+      fingerprint: g.fingerprint,
+      exampleSql: g.exampleSql,
+      tables: g.tables,
+      ...schemaCmds.length ? { suggestedCommands: schemaCmds } : {},
+      hints: [hint]
+    };
+  });
 }
 function buildHotTables(events) {
   const map = new Map;
@@ -106364,10 +106458,13 @@ function buildRepetition(events, threshold) {
         fingerprint: fp,
         sessionId: e.sessionId,
         tables: e.tables,
+        statement: e.statement,
         count: 0,
         totalDurationMs: 0,
         minTs: ts,
-        maxTs: ts
+        maxTs: ts,
+        exampleSql: e.sql,
+        exampleDuration: e.durationMs
       };
       groups.set(key, g);
     }
@@ -106377,15 +106474,27 @@ function buildRepetition(events, threshold) {
       g.minTs = ts;
     if (ts > g.maxTs)
       g.maxTs = ts;
+    if (e.durationMs > g.exampleDuration) {
+      g.exampleDuration = e.durationMs;
+      g.exampleSql = e.sql;
+    }
   }
-  return [...groups.values()].filter((g) => g.count >= threshold).map((g) => ({
-    fingerprint: g.fingerprint,
-    sessionId: g.sessionId,
-    count: g.count,
-    spanMs: g.maxTs - g.minTs,
-    totalDurationMs: g.totalDurationMs,
-    tables: g.tables
-  })).sort((a, b) => b.count - a.count);
+  return [...groups.values()].filter((g) => g.count >= threshold).sort((a, b) => b.count - a.count).map((g) => {
+    const spanMs = g.maxTs - g.minTs;
+    const hint = `N+1 suspect: the same query ran ${g.count}\xD7 within one session over ${spanMs}ms \u2014 ` + `collapse into a single query (JOIN / IN (...)) or cache the result`;
+    return {
+      fingerprint: g.fingerprint,
+      sessionId: g.sessionId,
+      count: g.count,
+      spanMs,
+      totalDurationMs: g.totalDurationMs,
+      tables: g.tables,
+      statement: g.statement,
+      exampleSql: g.exampleSql,
+      ...g.statement === "SELECT" ? { suggestedCommands: explainSuggestions(g.exampleSql) } : {},
+      hints: [hint]
+    };
+  });
 }
 function analyzeEvents(events, opts) {
   const timestamps = events.map((e) => e.timestamp).filter(Boolean).sort();
@@ -106439,7 +106548,7 @@ function buildSummary(events, slowMs) {
     }
   };
 }
-var isCompleted = (e) => e.type === "query_completed", isErrored = (e) => e.type === "query_errored";
+var isCompleted = (e) => e.type === "query_completed", isErrored = (e) => e.type === "query_errored", MAX_ERROR_SCHEMA_TABLES = 3;
 var init_analyze = __esm(() => {
   init_sql_metadata();
 });
@@ -106479,12 +106588,29 @@ function renderAnalysisText(report, top) {
   for (const r of report.repetition.slice(0, top)) {
     L2.push(`  ${r.count}x in session ${r.sessionId} (${r.spanMs}ms)  ${r.fingerprint}`);
   }
-  const cmds = [...new Set(report.byFingerprint.flatMap((f) => f.suggestedCommands ?? []))];
+  const cmds = [
+    ...new Set([
+      ...report.byFingerprint.flatMap((f) => f.suggestedCommands ?? []),
+      ...report.errors.flatMap((e) => e.suggestedCommands ?? []),
+      ...report.repetition.flatMap((r) => r.suggestedCommands ?? [])
+    ])
+  ];
   if (cmds.length) {
     L2.push("", "SUGGESTED COMMANDS");
     for (const c2 of cmds)
       L2.push(`  ${c2}`);
   }
+  const hints = [
+    ...new Set([
+      ...report.errors.flatMap((e) => e.hints ?? []),
+      ...report.repetition.flatMap((r) => r.hints ?? [])
+    ])
+  ];
+  if (hints.length) {
+    L2.push("", "HINTS");
+    for (const h of hints)
+      L2.push(`  ${h}`);
+  }
   return L2.join(`
 `);
 }

package/dist/core.mjs

@@ -23219,17 +23219,37 @@ function projectRows(rows, selection) {
   const columnNames = collectColumnNames(projectedRows);
   return { rows: normalizeRows(projectedRows, columnNames), columnNames };
 }
-function hasFieldPath(row, path) {
-  return readPath(row, path.split(".")).found;
+function hasFieldPath(row, segments) {
+  return readPath(row, segments).found;
 }
 function omitFieldPaths(rows, paths) {
-  return rows.map((row) => {
-    let projected = cloneRecord(row);
-    for (const path of paths)
-      projected = omitPath(projected, path.split("."));
+  const topLevel = new Set(paths);
+  const dotted = paths.filter((path) => path.includes(".")).map((path) => ({ head: path.slice(0, path.indexOf(".")), segments: path.split(".") }));
+  const maskRecord = (row) => {
+    let projected = cloneRecord(row, topLevel);
+    for (const { head, segments } of dotted) {
+      const value = row[head];
+      if (value !== null && typeof value === "object")
+        projected = omitPath(projected, segments);
+    }
     return projected;
+  };
+  return rows.map((row) => {
+    if (row === null || typeof row !== "object")
+      return {};
+    if (Array.isArray(row))
+      return maskArrayRow(row, maskRecord);
+    return maskRecord(row);
   });
 }
+function maskArrayRow(row, maskRecord) {
+  const out = {};
+  row.forEach((item, index) => {
+    const masked = Array.isArray(item) ? maskArrayRow(item, maskRecord) : item !== null && typeof item === "object" ? maskRecord(item) : item;
+    defineData(out, String(index), masked);
+  });
+  return out;
+}
 function readPath(value, segments) {
   if (segments.length === 0)
     return { found: true, value };
@@ -23273,10 +23293,10 @@ function omitPath(value, segments) {
   }
   return out;
 }
-function cloneRecord(value, omittedKey) {
+function cloneRecord(value, omittedKeys) {
   const out = {};
   for (const [key, child] of Object.entries(value)) {
-    if (key !== omittedKey)
+    if (!omittedKeys.has(key))
       defineData(out, key, child);
   }
   return out;
@@ -24116,6 +24136,16 @@ function matchesIndexGlob(pattern, name) {
 }
 
 // src/core/blacklist-validator.ts
+function flattenArrayRow(row) {
+  const records = [];
+  for (const item of row) {
+    if (Array.isArray(item))
+      records.push(...flattenArrayRow(item));
+    else if (item !== null && typeof item === "object")
+      records.push(item);
+  }
+  return records;
+}
 function dedupe2(values) {
   const seen = new Set;
   const result = [];
@@ -24216,7 +24246,56 @@ class BlacklistValidator {
     if (blacklistedColumns.length === 0) {
       return { filteredRows: rows, omittedColumns: [] };
     }
-    const omittedColumns = blacklistedColumns.filter((path3) => columnList.includes(path3) || rows.some((row) => hasFieldPath(row, path3)));
+    const probeNested = blacklistedColumns.some((path3) => path3.includes("."));
+    const presentColumns = new Set(columnList);
+    const nestedHeads = new Set;
+    const collect = (record) => {
+      for (const key of Object.getOwnPropertyNames(record)) {
+        presentColumns.add(key);
+        if (!probeNested)
+          continue;
+        const value = record[key];
+        if (value !== null && typeof value === "object")
+          nestedHeads.add(key);
+      }
+    };
+    for (const row of rows) {
+      if (row === null || typeof row !== "object")
+        continue;
+      if (Array.isArray(row)) {
+        for (const item of flattenArrayRow(row))
+          collect(item);
+        continue;
+      }
+      collect(row);
+    }
+    const protectedPaths = new Set(blacklistedColumns);
+    const omitted = new Set;
+    for (const path3 of blacklistedColumns) {
+      if (presentColumns.has(path3)) {
+        omitted.add(path3);
+        continue;
+      }
+      const dot = path3.indexOf(".");
+      if (dot < 0)
+        continue;
+      if (!nestedHeads.has(path3.slice(0, dot)))
+        continue;
+      const segments = path3.split(".");
+      if (rows.some((row) => hasFieldPath(row, segments)))
+        omitted.add(path3);
+    }
+    for (const column of presentColumns) {
+      let dot = column.indexOf(".");
+      while (dot >= 0) {
+        if (dot > 0 && protectedPaths.has(column.slice(0, dot))) {
+          omitted.add(column);
+          break;
+        }
+        dot = column.indexOf(".", dot + 1);
+      }
+    }
+    const omittedColumns = Array.from(omitted);
     if (omittedColumns.length === 0) {
       return { filteredRows: rows, omittedColumns: [] };
     }

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "dbcli-agent",
-  "version": "1.48.0",
+  "version": "1.49.0",
   "description": "Database CLI skill and command reference for AI agents.",
   "contextFileName": "AGENTS.md"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carllee1983/dbcli",
-  "version": "1.48.0",
+  "version": "1.49.0",
   "description": "Database CLI for AI agents",
   "type": "module",
   "publishConfig": {
@@ -81,8 +81,9 @@
     "typecheck": "tsc --noEmit --pretty false",
     "test:perf": "bun test ./tests/perf/*.bench.ts",
     "lint": "eslint src tests scripts --ext .ts --max-warnings=0",
-    "lint:fix": "eslint src tests scripts --ext .ts --fix --max-warnings=0",
-    "format": "prettier --write \"src/**/*.ts\" \"tests/**/*.ts\""
+    "format:check": "prettier --check .",
+    "format": "prettier --write .",
+    "lint:fix": "eslint src tests scripts --ext .ts --fix --max-warnings=0"
   },
   "dependencies": {
     "cli-table3": "^0.6.5",

package/plugins/dbcli-agent/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "dbcli-agent",
-  "version": "1.48.0",
+  "version": "1.49.0",
   "description": "Database CLI skill and command reference for AI agents",
   "author": {
     "name": "Carl Lee",
@@ -26,11 +26,7 @@
     "longDescription": "Installs the dbcli agent skill and reference guide so Codex can inspect schemas, query databases, respect blacklist boundaries, and recover from database errors through the dbcli command workflow.",
     "developerName": "Carl Lee",
     "category": "Productivity",
-    "capabilities": [
-      "Database",
-      "Local CLI",
-      "Agent Skill"
-    ],
+    "capabilities": ["Database", "Local CLI", "Agent Skill"],
     "defaultPrompt": [
       "Inspect my database with dbcli.",
       "Show schema safely with dbcli.",

package/plugins/dbcli-agent/skills/dbcli/SKILL.md

@@ -363,7 +363,7 @@ Full flags and edge cases: see [reference.md](reference.md) `init` section.
 | `assert` | query-only+ | **(v1.25)** SQL only. Verify an invariant; exit 1 on failure unless `--no-fail`. `--expect "rows>0\|value==X\|col:c not null\|unique\|between a and b\|>= n"`, `--vs <query> --compare rows\|value` (reconcile), `--against <snapshot> --tolerance <pct>`. |
 | `verification` | n/a | Inspect and manage local verification artifacts. `list` / `show <id-or-path>` / `summary` are read-only; `prune` is dry-run by default and deletes only with `--execute --force`. Reads `<cwd>/.dbcli/verification/`; no DB connection, no audit writes. |
 | `backfill artifact` | n/a | Build a bounded, reviewable source-to-SQL backfill artifact from JSON. Includes source/target identity, blacklist/schema preflight, read-back verification, and rollback hints; dry-run only and never executes writes. |
-| `proxy` | n/a | **(v1.26)** MySQL/MariaDB/PostgreSQL only. Local-dev observability proxy — relays app traffic to the real DB and appends query/latency/byte/error events to `.dbcli/proxy/events.jsonl`. Subcommands: `mysql` \| `mariadb` \| `postgresql`. `--listen`, `--target`, `--events`, `--slow-ms` (default `1000`), `--redact none\|literals`. Observe-only. **(v1.27)** `proxy analyze` aggregates the event log offline into a JSON/text report (summary, byFingerprint with suggestedCommands, slowest, errors, hotTables, N+1) — errors out if no events exist yet. |
+| `proxy` | n/a | **(v1.26)** MySQL/MariaDB/PostgreSQL only. Local-dev observability proxy — relays app traffic to the real DB and appends query/latency/byte/error events to `.dbcli/proxy/events.jsonl`. Subcommands: `mysql` \| `mariadb` \| `postgresql`. `--listen`, `--target`, `--events` (default `.dbcli/proxy/events.jsonl`), `--slow-ms` (default `1000`), `--redact none\|literals` (default `none`). Observe-only. **(v1.27)** `proxy analyze` aggregates the event log offline into a JSON/text report (summary, byFingerprint, slowest, errors, hotTables, N+1) — `--format`, `--top`, `--slow-ms`, `--n-plus-one`; errors out if no events exist yet. Actionable blocks carry `suggestedCommands` + `hints` so an agent can act: SELECT hotspots/N+1 → `explain` / `guide missing-index-for`, errors → `schema <table>` (verify names, never guess), N+1 → batch (JOIN / `IN (...)`). After analyzing, run each finding's `suggestedCommands`, read its `hints`, then propose the fix. |
 | `status` | query-only+ | Safe JSON/text summary (no credentials). |
 | `inspect` | query-only+ | Read-only context snapshot (connection, permission, blacklist, objects, snippets, context-aware `suggestedCommands`, and **(v1.23)** human-readable `hints`). `--for-agent` / `--brief` / `--no-connect` / `--require-schema-cache`. Supports `--recovery`. |
 | `report` | query-only+ | Diagnostic report built from `@diag/*` snippets. `--section <health\|capacity\|perf>` (comma-separated to combine), `--brief`, `--for-agent`, `--no-connect`. |

package/plugins/dbcli-agent/skills/dbcli/reference.md

@@ -1202,6 +1202,15 @@ dbcli proxy analyze --slow-ms 200 --n-plus-one 5  # custom thresholds
 
 **`proxy analyze`** — offline aggregation of the event log (no DB). Flags: `--events <path>` (default `.dbcli/proxy/events.jsonl`), `--format json|text` (default `json`), `--top <n>` (default 20; text rows + suggestedCommands depth), `--slow-ms <ms>` (default 1000; recomputes slowCount), `--n-plus-one <n>` (default 10), `--no-include-rotated`. JSON report blocks: `summary`, `byFingerprint` (sorted by total time; SELECT entries in the top-N carry `suggestedCommands` for `explain` / `guide missing-index-for`), `slowest`, `errors`, `hotTables`, `repetition` (N+1 suspects). Reads the current log plus the rotated `.1` segment by default.
 
+Every actionable block carries machine-readable next steps so an agent can move from "what is wrong" to "what to run":
+- `byFingerprint[]` — top-N SELECT entries get `suggestedCommands`: `dbcli explain "<sql>"` and `dbcli guide missing-index-for "<sql>"`.
+- `errors[]` — carries `tables`; emits `suggestedCommands` of `dbcli schema <table>` (capped at the first 3 tables) plus a `hints` note to verify table/column names before fixing (never guess column names). No tables known (e.g. a syntax error) → no `suggestedCommands`, but the hint still appears.
+- `repetition[]` — carries `statement` and a runnable `exampleSql` (the slowest occurrence). SELECT N+1 groups get `explain` / `guide missing-index-for` `suggestedCommands`; every group carries a `hints` note suggesting batching (JOIN / `IN (...)`) or caching.
+
+`suggestedCommands` are emitted as strings only — `proxy analyze` never executes them. When the proxy ran with `--redact literals`, `exampleSql` (and therefore the suggested commands) contains `?` placeholders; fill in real values before running them.
+
+**Acting on the report (agent loop):** after `proxy analyze`, for each block read `hints` for the diagnosis, run the entry's `suggestedCommands` to gather schema/plan/index evidence, then propose a concrete fix — add an index (`guide missing-index-for`), rewrite a slow SELECT (`explain`), batch an N+1 (`repetition`), or correct a column/table name (`errors` → `schema`). The text format mirrors this with aggregated `SUGGESTED COMMANDS` and `HINTS` sections; JSON keeps the suggestions attached per-finding.
+
 **Engines:** MySQL / MariaDB / PostgreSQL
 **Permission:** n/a (acts as a TCP relay; does not use dbcli's SQL permission model)
 

package/skills/dbcli/SKILL.md

@@ -363,7 +363,7 @@ Full flags and edge cases: see [reference.md](reference.md) `init` section.
 | `assert` | query-only+ | **(v1.25)** SQL only. Verify an invariant; exit 1 on failure unless `--no-fail`. `--expect "rows>0\|value==X\|col:c not null\|unique\|between a and b\|>= n"`, `--vs <query> --compare rows\|value` (reconcile), `--against <snapshot> --tolerance <pct>`. |
 | `verification` | n/a | Inspect and manage local verification artifacts. `list` / `show <id-or-path>` / `summary` are read-only; `prune` is dry-run by default and deletes only with `--execute --force`. Reads `<cwd>/.dbcli/verification/`; no DB connection, no audit writes. |
 | `backfill artifact` | n/a | Build a bounded, reviewable source-to-SQL backfill artifact from JSON. Includes source/target identity, blacklist/schema preflight, read-back verification, and rollback hints; dry-run only and never executes writes. |
-| `proxy` | n/a | **(v1.26)** MySQL/MariaDB/PostgreSQL only. Local-dev observability proxy — relays app traffic to the real DB and appends query/latency/byte/error events to `.dbcli/proxy/events.jsonl`. Subcommands: `mysql` \| `mariadb` \| `postgresql`. `--listen`, `--target`, `--events`, `--slow-ms` (default `1000`), `--redact none\|literals`. Observe-only. **(v1.27)** `proxy analyze` aggregates the event log offline into a JSON/text report (summary, byFingerprint with suggestedCommands, slowest, errors, hotTables, N+1) — errors out if no events exist yet. |
+| `proxy` | n/a | **(v1.26)** MySQL/MariaDB/PostgreSQL only. Local-dev observability proxy — relays app traffic to the real DB and appends query/latency/byte/error events to `.dbcli/proxy/events.jsonl`. Subcommands: `mysql` \| `mariadb` \| `postgresql`. `--listen`, `--target`, `--events` (default `.dbcli/proxy/events.jsonl`), `--slow-ms` (default `1000`), `--redact none\|literals` (default `none`). Observe-only. **(v1.27)** `proxy analyze` aggregates the event log offline into a JSON/text report (summary, byFingerprint, slowest, errors, hotTables, N+1) — `--format`, `--top`, `--slow-ms`, `--n-plus-one`; errors out if no events exist yet. Actionable blocks carry `suggestedCommands` + `hints` so an agent can act: SELECT hotspots/N+1 → `explain` / `guide missing-index-for`, errors → `schema <table>` (verify names, never guess), N+1 → batch (JOIN / `IN (...)`). After analyzing, run each finding's `suggestedCommands`, read its `hints`, then propose the fix. |
 | `status` | query-only+ | Safe JSON/text summary (no credentials). |
 | `inspect` | query-only+ | Read-only context snapshot (connection, permission, blacklist, objects, snippets, context-aware `suggestedCommands`, and **(v1.23)** human-readable `hints`). `--for-agent` / `--brief` / `--no-connect` / `--require-schema-cache`. Supports `--recovery`. |
 | `report` | query-only+ | Diagnostic report built from `@diag/*` snippets. `--section <health\|capacity\|perf>` (comma-separated to combine), `--brief`, `--for-agent`, `--no-connect`. |

package/skills/dbcli/reference.md

@@ -1202,6 +1202,15 @@ dbcli proxy analyze --slow-ms 200 --n-plus-one 5  # custom thresholds
 
 **`proxy analyze`** — offline aggregation of the event log (no DB). Flags: `--events <path>` (default `.dbcli/proxy/events.jsonl`), `--format json|text` (default `json`), `--top <n>` (default 20; text rows + suggestedCommands depth), `--slow-ms <ms>` (default 1000; recomputes slowCount), `--n-plus-one <n>` (default 10), `--no-include-rotated`. JSON report blocks: `summary`, `byFingerprint` (sorted by total time; SELECT entries in the top-N carry `suggestedCommands` for `explain` / `guide missing-index-for`), `slowest`, `errors`, `hotTables`, `repetition` (N+1 suspects). Reads the current log plus the rotated `.1` segment by default.
 
+Every actionable block carries machine-readable next steps so an agent can move from "what is wrong" to "what to run":
+- `byFingerprint[]` — top-N SELECT entries get `suggestedCommands`: `dbcli explain "<sql>"` and `dbcli guide missing-index-for "<sql>"`.
+- `errors[]` — carries `tables`; emits `suggestedCommands` of `dbcli schema <table>` (capped at the first 3 tables) plus a `hints` note to verify table/column names before fixing (never guess column names). No tables known (e.g. a syntax error) → no `suggestedCommands`, but the hint still appears.
+- `repetition[]` — carries `statement` and a runnable `exampleSql` (the slowest occurrence). SELECT N+1 groups get `explain` / `guide missing-index-for` `suggestedCommands`; every group carries a `hints` note suggesting batching (JOIN / `IN (...)`) or caching.
+
+`suggestedCommands` are emitted as strings only — `proxy analyze` never executes them. When the proxy ran with `--redact literals`, `exampleSql` (and therefore the suggested commands) contains `?` placeholders; fill in real values before running them.
+
+**Acting on the report (agent loop):** after `proxy analyze`, for each block read `hints` for the diagnosis, run the entry's `suggestedCommands` to gather schema/plan/index evidence, then propose a concrete fix — add an index (`guide missing-index-for`), rewrite a slow SELECT (`explain`), batch an N+1 (`repetition`), or correct a column/table name (`errors` → `schema`). The text format mirrors this with aggregated `SUGGESTED COMMANDS` and `HINTS` sections; JSON keeps the suggestions attached per-finding.
+
 **Engines:** MySQL / MariaDB / PostgreSQL
 **Permission:** n/a (acts as a TCP relay; does not use dbcli's SQL permission model)