shortcutxl 0.2.19 → 0.2.21

package/dist/custom/new-sheet/mutation-tracker.js

@@ -0,0 +1,358 @@
+/**
+ * Mutation Tracker — Proxy-based dirty cell tracking for sheet-exec.
+ *
+ * Wraps Workbook/Worksheet objects in Proxies that record every mutation
+ * (setCell, setRange, batchSetCells, etc.). Captures old values before
+ * each mutation. After code execution, resolves mutations to CellEdit[]
+ * by batch-fetching current values and display values.
+ *
+ * Each MutationRecord stores a workbook reference so resolve() works
+ * correctly across multiple workbooks.
+ *
+ * Proxy pattern adapted from os/runtime/headless-server/src/execution/executor.ts.
+ *
+ * TODO: Sparse range optimization — resolve() fetches the full bounding box for
+ * all mutations on a sheet. If mutations are sparse (e.g. A1 and Z100), this
+ * fetches many unneeded cells. Consider partitioning into sub-ranges.
+ */
+import { indexToAddress, parseExcelAddress } from './cell-diff/address-utils.js';
+// =============================================================================
+// Capture helpers
+// =============================================================================
+/** Capture old value + display value for a single cell before mutation. */
+async function captureOld(ws, address) {
+    let oldValue = null;
+    let oldDisplayValue;
+    try {
+        oldValue = await ws.getValue(address);
+        oldDisplayValue = await ws.getDisplayValue(address);
+    }
+    catch {
+        /* cell may not exist yet */
+    }
+    return { oldValue, oldDisplayValue };
+}
+/**
+ * Batch-capture old values for a rectangular range.
+ * Uses a single getRange call instead of N individual getValue calls.
+ */
+async function captureOldRange(ws, startRow, startCol, endRow, endCol) {
+    const result = new Map();
+    try {
+        const rangeData = await ws.getRange(startRow, startCol, endRow, endCol);
+        for (let r = startRow; r <= endRow; r++) {
+            for (let c = startCol; c <= endCol; c++) {
+                const addr = indexToAddress(r, c);
+                const cellData = rangeData[r - startRow]?.[c - startCol];
+                let oldDisplayValue;
+                try {
+                    oldDisplayValue = await ws.getDisplayValue(addr);
+                }
+                catch {
+                    /* cell may not exist yet */
+                }
+                result.set(addr, {
+                    oldValue: cellData?.value ?? null,
+                    oldDisplayValue
+                });
+            }
+        }
+    }
+    catch {
+        // Range may not exist yet — return empty map, individual cells will get null
+    }
+    return result;
+}
+// =============================================================================
+// Proxy wrappers
+// =============================================================================
+function createTrackedWorksheet(ws, sheetName, wb, mutations) {
+    return new Proxy(ws, {
+        get(target, prop, receiver) {
+            const original = Reflect.get(target, prop, receiver);
+            // setCell(address, value) or setCell(row, col, value)
+            if (prop === 'setCell') {
+                return async (first, ...rest) => {
+                    const addr = typeof first === 'string' ? first : indexToAddress(first, rest[0]);
+                    const old = await captureOld(target, addr);
+                    mutations.push({ workbook: wb, sheet: sheetName, address: addr, ...old });
+                    return original.call(target, first, ...rest);
+                };
+            }
+            // setRange(range, values[][]) or setRange(startRow, startCol, values[][])
+            if (prop === 'setRange') {
+                return async (first, ...rest) => {
+                    if (typeof first === 'string') {
+                        const parts = first.split(':');
+                        const start = parseExcelAddress(parts[0]);
+                        const end = parts[1] ? parseExcelAddress(parts[1]) : start;
+                        const oldValues = await captureOldRange(target, start.row, start.col, end.row, end.col);
+                        for (let r = start.row; r <= end.row; r++) {
+                            for (let c = start.col; c <= end.col; c++) {
+                                const addr = indexToAddress(r, c);
+                                const old = oldValues.get(addr) ?? { oldValue: null };
+                                mutations.push({ workbook: wb, sheet: sheetName, address: addr, ...old });
+                            }
+                        }
+                        return original.call(target, first, ...rest);
+                    }
+                    else {
+                        const startRow = first;
+                        const startCol = rest[0];
+                        const values = rest[1];
+                        if (Array.isArray(values)) {
+                            const endRow = startRow + values.length - 1;
+                            const endCol = startCol + Math.max(...values.map((r) => r?.length ?? 0)) - 1;
+                            const oldValues = await captureOldRange(target, startRow, startCol, endRow, endCol);
+                            for (let r = 0; r < values.length; r++) {
+                                for (let c = 0; c < (values[r]?.length ?? 0); c++) {
+                                    const addr = indexToAddress(startRow + r, startCol + c);
+                                    const old = oldValues.get(addr) ?? { oldValue: null };
+                                    mutations.push({ workbook: wb, sheet: sheetName, address: addr, ...old });
+                                }
+                            }
+                        }
+                        return original.call(target, first, ...rest);
+                    }
+                };
+            }
+            // batchSetCells([{ row, col, value }])
+            if (prop === 'batchSetCells') {
+                return async (updates) => {
+                    if (updates.length > 0) {
+                        const rows = updates.map((u) => u.row);
+                        const cols = updates.map((u) => u.col);
+                        const oldValues = await captureOldRange(target, Math.min(...rows), Math.min(...cols), Math.max(...rows), Math.max(...cols));
+                        for (const u of updates) {
+                            const addr = indexToAddress(u.row, u.col);
+                            const old = oldValues.get(addr) ?? { oldValue: null };
+                            mutations.push({ workbook: wb, sheet: sheetName, address: addr, ...old });
+                        }
+                    }
+                    return original.call(target, updates);
+                };
+            }
+            // batchSetFormulas([{ row, col, formula }])
+            if (prop === 'batchSetFormulas') {
+                return async (updates) => {
+                    if (updates.length > 0) {
+                        const rows = updates.map((u) => u.row);
+                        const cols = updates.map((u) => u.col);
+                        const oldValues = await captureOldRange(target, Math.min(...rows), Math.min(...cols), Math.max(...rows), Math.max(...cols));
+                        for (const u of updates) {
+                            const addr = indexToAddress(u.row, u.col);
+                            const old = oldValues.get(addr) ?? { oldValue: null };
+                            mutations.push({ workbook: wb, sheet: sheetName, address: addr, ...old });
+                        }
+                    }
+                    return original.call(target, updates);
+                };
+            }
+            // setDateValue(row, col, date)
+            if (prop === 'setDateValue') {
+                return async (row, col, ...args) => {
+                    const addr = indexToAddress(row, col);
+                    const old = await captureOld(target, addr);
+                    mutations.push({ workbook: wb, sheet: sheetName, address: addr, ...old });
+                    return original.call(target, row, col, ...args);
+                };
+            }
+            // setTimeValue(row, col, date)
+            if (prop === 'setTimeValue') {
+                return async (row, col, ...args) => {
+                    const addr = indexToAddress(row, col);
+                    const old = await captureOld(target, addr);
+                    mutations.push({ workbook: wb, sheet: sheetName, address: addr, ...old });
+                    return original.call(target, row, col, ...args);
+                };
+            }
+            if (typeof original === 'function') {
+                return original.bind(target);
+            }
+            return original;
+        }
+    });
+}
+function createTrackedWorkbook(wb, mutations) {
+    return new Proxy(wb, {
+        get(target, prop, receiver) {
+            const original = Reflect.get(target, prop, receiver);
+            if (prop === 'getSheetByIndex') {
+                return async (index) => {
+                    const ws = await original.call(target, index);
+                    const name = ws.getName();
+                    return createTrackedWorksheet(ws, name, target, mutations);
+                };
+            }
+            if (prop === 'getSheetByName') {
+                return async (sheetName) => {
+                    const ws = await original.call(target, sheetName);
+                    return createTrackedWorksheet(ws, sheetName, target, mutations);
+                };
+            }
+            if (prop === 'getSheet') {
+                return (sheetId) => {
+                    const ws = original.call(target, sheetId);
+                    const name = ws.getName();
+                    return createTrackedWorksheet(ws, name, target, mutations);
+                };
+            }
+            if (prop === 'getActiveSheet') {
+                return () => {
+                    const ws = original.call(target);
+                    const name = ws.getName();
+                    return createTrackedWorksheet(ws, name ?? '__active__', target, mutations);
+                };
+            }
+            if (prop === 'addSheet') {
+                return async (name, index) => {
+                    const ws = await original.call(target, name, index);
+                    return createTrackedWorksheet(ws, name ?? ws.getName(), target, mutations);
+                };
+            }
+            // Intercept sheets property to wrap sheets.add() return value
+            if (prop === 'sheets') {
+                const sheetsObj = original;
+                return new Proxy(sheetsObj, {
+                    get(sTarget, sProp, sReceiver) {
+                        const sOriginal = Reflect.get(sTarget, sProp, sReceiver);
+                        if (sProp === 'add') {
+                            return async (name, index) => {
+                                const ws = await sOriginal.call(sTarget, name, index);
+                                return createTrackedWorksheet(ws, name ?? ws.getName(), target, mutations);
+                            };
+                        }
+                        if (typeof sOriginal === 'function')
+                            return sOriginal.bind(sTarget);
+                        return sOriginal;
+                    }
+                });
+            }
+            if (typeof original === 'function') {
+                return original.bind(target);
+            }
+            return original;
+        }
+    });
+}
+// =============================================================================
+// MutationTracker
+// =============================================================================
+export class MutationTracker {
+    mutations = [];
+    trackedWorkbooks = new Map();
+    /**
+     * Wrap a Workbook in tracking Proxies. Returns a cached proxy if this
+     * workbook has already been wrapped, avoiding nested proxy chains.
+     */
+    track(wb) {
+        const existing = this.trackedWorkbooks.get(wb);
+        if (existing)
+            return existing;
+        const tracked = createTrackedWorkbook(wb, this.mutations);
+        this.trackedWorkbooks.set(wb, tracked);
+        return tracked;
+    }
+    /**
+     * After execution, resolve all mutations to CellEdit[] by batch-fetching
+     * current values, display values, and number formats from workbooks.
+     *
+     * Each mutation stores its workbook reference, so multi-workbook scenarios
+     * resolve correctly.
+     *
+     * getRange returns CellData[][] where CellData = { value, formula?, format?, ... }
+     * and format?.numberFormat holds the number format string.
+     */
+    async resolve() {
+        if (this.mutations.length === 0)
+            return [];
+        const cellEdits = [];
+        // Deduplicate: same workbook+sheet+address → keep first (true pre-execution oldValue)
+        const seen = new Map();
+        for (const m of this.mutations) {
+            // Use object identity for workbook dedup key
+            const wbId = this.getWorkbookId(m.workbook);
+            const key = `${wbId}\0${m.sheet}\0${m.address}`;
+            if (!seen.has(key)) {
+                seen.set(key, m);
+            }
+        }
+        const unique = [...seen.values()];
+        // Group by workbook+sheet for batch fetching
+        const groups = new Map();
+        for (const m of unique) {
+            const wbId = this.getWorkbookId(m.workbook);
+            const groupKey = `${wbId}\0${m.sheet}`;
+            if (!groups.has(groupKey)) {
+                groups.set(groupKey, { wb: m.workbook, sheet: m.sheet, mutations: [] });
+            }
+            groups.get(groupKey).mutations.push(m);
+        }
+        for (const [, { wb, sheet: sheetKey, mutations: sheetMutations }] of groups) {
+            try {
+                let ws;
+                let resolvedSheetName;
+                if (sheetKey === '__active__') {
+                    ws = wb.getActiveSheet();
+                    resolvedSheetName = ws.getName();
+                }
+                else {
+                    try {
+                        ws = await wb.getSheetByName(sheetKey);
+                        resolvedSheetName = sheetKey;
+                    }
+                    catch {
+                        ws = wb.getSheet(sheetKey);
+                        resolvedSheetName = ws.getName();
+                    }
+                }
+                // Parse addresses to row/col and compute bounding box
+                const positions = sheetMutations.map((m) => {
+                    const pos = parseExcelAddress(m.address);
+                    return { ...pos, address: m.address, mutation: m };
+                });
+                const minRow = Math.min(...positions.map((p) => p.row));
+                const maxRow = Math.max(...positions.map((p) => p.row));
+                const minCol = Math.min(...positions.map((p) => p.col));
+                const maxCol = Math.max(...positions.map((p) => p.col));
+                // Single batch fetch — getRange(startRow, startCol, endRow, endCol) inclusive
+                const rangeData = await ws.getRange(minRow, minCol, maxRow, maxCol);
+                for (const pos of positions) {
+                    const rowIdx = pos.row - minRow;
+                    const colIdx = pos.col - minCol;
+                    const cellData = rangeData[rowIdx]?.[colIdx];
+                    // Prefer cellData.formatted (from queryRange) — it's the Rust-formatted
+                    // display string and works reliably for formula cells. getDisplayValue()
+                    // returns "" for formula cells in headless/napi mode.
+                    const displayValue = cellData?.formatted ?? undefined;
+                    cellEdits.push({
+                        sheet: resolvedSheetName,
+                        address: pos.address,
+                        oldValue: pos.mutation.oldValue,
+                        value: cellData?.value ?? null,
+                        oldDisplayValue: pos.mutation.oldDisplayValue,
+                        displayValue,
+                        formula: cellData?.formula ?? null,
+                        numberFormat: cellData?.format?.numberFormat
+                    });
+                }
+            }
+            catch {
+                // Sheet may have been deleted — skip
+            }
+        }
+        return cellEdits;
+    }
+    /** Stable identity for a workbook across lookups. */
+    workbookIds = new Map();
+    nextWbId = 0;
+    getWorkbookId(wb) {
+        let id = this.workbookIds.get(wb);
+        if (id === undefined) {
+            id = this.nextWbId++;
+            this.workbookIds.set(wb, id);
+        }
+        return id;
+    }
+}
+//# sourceMappingURL=mutation-tracker.js.map

