runspec-node 0.3.0

package/src/inference.ts

@@ -0,0 +1,77 @@
+import type { ArgSpec, ScriptSpec } from './models';
+import { RunSpecError } from './errors';
+
+export const AUTONOMY_LEVELS = ['autonomous', 'confirm', 'supervised', 'manual'] as const;
+export const AUTONOMY_RANK = Object.fromEntries(AUTONOMY_LEVELS.map((l, i) => [l, i]));
+
+export function inferArg(raw: ArgSpec): ArgSpec {
+  const result = { ...raw };
+  const def = result.default;
+  const options = result.options;
+
+  if (!result.type) {
+    if (options !== undefined) {
+      result.type = 'choice';
+    } else if (typeof def === 'boolean') {
+      result.type = 'flag';
+    } else if (typeof def === 'number' && Number.isInteger(def)) {
+      result.type = 'int';
+    } else if (typeof def === 'number') {
+      result.type = 'float';
+    } else if (typeof def === 'string') {
+      result.type = 'str';
+    } else {
+      result.type = 'str';
+    }
+  }
+
+  if (result.required === undefined) {
+    const hasNoDefault = def === undefined || def === null;
+    result.required = hasNoDefault && result.type !== 'flag';
+  }
+
+  if (result.type === 'choice' && (!options || options.length === 0)) {
+    throw new RunSpecError(`Argument '${raw.name}' has type 'choice' but no 'options' list was provided.`);
+  }
+
+  return result;
+}
+
+export function inferScript(raw: ScriptSpec, configAutonomy: string): ScriptSpec {
+  const result = { ...raw };
+
+  if (!result.autonomy) {
+    result.autonomy = configAutonomy;
+  }
+
+  result.args = Object.fromEntries(Object.entries(result.args ?? {}).map(([name, arg]) => [name, inferArg(arg)]));
+
+  result.commands = Object.fromEntries(
+    Object.entries(result.commands ?? {}).map(([name, cmd]) => [name, inferScript(cmd, configAutonomy)]),
+  );
+
+  return result;
+}
+
+export function effectiveAutonomy(
+  scriptAutonomy: string,
+  providedArgs: Record<string, unknown>,
+  argSpecs: Record<string, ArgSpec>,
+): string {
+  let effective = scriptAutonomy;
+
+  for (const [argName, value] of Object.entries(providedArgs)) {
+    if (value === null || value === undefined) continue;
+    const spec = argSpecs[argName];
+    const argAutonomy = spec?.autonomy;
+    if (argAutonomy && isMoreRestrictive(argAutonomy, effective)) {
+      effective = argAutonomy;
+    }
+  }
+
+  return effective;
+}
+
+export function isMoreRestrictive(candidate: string, current: string): boolean {
+  return (AUTONOMY_RANK[candidate] ?? 0) > (AUTONOMY_RANK[current] ?? 0);
+}

package/src/loader.ts

