@superdoc/sdk 2.6.0 → 2.8.0

package/dist/runtime/embedded-platform.js

@@ -0,0 +1,99 @@
+import { chmodSync, existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { SDK_VERSION } from './sdk-version.generated.js';
+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.
+ *
+ * Resolution starts from the installed SDK so pnpm's isolated optional
+ * dependency remains visible after the SDK itself is bundled. `require.resolve`
+ * can also fall back to NODE_PATH, so the version check prevents a host binary
+ * from an unrelated SDK version in a flat store from satisfying this lookup.
+ * 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 sdkRequire;
+    try {
+        sdkRequire = createRequire(require.resolve('@superdoc/sdk'));
+    }
+    catch {
+        sdkRequire = require;
+    }
+    let binaryPath;
+    try {
+        binaryPath = sdkRequire.resolve(`${pkg}/bin/${binaryName}`);
+    }
+    catch {
+        return null;
+    }
+    try {
+        const platformVersion = sdkRequire(sdkRequire.resolve(`${pkg}/package.json`)).version;
+        if (platformVersion !== SDK_VERSION)
+            return null;
+    }
+    catch {
+        // An unreadable platform manifest 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

@@ -23,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
@@ -83,9 +98,15 @@ class HostTransport {
     pending = new Map();
     nextRequestId = 1;
     connecting = null;
+    disposePromise = null;
+    terminalDisposalError = null;
     stopping = false;
+    activeCalls = new Set();
     hostFeatures = new Set();
     documentRpcSessions = new Set();
+    dirtyDocumentRpcSessions = new Set();
+    documentRpcMutationStates = new Map();
+    indeterminateDiscardCloses = new Set();
     constructor(options) {
         this.hostBin = options.hostBin;
         this.processMode = options.processMode ?? 'cli';
@@ -101,22 +122,48 @@ class HostTransport {
                 details: { defaultChangeMode: options.defaultChangeMode },
             });
         }
-        this.defaultChangeMode = options.defaultChangeMode;
+        this.defaultChangeMode = options.defaultChangeMode ?? undefined;
         this.user = options.user;
-        this.documentRpcEnabled = documentRpc.documentRpcEnabled(options.env);
-        if (this.processMode === 'document' && !this.documentRpcEnabled) {
-            throw new errors.SuperDocCliError('SUPERDOC_SDK_DOCUMENT_HOST_BIN requires SUPERDOC_SDK_DOCUMENT_RPC=1.', {
-                code: 'INVALID_ARGUMENT',
-            });
-        }
+        this.documentRpcEnabled = this.processMode === 'document' || documentRpc.documentRpcEnabled(options.env);
     }
     async connect() {
-        await this.ensureConnected();
+        await this.runWhileActive(() => this.ensureConnected());
     }
     async dispose() {
-        if (!this.child)
+        if (this.disposePromise)
+            return this.disposePromise;
+        if (this.terminalDisposalError)
+            throw this.terminalDisposalError;
+        if (!this.child && !this.connecting && this.activeCalls.size === 0)
             return;
         this.stopping = true;
+        const disposal = this.disposeAfterActiveCalls();
+        this.disposePromise = disposal;
+        try {
+            await disposal;
+        }
+        finally {
+            if (this.disposePromise === disposal)
+                this.disposePromise = null;
+            this.stopping = false;
+        }
+    }
+    async disposeAfterActiveCalls() {
+        await Promise.allSettled(Array.from(this.activeCalls));
+        if (this.terminalDisposalError)
+            throw this.terminalDisposalError;
+        if (!this.child)
+            return;
+        try {
+            await this.reconcileIndeterminateDiscardCloses();
+            await this.persistDirtyDocumentRpcSessions();
+        }
+        catch (error) {
+            if (!this.child && error instanceof errors.SuperDocCliError) {
+                this.terminalDisposalError = error;
+            }
+            throw error;
+        }
         const child = this.child;
         try {
             await this.sendJsonRpcRequest('host.shutdown', {}, this.shutdownTimeoutMs);
@@ -135,29 +182,80 @@ class HostTransport {
             });
         });
         this.cleanupProcess(null);
