deepline 0.3.325 → 0.3.327

package/dist/cli/{db-NVO7P4VO.js → db-MNDRYYEX.js}

@@ -1,6 +1,10 @@
 "use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } } function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; }
 
-var _chunkMNKDSR2Jjs = require('./chunk-MNKDSR2J.js');
+var _chunkAID3OYVJjs = require('./chunk-AID3OYVJ.js');
+
+
+
+var _chunk4ZARCCPTjs = require('./chunk-4ZARCCPT.js');
 require('./chunk-LA46MMTL.js');
 
 
@@ -10,10 +14,13 @@ require('./chunk-LA46MMTL.js');
 
 
 
-var _chunkQQ2FG5W3js = require('./chunk-QQ2FG5W3.js');
-require('./chunk-PVDQ55PS.js');
+
+var _chunkUROXKPNDjs = require('./chunk-UROXKPND.js');
+
+
+var _chunkDM3SHV6Ujs = require('./chunk-DM3SHV6U.js');
 require('./chunk-XNYIZMNQ.js');
-require('./chunk-K7FC5IUU.js');
+require('./chunk-3MXRNPBN.js');
 require('./chunk-S6R3OX7B.js');
 
 
@@ -21,26 +28,18 @@ var _chunk7P5AA3SNjs = require('./chunk-7P5AA3SN.js');
 require('./chunk-OG64RBAC.js');
 require('./chunk-COGTRVWW.js');
 
-// src/cli/commands/db.ts
+// src/cli/operations/db-query.ts
 var _fs = require('fs');
 var _path = require('path');
