@mog-sdk/node 0.1.2 → 0.1.6

package/dist/index.d.cts

@@ -17,6 +17,8 @@ export type IEventBus = any;
 
 
 
+import * as _mog_kernel_bridges from '@mog/kernel/bridges';
+
 
 
 
@@ -26,6 +28,48 @@ export type IEventBus = any;
  */
 declare function save(wb: Workbook, path: string): Promise<void>;
 
+interface OverviewResult {
+    workbook: {
+        methods: string[];
+        subApis: string[];
+    };
+    worksheet: {
+        methods: string[];
+        subApis: string[];
+    };
+}
+interface MethodSummary {
+    name: string;
+    signature: string;
+    docstring: string;
+    tags: string[];
+}
+interface InterfaceResult {
+    name: string;
+    path: string;
+    docstring: string;
+    methods: MethodSummary[];
+}
+interface MethodResult {
+    name: string;
+    path: string;
+    signature: string;
+    docstring: string;
+    tags: string[];
+    types: Record<string, TypeResult>;
+}
+interface TypeResult {
+    name: string;
+    definition?: string;
+    isEnum?: boolean;
+    values?: Record<string, string>;
+    docstring?: string;
+}
+type DescribeResult = OverviewResult | InterfaceResult | MethodResult | TypeResult | null;
+declare const api: {
+    describe: (path?: string) => DescribeResult;
+};
+
 
 /**
  * A spreadsheet workbook — the primary API for all spreadsheet operations.
@@ -221,6 +265,19 @@ interface NapiAddonModule {
 /**
  * Options for creating a headless spreadsheet engine.
  */
