@superdoc-dev/sdk 1.0.0-alpha.1

package/src/runtime/spawn.ts

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

package/src/runtime/transport-common.ts

@@ -0,0 +1,134 @@
+import { SuperDocCliError } from './errors';
+
+export type ParamType = 'string' | 'number' | 'boolean' | 'json' | 'string[]';
+export type ParamKind = 'doc' | 'flag' | 'jsonFlag';
+
+export interface OperationParamSpec {
+  readonly name: string;
+  readonly kind: ParamKind;
+  flag?: string;
+  readonly type: ParamType;
+  required?: boolean;
+}
+
+export interface OperationSpec {
+  readonly id: string;
+  readonly command: readonly string[];
+  readonly params: readonly OperationParamSpec[];
+}
+
+export interface InvokeOptions {
+  timeoutMs?: number;
+  stdinBytes?: Uint8Array;
+}
+
+export type SuperDocTransport = 'spawn' | 'host';
+
+export interface SuperDocHostOptions {
+  startupTimeoutMs?: number;
+  shutdownTimeoutMs?: number;
+  requestTimeoutMs?: number;
+  watchdogTimeoutMs?: number;
+  maxQueueDepth?: number;
+}
+
+export interface SuperDocClientOptions {
+  cliBin?: string;
+  env?: Record<string, string | undefined>;
+  transport?: SuperDocTransport;
+  host?: SuperDocHostOptions;
+}
+
+export interface CliInvocation {
+  command: string;
+  prefixArgs: string[];
+}
+
+function hasExtension(filePath: string, extension: string): boolean {
+  return filePath.toLowerCase().endsWith(extension);
+}
+
+export function resolveInvocation(cliBin: string): CliInvocation {
+  if (hasExtension(cliBin, '.js')) {
+    return { command: 'node', prefixArgs: [cliBin] };
+  }
+
+  if (hasExtension(cliBin, '.ts')) {
+    return { command: 'bun', prefixArgs: [cliBin] };
+  }
+
+  return { command: cliBin, prefixArgs: [] };
+}
+
+function toCliFlag(flag: string): string {
+  return `--${flag}`;
+}
+
+function encodeParam(args: string[], spec: OperationParamSpec, value: unknown): void {
+  if (value == null) {
+    if (spec.required) {
+      throw new SuperDocCliError(`Missing required parameter: ${spec.name}`, {
+        code: 'INVALID_ARGUMENT',
+      });
+    }
+    return;
+  }
+
+  if (spec.kind === 'doc') {
+    args.push(String(value));
+    return;
+  }
+
+  const flag = toCliFlag(spec.flag ?? spec.name);
+
+  if (spec.type === 'boolean') {
+    if (value === true) {
+      args.push(flag);
+    }
+    return;
+  }
+
+  if (spec.type === 'string[]') {
+    if (!Array.isArray(value)) {
+      throw new SuperDocCliError(`Parameter ${spec.name} must be an array of strings.`, {
+        code: 'INVALID_ARGUMENT',
+      });
+    }
+
+    for (const item of value) {
+      args.push(flag, String(item));
+    }
+    return;
+  }
+
+  if (spec.type === 'json') {
+    args.push(flag, JSON.stringify(value));
+    return;
+  }
+
+  args.push(flag, String(value));
+}
+
+export function buildOperationArgv(
+  operation: OperationSpec,
+  params: Record<string, unknown>,
+  options: InvokeOptions,
+  runtimeTimeoutMs: number | undefined,
+  includeOutputFlag: boolean,
+): string[] {
+  const args: string[] = [...operation.command];
+  for (const param of operation.params) {
+    encodeParam(args, param, params[param.name]);
+  }
+
+  const timeoutMs = options.timeoutMs ?? runtimeTimeoutMs;
+  if (timeoutMs != null) {
+    args.push('--timeout-ms', String(timeoutMs));
+  }
+
+  if (includeOutputFlag) {
+    args.push('--output', 'json');
+  }
+
+  return args;
+}

package/src/skills.ts

@@ -0,0 +1,76 @@
+import { readFileSync, readdirSync } from 'node:fs';
+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_-]*$/;
+
+function resolveSkillFilePath(skillName: string): string {
+  const filePath = path.resolve(skillsDir, `${skillName}.md`);
+  const root = `${skillsDir}${path.sep}`;
+  if (!filePath.startsWith(root)) {
+    throw new SuperDocCliError('Skill name resolved outside SDK skill directory.', {
+      code: 'INVALID_ARGUMENT',
+      details: { skillName },
+    });
+  }
+  return filePath;
+}
+
+export function listSkills(): string[] {
+  try {
+    return readdirSync(skillsDir)
+      .filter((entry) => path.extname(entry) === '.md')
+      .map((entry) => path.basename(entry, '.md'))
+      .sort();
+  } catch (error) {
+    throw new SuperDocCliError('Unable to enumerate SDK skills.', {
+      code: 'SKILL_IO_ERROR',
+      details: {
+        skillsDir,
+        message: error instanceof Error ? error.message : String(error),
+      },
+    });
+  }
+}
+
+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 filePath = resolveSkillFilePath(normalized);
+  try {
+    return readFileSync(filePath, 'utf8');
+  } catch (error) {
+    const nodeError = error as NodeJS.ErrnoException;
+    if (nodeError?.code === 'ENOENT') {
+      let available: string[] = [];
+      try {
+        available = listSkills();
+      } catch {
+        // Keep available empty when directory enumeration itself fails.
+      }
+      throw new SuperDocCliError('Requested SDK skill was not found.', {
+        code: 'SKILL_NOT_FOUND',
+        details: {
+          name: normalized,
+          available,
+        },
+      });
+    }
+
+    throw new SuperDocCliError('Requested SDK skill was not found.', {
+      code: 'SKILL_IO_ERROR',
+      details: {
+        name: normalized,
+        message: error instanceof Error ? error.message : String(error),
+      },
+    });
+  }
+}