logisheets-runtime 1.3.0 → 1.5.0

package/dist/craft.d.ts

@@ -78,15 +78,38 @@ export declare function validateLoadedCrafts(loaded: readonly LoadedCraft[], wb:
  * contract as {@link applyCraftRequest}.
  */
 export declare function applyCraftResponse(loaded: readonly LoadedCraft[], resp: JsonRpcResponse, wb: Workbook): Promise<string[]>;
+/** Application code: a craft's `onValidate` rejected the request's inputs. */
+export declare const RPC_VALIDATION_FAILED = 1001;
 /**
- * A default {@link CraftRegistry} for local dev and tests. Crafts are
- * registered in-process against a fake base url; `importRuntime` just returns
- * the pre-registered module so no network or bundler is involved.
+ * Run one JSON-RPC exchange against a workbook's loaded crafts and return the
+ * reply. This is the generic "run a craft's request/response" primitive — a
+ * host registers it as an RPC method (or task handler) and never re-implements
+ * the exchange. Composes the three hooks in order:
+ *
+ *   1. {@link applyCraftRequest}   — write the request's inputs (`#INVALID_PARAMS` if a craft rejects one),
+ *   2. {@link validateLoadedCrafts} — validate them (`#VALIDATION_FAILED` + the violations if any fail),
+ *   3. {@link applyCraftResponse}  — read the outputs into `result` (`#INTERNAL_ERROR` if a craft errors).
+ *
+ * The crafts define what the exchange does (via their onRequest/onResponse);
+ * this function is entirely craft-agnostic.
+ */
+export declare function runCraftExchange(loaded: readonly LoadedCraft[], wb: Workbook, req: JsonRpcRequest): Promise<JsonRpcResponse>;
+/**
+ * An in-memory {@link CraftRegistry}: crafts are registered in-process with
+ * their already-imported runtime module, so `importRuntime` returns it directly
+ * — no network, bundler, or filesystem. This is the general-purpose registry
+ * for a host that knows its crafts up front (embedding, local dev, tests);
+ * production may instead back the registry with a real HTTP registry.
  */
-export declare class MockCraftRegistry implements CraftRegistry {
+export declare class MemoryCraftRegistry implements CraftRegistry {
     private readonly entries;
-    /** Register a craft's manifest and its already-imported runtime module. */
-    add(craftId: string, manifest: CraftManifest, module: unknown): this;
+    /**
+     * Register a craft by id with its runtime module (a {@link CraftRuntime},
+     * or a module whose default export is one). `manifest` is optional
+     * metadata; the default carries a non-empty `rtJs` so {@link loadCrafts}
+     * imports the module instead of skipping the craft as runtime-less.
+     */
+    add(craftId: string, module: unknown, manifest?: CraftManifest): this;
     getManifest(craftId: string): Promise<CraftManifest | undefined>;
     importRuntime(craftId: string): Promise<unknown | undefined>;
 }

package/dist/craft.js

@@ -13,8 +13,9 @@
 //      imported module *is* the craft's {@link CraftRuntime},
 //   4. call the runtime's `onLoad(state, workbook)` so it can rehydrate.
 //
-// The registry is a seam: production wires it to a real HTTP registry, tests
-// (and local dev) use {@link MockCraftRegistry}.
+// The registry is a seam: production may wire it to a real HTTP registry;
+// embedding hosts, local dev, and tests use the in-process {@link
+// MemoryCraftRegistry}.
 /**
  * The name of the AppData entry the host folds craft/block/interaction state
  * into. Mirrors the envelope written by the browser host on save.
@@ -164,18 +165,68 @@ export async function applyCraftResponse(loaded, resp, wb) {
     }
     return errors;
 }
+// JSON-RPC 2.0 error codes (kept local so this pure-logic module doesn't pull
+// in the HTTP server that also owns them).
+const RPC_INVALID_PARAMS = -32602;
+const RPC_INTERNAL_ERROR = -32603;
+/** Application code: a craft's `onValidate` rejected the request's inputs. */
+export const RPC_VALIDATION_FAILED = 1001;
+function errorResponse(id, code, message, data) {
+    return {
+        jsonrpc: '2.0',
+        id,
+        error: data === undefined ? { code, message } : { code, message, data },
+    };
+}
+/**
+ * Run one JSON-RPC exchange against a workbook's loaded crafts and return the
+ * reply. This is the generic "run a craft's request/response" primitive — a
+ * host registers it as an RPC method (or task handler) and never re-implements
+ * the exchange. Composes the three hooks in order:
+ *
+ *   1. {@link applyCraftRequest}   — write the request's inputs (`#INVALID_PARAMS` if a craft rejects one),
+ *   2. {@link validateLoadedCrafts} — validate them (`#VALIDATION_FAILED` + the violations if any fail),
+ *   3. {@link applyCraftResponse}  — read the outputs into `result` (`#INTERNAL_ERROR` if a craft errors).
+ *
+ * The crafts define what the exchange does (via their onRequest/onResponse);
+ * this function is entirely craft-agnostic.
+ */
+export async function runCraftExchange(loaded, wb, req) {
+    const id = req.id ?? null;
+    const reqErrors = await applyCraftRequest(loaded, req, wb);
+    if (reqErrors.length)
+        return errorResponse(id, RPC_INVALID_PARAMS, reqErrors.join('; '));
+    const violations = await validateLoadedCrafts(loaded, wb);
+    if (violations.length)
+        return errorResponse(id, RPC_VALIDATION_FAILED, 'validation failed', violations);
+    const resp = { jsonrpc: '2.0', id };
+    const respErrors = await applyCraftResponse(loaded, resp, wb);
+    if (respErrors.length)
+        return errorResponse(id, RPC_INTERNAL_ERROR, respErrors.join('; '));
+    return resp;
+}
 /**
- * A default {@link CraftRegistry} for local dev and tests. Crafts are
- * registered in-process against a fake base url; `importRuntime` just returns
- * the pre-registered module so no network or bundler is involved.
+ * An in-memory {@link CraftRegistry}: crafts are registered in-process with
+ * their already-imported runtime module, so `importRuntime` returns it directly
+ * — no network, bundler, or filesystem. This is the general-purpose registry
+ * for a host that knows its crafts up front (embedding, local dev, tests);
+ * production may instead back the registry with a real HTTP registry.
  */
-export class MockCraftRegistry {
+export class MemoryCraftRegistry {
     constructor() {
         this.entries = new Map();
     }
-    /** Register a craft's manifest and its already-imported runtime module. */
-    add(craftId, manifest, module) {
-        this.entries.set(craftId, { manifest, module });
+    /**
+     * Register a craft by id with its runtime module (a {@link CraftRuntime},
+     * or a module whose default export is one). `manifest` is optional
+     * metadata; the default carries a non-empty `rtJs` so {@link loadCrafts}
+     * imports the module instead of skipping the craft as runtime-less.
+     */
+    add(craftId, module, manifest) {
+        this.entries.set(craftId, {
+            manifest: manifest ?? { rtJs: craftId, html: '' },
+            module,
+        });
         return this;
     }
     getManifest(craftId) {

package/dist/enterprise.d.ts

@@ -51,6 +51,16 @@ export interface TaskContext {
 }
 /** A task handler runs one `rpcCall` against an ephemerally-loaded workbook. */
 export type TaskHandler = (ctx: TaskContext) => unknown | Promise<unknown>;
+/**
+ * The standard `compute` task handler: drive the workbook's loaded crafts
+ * through one JSON-RPC exchange (see {@link runCraftExchange}). Generic and
+ * craft-agnostic — the crafts loaded from the workbook's AppData define what
+ * "compute" does via their `onRequest`/`onResponse`; a runtime serving craft
+ * workbooks uses this instead of hand-writing the exchange. `ctx.params` is
+ * forwarded verbatim as the request params (e.g. `{inputs}`) and the JSON-RPC
+ * response envelope is returned.
+ */
+export declare const craftComputeHandler: TaskHandler;
 export interface EnterpriseServerOptions {
     runtime: SpreadsheetRuntime;
     /** Registry to load crafts from. Set after registration via {@link setRegistry}. */

package/dist/enterprise.js

@@ -15,7 +15,7 @@
 // depend on the merged data-gateway craft + engine cell ops (DATA_GATEWAY_CHANGES).
 import { createServer, } from 'node:http';
 import { SpreadsheetRuntime } from './index.js';
-import { loadCrafts, } from './craft.js';
+import { loadCrafts, runCraftExchange, } from './craft.js';
 import { WorkbookWatcher } from './watcher.js';
 export class ControlPlaneClient {
     constructor(opts) {
@@ -102,6 +102,24 @@ export class HttpCraftRegistry {
         }
     }
 }
+/**
+ * The standard `compute` task handler: drive the workbook's loaded crafts
+ * through one JSON-RPC exchange (see {@link runCraftExchange}). Generic and
+ * craft-agnostic — the crafts loaded from the workbook's AppData define what
+ * "compute" does via their `onRequest`/`onResponse`; a runtime serving craft
+ * workbooks uses this instead of hand-writing the exchange. `ctx.params` is
+ * forwarded verbatim as the request params (e.g. `{inputs}`) and the JSON-RPC
+ * response envelope is returned.
+ */
+export const craftComputeHandler = (ctx) => {
+    const req = {
+        jsonrpc: '2.0',
+        id: 1,
+        method: 'compute',
+        params: ctx.params,
+    };
+    return runCraftExchange(ctx.crafts, ctx.workbook, req);
+};
 export class EnterpriseRuntimeServer {
     constructor(opts) {
         this.handlers = new Map();
@@ -110,6 +128,9 @@ export class EnterpriseRuntimeServer {
         this.runtime = opts.runtime;
         this.registry = opts.registry;
         this.secret = opts.secret;
+        // Ship a generic `compute` by default so a craft-serving runtime needs
+        // no bespoke handler; anything in opts.taskHandlers can override it.
+        this.handlers.set('compute', craftComputeHandler);
         for (const [name, h] of Object.entries(opts.taskHandlers ?? {}))
             this.handlers.set(name, h);
     }
@@ -211,7 +232,9 @@ export class EnterpriseRuntimeServer {
             throw new Error(`unknown rpcCall: ${body.rpcCall}`);
         const wb = await this.loadFromUrl(body.workbookUrl);
         try {
-            const crafts = this.registry ? await loadCrafts(wb, this.registry) : [];
+            const crafts = this.registry
+                ? await loadCrafts(wb, this.registry)
+                : [];
             return await handler({ workbook: wb, crafts, params: body.params });
         }
         finally {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "logisheets-runtime",
-    "version": "1.3.0",
+    "version": "1.5.0",
     "description": "Headless LogiSheets spreadsheet runtime for Node — logisheets-core wired to the Node WASM engine. The Node counterpart of the browser app.",
     "type": "module",
     "main": "./dist/index.js",
@@ -18,8 +18,8 @@
     "author": "Jeremy He",
     "license": "MIT",
     "dependencies": {
-        "logisheets": "^1.3.0",
-        "logisheets-core": "^1.3.0"
+        "logisheets": "^1.5.0",
+        "logisheets-core": "^1.5.0"
     },
     "devDependencies": {
         "typescript": "^5.5.0",