@superdoc-dev/sdk 1.0.0-alpha.4 → 1.0.0-alpha.41

package/dist/runtime/host.cjs

@@ -0,0 +1,352 @@
+'use strict';
+
+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');
+
+const HOST_PROTOCOL_VERSION = '1.0';
+const REQUIRED_FEATURES = ['cli.invoke', 'host.shutdown'];
+const CHANGE_MODES = ['direct', 'tracked'];
+const JSON_RPC_TIMEOUT_CODE = -32011;
+/**
+ * Transport that communicates with a long-lived CLI host process over JSON-RPC stdio.
+ */
+class HostTransport {
+    cliBin;
+    env;
+    startupTimeoutMs;
+    shutdownTimeoutMs;
+    requestTimeoutMs;
+    watchdogTimeoutMs;
+    maxQueueDepth;
+    defaultChangeMode;
+    user;
+    child = null;
+    stdoutReader = null;
+    pending = new Map();
+    nextRequestId = 1;
+    connecting = null;
+    stopping = false;
+    constructor(options) {
+        this.cliBin = options.cliBin;
+        this.env = options.env;
+        this.startupTimeoutMs = options.startupTimeoutMs ?? 5_000;
+        this.shutdownTimeoutMs = options.shutdownTimeoutMs ?? 5_000;
+        this.requestTimeoutMs = options.requestTimeoutMs;
+        this.watchdogTimeoutMs = options.watchdogTimeoutMs ?? 30_000;
+        this.maxQueueDepth = options.maxQueueDepth ?? 100;
+        if (options.defaultChangeMode != null && !CHANGE_MODES.includes(options.defaultChangeMode)) {
+            throw new errors.SuperDocCliError('defaultChangeMode must be "direct" or "tracked".', {
+                code: 'INVALID_ARGUMENT',
+                details: { defaultChangeMode: options.defaultChangeMode },
+            });
+        }
+        this.defaultChangeMode = options.defaultChangeMode;
+        this.user = options.user;
+    }
+    async connect() {
+        await this.ensureConnected();
+    }
+    async dispose() {
+        if (!this.child)
+            return;
+        this.stopping = true;
+        const child = this.child;
+        try {
+            await this.sendJsonRpcRequest('host.shutdown', {}, this.shutdownTimeoutMs);
+        }
+        catch {
+            // ignore and force shutdown below
+        }
+        await new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                child.kill('SIGKILL');
+                resolve();
+            }, this.shutdownTimeoutMs);
+            child.once('close', () => {
+                clearTimeout(timer);
+                resolve();
+            });
+        });
+        this.cleanupProcess(null);
+        this.stopping = false;
+    }
+    async invoke(operation, params = {}, options = {}) {
+        await this.ensureConnected();
+        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);
+        const response = await this.sendJsonRpcRequest('cli.invoke', {
+            argv,
+            stdinBase64,
+        }, watchdogTimeout);
+        if (typeof response !== 'object' || response == null || Array.isArray(response)) {
+            throw new errors.SuperDocCliError('Host returned invalid cli.invoke result.', {
+                code: 'HOST_PROTOCOL_ERROR',
+                details: { result: response },
+            });
+        }
+        const resultRecord = response;
+        return resultRecord.data;
+    }
+    async ensureConnected() {
+        if (this.child && !this.child.killed) {
+            return;
+        }
+        if (this.connecting) {
+            await this.connecting;
+            return;
+        }
+        this.connecting = this.startHostProcess();
+        try {
+            await this.connecting;
+        }
+        finally {
+            this.connecting = null;
+        }
+    }
+    async startHostProcess() {
+        const { command, prefixArgs } = transportCommon.resolveInvocation(this.cliBin);
+        const args = [...prefixArgs, 'host', '--stdio'];
+        const child = node_child_process.spawn(command, args, {
+            env: {
+                ...process.env,
+                ...(this.env ?? {}),
+            },
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        this.child = child;
+        const stdoutReader = node_readline.createInterface({
+            input: child.stdout,
+            crlfDelay: Number.POSITIVE_INFINITY,
+        });
+        this.stdoutReader = stdoutReader;
+        stdoutReader.on('line', (line) => {
+            this.onStdoutLine(line);
+        });
+        child.stderr.on('data', () => {
+            // stderr intentionally ignored in host mode
+        });
+        child.on('error', (error) => {
+            this.handleDisconnect(new errors.SuperDocCliError('Host process failed.', {
+                code: 'HOST_DISCONNECTED',
+                details: {
+                    message: error instanceof Error ? error.message : String(error),
+                },
+            }));
+        });
+        child.on('close', (code, signal) => {
+            if (this.stopping) {
+                this.cleanupProcess(null);
+                return;
+            }
+            this.handleDisconnect(new errors.SuperDocCliError('Host process disconnected.', {
+                code: 'HOST_DISCONNECTED',
+                details: { exitCode: code, signal },
+            }));
+        });
+        try {
+            const capabilities = await this.sendJsonRpcRequest('host.capabilities', {}, this.startupTimeoutMs);
+            this.assertCapabilities(capabilities);
+        }
+        catch (error) {
+            const normalized = error instanceof errors.SuperDocCliError
+                ? error
+                : new errors.SuperDocCliError('Host handshake failed.', {
+                    code: 'HOST_HANDSHAKE_FAILED',
+                    details: {
+                        message: error instanceof Error ? error.message : String(error),
+                    },
+                });
+            this.handleDisconnect(normalized);
+            throw normalized;
+        }
+    }
+    assertCapabilities(response) {
+        if (typeof response !== 'object' || response == null || Array.isArray(response)) {
+            throw new errors.SuperDocCliError('Host capabilities response is invalid.', {
+                code: 'HOST_HANDSHAKE_FAILED',
+                details: { response },
+            });
+        }
+        const record = response;
+        const protocolVersion = record.protocolVersion;
+        const features = record.features;
+        if (protocolVersion !== HOST_PROTOCOL_VERSION) {
+            throw new errors.SuperDocCliError('Host protocol version is unsupported.', {
+                code: 'HOST_HANDSHAKE_FAILED',
+                details: {
+                    expected: HOST_PROTOCOL_VERSION,
+                    actual: protocolVersion,
+                },
+            });
+        }
+        if (!Array.isArray(features) || features.some((f) => typeof f !== 'string')) {
+            throw new errors.SuperDocCliError('Host capabilities.features must be a string array.', {
+                code: 'HOST_HANDSHAKE_FAILED',
+                details: { features },
+            });
+        }
+        for (const requiredFeature of REQUIRED_FEATURES) {
+            if (!features.includes(requiredFeature)) {
+                throw new errors.SuperDocCliError(`Host does not support required feature: ${requiredFeature}`, {
+                    code: 'HOST_HANDSHAKE_FAILED',
+                    details: { features },
+                });
+            }
+        }
+    }
+    resolveWatchdogTimeout(timeoutMsOverride) {
+        if (timeoutMsOverride != null) {
+            return Math.max(this.watchdogTimeoutMs, timeoutMsOverride + 1_000);
+        }
+        if (this.requestTimeoutMs != null) {
+            return Math.max(this.watchdogTimeoutMs, this.requestTimeoutMs + 1_000);
+        }
+        return this.watchdogTimeoutMs;
+    }
+    async sendJsonRpcRequest(method, params, watchdogTimeoutMs) {
+        const child = this.child;
+        if (!child || !child.stdin.writable) {
+            throw new errors.SuperDocCliError('Host process is not available.', {
+                code: 'HOST_DISCONNECTED',
+            });
+        }
+        if (this.pending.size >= this.maxQueueDepth) {
+            throw new errors.SuperDocCliError('Host request queue is full.', {
+                code: 'HOST_QUEUE_FULL',
+                details: { maxQueueDepth: this.maxQueueDepth },
+            });
+        }
+        const id = this.nextRequestId;
+        this.nextRequestId += 1;
+        const payload = JSON.stringify({
+            jsonrpc: '2.0',
+            id,
+            method,
+            params,
+        });
+        const promise = new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new errors.SuperDocCliError(`Host watchdog timed out waiting for ${method}.`, {
+                    code: 'HOST_TIMEOUT',
+                    details: { method, timeoutMs: watchdogTimeoutMs },
+                }));
+                this.handleDisconnect(new errors.SuperDocCliError('Host watchdog timeout; host process will be restarted on next request.', {
+                    code: 'HOST_DISCONNECTED',
+                    details: { method, timeoutMs: watchdogTimeoutMs },
+                }));
+            }, watchdogTimeoutMs);
+            this.pending.set(id, { resolve, reject, timer });
+            child.stdin.write(`${payload}\n`, (error) => {
+                if (!error)
+                    return;
+                const pending = this.pending.get(id);
+                if (!pending)
+                    return;
+                clearTimeout(pending.timer);
+                this.pending.delete(id);
+                reject(new errors.SuperDocCliError('Failed to write request to host process.', {
+                    code: 'HOST_DISCONNECTED',
+                    details: { method, message: error.message },
+                }));
+            });
+        });
+        return promise;
+    }
+    onStdoutLine(line) {
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            return;
+        }
+        if (typeof parsed !== 'object' || parsed == null || Array.isArray(parsed)) {
+            return;
+        }
+        const record = parsed;
+        if (record.jsonrpc !== '2.0') {
+            return;
+        }
+        // Notification (no id) — reserved for future eventing
+        if ('method' in record && !('id' in record)) {
+            return;
+        }
+        const idRaw = record.id;
+        if (typeof idRaw !== 'number') {
+            return;
+        }
+        const pending = this.pending.get(idRaw);
+        if (!pending) {
+            return;
+        }
+        clearTimeout(pending.timer);
+        this.pending.delete(idRaw);
+        if ('error' in record) {
+            pending.reject(this.mapJsonRpcError(record.error));
+            return;
+        }
+        pending.resolve(record.result);
+    }
+    mapJsonRpcError(rawError) {
+        if (typeof rawError !== 'object' || rawError == null || Array.isArray(rawError)) {
+            return new errors.SuperDocCliError('Host returned an unknown JSON-RPC error.', {
+                code: 'HOST_PROTOCOL_ERROR',
+                details: { error: rawError },
+            });
+        }
+        const error = rawError;
+        const data = error.data;
+        const cliCode = typeof data?.cliCode === 'string' ? data.cliCode : undefined;
+        const cliMessage = typeof data?.message === 'string' ? data.message : undefined;
+        const exitCode = typeof data?.exitCode === 'number' ? data.exitCode : undefined;
+        if (cliCode) {
+            return new errors.SuperDocCliError(cliMessage ?? error.message ?? 'Command failed.', {
+                code: cliCode,
+                details: data?.details,
+                exitCode,
+            });
+        }
+        if (error.code === JSON_RPC_TIMEOUT_CODE) {
+            return new errors.SuperDocCliError(error.message, {
+                code: 'TIMEOUT',
+                details: data,
+            });
+        }
+        return new errors.SuperDocCliError(error.message, {
+            code: 'COMMAND_FAILED',
+            details: data,
+        });
+    }
+    handleDisconnect(error) {
+        this.cleanupProcess(error);
+    }
+    cleanupProcess(error) {
+        const child = this.child;
+        if (child) {
+            child.removeAllListeners();
+            child.kill('SIGKILL');
+        }
+        this.child = null;
+        if (this.stdoutReader) {
+            this.stdoutReader.removeAllListeners();
+            this.stdoutReader.close();
+            this.stdoutReader = null;
+        }
+        const pendingEntries = Array.from(this.pending.values());
+        this.pending.clear();
+        const rejection = error ??
+            new errors.SuperDocCliError('Host process was disposed while request was in flight.', {
+                code: 'HOST_DISCONNECTED',
+            });
+        for (const pending of pendingEntries) {
+            clearTimeout(pending.timer);
+            pending.reject(rejection);
+        }
+    }
+}
+
+exports.HostTransport = HostTransport;

