@oxygen-agent/cli 1.1014.985 → 1.1014.1087

package/dist/command-families/tables/bundle-export.js

@@ -0,0 +1,198 @@
+import { readPositiveInt, readRecordString } from "../../cli-values.js";
+import { normalizeExportRowsFormat, formatRows } from "../../command-support.js";
+import { requestOxygen } from "../../http-client.js";
+import { OxygenError } from "@oxygen/shared/cli-result";
+import { writeFileSync, createWriteStream, renameSync, unlinkSync } from "node:fs";
+import { resolve } from "node:path";
+import { TABLE_BUNDLE_DEFAULT_PAGE_SIZE, TABLE_BUNDLE_LEGACY_SCHEMA_VERSION, TABLE_BUNDLE_MAX_PAGE_SIZE, TABLE_BUNDLE_SCHEMA_VERSION, readBundleNumber } from "./bundle-format.js";
+import { toBundleColumn } from "./bundle-import.js";
+import { tableWebUrl } from "./import-values.js";
+export async function exportRows(table, options) {
+    const format = normalizeExportRowsFormat(options.format);
+    const limit = readPositiveInt(options.limit);
+    const result = await requestOxygen("/api/cli/tables/query", {
+        method: "POST",
+        body: {
+            table,
+            ...(limit ? { limit } : {}),
+        },
+    });
+    const formatted = formatRows(result.rows, format, result.columns);
+    if (options.output) {
+        writeFileSync(options.output, formatted.content);
+    }
+    return {
+        table: result.table ?? null,
+        format,
+        rowCount: result.rows.length,
+        output: options.output ?? null,
+        ...(options.output ? {} : { content: formatted.content }),
+        ...(formatted.rescuedCount > 0 ? { rescuedNumericCells: formatted.rescuedCount } : {}),
+    };
+}
+// skipcq: JS-R1005 — intentional branching across describe/query pagination, column-definition normalization, and output sink (stdout/file)
+export async function exportTableBundle(table, options) {
+    const pageSize = Math.min(readPositiveInt(options.pageSize) ?? TABLE_BUNDLE_DEFAULT_PAGE_SIZE, TABLE_BUNDLE_MAX_PAGE_SIZE);
+    // Pull the canonical schema (incl. enrichment/tool definitions and
+    // semantic types) from `describe`; the paginated query response only
+    // surfaces the user-visible projection.
+    const describe = await requestOxygen("/api/cli/tables/describe", { method: "POST", body: { table } });
+    const tableMeta = describe.table ?? null;
+    const columns = (describe.columns ?? []).map(toBundleColumn);
+    const tableId = readRecordString(tableMeta, "id");
+    const tableSlug = readRecordString(tableMeta, "slug");
+    const projectSlug = readRecordString(tableMeta, "projectSlug");
+    const tableSummary = {
+        id: tableId ?? null,
+        slug: tableSlug ?? null,
+        name: readRecordString(tableMeta, "displayName") ?? readRecordString(tableMeta, "name") ?? null,
+        projectSlug: projectSlug ?? null,
+    };
+    const exportedAt = new Date().toISOString();
+    // With --output the bundle streams to disk one row per line, so memory stays
+    // flat however many rows the table has. The file is written under a .partial
+    // name and renamed only after the totals trailer lands, so an interrupted
+    // export can never be mistaken for a complete bundle.
+    const outputPath = options.output ? resolve(options.output) : null;
+    const partialPath = outputPath ? `${outputPath}.partial` : null;
+    const stream = partialPath ? createWriteStream(partialPath, { encoding: "utf8" }) : null;
+    const rows = [];
+    let cursor = null;
+    let expectedTotal = null;
+    let pageCount = 0;
+    let rowCount = 0;
+    let hasMoreFlag = false;
+    try {
+        if (stream) {
+            await writeBundleLine(stream, JSON.stringify({
+                schemaVersion: TABLE_BUNDLE_SCHEMA_VERSION,
+                exportedAt,
+                table: tableSummary,
+                columns,
+            }));
+        }
+        do {
+            const requestBody = { table, limit: pageSize };
+            if (cursor)
+                requestBody.cursor = cursor;
+            const page = await requestOxygen("/api/cli/tables/query", { method: "POST", body: requestBody });
+            pageCount += 1;
+            if (expectedTotal === null) {
+                expectedTotal = readBundleNumber(page.totalCount) ?? readBundleNumber(page.total_count) ?? null;
+            }
+            for (const row of page.rows ?? []) {
+                rowCount += 1;
+                if (stream)
+                    await writeBundleLine(stream, JSON.stringify({ row }));
+                else
+                    rows.push(row);
+            }
+            cursor = typeof page.nextCursor === "string" && page.nextCursor.length > 0 ? page.nextCursor : null;
+            hasMoreFlag = Boolean(page.hasMore);
+            // Defensive: hasMore=false should always mean cursor=null. If a future
+            // server change ever sets one without the other, stop iterating on
+            // hasMore=false so we don't loop forever.
+            if (!hasMoreFlag)
+                cursor = null;
+        } while (cursor);
+        if (expectedTotal !== null && rowCount !== expectedTotal) {
+            throw new OxygenError("bundle_export_incomplete", "Cursor pagination ended before every row was written. The bundle would be a silent under-export.", {
+                details: {
+                    table,
+                    totalCount: expectedTotal,
+                    exportedCount: rowCount,
+                    missing: expectedTotal - rowCount,
+                    pages: pageCount,
+                },
+                exitCode: 1,
+            });
+        }
+        const totals = {
+            rowCount,
+            ...(expectedTotal !== null ? { sourceTotalCount: expectedTotal } : {}),
+            pages: pageCount,
+            pageSize,
+        };
+        if (stream && partialPath && outputPath) {
+            await writeBundleLine(stream, JSON.stringify({ totals }));
+            await finishBundleStream(stream);
+            renameSync(partialPath, outputPath);
+        }
+        const summary = {
+            table_id: tableId ?? null,
+            table_slug: tableSlug ?? null,
+            schema_version: stream ? TABLE_BUNDLE_SCHEMA_VERSION : TABLE_BUNDLE_LEGACY_SCHEMA_VERSION,
+            format: stream ? "jsonl" : "json",
+            column_count: columns.length,
+            row_count: rowCount,
+            pages: pageCount,
+            page_size: pageSize,
+            output: options.output ?? null,
+            ...(tableId ? { web_url: tableWebUrl(tableId) } : tableSlug ? { web_url: tableWebUrl(tableSlug) } : {}),
+        };
+        // With --output, the file is the source of truth; keep the stdout response
+        // a small summary so it's readable.
+        if (stream)
+            return summary;
+        // When piping to stdout, emit the full single-document bundle so it can be
+        // redirected into a file. That document has to fit in one string, so say
+        // so — with the fix — instead of dying on a bare RangeError.
+        const bundle = {
+            schemaVersion: TABLE_BUNDLE_LEGACY_SCHEMA_VERSION,
+            exportedAt,
+            table: tableSummary,
+            columns,
+            rows,
+            totals,
+        };
+        assertBundleSerializable(bundle, rowCount);
+        return { ...summary, bundle };
+    }
+    catch (error) {
+        if (stream) {
+            stream.destroy();
+            if (partialPath) {
+                try {
+                    unlinkSync(partialPath);
+                }
+                catch {
+                    // The partial file may never have been created; nothing to clean.
+                }
+            }
+        }
+        throw error;
+    }
+}
+// Writes one bundle line and honors the stream's backpressure, so a 50k-row
+// export never accumulates the file in memory while the disk catches up.
+export function writeBundleLine(stream, line) {
+    return new Promise((resolveLine, rejectLine) => {
+        const onError = (error) => rejectLine(error);
+        if (stream.write(`${line}\n`, "utf8")) {
+            resolveLine();
+            return;
+        }
+        stream.once("error", onError);
+        stream.once("drain", () => {
+            stream.off("error", onError);
+            resolveLine();
+        });
+    });
+}
+export function finishBundleStream(stream) {
+    return new Promise((resolveStream, rejectStream) => {
+        stream.once("error", rejectStream);
+        stream.end(() => resolveStream());
+    });
+}
+export function assertBundleSerializable(bundle, rowCount) {
+    try {
+        JSON.stringify(bundle);
+    }
+    catch (error) {
+        if (error instanceof RangeError) {
+            throw new OxygenError("bundle_too_large", `This table's ${rowCount} rows do not fit in one JSON document. Re-run with --output <path>: the bundle then streams to the file one row per line, with no size limit.`, { details: { row_count: rowCount }, exitCode: 1 });
+        }
+        throw error;
+    }
+}