@@ -0,0 +1,120 @@
+import * as fs from 'fs';
+import { parse as parseTOML } from 'smol-toml';
+import type { RawConfig, RawSpec, ScriptSpec, ArgSpec, GroupSpec } from './models';
+
+export function loadRaw(configPath: string, format: 'pyproject' | 'runspec'): RawSpec {
+  const content = fs.readFileSync(configPath, 'utf-8');
+  const data = parseTOML(content) as Record<string, unknown>;
+
+  let raw: Record<string, unknown>;
+  let entryPoints: Record<string, string> = {};
+
+  if (format === 'pyproject') {
+    raw = ((data as any)?.tool?.runspec ?? {}) as Record<string, unknown>;
+    entryPoints = readEntryPoints(data);
+  } else {
+    raw = data;
+  }
+
+  const runnablesRaw: Record<string, Record<string, unknown>> = {};
+  for (const [key, value] of Object.entries(raw)) {
+    if (key !== 'config' && typeof value === 'object' && value !== null && !Array.isArray(value)) {
+      runnablesRaw[key] = value as Record<string, unknown>;
+    }
+  }
+
+  return {
+    config: normaliseConfig((raw['config'] ?? {}) as Record<string, unknown>),
+    runnables: normaliseRunnables(runnablesRaw),
+    entryPoints,
+  };
+}
+
+function normaliseConfig(raw: Record<string, unknown>): RawConfig {
+  return {
+    autonomyDefault: (raw['autonomy-default'] as string | undefined) ?? 'confirm',
+    lang: raw['lang'] as string | undefined,
+    version: String(raw['version'] ?? '1'),
+  };
+}
+
+function normaliseRunnables(raw: Record<string, Record<string, unknown>>): Record<string, ScriptSpec> {
+  return Object.fromEntries(Object.entries(raw).map(([name, data]) => [name, normaliseScript(name, data)]));
+}
+
+function normaliseScript(name: string, raw: Record<string, unknown>): ScriptSpec {
+  return {
+    name,
+    description: raw['description'] as string | undefined,
+    autonomy: raw['autonomy'] as string | undefined,
+    autonomyReason: raw['autonomy-reason'] as string | undefined,
+    output: raw['output'] as string | undefined,
+    args: normaliseArgs((raw['args'] ?? {}) as Record<string, unknown>),
+    groups: normaliseGroups((raw['groups'] ?? {}) as Record<string, unknown>),
+    commands: normaliseCommands((raw['commands'] ?? {}) as Record<string, Record<string, unknown>>),
+  };
+}
+
+function normaliseArgs(raw: Record<string, unknown>): Record<string, ArgSpec> {
+  return Object.fromEntries(
+    Object.entries(raw).map(([name, value]) => {
+      if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+        return [name, normaliseArg(name, value as Record<string, unknown>)];
+      }
+      return [name, normaliseArg(name, { default: value })];
+    }),
+  );
+}
+
+function normaliseArg(name: string, raw: Record<string, unknown>): ArgSpec {
+  return {
+    name,
+    type: (raw['type'] as string | undefined) ?? undefined,
+    required: raw['required'] as boolean | undefined,
+    default: raw['default'],
+    description: raw['description'] as string | undefined,
+    options: raw['options'] as string[] | undefined,
+    range: raw['range'] as [number, number] | undefined,
+    multiple: (raw['multiple'] as boolean | undefined) ?? false,
+    delimiter: raw['delimiter'] as string | undefined,
+    short: raw['short'] as string | undefined,
+    env: raw['env'] as string | undefined,
+    deprecated: raw['deprecated'] as string | undefined,
+    autonomy: raw['autonomy'] as string | undefined,
+    ui: raw['ui'] as string | undefined,
+    meta: raw['meta'] as Record<string, unknown> | undefined,
+  };
+}
+
+function normaliseGroups(raw: Record<string, unknown>): Record<string, GroupSpec> {
+  return Object.fromEntries(
+    Object.entries(raw).map(([name, data]) => {
+      const g = data as Record<string, unknown>;
+      return [
+        name,
+        {
+          name,
+          args: (g['args'] as string[]) ?? [],
+          exclusive: (g['exclusive'] as boolean | undefined) ?? false,
+          inclusive: (g['inclusive'] as boolean | undefined) ?? false,
+          atLeastOne: (g['at-least-one'] as boolean | undefined) ?? false,
+          exactlyOne: (g['exactly-one'] as boolean | undefined) ?? false,
+          condition: g['if'] as string | undefined,
+          requires: (g['requires'] as string[] | undefined) ?? [],
+        } satisfies GroupSpec,
+      ];
+    }),
+  );
+}
+
+function normaliseCommands(raw: Record<string, Record<string, unknown>>): Record<string, ScriptSpec> {
+  return Object.fromEntries(Object.entries(raw).map(([name, data]) => [name, normaliseScript(name, data)]));
+}
+
+function readEntryPoints(data: Record<string, unknown>): Record<string, string> {
+  const projectScripts = (data as any)?.project?.scripts;
+  if (projectScripts && typeof projectScripts === 'object') return projectScripts as Record<string, string>;
+  const poetryScripts = (data as any)?.tool?.poetry?.scripts;
+  if (poetryScripts && typeof poetryScripts === 'object') return poetryScripts as Record<string, string>;
+  return {};
+}

package/src/models.ts