package/dist/custom/new-sheet/sandbox-globals.js

@@ -0,0 +1,118 @@
+/**
+ * Sandbox globals for the headless sheet engine VM.
+ *
+ * Builds the global object injected into `vm.createContext()`.
+ * Separated from sheet-exec.ts so the lifecycle API surface is
+ * defined in one place and can be referenced by tests independently.
+ */
+import { readFile, writeFile } from 'node:fs/promises';
+import { basename } from 'node:path';
+import { getMethodInfo } from './api-lookup.js';
+// ---------------------------------------------------------------------------
+// Lifecycle functions
+// ---------------------------------------------------------------------------
+function buildLifecycleFunctions(pool, tracker) {
+    const createWorkbook = async (name) => {
+        const wbName = await pool.createWorkbook(name);
+        return tracker.track(pool.getWorkbook(wbName));
+    };
+    const loadWorkbook = async (path) => {
+        const name = basename(path);
+        if (pool.has(name)) {
+            pool.activeWorkbookName = name;
+            return tracker.track(pool.getWorkbook(name));
+        }
+        const buf = await readFile(path);
+        await pool.openWorkbook(name, buf);
+        pool.setSourcePath(name, path);
+        return tracker.track(pool.getWorkbook(name));
+    };
+    const getWorkbook = (name) => {
+        return tracker.track(pool.getWorkbook(name));
+    };
+    const listWorkbooks = () => {
+        return pool.listWorkbooks();
+    };
+    const saveWorkbook = async (path, wb) => {
+        const target = wb ??
+            (() => {
+                if (!pool.activeWorkbookName)
+                    throw new Error('No workbook open. Use createWorkbook() or loadWorkbook(path) first.');
+                return pool.getWorkbook(pool.activeWorkbookName);
+            })();
+        const buf = await target.toBuffer();
+        await writeFile(path, buf);
+        return path;
+    };
+    const closeWorkbook = async (name) => {
+        await pool.close(name);
+    };
+    const getActiveWorkbook = () => {
+        if (!pool.activeWorkbookName) {
+            throw new Error('No workbook open. Use createWorkbook() or loadWorkbook(path) first.');
+        }
+        return tracker.track(pool.getWorkbook(pool.activeWorkbookName));
+    };
+    return {
+        createWorkbook,
+        loadWorkbook,
+        getWorkbook,
+        listWorkbooks,
+        saveWorkbook,
+        closeWorkbook,
+        getActiveWorkbook
+    };
+}
+// ---------------------------------------------------------------------------
+// Full sandbox object
+// ---------------------------------------------------------------------------
+export function buildSandbox(deps) {
+    const { pool, tracker, console: sandboxConsole } = deps;
+    const lifecycle = buildLifecycleFunctions(pool, tracker);
+    return {
+        // Workbook lifecycle
+        createWorkbook: lifecycle.createWorkbook,
+        loadWorkbook: lifecycle.loadWorkbook,
+        getWorkbook: lifecycle.getWorkbook,
+        listWorkbooks: lifecycle.listWorkbooks,
+        saveWorkbook: lifecycle.saveWorkbook,
+        closeWorkbook: lifecycle.closeWorkbook,
+        // Convenience: active workbook/worksheet (lazy getters, tracked)
+        get workbook() {
+            return lifecycle.getActiveWorkbook();
+        },
+        get worksheet() {
+            return lifecycle.getActiveWorkbook().getActiveSheet();
+        },
+        // API discovery
+        getMethodInfo,
+        console: sandboxConsole,
+        // Standard globals
+        Math,
+        Date,
+        JSON,
+        Array,
+        Object,
+        String,
+        Number,
+        Boolean,
+        RegExp,
+        Map,
+        Set,
+        Promise,
+        Error,
+        TypeError,
+        RangeError,
+        parseInt,
+        parseFloat,
+        isNaN,
+        isFinite,
+        encodeURIComponent,
+        decodeURIComponent,
+        setTimeout,
+        clearTimeout,
+        Buffer,
+        URL
+    };
+}
+//# sourceMappingURL=sandbox-globals.js.map