package/dist/command-families/tables/bundle-format.d.ts

@@ -0,0 +1,66 @@
+import { QueryColumnDescriptor } from "../../command-support.js";
+import type { RowsFileFormat } from "@oxygen/shared/file-import";
+export declare const TABLE_BUNDLE_SCHEMA_VERSION = 2;
+export declare const TABLE_BUNDLE_LEGACY_SCHEMA_VERSION = 1;
+export declare const TABLE_BUNDLE_SUPPORTED_SCHEMA_VERSIONS: number[];
+export declare const TABLE_BUNDLE_MAX_PAGE_SIZE = 1000;
+export declare const TABLE_BUNDLE_DEFAULT_PAGE_SIZE = 500;
+export declare const TABLE_BUNDLE_HEADER_SCAN_BYTES: number;
+export declare const TABLE_BUNDLE_TRAILER_SCAN_BYTES: number;
+export type QueryPageResponse = {
+    table?: {
+        id?: string;
+        slug?: string;
+        displayName?: string;
+        name?: string;
+    };
+    columns?: QueryColumnDescriptor[];
+    rows: Record<string, unknown>[];
+    nextCursor?: string | null;
+    hasMore?: boolean;
+    totalCount?: number;
+    total_count?: number;
+    returnedCount?: number;
+    returned_count?: number;
+};
+export type ParsedTableBundle = {
+    schemaVersion: number;
+    tableName: string | null;
+    tableSummary: Record<string, unknown> | null;
+    columns: Record<string, unknown>[];
+    rows: Record<string, unknown>[];
+};
+export type OpenedTableBundle = {
+    schemaVersion: number;
+    tableName: string | null;
+    tableSummary: Record<string, unknown> | null;
+    columns: Record<string, unknown>[];
+    /**
+     * Rows the bundle states it holds: the array length of a single document,
+     * the totals trailer of a streamed bundle.
+     */
+    rowCount: number;
+    rows: () => AsyncIterable<Record<string, unknown>>;
+    /** Single-document bundles only: every row is already in memory. */
+    preloadedRows: Record<string, unknown>[] | null;
+};
+export declare function openTableBundle(filePath: string): Promise<OpenedTableBundle>;
+export declare function iterateArrayRows(rows: Record<string, unknown>[]): AsyncGenerator<Record<string, unknown>>;
+export declare function openStreamedTableBundle(filePath: string, header: Record<string, unknown>): OpenedTableBundle;
+export declare function iterateStreamedBundleRows(filePath: string): AsyncGenerator<Record<string, unknown>>;
+export declare function readBundleBatches(input: {
+    bundle: OpenedTableBundle;
+    validColumnKeys: Set<string>;
+    upsertKey: string | null;
+    batchSize: number;
+    tableId: string;
+    resumeCommand: string;
+}): AsyncGenerator<Record<string, unknown>[]>;
+export declare function readFirstBundleLine(filePath: string): string | null;
+export declare function readLastBundleLine(filePath: string): string;
+export declare function parseJsonObjectOrNull(text: string): Record<string, unknown> | null;
+export declare function parseBundleFile(text: string): ParsedTableBundle;
+export declare function stripRowForImport(row: Record<string, unknown>, validColumnKeys: Set<string>): Record<string, unknown>;
+export declare function readBundleNumber(value: unknown): number | null;
+export declare function readRowsFile(path: string, format: RowsFileFormat, sheet?: string): Promise<Record<string, unknown>[]>;
+export declare function normalizeCreatedTableUpsertKey(value: string | undefined, keyBySource: Record<string, string>): string | undefined;

