@superdoc-dev/sdk 1.0.0-alpha.1 → 1.0.0-alpha.2

package/src/index.ts

@@ -1,24 +1,63 @@
 import { createDocApi } from './generated/client';
 import { SuperDocRuntime, type SuperDocClientOptions } from './runtime/process';
 
+/**
+ * High-level client for interacting with SuperDoc documents via the CLI.
+ *
+ * Provides a typed `doc` API for opening, querying, and mutating documents.
+ * Call {@link connect} before operations and {@link dispose} when finished
+ * to manage the host process lifecycle.
+ *
+ * @example
+ * ```typescript
+ * const client = new SuperDocClient();
+ * await client.connect();
+ * const result = await client.doc.find({ doc: 'report.docx', type: 'text', pattern: 'hello' });
+ * await client.dispose();
+ * ```
+ */
 export class SuperDocClient {
   private readonly runtime: SuperDocRuntime;
   readonly doc: ReturnType<typeof createDocApi>;
 
+  /**
+   * @param options - Client configuration including environment overrides.
+   */
   constructor(options: SuperDocClientOptions = {}) {
     this.runtime = new SuperDocRuntime(options);
     this.doc = createDocApi(this.runtime);
   }
 
+  /**
+   * Establish the connection to the CLI host process.
+   * Can be called eagerly; otherwise the host starts lazily on the first command.
+   */
   async connect(): Promise<void> {
     await this.runtime.connect();
   }
 
+  /**
+   * Shut down the CLI host process and release resources.
+   */
   async dispose(): Promise<void> {
     await this.runtime.dispose();
   }
 }
 
+/**
+ * Create a new {@link SuperDocClient} instance.
+ *
+ * @param options - Client configuration.
+ * @returns A configured client ready for document operations.
+ *
+ * @example
+ * ```typescript
+ * const client = createSuperDocClient();
+ * await client.connect();
+ * const info = await client.doc.info({ doc: 'report.docx' });
+ * await client.dispose();
+ * ```
+ */
 export function createSuperDocClient(options: SuperDocClientOptions = {}): SuperDocClient {
   return new SuperDocClient(options);
 }

package/src/runtime/__tests__/transport-common.test.ts