@@ -0,0 +1,61 @@
+export interface RawConfig {
+  autonomyDefault: string;
+  lang?: string;
+  version: string;
+}
+
+export interface ArgSpec {
+  name: string;
+  type?: string;
+  required?: boolean;
+  default?: unknown;
+  description?: string;
+  options?: string[];
+  range?: [number, number];
+  multiple?: boolean;
+  delimiter?: string;
+  short?: string;
+  env?: string;
+  deprecated?: string;
+  autonomy?: string;
+  ui?: string;
+  meta?: Record<string, unknown>;
+}
+
+export interface GroupSpec {
+  name: string;
+  args: string[];
+  exclusive?: boolean;
+  inclusive?: boolean;
+  atLeastOne?: boolean;
+  exactlyOne?: boolean;
+  condition?: string;
+  requires?: string[];
+}
+
+export interface ScriptSpec {
+  name: string;
+  description?: string;
+  autonomy?: string;
+  autonomyReason?: string;
+  output?: string;
+  args: Record<string, ArgSpec>;
+  groups: Record<string, GroupSpec>;
+  commands: Record<string, ScriptSpec>;
+}
+
+export interface RawSpec {
+  config: RawConfig;
+  runnables: Record<string, ScriptSpec>;
+  entryPoints: Record<string, string>;
+}
+
+export interface ParsedArgs {
+  [key: string]: unknown;
+  readonly __agent__: boolean;
+  readonly __script__: string;
+  readonly __command__: string | undefined;
+  readonly __autonomy__: string;
+  readonly __source__: string;
+  readonly __spec__: ScriptSpec;
+}

package/src/parser.ts

