@superdoc/sdk 2.5.0 → 2.7.0

package/dist/runtime/embedded-platform.d.ts

@@ -0,0 +1,5 @@
+export type SupportedEmbeddedTarget = 'darwin-arm64' | 'darwin-x64' | 'linux-x64' | 'linux-arm64' | 'windows-x64';
+export declare function resolveEmbeddedTarget(platform?: NodeJS.Platform, arch?: NodeJS.Architecture): SupportedEmbeddedTarget | null;
+export declare function embeddedPlatformPackage(target: SupportedEmbeddedTarget): string;
+export declare function resolveEmbeddedPlatformBinary(target: SupportedEmbeddedTarget, binaryName: string): string | null;
+export declare function ensureEmbeddedExecutable(binaryPath: string): void;

package/dist/runtime/embedded-platform.js

@@ -0,0 +1,93 @@
+import { chmodSync, existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+const require = createRequire(import.meta.url);
+const TARGET_TO_PACKAGE = {
+    'darwin-arm64': '@superdoc/sdk-darwin-arm64',
+    'darwin-x64': '@superdoc/sdk-darwin-x64',
+    'linux-x64': '@superdoc/sdk-linux-x64',
+    'linux-arm64': '@superdoc/sdk-linux-arm64',
+    'windows-x64': '@superdoc/sdk-windows-x64',
+};
+const TARGET_TO_DIR = {
+    'darwin-arm64': 'sdk-darwin-arm64',
+    'darwin-x64': 'sdk-darwin-x64',
+    'linux-x64': 'sdk-linux-x64',
+    'linux-arm64': 'sdk-linux-arm64',
+    'windows-x64': 'sdk-windows-x64',
+};
+export function resolveEmbeddedTarget(platform = process.platform, arch = process.arch) {
+    if (platform === 'darwin' && arch === 'arm64')
+        return 'darwin-arm64';
+    if (platform === 'darwin' && arch === 'x64')
+        return 'darwin-x64';
+    if (platform === 'linux' && arch === 'x64')
+        return 'linux-x64';
+    if (platform === 'linux' && arch === 'arm64')
+        return 'linux-arm64';
+    if (platform === 'win32' && arch === 'x64')
+        return 'windows-x64';
+    return null;
+}
+export function embeddedPlatformPackage(target) {
+    return TARGET_TO_PACKAGE[target];
+}
+/**
+ * The binary shipped inside this package (`platforms/<target>/bin/`). A build
+ * that carries its own host is authoritative — it is the only copy guaranteed
+ * to match this SDK's code — so it is tried before any resolver lookup.
+ */
+function resolveFromPackageLocal(target, binaryName) {
+    const workspacePath = path.resolve(fileURLToPath(new URL('../../platforms', import.meta.url)), TARGET_TO_DIR[target], 'bin', binaryName);
+    return existsSync(workspacePath) ? workspacePath : null;
+}
+/**
+ * Resolve the platform package through Node, and reject a version that is not
+ * this SDK's own.
+ *
+ * `require.resolve` falls back to NODE_PATH, which package managers set to a
+ * flat store directory (pnpm does it for every binary shim). A host binary from
+ * an unrelated SDK version installed anywhere in that store then satisfies this
+ * lookup, and the SDK silently drives a foreign engine: seen in the wild as an
+ * SDK 2.2.1 install executing a hoisted 2.0.0 host, which failed operations the
+ * matching host performs correctly. optionalDependencies pin the platform
+ * package to an exact version, so a mismatch here is never legitimate.
+ */
+function resolveFromPlatformPackage(target, binaryName) {
+    const pkg = TARGET_TO_PACKAGE[target];
+    let binaryPath;
+    try {
+        binaryPath = require.resolve(`${pkg}/bin/${binaryName}`);
+    }
+    catch {
+        return null;
+    }
+    try {
+        const platformVersion = require(require.resolve(`${pkg}/package.json`)).version;
+        const ownVersion = require(fileURLToPath(new URL('../../package.json', import.meta.url))).version;
+        if (platformVersion !== ownVersion)
+            return null;
+    }
+    catch {
+        // Either manifest being unreadable is itself disqualifying: an unverifiable
+        // host is exactly the case this guard exists to reject.
+        return null;
+    }
+    return binaryPath;
+}
+export function resolveEmbeddedPlatformBinary(target, binaryName) {
+    // Package-local first: a self-contained build must never be overridden by
+    // whatever the module resolver happens to find on NODE_PATH.
+    return resolveFromPackageLocal(target, binaryName) ?? resolveFromPlatformPackage(target, binaryName);
+}
+export function ensureEmbeddedExecutable(binaryPath) {
+    if (process.platform === 'win32')
+        return;
+    try {
+        chmodSync(binaryPath, 0o755);
+    }
+    catch {
+        // Non-fatal: spawn() reports the actionable execution error.
+    }
+}

package/dist/runtime/host.cjs

@@ -4,9 +4,11 @@ var node_child_process = require('node:child_process');
 var node_readline = require('node:readline');
 var transportCommon = require('./transport-common.cjs');
 var errors = require('./errors.cjs');
+var documentRpc = require('./document-rpc.cjs');
 
 const HOST_PROTOCOL_VERSION = '1.0';
-const REQUIRED_FEATURES = ['cli.invoke', 'host.shutdown'];
+const CLI_HOST_REQUIRED_FEATURES = ['cli.invoke', 'host.shutdown'];
+const DOCUMENT_HOST_REQUIRED_FEATURES = [...documentRpc.DOCUMENT_RPC_FEATURES, 'host.shutdown'];
 const CHANGE_MODES = ['direct', 'tracked'];
 const FORWARD_HOST_STDERR = typeof process !== 'undefined' && typeof process.env?.SUPERDOC_DEBUG_TEXT_REWRITE === 'string'
     ? process.env.SUPERDOC_DEBUG_TEXT_REWRITE === '1'
@@ -21,6 +23,21 @@ const HOST_DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
 // abort. The buffer absorbs JSON-RPC serialization, stdio drain, and event-
 // loop latency.
 const WATCHDOG_HEADROOM_MS = 5_000;
+function mapCliInvocationResult(operation, value) {
+    const envelopeKey = operation.responseEnvelopeKey;
+    if (envelopeKey === null || envelopeKey === undefined)
+        return value;
+    if (typeof envelopeKey !== 'string' || envelopeKey.length === 0) {
+        throw new errors.SuperDocCliError('Generated operation has invalid response envelope metadata.', {
+            code: 'HOST_PROTOCOL_ERROR',
+            details: { operationId: operation.operationId, responseEnvelopeKey: envelopeKey },
+        });
+    }
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return value;
+    const extracted = value[envelopeKey];
+    return extracted === undefined ? value : extracted;
+}
 /**
  * Builds the argv passed to `spawn` for `superdoc host --stdio`. Propagates
  * `requestTimeoutMs` to the host via `--request-timeout-ms`, since the SDK
@@ -35,6 +52,9 @@ function buildHostSpawnArgs(prefixArgs, options) {
     }
     return args;
 }
+function buildDocumentHostSpawnArgs(prefixArgs) {
+    return [...prefixArgs];
+}
 /**
  * Computes the JS-side watchdog timeout for a single JSON-RPC request.
  *
@@ -60,11 +80,10 @@ function resolveJsWatchdogTimeout(watchdogTimeoutMs, requestTimeoutMs, timeoutMs
     }
     return Math.max(watchdogTimeoutMs, HOST_DEFAULT_REQUEST_TIMEOUT_MS + WATCHDOG_HEADROOM_MS);
 }
-/**
- * Transport that communicates with a long-lived CLI host process over JSON-RPC stdio.
- */
+/** Transport for the legacy CLI host or the structured document host. */
 class HostTransport {
-    cliBin;
+    hostBin;
+    processMode;
     env;
     startupTimeoutMs;
     shutdownTimeoutMs;
@@ -73,14 +92,18 @@ class HostTransport {
     maxQueueDepth;
     defaultChangeMode;
     user;
+    documentRpcEnabled;
     child = null;
     stdoutReader = null;
     pending = new Map();
     nextRequestId = 1;
     connecting = null;
     stopping = false;
+    hostFeatures = new Set();
+    documentRpcSessions = new Set();
     constructor(options) {
-        this.cliBin = options.cliBin;
+        this.hostBin = options.hostBin;
+        this.processMode = options.processMode ?? 'cli';
         this.env = options.env;
         this.startupTimeoutMs = options.startupTimeoutMs ?? 5_000;
         this.shutdownTimeoutMs = options.shutdownTimeoutMs ?? 5_000;
@@ -93,8 +116,9 @@ class HostTransport {
                 details: { defaultChangeMode: options.defaultChangeMode },
             });
         }
-        this.defaultChangeMode = options.defaultChangeMode;
+        this.defaultChangeMode = options.defaultChangeMode ?? undefined;
         this.user = options.user;
+        this.documentRpcEnabled = this.processMode === 'document' || documentRpc.documentRpcEnabled(options.env);
     }
     async connect() {
         await this.ensureConnected();
@@ -125,6 +149,53 @@ class HostTransport {
     }
     async invoke(operation, params = {}, options = {}) {
         await this.ensureConnected();
+        const shouldOpenThroughCliTimeoutFallback = this.processMode === 'cli' &&
+            (this.requestTimeoutMs !== undefined ||
+                (options.timeoutMs !== undefined && !this.hostFeatures.has(documentRpc.DOCUMENT_RPC_REQUEST_TIMEOUT_FEATURE)));
+        if (this.documentRpcEnabled &&
+            documentRpc.supportsDocumentRpc(this.hostFeatures) &&
+            (this.defaultChangeMode === undefined || this.hostFeatures.has(documentRpc.DOCUMENT_RPC_DEFAULT_CHANGE_MODE_FEATURE)) &&
+            operation.operationId === 'doc.open' &&
+            documentRpc.canOpenWithDocumentRpc(params, options) &&
+            !shouldOpenThroughCliTimeoutFallback) {
+            const opened = documentRpc.buildDocumentOpenParams(params, this.user, this.defaultChangeMode);
+            const requestTimeoutMs = this.resolveDocumentRequestTimeout(options.timeoutMs);
+            const response = await this.sendJsonRpcRequest('document.open', opened.params, this.resolveWatchdogTimeout(options.timeoutMs), { requestTimeoutMs });
+            const result = documentRpc.mapDocumentOpenResult(response, opened.sessionId, params.doc);
+            this.documentRpcSessions.add(opened.sessionId);
+            return result;
+        }
+        const sessionId = typeof params.sessionId === 'string' ? params.sessionId : undefined;
+        if (sessionId !== undefined && this.documentRpcSessions.has(sessionId)) {
+            const request = documentRpc.buildDocumentInvokeParams(sessionId, operation, params, options, this.hostFeatures);
+            const supportsResponseTimeout = documentRpc.documentRpcRequestSupportsResponseTimeout(operation, request);
+            const requestTimeoutMs = supportsResponseTimeout
+                ? this.resolveDocumentRequestTimeout(options.timeoutMs)
+                : undefined;
+            const response = await this.sendJsonRpcRequest(request.method, request.params, this.resolveWatchdogTimeout(options.timeoutMs), { requestTimeoutMs });
+            const result = documentRpc.mapDocumentLifecycleResult(operation.operationId, response, sessionId, operation.operationId === 'doc.save' ? request.params.path === undefined : undefined);
+            if (operation.operationId === 'doc.close')
+                this.documentRpcSessions.delete(sessionId);
+            return result;
+        }
+        if (this.processMode === 'document') {
+            throw new errors.SuperDocCliError(`Standalone document host does not support ${operation.operationId} through structured RPC v0.`, {
+                code: 'DOCUMENT_RPC_INPUT_UNSUPPORTED',
+                details: { operationId: operation.operationId },
+            });
+        }
+        const cliHostRequestTimeoutMs = this.requestTimeoutMs ?? HOST_DEFAULT_REQUEST_TIMEOUT_MS;
+        if (options.timeoutMs !== undefined && options.timeoutMs > cliHostRequestTimeoutMs) {
+            throw new errors.SuperDocCliError(`CLI host cannot honor timeoutMs=${options.timeoutMs} above its ${cliHostRequestTimeoutMs}ms request ceiling.`, {
+                code: 'DOCUMENT_RPC_INPUT_UNSUPPORTED',
+                details: {
+                    feature: documentRpc.DOCUMENT_RPC_REQUEST_TIMEOUT_FEATURE,
+                    operationId: operation.operationId,
+                    timeoutMs: options.timeoutMs,
+                    hostRequestTimeoutMs: cliHostRequestTimeoutMs,
+                },
+            });
+        }
         const argv = transportCommon.buildOperationArgv(operation, params, options, this.requestTimeoutMs, this.defaultChangeMode, this.user);
         const stdinBase64 = options.stdinBytes ? Buffer.from(options.stdinBytes).toString('base64') : '';
         const watchdogTimeout = this.resolveWatchdogTimeout(options.timeoutMs);
@@ -139,16 +210,16 @@ class HostTransport {
             });
         }
         const resultRecord = response;
-        return resultRecord.data;
+        return mapCliInvocationResult(operation, resultRecord.data);
     }
     async ensureConnected() {
-        if (this.child && !this.child.killed) {
-            return;
-        }
         if (this.connecting) {
             await this.connecting;
             return;
         }
+        if (this.child && !this.child.killed) {
+            return;
+        }
         this.connecting = this.startHostProcess();
         try {
             await this.connecting;
@@ -158,12 +229,14 @@ class HostTransport {
         }
     }
     async startHostProcess() {
-        const { command, prefixArgs } = transportCommon.resolveInvocation(this.cliBin);
-        const args = buildHostSpawnArgs(prefixArgs, { requestTimeoutMs: this.requestTimeoutMs });
+        const { command, prefixArgs } = transportCommon.resolveInvocation(this.hostBin);
+        const args = this.processMode === 'document'
+            ? buildDocumentHostSpawnArgs(prefixArgs)
+            : buildHostSpawnArgs(prefixArgs, { requestTimeoutMs: this.requestTimeoutMs });
         const child = node_child_process.spawn(command, args, {
             env: {
                 ...process.env,
-                ...(this.env ?? {}),
+                ...this.env,
             },
             stdio: ['pipe', 'pipe', 'pipe'],
         });
@@ -242,7 +315,14 @@ class HostTransport {
                 details: { features },
             });
         }