-var CUSTOMER_DB_QUERY_FORMATS = /* @__PURE__ */ new Set(["table", "json", "csv", "markdown"]);
-var CUSTOMER_DB_QUERY_MAX_ROWS = 1e3;
-function parsePositiveInteger(value, flagName) {
-  const parsed = Number.parseInt(value, 10);
-  if (!Number.isFinite(parsed) || parsed <= 0) {
-    throw new Error(`${flagName} must be a positive integer.`);
-  }
-  return parsed;
+
+// src/cli/renderers/db-query.ts
+
+
+function queryIntentLine(operationKey) {
+  return operationKey === void 0 ? "The tool equivalent starts a new SQL execution; it cannot recover this unkeyed operation." : "The tool equivalent recovers this SQL operation through its original key.";
 }
-function parseMaxRows(value) {
-  const parsed = parsePositiveInteger(value, "--max-rows");
-  if (parsed > CUSTOMER_DB_QUERY_MAX_ROWS) {
-    throw new Error(
-      `--max-rows must be ${CUSTOMER_DB_QUERY_MAX_ROWS} or less. Add LIMIT/OFFSET to page larger exports.`
-    );
-  }
-  return parsed;
+function errorMessage(value) {
+  return value instanceof Error ? value.message : String(_nullishCoalesce(value, () => ( "")));
 }
 function formatCell(value) {
   if (value === null || value === void 0) return "";
@@ -48,8 +47,8 @@ function formatCell(value) {
   return text.length > 80 ? `${text.slice(0, 77)}...` : text;
 }
 function tableLines(result) {
-  const rows = _chunkQQ2FG5W3js.dataExportRows.call(void 0, customerDbRows(result));
-  const responseColumns = _chunkQQ2FG5W3js.dataExportColumns.call(void 0, 
+  const rows = _chunkUROXKPNDjs.dataExportRows.call(void 0, customerDbRows(result));
+  const responseColumns = _chunkUROXKPNDjs.dataExportColumns.call(void 0, 
     rows,
     customerDbColumnNames(result)
   );
@@ -95,23 +94,11 @@ function tableLines(result) {
   return lines;
 }
 function customerDbRows(result) {
-  return _chunkQQ2FG5W3js.recordRows.call(void 0, result.rows);
+  return _chunkUROXKPNDjs.recordRows.call(void 0, result.rows);
 }
 function customerDbColumnNames(result) {
   return result.columns.map((column) => column.name).filter(Boolean);
 }
-function errorMessage(value) {
-  return value instanceof Error ? value.message : String(_nullishCoalesce(value, () => ( "")));
-}
-function resolveDbQuerySql(rawSql, readFile = (path) => _fs.readFileSync.call(void 0, path, "utf8")) {
-  const value = rawSql.trim();
-  if (!value.startsWith("@")) return value;
-  const filePath = value.slice(1).trim();
-  if (!filePath) {
-    throw new Error("--sql @file requires a file path after `@`.");
-  }
-  return readFile(_path.resolve.call(void 0, filePath)).trim();
-}
 function collectErrorText(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
     return errorMessage(value);
@@ -129,14 +116,15 @@ function collectErrorText(value) {
   ].filter(Boolean).join("\n");
 }
 function formatDbQueryError(sql, error) {
-  const text = collectErrorText(error);
+  const text = error instanceof _chunkDM3SHV6Ujs.CustomerDbQueryOutcomeUnknownError ? collectErrorText(error.cause) : collectErrorText(error);
   const lower = text.toLowerCase();
   const referencesStorage = /"storage"\.|storage\./i.test(sql);
   const runIdColumnMissing = /column\s+"?run_id"?\s+does not exist/i.test(text) || /run_id.*does not exist/i.test(lower);
   const relationMissing = /relation\s+["']?[^"']*storage[^"']*["']?\s+does not exist/i.test(text) || /42p01/i.test(text);
   if (referencesStorage && relationMissing) {
     return [
-      "Customer DB query failed: the referenced storage table does not exist.",
+      ...error instanceof _chunkDM3SHV6Ujs.CustomerDbQueryOutcomeUnknownError ? [error.message] : [],
+      error instanceof _chunkDM3SHV6Ujs.CustomerDbQueryOutcomeUnknownError ? "The server reported that the referenced storage table does not exist." : "Customer DB query failed: the referenced storage table does not exist.",
       "Play dataset tables are created only when the corresponding ctx.dataset(...).run(...) call executes. Pilot branches, early returns, and runs that fail before the dataset do not create that table.",
       "Use `deepline runs get <run-id> --full --json` to inspect returned dataset handles, then export them with `deepline runs export <run-id> --dataset result.rows --out rows.csv`.",
       `Original error: ${errorMessage(error)}`
@@ -144,6 +132,7 @@ function formatDbQueryError(sql, error) {
   }
   if (referencesStorage && runIdColumnMissing) {
     return [
+      ...error instanceof _chunkDM3SHV6Ujs.CustomerDbQueryOutcomeUnknownError ? [error.message] : [],
       "Customer DB query failed: storage dataset tables use `_run_id`, not `run_id`.",
       "Prefer `deepline runs export <run-id> --dataset result.rows --out rows.csv` unless you are doing deep table debugging.",
       `Original error: ${errorMessage(error)}`
@@ -154,33 +143,11 @@ function formatDbQueryError(sql, error) {
   }
   return errorMessage(error);
 }
-function dbRepairHumanLines(result) {
-  const repair = result.repair;
-  return [
-    "Workspace storage repair completed.",
-    ...repair ? [
-      `Location changed: ${repair.location.changed ? "yes" : "no"}`,
-      `Storage contract: ${repair.storage_contract.current ? "current" : "not ready"}`,
-      `Runtime migration: ${repair.runtime_migration.current ? "current" : "not ready"}`,
-      `Runtime capability probe: ${repair.runtime_capabilities.after.runtime_capabilities_ready ? "passed" : "failed"}`,
-      `Materialized table grants reconciled: ${repair.materialized_tables.repaired_count}`
-    ] : [
-      "Runtime capability probe: unavailable from this server version",
-      `Materialized table grants reconciled: ${result.count}`
-    ],
-    `Runtime role: ${result.connection_grants.runtime_role}`,
-    `Customer DB role: ${result.connection_grants.customer_db_role}`
-  ];
-}
-function dbRepairPlainText(result) {
-  return result.repair ? "Workspace storage repair completed. Runtime capability probe passed.\n" : `Workspace storage repair completed. ${result.count} materialized table grant(s) reconciled; runtime capability probe unavailable.
-`;
-}
 function writeCustomerDbCsv(result, outPath) {
   const resolved = _path.resolve.call(void 0, outPath);
   _fs.writeFileSync.call(void 0, 
     resolved,
-    _chunkQQ2FG5W3js.dataExportCsvString.call(void 0, customerDbRows(result), customerDbColumnNames(result)),
+    _chunkUROXKPNDjs.dataExportCsvString.call(void 0, customerDbRows(result), customerDbColumnNames(result)),
     "utf-8"
   );
   return resolved;
@@ -194,81 +161,51 @@ function dbQueryExportEnvelope(input) {
     row_count_returned: input.result.row_count_returned,
     truncated: input.result.truncated,
     ...input.outPath ? { file: input.outPath, local: { file: input.outPath } } : {},
-    next: { toolEquivalent: input.toolCommand },
+    next: {
+      toolEquivalent: input.toolCommand,
+      executionIntent: input.operationKey === void 0 ? "new_execution" : "recover_original",
+      ...input.operationKey === void 0 ? {} : { recoverOperation: input.toolCommand }
+    },
     render: {
       sections: [
         {
           title: "customer db export",
           lines: [
-            `Rendered ${input.result.row_count_returned} row(s) as ${input.format} to ${destination}`
+            `Rendered ${input.result.row_count_returned} row(s) as ${input.format} to ${destination}`,
+            queryIntentLine(input.operationKey)
           ]
         }
       ],
-      actions: [{ label: "Tool equivalent", command: input.toolCommand }]
+      actions: [
+        {
+          label: "Tool equivalent",
+          command: input.toolCommand
+        }
+      ]
     }
   };
 }
-async function handleDbQuery(args) {
-  const sqlIndex = args.indexOf("--sql");
-  const rawSql = sqlIndex >= 0 ? _optionalChain([args, 'access', _ => _[sqlIndex + 1], 'optionalAccess', _2 => _2.trim, 'call', _3 => _3()]) : "";
-  if (!rawSql) {
-    console.error(
-      'Usage: deepline db query --sql "select * from table limit 20"|@query.sql [--max-rows N] [--json]'
-    );
-    return 1;
-  }
-  let sql;
-  try {
-    sql = resolveDbQuerySql(rawSql);
-  } catch (error) {
-    console.error(errorMessage(error));
-    return 1;
-  }
-  if (!sql) {
-    console.error("SQL file is empty.");
-    return 1;
-  }
-  const maxRowsIndex = args.indexOf("--max-rows");
-  const maxRows = maxRowsIndex >= 0 && args[maxRowsIndex + 1] ? parseMaxRows(args[maxRowsIndex + 1]) : void 0;
-  const formatIndex = args.indexOf("--format");
-  const format = formatIndex >= 0 ? _optionalChain([args, 'access', _4 => _4[formatIndex + 1], 'optionalAccess', _5 => _5.trim, 'call', _6 => _6(), 'access', _7 => _7.toLowerCase, 'call', _8 => _8()]) : "";
-  if (format && !CUSTOMER_DB_QUERY_FORMATS.has(format)) {
-    console.error(
-      'Usage: deepline db query --sql "select * from table limit 20" [--format table|json|csv|markdown] [--out path]'
-    );
-    return 1;
-  }
-  const outIndex = args.indexOf("--out");
-  const outPath = outIndex >= 0 ? _optionalChain([args, 'access', _9 => _9[outIndex + 1], 'optionalAccess', _10 => _10.trim, 'call', _11 => _11()]) : "";
-  if (outIndex >= 0 && !outPath) {
-    console.error("--out requires a path.");
-    return 1;
-  }
-  const jsonOutput = _chunkQQ2FG5W3js.argsWantJson.call(void 0, args);
-  const explicitJsonOutput = args.includes("--json");
-  const client = new (0, _chunkMNKDSR2Jjs.DeeplineClient)();
-  let result;
-  try {
-    result = await client.db.query({ sql, maxRows });
-  } catch (error) {
-    console.error(formatDbQueryError(sql, error));
-    return 1;
-  }
-  const toolCommand = `deepline tools execute query_customer_db --payload ${JSON.stringify(
-    {
-      sql,
-      ...maxRows ? { max_rows: maxRows } : {}
-    }
-  )} --json`;
+function renderDbQueryResult(result, query, options) {
+  const { sql, maxRows, operationKey } = query;
+  const { format, out: outPath, json: explicitJsonOutput = false } = options;
+  const jsonOutput = explicitJsonOutput || _chunkUROXKPNDjs.shouldEmitJson.call(void 0, );
+  const toolPayload = JSON.stringify({
+    sql,
+    result_mode: "rows",
+    ...maxRows ? { max_rows: maxRows } : {},
+    ...operationKey !== void 0 ? { operation_key: operationKey } : {}
+  });
+  const toolCommand = `deepline tools execute query_customer_db --payload ${_chunkAID3OYVJjs.shellQuote.call(void 0, toolPayload)} --json`;
   if (format === "csv") {
     if (outPath) {
       const exportedPath = writeCustomerDbCsv(result, outPath);
-      _chunkQQ2FG5W3js.printCommandEnvelope.call(void 0, 
+      _chunkUROXKPNDjs.printCommandEnvelope.call(void 0, 
         dbQueryExportEnvelope({
           result,
           format,
           outPath: exportedPath,
-          toolCommand
+          toolCommand,
+          operationKey
         }),
         {
           json: jsonOutput,
@@ -276,39 +213,41 @@ async function handleDbQuery(args) {
 `
         }
       );
-      return 0;
+      return;
     }
-    _chunkQQ2FG5W3js.printCommandEnvelope.call(void 0, 
+    _chunkUROXKPNDjs.printCommandEnvelope.call(void 0, 
       dbQueryExportEnvelope({
         result,
         format,
         outPath: null,
-        toolCommand
+        toolCommand,
+        operationKey
       }),
       {
         json: explicitJsonOutput,
-        text: _chunkQQ2FG5W3js.dataExportCsvString.call(void 0, 
+        text: _chunkUROXKPNDjs.dataExportCsvString.call(void 0, 
           customerDbRows(result),
           customerDbColumnNames(result)
         )
       }
     );
-    return 0;
+    return;
   }
   if (format === "markdown") {
-    const content = _chunkQQ2FG5W3js.markdownTableFromRows.call(void 0, 
+    const content = _chunkUROXKPNDjs.markdownTableFromRows.call(void 0, 
       customerDbRows(result),
       customerDbColumnNames(result)
     );
     if (outPath) {
       const exportedPath = _path.resolve.call(void 0, outPath);
       _fs.writeFileSync.call(void 0, exportedPath, content, "utf-8");
-      _chunkQQ2FG5W3js.printCommandEnvelope.call(void 0, 
+      _chunkUROXKPNDjs.printCommandEnvelope.call(void 0, 
         dbQueryExportEnvelope({
           result,
           format,
           outPath: exportedPath,
-          toolCommand
+          toolCommand,
+          operationKey
         }),
         {
           json: jsonOutput,
@@ -316,42 +255,176 @@ async function handleDbQuery(args) {
 `
         }
       );
-      return 0;
+      return;
     }
-    _chunkQQ2FG5W3js.printCommandEnvelope.call(void 0, 
+    _chunkUROXKPNDjs.printCommandEnvelope.call(void 0, 
       dbQueryExportEnvelope({
         result,
         format,
         outPath: null,
-        toolCommand
+        toolCommand,
+        operationKey
       }),
       {
         json: explicitJsonOutput,
         text: content
       }
     );
-    return 0;
+    return;
   }
-  _chunkQQ2FG5W3js.printCommandEnvelope.call(void 0, 
+  _chunkUROXKPNDjs.printCommandEnvelope.call(void 0, 
     {
       ...result,
-      next: { toolEquivalent: toolCommand },
+      next: {
+        toolEquivalent: toolCommand,
+        executionIntent: operationKey === void 0 ? "new_execution" : "recover_original",
+        ...operationKey === void 0 ? {} : { recoverOperation: toolCommand }
+      },
       render: {
-        sections: [{ title: "customer db query", lines: tableLines(result) }],
-        actions: [{ label: "Tool equivalent", command: toolCommand }]
+        sections: [
+          {
+            title: "customer db query",
+            lines: [...tableLines(result), queryIntentLine(operationKey)]
+          }
+        ],
+        actions: [
+          {
+            label: "Tool equivalent",
+            command: toolCommand
+          }
+        ]
       }
     },
     {
       json: explicitJsonOutput || format === "json" || format !== "table" && jsonOutput
     }
   );
-  return 0;
+  return;
+}
+
+// src/cli/operations/db-query.ts
+function resolveDbQuerySql(rawSql, readFile = (path) => _fs.readFileSync.call(void 0, path, "utf8")) {
+  const value = rawSql.trim();
+  if (!value.startsWith("@")) return value;
+  const filePath = value.slice(1).trim();
+  if (!filePath) {
+    throw new Error("--sql @file requires a file path after `@`.");
+  }
+  return readFile(_path.resolve.call(void 0, filePath)).trim();
+}
+async function runDbQueryCommand(options) {
+  let sql = "";
+  try {
+    sql = resolveDbQuerySql(options.sql);
+    if (!sql) throw new Error("SQL file is empty.");
+    const maxRows = options.maxRows === void 0 ? void 0 : Number(options.maxRows);
+    if (maxRows !== void 0 && maxRows > 1e3)
+      throw new Error(
+        "--max-rows must be 1000 or less. Add LIMIT/OFFSET to page larger exports."
+      );
+    if (maxRows !== void 0 && (!Number.isSafeInteger(maxRows) || maxRows < 1)) {
+      throw new Error(
+        "--max-rows must be a positive whole number of 1000 or less. Add LIMIT/OFFSET to page larger exports."
+      );
+    }
+    const operationKey = options.operationKey;
+    if (operationKey !== void 0 && (!operationKey.trim() || operationKey.length > 512)) {
+      throw new Error(
+        "--operation-key requires a non-empty intended-operation key of at most 512 characters."
+      );
+    }
+    const format = _optionalChain([options, 'access', _ => _.format, 'optionalAccess', _2 => _2.trim, 'call', _3 => _3(), 'access', _4 => _4.toLowerCase, 'call', _5 => _5()]);
+    if (format !== void 0 && !["table", "json", "csv", "markdown"].includes(format)) {
+      throw new Error("--format must be table, json, csv, or markdown.");
+    }
+    const out = _optionalChain([options, 'access', _6 => _6.out, 'optionalAccess', _7 => _7.trim, 'call', _8 => _8()]);
+    if (out !== void 0 && !out) throw new Error("--out requires a path.");
+    if (out !== void 0 && format !== "csv" && format !== "markdown")
+      throw new Error("--out requires --format csv or --format markdown.");
+    const query = {
+      sql,
+      ...maxRows === void 0 ? {} : { maxRows },
+      ...operationKey === void 0 ? {} : { operationKey }
+    };
+    const plan = _chunk4ZARCCPTjs.planCustomerDbQuery.call(void 0, query);
+    if (options.dryRun) {
+      _chunkUROXKPNDjs.printCommandEnvelope.call(void 0, 
+        {
+          dryRun: true,
+          ...plan,
+          effects: {
+            ...plan.effects,
+            localWrites: out === void 0 ? "none" : "export_file"
+          },
+          output: {
+            format: _nullishCoalesce(format, () => ( "automatic")),
+            ...out === void 0 ? {} : { file: _path.resolve.call(void 0, out) }
+          }
+        },
+        { json: options.json || _chunkUROXKPNDjs.shouldEmitJson.call(void 0, ) }
+      );
+      return 0;
+    }
+    const client = new (0, _chunk4ZARCCPTjs.DeeplineClient)();
+    const result = await client.db.query(query);
+    renderDbQueryResult(result, query, {
+      format,
+      out,
+      json: options.json
+    });
+    return 0;
+  } catch (error) {
+    if (error instanceof _chunkDM3SHV6Ujs.CustomerDbQueryOutcomeUnknownError && (options.json || _chunkUROXKPNDjs.shouldEmitJson.call(void 0, ))) {
+      _chunkUROXKPNDjs.printCommandEnvelope.call(void 0, 
+        {
+          ok: false,
+          error: {
+            code: error.code,
+            message: error.message,
+            outcome: error.outcome,
+            retryable: error.retryable,
+            ...error.operationKey === void 0 ? {} : { operationKey: error.operationKey }
+          }
+        },
+        { json: true }
+      );
+    }
+    console.error(formatDbQueryError(sql, error));
+    return 1;
+  }
+}
+
+// src/cli/commands/db.ts
+function errorMessage2(value) {
+  return value instanceof Error ? value.message : String(_nullishCoalesce(value, () => ( "")));
+}
+function dbRepairHumanLines(result) {
+  const repair = result.repair;
+  return [
+    "Workspace storage repair completed.",
+    ...repair ? [
+      `Location changed: ${repair.location.changed ? "yes" : "no"}`,
+      `Storage contract: ${repair.storage_contract.current ? "current" : "not ready"}`,
+      `Runtime migration: ${repair.runtime_migration.current ? "current" : "not ready"}`,
+      `Runtime capability probe: ${repair.runtime_capabilities.after.runtime_capabilities_ready ? "passed" : "failed"}`,
+      `Materialized table grants reconciled: ${repair.materialized_tables.repaired_count}`
+    ] : [
+      "Runtime capability probe: unavailable from this server version",
+      `Materialized table grants reconciled: ${result.count}`
+    ],
+    `Runtime role: ${result.connection_grants.runtime_role}`,
+    `Customer DB role: ${result.connection_grants.customer_db_role}`
+  ];
+}
+function dbRepairPlainText(result) {
+  return result.repair ? "Workspace storage repair completed. Runtime capability probe passed.\n" : `Workspace storage repair completed. ${result.count} materialized table grant(s) reconciled; runtime capability probe unavailable.
+`;
 }
 async function handleDbRepair(args) {
   const providerIndex = args.indexOf("--provider");
-  const provider = providerIndex >= 0 ? _optionalChain([args, 'access', _12 => _12[providerIndex + 1], 'optionalAccess', _13 => _13.trim, 'call', _14 => _14()]) : void 0;
-  const jsonOutput = _chunkQQ2FG5W3js.argsWantJson.call(void 0, args);
-  const client = new (0, _chunkMNKDSR2Jjs.DeeplineClient)();
+  const provider = providerIndex >= 0 ? _optionalChain([args, 'access', _9 => _9[providerIndex + 1], 'optionalAccess', _10 => _10.trim, 'call', _11 => _11()]) : void 0;
+  const jsonOutput = _chunkUROXKPNDjs.argsWantJson.call(void 0, args);
+  const client = new (0, _chunk4ZARCCPTjs.DeeplineClient)();
   let result;
   try {
     result = await client.repairIngestionStorage(
@@ -364,10 +437,10 @@ async function handleDbRepair(args) {
       );
       return 1;
     }
-    console.error(errorMessage(error));
+    console.error(errorMessage2(error));
     return 1;
   }
-  _chunkQQ2FG5W3js.printCommandEnvelope.call(void 0, 
+  _chunkUROXKPNDjs.printCommandEnvelope.call(void 0, 
     {
       command: "db repair",
       status: result.status,
@@ -427,6 +500,11 @@ Examples:
   CREATE TABLE storage.blocked (...) instead of CREATE TABLE blocked (...).
   --format csv and --format markdown are explicit data/display formats and can
   be written directly with --out.
+  Effects: SQL may mutate customer storage; --out writes one local export. SQL does not spend credits.
+  SQL is attempted once, without automatic retries or URL failover. A lost response means unknown outcome.
+  For recoverable writes, choose --operation-key before execution. Recover with the original key,
+  SQL and options; a new key starts a new operation. A key added afterward cannot recover unkeyed SQL.
+  --dry-run shows this plan without executing SQL, exporting data, or maintaining the installation.
 
 Examples:
   deepline db query --sql "select * from companies limit 20"
@@ -437,18 +515,17 @@ Examples:
   deepline db query --sql "select * from contacts limit 20" --format csv --out contacts.csv
   deepline db query --sql "select domain, name from companies limit 20" --format markdown
 `
-  ).requiredOption("--sql <sql>", "SQL statement").option("--max-rows <n>", "Maximum returned rows").option("--format <format>", "Output format: table, json, csv, or markdown").option("--out <path>", "Write csv or markdown output to a file").option(
+  ).requiredOption("--sql <sql>", "SQL statement").option(
+    "--dry-run",
+    "Describe the request, effects and recovery without executing SQL or writing an export"
+  ).option("--max-rows <n>", "Maximum returned rows").option(
+    "--operation-key <key>",
+    "Recover this intended transactional SQL operation; separate intentions need separate keys"
+  ).option("--format <format>", "Output format: table, json, csv, or markdown").option("--out <path>", "Write csv or markdown output to a file").option(
     "--json",
     "Emit raw JSON response. Also automatic when stdout is piped"
   ).action(async (options) => {
-    process.exitCode = await handleDbQuery([
-      "--sql",
-      options.sql,
-      ...options.maxRows ? ["--max-rows", options.maxRows] : [],
-      ...options.format ? ["--format", options.format] : [],
-      ...options.out ? ["--out", options.out] : [],
-      ...options.json ? ["--json"] : []
-    ]);
+    process.exitCode = await runDbQueryCommand(options);
   });
   db.command("repair").description(
     "Repair this workspace storage contract (role/DB grants). Org admin only."

package/dist/cli/{describe-26OMF3A4.mjs → describe-KJWOHMKC.mjs}

@@ -2,10 +2,10 @@ import {
   describedTool,
   publicToolSchemas,
   toolMetadataJsonForDescribe
-} from "./chunk-H5TJBRSC.mjs";
+} from "./chunk-HOWQKN6J.mjs";
 import {
   describedPlay
-} from "./chunk-7MD453WV.mjs";
+} from "./chunk-ZOFARJWH.mjs";
 import {
   SCHEMA_LINE_LIMIT,
   addDescribeOptions,
@@ -13,26 +13,27 @@ import {
   examples,
   schemaLines,
   topLevelField
-} from "./chunk-76VKBPOC.mjs";
+} from "./chunk-JOA6IKDE.mjs";
+import "./chunk-OVDNJAJN.mjs";
 import "./chunk-EDWJY6T4.mjs";
-import "./chunk-OPERWJR6.mjs";
-import "./chunk-6VZDSBK6.mjs";
+import "./chunk-D6GD5AVN.mjs";
+import "./chunk-REP2MYBI.mjs";
 import "./chunk-MIMASXO4.mjs";
-import "./chunk-OWJZUE3Y.mjs";
+import "./chunk-GVESPYSY.mjs";
 import {
   DeeplineClient
-} from "./chunk-XIVUB36F.mjs";
+} from "./chunk-QZAP5VOS.mjs";
 import "./chunk-CBVIJSHF.mjs";
 import "./chunk-WXLOW623.mjs";
 import "./chunk-UFS752TU.mjs";
 import "./chunk-GAMFK2ZP.mjs";
 import {
   printCommandEnvelope
-} from "./chunk-AQUNQJ5Y.mjs";
-import "./chunk-YE3O2UHM.mjs";
+} from "./chunk-F45425TB.mjs";
+import "./chunk-CCRQ2VGJ.mjs";
 import "./chunk-DLIRSHV6.mjs";
-import "./chunk-NWBARG3F.mjs";
-import "./chunk-7PZFGB7L.mjs";
+import "./chunk-G5774EFF.mjs";
+import "./chunk-YIY74KUF.mjs";
 import "./chunk-H7HIDGZ7.mjs";
 import "./chunk-KP7W5NO6.mjs";
 import "./chunk-6IKARAYD.mjs";