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

package/src/runtime/host.ts

@@ -1,481 +0,0 @@
-import { spawn, type ChildProcessWithoutNullStreams } from 'node:child_process';
-import { createInterface, type Interface as ReadlineInterface } from 'node:readline';
-import {
-  buildOperationArgv,
-  resolveInvocation,
-  type ChangeMode,
-  type InvokeOptions,
-  type OperationSpec,
-  type SuperDocClientOptions,
-} from './transport-common';
-import { SuperDocCliError } from './errors';
-
-type PendingRequest = {
-  resolve: (value: unknown) => void;
-  reject: (error: SuperDocCliError) => void;
-  timer: NodeJS.Timeout;
-};
-
-type JsonRpcErrorData = {
-  cliCode?: unknown;
-  message?: unknown;
-  details?: unknown;
-  exitCode?: unknown;
-};
-
-type JsonRpcError = {
-  code: number;
-  message: string;
-  data?: JsonRpcErrorData;
-};
-
-const HOST_PROTOCOL_VERSION = '1.0';
-const REQUIRED_FEATURES = ['cli.invoke', 'host.shutdown'];
-const CHANGE_MODES = ['direct', 'tracked'] as const;
-
-const JSON_RPC_TIMEOUT_CODE = -32011;
-
-/**
- * Transport that communicates with a long-lived CLI host process over JSON-RPC stdio.
- *
- * The host process is spawned lazily on first invocation and kept alive for
- * subsequent calls. Call {@link dispose} to gracefully shut it down.
- */
-export class HostTransport {
-  private readonly cliBin: string;
-  private readonly env?: Record<string, string | undefined>;
-  private readonly startupTimeoutMs: number;
-  private readonly shutdownTimeoutMs: number;
-  private readonly requestTimeoutMs?: number;
-  private readonly watchdogTimeoutMs: number;
-  private readonly maxQueueDepth: number;
-  private readonly defaultChangeMode?: ChangeMode;
-
-  private child: ChildProcessWithoutNullStreams | null = null;
-  private stdoutReader: ReadlineInterface | null = null;
-  private readonly pending = new Map<number, PendingRequest>();
-  private nextRequestId = 1;
-  private connecting: Promise<void> | null = null;
-  private stopping = false;
-
-  constructor(options: { cliBin: string } & SuperDocClientOptions) {
-    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 SuperDocCliError('defaultChangeMode must be "direct" or "tracked".', {
-        code: 'INVALID_ARGUMENT',
-        details: { defaultChangeMode: options.defaultChangeMode },
-      });
-    }
-    this.defaultChangeMode = options.defaultChangeMode;
-  }
-
-  async connect(): Promise<void> {
-    await this.ensureConnected();
-  }
-
-  async dispose(): Promise<void> {
-    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<void>((resolve) => {
-      const timer = setTimeout(() => {
-        child.kill('SIGKILL');
-        resolve();
-      }, this.shutdownTimeoutMs);
-
-      child.once('close', () => {
-        clearTimeout(timer);
-        resolve();
-      });
-    });
-
-    this.cleanupProcess(null);
-    this.stopping = false;
-  }
-
-  async invoke<TData extends Record<string, unknown>>(
-    operation: OperationSpec,
-    params: Record<string, unknown> = {},
-    options: InvokeOptions = {},
-  ): Promise<TData> {
-    await this.ensureConnected();
-
-    const argv = buildOperationArgv(operation, params, options, this.requestTimeoutMs, false, this.defaultChangeMode);
-    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 SuperDocCliError('Host returned invalid cli.invoke result.', {
-        code: 'HOST_PROTOCOL_ERROR',
-        details: { result: response },
-      });
-    }
-
-    const resultRecord = response as Record<string, unknown>;
-    return resultRecord.data as TData;
-  }
-
-  private async ensureConnected(): Promise<void> {
-    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;
-    }
-  }
-
-  private async startHostProcess(): Promise<void> {
-    const { command, prefixArgs } = resolveInvocation(this.cliBin);
-    const args = [...prefixArgs, 'host', '--stdio'];
-
-    const child = spawn(command, args, {
-      env: {
-        ...process.env,
-        ...(this.env ?? {}),
-      },
-      stdio: ['pipe', 'pipe', 'pipe'],
-    });
-
-    this.child = child;
-
-    const stdoutReader = createInterface({
-      input: child.stdout,
-      crlfDelay: Number.POSITIVE_INFINITY,
-    });
-    this.stdoutReader = stdoutReader;
-
-    stdoutReader.on('line', (line) => {
-      this.onStdoutLine(line);
-    });
-
-    child.stderr.on('data', () => {
-      // stderr is intentionally ignored in host mode unless process exits unexpectedly
-    });
-
-    child.on('error', (error) => {
-      this.handleDisconnect(
-        new SuperDocCliError('Host process failed.', {
-          code: 'HOST_DISCONNECTED',
-          details: {
-            message: error instanceof Error ? error.message : String(error),
-          },
-        }),
-      );
-    });
-
-    child.on('close', (code, signal) => {
-      const isExpectedClose = this.stopping;
-      if (isExpectedClose) {
-        this.cleanupProcess(null);
-        return;
-      }
-
-      this.handleDisconnect(
-        new 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 SuperDocCliError
-          ? error
-          : new SuperDocCliError('Host handshake failed.', {
-              code: 'HOST_HANDSHAKE_FAILED',
-              details: {
-                message: error instanceof Error ? error.message : String(error),
-              },
-            });
-      this.handleDisconnect(normalized);
-      throw normalized;
-    }
-  }
-
-  private assertCapabilities(response: unknown): void {
-    if (typeof response !== 'object' || response == null || Array.isArray(response)) {
-      throw new SuperDocCliError('Host capabilities response is invalid.', {
-        code: 'HOST_HANDSHAKE_FAILED',
-        details: { response },
-      });
-    }
-
-    const record = response as Record<string, unknown>;
-    const protocolVersion = record.protocolVersion;
-    const features = record.features;
-
-    if (protocolVersion !== HOST_PROTOCOL_VERSION) {
-      throw new SuperDocCliError('Host protocol version is unsupported.', {
-        code: 'HOST_HANDSHAKE_FAILED',
-        details: {
-          expected: HOST_PROTOCOL_VERSION,
-          actual: protocolVersion,
-        },
-      });
-    }
-
-    if (!Array.isArray(features) || features.some((feature) => typeof feature !== 'string')) {
-      throw new 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 SuperDocCliError(`Host does not support required feature: ${requiredFeature}`, {
-          code: 'HOST_HANDSHAKE_FAILED',
-          details: { features },
-        });
-      }
-    }
-  }
-
-  private resolveWatchdogTimeout(timeoutMsOverride: number | undefined): number {
-    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;
-  }
-
-  private async sendJsonRpcRequest(method: string, params: unknown, watchdogTimeoutMs: number): Promise<unknown> {
-    const child = this.child;
-    if (!child || !child.stdin.writable) {
-      throw new SuperDocCliError('Host process is not available.', {
-        code: 'HOST_DISCONNECTED',
-      });
-    }
-
-    if (this.pending.size >= this.maxQueueDepth) {
-      throw new 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<unknown>((resolve, reject) => {
-      const timer = setTimeout(() => {
-        this.pending.delete(id);
-
-        const timeoutError = new SuperDocCliError(`Host watchdog timed out waiting for ${method}.`, {
-          code: 'HOST_TIMEOUT',
-          details: {
-            method,
-            timeoutMs: watchdogTimeoutMs,
-          },
-        });
-
-        reject(timeoutError);
-
-        this.handleDisconnect(
-          new 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 SuperDocCliError('Failed to write request to host process.', {
-            code: 'HOST_DISCONNECTED',
-            details: {
-              method,
-              message: error.message,
-            },
-          }),
-        );
-      });
-    });
-
-    return promise;
-  }
-
-  private onStdoutLine(line: string): void {
-    let parsed: unknown;
-    try {
-      parsed = JSON.parse(line);
-    } catch {
-      // Ignore non-protocol stdout noise (for example telemetry/logging lines).
-      return;
-    }
-
-    if (typeof parsed !== 'object' || parsed == null || Array.isArray(parsed)) {
-      return;
-    }
-
-    const record = parsed as Record<string, unknown>;
-    if (record.jsonrpc !== '2.0') {
-      return;
-    }
-
-    if ('method' in record && !('id' in record)) {
-      // Notification; reserved for future eventing.
-      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);
-  }
-
-  private mapJsonRpcError(rawError: unknown): SuperDocCliError {
-    if (typeof rawError !== 'object' || rawError == null || Array.isArray(rawError)) {
-      return new SuperDocCliError('Host returned an unknown JSON-RPC error.', {
-        code: 'HOST_PROTOCOL_ERROR',
-        details: { error: rawError },
-      });
-    }
-
-    const error = rawError as JsonRpcError;
-
-    const data = error.data as JsonRpcErrorData | undefined;
-    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 SuperDocCliError(cliMessage ?? error.message ?? 'Command failed.', {
-        code: cliCode,
-        details: data?.details,
-        exitCode,
-      });
-    }
-
-    if (error.code === JSON_RPC_TIMEOUT_CODE) {
-      return new SuperDocCliError(error.message, {
-        code: 'TIMEOUT',
-        details: data,
-      });
-    }
-
-    return new SuperDocCliError(error.message, {
-      code: 'COMMAND_FAILED',
-      details: data,
-    });
-  }
-
-  private handleDisconnect(error: SuperDocCliError): void {
-    this.cleanupProcess(error);
-  }
-
-  private cleanupProcess(error: SuperDocCliError | null): void {
-    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();
-
-    if (!error) {
-      for (const pending of pendingEntries) {
-        clearTimeout(pending.timer);
-      }
-      return;
-    }
-
-    for (const pending of pendingEntries) {
-      clearTimeout(pending.timer);
-      pending.reject(error);
-    }
-  }
-}

