@superdoc-dev/sdk 1.0.0-alpha.1

package/src/index.ts

@@ -0,0 +1,33 @@
+import { createDocApi } from './generated/client';
+import { SuperDocRuntime, type SuperDocClientOptions } from './runtime/process';
+
+export class SuperDocClient {
+  private readonly runtime: SuperDocRuntime;
+  readonly doc: ReturnType<typeof createDocApi>;
+
+  constructor(options: SuperDocClientOptions = {}) {
+    this.runtime = new SuperDocRuntime(options);
+    this.doc = createDocApi(this.runtime);
+  }
+
+  async connect(): Promise<void> {
+    await this.runtime.connect();
+  }
+
+  async dispose(): Promise<void> {
+    await this.runtime.dispose();
+  }
+}
+
+export function createSuperDocClient(options: SuperDocClientOptions = {}): SuperDocClient {
+  return new SuperDocClient(options);
+}
+
+export { getSkill, listSkills } from './skills';
+export { SuperDocCliError } from './runtime/errors';
+export type {
+  InvokeOptions,
+  OperationSpec,
+  OperationParamSpec,
+  SuperDocClientOptions,
+} from './runtime/process';

package/src/runtime/embedded-cli.ts

@@ -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 { SuperDocCliError } from './errors';
+
+const require = createRequire(import.meta.url);
+
+type SupportedTarget = 'darwin-arm64' | 'darwin-x64' | 'linux-x64' | 'linux-arm64' | 'windows-x64';
+
+const TARGET_TO_PACKAGE: Record<SupportedTarget, string> = {
+  'darwin-arm64': '@superdoc-dev/sdk-darwin-arm64',
+  'darwin-x64': '@superdoc-dev/sdk-darwin-x64',
+  'linux-x64': '@superdoc-dev/sdk-linux-x64',
+  'linux-arm64': '@superdoc-dev/sdk-linux-arm64',
+  'windows-x64': '@superdoc-dev/sdk-windows-x64',
+};
+
+const TARGET_TO_DIR: Record<SupportedTarget, string> = {
+  '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',
+};
+
+function resolveTarget(): SupportedTarget | null {
+  const platform = process.platform;
+  const 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;
+}
+
+function binaryNameForTarget(target: SupportedTarget): string {
+  return target === 'windows-x64' ? 'superdoc.exe' : 'superdoc';
+}
+
+function ensureExecutable(binaryPath: string): void {
+  if (process.platform === 'win32') return;
+  try {
+    chmodSync(binaryPath, 0o755);
+  } catch {
+    // Non-fatal: if chmod fails, spawn() will surface the real execution error.
+  }
+}
+
+function resolveFromPlatformPackage(target: SupportedTarget): string | null {
+  const pkg = TARGET_TO_PACKAGE[target];
+  const binaryName = binaryNameForTarget(target);
+
+  try {
+    return require.resolve(`${pkg}/bin/${binaryName}`);
+  } catch {
+    return null;
+  }
+}
+
+function resolveFromWorkspaceFallback(target: SupportedTarget): string | null {
+  const binaryName = binaryNameForTarget(target);
+  const dirName = TARGET_TO_DIR[target];
+  const filePath = path.resolve(fileURLToPath(new URL('../../platforms', import.meta.url)), dirName, 'bin', binaryName);
+  if (!existsSync(filePath)) return null;
+  return filePath;
+}
+
+export function resolveEmbeddedCliBinary(): string {
+  const target = resolveTarget();
+  if (!target) {
+    throw new SuperDocCliError('No embedded SuperDoc CLI binary is available for this platform.', {
+      code: 'UNSUPPORTED_PLATFORM',
+      details: {
+        platform: process.platform,
+        arch: process.arch,
+      },
+    });
+  }
+
+  const platformPackagePath = resolveFromPlatformPackage(target);
+  const resolvedPath = platformPackagePath ?? resolveFromWorkspaceFallback(target);
+
+  if (!resolvedPath) {
+    throw new SuperDocCliError('Embedded SuperDoc CLI binary is missing for this platform.', {
+      code: 'CLI_BINARY_MISSING',
+      details: {
+        target,
+        packageName: TARGET_TO_PACKAGE[target],
+      },
+    });
+  }
+
+  ensureExecutable(resolvedPath);
+  return resolvedPath;
+}

package/src/runtime/errors.ts

@@ -0,0 +1,13 @@
+export class SuperDocCliError extends Error {
+  readonly code: string;
+  readonly details?: unknown;
+  readonly exitCode?: number;
+
+  constructor(message: string, options: { code: string; details?: unknown; exitCode?: number }) {
+    super(message);
+    this.name = 'SuperDocCliError';
+    this.code = options.code;
+    this.details = options.details;
+    this.exitCode = options.exitCode;
+  }
+}

package/src/runtime/host.ts

@@ -0,0 +1,463 @@
+import { spawn, type ChildProcessWithoutNullStreams } from 'node:child_process';
+import { createInterface, type Interface as ReadlineInterface } from 'node:readline';
+import { buildOperationArgv, resolveInvocation, type InvokeOptions, type OperationSpec, type SuperDocHostOptions } 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 JSON_RPC_TIMEOUT_CODE = -32011;
+
+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 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;
+    env?: Record<string, string | undefined>;
+    host?: SuperDocHostOptions;
+  }) {
+    this.cliBin = options.cliBin;
+    this.env = options.env;
+
+    this.startupTimeoutMs = options.host?.startupTimeoutMs ?? 5_000;
+    this.shutdownTimeoutMs = options.host?.shutdownTimeoutMs ?? 5_000;
+    this.requestTimeoutMs = options.host?.requestTimeoutMs;
+    this.watchdogTimeoutMs = options.host?.watchdogTimeoutMs ?? 30_000;
+    this.maxQueueDepth = options.host?.maxQueueDepth ?? 100;
+  }
+
+  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);
+    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

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