@xpert-ai/plugin-sdk 3.18.4 → 3.18.6

package/CHANGELOG.md

@@ -1,5 +1,56 @@
 # @xpert-ai/plugin-sdk
 
+## 3.18.6
+
+### Patch Changes
+
+- a8a251d: Support non-tool MCP capabilities, task policies and transport-specific input validation on decorated tool providers. Pass execution-scoped workspace files and Agent feature configuration to middleware business methods and allow existing MCP result envelopes without requiring a new structured output schema.
+
+  Share runtime component fingerprinting across host entry points and include transport input schemas, task policies, resources, resource templates and prompts in update detection.
+
+  Add resource, resource-template and prompt method decorators with inherited method discovery, shared runtime/fingerprint definitions and legacy extension compatibility.
+
+- 983b730: Prepare the Xpert 3.18.6 patch release, including plugin-sdk.
+
+  Extend decorated MCP capabilities and structured knowledge graph runtime contracts.
+  Improve document parsing and scanned-page understanding, semantic FAQ exclusion,
+  manual tags during document import, and per-knowledgebase vector storage selection.
+  Include schema-driven sliders and the scoped database workbench adapter.
+
+  The target platform version is 3.18.6. Verify contracts, plugin-sdk, and xpert-ui
+  all resolve to this version in the release version PR, including changelogs,
+  internal dependency references, and lockfile entries. Publish the separately
+  versioned Runtime Suite source images before creating platform-version aliases.
+
+- Updated dependencies [9a2a2a0]
+- Updated dependencies [089e3ff]
+- Updated dependencies [983b730]
+  - @xpert-ai/contracts@3.18.6
+
+## 3.18.5
+
+### Patch Changes
+
+- 6a51c17: Add a shared knowledge document language hint and bounded, model-free language detection for natural text chunk boundaries. Preserve Auto strategy routing, explicit separators, token limits, and parent-child behavior, and expose the requested and detected languages in chunk previews.
+- 8402f72: Prepare the Xpert 3.18.5 patch release, including plugin-sdk.
+
+  Add knowledge document chunk token limits, question generation, automatic and
+  structure-aware chunking, spreadsheet table metadata, and format-specific scoped
+  parsers with diagnostics. Preserve OCR chunk limits and table context.
+
+  Extend MCP resource reads with scoped workspace files and the requested resource
+  URI, preserve confirmation sessions, and reauthorize queued execution. Add PPTX
+  preview and editing with binary workspace saves and edited downloads.
+
+  The target platform version is 3.18.5. Verify contracts, plugin-sdk, and xpert-ui
+  all resolve to this version in the release version PR, including changelogs,
+  internal dependency references, and lockfile entries.
+
+- Updated dependencies [6a51c17]
+- Updated dependencies [95ec638]
+- Updated dependencies [8402f72]
+  - @xpert-ai/contracts@3.18.5
+
 ## 3.18.4
 
 ### Patch Changes

package/README.md