package/src/runtime/process.ts

@@ -1,45 +0,0 @@
-import { HostTransport } from './host';
-import { resolveEmbeddedCliBinary } from './embedded-cli';
-import type {
-  InvokeOptions,
-  OperationParamSpec,
-  OperationSpec,
-  SuperDocClientOptions,
-} from './transport-common';
-
-/**
- * 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.
- */
-export class SuperDocRuntime {
-  private readonly transport: HostTransport;
-
-  constructor(options: SuperDocClientOptions = {}) {
-    const cliBin = options.env?.SUPERDOC_CLI_BIN ?? process.env.SUPERDOC_CLI_BIN ?? resolveEmbeddedCliBinary();
-
-    this.transport = new HostTransport({
-      cliBin,
-      ...options,
-    });
-  }
-
-  async connect(): Promise<void> {
-    await this.transport.connect();
-  }
-
-  async dispose(): Promise<void> {
-    await this.transport.dispose();
-  }
-
-  async invoke<TData extends Record<string, unknown>>(
-    operation: OperationSpec,
-    params: Record<string, unknown> = {},
-    options: InvokeOptions = {},
-  ): Promise<TData> {
-    return this.transport.invoke<TData>(operation, params, options);
-  }
-}
-
-export type { InvokeOptions, OperationParamSpec, OperationSpec, SuperDocClientOptions };

