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

package/src/index.ts

@@ -62,7 +62,15 @@ export function createSuperDocClient(options: SuperDocClientOptions = {}): Super
   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,
@@ -70,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

@@ -31,12 +31,12 @@ describe('buildOperationArgv', () => {
   };
 
   test('starts with command segments', () => {
-    const args = buildOperationArgv(baseOperation, {}, {}, undefined, false);
+    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);
+    const args = buildOperationArgv(baseOperation, {}, {}, undefined, true, undefined);
     expect(args).toEqual(['test', 'run', '--output', 'json']);
   });
 
@@ -45,7 +45,7 @@ describe('buildOperationArgv', () => {
       ...baseOperation,
       params: [{ name: 'session', kind: 'flag', flag: 'session', type: 'string' }],
     };
-    const args = buildOperationArgv(op, { session: 'my-session' }, {}, undefined, false);
+    const args = buildOperationArgv(op, { session: 'my-session' }, {}, undefined, false, undefined);
     expect(args).toEqual(['test', 'run', '--session', 'my-session']);
   });
 
@@ -54,10 +54,10 @@ describe('buildOperationArgv', () => {
       ...baseOperation,
       params: [{ name: 'force', kind: 'flag', flag: 'force', type: 'boolean' }],
     };
-    const trueArgs = buildOperationArgv(op, { force: true }, {}, undefined, false);
+    const trueArgs = buildOperationArgv(op, { force: true }, {}, undefined, false, undefined);
     expect(trueArgs).toEqual(['test', 'run', '--force']);
 
-    const falseArgs = buildOperationArgv(op, { force: false }, {}, undefined, false);
+    const falseArgs = buildOperationArgv(op, { force: false }, {}, undefined, false, undefined);
     expect(falseArgs).toEqual(['test', 'run']);
   });
 
@@ -66,7 +66,7 @@ describe('buildOperationArgv', () => {
       ...baseOperation,
       params: [{ name: 'limit', kind: 'flag', flag: 'limit', type: 'number' }],
     };
-    const args = buildOperationArgv(op, { limit: 10 }, {}, undefined, false);
+    const args = buildOperationArgv(op, { limit: 10 }, {}, undefined, false, undefined);
     expect(args).toEqual(['test', 'run', '--limit', '10']);
   });
 
@@ -75,7 +75,7 @@ describe('buildOperationArgv', () => {
       ...baseOperation,
       params: [{ name: 'query', kind: 'jsonFlag', flag: 'query-json', type: 'json' }],
     };
-    const args = buildOperationArgv(op, { query: { type: 'text' } }, {}, undefined, false);
+    const args = buildOperationArgv(op, { query: { type: 'text' } }, {}, undefined, false, undefined);
     expect(args).toEqual(['test', 'run', '--query-json', '{"type":"text"}']);
   });
 
@@ -84,7 +84,7 @@ describe('buildOperationArgv', () => {
       ...baseOperation,
       params: [{ name: 'doc', kind: 'doc', type: 'string' }],
     };
-    const args = buildOperationArgv(op, { doc: '/path/to/file.docx' }, {}, undefined, false);
+    const args = buildOperationArgv(op, { doc: '/path/to/file.docx' }, {}, undefined, false, undefined);
     expect(args).toEqual(['test', 'run', '/path/to/file.docx']);
   });
 
@@ -93,7 +93,7 @@ describe('buildOperationArgv', () => {
       ...baseOperation,
       params: [{ name: 'include', kind: 'flag', flag: 'include', type: 'string[]' }],
     };
-    const args = buildOperationArgv(op, { include: ['a', 'b'] }, {}, undefined, false);
+    const args = buildOperationArgv(op, { include: ['a', 'b'] }, {}, undefined, false, undefined);
     expect(args).toEqual(['test', 'run', '--include', 'a', '--include', 'b']);
   });
 