@@ -0,0 +1,151 @@
+import { describe, expect, test } from 'bun:test';
+import { buildOperationArgv, resolveInvocation, type OperationSpec } from '../transport-common';
+
+describe('resolveInvocation', () => {
+  test('resolves .js files via node', () => {
+    const result = resolveInvocation('/path/to/cli.js');
+    expect(result).toEqual({ command: 'node', prefixArgs: ['/path/to/cli.js'] });
+  });
+
+  test('resolves .ts files via bun', () => {
+    const result = resolveInvocation('/path/to/cli.ts');
+    expect(result).toEqual({ command: 'bun', prefixArgs: ['/path/to/cli.ts'] });
+  });
+
+  test('resolves plain binaries directly', () => {
+    const result = resolveInvocation('/usr/bin/superdoc');
+    expect(result).toEqual({ command: '/usr/bin/superdoc', prefixArgs: [] });
+  });
+
+  test('extension check is case-insensitive', () => {
+    expect(resolveInvocation('/path/CLI.JS').command).toBe('node');
+    expect(resolveInvocation('/path/CLI.TS').command).toBe('bun');
+  });
+});
+
+describe('buildOperationArgv', () => {
+  const baseOperation: OperationSpec = {
+    id: 'test.op',
+    command: ['test', 'run'],
+    params: [],
+  };
+
+  test('starts with command segments', () => {
+    const args = buildOperationArgv(baseOperation, {}, {}, undefined, false);
+    expect(args).toEqual(['test', 'run']);
+  });
+
+  test('appends --output json when includeOutputFlag is true', () => {
+    const args = buildOperationArgv(baseOperation, {}, {}, undefined, true);
+    expect(args).toEqual(['test', 'run', '--output', 'json']);
+  });
+
+  test('encodes string flag parameters', () => {
+    const op: OperationSpec = {
+      ...baseOperation,
+      params: [{ name: 'session', kind: 'flag', flag: 'session', type: 'string' }],
+    };
+    const args = buildOperationArgv(op, { session: 'my-session' }, {}, undefined, false);
+    expect(args).toEqual(['test', 'run', '--session', 'my-session']);
+  });
+
+  test('encodes boolean flag parameters as presence-only', () => {
+    const op: OperationSpec = {
+      ...baseOperation,
+      params: [{ name: 'force', kind: 'flag', flag: 'force', type: 'boolean' }],
+    };
+    const trueArgs = buildOperationArgv(op, { force: true }, {}, undefined, false);
+    expect(trueArgs).toEqual(['test', 'run', '--force']);
+
+    const falseArgs = buildOperationArgv(op, { force: false }, {}, undefined, false);
+    expect(falseArgs).toEqual(['test', 'run']);
+  });
+
+  test('encodes number flag parameters', () => {
+    const op: OperationSpec = {
+      ...baseOperation,
+      params: [{ name: 'limit', kind: 'flag', flag: 'limit', type: 'number' }],
+    };
+    const args = buildOperationArgv(op, { limit: 10 }, {}, undefined, false);
+    expect(args).toEqual(['test', 'run', '--limit', '10']);
+  });
+
+  test('encodes json flag parameters as JSON strings', () => {
+    const op: OperationSpec = {
+      ...baseOperation,
+      params: [{ name: 'query', kind: 'jsonFlag', flag: 'query-json', type: 'json' }],
+    };
+    const args = buildOperationArgv(op, { query: { type: 'text' } }, {}, undefined, false);
+    expect(args).toEqual(['test', 'run', '--query-json', '{"type":"text"}']);
+  });
+
+  test('encodes doc positional parameters', () => {
+    const op: OperationSpec = {
+      ...baseOperation,
+      params: [{ name: 'doc', kind: 'doc', type: 'string' }],
+    };
+    const args = buildOperationArgv(op, { doc: '/path/to/file.docx' }, {}, undefined, false);
+    expect(args).toEqual(['test', 'run', '/path/to/file.docx']);
+  });
+
+  test('encodes string[] flag parameters as repeated flags', () => {
+    const op: OperationSpec = {
+      ...baseOperation,
+      params: [{ name: 'include', kind: 'flag', flag: 'include', type: 'string[]' }],
+    };
+    const args = buildOperationArgv(op, { include: ['a', 'b'] }, {}, undefined, false);
+    expect(args).toEqual(['test', 'run', '--include', 'a', '--include', 'b']);
+  });
+
+  test('skips null/undefined optional parameters', () => {
+    const op: OperationSpec = {
+      ...baseOperation,
+      params: [{ name: 'session', kind: 'flag', flag: 'session', type: 'string' }],
+    };
+    const args = buildOperationArgv(op, {}, {}, undefined, false);
+    expect(args).toEqual(['test', 'run']);
+  });
+
+  test('throws on missing required parameters', () => {
+    const op: OperationSpec = {
+      ...baseOperation,
+      params: [{ name: 'doc', kind: 'doc', type: 'string', required: true }],
+    };
+    expect(() => buildOperationArgv(op, {}, {}, undefined, false)).toThrow('Missing required parameter: doc');
+  });
+
+  test('throws on non-array value for string[] parameter', () => {
+    const op: OperationSpec = {
+      ...baseOperation,
+      params: [{ name: 'include', kind: 'flag', flag: 'include', type: 'string[]' }],
+    };
+    expect(() => buildOperationArgv(op, { include: 'not-an-array' }, {}, undefined, false)).toThrow(
+      'must be an array',
+    );
+  });
+
+  test('appends timeout from invoke options', () => {
+    const args = buildOperationArgv(baseOperation, {}, { timeoutMs: 5000 }, undefined, false);
+    expect(args).toEqual(['test', 'run', '--timeout-ms', '5000']);
+  });
+
+  test('invoke timeout takes precedence over runtime timeout', () => {
+    const args = buildOperationArgv(baseOperation, {}, { timeoutMs: 3000 }, 10000, false);
+    expect(args).toContain('3000');
+    expect(args).not.toContain('10000');
+  });
+
+  test('falls back to runtime timeout when invoke timeout is absent', () => {
+    const args = buildOperationArgv(baseOperation, {}, {}, 7000, false);
+    expect(args).toEqual(['test', 'run', '--timeout-ms', '7000']);
+  });
+
+  test('uses flag name as fallback when flag property is undefined', () => {
+    const op: OperationSpec = {
+      ...baseOperation,
+      params: [{ name: 'mode', kind: 'flag', type: 'string' }],
+    };
+    const args = buildOperationArgv(op, { mode: 'fast' }, {}, undefined, false);
+    expect(args).toEqual(['test', 'run', '--mode', 'fast']);
+  });
+});

