@mog-sdk/node 0.1.0

package/README.md

@@ -0,0 +1,277 @@
+# @mog/sdk
+
+Shortcut Data OS SDK — headless spreadsheet engine for Node.js. Runs the real kernel + Rust compute-core without a browser.
+
+## Quick Start
+
+```typescript
+import { createWorkbook } from '@mog/sdk';
+
+const wb = await createWorkbook();
+const ws = wb.activeSheet;
+
+await ws.setCell('A1', 42);
+await ws.setCell('A2', 58);
+await ws.setCell('A3', '=A1+A2');
+
+const val = await ws.getValue('A3'); // 100
+await wb.dispose();
+```
+
+Three lines to a running spreadsheet engine. No addon injection, no context threading, no active-sheet callbacks.
+
+## Install
+
+```bash
+# Monorepo — already available as workspace dependency
+pnpm add @mog/sdk
+
+# The native Rust addon must be built first
+cd compute-core-napi && pnpm build
+```
+
+## API Reference
+
+### Creating Workbooks
+
+```typescript
+// Zero-arg: blank workbook, auto-detects platform
+const wb = await createWorkbook();
+
+// With options: import XLSX
+const wb = await createWorkbook({
+  source: { type: 'bytes', data: new Uint8Array(buffer) }
+});
+
+// Power-user: pre-existing kernel context (browser app path)
+const wb = await createWorkbook({ ctx, eventBus });
+```
+
+### Reading Data
+
+```typescript
+const ws = wb.activeSheet;
+
+// Single cell value (computed)
+const val = await ws.getValue('A1');        // CellValue | null
+const val2 = await ws.getValue(0, 0);       // numeric addressing
+
+// Full cell data (value + formula + format)
+const cell = await ws.getCell('A1');
+
+// All data in used range as 2D array
+const data = await ws.getData();            // CellValue[][]
+
+// Range read
+const range = await ws.getRange('A1:C10');  // CellData[][]
+
+// LLM-friendly presentation
+await ws.describe('A3');                    // "100(=A1+A2)"
+await ws.describeRange('A1:B3');            // Tabular text
+await ws.summarize();                       // Full sheet overview
+```
+
+### Writing Data
+
+```typescript
+// Single cell (A1 or numeric)
+await ws.setCell('A1', 42);
+await ws.setCell('A2', '=A1*2');
+await ws.setCell(2, 0, 'text');
+
+// Bulk write
+await ws.setRange('A1', [
+  ['Name', 'Score'],
+  ['Alice', 92],
+  ['Bob', 85],
+]);
+```
+
+### Working with Sheets
+
+```typescript
+const count = await wb.getSheetCount();
+const names = await wb.getSheetNames();
+const ws2 = await wb.sheets.add('Sheet2');
+
+// Get or create (idempotent)
+const { sheet, created } = await wb.getOrCreateSheet('Data');
+```
+
+### Tables and Structured Data
+
+```typescript
+// One-liner table creation
+await ws.createTable('SalesData', {
+  headers: ['Product', 'Q1', 'Q2'],
+  data: [
+    ['Widget', 100, 150],
+    ['Gadget', 200, 180],
+  ],
+});
+```
+
+### Serialization
+
+```typescript
+// CSV (RFC 4180, formula injection protected)
+const csv = await ws.toCSV();
+const tsvData = await ws.toCSV({ separator: '\t' });
+
+// JSON (array of objects, first row as headers)
+const json = await ws.toJSON();
+// [{ Product: 'Widget', Q1: 100, Q2: 150 }, ...]
+
+const jsonNoHeader = await ws.toJSON({ headerRow: 'none' });
+// [{ A: 'Product', B: 'Q1', C: 'Q2' }, ...]
+```
+
+### File I/O (SDK-only, Node.js)
+
+```typescript
+import { save } from '@mog/sdk';
+
+// Export workbook to file (format by extension)
+await save(wb, 'output.xlsx');
+```
+
+### Formulas
+
+Each `setCell` mutation triggers automatic recalc in Rust. Formulas are evaluated by the time `setCell` returns — no manual `calculate()` needed.
+
+```typescript
+await ws.setCell('A1', 10);
+await ws.setCell('A2', 20);
+await ws.setCell('A3', '=SUM(A1:A2)');
+
+const val = await ws.getValue('A3'); // 30
+
+// Search by formula
+const cells = await ws.findByFormula(/SUM/);  // ['A3']
+const formula = await ws.getFormula('A3');     // '=SUM(A1:A2)'
+```
+
+### Formatting & Structure
+
+```typescript
+await ws.setFormat('A1', { bold: true, fontColor: '#FF0000' });
+await ws.setRangeFormat('A1:B3', { italic: true });
+
+await ws.structure.insertRows(2, 3);
+await ws.structure.deleteColumns(1, 1);
+await ws.structure.mergeCells('A1:B1');
+```
+
+### Full Kernel API
+
+The full kernel API is accessible — charts, tables, filters, validation, conditional formatting, pivots, and all 23 domain sub-APIs:
+
+```typescript
+// Charts
+await ws.charts.add({ type: 'bar', dataRange: 'A1:B5' });
+
+// Conditional formatting
+await ws.conditionalFormatting.add({ range: 'B2:B10', rule: { type: 'greaterThan', value: 100 } });
+
+// Tables
+await ws.tables.add('MyTable', 'A1:C5', { hasHeaders: true });
+
+// Filters
+await ws.filters.add('A1:C10');
+```
+
+### Low-Level Access
+
+Drop to the raw compute bridge when the high-level API isn't enough:
+
+```typescript
+const bridge = wb.context.computeBridge;
+const sheetId = (await bridge.getAllSheetIds())[0];
+const result = await bridge.setCell(sheetId, crypto.randomUUID(), 0, 0, '=1+1');
+```
+
+### Cleanup
+
+**Always dispose when done** to avoid resource leaks:
+
+```typescript
+await wb.dispose();
+```
+
+## Interactive Script Runner
+
+```bash
+# From sdk/
+node run.cjs                          # runs examples/hello.ts
+node run.cjs examples/explore-api.ts  # explore the full API
+node run.cjs my-script.ts             # run your own script
+```
+
+Scripts export a default async function that receives a ready `Workbook`:
+
+```typescript
+import type { Workbook } from '../src/index';
+
+export default async function (wb: Workbook) {
+  const ws = wb.activeSheet;
+  await ws.setCell('A1', 'Hello from SDK!');
+  console.log(await ws.getValue('A1'));
+}
+```
+
+## Backward Compatibility
+
+`HeadlessEngine` and `createHeadlessEngine()` are preserved for existing consumers:
+
+```typescript
+import { createHeadlessEngine } from '@mog/sdk';
+
+const engine = await createHeadlessEngine({ computeAddon: addon });
+const ws = engine.workbook.getActiveSheet();
+```
+
+New code should use `createWorkbook()` directly.
+
+## Architecture
+
+```
+createWorkbook()
+  └─ DocumentFactory.create({ environment: 'headless' })
+       └─ DocumentLifecycleSystem (XState machine)
+            ├─ createTransport() → auto-detects NAPI
+            │    ├─ LazyNapiTransport → compute-core-napi.node (Rust)
+            │    └─ CompositeTransport → xlsx-parser-napi.node (optional)
+            ├─ ComputeBridge (async cell ops, recalc)
+            └─ DocumentContext (kernel services, event bus)
+                 └─ Workbook / Worksheet (unified API)
+```
+
+The SDK boots the **same kernel** used by the browser app, with headless stubs for browser-only services (Canvas, DOM, IndexedDB). Transport goes through napi-rs directly to Rust — no WASM, no IPC, full native speed.
+
+## Prerequisites
+
+- **Node.js** 20+
+- **pnpm** 10+
+- **Native addon** built: `cd compute-core-napi && pnpm build`
+
+To check if the addon is current:
+
+```bash
+node check-addon.cjs
+```
+
+## Example Scripts
+
+| Script | What it does |
+|--------|-------------|
+| `examples/hello.ts` | Boot, write cells, read back |
+| `examples/explore-api.ts` | Write dataset, read, search, summarize |
+| `examples/getrange-test.ts` | Validate batch_get_cells: formulas, empty cells, identity |
+| `examples/test-interactive.ts` | Interactive API exploration |
+| `examples/test-usedrange.ts` | Used range detection |
+
+## Known Issues
+
+**Console noise on boot**: `[SchemaValidationBridge]` errors during startup are harmless — the schema bridge tries to populate caches before the compute bridge is fully ready.
+
+**IndexedDB error on dispose**: `indexedDB is not defined` appears on shutdown. The kernel tries to save to IndexedDB (browser API) which doesn't exist in Node.js. Caught and harmless.