@cyanheads/mcp-ts-core 0.8.7 → 0.8.9

package/dist/canvas/providers/duckdb/exportWriter.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @fileoverview Path resolution and sandboxing for canvas export targets.
+ *
+ * Refinement #1 in issue #97: path-based exports must be sandboxed to
+ * `CANVAS_EXPORT_PATH`. Absolute paths and `..` traversal are rejected;
+ * the resolved path is always inside the sandbox root. Stream-based exports
+ * write to a temp file inside the sandbox and pipe its bytes to the caller's
+ * `WritableStream`, then unlink the temp file.
+ *
+ * @module src/canvas/providers/duckdb/exportWriter
+ */
+import type { ExportFormat, ExportTarget } from '../../types.js';
+/**
+ * Resolve a caller-supplied relative path against the sandbox root, refusing
+ * absolute inputs and traversal escapes. Always returns an absolute path
+ * that is, by post-condition, a descendant of `rootPath`.
+ *
+ * The sandbox root itself is created if missing.
+ */
+export declare function resolveExportPath(rootPath: string, requested: string): Promise<string>;
+/**
+ * Map an export format to its DuckDB `COPY ... TO` `(FORMAT ...)` clause.
+ * JSON uses DuckDB's `JSON` format (line-delimited JSON by default).
+ */
+export declare function copyFormatClause(format: ExportFormat): string;
+/**
+ * Pipe a written sandbox file into a caller-supplied `WritableStream`,
+ * unlinking the temp file when finished. Used for the stream branch of
+ * {@link ExportTarget}.
+ */
+export declare function pipeFileToStream(filePath: string, stream: WritableStream<Uint8Array>): Promise<{
+    sizeBytes: number;
+}>;
+/**
+ * Generate a unique temp file path inside the sandbox for stream-based exports.
+ * Creates the sandbox root if missing so the caller can write immediately.
+ */
+export declare function tempFilePathFor(rootPath: string, format: ExportFormat): Promise<string>;
+/**
+ * Best-effort size lookup for a written file. Returns 0 if `stat` fails.
+ */
+export declare function safeSizeBytes(path: string): Promise<number>;
+/** Discriminator for {@link ExportTarget}. */
+export declare function isPathTarget(target: ExportTarget): target is {
+    format: ExportFormat;
+    path: string;
+};
+//# sourceMappingURL=exportWriter.d.ts.map

package/dist/canvas/providers/duckdb/exportWriter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exportWriter.d.ts","sourceRoot":"","sources":["../../../../src/canvas/providers/duckdb/exportWriter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAMH,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEjE;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAuB5F;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAS7D;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,GACjC,OAAO,CAAC;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC,CA4BhC;AAED;;;GAGG;AACH,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,CAM7F;AAED;;GAEG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAOjE;AAED,8CAA8C;AAC9C,wBAAgB,YAAY,CAC1B,MAAM,EAAE,YAAY,GACnB,MAAM,IAAI;IAAE,MAAM,EAAE,YAAY,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAElD"}

package/dist/canvas/providers/duckdb/exportWriter.js