package/src/runtime/embedded-cli.ts

@@ -69,6 +69,16 @@ function resolveFromWorkspaceFallback(target: SupportedTarget): string | null {
   return filePath;
 }
 
+/**
+ * Resolve the path to the embedded SuperDoc CLI binary for the current platform.
+ *
+ * Checks platform-specific npm packages first, then falls back to a workspace
+ * `platforms/` directory. Ensures the binary is executable before returning.
+ *
+ * @returns Absolute path to the CLI binary.
+ * @throws {SuperDocCliError} With code `UNSUPPORTED_PLATFORM` if the current OS/arch is not supported.
+ * @throws {SuperDocCliError} With code `CLI_BINARY_MISSING` if no binary is found.
+ */
 export function resolveEmbeddedCliBinary(): string {
   const target = resolveTarget();
   if (!target) {

package/src/runtime/errors.ts

@@ -1,3 +1,20 @@
+/**
+ * Error thrown by the SuperDoc SDK when a CLI operation fails.
+ *
+ * Includes a machine-readable `code` for programmatic error handling
+ * and optional `details` with structured diagnostic context.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await client.doc.open({ doc: 'missing.docx' });
+ * } catch (error) {
+ *   if (error instanceof SuperDocCliError) {
+ *     console.error(error.code, error.message);
+ *   }
+ * }
+ * ```
+ */
 export class SuperDocCliError extends Error {
   readonly code: string;
   readonly details?: unknown;

package/src/runtime/host.ts

@@ -1,6 +1,6 @@
 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 { buildOperationArgv, resolveInvocation, type InvokeOptions, type OperationSpec, type SuperDocClientOptions } from './transport-common';
 import { SuperDocCliError } from './errors';
 
 type PendingRequest = {
@@ -27,6 +27,12 @@ const REQUIRED_FEATURES = ['cli.invoke', 'host.shutdown'];
 
 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>;
@@ -43,19 +49,15 @@ export class HostTransport {
   private connecting: Promise<void> | null = null;
   private stopping = false;
 
-  constructor(options: {
-    cliBin: string;
-    env?: Record<string, string | undefined>;
-    host?: SuperDocHostOptions;
-  }) {
+  constructor(options: { cliBin: string } & SuperDocClientOptions) {
     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;
+    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;
   }
 
   async connect(): Promise<void> {

package/src/runtime/process.ts

@@ -1,36 +1,27 @@
 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>;
-};
-
+/**
+ * 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: RuntimeTransport;
+  private readonly transport: HostTransport;
 
   constructor(options: SuperDocClientOptions = {}) {
-    const cliBin = options.cliBin ?? process.env.SUPERDOC_CLI_BIN ?? resolveEmbeddedCliBinary();
-    const transportMode = options.transport ?? 'spawn';
+    const cliBin = process.env.SUPERDOC_CLI_BIN ?? resolveEmbeddedCliBinary();
 
-    this.transport = this.createTransport(transportMode, {
+    this.transport = new HostTransport({
       cliBin,
-      env: options.env,
-      host: options.host,
+      ...options,
     });
   }
 
@@ -49,21 +40,6 @@ export class SuperDocRuntime {
   ): 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 };
+export type { InvokeOptions, OperationParamSpec, OperationSpec, SuperDocClientOptions };

package/src/runtime/transport-common.ts

@@ -1,44 +1,52 @@
 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;
-  flag?: string;
+  readonly flag?: string;
   readonly type: ParamType;
-  required?: boolean;
+  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 SuperDocTransport = 'spawn' | 'host';
-
-export interface SuperDocHostOptions {
+/** 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;
 }
 
-export interface SuperDocClientOptions {
-  cliBin?: string;
-  env?: Record<string, string | undefined>;
-  transport?: SuperDocTransport;
-  host?: SuperDocHostOptions;
-}
-
+/** Resolved command and prefix args for spawning the CLI. */
 export interface CliInvocation {
   command: string;
   prefixArgs: string[];
@@ -48,6 +56,12 @@ 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] };
@@ -109,6 +123,17 @@ function encodeParam(args: string[], spec: OperationParamSpec, value: unknown):
   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>,

package/src/skills.ts

@@ -18,6 +18,12 @@ function resolveSkillFilePath(skillName: string): string {
   return filePath;
 }
 
+/**
+ * List the names of all SDK skills bundled with this package.
+ *
+ * @returns Sorted array of skill names (without the `.md` extension).
+ * @throws {SuperDocCliError} With code `SKILL_IO_ERROR` if the skills directory cannot be read.
+ */
 export function listSkills(): string[] {
   try {
     return readdirSync(skillsDir)
@@ -35,6 +41,15 @@ export function listSkills(): string[] {
   }
 }
 
+/**
+ * Read the content of a bundled SDK skill by name.
+ *
+ * @param name - Skill name (e.g. `"editing-docx"`). Must match `[A-Za-z0-9][A-Za-z0-9_-]*`.
+ * @returns The skill file content as a UTF-8 string.
+ * @throws {SuperDocCliError} With code `INVALID_ARGUMENT` if the name is empty or contains invalid characters.
+ * @throws {SuperDocCliError} With code `SKILL_NOT_FOUND` if no skill with that name exists.
+ * @throws {SuperDocCliError} With code `SKILL_IO_ERROR` for other file-system read failures.
+ */
 export function getSkill(name: string): string {
   const normalized = name.trim();
   if (!normalized || !SKILL_NAME_RE.test(normalized)) {

package/src/runtime/spawn.ts

@@ -1,190 +0,0 @@
-import { spawn } from 'node:child_process';
-import { CONTRACT } from '../generated/contract';
-import { SuperDocCliError } from './errors';
-import { buildOperationArgv, resolveInvocation, type InvokeOptions, type OperationSpec } from './transport-common';
-
-type CliEnvelopeSuccess = {
-  ok: true;
-  command: string;
-  data: Record<string, unknown>;
-  meta?: {
-    version?: string;
-  };
-};
-
-type CliEnvelopeError = {
-  ok: false;
-  error: {
-    code: string;
-    message: string;
-    details?: unknown;
-  };
-  meta?: {
-    version?: string;
-  };
-};
-
-type CliEnvelope = CliEnvelopeSuccess | CliEnvelopeError;
-
-function parseEnvelope(stdout: string, stderr: string): CliEnvelope {
-  const output = stdout || stderr;
-  if (!output.trim()) {
-    throw new SuperDocCliError('CLI returned no JSON envelope.', {
-      code: 'COMMAND_FAILED',
-      details: { stdout, stderr },
-    });
-  }
-
-  const attempts: string[] = [output.trim()];
-  const lines = output.split(/\r?\n/);
-  for (let index = 0; index < lines.length; index += 1) {
-    if (!lines[index]?.trim().startsWith('{')) continue;
-    attempts.push(lines.slice(index).join('\n').trim());
-  }
-
-  for (const candidate of attempts) {
-    if (!candidate) continue;
-    try {
-      const parsed = JSON.parse(candidate) as CliEnvelope;
-      if (typeof parsed === 'object' && parsed != null && 'ok' in parsed) {
-        return parsed;
-      }
-    } catch {
-      // try next candidate
-    }
-  }
-
-  try {
-    return JSON.parse(output.trim()) as CliEnvelope;
-  } catch (error) {
-    throw new SuperDocCliError('CLI returned invalid JSON envelope.', {
-      code: 'JSON_PARSE_ERROR',
-      details: {
-        stdout,
-        stderr,
-        message: error instanceof Error ? error.message : String(error),
-      },
-    });
-  }
-}
-
-function parseSemver(version: string): [number, number, number] | null {
-  const core = version.split('-', 1)[0];
-  const [majorText, minorText, patchText] = core.split('.');
-  if (!majorText || !minorText || !patchText) return null;
-
-  const major = Number(majorText);
-  const minor = Number(minorText);
-  const patch = Number(patchText);
-  if (!Number.isInteger(major) || !Number.isInteger(minor) || !Number.isInteger(patch)) {
-    return null;
-  }
-  return [major, minor, patch];
-}
-
-function isVersionLessThan(actual: string, minimum: string): boolean {
-  const actualParsed = parseSemver(actual);
-  const minimumParsed = parseSemver(minimum);
-  if (!actualParsed || !minimumParsed) return false;
-
-  if (actualParsed[0] !== minimumParsed[0]) return actualParsed[0] < minimumParsed[0];
-  if (actualParsed[1] !== minimumParsed[1]) return actualParsed[1] < minimumParsed[1];
-  return actualParsed[2] < minimumParsed[2];
-}
-
-function assertCompatibleCliVersion(envelope: CliEnvelope): void {
-  const actualVersion = envelope.meta?.version;
-  const minimumVersion = CONTRACT.cli.minVersion;
-  if (!actualVersion || !minimumVersion) return;
-  if (actualVersion === '0.0.0') return;
-
-  if (isVersionLessThan(actualVersion, minimumVersion)) {
-    throw new SuperDocCliError(
-      `CLI version ${actualVersion} is older than minimum required ${minimumVersion}.`,
-      {
-        code: 'CLI_VERSION_UNSUPPORTED',
-        details: {
-          cliVersion: actualVersion,
-          minVersion: minimumVersion,
-        },
-      },
-    );
-  }
-}
-
-export class SpawnTransport {
-  private readonly cliBin: string;
-  private readonly env?: Record<string, string | undefined>;
-
-  constructor(options: { cliBin: string; env?: Record<string, string | undefined> }) {
-    this.cliBin = options.cliBin;
-    this.env = options.env;
-  }
-
-  async invoke<TData extends Record<string, unknown>>(
-    operation: OperationSpec,
-    params: Record<string, unknown> = {},
-    options: InvokeOptions = {},
-  ): Promise<TData> {
-    const { command, prefixArgs } = resolveInvocation(this.cliBin);
-    const commandArgs = buildOperationArgv(operation, params, options, undefined, true);
-    const args: string[] = [...prefixArgs, ...commandArgs];
-
-    const spawned = spawn(command, args, {
-      env: {
-        ...process.env,
-        ...(this.env ?? {}),
-      },
-      stdio: ['pipe', 'pipe', 'pipe'],
-    });
-
-    let stdout = '';
-    let stderr = '';
-
-    const stdoutPromise = new Promise<void>((resolve) => {
-      spawned.stdout.on('data', (chunk) => {
-        stdout += String(chunk);
-      });
-      spawned.stdout.on('end', () => resolve());
-    });
-
-    const stderrPromise = new Promise<void>((resolve) => {
-      spawned.stderr.on('data', (chunk) => {
-        stderr += String(chunk);
-      });
-      spawned.stderr.on('end', () => resolve());
-    });
-
-    if (options.stdinBytes) {
-      spawned.stdin.write(options.stdinBytes);
-    }
-    spawned.stdin.end();
-
-    const exitCode = await new Promise<number>((resolve, reject) => {
-      spawned.on('error', reject);
-      spawned.on('close', (code) => resolve(code ?? 1));
-    });
-
-    await Promise.all([stdoutPromise, stderrPromise]);
-
-    const envelope = parseEnvelope(stdout, stderr);
-    assertCompatibleCliVersion(envelope);
-    if (envelope.ok) {
-      return envelope.data as TData;
-    }
-
-    throw new SuperDocCliError(envelope.error.message, {
-      code: envelope.error.code,
-      details: envelope.error.details,
-      exitCode,
-    });
-  }
-
-  async connect(): Promise<void> {
-    // no-op in one-shot spawn mode
-  }
-
-  async dispose(): Promise<void> {
-    // no-op in one-shot spawn mode
-  }
-}