-        this.stopping = false;
     }
     async invoke(operation, params = {}, options = {}) {
+        return this.runWhileActive(() => this.invokeWhileActive(operation, params, options));
+    }
+    async invokeWhileActive(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.user === undefined &&
+            (this.defaultChangeMode === undefined || this.hostFeatures.has(documentRpc.DOCUMENT_RPC_DEFAULT_CHANGE_MODE_FEATURE)) &&
             operation.operationId === 'doc.open' &&
-            documentRpc.canOpenWithDocumentRpc(params, options)) {
-            const opened = documentRpc.buildDocumentOpenParams(params);
-            const response = await this.sendJsonRpcRequest('document.open', opened.params, this.resolveWatchdogTimeout(options.timeoutMs));
+            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);
+            this.indeterminateDiscardCloses.delete(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);
-            const response = await this.sendJsonRpcRequest(request.method, request.params, this.resolveWatchdogTimeout(options.timeoutMs));
-            const result = documentRpc.mapDocumentLifecycleResult(operation.operationId, response, sessionId);
-            if (operation.operationId === 'doc.close')
+            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 documentOperation = operation;
+            const requestOptions = typeof request.params.options === 'object' &&
+                request.params.options !== null &&
+                !Array.isArray(request.params.options)
+                ? request.params.options
+                : undefined;
+            const tracksMutation = request.method === 'document.invoke' && documentOperation.mutates === true && requestOptions?.dryRun !== true;
+            if (tracksMutation)
+                this.beginDocumentRpcMutation(sessionId);
+            let result;
+            try {
+                const response = await this.sendJsonRpcRequest(request.method, request.params, this.resolveWatchdogTimeout(options.timeoutMs), { requestTimeoutMs });
+                result = documentRpc.mapDocumentLifecycleResult(operation.operationId, response, sessionId, operation.operationId === 'doc.save' ? request.params.path === undefined : undefined);
+            }
+            catch (error) {
+                if (tracksMutation) {
+                    const indeterminate = error instanceof errors.SuperDocCliError && ['TIMEOUT', 'HOST_TIMEOUT', 'HOST_DISCONNECTED'].includes(error.code);
+                    this.settleDocumentRpcMutation(sessionId, indeterminate ? 'indeterminate' : 'not-applied');
+                }
+                if (operation.operationId === 'doc.close' &&
+                    request.params.discard === true &&
+                    error instanceof errors.SuperDocCliError &&
+                    error.code === 'TIMEOUT') {
+                    this.indeterminateDiscardCloses.add(sessionId);
+                }
+                throw error;
+            }
+            if (tracksMutation) {
+                const failedReceipt = typeof result === 'object' &&
+                    result !== null &&
+                    !Array.isArray(result) &&
+                    result.success === false;
+                this.settleDocumentRpcMutation(sessionId, failedReceipt ? 'not-applied' : 'applied');
+            }
+            if (operation.operationId === 'doc.close') {
                 this.documentRpcSessions.delete(sessionId);
+                this.clearDirtyDocumentRpcSession(sessionId);
+                this.indeterminateDiscardCloses.delete(sessionId);
+            }
+            else if (operation.operationId === 'doc.save') {
+                if (request.params.mode === undefined || request.params.mode === 'review-preserving') {
+                    this.markDocumentRpcSessionSaved(sessionId);
+                }
+            }
             return result;
         }
         if (this.processMode === 'document') {
@@ -166,6 +264,18 @@ class HostTransport {
                 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);
@@ -180,7 +290,21 @@ class HostTransport {
             });
         }
         const resultRecord = response;
