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

package/src/index.ts

@@ -1,87 +0,0 @@
-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, installSkill, listSkills } from './skills';
-export {
-  chooseTools,
-  dispatchSuperDocTool,
-  getToolCatalog,
-  inferDocumentFeatures,
-  listTools,
-  resolveToolOperation,
-} from './tools';
-export { SuperDocCliError } from './runtime/errors';
-export type {
-  InvokeOptions,
-  OperationSpec,
-  OperationParamSpec,
-  SuperDocClientOptions,
-} from './runtime/process';
-export type {
-  DocumentFeatures,
-  ToolChooserInput,
-  ToolPhase,
-  ToolProfile,
-  ToolProvider,
-} from './tools';

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

@@ -1,38 +0,0 @@
-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

@@ -1,174 +0,0 @@
-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

@@ -1,109 +0,0 @@
-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;
-}
-
-/**
- * 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) {
-    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

@@ -1,30 +0,0 @@
-/**
- * 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;
-  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;
-  }
-}