@@ -0,0 +1,239 @@
+import * as path from 'path';
+import { findConfig, findScriptName } from './finder';
+import { loadRaw } from './loader';
+import { inferScript, effectiveAutonomy } from './inference';
+import { coerce } from './types';
+import { validateArgs, validateGroups, raiseIfErrors } from './validator';
+import { RunSpecError } from './errors';
+import type { ParsedArgs, ScriptSpec, ArgSpec } from './models';
+
+export interface ParseOptions {
+  scriptName?: string;
+  argv?: string[];
+  cwd?: string;
+}
+
+export function parse(opts: ParseOptions = {}): ParsedArgs {
+  const { scriptName, argv: argvOverride, cwd } = opts;
+
+  const { configPath, format } = findConfig(cwd);
+  const raw = loadRaw(configPath, format);
+  const config = raw.config;
+
+  const name = scriptName ?? findScriptName(configPath, format) ?? inferFromArgv();
+  if (!name) throw new RunSpecError('✗  Could not determine runnable name. Pass scriptName option.');
+  if (name === 'config') throw new RunSpecError("✗  'config' is a reserved name in runspec.\n   Rename your runnable.");
+
+  if (!(name in raw.runnables)) {
+    const available = Object.keys(raw.runnables).join(', ') || '(none)';
+    throw new RunSpecError(`✗  Runnable '${name}' not found.\n   Available: ${available}\n   Config: ${configPath}`);
+  }
+
+  const rawScript = inferScript(raw.runnables[name], config.autonomyDefault);
+
+  let argv = argvOverride ?? process.argv.slice(2);
+  let activeScript = rawScript;
+  let activeCommand: string | undefined;
+
+  const commands = rawScript.commands ?? {};
+  if (Object.keys(commands).length > 0 && argv.length > 0 && argv[0] in commands) {
+    activeCommand = argv[0];
+    activeScript = commands[argv[0]];
+    argv = argv.slice(1);
+  }
+
+  if (argv.includes('--help') || argv.includes('-h')) {
+    printHelp(name, activeScript, activeCommand);
+    process.exit(0);
+  }
+
+  let parsedValues = parseArgv(argv, activeScript.args ?? {});
+  parsedValues = applyEnv(parsedValues, activeScript.args ?? {});
+  parsedValues = applyDefaults(parsedValues, activeScript.args ?? {});
+
+  raiseIfErrors(validateArgs(parsedValues, activeScript.args ?? {}));
+  raiseIfErrors(validateGroups(parsedValues, activeScript.groups ?? {}));
+
+  const coercedValues = coerceValues(parsedValues, activeScript.args ?? {});
+
+  const autonomy = effectiveAutonomy(
+    activeScript.autonomy ?? config.autonomyDefault,
+    parsedValues,
+    activeScript.args ?? {},
+  );
+
+  const agent = ['1', 'true', 'yes'].includes((process.env['RUNSPEC_AGENT'] ?? '').toLowerCase());
+
+  return {
+    ...coercedValues,
+    __agent__: agent,
+    __script__: name,
+    __command__: activeCommand,
+    __autonomy__: autonomy,
+    __source__: configPath,
+    __spec__: activeScript,
+  } as ParsedArgs;
+}
+
+export function loadSpec(opts: ParseOptions = {}): ParsedArgs {
+  return parse({ ...opts, argv: [] });
+}
+
+function inferFromArgv(): string {
+  const argv1 = process.argv[1] ?? '';
+  return path.basename(argv1, path.extname(argv1)) || 'unknown';
+}
+
+function parseArgv(argv: string[], argSpecs: Record<string, ArgSpec>): Record<string, unknown> {
+  const nameMap: Record<string, string> = {};
+  const shortMap: Record<string, string> = {};
+
+  for (const [name, spec] of Object.entries(argSpecs)) {
+    const norm = name.replace(/-/g, '_');
+    nameMap[`--${name}`] = norm;
+    nameMap[`--${norm}`] = norm;
+    if (spec.short) shortMap[spec.short] = norm;
+  }
+
+  const result: Record<string, unknown> = {};
+  for (const name of Object.keys(argSpecs)) {
+    result[name.replace(/-/g, '_')] = undefined;
+  }
+
+  let i = 0;
+  while (i < argv.length) {
+    const token = argv[i];
+
+    if (token.startsWith('--') && token.includes('=')) {
+      const eqIdx = token.indexOf('=');
+      const key = token.slice(0, eqIdx);
+      const value = token.slice(eqIdx + 1);
+      const norm = nameMap[key];
+      if (norm) {
+        const hyphenName = norm.replace(/_/g, '-');
+        const spec = argSpecs[hyphenName] ?? argSpecs[norm] ?? {};
+        result[norm] = appendOrSet(result[norm], value, spec);
+      }
+      i++;
+      continue;
+    }
+
+    const norm = nameMap[token] ?? shortMap[token];
+    if (norm) {
+      const hyphenName = norm.replace(/_/g, '-');
+      const spec = argSpecs[hyphenName] ?? argSpecs[norm] ?? {};
+      const argType = spec.type ?? 'str';
+
+      if (argType === 'flag') {
+        result[norm] = true;
+        i++;
+      } else if (i + 1 < argv.length && !argv[i + 1].startsWith('-')) {
+        const raw = argv[i + 1];
+        const delimiter = spec.delimiter;
+        const parsed: string | string[] = delimiter ? raw.split(delimiter) : raw;
+        result[norm] = appendOrSet(result[norm], parsed, spec);
+        i += 2;
+      } else {
+        result[norm] = true;
+        i++;
+      }
+      continue;
+    }
+
+    i++;
+  }
+
+  return result;
+}
+
+function appendOrSet(current: unknown, value: unknown, spec: ArgSpec): unknown {
+  if (spec.multiple) {
+    if (Array.isArray(value)) return [...((current as unknown[]) ?? []), ...value];
+    return [...((current as unknown[]) ?? []), value];
+  }
+  return value;
+}
+
+function applyEnv(parsed: Record<string, unknown>, argSpecs: Record<string, ArgSpec>): Record<string, unknown> {
+  const result = { ...parsed };
+  for (const [name, spec] of Object.entries(argSpecs)) {
+    const norm = name.replace(/-/g, '_');
+    if ((result[norm] === null || result[norm] === undefined) && spec.env) {
+      const envVal = process.env[spec.env];
+      if (envVal !== undefined) result[norm] = envVal;
+    }
+  }
+  return result;
+}
+
+function applyDefaults(parsed: Record<string, unknown>, argSpecs: Record<string, ArgSpec>): Record<string, unknown> {
+  const result = { ...parsed };
+  for (const [name, spec] of Object.entries(argSpecs)) {
+    const norm = name.replace(/-/g, '_');
+    if ((result[norm] === null || result[norm] === undefined) && spec.default !== undefined && spec.default !== null) {
+      result[norm] = spec.default;
+    }
+  }
+  return result;
+}
+
+function coerceValues(parsed: Record<string, unknown>, argSpecs: Record<string, ArgSpec>): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  for (const [name, spec] of Object.entries(argSpecs)) {
+    const norm = name.replace(/-/g, '_');
+    const value = parsed[norm];
+    if (value === null || value === undefined) {
+      result[norm] = undefined;
+      continue;
+    }
+    try {
+      result[norm] = coerce(value, spec);
+    } catch (e) {
+      throw new RunSpecError(`✗  ${(e as Error).message}`);
+    }
+  }
+  return result;
+}
+
+export function printHelp(name: string, script: ScriptSpec, command?: string): void {
+  const fullName = command ? `${name} ${command}` : name;
+  const args = script.args ?? {};
+
+  const usageParts = [fullName];
+  for (const [argName, spec] of Object.entries(args)) {
+    const flag = `--${argName}`;
+    if (spec.type === 'flag') {
+      usageParts.push(`[${flag}]`);
+    } else if (spec.required) {
+      usageParts.push(`${flag} <${spec.type ?? 'str'}>`);
+    } else {
+      usageParts.push(`[${flag} <${spec.type ?? 'str'}>]`);
+    }
+  }
+
+  console.log(`Usage: ${usageParts.join(' ')}`);
+  if (script.description) console.log(`\n${script.description}`);
+
+  if (Object.keys(args).length > 0) {
+    console.log('\nArguments:');
+    for (const [argName, spec] of Object.entries(args)) {
+      const flag = `  --${argName}`;
+      const parts: string[] = [];
+      if (spec.type === 'flag') parts.push('flag');
+      else parts.push(spec.type ?? 'str');
+      if (spec.required) parts.push('required');
+      else if (spec.default !== undefined && spec.default !== null) parts.push(`default: ${spec.default}`);
+      if (spec.options) parts.push(`one of: ${spec.options.join(', ')}`);
+      const meta = `(${parts.join(', ')})`;
+      if (spec.description) console.log(`${flag.padEnd(24)} ${spec.description}  ${meta}`);
+      else console.log(`${flag.padEnd(24)} ${meta}`);
+    }
+  }
+
+  if (script.autonomy) {
+    console.log(`\nAutonomy: ${script.autonomy}`);
+    if (script.autonomyReason) console.log(`  ${script.autonomyReason}`);
+  }
+
+  console.log('\n  -h, --help    Show this message and exit');
+}

