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

package/src/index.ts

@@ -1,29 +1,76 @@
 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);
 }
 
-export { getSkill, listSkills } from './skills';
+export { getSkill, installSkill, listSkills } from './skills';
+export {
+  chooseTools,
+  dispatchSuperDocTool,
+  getToolCatalog,
+  inferDocumentFeatures,
+  listTools,
+  resolveToolOperation,
+} from './tools';
 export { SuperDocCliError } from './runtime/errors';
 export type {
   InvokeOptions,
@@ -31,3 +78,10 @@ export type {
   OperationParamSpec,
   SuperDocClientOptions,
 } from './runtime/process';
+export type {
+  DocumentFeatures,
+  ToolChooserInput,
+  ToolPhase,
+  ToolProfile,
+  ToolProvider,
+} from './tools';

package/src/runtime/__tests__/process.test.ts

@@ -0,0 +1,38 @@
+import { afterEach, describe, expect, test } from 'bun:test';
+import { SuperDocRuntime } from '../process';
+
+const ORIGINAL_SUPERDOC_CLI_BIN = process.env.SUPERDOC_CLI_BIN;
+
+function runtimeCliBin(runtime: SuperDocRuntime): string {
+  return (runtime as unknown as { transport: { cliBin: string } }).transport.cliBin;
+}
+
+afterEach(() => {
+  if (ORIGINAL_SUPERDOC_CLI_BIN == null) {
+    delete process.env.SUPERDOC_CLI_BIN;
+    return;
+  }
+  process.env.SUPERDOC_CLI_BIN = ORIGINAL_SUPERDOC_CLI_BIN;
+});
+
+describe('SuperDocRuntime', () => {
+  test('prefers SUPERDOC_CLI_BIN from client options env over process env', () => {
+    process.env.SUPERDOC_CLI_BIN = '/process/env/superdoc';
+
+    const runtime = new SuperDocRuntime({
+      env: {
+        SUPERDOC_CLI_BIN: '/options/env/superdoc',
+      },
+    });
+
+    expect(runtimeCliBin(runtime)).toBe('/options/env/superdoc');
+  });
+
+  test('uses process env SUPERDOC_CLI_BIN when client options env does not provide one', () => {
+    process.env.SUPERDOC_CLI_BIN = '/process/env/superdoc';
+
+    const runtime = new SuperDocRuntime();
+
+    expect(runtimeCliBin(runtime)).toBe('/process/env/superdoc');
+  });
+});

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

@@ -0,0 +1,174 @@
+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, undefined);
+    expect(args).toEqual(['test', 'run']);
+  });
+
+  test('appends --output json when includeOutputFlag is true', () => {
+    const args = buildOperationArgv(baseOperation, {}, {}, undefined, true, undefined);
+    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, undefined);
+    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, undefined);
+    expect(trueArgs).toEqual(['test', 'run', '--force']);
+
+    const falseArgs = buildOperationArgv(op, { force: false }, {}, undefined, false, undefined);
+    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, undefined);
+    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, undefined);
+    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, undefined);
+    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, undefined);
+    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, undefined);
+    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, undefined)).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, undefined)).toThrow(
+      'must be an array',
+    );
+  });
+
+  test('appends timeout from invoke options', () => {
+    const args = buildOperationArgv(baseOperation, {}, { timeoutMs: 5000 }, undefined, false, undefined);
+    expect(args).toEqual(['test', 'run', '--timeout-ms', '5000']);
+  });
+
+  test('invoke timeout takes precedence over runtime timeout', () => {
+    const args = buildOperationArgv(baseOperation, {}, { timeoutMs: 3000 }, 10000, false, undefined);
+    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, undefined);
+    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, undefined);
+    expect(args).toEqual(['test', 'run', '--mode', 'fast']);
+  });
+
+  test('injects default change mode when operation supports changeMode and params omit it', () => {
+    const op: OperationSpec = {
+      ...baseOperation,
+      params: [{ name: 'changeMode', kind: 'flag', flag: 'change-mode', type: 'string' }],
+    };
+    const args = buildOperationArgv(op, {}, {}, undefined, false, 'tracked');
+    expect(args).toEqual(['test', 'run', '--change-mode', 'tracked']);
+  });
+
+  test('does not inject default change mode when operation does not support changeMode', () => {
+    const args = buildOperationArgv(baseOperation, {}, {}, undefined, false, 'tracked');
+    expect(args).toEqual(['test', 'run']);
+  });
+
+  test('explicit changeMode parameter overrides default change mode', () => {
+    const op: OperationSpec = {
+      ...baseOperation,
+      params: [{ name: 'changeMode', kind: 'flag', flag: 'change-mode', type: 'string' }],
+    };
+    const args = buildOperationArgv(op, { changeMode: 'direct' }, {}, undefined, false, 'tracked');
+    expect(args).toEqual(['test', 'run', '--change-mode', 'direct']);
+  });
+});

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,13 @@
 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 ChangeMode,
+  type InvokeOptions,
+  type OperationSpec,
+  type SuperDocClientOptions,
+} from './transport-common';
 import { SuperDocCliError } from './errors';
 
 type PendingRequest = {
@@ -24,9 +31,16 @@ type JsonRpcError = {
 
 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>;
@@ -35,6 +49,7 @@ export class HostTransport {
   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;
@@ -43,19 +58,22 @@ 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;
+    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> {
@@ -97,7 +115,7 @@ export class HostTransport {
   ): Promise<TData> {
     await this.ensureConnected();
 
-    const argv = buildOperationArgv(operation, params, options, this.requestTimeoutMs, false);
+    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);
 

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 = options.env?.SUPERDOC_CLI_BIN ?? 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,56 @@
 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 type ChangeMode = 'direct' | 'tracked';
 
-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;
+  /** Default change mode for mutation operations that support `changeMode`. */
+  defaultChangeMode?: ChangeMode;
 }
 
-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 +60,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,16 +127,33 @@ 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>,
   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, params[param.name]);
+    encodeParam(args, param, normalizedParams[param.name]);
   }
 
   const timeoutMs = options.timeoutMs ?? runtimeTimeoutMs;