package/dist/custom/new-sheet/sdk-types.js

@@ -0,0 +1,9 @@
+/**
+ * SDK type seam — the ONLY file in new-sheet/ that imports @shortcut/sdk.
+ *
+ * All other new-sheet files import from here. To sever the SDK dependency
+ * (e.g. for a build that excludes new-sheet), this is the single cut point.
+ */
+// @ts-ignore — optional dep: severed for published builds (not in package.json)
+export { createHeadlessEngine } from '@shortcut/sdk';
+//# sourceMappingURL=sdk-types.js.map

package/dist/custom/new-sheet/sheet-engine-poc.js

@@ -0,0 +1,112 @@
+// Note: `wb` is a pre-booted Workbook from the runner harness.
+// We also test creating additional engines to prove multi-workbook works.
+import { createHeadlessEngine } from './sdk-types.js';
+export default async function (wb) {
+    const computeAddon = require('@shortcut/compute-core-napi');
+    computeAddon.computeSetCurrentTime(45292.0);
+    let passed = 0;
+    let failed = 0;
+    function assert(cond, msg) {
+        if (!cond) {
+            console.error(`  FAIL: ${msg}`);
+            failed++;
+        }
+        else {
+            console.log(`  PASS: ${msg}`);
+            passed++;
+        }
+    }
+    function assertEq(actual, expected, msg) {
+        if (String(actual) !== String(expected)) {
+            console.error(`  FAIL: ${msg} — expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}`);
+            failed++;
+        }
+        else {
+            console.log(`  PASS: ${msg}`);
+            passed++;
+        }
+    }
+    // =========================================================================
+    // Test 1: Basic cell read/write (using the pre-booted workbook)
+    // =========================================================================
+    console.log('\n--- Test 1: Basic cell read/write ---');
+    const ws1 = wb.getActiveSheet();
+    await ws1.setCell('A1', 100);
+    await ws1.setCell('B1', 'hello');
+    assertEq(await ws1.getValue('A1'), 100, 'A1 = 100');
+    assertEq(await ws1.getValue('B1'), 'hello', 'B1 = hello');
+    // =========================================================================
+    // Test 2: Formula evaluation
+    // =========================================================================
+    console.log('\n--- Test 2: Formula evaluation ---');
+    await ws1.setCell('A2', 200);
+    await ws1.setCell('A3', '=A1+A2');
+    assertEq(await ws1.getValue('A3'), 300, '=A1+A2 evaluates to 300');
+    await ws1.setCell('A4', '=SUM(A1:A2)');
+    assertEq(await ws1.getValue('A4'), 300, '=SUM(A1:A2) evaluates to 300');
+    // =========================================================================
+    // Test 3: Multiple independent engines
+    // =========================================================================
+    console.log('\n--- Test 3: Multiple independent engines ---');
+    const engine2 = await createHeadlessEngine({ computeAddon });
+    const wb2 = engine2.workbook;
+    const ws2 = wb2.getActiveSheet();
+    await ws2.setCell('A1', 999);
+    assertEq(await ws2.getValue('A1'), 999, 'engine2 A1 = 999');
+    assertEq(await ws1.getValue('A1'), 100, 'engine1 A1 still 100 (isolated)');
+    await engine2.dispose();
+    // =========================================================================
+    // Test 4: Add sheet, write to new sheet
+    // =========================================================================
+    console.log('\n--- Test 4: Add sheet ---');
+    await wb.sheets.add('Data');
+    const names = await wb.getSheetNames();
+    assert(names.includes('Data'), `Data sheet exists (sheets: ${names.join(', ')})`);
+    const wsData = await wb.getSheetByName('Data');
+    await wsData.setCell('A1', 'on second sheet');
+    assertEq(await wsData.getValue('A1'), 'on second sheet', 'Data!A1 correct');
+    // =========================================================================
+    // Test 5: Scale — create N engines
+    // =========================================================================
+    console.log('\n--- Test 5: Scale test ---');
+    const N = 20;
+    const t0 = performance.now();
+    const engines = [];
+    for (let i = 0; i < N; i++) {
+        const eng = await createHeadlessEngine({ computeAddon });
+        const ws = eng.workbook.getActiveSheet();
+        await ws.setCell('A1', i);
+        await ws.setCell('A2', '=A1*2');
+        engines.push(eng);
+    }
+    const createTime = performance.now() - t0;
+    console.log(`  Created ${N} engines in ${createTime.toFixed(0)}ms (${(createTime / N).toFixed(1)}ms each)`);
+    let allCorrect = true;
+    for (let i = 0; i < N; i++) {
+        const ws = engines[i].workbook.getActiveSheet();
+        const val = await ws.getValue('A2');
+        if (val !== i * 2) {
+            console.error(`  FAIL: engine${i} A2 expected ${i * 2}, got ${val}`);
+            allCorrect = false;
+            break;
+        }
+    }
+    assert(allCorrect, `all ${N} engines have correct independent values`);
+    for (const eng of engines)
+        await eng.dispose();
+    // =========================================================================
+    // Test 6: Memory snapshot
+    // =========================================================================
+    console.log('\n--- Test 6: Memory ---');
+    const mem = process.memoryUsage();
+    console.log(`  RSS: ${(mem.rss / 1024 / 1024).toFixed(1)} MB`);
+    console.log(`  Heap: ${(mem.heapUsed / 1024 / 1024).toFixed(1)} MB`);
+    console.log(`  External: ${(mem.external / 1024 / 1024).toFixed(1)} MB`);
+    // =========================================================================
+    // Summary
+    // =========================================================================
+    console.log(`\n=== Results: ${passed} passed, ${failed} failed ===`);
+    if (failed > 0)
+        throw new Error(`${failed} test(s) failed`);
+}
+//# sourceMappingURL=sheet-engine-poc.js.map