@carllee1983/dbcli 9.0.0 → 9.1.0

package/dist/core.mjs

@@ -1092,10 +1092,17 @@ var DATABASE_SYSTEMS = Object.freeze([
   "postgresql",
   "mysql",
   "mariadb",
+  "sqlite",
   "mongodb",
   "redis",
   "elasticsearch"
 ]);
+var SQL_DATABASE_SYSTEMS = Object.freeze([
+  "postgresql",
+  "mysql",
+  "mariadb",
+  "sqlite"
+]);
 
 class ConnectionError extends Error {
   code;
@@ -1247,6 +1254,38 @@ var ENGINE_CAPABILITIES = Object.freeze({
     ...SQL_BASE,
     check: cap("limited", "readonly", "SQL-only and strongest on MySQL/MariaDB.")
   }),
+  sqlite: Object.freeze({
+    ...SQL_BASE,
+    init: cap("supported", "local-write", "Asks for a file path and a permission; the file must already exist."),
+    use: cap("supported", "local-write", "Switches connections and displays the file path."),
+    schemaFullScan: cap("unsupported", "none", "Full schema cache scan is not implemented for SQLite."),
+    lint: cap("unsupported", "none", "Static lint is not enabled for the SQLite dialect yet."),
+    queries: cap("supported", "local-write", "Snippets may declare `engine: sqlite` and bind with `?` placeholders."),
+    insert: cap("supported", "db-write", "Row insert through the shared data-executor path."),
+    update: cap("supported", "db-write", "Row update with a mandatory --where clause."),
+    delete: cap("supported", "db-write", "Row delete with a mandatory --where clause."),
+    export: cap("supported", "local-write", "Exports SELECT results to json, csv or html through the shared query path."),
+    check: cap("unsupported", "none", "Data health check is not enabled for SQLite."),
+    diff: cap("unsupported", "none", "Schema snapshots are not enabled for SQLite."),
+    migrate: cap("unsupported", "none", "SQLite ALTER TABLE covers few operations and a column change is a table rebuild; no DDL generator exists."),
+    shell: cap("unsupported", "none", "The REPL is not enabled for SQLite."),
+    doctor: cap("supported", "readonly", "Checks the file exists, is readable, and is writable when the permission allows writes."),
+    inspect: cap("unsupported", "none", "Inspection collectors are not enabled for SQLite."),
+    report: cap("unsupported", "none", "Report diagnostics query engine-specific statistics views."),
+    guide: cap("unsupported", "none", "Guides depend on engine-specific EXPLAIN output."),
+    explain: cap("unsupported", "none", "EXPLAIN handling is not enabled for SQLite."),
+    plan: cap("unsupported", "none", "Plan capture is not enabled for SQLite."),
+    impactAssess: cap("unsupported", "none", "Impact assessment is not enabled for SQLite."),
+    assert: cap("unsupported", "none", "Assertions are not enabled for SQLite."),
+    snapshot: cap("unsupported", "none", "Result snapshots are not enabled for SQLite."),
+    verify: cap("unsupported", "none", "Write verification is not enabled for SQLite."),
+    semantic: cap("unsupported", "none", "Semantic context work is not enabled for SQLite."),
+    design: cap("unsupported", "none", "Schema design work is not enabled for SQLite."),
+    proxy: cap("not-applicable", "none", "SQLite has no network protocol to proxy."),
+    proxyAnalyze: cap("not-applicable", "none", "There are no SQLite proxy events to analyse."),
+    password: cap("not-applicable", "none", "A SQLite connection has no credential to store or rotate."),
+    queryLimitGuard: cap("limited", "readonly", "Applies the same LIMIT rewrite as the other SQL engines; under query-only the handle is opened read-only, which a database with an unreplayed WAL cannot satisfy.")
+  }),
   mysql: Object.freeze(SQL_BASE),
   mariadb: Object.freeze(SQL_BASE),
   mongodb: Object.freeze({
@@ -1616,7 +1655,8 @@ var messages_default = {
     connection_not_found: "Connection '{name}' does not exist",
     cannot_remove_last: "Cannot remove the last connection",
     connection_already_exists: "Connection '{name}' already exists",
-    rename_invalid_format: "Usage: --rename <old-name>:<new-name>"
+    rename_invalid_format: "Usage: --rename <old-name>:<new-name>",
+    prompt_sqlite_file: "SQLite database file path: "
   },
   inspect: {
     description: "Read-only snapshot of connection, permission, blacklist, objects, snippets, and suggested next commands.",
@@ -1785,7 +1825,8 @@ Or use interactive mode: run "dbcli init --use-env-refs" without --no-interactiv
     env_var_not_defined: `Cannot test connection: environment variable {envKey} is not defined.
 Set {envKey} in .env or environment variables.
 Hint: run 'export {envKey}=<value>' and retry`,
-    invalid_output_format: "--format {format} is not supported here \u2014 use text or json"
+    invalid_output_format: "--format {format} is not supported here \u2014 use text or json",
+    sqlite_file_required: "A SQLite connection needs a file path. Pass --file <path> or run init interactively."
   },
   success: {
     inserted: "Successfully inserted {count} row(s)",
@@ -1946,7 +1987,8 @@ var messages_default2 = {
     connection_not_found: "\u9023\u7DDA '{name}' \u4E0D\u5B58\u5728",
     cannot_remove_last: "\u7121\u6CD5\u79FB\u9664\u6700\u5F8C\u4E00\u500B\u9023\u7DDA",
     connection_already_exists: "\u9023\u7DDA '{name}' \u5DF2\u5B58\u5728",
-    rename_invalid_format: "\u7528\u6CD5\uFF1A--rename <\u820A\u540D\u7A31>:<\u65B0\u540D\u7A31>"
+    rename_invalid_format: "\u7528\u6CD5\uFF1A--rename <\u820A\u540D\u7A31>:<\u65B0\u540D\u7A31>",
+    prompt_sqlite_file: "SQLite \u8CC7\u6599\u5EAB\u6A94\u6848\u8DEF\u5F91\uFF1A"
   },
   inspect: {
     description: "\u552F\u8B80\u6AA2\u8996\uFF1A\u9023\u7DDA\u3001\u6B0A\u9650\u3001\u9ED1\u540D\u55AE\u3001\u7269\u4EF6\u3001\u7247\u6BB5\u8207\u5EFA\u8B70\u4E0B\u4E00\u6B65\u6307\u4EE4\u3002",
@@ -2115,7 +2157,8 @@ var messages_default2 = {
     env_var_not_defined: `\u7121\u6CD5\u6E2C\u8A66\u9023\u7DDA\uFF1A\u74B0\u5883\u8B8A\u6578 {envKey} \u672A\u5B9A\u7FA9\u3002
 \u8ACB\u5728 .env \u6216\u74B0\u5883\u8B8A\u6578\u4E2D\u8A2D\u5B9A {envKey}\u3002
 \u63D0\u793A\uFF1A\u57F7\u884C 'export {envKey}=<value>' \u5F8C\u91CD\u8A66`,
-    invalid_output_format: "\u7121\u6CD5\u4F7F\u7528 --format {format}\uFF0C\u8ACB\u4F7F\u7528 text \u6216 json"
+    invalid_output_format: "\u7121\u6CD5\u4F7F\u7528 --format {format}\uFF0C\u8ACB\u4F7F\u7528 text \u6216 json",
+    sqlite_file_required: "SQLite \u9023\u7DDA\u9700\u8981\u4E00\u500B\u6A94\u6848\u8DEF\u5F91\u3002\u8ACB\u7528 --file <path>\uFF0C\u6216\u4EE5\u4E92\u52D5\u6A21\u5F0F\u57F7\u884C init\u3002"
   },
   success: {
     inserted: "\u6210\u529F\u63D2\u5165 {count} \u5217",
@@ -2649,7 +2692,7 @@ function fixDoubleEncodedUtf8(str) {
 
 // src/adapters/identifier-quote.ts
 function quoteCharFor(dialect) {
-  return dialect === "postgresql" ? '"' : "`";
+  return dialect === "postgresql" || dialect === "sqlite" ? '"' : "`";
 }
 function assertQuotable(name, what) {
   if (name.length === 0) {
@@ -3951,7 +3994,16 @@ function stripCommentsAndStrings(sql, options = {}) {
         continue;
       }
     }
-    if (mysqlDialect && char === "`") {
+    if (options.dialect === "sqlite" && char === "[") {
+      i++;
+      while (i < sql.length && sql[i] !== "]")
+        i++;
+      if (i < sql.length)
+        i++;
+      result += " ";
+      continue;
+    }
+    if ((mysqlDialect || options.dialect === "sqlite") && char === "`") {
       i++;
       while (i < sql.length) {
         if (sql[i] === "`") {
@@ -4024,8 +4076,14 @@ function extractFirstKeyword(sql) {
   }
   return firstKeyword;
 }
-function mapKeywordToType(keyword) {
+var DECLARED_ADMIN_ONLY_KEYWORDS = new Set(["PRAGMA", "VACUUM", "REINDEX"]);
+function isDeclaredAdminOnly(keyword) {
+  return DECLARED_ADMIN_ONLY_KEYWORDS.has(keyword.toUpperCase());
+}
+function mapKeywordToType(keyword, dialect) {
   const upper = keyword.toUpperCase();
+  if (upper === "REPLACE" && dialect === "sqlite")
+    return "REPLACE";
   if (upper === "SELECT")
     return "SELECT";
   if (upper === "SHOW")
@@ -4055,7 +4113,7 @@ function mapKeywordToType(keyword) {
   return "UNKNOWN";
 }
 function isDestructiveOperation(type) {
-  return ["DELETE", "DROP", "ALTER", "TRUNCATE", "CREATE", "GRANT"].includes(type);
+  return ["DELETE", "REPLACE", "DROP", "ALTER", "TRUNCATE", "CREATE", "GRANT"].includes(type);
 }
 function extractAllKeywords(sql) {
   const upper = sql.toUpperCase();
@@ -4135,6 +4193,16 @@ function permissionAtLeast(actual, required) {
 }
 
 // src/core/permission-guard.ts
+class ConnectionBoundaryError extends Error {
+  classification;
+  constructor(message, classification) {
+    super(message);
+    this.classification = classification;
+    this.name = "ConnectionBoundaryError";
+    Object.setPrototypeOf(this, ConnectionBoundaryError.prototype);
+  }
+}
+
 class PermissionError extends Error {
   classification;
   requiredPermission;
@@ -4146,9 +4214,9 @@ class PermissionError extends Error {
     Object.setPrototypeOf(this, PermissionError.prototype);
   }
 }
-function classifyStatement(sql) {
+function classifyStatement(sql, dialect) {
   const normalized = normalizeSQL(sql);
-  const stripped = stripCommentsAndStrings(normalized);
+  const stripped = stripCommentsAndStrings(normalized, { dialect });
   const upper = stripped.toUpperCase();
   if (/^\s*ANALYZE\s+SELECT\b/i.test(stripped)) {
     return {
@@ -4161,7 +4229,16 @@ function classifyStatement(sql) {
   }
   const composite = detectCompositePatterns(upper);
   const firstKeyword = extractFirstKeyword(stripped);
-  const type = mapKeywordToType(firstKeyword);
+  if (isDeclaredAdminOnly(firstKeyword)) {
+    return {
+      type: "UNKNOWN",
+      isDangerous: true,
+      keywords: extractAllKeywords(stripped),
+      isComposite: false,
+      confidence: "HIGH"
+    };
+  }
+  const type = mapKeywordToType(firstKeyword, dialect);
   return {
     type,
     isDangerous: isDestructiveOperation(type),
@@ -4170,7 +4247,7 @@ function classifyStatement(sql) {
     confidence: determineConfidence(type, firstKeyword, upper)
   };
 }
-var SQL_DIALECTS = ["postgresql", "mysql", "mariadb"];
+var SQL_DIALECTS = ["postgresql", "mysql", "mariadb", "sqlite"];
 var SQL_WRITE_OR_DDL_KEYWORDS = /(?<![.\w])(INSERT|UPDATE|DELETE|MERGE|UPSERT|REPLACE|TRUNCATE|DROP|ALTER|CREATE|GRANT|REVOKE|RENAME|INTO)\b(?!\s*\()/i;
 var SQL_LOCK_CLAUSE = /\bFOR\s+(?:NO\s+KEY\s+)?UPDATE\b|\bFOR\s+(?:KEY\s+)?SHARE\b/gi;
 function findWriteKeyword(sql, dialects) {
@@ -4207,8 +4284,22 @@ function escalateHiddenWrite(sql, classification, dialect) {
     escalatedFrom: hidden
   };
 }
+var SQLITE_CROSS_DATABASE = /^\s*(ATTACH|DETACH)\b/i;
+function reachesAnotherDatabase(sql, dialect) {
+  if (dialect !== "sqlite")
+    return false;
+  return stripCommentsAndStrings(sql, { dialect }).split(";").some((statement) => SQLITE_CROSS_DATABASE.test(statement));
+}
 function checkPermission(sql, permission, dialect) {
-  const classification = escalateHiddenWrite(sql, classifyStatement(sql), dialect);
+  if (reachesAnotherDatabase(sql, dialect)) {
+    return {
+      allowed: false,
+      reason: "ATTACH and DETACH are refused on a SQLite connection: they reach a database file " + "outside the one this connection names, which the blacklist, audit log and schema " + "cache are all scoped to. Configure a second connection instead.",
+      classification: classifyStatement(sql),
+      boundary: true
+    };
+  }
+  const classification = escalateHiddenWrite(sql, classifyStatement(sql, dialect), dialect);
   if (permission !== "admin" && containsMultipleStatements(sql, dialect)) {
     return {
       allowed: false,
@@ -4222,7 +4313,7 @@ function checkPermission(sql, permission, dialect) {
 var TIER_GRANTS = [
   { permission: "query-only", types: ["SELECT", "SHOW", "DESCRIBE", "EXPLAIN"] },
   { permission: "read-write", types: ["INSERT", "UPDATE"] },
-  { permission: "data-admin", types: ["DELETE"] }
+  { permission: "data-admin", types: ["DELETE", "REPLACE"] }
 ];
 function minimumPermissionFor(type) {
   return TIER_GRANTS.find((tier) => tier.types.includes(type))?.permission ?? "admin";
@@ -4296,6 +4387,9 @@ function enforcePermissionForType(type, permission) {
 }
 function enforcePermission(sql, permission, dialect) {
   const result = checkPermission(sql, permission, dialect);
+  if (result.boundary) {
+    throw new ConnectionBoundaryError(result.reason, result.classification);
+  }
   if (!result.allowed) {
     throw new PermissionError(result.reason, result.classification, result.requiredPermission ?? "admin");
   }
@@ -4577,6 +4671,18 @@ function tokenize(sql, dialect, backslashEscapes) {
       }
       continue;
     }
+    if (dialect === "sqlite" && char === "[") {
+      i++;
+      let value = "";
+      while (i < sql.length && sql[i] !== "]") {
+        value += sql[i];
+        i++;
+      }
+      if (i < sql.length)
+        i++;
+      tokens.push({ kind: "identifier", value, quoted: true });
+      continue;
+    }
     if (char === '"' || char === "`") {
       const quote = char;
       i++;
@@ -5307,7 +5413,7 @@ class DataExecutor {
     return this.dbSystem;
   }
   getQuoteChar() {
-    return this.dbSystem === "mysql" ? "`" : '"';
+    return this.dbSystem === "mysql" || this.dbSystem === "mariadb" ? "`" : '"';
   }
   checkBlacklist(operation, tableName) {
     this.blacklistValidator?.checkTableBlacklist(operation, tableName, []);
@@ -9425,6 +9531,35 @@ var SqlConnectionConfigSchema = exports_external.object({
   database: StringOrEnvRef,
   ...TimeoutField
 });
+var SQLITE_MEMORY_TARGET_MESSAGE = "SQLite in-memory databases are refused: a memory target is a different database on every " + "connection, so it cannot be the connection identity the blacklist, audit log and schema " + "cache are scoped to. Point `file` at a database file on disk. See ADR-0038.";
+function isSqliteMemoryTarget(value) {
+  const trimmed = value.trim();
+  if (trimmed.toLowerCase() === ":memory:")
+    return true;
+  if (!trimmed.toLowerCase().startsWith("file:"))
+    return false;
+  const withoutScheme = trimmed.slice("file:".length);
+  const queryStart = withoutScheme.indexOf("?");
+  const path = queryStart === -1 ? withoutScheme : withoutScheme.slice(0, queryStart);
+  if (path.toLowerCase() === ":memory:")
+    return true;
+  const query = queryStart === -1 ? "" : withoutScheme.slice(queryStart + 1);
+  return new URLSearchParams(query).get("mode")?.toLowerCase() === "memory";
+}
+var SqliteConnectionConfigSchema = exports_external.object({
+  system: exports_external.literal("sqlite"),
+  file: exports_external.union([exports_external.string().min(1), EnvRefSchema]).superRefine((value, ctx) => {
+    if (typeof value === "string" && isSqliteMemoryTarget(value)) {
+      ctx.addIssue({ code: exports_external.ZodIssueCode.custom, message: SQLITE_MEMORY_TARGET_MESSAGE });
+    }
+  }),
+  host: OptStringOrEnvRef,
+  port: exports_external.union([exports_external.number().int(), EnvRefSchema]).optional().default(0),
+  user: OptStringOrEnvRef,
+  password: exports_external.union([exports_external.string(), EnvRefSchema]).optional().default(""),
+  database: OptStringOrEnvRef,
+  ...TimeoutField
+});
 var RedisConnectionConfigSchema = exports_external.object({
   system: exports_external.literal("redis"),
   host: StringOrEnvRef,
@@ -9451,6 +9586,7 @@ var ElasticsearchConnectionConfigSchema = exports_external.object({
 });
 var ConnectionConfigSchema = exports_external.union([
   SqlConnectionConfigSchema,
+  SqliteConnectionConfigSchema,
   MongoDBConnectionConfigSchema,
   RedisConnectionConfigSchema,
   ElasticsearchConnectionConfigSchema
@@ -9521,6 +9657,11 @@ var SqlNamedConnectionSchema = SqlConnectionConfigSchema.extend({
   envFile: exports_external.string().optional(),
   environment: EnvironmentLabelSchema
 });
+var SqliteNamedConnectionSchema = SqliteConnectionConfigSchema.extend({
+  permission: PermissionSchema,
+  envFile: exports_external.string().optional(),
+  environment: EnvironmentLabelSchema
+});
 var MongoDBNamedConnectionSchema = MongoDBConnectionConfigSchema.extend({
   permission: PermissionSchema,
   envFile: exports_external.string().optional(),
@@ -9538,6 +9679,7 @@ var ElasticsearchNamedConnectionSchema = ElasticsearchConnectionConfigSchema.ext
 });
 var NamedConnectionUnion = exports_external.union([
   SqlNamedConnectionSchema,
+  SqliteNamedConnectionSchema,
   MongoDBNamedConnectionSchema,
   RedisNamedConnectionSchema,
   ElasticsearchNamedConnectionSchema
@@ -9972,6 +10114,7 @@ function listConnections(config) {
       port: c.port ?? 27017,
       database: c.database ?? "",
       ...c.uri !== undefined && { uri: c.uri },
+      ...c.file !== undefined && { file: c.file },
       isDefault: name === config.default
     };
   });
@@ -10001,7 +10144,10 @@ function setDefaultConnection(config, name) {
 function migrateV1ToV2(v1) {
   const system = v1.connection.system;
   if (!SQL_SYSTEMS.includes(system)) {
-    throw new Error(`v1\u2192v2 \u81EA\u52D5\u5347\u7D1A\u76EE\u524D\u50C5\u652F\u63F4 SQL \u9023\u7DDA(mysql/postgresql/mariadb),\u4E0D\u652F\u63F4 '${system}'`);
+    if (system === "sqlite") {
+      throw new Error(`v1\u2192v2 \u81EA\u52D5\u5347\u7D1A\u4E0D\u63A5\u53D7 'sqlite'\uFF1Av1 \u8A2D\u5B9A\u683C\u5F0F\u65E9\u65BC SQLite \u652F\u63F4\uFF0C\u4E0D\u53EF\u80FD\u662F\u7531 dbcli \u5BEB\u51FA\u4F86\u7684\u3002` + `\u8ACB\u7528 'dbcli init --system sqlite' \u76F4\u63A5\u5EFA\u7ACB v2 \u9023\u7DDA\u3002`);
+    }
+    throw new Error(`v1\u2192v2 \u81EA\u52D5\u5347\u7D1A\u76EE\u524D\u50C5\u652F\u63F4 mysql/postgresql/mariadb \u7684\u9010\u6B04\u9023\u7DDA\u8A2D\u5B9A,\u4E0D\u652F\u63F4 '${system}'`);
   }
   const c = v1.connection;
   return {
@@ -11749,6 +11895,15 @@ function dedupe2(values) {
   }
   return result;
 }
+var NO_MASKING_COST = Object.freeze({
+  rowsScanned: 0,
+  keysScanned: 0,
+  ruleEvaluations: 0,
+  pathSplits: 0,
+  nestedProbeRows: 0,
+  nestedGlobRows: 0,
+  nestedGlobMatches: 0
+});
 function omittedByName(omittedColumns, path) {
   return omittedColumns.some((omitted) => path === omitted || path.startsWith(`${omitted}.`));
 }
@@ -11866,13 +12021,25 @@ class BlacklistValidator {
     const tables = dedupe2(tableNames);
     const blacklistedColumns = tables.length === 0 ? this.manager.getAllBlacklistedColumns() : Array.from(new Set(tables.flatMap((table) => this.manager.getBlacklistedColumns(table))));
     if (blacklistedColumns.length === 0) {
-      return { filteredRows: rows, omittedColumns: [], reachesOmitted: () => false };
+      return {
+        filteredRows: rows,
+        omittedColumns: [],
+        cost: NO_MASKING_COST,
+        reachesOmitted: () => false
+      };
     }
+    let rowsScanned = 0;
+    let keysScanned = 0;
+    let ruleEvaluations = 0;
+    let pathSplits = 0;
+    let nestedProbeRows = 0;
+    let nestedGlobRows = 0;
     const probeNested = blacklistedColumns.some((path) => path.includes("."));
     const presentColumns = new Set(columnList);
     const nestedHeads = new Set;
     const collect = (record) => {
       for (const key of Object.getOwnPropertyNames(record)) {
+        keysScanned += 1;
         presentColumns.add(key);
         if (!probeNested)
           continue;
@@ -11882,6 +12049,7 @@ class BlacklistValidator {
       }
     };
     for (const row of rows) {
+      rowsScanned += 1;
       if (row === null || typeof row !== "object")
         continue;
       if (Array.isArray(row)) {
@@ -11904,6 +12072,7 @@ class BlacklistValidator {
     }
     const omitted = new Set;
     for (const path of blacklistedColumns) {
+      ruleEvaluations += 1;
       const present = presentByFolded.get(foldFieldPath(path));
       if (present !== undefined) {
         for (const name of present)
@@ -11915,8 +12084,17 @@ class BlacklistValidator {
         continue;
       if (!nestedHeads.has(foldFieldPath(path.slice(0, dot))))
         continue;
+      pathSplits += 1;
       const segments = path.split(".").map(foldFieldPath);
-      if (rows.some((row) => hasFieldPath(row, segments, PRE_FOLDED)))
+      let found = false;
+      for (const row of rows) {
+        nestedProbeRows += 1;
+        if (hasFieldPath(row, segments, PRE_FOLDED)) {
+          found = true;
+          break;
+        }
+      }
+      if (found)
         omitted.add(path);
     }
     const nestedGlobs = globRules.filter((pattern) => pattern.segments.length > 1);
@@ -11927,6 +12105,7 @@ class BlacklistValidator {
       for (const row of rows) {
         if (pending.size === 0)
           break;
+        nestedGlobRows += 1;
         if (row === null || typeof row !== "object")
           continue;
         collectNestedMatches(row, states, pending, (pattern) => {
@@ -11964,13 +12143,35 @@ class BlacklistValidator {
     }
     const omittedColumns = Array.from(omitted);
     if (omittedColumns.length === 0) {
-      return { filteredRows: rows, omittedColumns: [], reachesOmitted: () => false };
+      return {
+        filteredRows: rows,
+        omittedColumns: [],
+        cost: Object.freeze({
+          rowsScanned,
+          keysScanned,
+          ruleEvaluations,
+          pathSplits,
+          nestedProbeRows,
+          nestedGlobRows,
+          nestedGlobMatches: matchedNested.length
+        }),
+        reachesOmitted: () => false
+      };
     }
     const removalPaths = matchedNested.length === 0 ? omittedColumns : omittedColumns.filter((path) => !matchedNested.some((p) => p.raw === path));
     const filteredRows = omitFieldPaths(rows, removalPaths, matchedNested.length > 0 ? { ...FOLD_CASE2, patterns: matchedNested } : FOLD_CASE2);
     return {
       filteredRows,
       omittedColumns,
+      cost: Object.freeze({
+        rowsScanned,
+        keysScanned,
+        ruleEvaluations,
+        pathSplits,
+        nestedProbeRows,
+        nestedGlobRows,
+        nestedGlobMatches: matchedNested.length
+      }),
       reachesOmitted: (path) => {
         if (omittedByName(removalPaths, path))
           return true;

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "dbcli-agent",
-  "version": "9.0.0",
+  "version": "9.1.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": "9.0.0",
+  "version": "9.1.0",
   "description": "Database CLI for AI agents",
   "type": "module",
   "publishConfig": {
@@ -86,9 +86,10 @@
     "core-stdout:check": "bun run scripts/check-core-no-stdout.ts",
     "plan:check": "bun run scripts/check-plan-acceptance.ts",
     "forgeflow:check": "bun run scripts/check-forgeflow-adoption.ts && bun run scripts/check-forgeflow-handoff.ts",
+    "forgeflow:contract": "bun run scripts/check-forgeflow-contract.ts",
     "typecheck": "tsc --noEmit --pretty false",
     "typecheck:tests": "tsc --noEmit --pretty false -p tsconfig.tests.json",
-    "test:perf": "bun test ./tests/perf/*.bench.ts",
+    "test:perf": "bun test --timeout 30000 ./tests/perf/*.bench.ts",
     "lint": "eslint src tests scripts --ext .ts --max-warnings=0",
     "format:check": "prettier --check .",
     "format": "prettier --write .",

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

@@ -1,6 +1,6 @@
 {
   "name": "dbcli-agent",
-  "version": "9.0.0",
+  "version": "9.1.0",
   "description": "Database CLI skill and command reference for AI agents",
   "author": {
     "name": "Carl Lee",

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

@@ -3872,7 +3872,7 @@ GET /orders/_search
 
 - Enter a request line `<METHOD> /<path>`, then an optional multi-line JSON body; a **blank line** submits the block. Responses render as pretty-printed JSON.
 - **The connection's permission tier applies, as it does to `dbcli query`.** The request is classified through the same classifier the query path uses, on the path the server will actually route — the query string is discarded and percent-encoding and dot segments are resolved first, so `?filter_path=...` cannot change the verdict.
-- **Reads are an allowlist; anything else needs `admin`.** Permitted below `admin`: `_search` and `_count` on an index or unscoped, `_doc` / `_source` reads, `_mapping` / `_settings` / `_alias` reads, `_cat/*` (except `_cat/aliases` and `_cat/tasks`), `_cluster/health`, and `GET` / `HEAD` of a bare index name. Writes to one document are the usual tiers. **Everything else — including any endpoint not listed here — requires `admin`**, so `DELETE /<index>`, `DELETE /_all`, `_delete_by_query`, `_update_by_query`, `_reindex`, `_aliases`, `PUT /<index>/_mapping`, `PUT /<index>/_settings`, `_sql`, `_scripts`, `_security`, `_snapshot`, `_nodes` and `_cluster/state` are all refused below it. The list is a floor, not a claim that everything absent from it is dangerous: a missing entry costs you an unnecessary `admin` requirement rather than a bypass. See [ADR-0014](https://github.com/CarlLee1983/dbcli/blob/main/docs/adr/0014-elasticsearch-reads-are-an-allowlist.md).
+- **Reads are an allowlist; anything else needs `admin`.** Permitted below `admin`: `_search` and `_count` on an index or unscoped, `_doc` / `_source` reads, `_mapping` / `_settings` / `_alias` reads, `_cat/*` (except `_cat/aliases` and `_cat/tasks`), `_cluster/health`, and `GET` / `HEAD` of a bare index name. Writes to one document are the usual tiers. **Everything else — including any endpoint not listed here — requires `admin`**, so `DELETE /<index>`, `DELETE /_all`, `_delete_by_query`, `_update_by_query`, `_reindex`, `_aliases`, `PUT /<index>/_mapping`, `PUT /<index>/_settings`, `_sql`, `_scripts`, `_security`, `_snapshot`, `_nodes` and `_cluster/state` are all refused below it. The list is a floor, not a claim that everything absent from it is dangerous: a missing entry costs you an unnecessary `admin` requirement rather than a bypass. See [ADR-0014](https://github.com/CarlLee1983/dbcli/blob/main/docs/adr/ADR-0014-elasticsearch-reads-are-an-allowlist.md).
 - A path is refused unless it is **byte-identical** to what the URL parser produces — the same parser the request goes through — and the refusal tells you the canonical spelling to write instead. This is what stops a path that reads one way here and routes another way at the server: `#` truncates a path in transit (`POST /_reindex#/_count` reaches Elasticsearch as `POST /_reindex`), and tab, newline and `\` are rewritten too. A document id containing a space or a non-ASCII character must be written percent-encoded; the error message gives you the exact string.
 - A quoted string request body is refused; write the body as JSON. So is a `source=` query parameter — Elasticsearch accepts it in place of a body, where none of the body checks can see it. `_source`, `_source_includes` and `_source_excludes` are unaffected.
 - Blacklisted field names are refused in the query string as well as the body, because the URI-search form names fields directly (`?q=…`, `?sort=…`, `?docvalue_fields=…`). A name matches on any dot component, so `password.keyword` — the multi-field every `text` field gets by default — and `params._source.password` inside a script are both refused.

package/skills/dbcli/reference.md

@@ -3872,7 +3872,7 @@ GET /orders/_search
 
 - Enter a request line `<METHOD> /<path>`, then an optional multi-line JSON body; a **blank line** submits the block. Responses render as pretty-printed JSON.
 - **The connection's permission tier applies, as it does to `dbcli query`.** The request is classified through the same classifier the query path uses, on the path the server will actually route — the query string is discarded and percent-encoding and dot segments are resolved first, so `?filter_path=...` cannot change the verdict.
-- **Reads are an allowlist; anything else needs `admin`.** Permitted below `admin`: `_search` and `_count` on an index or unscoped, `_doc` / `_source` reads, `_mapping` / `_settings` / `_alias` reads, `_cat/*` (except `_cat/aliases` and `_cat/tasks`), `_cluster/health`, and `GET` / `HEAD` of a bare index name. Writes to one document are the usual tiers. **Everything else — including any endpoint not listed here — requires `admin`**, so `DELETE /<index>`, `DELETE /_all`, `_delete_by_query`, `_update_by_query`, `_reindex`, `_aliases`, `PUT /<index>/_mapping`, `PUT /<index>/_settings`, `_sql`, `_scripts`, `_security`, `_snapshot`, `_nodes` and `_cluster/state` are all refused below it. The list is a floor, not a claim that everything absent from it is dangerous: a missing entry costs you an unnecessary `admin` requirement rather than a bypass. See [ADR-0014](https://github.com/CarlLee1983/dbcli/blob/main/docs/adr/0014-elasticsearch-reads-are-an-allowlist.md).
+- **Reads are an allowlist; anything else needs `admin`.** Permitted below `admin`: `_search` and `_count` on an index or unscoped, `_doc` / `_source` reads, `_mapping` / `_settings` / `_alias` reads, `_cat/*` (except `_cat/aliases` and `_cat/tasks`), `_cluster/health`, and `GET` / `HEAD` of a bare index name. Writes to one document are the usual tiers. **Everything else — including any endpoint not listed here — requires `admin`**, so `DELETE /<index>`, `DELETE /_all`, `_delete_by_query`, `_update_by_query`, `_reindex`, `_aliases`, `PUT /<index>/_mapping`, `PUT /<index>/_settings`, `_sql`, `_scripts`, `_security`, `_snapshot`, `_nodes` and `_cluster/state` are all refused below it. The list is a floor, not a claim that everything absent from it is dangerous: a missing entry costs you an unnecessary `admin` requirement rather than a bypass. See [ADR-0014](https://github.com/CarlLee1983/dbcli/blob/main/docs/adr/ADR-0014-elasticsearch-reads-are-an-allowlist.md).
 - A path is refused unless it is **byte-identical** to what the URL parser produces — the same parser the request goes through — and the refusal tells you the canonical spelling to write instead. This is what stops a path that reads one way here and routes another way at the server: `#` truncates a path in transit (`POST /_reindex#/_count` reaches Elasticsearch as `POST /_reindex`), and tab, newline and `\` are rewritten too. A document id containing a space or a non-ASCII character must be written percent-encoded; the error message gives you the exact string.
 - A quoted string request body is refused; write the body as JSON. So is a `source=` query parameter — Elasticsearch accepts it in place of a body, where none of the body checks can see it. `_source`, `_source_includes` and `_source_excludes` are unaffected.
 - Blacklisted field names are refused in the query string as well as the body, because the URI-search form names fields directly (`?q=…`, `?sort=…`, `?docvalue_fields=…`). A name matches on any dot component, so `password.keyword` — the multi-field every `text` field gets by default — and `params._source.password` inside a script are both refused.