@rex0220/kintone-sql-tools 3.28.0 → 3.29.0

package/README.md

@@ -7,8 +7,14 @@ kintone アプリを SQL 風の構文で操作するツールセットです。
 - MCP サーバー（AI クライアントから kintone を SQL 操作。Claude Desktop 用 MCPB 同梱）
 - read-only エンジン・ライブラリ（ESM / CJS / UMD）
 
-他の kintone プラグインやカスタマイズへ read-only kSQL エンジンを組み込む場合は、
-[エンジン・ライブラリ利用ガイド](docs/ksql_engine_library.md)を参照してください。
+他の kintone プラグインやカスタマイズへ read-only kSQL エンジンを組み込む場合は、
+[エンジン・ライブラリ利用ガイド](docs/ksql_engine_library.md)を参照してください。
+
+engine ライブラリでは、`runQuery()` が単文の `SELECT` / `WITH` / `UNION` /
+`SHOW APPS` / `DESCRIBE` / 既存レコード `VALIDATE` を、`runBatch()` がそれらに加えて
+`CREATE` / `DROP TEMP TABLE`、`SET` / `DECLARE`、`ASSERT`、`EXPLAIN` を実行します。
+書き込み DML、DML `VALIDATE ONLY`、`IMPORT`、`APPLY` は対象外です。
+生成 AI が MCP で作った SQL を library で実行する場合は、この API 別の境界を確認してください。
 
 ## 機能概要
 

package/dist-cli/ksql.js

@@ -16158,21 +16158,28 @@ async function runWithDeadline(work, remainingMs, onTimeout) {
   }
 }
 function toBatchStatementError(e) {
+  let error;
   if (e instanceof ApplyWritePartialFailureError) {
-    return { code: e.name, message: e.message, partialSuccess: e.partialSuccess };
-  }
-  if (e instanceof Error) {
+    error = { code: e.name, message: e.message, partialSuccess: e.partialSuccess };
+  } else if (e instanceof Error) {
     const name = e.name !== "Error" ? e.name : null;
-    return { code: name ?? codeFromMessagePrefix(e.message), message: e.message };
-  }
-  if (e !== null && typeof e === "object") {
+    error = { code: name ?? codeFromMessagePrefix(e.message), message: e.message };
+  } else if (e !== null && typeof e === "object") {
     const obj = e;
-    const message2 = typeof obj.message === "string" && obj.message.length > 0 ? obj.message : safeJsonStringify(e);
-    const code = typeof obj.code === "string" && obj.code.length > 0 ? obj.code : codeFromMessagePrefix(message2);
-    return { code, message: message2 };
+    const message = typeof obj.message === "string" && obj.message.length > 0 ? obj.message : safeJsonStringify(e);
+    const code = typeof obj.code === "string" && obj.code.length > 0 ? obj.code : codeFromMessagePrefix(message);
+    error = { code, message };
+  } else {
+    const message = String(e);
+    error = { code: codeFromMessagePrefix(message), message };
   }
-  const message = String(e);
-  return { code: codeFromMessagePrefix(message), message };
+  Object.defineProperty(error, "cause", {
+    value: e,
+    enumerable: false,
+    configurable: false,
+    writable: false
+  });
+  return error;
 }
 function codeFromMessagePrefix(message) {
   return message.match(/^([A-Za-z]+Error):/)?.[1] ?? "Error";

package/dist-engine/batch.d.ts

@@ -0,0 +1,13 @@
+import type { BatchResult, RunBatchOptions } from "./publicTypes";
+/**
+ * Executes a read-only multi-statement batch.
+ *
+ * In addition to the row-returning statements accepted by runQuery, this API
+ * accepts CREATE/DROP TEMP TABLE, SET, DECLARE, ASSERT, and EXPLAIN. IMPORT,
+ * APPLY, DML VALIDATE ONLY, and writing DML remain outside the library boundary.
+ *
+ * If any statement fails, this function throws KsqlEngineError without
+ * returning partial results. statementIndex and statementType identify the
+ * failed statement.
+ */
+export declare function runBatch(sql: string, options: RunBatchOptions): Promise<BatchResult>;

package/dist-engine/errors.d.ts

@@ -1,8 +1,13 @@
 export declare class KsqlEngineError extends Error {
     readonly code: "PARSE_ERROR" | "READ_ONLY_VIOLATION" | "SEARCH_ABORTED" | "FETCH_LIMIT_EXCEEDED" | "CLIENT_ERROR" | "EXECUTION_ERROR";
     readonly cause?: unknown;
+    /** Zero-based index of the failed statement when raised by runBatch. */
+    readonly statementIndex?: number;
+    /** Parser statement type of the failed statement when raised by runBatch. */
+    readonly statementType?: string;
     constructor(code: KsqlEngineError["code"], message: string, cause?: unknown);
 }
+export declare function withStatementDiagnostic(error: KsqlEngineError, statementIndex: number, statementType: string): KsqlEngineError;
 export declare function readOnlyViolation(message: string): KsqlEngineError;
 export declare function parseError(message: string, cause?: unknown): KsqlEngineError;
 export declare function searchAborted(): KsqlEngineError;