@@ -67,6 +67,50 @@ export class OrderOperationsTools {
 
 MCP exposure is explicit. Provide strict Zod input/output schemas and return an allowlisted DTO; the host validates the output and maps it to `structuredContent` and a JSON `TextContent` block so clients that only expose text can still read the result. With `resultFormat: 'tool_result'`, image and other content blocks are preserved and the validated structured metadata also receives a JSON text fallback. Invocation context is constructed for every call and must never be cached on the Provider singleton. `getMiddlewareExtensions()` may add Agent-only hooks such as `wrapToolCall`, but business-critical behavior belongs in the method or shared service.
 
+Use the same `@XpertToolProvider` class for every capability:
+
+| Decorator                | Method signature                                                | Result                       |
+| ------------------------ | --------------------------------------------------------------- | ---------------------------- |
+| `@XpertTool`             | `(input, context)`                                              | Tool DTO or content envelope |
+| `@XpertResource`         | `(context: ResourceReadContext)`                                | `McpResourceReadResult`      |
+| `@XpertResourceTemplate` | `(args: Record<string, string>, context: ResourceReadContext)`  | `McpResourceReadResult`      |
+| `@XpertPrompt`           | `(args: Record<string, string>, context: ToolExecutionContext)` | `McpPromptResult`            |
+
+No business base class is required. All four decorators support inherited methods;
+a child override replaces the parent declaration, and an undecorated override
+removes that exposure. The SDK reuses its existing `BuiltinToolset` adapter.
+Resource-only and prompt-only providers are supported. Template and prompt options
+can specify `completionMethod` to bind an instance `McpCompletionHandler`.
+
+```ts
+@XpertResourceTemplate({
+  key: 'project', uriTemplate: 'example://projects/{projectId}',
+  arguments: { projectId: { required: true } }, requiredContext: ['tenant', 'principal']
+})
+readProject(args: Record<string, string>, context: ResourceReadContext) {
+  return this.projects.readResource(args.projectId, context)
+}
+```
+
+Handlers receive the current caller's context and retain their provider `this`.
+Do not cache caller context on a singleton. `getMcpExtensions()` remains a legacy
+compatibility hook; duplicate keys or public URIs/names are rejected when merged
+with decorated declarations. Runtime publication and component fingerprints use
+the same resolved definitions. App bundles remain in provider options.
+
+Use `mcp.task` for the existing MCP task policy and `mcp.inputSchema` for stricter
+transport inputs (for example, requiring project identity that native Workbench
+calls may infer). The MCP adapter validates the shared schema first, then the
+transport schema. The transport schema is advertised to MCP clients. Native
+methods also receive execution-scoped workspace files via `context.host.files`
+and the current Agent feature configuration via `context.xpertFeatures`.
+
+Existing tools without a structured output contract may explicitly select
+`resultFormat: 'tool_result'` and omit `outputSchema`. The SDK still validates the
+content envelope and media blocks, but does not claim to validate business fields
+in `structuredContent`. DTO-format MCP methods continue to require a strict
+output schema, and supplied output schemas retain their validation.
+
 For completed operations, `prepareToolResult(() => project(result), () => minimalReceipt)` defers output mapping to the adapter. The normal path maps and validates once; projection, validation or JSON serialization failures recover a bounded receipt without executing the business method again. Declare `outputSchema: z.union([normalSchema, receiptSchema])`, with strict objects in every branch. The fallback is validated too. Business exceptions thrown before the method returns remain errors. With `tool_result`, both callbacks return the content envelope and the union describes its structured metadata. The MCP protocol still validates the published JSON Schema; custom Zod refinements remain enforced by the SDK. Do not put side effects inside either callback.
 
 For a host-native MCP App, declare each static HTML bundle once in the Provider's `apps` array, then bind a Tool with `mcp.app.resourceKey` and include `app` visibility. The App key must exist in the same Provider and its entry must be a relative `.html` path inside the packaged plugin. The host publishes the bundle as a `ui://` resource; plugins must not create a stdio server or put CSP/credentials in Tool results.

package/data-workbench.cjs.default.js

@@ -0,0 +1 @@
+exports._default = require('./data-workbench.cjs.js').default;

package/data-workbench.cjs.js

@@ -0,0 +1,518 @@
+'use strict';
+
+var _extends = require('./_extends.cjs.js');
+
+const DataSourceRuntimeCapability = Object.freeze({
+    id: 'platform.datasource.workbench',
+    description: 'Scoped database workbench access; credentials remain host-owned.',
+    __type: undefined
+});
+
+const WRITE = new Set([
+    'INSERT',
+    'UPDATE',
+    'DELETE',
+    'CREATE',
+    'ALTER',
+    'DROP',
+    'TRUNCATE',
+    'RENAME'
+]);
+const FORBIDDEN = new Set([
+    'INTO',
+    'OUTFILE',
+    'DUMPFILE',
+    'PROCEDURE',
+    'CALL',
+    'COPY',
+    'LOAD',
+    'EXPORT',
+    'IMPORT',
+    'GRANT',
+    'REVOKE',
+    'LOCK',
+    'UNLOCK',
+    'KILL',
+    'SET',
+    'RESET',
+    'ANALYZE',
+    'VACUUM',
+    'OPTIMIZE',
+    'ATTACH',
+    'DETACH'
+]);
+const SAFE_FUNCTIONS = new Set('ABS ACOS ASIN ATAN ATAN2 AVG CAST CEIL CEILING COALESCE CONCAT CONCAT_WS CONVERT COS COUNT CURDATE CURRENT_DATE CURRENT_TIMESTAMP DATE DATE_ADD DATE_SUB DATE_FORMAT DATEDIFF DAY DAYOFMONTH DAYOFWEEK EXTRACT FLOOR FORMAT GREATEST GROUP_CONCAT IF IFNULL JSON_EXTRACT JSON_LENGTH JSON_UNQUOTE LEAST LEFT LENGTH LN LOG LOWER LPAD LTRIM MAX MD5 MIN MOD MONTH NOW NULLIF POWER RAND REPLACE REVERSE RIGHT ROUND ROW_NUMBER RANK DENSE_RANK LAG LEAD FIRST_VALUE LAST_VALUE LPAD RPAD RTRIM SIGN SIN SQRT STDDEV STDDEV_POP STDDEV_SAMP SUBSTR SUBSTRING SUM TAN TO_CHAR TO_DATE TO_TIMESTAMP TRIM TRUNC UPPER VAR_POP VAR_SAMP VERSION WEEK YEAR DATABASE CURRENT_DATABASE CURRENT_SCHEMA ARRAY_AGG STRING_AGG JSON_AGG JSON_BUILD_OBJECT PG_GET_VIEWDEF'.split(' '));
+const SQL_PARENS = new Set('IN AS EXISTS OVER PARTITION VALUES SELECT WITH AND OR NOT ON USING FILTER GROUPING ROLLUP CUBE DISTINCT EXPLAIN'.split(' '));
+const UNSAFE_FUNCTIONS = /\b(pg_sleep|sleep|benchmark|dblink\w*|lo_\w+|pg_(?:read|write|ls|stat|terminate|cancel|reload|rotate|log|create|drop|promote|switch|backup|replication|advisory)\w*|get_lock|release_lock|load_file|nextval|setval|set_config|http\w*|s3|hdfs|jdbc|mysql|postgresql|file|url)\s*\(/i;
+function splitWorkbenchSql(source) {
+    if (!source.trim() || source.length > 100000 || source.includes('\0')) throw new Error('invalid_sql');
+    const statements = [];
+    let start = 0, index = 0, clean = '';
+    const finish = (end)=>{
+        const text = clean.trim();
+        if (text) {
+            var _text_toUpperCase_match;
+            const words = (_text_toUpperCase_match = text.toUpperCase().match(/[A-Z_][A-Z_0-9]*/g)) != null ? _text_toUpperCase_match : [];
+            const first = words[0];
+            let effect = 'unsupported';
+            if (WRITE.has(first)) effect = 'write';
+            if (first === 'SELECT' || first === 'WITH' || first === 'SHOW' || first === 'DESC' || first === 'DESCRIBE' || first === 'EXPLAIN') {
+                effect = 'read';
+                if (words.some((word, index)=>WRITE.has(word) && !(first === 'SHOW' && index === 1 && word === 'CREATE') || FORBIDDEN.has(word)) || UNSAFE_FUNCTIONS.test(text) || /\bFOR\s+(UPDATE|SHARE)\b/i.test(text) || /:=|\bEXPLAIN\s+ANALYZE\b|@/i.test(text)) effect = 'unsupported';
+                // eslint-disable-next-line no-control-regex -- intentional: reject any non-ASCII/control input
+                if (/[^\x00-\x7f]/.test(text) || /\.\s*[A-Z_][A-Z_0-9]*\s*\(/i.test(text)) effect = 'unsupported';
+                if ([
+                    ...text.matchAll(/([A-Z_][A-Z_0-9]*)\s*\(/gi)
+                ].some((match)=>!SAFE_FUNCTIONS.has(match[1].toUpperCase()) && !SQL_PARENS.has(match[1].toUpperCase()))) effect = 'unsupported';
+                if (first === 'SHOW' && !/^(SHOW\s+(DATABASES|SCHEMAS|CATALOGS|TABLES|FULL\s+TABLES|COLUMNS|FULL\s+COLUMNS|INDEX|INDEXES|KEYS|CREATE\s+TABLE|CREATE\s+VIEW|PARTITIONS|VARIABLES|STATUS|GRANTS))\b/i.test(text)) effect = 'unsupported';
+            }
+            // CREATE/ALTER routines, external resources and privileged SQL are outside this app.
+            if (effect === 'write' && /\b(FUNCTION|PROCEDURE|TRIGGER|USER|ROLE|CATALOG|RESOURCE|SYSTEM|SERVER|EXTENSION|FILE|OUTFILE|DUMPFILE|EXECUTE)\b/i.test(text)) effect = 'unsupported';
+            statements.push({
+                sql: source.slice(start, end).trim(),
+                words,
+                effect
+            });
+        }
+        clean = '';
+        start = end + 1;
+    };
+    while(index < source.length){
+        const c = source[index], next = source[index + 1];
+        if (c === '-' && next === '-' || c === '#') {
+            while(index < source.length && source[index] !== '\n')index++;
+            clean += ' ';
+            continue;
+        }
+        if (c === '/' && next === '*') {
+            if (source[index + 2] === '!') throw new Error('executable_comment_not_supported');
+            const end = source.indexOf('*/', index + 2);
+            if (end < 0) throw new Error('unterminated_comment');
+            index = end + 2;
+            clean += ' ';
+            continue;
+        }
+        if (c === "'" || c === '"' || c === '`') {
+            const quote = c;
+            let closed = false;
+            index++;
+            while(index < source.length){
+                if (source[index] === '\\') throw new Error('use_parameters_for_backslash_literals');
+                if (source[index] === quote) {
+                    if (source[index + 1] === quote) {
+                        index += 2;
+                        continue;
+                    }
+                    index++;
+                    closed = true;
+                    break;
+                }
+                index++;
+            }
+            if (!closed) throw new Error('unterminated_literal');
+            clean += quote === "'" ? ' ? ' : ' identifier ';
+            continue;
+        }
+        if (c === '$') {
+            var _source_slice_match;
+            const tag = (_source_slice_match = source.slice(index).match(/^\$(?:[A-Za-z_][A-Za-z_0-9]*)?\$/)) == null ? void 0 : _source_slice_match[0];
+            if (tag) {
+                const end = source.indexOf(tag, index + tag.length);
+                if (end < 0) throw new Error('unterminated_literal');
+                index = end + tag.length;
+                clean += ' ? ';
+                continue;
+            }
+        }
+        if (c === ';') {
+            finish(index);
+            index++;
+            continue;
+        }
+        clean += c;
+        index++;
+    }
+    finish(source.length);
+    if (!statements.length || statements.length > 50) throw new Error('statement_count_exceeded');
+    return statements;
+}
+function requireReadStatement(sql) {
+    const statements = splitWorkbenchSql(sql);
+    if (statements.length !== 1 || statements[0].effect !== 'read') throw new Error('read_only_violation');
+    return statements[0].sql;
+}
+function quoteDatabaseIdentifier(name, engine) {
+    // eslint-disable-next-line no-control-regex -- intentional: reject control characters in identifiers
+    if (!name || name.length > 256 || /[\0-\x1f]/.test(name)) throw new Error('invalid_identifier');
+    const quote = engine === 'postgres' ? '"' : '`';
+    return quote + name.split(quote).join(quote + quote) + quote;
+}
+
+const number = (value)=>Number(value != null ? value : 0);
+const string = (value)=>value == null ? '' : String(value);
+const cell = (result, row, name)=>row[result.columns.findIndex((column)=>column.name.toLowerCase() === name.toLowerCase())];
+/** One adapter per physical connection. A host session must not share it across users. */ class SqlDatabaseWorkbenchAdapter {
+    quote(name) {
+        return quoteDatabaseIdentifier(name, this.engine);
+    }
+    ref(object) {
+        this.assertLocation(object);
+        var _object_schema, _ref, _object_database;
+        const namespace = this.engine === 'postgres' ? (_ref = (_object_schema = object.schema) != null ? _object_schema : this.initial.schema) != null ? _ref : 'public' : (_object_database = object.database) != null ? _object_database : this.initial.database;
+        if (!namespace) throw new Error('database_required');
+        return `${this.quote(namespace)}.${this.quote(object.name)}`;
+    }
+    assertLocation(location) {
+        if (location.engineCatalog && location.engineCatalog !== 'internal') throw new Error('external_catalog_not_supported');
+        if (this.engine === 'postgres' && location.database && location.database !== this.initial.database) throw new Error('database_requires_new_connection');
+    }
+    async raw(sql, parameters = [], maxRows = 1001, signal, timeoutMs = 30000) {
+        if (this.closed) throw new Error('session_closed');
+        return this.transport.execute(sql, parameters, {
+            maxRows,
+            timeoutMs,
+            signal
+        });
+    }
+    async capabilities() {
+        if (!this.version) {
+            var _result_rows_;
+            const result = await this.raw(this.engine === 'doris' ? 'SELECT @@version_comment AS version' : 'SELECT version() AS version', [], 1);
+            this.version = string((_result_rows_ = result.rows[0]) == null ? void 0 : _result_rows_[0]);
+        }
+        const supported = this.engine !== 'doris' || /(?:^|[^0-9])(?:2\.1|3\.\d+|4\.\d+)(?:[.\s_-]|$)/.test(this.version);
+        return {
+            engine: this.engine,
+            version: this.version,
+            query: true,
+            explain: true,
+            transactions: this.engine !== 'doris',
+            cancel: true,
+            import: supported,
+            writes: supported,
+            nativeReadOnly: this.engine !== 'doris',
+            objectKinds: [
+                'table',
+                'view'
+            ],
+            diagnostics: this.engine === 'doris' ? [
+                ...supported ? [] : [
+                    'doris_version_unverified_writes_disabled'
+                ],
+                'doris_permissions_enforce_read_only',
+                'external_catalog_not_supported',
+                'doris_transactions_not_exposed'
+            ] : []
+        };
+    }
+    async locations() {
+        const result = await this.raw(this.engine === 'postgres' ? "SELECT schema_name AS name FROM information_schema.schemata WHERE schema_name NOT LIKE 'pg_%' AND schema_name <> 'information_schema' ORDER BY schema_name LIMIT 1000" : "SELECT schema_name AS name FROM information_schema.schemata WHERE schema_name NOT IN ('information_schema','performance_schema','mysql','sys') ORDER BY schema_name LIMIT 1000");
+        return result.rows.map((row)=>this.engine === 'postgres' ? {
+                database: this.initial.database,
+                schema: string(row[0])
+            } : _extends._extends({
+                database: string(row[0])
+            }, this.engine === 'doris' ? {
+                engineCatalog: 'internal'
+            } : {}));
+    }
+    async objects(input) {
+        this.assertLocation(input);
+        var _input_page, _input_pageSize;
+        const page = Math.max(1, Math.min((_input_page = input.page) != null ? _input_page : 1, 10000)), pageSize = Math.max(1, Math.min((_input_pageSize = input.pageSize) != null ? _input_pageSize : 100, 1000));
+        var _input_schema, _ref, _input_database;
+        const namespace = this.engine === 'postgres' ? (_ref = (_input_schema = input.schema) != null ? _input_schema : this.initial.schema) != null ? _ref : 'public' : (_input_database = input.database) != null ? _input_database : this.initial.database;
+        if (!namespace) return {
+            items: [],
+            page,
+            pageSize,
+            hasMore: false
+        };
+        const placeholder = (i)=>this.engine === 'postgres' ? `$${i}` : '?';
+        var _input_search;
+        const result = await this.raw(`SELECT table_name, table_type FROM information_schema.tables WHERE table_schema = ${placeholder(1)} AND table_name LIKE ${placeholder(2)} ORDER BY table_name LIMIT ${pageSize + 1} OFFSET ${(page - 1) * pageSize}`, [
+            namespace,
+            `%${(_input_search = input.search) != null ? _input_search : ''}%`
+        ], pageSize + 1);
+        return {
+            items: result.rows.slice(0, pageSize).map((row)=>({
+                    database: input.database,
+                    schema: input.schema,
+                    engineCatalog: input.engineCatalog,
+                    name: string(row[0]),
+                    kind: string(row[1]).includes('VIEW') ? 'view' : 'table'
+                })),
+            page,
+            pageSize,
+            hasMore: result.rows.length > pageSize
+        };
+    }
+    async describe(object) {
+        const reference = this.ref(object);
+        var _object_schema, _ref, _object_database, _ref1;
+        const namespace = this.engine === 'postgres' ? (_ref = (_object_schema = object.schema) != null ? _object_schema : this.initial.schema) != null ? _ref : 'public' : (_ref1 = (_object_database = object.database) != null ? _object_database : this.initial.database) != null ? _ref1 : '';
+        const p = (i)=>this.engine === 'postgres' ? `$${i}` : '?';
+        const metadata = await this.raw(this.engine === 'postgres' ? `SELECT a.attname AS column_name, pg_catalog.format_type(a.atttypid,a.atttypmod) AS data_type, CASE WHEN a.attnotnull THEN 'NO' ELSE 'YES' END AS is_nullable, a.attnum AS ordinal_position, pg_get_expr(d.adbin,d.adrelid) AS column_default FROM pg_catalog.pg_attribute a JOIN pg_catalog.pg_class c ON c.oid=a.attrelid JOIN pg_catalog.pg_namespace n ON n.oid=c.relnamespace LEFT JOIN pg_catalog.pg_attrdef d ON d.adrelid=a.attrelid AND d.adnum=a.attnum WHERE n.nspname=$1 AND c.relname=$2 AND a.attnum>0 AND NOT a.attisdropped ORDER BY a.attnum LIMIT 1000` : `SELECT column_name, column_type AS data_type, is_nullable, ordinal_position, column_default FROM information_schema.columns WHERE table_schema = ${p(1)} AND table_name = ${p(2)} ORDER BY ordinal_position LIMIT 1000`, [
+            namespace,
+            object.name
+        ]);
+        const columns = metadata.rows.map((row, index)=>({
+                id: `c${index}`,
+                name: string(cell(metadata, row, 'column_name')),
+                dataType: string(cell(metadata, row, 'data_type')),
+                nullable: string(cell(metadata, row, 'is_nullable')) === 'YES',
+                ordinal: number(cell(metadata, row, 'ordinal_position')),
+                defaultValue: cell(metadata, row, 'column_default') == null ? null : string(cell(metadata, row, 'column_default'))
+            }));
+        if (!columns.length) throw new Error('object_not_found_or_denied');
+        const keys = [], diagnostics = [];
+        let definition = '', model;
+        if (this.engine === 'postgres') {
+            const result = await this.raw(`SELECT tc.constraint_name, tc.constraint_type, kcu.column_name, kcu.ordinal_position, ccu.table_schema AS foreign_schema, ccu.table_name AS foreign_table, ccu.column_name AS foreign_column FROM information_schema.table_constraints tc JOIN information_schema.key_column_usage kcu ON tc.constraint_catalog=kcu.constraint_catalog AND tc.constraint_schema=kcu.constraint_schema AND tc.constraint_name=kcu.constraint_name LEFT JOIN information_schema.referential_constraints rc ON rc.constraint_catalog=tc.constraint_catalog AND rc.constraint_schema=tc.constraint_schema AND rc.constraint_name=tc.constraint_name LEFT JOIN information_schema.key_column_usage ccu ON ccu.constraint_catalog=rc.unique_constraint_catalog AND ccu.constraint_schema=rc.unique_constraint_schema AND ccu.constraint_name=rc.unique_constraint_name AND ccu.ordinal_position=kcu.position_in_unique_constraint WHERE tc.table_schema=$1 AND tc.table_name=$2 ORDER BY tc.constraint_name,kcu.ordinal_position LIMIT 1000`, [
+                namespace,
+                object.name
+            ]);
+            for (const row of result.rows){
+                const name = string(cell(result, row, 'constraint_name')), kind = string(cell(result, row, 'constraint_type'));
+                let key = keys.find((item)=>item.name === name);
+                if (!key) {
+                    key = {
+                        name,
+                        kind: kind === 'PRIMARY KEY' ? 'primary' : kind === 'FOREIGN KEY' ? 'foreign' : 'unique',
+                        columns: []
+                    };
+                    keys.push(key);
+                }
+                key.columns.push(string(cell(result, row, 'column_name')));
+                if (key.kind === 'foreign') {
+                    var _key;
+                    key.referencedTable = {
+                        schema: string(cell(result, row, 'foreign_schema')),
+                        name: string(cell(result, row, 'foreign_table')),
+                        kind: 'table'
+                    };
+                    var _referencedColumns;
+                    ((_referencedColumns = (_key = key).referencedColumns) != null ? _referencedColumns : _key.referencedColumns = []).push(string(cell(result, row, 'foreign_column')));
+                }
+            }
+            if (object.kind === 'view') {
+                var _source_rows_;
+                const source = await this.raw('SELECT pg_get_viewdef($1::regclass, true) AS definition', [
+                    reference
+                ], 1);
+                definition = `CREATE VIEW ${reference} AS\n${string((_source_rows_ = source.rows[0]) == null ? void 0 : _source_rows_[0])}`;
+            } else {
+                definition = `CREATE TABLE ${reference} (\n${columns.map((column)=>`  ${this.quote(column.name)} ${column.dataType}${column.nullable ? '' : ' NOT NULL'}${column.defaultValue === null ? '' : ` DEFAULT ${column.defaultValue}`}`).join(',\n')}\n);`;
+                diagnostics.push('definition_reconstructed_from_metadata');
+            }
+        } else {
+            var _source_rows_1;
+            const source = await this.raw(`SHOW CREATE ${object.kind === 'view' ? 'VIEW' : 'TABLE'} ${reference}`, [], 1);
+            definition = string((_source_rows_1 = source.rows[0]) == null ? void 0 : _source_rows_1[1]);
+            if (this.engine === 'doris') {
+                const match = definition.match(/\b(UNIQUE|DUPLICATE|AGGREGATE)\s+KEY\s*\(([^)]*)\)/i);
+                model = (match == null ? void 0 : match[1].toUpperCase()) === 'UNIQUE' ? 'unique' : (match == null ? void 0 : match[1].toUpperCase()) === 'DUPLICATE' ? 'duplicate' : (match == null ? void 0 : match[1].toUpperCase()) === 'AGGREGATE' ? 'aggregate' : undefined;
+                if (model === 'unique' && match) keys.push({
+                    name: 'UNIQUE KEY',
+                    kind: 'primary',
+                    columns: [
+                        ...match[2].matchAll(/`((?:``|[^`])+)`/g)
+                    ].map((item)=>item[1].split('``').join('`'))
+                });
+            } else {
+                const index = await this.raw(`SHOW INDEX FROM ${reference}`);
+                for (const row of index.rows){
+                    const name = string(cell(index, row, 'Key_name'));
+                    let key = keys.find((item)=>item.name === name);
+                    if (!key) {
+                        key = {
+                            name,
+                            kind: name === 'PRIMARY' ? 'primary' : number(cell(index, row, 'Non_unique')) === 0 ? 'unique' : 'index',
+                            columns: []
+                        };
+                        keys.push(key);
+                    }
+                    key.columns.push(string(cell(index, row, 'Column_name')));
+                }
+                const foreign = await this.raw('SELECT constraint_name,column_name,referenced_table_schema,referenced_table_name,referenced_column_name FROM information_schema.key_column_usage WHERE table_schema=? AND table_name=? AND referenced_table_name IS NOT NULL ORDER BY constraint_name,ordinal_position LIMIT 1000', [
+                    namespace,
+                    object.name
+                ]);
+                for (const row of foreign.rows){
+                    var _key_referencedColumns;
+                    let key = keys.find((item)=>item.name === string(row[0]));
+                    if (!key) {
+                        key = {
+                            name: string(row[0]),
+                            kind: 'foreign',
+                            columns: [],
+                            referencedTable: {
+                                database: string(row[2]),
+                                name: string(row[3]),
+                                kind: 'table'
+                            },
+                            referencedColumns: []
+                        };
+                        keys.push(key);
+                    }
+                    key.columns.push(string(row[1]));
+                    (_key_referencedColumns = key.referencedColumns) == null ? void 0 : _key_referencedColumns.push(string(row[4]));
+                }
+            }
+        }
+        const editable = (this.engine !== 'doris' || (await this.capabilities()).writes) && object.kind === 'table' && keys.some((key)=>(key.kind === 'primary' || key.kind === 'unique') && key.columns.length > 0 && key.columns.every((name)=>{
+                var _columns_find;
+                return ((_columns_find = columns.find((column)=>column.name === name)) == null ? void 0 : _columns_find.nullable) === false;
+            }));
+        return {
+            object,
+            columns,
+            keys,
+            definition,
+            model,
+            editable,
+            diagnostics
+        };
+    }
+    async query(input, signal) {
+        this.assertLocation(input);
+        if (input.database && input.database !== this.initial.database) throw new Error('database_requires_new_connection');
+        if (input.schema && input.schema !== this.initial.schema) throw new Error('schema_requires_new_connection');
+        if (this.busy) throw new Error('session_busy');
+        if (input.mode === 'read') {
+            requireReadStatement(input.sql);
+        }
+        const statements = splitWorkbenchSql(input.sql);
+        if (statements.length !== 1 || statements[0].effect === 'unsupported') throw new Error('unsupported_statement');
+        var _input_limit, _input_offset;
+        const limit = Math.max(1, Math.min((_input_limit = input.limit) != null ? _input_limit : 100, 1000)), offset = Math.max(0, Math.min((_input_offset = input.offset) != null ? _input_offset : 0, 100000));
+        if (input.mode === 'write' && !(await this.capabilities()).writes) throw new Error('engine_version_writes_unavailable');
+        if (input.mode === 'write' && offset) throw new Error('mutation_cannot_be_paginated');
+        let sql = statements[0].sql;
+        // Wrap a SELECT instead of appending LIMIT after an existing LIMIT or trailing comment.
+        if (input.mode === 'read' && [
+            'SELECT',
+            'WITH'
+        ].includes(statements[0].words[0])) sql = `SELECT * FROM (\n${sql}\n) AS ${this.quote('_db_studio_page')} LIMIT ${limit + 1} OFFSET ${offset}`;
+        else if (offset) throw new Error('statement_cannot_be_paginated');
+        this.busy = true;
+        let readTransaction = false;
+        try {
+            if (input.mode === 'read' && this.engine !== 'doris' && !this.transactionOpen) {
+                await this.raw(this.engine === 'postgres' ? 'BEGIN READ ONLY' : 'START TRANSACTION READ ONLY', [], 1);
+                readTransaction = true;
+            }
+            var _input_timeoutMs;
+            const result = await this.raw(sql, input.parameters, limit + 1, signal, Math.max(1, Math.min((_input_timeoutMs = input.timeoutMs) != null ? _input_timeoutMs : 30000, 120000)));
+            const hasMore = result.rows.length > limit || result.truncated;
+            return _extends._extends({}, result, {
+                rows: result.rows.slice(0, limit),
+                hasMore,
+                truncated: result.truncated
+            });
+        } finally{
+            try {
+                if (readTransaction) {
+                    try {
+                        await this.raw('ROLLBACK', [], 1);
+                    } catch (e) {
+                        await this.close();
+                    }
+                }
+            } finally{
+                this.busy = false;
+            }
+        }
+    }
+    async explain(input, signal) {
+        const sql = requireReadStatement(input.sql);
+        if (!/^(SELECT|WITH)\b/i.test(sql)) throw new Error('explain_requires_select');
+        const prefix = this.engine === 'postgres' ? 'EXPLAIN (FORMAT JSON) ' : this.engine === 'mysql' ? 'EXPLAIN FORMAT=JSON ' : 'EXPLAIN ';
+        return this.query(_extends._extends({}, input, {
+            sql: prefix + sql,
+            mode: 'read'
+        }), signal);
+    }
+    async transaction(action) {
+        if (this.engine === 'doris') throw new Error('transactions_not_supported');
+        if (this.busy) throw new Error('session_busy');
+        if (action === 'begin' && this.transactionOpen) throw new Error('transaction_already_open');
+        if (action !== 'begin' && !this.transactionOpen) throw new Error('transaction_not_open');
+        this.busy = true;
+        try {
+            await this.raw(action.toUpperCase(), [], 1);
+            this.transactionOpen = action === 'begin';
+        } finally{
+            this.busy = false;
+        }
+    }
+    async importRows(input, signal) {
+        this.assertLocation(input);
+        if (this.busy) throw new Error('session_busy');
+        if (!(await this.capabilities()).import) throw new Error('engine_version_import_unavailable');
+        if (new Set(input.columns).size !== input.columns.length) throw new Error('duplicate_import_columns');
+        if (!input.rows.length || input.rows.length > 10000 || !input.columns.length || input.columns.length > 500 || input.rows.some((row)=>row.length !== input.columns.length)) throw new Error('invalid_import_shape');
+        if (this.transport.importRows) {
+            this.busy = true;
+            try {
+                return await this.transport.importRows(input, signal);
+            } finally{
+                this.busy = false;
+            }
+        }
+        if (this.engine === 'doris') throw new Error('stream_load_required');
+        const reference = this.ref(_extends._extends({}, input, {
+            name: input.table,
+            kind: 'table'
+        }));
+        await this.transaction('begin');
+        try {
+            for(let i = 0; i < input.rows.length; i += 100){
+                const batch = input.rows.slice(i, i + 100), values = batch.flat();
+                let n = 0;
+                const placeholders = batch.map((row)=>`(${row.map(()=>this.engine === 'postgres' ? `$${++n}` : '?').join(',')})`).join(',');
+                await this.query({
+                    sql: `INSERT INTO ${reference} (${input.columns.map((name)=>this.quote(name)).join(',')}) VALUES ${placeholders}`,
+                    parameters: values,
+                    mode: 'write'
+                }, signal);
+            }
+            await this.transaction('commit');
+            return {
+                outcome: 'succeeded',
+                loadedRows: input.rows.length,
+                filteredRows: 0,
+                label: input.operationId,
+                diagnostics: []
+            };
+        } catch (error) {
+            try {
+                await this.transaction('rollback');
+            } catch (e) {
+                await this.close();
+            }
+            throw error;
+        }
+    }
+    async cancel() {
+        await this.close();
+    }
+    async close() {
+        this.closed = true;
+        await this.transport.close();
+    }
+    constructor(engine, transport, initial = {}){
+        this.transactionOpen = false;
+        this.busy = false;
+        this.closed = false;
+        this.engine = engine;
+        this.transport = transport;
+        this.initial = initial;
+    }
+}
+
+exports.DataSourceRuntimeCapability = DataSourceRuntimeCapability;
+exports.SqlDatabaseWorkbenchAdapter = SqlDatabaseWorkbenchAdapter;
+exports.quoteDatabaseIdentifier = quoteDatabaseIdentifier;
+exports.requireReadStatement = requireReadStatement;
+exports.splitWorkbenchSql = splitWorkbenchSql;

package/data-workbench.cjs.mjs

@@ -0,0 +1,2 @@
+export * from './data-workbench.cjs.js';
+export { _default as default } from './data-workbench.cjs.default.js';

package/data-workbench.d.ts

@@ -0,0 +1 @@
+export * from "./src/data-workbench";