+/**
+ * A code-executor factory compatible with WorkbookImpl.setCodeExecutorFactory().
+ * Engine layers supply this to wire a VM executor without circular dependencies.
+ *
+ * The factory receives the HeadlessEngine so it can access the workbook/context.
+ * It returns an object whose `execute` method runs agent code and returns the
+ * contract CodeExecutionResult.
+ */
+type HeadlessCodeExecutorFactory = (engine: HeadlessEngine) => {
+    execute(code: string, options?: CodeExecutionOptions): Promise<CodeExecutionResult>;
+    cancelExecution?(executionId: string): void;
+    dispose(): void;
+};
 interface HeadlessOptions {
     /** Pre-loaded napi addon module (the object returned by require('compute-core-napi.node')) */
     computeAddon: NapiAddonModule;
@@ -228,6 +285,16 @@ interface HeadlessOptions {
     docId?: string;
     /** XLSX buffer to import on boot (triggers hydrating state) */
     xlsxSource?: Buffer;
+    /**
+     * Optional code-executor factory.  When provided, `wb.executeCode()` will
+     * work by delegating to the executor returned by this factory.
+     * The factory is called lazily on the first `executeCode()` invocation.
+     */
+    codeExecutorFactory?: HeadlessCodeExecutorFactory;
+    /** Pre-built WorkbookSnapshot to initialize the engine from (for collaboration).
+     *  When provided, the engine is created with this snapshot instead of an empty one.
+     *  This ensures the engine shares the same CellIds as the source engine. */
+    initialSnapshot?: Record<string, unknown>;
 }
 /**
  * Thin shim that delegates to DocumentFactory with `{ environment: 'headless' }`.
@@ -252,6 +319,9 @@ declare class HeadlessLifecycleSystem {
     /**
      * Create a new blank document.
      * Delegates to DocumentFactory.create() with headless environment.
+     *
+     * If `initialSnapshot` is set on options, creates the engine from that snapshot
+     * instead of an empty one (for collaboration — ensures same CellIds as origin).
      */
     create(docId: string): Promise<void>;
     /**
@@ -310,6 +380,10 @@ declare class HeadlessEngine {
      * @see contracts/src/api/ — Interface definitions
      */
     get workbook(): Workbook;
+    /**
+     * @internal Access the WorkbookInternal for infrastructure wiring (e.g. code executor).
+     */
+    get _workbookInternal(): WorkbookInternal;
     /**
      * Initialize the workbook instance asynchronously.
      * Must be called after construction and before accessing `workbook`.
@@ -374,4 +448,119 @@ declare class HeadlessEngine {
  */
 declare function createHeadlessEngine(options: HeadlessOptions): Promise<HeadlessEngine>;
 
-export { HeadlessEngine, type HeadlessOptions, type NapiAddonModule, createHeadlessEngine, save };
+type SyncMode = 'immediate' | 'batch' | 'manual';
+interface LockScope {
+    type: 'sheet' | 'workbook';
+    sheetId?: string;
+}
+interface Lock {
+    id: string;
+    owner: string;
+    scope: LockScope;
+}
+interface CollaborativeEngineOptions {
+    /** Pre-loaded napi addon module. */
+    computeAddon: NapiAddonModule;
+    /** Coordinator handle (from coordinator_create). If not provided, one is created. */
+    coordinatorHandle?: number;
+    /** How sync is triggered. Default: 'immediate'. */
+    syncMode?: SyncMode;
+    /** For batch mode: flush after N mutations. Default: 10. */
+    batchSize?: number;
+    /** XLSX buffer to import on boot. */
+    xlsxSource?: Buffer;
+    /** Participant ID. Defaults to random UUID. */
+    participantId?: string;
+    /** Document ID. Defaults to random UUID. */
+    docId?: string;
+}
+interface FlushResult {
+    serverDiff: number[];
+    ok: boolean;
+}
+interface SyncResult {
+    pushed: boolean;
+    pulled: boolean;
+}
+declare class CollaborativeEngine {
+    private readonly _inner;
+    private readonly _coordinator;
+    private readonly _participantId;
+    private readonly _syncMode;
+    private readonly _batchSize;
+    private _pendingMutations;
+    private _touchedSheets;
+    private _disposed;
+    private _ownsCoordinator;
+    /** @internal — use CollaborativeEngine.create() */
+    private constructor();
+    static create(options: CollaborativeEngineOptions): Promise<CollaborativeEngine>;
+    /**
+     * Create a CollaborativeEngine from the coordinator's current Yrs state.
+     *
+     * Used for the 2nd, 3rd, ... participants. The coordinator already has state
+     * pushed by the first participant. This method:
+     * 1. Gets the coordinator's Yrs state bytes
+     * 2. Converts to a WorkbookSnapshot via yrs_state_to_snapshot_json (NAPI)
+     * 3. Creates a HeadlessEngine initialized from that snapshot (same CellIds)
+     * 4. Pushes/pulls to align Yrs docs with the coordinator
+     */
+    static createFromCoordinator(options: {
+        computeAddon: NapiAddonModule;
+        coordinatorHandle: number;
+        syncMode?: SyncMode;
+        participantId?: string;
+    }): Promise<CollaborativeEngine>;
+    /** The standard Workbook API. Agents use this. */
+    get workbook(): Workbook;
+    /** Convenience: active worksheet. */
+    get ws(): Worksheet;
+    /** This engine's participant ID. */
+    get participantId(): string;
+    /** The coordinator handle (for sharing between engines). */
+    get coordinatorHandle(): number;
+    /** Current sync mode. */
+    get syncMode(): SyncMode;
+    /** Access to the underlying compute bridge (for sync operations). */
+    get computeBridge(): _mog_kernel_bridges.ComputeBridge;
+    /** Track that a sheet was touched (for lock validation). */
+    trackSheetTouch(sheetId: string): void;
+    /**
+     * Push local changes to the coordinator.
+     * In manual mode, call this explicitly. In immediate mode, auto-called.
+     */
+    flush(): Promise<FlushResult>;
+    /**
+     * Pull remote changes from the coordinator.
+     */
+    pull(): Promise<void>;
+    /**
+     * Full sync cycle: push local changes, then pull remote changes.
+     */
+    sync(): Promise<SyncResult>;
+    /** Acquire a lock. Returns lock ID. */
+    lock(scope: LockScope, ttlSeconds?: number): Promise<string>;
+    /** Release a lock. */
+    unlock(lockId: string): Promise<void>;
+    /** List all active locks. */
+    locks(): Promise<Lock[]>;
+    /** Dispose the engine — leave coordinator, release locks, dispose engine. */
+    dispose(): Promise<void>;
+}
+/**
+ * Create a coordinator and N collaborative engines sharing it.
+ * All engines use manual sync mode (for test scenarios).
+ */
+declare function createCollaborativeGroup(addon: NapiAddonModule, count: number, options?: {
+    syncMode?: SyncMode;
+    xlsxSource?: Buffer;
+}): Promise<{
+    engines: CollaborativeEngine[];
+    coordinatorHandle: number;
+    /** Sync all engines: each flushes then pulls. */
+    sync: () => Promise<void>;
+    /** Dispose all engines and the coordinator. */
+    dispose: () => Promise<void>;
+}>;
+
+export { type Lock as CollabLock, type LockScope as CollabLockScope, CollaborativeEngine, type CollaborativeEngineOptions, type DescribeResult, type HeadlessCodeExecutorFactory, HeadlessEngine, type HeadlessOptions, type InterfaceResult, type MethodResult, type MethodSummary, type NapiAddonModule, type OverviewResult, type SyncMode, type TypeResult, api, createCollaborativeGroup, createHeadlessEngine, save };

package/dist/index.d.ts

@@ -17,6 +17,8 @@ export type IEventBus = any;
 
 
 
+import * as _mog_kernel_bridges from '@mog/kernel/bridges';
+
 
 
 
@@ -26,6 +28,48 @@ export type IEventBus = any;
  */
 declare function save(wb: Workbook, path: string): Promise<void>;
 
+interface OverviewResult {
+    workbook: {
+        methods: string[];
+        subApis: string[];
+    };
+    worksheet: {
+        methods: string[];
+        subApis: string[];
+    };
+}
+interface MethodSummary {
+    name: string;
+    signature: string;
+    docstring: string;
+    tags: string[];
+}
+interface InterfaceResult {
+    name: string;
+    path: string;
+    docstring: string;
+    methods: MethodSummary[];
+}
+interface MethodResult {
+    name: string;
+    path: string;
+    signature: string;
+    docstring: string;
+    tags: string[];
+    types: Record<string, TypeResult>;
+}
+interface TypeResult {
+    name: string;
+    definition?: string;
+    isEnum?: boolean;
+    values?: Record<string, string>;
+    docstring?: string;
+}
+type DescribeResult = OverviewResult | InterfaceResult | MethodResult | TypeResult | null;
+declare const api: {
+    describe: (path?: string) => DescribeResult;
+};
+
 
 /**
  * A spreadsheet workbook — the primary API for all spreadsheet operations.
@@ -221,6 +265,19 @@ interface NapiAddonModule {
 /**
  * Options for creating a headless spreadsheet engine.
  */
+/**
+ * A code-executor factory compatible with WorkbookImpl.setCodeExecutorFactory().
+ * Engine layers supply this to wire a VM executor without circular dependencies.
+ *
+ * The factory receives the HeadlessEngine so it can access the workbook/context.
+ * It returns an object whose `execute` method runs agent code and returns the
+ * contract CodeExecutionResult.
+ */
+type HeadlessCodeExecutorFactory = (engine: HeadlessEngine) => {
+    execute(code: string, options?: CodeExecutionOptions): Promise<CodeExecutionResult>;
+    cancelExecution?(executionId: string): void;
+    dispose(): void;
+};
 interface HeadlessOptions {
     /** Pre-loaded napi addon module (the object returned by require('compute-core-napi.node')) */
     computeAddon: NapiAddonModule;
@@ -228,6 +285,16 @@ interface HeadlessOptions {
     docId?: string;
     /** XLSX buffer to import on boot (triggers hydrating state) */
     xlsxSource?: Buffer;
+    /**
+     * Optional code-executor factory.  When provided, `wb.executeCode()` will
+     * work by delegating to the executor returned by this factory.
+     * The factory is called lazily on the first `executeCode()` invocation.
+     */
+    codeExecutorFactory?: HeadlessCodeExecutorFactory;
+    /** Pre-built WorkbookSnapshot to initialize the engine from (for collaboration).
+     *  When provided, the engine is created with this snapshot instead of an empty one.
+     *  This ensures the engine shares the same CellIds as the source engine. */
+    initialSnapshot?: Record<string, unknown>;
 }
 /**
  * Thin shim that delegates to DocumentFactory with `{ environment: 'headless' }`.
@@ -252,6 +319,9 @@ declare class HeadlessLifecycleSystem {
     /**
      * Create a new blank document.
      * Delegates to DocumentFactory.create() with headless environment.
+     *
+     * If `initialSnapshot` is set on options, creates the engine from that snapshot
+     * instead of an empty one (for collaboration — ensures same CellIds as origin).
      */
     create(docId: string): Promise<void>;
     /**
@@ -310,6 +380,10 @@ declare class HeadlessEngine {
      * @see contracts/src/api/ — Interface definitions
      */
     get workbook(): Workbook;
+    /**
+     * @internal Access the WorkbookInternal for infrastructure wiring (e.g. code executor).
+     */
+    get _workbookInternal(): WorkbookInternal;
     /**
      * Initialize the workbook instance asynchronously.
      * Must be called after construction and before accessing `workbook`.
@@ -374,4 +448,119 @@ declare class HeadlessEngine {
  */
 declare function createHeadlessEngine(options: HeadlessOptions): Promise<HeadlessEngine>;
 
-export { HeadlessEngine, type HeadlessOptions, type NapiAddonModule, createHeadlessEngine, save };
+type SyncMode = 'immediate' | 'batch' | 'manual';
+interface LockScope {
+    type: 'sheet' | 'workbook';
+    sheetId?: string;
+}
+interface Lock {
+    id: string;
+    owner: string;
+    scope: LockScope;
+}
+interface CollaborativeEngineOptions {
+    /** Pre-loaded napi addon module. */
+    computeAddon: NapiAddonModule;
+    /** Coordinator handle (from coordinator_create). If not provided, one is created. */
+    coordinatorHandle?: number;
+    /** How sync is triggered. Default: 'immediate'. */
+    syncMode?: SyncMode;
+    /** For batch mode: flush after N mutations. Default: 10. */
+    batchSize?: number;
+    /** XLSX buffer to import on boot. */
+    xlsxSource?: Buffer;
+    /** Participant ID. Defaults to random UUID. */
+    participantId?: string;
+    /** Document ID. Defaults to random UUID. */
+    docId?: string;
+}
+interface FlushResult {
+    serverDiff: number[];
+    ok: boolean;
+}
+interface SyncResult {
+    pushed: boolean;
+    pulled: boolean;
+}
+declare class CollaborativeEngine {
+    private readonly _inner;
+    private readonly _coordinator;
+    private readonly _participantId;
+    private readonly _syncMode;
+    private readonly _batchSize;
+    private _pendingMutations;
+    private _touchedSheets;
+    private _disposed;
+    private _ownsCoordinator;
+    /** @internal — use CollaborativeEngine.create() */
+    private constructor();
+    static create(options: CollaborativeEngineOptions): Promise<CollaborativeEngine>;
+    /**
+     * Create a CollaborativeEngine from the coordinator's current Yrs state.
+     *
+     * Used for the 2nd, 3rd, ... participants. The coordinator already has state
+     * pushed by the first participant. This method:
+     * 1. Gets the coordinator's Yrs state bytes
+     * 2. Converts to a WorkbookSnapshot via yrs_state_to_snapshot_json (NAPI)
+     * 3. Creates a HeadlessEngine initialized from that snapshot (same CellIds)
+     * 4. Pushes/pulls to align Yrs docs with the coordinator
+     */
+    static createFromCoordinator(options: {
+        computeAddon: NapiAddonModule;
+        coordinatorHandle: number;
+        syncMode?: SyncMode;
+        participantId?: string;
+    }): Promise<CollaborativeEngine>;
+    /** The standard Workbook API. Agents use this. */
+    get workbook(): Workbook;
+    /** Convenience: active worksheet. */
+    get ws(): Worksheet;
+    /** This engine's participant ID. */
+    get participantId(): string;
+    /** The coordinator handle (for sharing between engines). */
+    get coordinatorHandle(): number;
+    /** Current sync mode. */
+    get syncMode(): SyncMode;
+    /** Access to the underlying compute bridge (for sync operations). */
+    get computeBridge(): _mog_kernel_bridges.ComputeBridge;
+    /** Track that a sheet was touched (for lock validation). */
+    trackSheetTouch(sheetId: string): void;
+    /**
+     * Push local changes to the coordinator.
+     * In manual mode, call this explicitly. In immediate mode, auto-called.
+     */
+    flush(): Promise<FlushResult>;
+    /**
+     * Pull remote changes from the coordinator.
+     */
+    pull(): Promise<void>;
+    /**
+     * Full sync cycle: push local changes, then pull remote changes.
+     */
+    sync(): Promise<SyncResult>;
+    /** Acquire a lock. Returns lock ID. */
+    lock(scope: LockScope, ttlSeconds?: number): Promise<string>;
+    /** Release a lock. */
+    unlock(lockId: string): Promise<void>;
+    /** List all active locks. */
+    locks(): Promise<Lock[]>;
+    /** Dispose the engine — leave coordinator, release locks, dispose engine. */
+    dispose(): Promise<void>;
+}
+/**
+ * Create a coordinator and N collaborative engines sharing it.
+ * All engines use manual sync mode (for test scenarios).
+ */
+declare function createCollaborativeGroup(addon: NapiAddonModule, count: number, options?: {
+    syncMode?: SyncMode;
+    xlsxSource?: Buffer;
+}): Promise<{
+    engines: CollaborativeEngine[];
+    coordinatorHandle: number;
+    /** Sync all engines: each flushes then pulls. */
+    sync: () => Promise<void>;
+    /** Dispose all engines and the coordinator. */
+    dispose: () => Promise<void>;
+}>;
+
+export { type Lock as CollabLock, type LockScope as CollabLockScope, CollaborativeEngine, type CollaborativeEngineOptions, type DescribeResult, type HeadlessCodeExecutorFactory, HeadlessEngine, type HeadlessOptions, type InterfaceResult, type MethodResult, type MethodSummary, type NapiAddonModule, type OverviewResult, type SyncMode, type TypeResult, api, createCollaborativeGroup, createHeadlessEngine, save };