package/src/serve.ts

@@ -0,0 +1,196 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import * as readline from 'readline';
+import { spawnSync } from 'child_process';
+import { findConfig } from './finder';
+import { loadRaw } from './loader';
+import { inferScript } from './inference';
+import { buildSchema } from './cli';
+
+const MCP_PROTOCOL_VERSION = '2024-11-05';
+const ERR_PARSE = -32700;
+const ERR_METHOD_NOT_FOUND = -32601;
+const ERR_INVALID_PARAMS = -32602;
+
+export function serve(): void {
+  let configPath: string;
+  let format: 'pyproject' | 'runspec';
+
+  try {
+    ({ configPath, format } = findConfig(process.cwd()));
+  } catch (e) {
+    process.stderr.write(`runspec serve: ${(e as Error).message}\n`);
+    process.exit(1);
+  }
+
+  const raw = loadRaw(configPath, format);
+  const config = raw.config;
+
+  const tools: Record<string, Record<string, unknown>> = {};
+  const argSpecs: Record<string, Record<string, unknown>> = {};
+
+  for (const [name, runnable] of Object.entries(raw.runnables)) {
+    const inferred = inferScript(runnable, config.autonomyDefault);
+    tools[name] = buildSchema(name, inferred, 'mcp');
+    argSpecs[name] = inferred.args ?? {};
+  }
+
+  const serverName = serverNameFromConfig(config as unknown as Record<string, unknown>);
+  const binDir = path.join(path.dirname(configPath), 'node_modules', '.bin');
+
+  mcpLoop(tools, argSpecs, binDir, serverName);
+}
+
+function mcpLoop(
+  tools: Record<string, Record<string, unknown>>,
+  argSpecs: Record<string, Record<string, unknown>>,
+  binDir: string,
+  serverName: string,
+): void {
+  const rl = readline.createInterface({ input: process.stdin, crlfDelay: Infinity });
+
+  rl.on('line', (line) => {
+    const trimmed = line.trim();
+    if (!trimmed) return;
+
+    let request: Record<string, unknown>;
+    try {
+      request = JSON.parse(trimmed) as Record<string, unknown>;
+    } catch {
+      writeMsg({ jsonrpc: '2.0', id: null, error: { code: ERR_PARSE, message: 'Parse error' } });
+      return;
+    }
+
+    const response = dispatch(request, tools, argSpecs, binDir, serverName);
+    if (response !== null) writeMsg(response);
+  });
+}
+
+function dispatch(
+  request: Record<string, unknown>,
+  tools: Record<string, Record<string, unknown>>,
+  argSpecs: Record<string, Record<string, unknown>>,
+  binDir: string,
+  serverName: string,
+): Record<string, unknown> | null {
+  const method = (request['method'] as string) ?? '';
+  const reqId = request['id'];
+
+  if (reqId === undefined || reqId === null) return null;
+
+  if (method === 'initialize') return handleInitialize(reqId, serverName);
+  if (method === 'tools/list') return handleToolsList(reqId, tools);
+  if (method === 'tools/call') {
+    return handleToolsCall(reqId, (request['params'] ?? {}) as Record<string, unknown>, tools, argSpecs, binDir);
+  }
+
+  return { jsonrpc: '2.0', id: reqId, error: { code: ERR_METHOD_NOT_FOUND, message: `Method not found: ${method}` } };
+}
+
+function handleInitialize(reqId: unknown, serverName: string): Record<string, unknown> {
+  const version = '0.3.0';
+  return {
+    jsonrpc: '2.0',
+    id: reqId,
+    result: {
+      protocolVersion: MCP_PROTOCOL_VERSION,
+      capabilities: { tools: {} },
+      serverInfo: { name: serverName, version },
+    },
+  };
+}
+
+function handleToolsList(reqId: unknown, tools: Record<string, Record<string, unknown>>): Record<string, unknown> {
+  return { jsonrpc: '2.0', id: reqId, result: { tools: Object.values(tools) } };
+}
+
+function handleToolsCall(
+  reqId: unknown,
+  params: Record<string, unknown>,
+  tools: Record<string, Record<string, unknown>>,
+  argSpecs: Record<string, Record<string, unknown>>,
+  binDir: string,
+): Record<string, unknown> {
+  const name = (params['name'] as string) ?? '';
+  const args = (params['arguments'] as Record<string, unknown>) ?? {};
+
+  if (!(name in tools)) {
+    return { jsonrpc: '2.0', id: reqId, error: { code: ERR_INVALID_PARAMS, message: `Unknown tool: ${name}` } };
+  }
+
+  const cmd = findScript(name, binDir);
+  if (!cmd) {
+    return {
+      jsonrpc: '2.0',
+      id: reqId,
+      result: {
+        content: [{ type: 'text', text: `Script not found in ${binDir}: ${name}` }],
+        isError: true,
+      },
+    };
+  }
+
+  const argv = argsToArgv(args, argSpecs[name] ?? {});
+  const env = { ...process.env, RUNSPEC_AGENT: '1' };
+
+  const result = spawnSync(cmd, argv, { encoding: 'utf-8', env });
+
+  if (result.status === 0) {
+    return {
+      jsonrpc: '2.0',
+      id: reqId,
+      result: { content: [{ type: 'text', text: result.stdout ?? '' }], isError: false },
+    };
+  }
+
+  const parts = [`exit_code: ${result.status ?? 'unknown'}`];
+  if (result.stdout) parts.push(`stdout:\n${result.stdout.trimEnd()}`);
+  if (result.stderr) parts.push(`stderr:\n${result.stderr.trimEnd()}`);
+
+  return {
+    jsonrpc: '2.0',
+    id: reqId,
+    result: { content: [{ type: 'text', text: parts.join('\n') }], isError: true },
+  };
+}
+
+function argsToArgv(args: Record<string, unknown>, argSpecs: Record<string, unknown>): string[] {
+  const argv: string[] = [];
+
+  for (const [argName, spec] of Object.entries(argSpecs)) {
+    const s = spec as Record<string, unknown>;
+    let value = args[argName] ?? args[argName.replace(/-/g, '_')];
+    if (value === null || value === undefined) continue;
+
+    const flag = `--${argName}`;
+    const argType = (s['type'] as string) ?? 'str';
+
+    if (argType === 'flag') {
+      if (value) argv.push(flag);
+    } else if (s['multiple'] && Array.isArray(value)) {
+      for (const item of value) argv.push(flag, String(item));
+    } else {
+      argv.push(flag, String(value));
+    }
+  }
+
+  return argv;
+}
+
+function findScript(name: string, binDir: string): string | null {
+  const candidate = path.join(binDir, name);
+  if (fs.existsSync(candidate)) return candidate;
+  const candidateExe = path.join(binDir, name + '.exe');
+  if (fs.existsSync(candidateExe)) return candidateExe;
+  return null;
+}
+
+function serverNameFromConfig(config: Record<string, unknown>): string {
+  const name = config['name'];
+  if (name && typeof name === 'string') return name;
+  return path.basename(path.dirname(process.execPath));
+}
+
+function writeMsg(response: Record<string, unknown>): void {
+  process.stdout.write(JSON.stringify(response) + '\n');
+}