-        for (const requiredFeature of REQUIRED_FEATURES) {
+        const requiredFeatures = this.processMode === 'document'
+            ? [
+                ...DOCUMENT_HOST_REQUIRED_FEATURES,
+                ...(this.defaultChangeMode === undefined ? [] : [documentRpc.DOCUMENT_RPC_DEFAULT_CHANGE_MODE_FEATURE]),
+                ...(this.requestTimeoutMs === undefined ? [] : [documentRpc.DOCUMENT_RPC_REQUEST_TIMEOUT_FEATURE]),
+            ]
+            : CLI_HOST_REQUIRED_FEATURES;
+        for (const requiredFeature of requiredFeatures) {
             if (!features.includes(requiredFeature)) {
                 throw new errors.SuperDocCliError(`Host does not support required feature: ${requiredFeature}`, {
                     code: 'HOST_HANDSHAKE_FAILED',
@@ -250,11 +330,27 @@ class HostTransport {
                 });
             }
         }
+        this.hostFeatures.clear();
+        for (const feature of features)
+            this.hostFeatures.add(feature);
     }
     resolveWatchdogTimeout(timeoutMsOverride) {
         return resolveJsWatchdogTimeout(this.watchdogTimeoutMs, this.requestTimeoutMs, timeoutMsOverride);
     }
-    async sendJsonRpcRequest(method, params, watchdogTimeoutMs) {
+    resolveDocumentRequestTimeout(timeoutMsOverride) {
+        const requestTimeoutMs = timeoutMsOverride ?? this.requestTimeoutMs;
+        if (requestTimeoutMs === undefined)
+            return undefined;
+        if (this.hostFeatures.has(documentRpc.DOCUMENT_RPC_REQUEST_TIMEOUT_FEATURE))
+            return requestTimeoutMs;
+        if (this.processMode === 'cli' && timeoutMsOverride === undefined)
+            return undefined;
+        throw new errors.SuperDocCliError(`Structured document RPC host does not support ${documentRpc.DOCUMENT_RPC_REQUEST_TIMEOUT_FEATURE}.`, {
+            code: 'DOCUMENT_RPC_INPUT_UNSUPPORTED',
+            details: { feature: documentRpc.DOCUMENT_RPC_REQUEST_TIMEOUT_FEATURE },
+        });
+    }
+    async sendJsonRpcRequest(method, params, watchdogTimeoutMs, metadata = {}) {
         const child = this.child;
         if (!child || !child.stdin.writable) {
             throw new errors.SuperDocCliError('Host process is not available.', {
@@ -274,6 +370,7 @@ class HostTransport {
             id,
             method,
             params,
+            ...(metadata.requestTimeoutMs === undefined ? {} : { requestTimeoutMs: metadata.requestTimeoutMs }),
         });
         const promise = new Promise((resolve, reject) => {
             const timer = setTimeout(() => {
@@ -349,6 +446,7 @@ class HostTransport {
         const error = rawError;
         const data = error.data;
         const cliCode = typeof data?.cliCode === 'string' ? data.cliCode : undefined;
+        const domainCode = typeof data?.domainCode === 'string' ? data.domainCode : undefined;
         const cliMessage = typeof data?.message === 'string' ? data.message : undefined;
         const exitCode = typeof data?.exitCode === 'number' ? data.exitCode : undefined;
         if (cliCode) {
@@ -358,6 +456,16 @@ class HostTransport {
                 exitCode,
             });
         }
+        if (domainCode) {
+            return new errors.SuperDocCliError(error.message, {
+                code: domainCode,
+                details: {
+                    ...(data?.details === undefined ? {} : { domainDetails: data.details }),
+                    ...(data?.stage === undefined ? {} : { stage: data.stage }),
+                    ...(data?.byteLength === undefined ? {} : { byteLength: data.byteLength }),
+                },
+            });
+        }
         if (error.code === JSON_RPC_TIMEOUT_CODE) {
             return new errors.SuperDocCliError(error.message, {
                 code: 'TIMEOUT',
@@ -373,6 +481,8 @@ class HostTransport {
         this.cleanupProcess(error);
     }
     cleanupProcess(error) {
+        this.hostFeatures.clear();
+        this.documentRpcSessions.clear();
         const child = this.child;
         if (child) {
             child.removeAllListeners();
@@ -398,5 +508,7 @@ class HostTransport {
 }
 
 exports.HostTransport = HostTransport;
+exports.buildDocumentHostSpawnArgs = buildDocumentHostSpawnArgs;
 exports.buildHostSpawnArgs = buildHostSpawnArgs;
+exports.mapCliInvocationResult = mapCliInvocationResult;
 exports.resolveJsWatchdogTimeout = resolveJsWatchdogTimeout;

package/dist/runtime/host.d.ts

@@ -1,4 +1,5 @@
 import { type InvokeOptions, type OperationSpec, type SuperDocClientOptions } from './transport-common.js';
+export declare function mapCliInvocationResult(operation: OperationSpec, value: unknown): unknown;
 /**
  * Builds the argv passed to `spawn` for `superdoc host --stdio`. Propagates
  * `requestTimeoutMs` to the host via `--request-timeout-ms`, since the SDK
@@ -9,6 +10,7 @@ import { type InvokeOptions, type OperationSpec, type SuperDocClientOptions } fr
 export declare function buildHostSpawnArgs(prefixArgs: readonly string[], options: {
     requestTimeoutMs?: number;
 }): string[];
+export declare function buildDocumentHostSpawnArgs(prefixArgs: readonly string[]): string[];
 /**
  * Computes the JS-side watchdog timeout for a single JSON-RPC request.
  *
@@ -26,11 +28,10 @@ export declare function buildHostSpawnArgs(prefixArgs: readonly string[], option
  * Exported for unit testing.
  */
 export declare function resolveJsWatchdogTimeout(watchdogTimeoutMs: number, requestTimeoutMs: number | undefined, timeoutMsOverride: number | undefined): number;
-/**
- * Transport that communicates with a long-lived CLI host process over JSON-RPC stdio.
- */
+/** Transport for the legacy CLI host or the structured document host. */
 export declare class HostTransport {
-    private readonly cliBin;
+    private readonly hostBin;
+    private readonly processMode;
     private readonly env?;
     private readonly startupTimeoutMs;
     private readonly shutdownTimeoutMs;
@@ -39,14 +40,18 @@ export declare class HostTransport {
     private readonly maxQueueDepth;
     private readonly defaultChangeMode?;
     private readonly user?;
+    private readonly documentRpcEnabled;
     private child;
     private stdoutReader;
     private readonly pending;
     private nextRequestId;
     private connecting;
     private stopping;
+    private readonly hostFeatures;
+    private readonly documentRpcSessions;
     constructor(options: {
-        cliBin: string;
+        hostBin: string;
+        processMode?: 'cli' | 'document';
     } & SuperDocClientOptions);
     connect(): Promise<void>;
     dispose(): Promise<void>;
@@ -55,6 +60,7 @@ export declare class HostTransport {
     private startHostProcess;
     private assertCapabilities;
     private resolveWatchdogTimeout;
+    private resolveDocumentRequestTimeout;
     private sendJsonRpcRequest;
     private onStdoutLine;
     private mapJsonRpcError;