@@ -102,7 +102,7 @@ describe('buildOperationArgv', () => {
       ...baseOperation,
       params: [{ name: 'session', kind: 'flag', flag: 'session', type: 'string' }],
     };
-    const args = buildOperationArgv(op, {}, {}, undefined, false);
+    const args = buildOperationArgv(op, {}, {}, undefined, false, undefined);
     expect(args).toEqual(['test', 'run']);
   });
 
@@ -111,7 +111,7 @@ describe('buildOperationArgv', () => {
       ...baseOperation,
       params: [{ name: 'doc', kind: 'doc', type: 'string', required: true }],
     };
-    expect(() => buildOperationArgv(op, {}, {}, undefined, false)).toThrow('Missing required parameter: doc');
+    expect(() => buildOperationArgv(op, {}, {}, undefined, false, undefined)).toThrow('Missing required parameter: doc');
   });
 
   test('throws on non-array value for string[] parameter', () => {
@@ -119,24 +119,24 @@ describe('buildOperationArgv', () => {
       ...baseOperation,
       params: [{ name: 'include', kind: 'flag', flag: 'include', type: 'string[]' }],
     };
-    expect(() => buildOperationArgv(op, { include: 'not-an-array' }, {}, undefined, false)).toThrow(
+    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);
+    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);
+    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);
+    const args = buildOperationArgv(baseOperation, {}, {}, 7000, false, undefined);
     expect(args).toEqual(['test', 'run', '--timeout-ms', '7000']);
   });
 