-        return resultRecord.data;
+        return mapCliInvocationResult(operation, resultRecord.data);
+    }
+    runWhileActive(start) {
+        if (this.terminalDisposalError) {
+            return Promise.reject(this.terminalDisposalError);
+        }
+        if (this.stopping) {
+            return Promise.reject(new errors.SuperDocCliError('Host is disposing.', {
+                code: 'HOST_DISCONNECTED',
+            }));
+        }
+        const activeCall = start();
+        this.activeCalls.add(activeCall);
+        void activeCall.then(() => this.activeCalls.delete(activeCall), () => this.activeCalls.delete(activeCall));
+        return activeCall;
     }
     async ensureConnected() {
         if (this.connecting) {
@@ -206,7 +330,7 @@ class HostTransport {
         const child = node_child_process.spawn(command, args, {
             env: {
                 ...process.env,
-                ...(this.env ?? {}),
+                ...this.env,
             },
             stdio: ['pipe', 'pipe', 'pipe'],
         });
@@ -234,7 +358,7 @@ class HostTransport {
             }));
         });
         child.on('close', (code, signal) => {
-            if (this.stopping) {
+            if (this.stopping && this.dirtyDocumentRpcSessions.size === 0) {
                 this.cleanupProcess(null);
                 return;
             }
@@ -285,7 +409,13 @@ class HostTransport {
                 details: { features },
             });
         }
-        const requiredFeatures = this.processMode === 'document' ? DOCUMENT_HOST_REQUIRED_FEATURES : CLI_HOST_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}`, {
@@ -301,7 +431,79 @@ class HostTransport {
     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 },
+        });
+    }
+    beginDocumentRpcMutation(sessionId) {
+        const state = this.documentRpcMutationStates.get(sessionId) ?? {
+            confirmedDirty: this.dirtyDocumentRpcSessions.has(sessionId),
+            pendingCount: 0,
+        };
+        state.pendingCount += 1;
+        this.documentRpcMutationStates.set(sessionId, state);
+        this.dirtyDocumentRpcSessions.add(sessionId);
+    }
+    settleDocumentRpcMutation(sessionId, outcome) {
+        const state = this.documentRpcMutationStates.get(sessionId);
+        if (!state)
+            return;
+        state.pendingCount = Math.max(0, state.pendingCount - 1);
+        if (outcome !== 'not-applied')
+            state.confirmedDirty = true;
+        if (state.confirmedDirty || state.pendingCount > 0) {
+            this.dirtyDocumentRpcSessions.add(sessionId);
+            return;
+        }
+        this.clearDirtyDocumentRpcSession(sessionId);
+    }
+    clearDirtyDocumentRpcSession(sessionId) {
+        this.dirtyDocumentRpcSessions.delete(sessionId);
+        this.documentRpcMutationStates.delete(sessionId);
+    }
+    markDocumentRpcSessionSaved(sessionId) {
+        const state = this.documentRpcMutationStates.get(sessionId);
+        if (!state || state.pendingCount === 0) {
+            this.clearDirtyDocumentRpcSession(sessionId);
+            return;
+        }
+        state.confirmedDirty = false;
+        this.dirtyDocumentRpcSessions.add(sessionId);
+    }
+    async persistDirtyDocumentRpcSessions() {
+        if (this.dirtyDocumentRpcSessions.size === 0)
+            return;
+        if (!this.hostFeatures.has(documentRpc.DOCUMENT_RPC_SOURCE_SAVE_FEATURE)) {
+            throw new errors.SuperDocCliError('Document host cannot persist dirty sessions during client disposal because it does not support source saves.', {
+                code: 'DOCUMENT_RPC_INPUT_UNSUPPORTED',
+                details: { feature: documentRpc.DOCUMENT_RPC_SOURCE_SAVE_FEATURE },
+            });
+        }
+        for (const sessionId of this.dirtyDocumentRpcSessions) {
+            const response = await this.sendJsonRpcRequest('document.save', { sessionId }, this.resolveWatchdogTimeout(undefined));
+            documentRpc.mapDocumentLifecycleResult('doc.save', response, sessionId, true);
+            this.markDocumentRpcSessionSaved(sessionId);
+        }
+    }
+    async reconcileIndeterminateDiscardCloses() {
+        for (const sessionId of this.indeterminateDiscardCloses) {
+            const response = await this.sendJsonRpcRequest('document.close', { sessionId, discard: true }, this.resolveWatchdogTimeout(undefined));
+            documentRpc.mapDocumentLifecycleResult('doc.close', response, sessionId);
+            this.documentRpcSessions.delete(sessionId);
+            this.clearDirtyDocumentRpcSession(sessionId);
+            this.indeterminateDiscardCloses.delete(sessionId);
+        }
+    }
+    async sendJsonRpcRequest(method, params, watchdogTimeoutMs, metadata = {}) {
         const child = this.child;
         if (!child || !child.stdin.writable) {
             throw new errors.SuperDocCliError('Host process is not available.', {
@@ -321,6 +523,7 @@ class HostTransport {
             id,
             method,
             params,
+            ...(metadata.requestTimeoutMs === undefined ? {} : { requestTimeoutMs: metadata.requestTimeoutMs }),
         });
         const promise = new Promise((resolve, reject) => {
             const timer = setTimeout(() => {
@@ -431,8 +634,17 @@ class HostTransport {
         this.cleanupProcess(error);
     }
     cleanupProcess(error) {
+        if (error && this.dirtyDocumentRpcSessions.size > 0 && !this.terminalDisposalError) {
+            this.terminalDisposalError = new errors.SuperDocCliError('Document host disconnected before dirty sessions could be persisted.', {
+                code: 'HOST_DISCONNECTED',
+                details: { causeCode: error.code, causeDetails: error.details },
+            });
+        }
         this.hostFeatures.clear();
         this.documentRpcSessions.clear();
+        this.dirtyDocumentRpcSessions.clear();
+        this.documentRpcMutationStates.clear();
+        this.indeterminateDiscardCloses.clear();
         const child = this.child;
         if (child) {
             child.removeAllListeners();
@@ -460,4 +672,5 @@ 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
@@ -45,20 +46,36 @@ export declare class HostTransport {
     private readonly pending;
     private nextRequestId;
     private connecting;
+    private disposePromise;
+    private terminalDisposalError;
     private stopping;
+    private readonly activeCalls;
     private readonly hostFeatures;
     private readonly documentRpcSessions;
+    private readonly dirtyDocumentRpcSessions;
+    private readonly documentRpcMutationStates;
+    private readonly indeterminateDiscardCloses;
     constructor(options: {
         hostBin: string;
         processMode?: 'cli' | 'document';
     } & SuperDocClientOptions);
     connect(): Promise<void>;
     dispose(): Promise<void>;
+    private disposeAfterActiveCalls;
     invoke<TData = unknown>(operation: OperationSpec, params?: Record<string, unknown>, options?: InvokeOptions): Promise<TData>;
+    private invokeWhileActive;
+    private runWhileActive;
     private ensureConnected;
     private startHostProcess;
     private assertCapabilities;
     private resolveWatchdogTimeout;
+    private resolveDocumentRequestTimeout;
+    private beginDocumentRpcMutation;
+    private settleDocumentRpcMutation;
+    private clearDirtyDocumentRpcSession;
+    private markDocumentRpcSessionSaved;
+    private persistDirtyDocumentRpcSessions;
+    private reconcileIndeterminateDiscardCloses;
     private sendJsonRpcRequest;
     private onStdoutLine;
     private mapJsonRpcError;