package/src/runtime/transport-common.ts

@@ -1,169 +0,0 @@
-import { SuperDocCliError } from './errors';
-
-/** Allowed CLI parameter value types. */
-export type ParamType = 'string' | 'number' | 'boolean' | 'json' | 'string[]';
-
-/** How a parameter is passed to the CLI (`doc` positional, `flag`, or `jsonFlag`). */
-export type ParamKind = 'doc' | 'flag' | 'jsonFlag';
-
-/** Describes a single parameter in a CLI operation. */
-export interface OperationParamSpec {
-  readonly name: string;
-  readonly kind: ParamKind;
-  readonly flag?: string;
-  readonly type: ParamType;
-  readonly required?: boolean;
-}
-
-/** Describes a CLI operation (command segments and its parameter specs). */
-export interface OperationSpec {
-  readonly id: string;
-  readonly command: readonly string[];
-  readonly params: readonly OperationParamSpec[];
-}
-
-/** Per-call options for a CLI invocation. */
-export interface InvokeOptions {
-  /** Timeout in milliseconds forwarded to the CLI `--timeout-ms` flag. */
-  timeoutMs?: number;
-  /** Raw bytes piped to the CLI process stdin. */
-  stdinBytes?: Uint8Array;
-}
-
-export type ChangeMode = 'direct' | 'tracked';
-
-/** Top-level options for creating a {@link SuperDocClient}. */
-export interface SuperDocClientOptions {
-  /** Extra environment variables merged into the CLI process environment. */
-  env?: Record<string, string | undefined>;
-  /** Timeout in milliseconds for the host process startup handshake. */
-  startupTimeoutMs?: number;
-  /** Timeout in milliseconds for graceful host shutdown. */
-  shutdownTimeoutMs?: number;
-  /** Default per-request timeout in milliseconds. */
-  requestTimeoutMs?: number;
-  /** Idle watchdog timeout in milliseconds. */
-  watchdogTimeoutMs?: number;
-  /** Maximum number of queued requests. */
-  maxQueueDepth?: number;
-  /** Default change mode for mutation operations that support `changeMode`. */
-  defaultChangeMode?: ChangeMode;
-}
-
-/** Resolved command and prefix args for spawning the CLI. */
-export interface CliInvocation {
-  command: string;
-  prefixArgs: string[];
-}
-
-function hasExtension(filePath: string, extension: string): boolean {
-  return filePath.toLowerCase().endsWith(extension);
-}
-
-/**
- * Determine how to spawn the CLI binary based on its file extension.
- *
- * @param cliBin - Path to the CLI binary or script.
- * @returns The shell command and any prefix arguments needed to execute it.
- */
-export function resolveInvocation(cliBin: string): CliInvocation {
-  if (hasExtension(cliBin, '.js')) {
-    return { command: 'node', prefixArgs: [cliBin] };
-  }
-
-  if (hasExtension(cliBin, '.ts')) {
-    return { command: 'bun', prefixArgs: [cliBin] };
-  }
-
-  return { command: cliBin, prefixArgs: [] };
-}
-
-function toCliFlag(flag: string): string {
-  return `--${flag}`;
-}
-
-function encodeParam(args: string[], spec: OperationParamSpec, value: unknown): void {
-  if (value == null) {
-    if (spec.required) {
-      throw new SuperDocCliError(`Missing required parameter: ${spec.name}`, {
-        code: 'INVALID_ARGUMENT',
-      });
-    }
-    return;
-  }
-
-  if (spec.kind === 'doc') {
-    args.push(String(value));
-    return;
-  }
-
-  const flag = toCliFlag(spec.flag ?? spec.name);
-
-  if (spec.type === 'boolean') {
-    if (value === true) {
-      args.push(flag);
-    }
-    return;
-  }
-
-  if (spec.type === 'string[]') {
-    if (!Array.isArray(value)) {
-      throw new SuperDocCliError(`Parameter ${spec.name} must be an array of strings.`, {
-        code: 'INVALID_ARGUMENT',
-      });
-    }
-
-    for (const item of value) {
-      args.push(flag, String(item));
-    }
-    return;
-  }
-
-  if (spec.type === 'json') {
-    args.push(flag, JSON.stringify(value));
-    return;
-  }
-
-  args.push(flag, String(value));
-}
-
-/**
- * Build the CLI argument vector for an operation invocation.
- *
- * @param operation - The operation spec describing the command and its parameters.
- * @param params - User-supplied parameter values keyed by param name.
- * @param options - Per-call invoke options (timeout, stdin).
- * @param runtimeTimeoutMs - Default timeout from the runtime configuration.
- * @param includeOutputFlag - Whether to append `--output json`.
- * @returns The argument array ready to be passed to `spawn`.
- * @throws {SuperDocCliError} With code `INVALID_ARGUMENT` if a required parameter is missing.
- */
-export function buildOperationArgv(
-  operation: OperationSpec,
-  params: Record<string, unknown>,
-  options: InvokeOptions,
-  runtimeTimeoutMs: number | undefined,
-  includeOutputFlag: boolean,
-  defaultChangeMode?: ChangeMode,
-): string[] {
-  const normalizedParams =
-    defaultChangeMode != null && params.changeMode == null && operation.params.some((param) => param.name === 'changeMode')
-      ? { ...params, changeMode: defaultChangeMode }
-      : params;
-
-  const args: string[] = [...operation.command];
-  for (const param of operation.params) {
-    encodeParam(args, param, normalizedParams[param.name]);
-  }
-
-  const timeoutMs = options.timeoutMs ?? runtimeTimeoutMs;
-  if (timeoutMs != null) {
-    args.push('--timeout-ms', String(timeoutMs));
-  }
-
-  if (includeOutputFlag) {
-    args.push('--output', 'json');
-  }
-
-  return args;
-}