package/dist/runtime/host.d.ts

@@ -11,6 +11,7 @@ export declare class HostTransport {
     private readonly watchdogTimeoutMs;
     private readonly maxQueueDepth;
     private readonly defaultChangeMode?;
+    private readonly user?;
     private child;
     private stdoutReader;
     private readonly pending;
@@ -22,7 +23,7 @@ export declare class HostTransport {
     } & SuperDocClientOptions);
     connect(): Promise<void>;
     dispose(): Promise<void>;
-    invoke<TData extends Record<string, unknown>>(operation: OperationSpec, params?: Record<string, unknown>, options?: InvokeOptions): Promise<TData>;
+    invoke<TData = unknown>(operation: OperationSpec, params?: Record<string, unknown>, options?: InvokeOptions): Promise<TData>;
     private ensureConnected;
     private startHostProcess;
     private assertCapabilities;

package/dist/runtime/host.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"host.d.ts","sourceRoot":"","sources":["../../src/runtime/host.ts"],"names":[],"mappings":"AAEA,OAAO,EAIL,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,qBAAqB,EAC3B,MAAM,uBAAuB,CAAC;AA4B/B;;GAEG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAqC;IAC1D,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAC,CAAa;IAEhD,OAAO,CAAC,KAAK,CAA+C;IAC5D,OAAO,CAAC,YAAY,CAAkC;IACtD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqC;IAC7D,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,UAAU,CAA8B;IAChD,OAAO,CAAC,QAAQ,CAAS;gBAEb,OAAO,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,qBAAqB;IAkBzD,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAIxB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IA4BxB,MAAM,CAAC,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChD,SAAS,EAAE,aAAa,EACxB,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,EACpC,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,KAAK,CAAC;YA2BH,eAAe;YAkBf,gBAAgB;IAuE9B,OAAO,CAAC,kBAAkB;IAuC1B,OAAO,CAAC,sBAAsB;YAYhB,kBAAkB;IAkEhC,OAAO,CAAC,YAAY;IA2CpB,OAAO,CAAC,eAAe;IAmCvB,OAAO,CAAC,gBAAgB;IAIxB,OAAO,CAAC,cAAc;CA6BvB"}
+{"version":3,"file":"host.d.ts","sourceRoot":"","sources":["../../src/runtime/host.ts"],"names":[],"mappings":"AAEA,OAAO,EAIL,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,qBAAqB,EAE3B,MAAM,uBAAuB,CAAC;AA4B/B;;GAEG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAqC;IAC1D,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAC,CAAa;IAChD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAe;IAErC,OAAO,CAAC,KAAK,CAA+C;IAC5D,OAAO,CAAC,YAAY,CAAkC;IACtD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqC;IAC7D,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,UAAU,CAA8B;IAChD,OAAO,CAAC,QAAQ,CAAS;gBAEb,OAAO,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,qBAAqB;IAmBzD,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAIxB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IA4BxB,MAAM,CAAC,KAAK,GAAG,OAAO,EAC1B,SAAS,EAAE,aAAa,EACxB,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,EACpC,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,KAAK,CAAC;YAkCH,eAAe;YAkBf,gBAAgB;IAuE9B,OAAO,CAAC,kBAAkB;IAuC1B,OAAO,CAAC,sBAAsB;YAYhB,kBAAkB;IAkEhC,OAAO,CAAC,YAAY;IA2CpB,OAAO,CAAC,eAAe;IAmCvB,OAAO,CAAC,gBAAgB;IAIxB,OAAO,CAAC,cAAc;CA6BvB"}