@@ -145,7 +145,30 @@ describe('buildOperationArgv', () => {
       ...baseOperation,
       params: [{ name: 'mode', kind: 'flag', type: 'string' }],
     };
-    const args = buildOperationArgv(op, { mode: 'fast' }, {}, undefined, false);
+    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/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 SuperDocClientOptions } from './transport-common';
+import {
+  buildOperationArgv,
+  resolveInvocation,
+  type ChangeMode,
+  type InvokeOptions,
+  type OperationSpec,
+  type SuperDocClientOptions,
+} from './transport-common';
 import { SuperDocCliError } from './errors';
 
 type PendingRequest = {
@@ -24,6 +31,7 @@ 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;
 
@@ -41,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;
@@ -58,6 +67,13 @@ export class HostTransport {
     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> {
@@ -99,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

@@ -17,7 +17,7 @@ export class SuperDocRuntime {
   private readonly transport: HostTransport;
 
   constructor(options: SuperDocClientOptions = {}) {
-    const cliBin = process.env.SUPERDOC_CLI_BIN ?? resolveEmbeddedCliBinary();
+    const cliBin = options.env?.SUPERDOC_CLI_BIN ?? process.env.SUPERDOC_CLI_BIN ?? resolveEmbeddedCliBinary();
 
     this.transport = new HostTransport({
       cliBin,

package/src/runtime/transport-common.ts

@@ -30,6 +30,8 @@ export interface InvokeOptions {
   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. */
@@ -44,6 +46,8 @@ export interface SuperDocClientOptions {
   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. */
@@ -140,10 +144,16 @@ export function buildOperationArgv(
   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;

package/src/skills.ts

@@ -1,10 +1,34 @@
-import { readFileSync, readdirSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { SuperDocCliError } from './runtime/errors';
 
 const skillsDir = path.resolve(fileURLToPath(new URL('../skills', import.meta.url)));
 const SKILL_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+const SUPPORTED_SKILL_RUNTIMES = ['claude'] as const;
+const SUPPORTED_INSTALL_SCOPES = ['project', 'user'] as const;
+
+type SkillRuntime = (typeof SUPPORTED_SKILL_RUNTIMES)[number];
+type SkillInstallScope = (typeof SUPPORTED_INSTALL_SCOPES)[number];
+
+export interface InstallSkillOptions {
+  runtime?: SkillRuntime;
+  scope?: SkillInstallScope;
+  targetDir?: string;
+  cwd?: string;
+  homeDir?: string;
+  overwrite?: boolean;
+}
+
+export interface InstalledSkillResult {
+  name: string;
+  runtime: SkillRuntime;
+  scope: SkillInstallScope | 'custom';
+  path: string;
+  written: boolean;
+  overwritten: boolean;
+}
 
 function resolveSkillFilePath(skillName: string): string {
   const filePath = path.resolve(skillsDir, `${skillName}.md`);
@@ -18,6 +42,17 @@ function resolveSkillFilePath(skillName: string): string {
   return filePath;
 }
 
+function normalizeSkillName(name: string): string {
+  const normalized = name.trim();
+  if (!normalized || !SKILL_NAME_RE.test(normalized)) {
+    throw new SuperDocCliError('Skill name is required.', {
+      code: 'INVALID_ARGUMENT',
+      details: { name },
+    });
+  }
+  return normalized;
+}
+
 /**
  * List the names of all SDK skills bundled with this package.
  *
@@ -51,13 +86,7 @@ export function listSkills(): string[] {
  * @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)) {
-    throw new SuperDocCliError('Skill name is required.', {
-      code: 'INVALID_ARGUMENT',
-      details: { name },
-    });
-  }
+  const normalized = normalizeSkillName(name);
 
   const filePath = resolveSkillFilePath(normalized);
   try {
@@ -89,3 +118,78 @@ export function getSkill(name: string): string {
     });
   }
 }
+
+/**
+ * Install a bundled SDK skill into an agent runtime directory.
+ *
+ * Defaults to Claude's project-local skill path: `./.claude/skills/<name>/SKILL.md`.
+ */
+export function installSkill(name: string, options: InstallSkillOptions = {}): InstalledSkillResult {
+  const normalizedName = normalizeSkillName(name);
+  const runtime = options.runtime ?? 'claude';
+  if (!SUPPORTED_SKILL_RUNTIMES.includes(runtime)) {
+    throw new SuperDocCliError('Unsupported skill runtime.', {
+      code: 'INVALID_ARGUMENT',
+      details: { runtime, supportedRuntimes: SUPPORTED_SKILL_RUNTIMES },
+    });
+  }
+
+  const scope = options.scope ?? 'project';
+  if (!SUPPORTED_INSTALL_SCOPES.includes(scope)) {
+    throw new SuperDocCliError('Unsupported skill install scope.', {
+      code: 'INVALID_ARGUMENT',
+      details: { scope, supportedScopes: SUPPORTED_INSTALL_SCOPES },
+    });
+  }
+
+  const skillsRoot =
+    options.targetDir !== undefined
+      ? path.resolve(options.targetDir)
+      : scope === 'user'
+        ? path.resolve(options.homeDir ?? os.homedir(), '.claude', 'skills')
+        : path.resolve(options.cwd ?? process.cwd(), '.claude', 'skills');
+  const skillFile = path.join(skillsRoot, normalizedName, 'SKILL.md');
+  const overwrite = options.overwrite ?? true;
+  const alreadyExists = existsSync(skillFile);
+
+  if (!overwrite && alreadyExists) {
+    return {
+      name: normalizedName,
+      runtime,
+      scope: options.targetDir !== undefined ? 'custom' : scope,
+      path: skillFile,
+      written: false,
+      overwritten: false,
+    };
+  }
+
+  try {
+    const content = getSkill(name);
+    mkdirSync(path.dirname(skillFile), { recursive: true });
+    writeFileSync(skillFile, content, 'utf8');
+  } catch (error) {
+    if (error instanceof SuperDocCliError) {
+      throw error;
+    }
+
+    throw new SuperDocCliError('Unable to install SDK skill.', {
+      code: 'SKILL_IO_ERROR',
+      details: {
+        name: normalizedName,
+        runtime,
+        scope: options.targetDir !== undefined ? 'custom' : scope,
+        path: skillFile,
+        message: error instanceof Error ? error.message : String(error),
+      },
+    });
+  }
+
+  return {
+    name: normalizedName,
+    runtime,
+    scope: options.targetDir !== undefined ? 'custom' : scope,
+    path: skillFile,
+    written: true,
+    overwritten: alreadyExists,
+  };
+}