@@ -0,0 +1,119 @@
+/**
+ * @fileoverview Path resolution and sandboxing for canvas export targets.
+ *
+ * Refinement #1 in issue #97: path-based exports must be sandboxed to
+ * `CANVAS_EXPORT_PATH`. Absolute paths and `..` traversal are rejected;
+ * the resolved path is always inside the sandbox root. Stream-based exports
+ * write to a temp file inside the sandbox and pipe its bytes to the caller's
+ * `WritableStream`, then unlink the temp file.
+ *
+ * @module src/canvas/providers/duckdb/exportWriter
+ */
+import { mkdir, open, stat, unlink } from 'node:fs/promises';
+import { isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { validationError } from '../../../types-global/errors.js';
+/**
+ * Resolve a caller-supplied relative path against the sandbox root, refusing
+ * absolute inputs and traversal escapes. Always returns an absolute path
+ * that is, by post-condition, a descendant of `rootPath`.
+ *
+ * The sandbox root itself is created if missing.
+ */
+export async function resolveExportPath(rootPath, requested) {
+    if (typeof requested !== 'string' || requested.length === 0) {
+        throw validationError('Export path must be a non-empty string.', {
+            reason: 'export_path_empty',
+        });
+    }
+    if (isAbsolute(requested)) {
+        throw validationError('Export path must be relative — absolute paths are rejected to keep writes inside the canvas sandbox.', { reason: 'export_path_absolute', requested });
+    }
+    const root = resolve(rootPath);
+    const candidate = resolve(root, requested);
+    const rel = relative(root, candidate);
+    if (rel.startsWith(`..${sep}`) || rel === '..') {
+        throw validationError('Export path escapes the canvas sandbox. Use a path inside CANVAS_EXPORT_PATH.', { reason: 'export_path_escapes', requested });
+    }
+    await mkdir(root, { recursive: true });
+    return candidate;
+}
+/**
+ * Map an export format to its DuckDB `COPY ... TO` `(FORMAT ...)` clause.
+ * JSON uses DuckDB's `JSON` format (line-delimited JSON by default).
+ */
+export function copyFormatClause(format) {
+    switch (format) {
+        case 'csv':
+            return "(FORMAT 'csv', HEADER true)";
+        case 'parquet':
+            return "(FORMAT 'parquet')";
+        case 'json':
+            return "(FORMAT 'json')";
+    }
+}
+/**
+ * Pipe a written sandbox file into a caller-supplied `WritableStream`,
+ * unlinking the temp file when finished. Used for the stream branch of
+ * {@link ExportTarget}.
+ */
+export async function pipeFileToStream(filePath, stream) {
+    const writer = stream.getWriter();
+    let total = 0;
+    try {
+        const handle = await open(filePath, 'r');
+        try {
+            const chunkSize = 64 * 1024;
+            const buffer = new Uint8Array(chunkSize);
+            while (true) {
+                const { bytesRead } = await handle.read(buffer, 0, chunkSize, null);
+                if (bytesRead === 0)
+                    break;
+                // Slice owns its bytes — safe to pass to the writer.
+                await writer.write(buffer.slice(0, bytesRead));
+                total += bytesRead;
+            }
+        }
+        finally {
+            await handle.close();
+        }
+        await writer.close();
+    }
+    catch (err) {
+        await writer.abort(err);
+        throw err;
+    }
+    finally {
+        await unlink(filePath).catch(() => {
+            // Best-effort cleanup — file may already be gone if abort raced.
+        });
+    }
+    return { sizeBytes: total };
+}
+/**
+ * Generate a unique temp file path inside the sandbox for stream-based exports.
+ * Creates the sandbox root if missing so the caller can write immediately.
+ */
+export async function tempFilePathFor(rootPath, format) {
+    const root = resolve(rootPath);
+    await mkdir(root, { recursive: true });
+    const stamp = Date.now().toString(36);
+    const rand = Math.random().toString(36).slice(2, 10);
+    return join(root, `.canvas-export-${stamp}-${rand}.${format}`);
+}
+/**
+ * Best-effort size lookup for a written file. Returns 0 if `stat` fails.
+ */
+export async function safeSizeBytes(path) {
+    try {
+        const info = await stat(path);
+        return info.size;
+    }
+    catch {
+        return 0;
+    }
+}
+/** Discriminator for {@link ExportTarget}. */
+export function isPathTarget(target) {
+    return 'path' in target;
+}
+//# sourceMappingURL=exportWriter.js.map

package/dist/canvas/providers/duckdb/exportWriter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exportWriter.js","sourceRoot":"","sources":["../../../../src/canvas/providers/duckdb/exportWriter.ts"],"names":[],"mappings":"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"}

package/dist/canvas/providers/duckdb/schemaSniffer.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @fileoverview Schema inference for {@link DuckdbProvider.registerTable}.
+ * Materializes the first N rows of an iterable, unions JS-side types per
+ * column, and maps to DuckDB column types. Used only when the caller does
+ * not pass an explicit `schema` to `registerTable`. For `AsyncIterable`
+ * inputs the caller must supply a schema — we cannot peek without consuming.
+ *
+ * Algorithm (refinement 4 in issue #97):
+ *   1. Buffer up to `sniffRowCount` rows (default 100).
+ *   2. For each column, take the union of observed JS-side types
+ *      (`string`, `number-int`, `number-float`, `bigint`, `boolean`, `null`,
+ *      `object`).
+ *   3. Map the union to a DuckDB type via {@link unionToDuckdbType}, with
+ *      `VARCHAR` as the safe fallback when the union has no clean answer.
+ *   4. Return `(schema, sniffedRows)` so the caller can append the buffered
+ *      rows without re-iterating.
+ *
+ * @module src/canvas/providers/duckdb/schemaSniffer
+ */
+import type { ColumnSchema } from '../../types.js';
+/** Row-shape used internally — mirrors what registerTable accepts. */
+type Row = Record<string, unknown>;
+/**
+ * Outcome of a sniff: the inferred schema plus the buffered rows we consumed
+ * from the iterable. Callers append `sniffedRows` first, then continue
+ * draining whatever's left of the iterator.
+ */
+export interface SniffedSchema {
+    schema: ColumnSchema[];
+    /** Rows already consumed from the iterable. Append these first. */
+    sniffedRows: Row[];
+}
+/**
+ * Materialize up to `sniffRowCount` rows from the iterable and return the
+ * inferred schema plus the buffered rows. Throws if the input is empty.
+ *
+ * Column ordering is determined by first-appearance across the buffered rows
+ * — column names from the first row come first, then any new keys added by
+ * later rows (each appended in observation order). Missing keys in any row
+ * count as `null` for type inference purposes.
+ */
+export declare function sniffSchema(iterable: Iterable<Row>, sniffRowCount: number): SniffedSchema;
+export {};
+//# sourceMappingURL=schemaSniffer.d.ts.map

package/dist/canvas/providers/duckdb/schemaSniffer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemaSniffer.d.ts","sourceRoot":"","sources":["../../../../src/canvas/providers/duckdb/schemaSniffer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAc,MAAM,gBAAgB,CAAC;AAE/D,sEAAsE;AACtE,KAAK,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEnC;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,YAAY,EAAE,CAAC;IACvB,mEAAmE;IACnE,WAAW,EAAE,GAAG,EAAE,CAAC;CACpB;AA6DD;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,QAAQ,CAAC,GAAG,CAAC,EAAE,aAAa,EAAE,MAAM,GAAG,aAAa,CAiDzF"}

package/dist/canvas/providers/duckdb/schemaSniffer.js

@@ -0,0 +1,134 @@
+/**
+ * @fileoverview Schema inference for {@link DuckdbProvider.registerTable}.
+ * Materializes the first N rows of an iterable, unions JS-side types per
+ * column, and maps to DuckDB column types. Used only when the caller does
+ * not pass an explicit `schema` to `registerTable`. For `AsyncIterable`
+ * inputs the caller must supply a schema — we cannot peek without consuming.
+ *
+ * Algorithm (refinement 4 in issue #97):
+ *   1. Buffer up to `sniffRowCount` rows (default 100).
+ *   2. For each column, take the union of observed JS-side types
+ *      (`string`, `number-int`, `number-float`, `bigint`, `boolean`, `null`,
+ *      `object`).
+ *   3. Map the union to a DuckDB type via {@link unionToDuckdbType}, with
+ *      `VARCHAR` as the safe fallback when the union has no clean answer.
+ *   4. Return `(schema, sniffedRows)` so the caller can append the buffered
+ *      rows without re-iterating.
+ *
+ * @module src/canvas/providers/duckdb/schemaSniffer
+ */
+import { validationError } from '../../../types-global/errors.js';
+function classify(value) {
+    if (value === null || value === undefined)
+        return 'null';
+    if (typeof value === 'string')
+        return 'string';
+    if (typeof value === 'boolean')
+        return 'boolean';
+    if (typeof value === 'bigint')
+        return 'bigint';
+    if (typeof value === 'number') {
+        return Number.isInteger(value) ? 'integer' : 'double';
+    }
+    // Arrays, plain objects, dates, etc. all fall through here. Stored as JSON.
+    return 'object';
+}
+/**
+ * Choose a DuckDB column type for a column based on the union of JS types
+ * observed in the first N rows. Conservative: when the union mixes strings
+ * with numerics, falls back to `VARCHAR` rather than guessing.
+ */
+function unionToDuckdbType(observed) {
+    const nonNull = new Set(observed);
+    nonNull.delete('null');
+    if (nonNull.size === 0)
+        return 'VARCHAR';
+    if (nonNull.size === 1) {
+        const [only] = nonNull;
+        switch (only) {
+            case 'string':
+                return 'VARCHAR';
+            case 'integer':
+                return 'BIGINT';
+            case 'double':
+                return 'DOUBLE';
+            case 'bigint':
+                return 'BIGINT';
+            case 'boolean':
+                return 'BOOLEAN';
+            case 'object':
+                return 'JSON';
+            default:
+                return 'VARCHAR';
+        }
+    }
+    // Numeric widening — INTEGER + DOUBLE → DOUBLE; INTEGER + BIGINT → BIGINT.
+    if (nonNull.has('double') && nonNull.has('integer') && nonNull.size === 2)
+        return 'DOUBLE';
+    if (nonNull.has('bigint') && nonNull.has('integer') && nonNull.size === 2)
+        return 'BIGINT';
+    if (nonNull.has('double') &&
+        nonNull.has('integer') &&
+        nonNull.has('bigint') &&
+        nonNull.size === 3) {
+        return 'DOUBLE';
+    }
+    // Mixed string+structured → JSON when string is absent; otherwise VARCHAR.
+    if (!nonNull.has('string') && nonNull.has('object'))
+        return 'JSON';
+    return 'VARCHAR';
+}
+/**
+ * Materialize up to `sniffRowCount` rows from the iterable and return the
+ * inferred schema plus the buffered rows. Throws if the input is empty.
+ *
+ * Column ordering is determined by first-appearance across the buffered rows
+ * — column names from the first row come first, then any new keys added by
+ * later rows (each appended in observation order). Missing keys in any row
+ * count as `null` for type inference purposes.
+ */
+export function sniffSchema(iterable, sniffRowCount) {
+    if (sniffRowCount < 1) {
+        throw validationError('sniffRowCount must be at least 1.', { sniffRowCount });
+    }
+    const sniffedRows = [];
+    let count = 0;
+    for (const row of iterable) {
+        sniffedRows.push(row);
+        count += 1;
+        if (count >= sniffRowCount)
+            break;
+    }
+    if (sniffedRows.length === 0) {
+        throw validationError('Cannot infer schema from an empty input. Provide either rows or an explicit `schema`.', { reason: 'empty_input' });
+    }
+    const observedByCol = new Map();
+    const columnOrder = [];
+    for (const row of sniffedRows) {
+        for (const key of Object.keys(row)) {
+            let bag = observedByCol.get(key);
+            if (!bag) {
+                bag = new Set();
+                observedByCol.set(key, bag);
+                columnOrder.push(key);
+            }
+            bag.add(classify(row[key]));
+        }
+        // Account for missing keys as `null` against existing columns.
+        for (const key of columnOrder) {
+            if (!(key in row)) {
+                observedByCol.get(key)?.add('null');
+            }
+        }
+    }
+    const schema = columnOrder.map((name) => {
+        const observed = observedByCol.get(name) ?? new Set(['null']);
+        return {
+            name,
+            type: unionToDuckdbType(observed),
+            nullable: observed.has('null') || observed.size === 0,
+        };
+    });
+    return { schema, sniffedRows };
+}
+//# sourceMappingURL=schemaSniffer.js.map

package/dist/canvas/providers/duckdb/schemaSniffer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemaSniffer.js","sourceRoot":"","sources":["../../../../src/canvas/providers/duckdb/schemaSniffer.ts"],"names":[],"mappings":"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"}

package/dist/canvas/types.d.ts

@@ -0,0 +1,134 @@
+/**
+ * @fileoverview Public types for the DataCanvas primitive — column schemas,
+ * table info, and option/result shapes for register/query/export/describe.
+ * Engine-agnostic: DuckDB is the v1 implementation but these types do not bind
+ * to it.
+ * @module src/canvas/types
+ */
+/**
+ * Column type tag used when an explicit schema is provided to
+ * {@link IDataCanvasProvider.registerTable}. The DuckDB provider maps these
+ * to native DuckDB types; future engines map to their nearest equivalents.
+ */
+export type ColumnType = 'VARCHAR' | 'INTEGER' | 'BIGINT' | 'DOUBLE' | 'BOOLEAN' | 'TIMESTAMP' | 'DATE' | 'JSON' | 'BLOB';
+/** Single column declaration in an explicit table schema. */
+export interface ColumnSchema {
+    /** Column name. Validated against the canvas identifier rules. */
+    name: string;
+    /** Whether NULL values are permitted. Defaults to `true`. */
+    nullable?: boolean;
+    /** Column type tag. */
+    type: ColumnType;
+}
+/** Metadata returned by {@link CanvasInstance.describe}. */
+export interface TableInfo {
+    /** Approximate in-memory footprint in bytes (engine-specific estimate). */
+    approxSizeBytes?: number;
+    /** Resolved schema for the table. */
+    columns: ColumnSchema[];
+    /** Canvas-local table name. */
+    name: string;
+    /** Number of rows currently stored. */
+    rowCount: number;
+}
+/** Options for {@link CanvasInstance.registerTable}. */
+export interface RegisterTableOptions {
+    /**
+     * Explicit schema. When omitted, the provider sniffs the first N rows
+     * (default 100) to infer types, falling back to `VARCHAR` for ambiguous
+     * columns. **Required** when `rows` is an `AsyncIterable` — the provider
+     * cannot peek without consuming.
+     */
+    schema?: ColumnSchema[];
+    /** Cancellation signal forwarded to the provider. */
+    signal?: AbortSignal;
+}
+/** Result of a successful {@link CanvasInstance.registerTable} call. */
+export interface RegisterTableResult {
+    /** Column names in declaration order. */
+    columns: string[];
+    /** Number of rows ingested. */
+    rowCount: number;
+    /** Resolved (validated, quoted-safe) table name. */
+    tableName: string;
+}
+/** Options for {@link CanvasInstance.query}. */
+export interface QueryOptions {
+    /**
+     * Number of rows to include in the immediate response. Defaults to
+     * `rowLimit`. Use a smaller value (e.g. 50) when `registerAs` is set and
+     * the caller only wants a sample.
+     */
+    preview?: number;
+    /**
+     * Persist the result set as a new canvas table. The returned `rows` is
+     * still bounded by `preview`/`rowLimit`; the full result lives on-canvas
+     * under this name. Throws `Conflict` if a table with this name already
+     * exists.
+     */
+    registerAs?: string;
+    /**
+     * Hard cap on rows materialized into the response. Default 10_000. To keep
+     * a full result set, use `registerAs` (canonical) rather than raising this.
+     */
+    rowLimit?: number;
+    /** Cancellation signal — interrupts the underlying connection. */
+    signal?: AbortSignal;
+}
+/** Result of a successful {@link CanvasInstance.query} call. */
+export interface QueryResult {
+    /** Column names in projection order. */
+    columns: string[];
+    /** Total rows the query produced (may exceed `rows.length` when capped). */
+    rowCount: number;
+    /** Materialized rows (bounded by `preview`/`rowLimit`). */
+    rows: Record<string, unknown>[];
+    /** Set when `registerAs` was supplied. */
+    tableName?: string;
+}
+/** Supported export formats. */
+export type ExportFormat = 'csv' | 'parquet' | 'json';
+/**
+ * Discriminated export target. Path-targeted exports are sandboxed to
+ * `CANVAS_EXPORT_PATH`; absolute paths and `..` traversal are rejected.
+ */
+export type ExportTarget = {
+    format: ExportFormat;
+    path: string;
+} | {
+    format: ExportFormat;
+    stream: WritableStream<Uint8Array>;
+};
+/** Options for {@link CanvasInstance.export}. */
+export interface ExportOptions {
+    /** Cancellation signal. */
+    signal?: AbortSignal;
+}
+/** Result of a successful {@link CanvasInstance.export} call. */
+export interface ExportResult {
+    /** Format that was written. */
+    format: ExportFormat;
+    /** Absolute path written, when the target was a path; undefined for streams. */
+    path?: string;
+    /** Rows written. */
+    rowCount: number;
+    /** Bytes written. */
+    sizeBytes: number;
+}
+/** Options for {@link CanvasInstance.describe}. */
+export interface DescribeOptions {
+    /** When set, return only the named table. */
+    tableName?: string;
+}
+/** Options for {@link DataCanvas.acquire}. */
+export interface AcquireOptions {
+    /** Cancellation signal for the acquire/init handshake. */
+    signal?: AbortSignal;
+}
+/**
+ * Async row iterator accepted by {@link CanvasInstance.registerTable}.
+ * Materialized arrays are also accepted; iterables are forwarded row-by-row
+ * to the provider's appender.
+ */
+export type RegisterRows = AsyncIterable<Record<string, unknown>> | Iterable<Record<string, unknown>>;
+//# sourceMappingURL=types.d.ts.map

package/dist/canvas/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/canvas/types.ts"],"names":[],"mappings":"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"}

package/dist/canvas/types.js

@@ -0,0 +1,9 @@
+/**
+ * @fileoverview Public types for the DataCanvas primitive — column schemas,
+ * table info, and option/result shapes for register/query/export/describe.
+ * Engine-agnostic: DuckDB is the v1 implementation but these types do not bind
+ * to it.
+ * @module src/canvas/types
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/canvas/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/canvas/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}