package/dist/runtime/host.js

@@ -18,6 +18,7 @@ export class HostTransport {
     watchdogTimeoutMs;
     maxQueueDepth;
     defaultChangeMode;
+    user;
     child = null;
     stdoutReader = null;
     pending = new Map();
@@ -39,6 +40,7 @@ export class HostTransport {
             });
         }
         this.defaultChangeMode = options.defaultChangeMode;
+        this.user = options.user;
     }
     async connect() {
         await this.ensureConnected();
@@ -69,7 +71,7 @@ export class HostTransport {
     }
     async invoke(operation, params = {}, options = {}) {
         await this.ensureConnected();
-        const argv = buildOperationArgv(operation, params, options, this.requestTimeoutMs, this.defaultChangeMode);
+        const argv = 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);
         const response = await this.sendJsonRpcRequest('cli.invoke', {

package/dist/runtime/process.cjs

@@ -0,0 +1,32 @@
+'use strict';
+
+var host = require('./host.cjs');
+var embeddedCli = require('./embedded-cli.cjs');
+
+/**
+ * Internal runtime that delegates CLI invocations to a persistent host transport.
+ *
+ * Resolves the CLI binary and creates a {@link HostTransport} that communicates
+ * with a long-lived `superdoc host --stdio` process.
+ */
+class SuperDocRuntime {
+    transport;
+    constructor(options = {}) {
+        const cliBin = options.env?.SUPERDOC_CLI_BIN ?? process.env.SUPERDOC_CLI_BIN ?? embeddedCli.resolveEmbeddedCliBinary();
+        this.transport = new host.HostTransport({
+            cliBin,
+            ...options,
+        });
+    }
+    async connect() {
+        await this.transport.connect();
+    }
+    async dispose() {
+        await this.transport.dispose();
+    }
+    async invoke(operation, params = {}, options = {}) {
+        return this.transport.invoke(operation, params, options);
+    }
+}
+
+exports.SuperDocRuntime = SuperDocRuntime;

package/dist/runtime/process.d.ts

@@ -10,7 +10,7 @@ export declare class SuperDocRuntime {
     constructor(options?: SuperDocClientOptions);
     connect(): Promise<void>;
     dispose(): Promise<void>;
-    invoke<TData extends Record<string, unknown>>(operation: OperationSpec, params?: Record<string, unknown>, options?: InvokeOptions): Promise<TData>;
+    invoke<TData = unknown>(operation: OperationSpec, params?: Record<string, unknown>, options?: InvokeOptions): Promise<TData>;
 }
 export type { InvokeOptions, OperationParamSpec, OperationSpec, SuperDocClientOptions };
 //# sourceMappingURL=process.d.ts.map

package/dist/runtime/process.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"process.d.ts","sourceRoot":"","sources":["../../src/runtime/process.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,aAAa,EACb,kBAAkB,EAClB,aAAa,EACb,qBAAqB,EACtB,MAAM,uBAAuB,CAAC;AAE/B;;;;;GAKG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgB;gBAE9B,OAAO,GAAE,qBAA0B;IASzC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAIxB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAIxB,MAAM,CAAC,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChD,SAAS,EAAE,aAAa,EACxB,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,EACpC,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,KAAK,CAAC;CAGlB;AAED,YAAY,EAAE,aAAa,EAAE,kBAAkB,EAAE,aAAa,EAAE,qBAAqB,EAAE,CAAC"}
+{"version":3,"file":"process.d.ts","sourceRoot":"","sources":["../../src/runtime/process.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,kBAAkB,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAErH;;;;;GAKG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgB;gBAE9B,OAAO,GAAE,qBAA0B;IASzC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAIxB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAIxB,MAAM,CAAC,KAAK,GAAG,OAAO,EAC1B,SAAS,EAAE,aAAa,EACxB,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,EACpC,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,KAAK,CAAC;CAGlB;AAED,YAAY,EAAE,aAAa,EAAE,kBAAkB,EAAE,aAAa,EAAE,qBAAqB,EAAE,CAAC"}

package/dist/runtime/transport-common.cjs

@@ -0,0 +1,79 @@
+'use strict';
+
+function hasExtension(filePath, extension) {
+    return filePath.toLowerCase().endsWith(extension);
+}
+function resolveInvocation(cliBin) {
+    if (hasExtension(cliBin, '.js')) {
+        return { command: 'node', prefixArgs: [cliBin] };
+    }
+    if (hasExtension(cliBin, '.ts')) {
+        return { command: 'bun', prefixArgs: [cliBin] };
+    }
+    return { command: cliBin, prefixArgs: [] };
+}
+/**
+ * Build the CLI argument vector for an operation invocation.
+ *
+ * Key design choices vs old SDK:
+ * - changeMode injection BEFORE argv loop, not after. changeMode is already a
+ *   param in operationSpec.params (envelope param for mutations). Appending after
+ *   the loop would duplicate it.
+ * - Booleans encoded as `--flag true`/`--flag false` explicitly, matching current CLI.
+ */
+function buildOperationArgv(operation, params, options, runtimeTimeoutMs, defaultChangeMode, user) {
+    // Inject defaultChangeMode into params BEFORE encoding — single source of truth.
+    let normalizedParams = defaultChangeMode != null && params.changeMode == null && operation.params.some((p) => p.name === 'changeMode')
+        ? { ...params, changeMode: defaultChangeMode }
+        : params;
+    // Inject user identity for doc.open when not already specified.
+    if (user != null && operation.operationId === 'doc.open') {
+        if (normalizedParams.userName == null && user.name) {
+            normalizedParams = { ...normalizedParams, userName: user.name };
+        }
+        if (normalizedParams.userEmail == null && user.email) {
+            normalizedParams = { ...normalizedParams, userEmail: user.email };
+        }
+    }
+    const argv = [...operation.commandTokens];
+    for (const spec of operation.params) {
+        const value = normalizedParams[spec.name];
+        if (value == null)
+            continue;
+        const flag = `--${spec.flag ?? spec.name}`;
+        switch (spec.kind) {
+            case 'doc':
+                argv.push(String(value));
+                break;
+            case 'flag':
+                if (spec.type === 'boolean') {
+                    // Explicit true/false — matches current CLI operation-executor.ts.
+                    argv.push(flag, value === true ? 'true' : 'false');
+                }
+                else if (spec.type === 'string[]') {
+                    if (Array.isArray(value)) {
+                        for (const entry of value)
+                            argv.push(flag, String(entry));
+                    }
+                }
+                else {
+                    argv.push(flag, String(value));
+                }
+                break;
+            case 'jsonFlag':
+                // CLI always parses --*-json values via JSON.parse, so even scalar
+                // strings must be serialized as JSON string literals.
+                argv.push(flag, JSON.stringify(value));
+                break;
+        }
+    }
+    const timeoutMs = options.timeoutMs ?? runtimeTimeoutMs;
+    if (timeoutMs != null) {
+        argv.push('--timeout-ms', String(timeoutMs));
+    }
+    argv.push('--output', 'json');
+    return argv;
+}
+
+exports.buildOperationArgv = buildOperationArgv;
+exports.resolveInvocation = resolveInvocation;

package/dist/runtime/transport-common.d.ts

@@ -17,6 +17,10 @@ export interface InvokeOptions {
     stdinBytes?: Uint8Array;
 }
 export type ChangeMode = 'direct' | 'tracked';
+export interface UserIdentity {
+    name: string;
+    email?: string;
+}
 export interface SuperDocClientOptions {
     env?: Record<string, string | undefined>;
     startupTimeoutMs?: number;
@@ -25,6 +29,7 @@ export interface SuperDocClientOptions {
     watchdogTimeoutMs?: number;
     maxQueueDepth?: number;
     defaultChangeMode?: ChangeMode;
+    user?: UserIdentity;
 }
 export interface CliInvocation {
     command: string;
@@ -40,5 +45,5 @@ export declare function resolveInvocation(cliBin: string): CliInvocation;
  *   the loop would duplicate it.
  * - Booleans encoded as `--flag true`/`--flag false` explicitly, matching current CLI.
  */
-export declare function buildOperationArgv(operation: OperationSpec, params: Record<string, unknown>, options: InvokeOptions, runtimeTimeoutMs: number | undefined, defaultChangeMode?: ChangeMode): string[];
+export declare function buildOperationArgv(operation: OperationSpec, params: Record<string, unknown>, options: InvokeOptions, runtimeTimeoutMs: number | undefined, defaultChangeMode?: ChangeMode, user?: UserIdentity): string[];
 //# sourceMappingURL=transport-common.d.ts.map

package/dist/runtime/transport-common.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transport-common.d.ts","sourceRoot":"","sources":["../../src/runtime/transport-common.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,GAAG,UAAU,CAAC;AAC9E,MAAM,MAAM,SAAS,GAAG,KAAK,GAAG,MAAM,GAAG,UAAU,CAAC;AAEpD,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,QAAQ,CAAC,MAAM,EAAE,SAAS,kBAAkB,EAAE,CAAC;CAChD;AAED,MAAM,WAAW,aAAa;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB;AAED,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE9C,MAAM,WAAW,qBAAqB;IACpC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACzC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iBAAiB,CAAC,EAAE,UAAU,CAAC;CAChC;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAMD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,CAU/D;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,aAAa,EACxB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,OAAO,EAAE,aAAa,EACtB,gBAAgB,EAAE,MAAM,GAAG,SAAS,EACpC,iBAAiB,CAAC,EAAE,UAAU,GAC7B,MAAM,EAAE,CA8CV"}
+{"version":3,"file":"transport-common.d.ts","sourceRoot":"","sources":["../../src/runtime/transport-common.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,GAAG,UAAU,CAAC;AAC9E,MAAM,MAAM,SAAS,GAAG,KAAK,GAAG,MAAM,GAAG,UAAU,CAAC;AAEpD,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,QAAQ,CAAC,MAAM,EAAE,SAAS,kBAAkB,EAAE,CAAC;CAChD;AAED,MAAM,WAAW,aAAa;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB;AAED,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE9C,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,qBAAqB;IACpC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACzC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iBAAiB,CAAC,EAAE,UAAU,CAAC;IAC/B,IAAI,CAAC,EAAE,YAAY,CAAC;CACrB;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAMD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,CAU/D;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,aAAa,EACxB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,OAAO,EAAE,aAAa,EACtB,gBAAgB,EAAE,MAAM,GAAG,SAAS,EACpC,iBAAiB,CAAC,EAAE,UAAU,EAC9B,IAAI,CAAC,EAAE,YAAY,GAClB,MAAM,EAAE,CAwDV"}

package/dist/runtime/transport-common.js

@@ -19,13 +19,20 @@ export function resolveInvocation(cliBin) {
  *   the loop would duplicate it.
  * - Booleans encoded as `--flag true`/`--flag false` explicitly, matching current CLI.
  */
-export function buildOperationArgv(operation, params, options, runtimeTimeoutMs, defaultChangeMode) {
+export function buildOperationArgv(operation, params, options, runtimeTimeoutMs, defaultChangeMode, user) {
     // Inject defaultChangeMode into params BEFORE encoding — single source of truth.
-    const normalizedParams = defaultChangeMode != null &&
-        params.changeMode == null &&
-        operation.params.some((p) => p.name === 'changeMode')
+    let normalizedParams = defaultChangeMode != null && params.changeMode == null && operation.params.some((p) => p.name === 'changeMode')
         ? { ...params, changeMode: defaultChangeMode }
         : params;
+    // Inject user identity for doc.open when not already specified.
+    if (user != null && operation.operationId === 'doc.open') {
+        if (normalizedParams.userName == null && user.name) {
+            normalizedParams = { ...normalizedParams, userName: user.name };
+        }
+        if (normalizedParams.userEmail == null && user.email) {
+            normalizedParams = { ...normalizedParams, userEmail: user.email };
+        }
+    }
     const argv = [...operation.commandTokens];
     for (const spec of operation.params) {
         const value = normalizedParams[spec.name];
@@ -52,6 +59,8 @@ export function buildOperationArgv(operation, params, options, runtimeTimeoutMs,
                 }
                 break;
             case 'jsonFlag':
+                // CLI always parses --*-json values via JSON.parse, so even scalar
+                // strings must be serialized as JSON string literals.
                 argv.push(flag, JSON.stringify(value));
                 break;
         }