package/dist/command-families/tables/bundle-format.js

@@ -0,0 +1,274 @@
+import { readRecordString } from "../../cli-values.js";
+import { readRecord } from "../../command-support.js";
+import { OxygenError } from "@oxygen/shared/cli-result";
+import { parseRowsFileBuffer } from "@oxygen/shared/file-import";
+import { existsSync, readFileSync, createReadStream, statSync, openSync, readSync, closeSync } from "node:fs";
+import { createInterface } from "node:readline/promises";
+// Bundle formats. Version 2 is line-delimited: a header line carrying the
+// schema, then one `{"row":…}` line per row, then a `{"totals":…}` trailer.
+// It exists because the version-1 single-document bundle is assembled in memory
+// and serialized once, and a 52k-row table carrying LinkedIn profile text pushed
+// that one string past V8's limit ("Invalid string length") on 2026-09-14: the
+// export died after twelve minutes with nothing on disk, and a 96-column table
+// on the other side of the same copy could never have been read back into
+// memory by the importer either. `--output` now streams version 2; import reads
+// both versions, streaming version 2 so file size no longer matters.
+export const TABLE_BUNDLE_SCHEMA_VERSION = 2;
+export const TABLE_BUNDLE_LEGACY_SCHEMA_VERSION = 1;
+export const TABLE_BUNDLE_SUPPORTED_SCHEMA_VERSIONS = [TABLE_BUNDLE_LEGACY_SCHEMA_VERSION, TABLE_BUNDLE_SCHEMA_VERSION];
+export const TABLE_BUNDLE_MAX_PAGE_SIZE = 1000;
+export const TABLE_BUNDLE_DEFAULT_PAGE_SIZE = 500;
+// How much of a bundle file is read to find its header line and totals trailer
+// without loading the whole file: 8 MiB comfortably holds a header for a
+// 100-column table with long AI prompts, and the trailer is one short line.
+export const TABLE_BUNDLE_HEADER_SCAN_BYTES = 8 * 1024 * 1024;
+export const TABLE_BUNDLE_TRAILER_SCAN_BYTES = 1024 * 1024;
+// Opens either bundle format. A streamed (version 2) bundle is recognised by
+// its header line and read line by line, so a multi-GB file never has to fit
+// in memory; a single-document (version 1) bundle is parsed whole, as before.
+export async function openTableBundle(filePath) {
+    if (!existsSync(filePath)) {
+        throw new OxygenError("invalid_input", `Bundle file not found: ${filePath}`, {
+            details: { file: filePath },
+            exitCode: 1,
+        });
+    }
+    const firstLine = readFirstBundleLine(filePath);
+    const header = firstLine === null ? null : parseJsonObjectOrNull(firstLine);
+    if (header && readBundleNumber(header.schemaVersion) === TABLE_BUNDLE_SCHEMA_VERSION) {
+        return openStreamedTableBundle(filePath, header);
+    }
+    let raw;
+    try {
+        raw = readFileSync(filePath, "utf8");
+    }
+    catch (error) {
+        if (error instanceof RangeError || error.code === "ERR_STRING_TOO_LONG") {
+            throw new OxygenError("bundle_too_large", "This bundle is one JSON document too large to load into memory. Re-export it with the current CLI (`oxygen tables export-bundle <table> --output <path>`), which writes one row per line and imports at any size.", { details: { file: filePath }, exitCode: 1 });
+        }
+        throw error;
+    }
+    const parsed = parseBundleFile(raw);
+    return {
+        schemaVersion: parsed.schemaVersion,
+        tableName: parsed.tableName,
+        tableSummary: parsed.tableSummary,
+        columns: parsed.columns,
+        rowCount: parsed.rows.length,
+        preloadedRows: parsed.rows,
+        rows: () => iterateArrayRows(parsed.rows),
+    };
+}
+export async function* iterateArrayRows(rows) {
+    for (const row of rows)
+        yield row;
+}
+export function openStreamedTableBundle(filePath, header) {
+    const rawColumns = header.columns;
+    if (!Array.isArray(rawColumns)) {
+        throw new OxygenError("invalid_bundle", "Streamed bundle header is missing a columns array.", {
+            details: { file: filePath },
+            exitCode: 1,
+        });
+    }
+    const tableSummary = readRecord(header, "table");
+    // The totals trailer is the last thing the exporter writes, so its absence
+    // means the export was interrupted: refuse before creating anything rather
+    // than importing a silently truncated table.
+    const trailer = parseJsonObjectOrNull(readLastBundleLine(filePath));
+    const totals = trailer ? readRecord(trailer, "totals") : null;
+    const rowCount = totals ? readBundleNumber(totals.rowCount) : null;
+    if (rowCount === null) {
+        throw new OxygenError("invalid_bundle", "This streamed bundle has no totals trailer, so the export that produced it was interrupted before it finished. Re-run `oxygen tables export-bundle` and import the complete file.", { details: { file: filePath }, exitCode: 1 });
+    }
+    return {
+        schemaVersion: TABLE_BUNDLE_SCHEMA_VERSION,
+        tableName: tableSummary
+            ? (readRecordString(tableSummary, "name") ?? readRecordString(tableSummary, "displayName"))
+            : null,
+        tableSummary,
+        columns: rawColumns.filter((entry) => Boolean(entry) && typeof entry === "object" && !Array.isArray(entry)),
+        rowCount,
+        preloadedRows: null,
+        rows: () => iterateStreamedBundleRows(filePath),
+    };
+}
+export async function* iterateStreamedBundleRows(filePath) {
+    const fileStream = createReadStream(filePath, { encoding: "utf8" });
+    const reader = createInterface({ input: fileStream, crlfDelay: Infinity });
+    let lineNumber = 0;
+    try {
+        for await (const line of reader) {
+            lineNumber += 1;
+            if (lineNumber === 1 || !line.trim())
+                continue;
+            const entry = parseJsonObjectOrNull(line);
+            if (!entry) {
+                throw new OxygenError("invalid_bundle", `Line ${lineNumber} of the bundle is not a JSON object.`, {
+                    details: { file: filePath, line: lineNumber },
+                    exitCode: 1,
+                });
+            }
+            if ("totals" in entry)
+                return;
+            const row = readRecord(entry, "row");
+            if (!row) {
+                throw new OxygenError("invalid_bundle", `Line ${lineNumber} of the bundle is neither a row nor the totals trailer.`, { details: { file: filePath, line: lineNumber }, exitCode: 1 });
+            }
+            yield row;
+        }
+    }
+    finally {
+        reader.close();
+        fileStream.destroy();
+    }
+}
+// Batches the bundle's rows for the shared import writer, stripping tenant-local
+// fields and enforcing the upsert key on the way through.
+export async function* readBundleBatches(input) {
+    let batch = [];
+    let rowNumber = 0;
+    for await (const rawRow of input.bundle.rows()) {
+        rowNumber += 1;
+        const row = stripRowForImport(rawRow, input.validColumnKeys);
+        if (input.upsertKey && (row[input.upsertKey] === undefined || row[input.upsertKey] === null)) {
+            throw new OxygenError("invalid_bundle", `Row ${rowNumber} is missing a value for the upsert key "${input.upsertKey}".`, {
+                details: {
+                    key: input.upsertKey,
+                    row_number: rowNumber,
+                    table_id: input.tableId,
+                    resume_command: input.resumeCommand,
+                },
+                exitCode: 1,
+            });
+        }
+        batch.push(row);
+        if (batch.length >= input.batchSize) {
+            yield batch;
+            batch = [];
+        }
+    }
+    if (batch.length > 0)
+        yield batch;
+}
+// Reads up to the first newline without loading the file. Returns null when no
+// newline appears inside the scan window and the file is larger than it, which
+// is what a huge single-document bundle looks like.
+export function readFirstBundleLine(filePath) {
+    const size = statSync(filePath).size;
+    const span = Math.min(size, TABLE_BUNDLE_HEADER_SCAN_BYTES);
+    if (span === 0)
+        return "";
+    const fd = openSync(filePath, "r");
+    try {
+        const buffer = Buffer.alloc(span);
+        const read = readSync(fd, buffer, 0, span, 0);
+        const text = buffer.subarray(0, read).toString("utf8");
+        const newline = text.indexOf("\n");
+        if (newline >= 0)
+            return text.slice(0, newline);
+        return read < size ? null : text;
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+export function readLastBundleLine(filePath) {
+    const size = statSync(filePath).size;
+    const span = Math.min(size, TABLE_BUNDLE_TRAILER_SCAN_BYTES);
+    if (span === 0)
+        return "";
+    const fd = openSync(filePath, "r");
+    try {
+        const buffer = Buffer.alloc(span);
+        const read = readSync(fd, buffer, 0, span, size - span);
+        const lines = buffer.subarray(0, read).toString("utf8").split("\n").map((line) => line.trim()).filter(Boolean);
+        return lines.at(-1) ?? "";
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+export function parseJsonObjectOrNull(text) {
+    try {
+        const parsed = JSON.parse(text);
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+            ? parsed
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function parseBundleFile(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (error) {
+        throw new OxygenError("invalid_bundle", "Bundle file is not valid JSON.", {
+            details: { reason: error instanceof Error ? error.message : "unknown" },
+            exitCode: 1,
+        });
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new OxygenError("invalid_bundle", "Bundle file must be a JSON object.", { exitCode: 1 });
+    }
+    const record = parsed;
+    const schemaVersion = typeof record.schemaVersion === "number" ? record.schemaVersion : 1;
+    // A version-2 bundle never reaches this parser (openTableBundle streams it),
+    // so a single document claiming any other version is from a CLI this one
+    // does not know.
+    if (schemaVersion !== TABLE_BUNDLE_LEGACY_SCHEMA_VERSION) {
+        throw new OxygenError("unsupported_bundle_version", `Bundle schema version ${schemaVersion} is not supported by this CLI.`, {
+            details: { supported: TABLE_BUNDLE_SUPPORTED_SCHEMA_VERSIONS, got: schemaVersion },
+            exitCode: 1,
+        });
+    }
+    const rawColumns = record.columns;
+    if (!Array.isArray(rawColumns)) {
+        throw new OxygenError("invalid_bundle", "Bundle is missing a columns array.", { exitCode: 1 });
+    }
+    const rawRows = record.rows;
+    if (!Array.isArray(rawRows)) {
+        throw new OxygenError("invalid_bundle", "Bundle is missing a rows array.", { exitCode: 1 });
+    }
+    const tableSummary = record.table && typeof record.table === "object" && !Array.isArray(record.table)
+        ? record.table
+        : null;
+    return {
+        schemaVersion,
+        tableName: tableSummary
+            ? (readRecordString(tableSummary, "name") ?? readRecordString(tableSummary, "displayName"))
+            : null,
+        tableSummary,
+        columns: rawColumns.filter((entry) => Boolean(entry) && typeof entry === "object" && !Array.isArray(entry)),
+        rows: rawRows.filter((entry) => Boolean(entry) && typeof entry === "object" && !Array.isArray(entry)),
+    };
+}
+export function stripRowForImport(row, validColumnKeys) {
+    const out = {};
+    for (const [key, value] of Object.entries(row)) {
+        if (key === "_row_id" || key === "_created_at" || key === "_updated_at")
+            continue;
+        if (validColumnKeys.size > 0 && !validColumnKeys.has(key))
+            continue;
+        out[key] = value;
+    }
+    return out;
+}
+export function readBundleNumber(value) {
+    if (typeof value === "number" && Number.isFinite(value))
+        return value;
+    if (typeof value === "string" && value.trim() && Number.isFinite(Number(value)))
+        return Number(value);
+    return null;
+}
+export async function readRowsFile(path, format, sheet) {
+    return await parseRowsFileBuffer(readFileSync(path), format, sheet ? { sheet } : {});
+}
+export function normalizeCreatedTableUpsertKey(value, keyBySource) {
+    if (!value)
+        return undefined;
+    return keyBySource[value] ?? value;
+}

package/dist/command-families/tables/bundle-import.d.ts

@@ -0,0 +1,20 @@
+import { QueryColumnDescriptor } from "../../command-support.js";
+import { TablesImportBundleOptions } from "./options.js";
+export declare function importTableBundle(// skipcq: JS-R1005
+options: TablesImportBundleOptions, binaryName: string): Promise<Record<string, unknown>>;
+export declare function buildBundleResumeCommand(input: {
+    file: string;
+    tableId: string;
+    key: string | null;
+    batchSize: number;
+    binaryName: string;
+}): string;
+export declare function toBundleColumn(column: QueryColumnDescriptor): Record<string, unknown>;
+export declare function bundleColumnToCreateInput(column: Record<string, unknown>): {
+    label: string;
+    key?: string;
+    dataType?: string;
+    kind?: string;
+    semanticType?: string;
+    definition?: Record<string, unknown>;
+};