@superdoc-dev/sdk 1.0.0-alpha.3 → 1.0.0-alpha.30

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

@@ -0,0 +1,37 @@
+import { type InvokeOptions, type OperationSpec, type SuperDocClientOptions } from './transport-common.js';
+/**
+ * Transport that communicates with a long-lived CLI host process over JSON-RPC stdio.
+ */
+export declare class HostTransport {
+    private readonly cliBin;
+    private readonly env?;
+    private readonly startupTimeoutMs;
+    private readonly shutdownTimeoutMs;
+    private readonly requestTimeoutMs?;
+    private readonly watchdogTimeoutMs;
+    private readonly maxQueueDepth;
+    private readonly defaultChangeMode?;
+    private readonly user?;
+    private child;
+    private stdoutReader;
+    private readonly pending;
+    private nextRequestId;
+    private connecting;
+    private stopping;
+    constructor(options: {
+        cliBin: string;
+    } & SuperDocClientOptions);
+    connect(): Promise<void>;
+    dispose(): Promise<void>;
+    invoke<TData = unknown>(operation: OperationSpec, params?: Record<string, unknown>, options?: InvokeOptions): Promise<TData>;
+    private ensureConnected;
+    private startHostProcess;
+    private assertCapabilities;
+    private resolveWatchdogTimeout;
+    private sendJsonRpcRequest;
+    private onStdoutLine;
+    private mapJsonRpcError;
+    private handleDisconnect;
+    private cleanupProcess;
+}
+//# sourceMappingURL=host.d.ts.map

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

@@ -0,0 +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,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"}