@nimrobo/mcporter-remote 0.1.0

package/src/cli/emit-ts-command.ts

@@ -0,0 +1,260 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import type { ServerDefinition } from '../config.js';
+import type { Runtime } from '../runtime.js';
+import { type EmitMetadata, renderClientModule, renderTypesModule, type ToolDocEntry } from './emit-ts-templates.js';
+import { extractGeneratorFlags } from './generate/flag-parser.js';
+import { readPackageMetadata } from './generate/template.js';
+import type { ToolMetadata } from './generate/tools.js';
+import { extractHttpServerTarget } from './http-utils.js';
+import { buildToolDoc } from './list-detail-helpers.js';
+import { consumeOutputFormat } from './output-format.js';
+import { findServerByHttpUrl } from './server-lookup.js';
+import { loadToolMetadata } from './tool-cache.js';
+
+interface EmitTsFlags {
+  server?: string;
+  outPath?: string;
+  mode: 'types' | 'client';
+  includeOptional: boolean;
+  typesOutPath?: string;
+  format: 'text' | 'json';
+}
+
+interface ParsedEmitTsOptions extends Required<Omit<EmitTsFlags, 'server' | 'outPath' | 'typesOutPath'>> {
+  server: string;
+  outPath: string;
+  typesOutPath?: string;
+}
+
+export async function handleEmitTs(runtime: Runtime, args: string[]): Promise<void> {
+  const options = parseEmitTsArgs(args);
+  const definition = getServerDefinition(runtime, options.server);
+  const metadataEntries = await loadToolMetadata(runtime, options.server, {
+    includeSchema: true,
+    autoAuthorize: false,
+  });
+  const generator = await readPackageMetadata();
+  const metadata: EmitMetadata = {
+    server: definition,
+    generatorLabel: `${generator.name}@${generator.version}`,
+    generatedAt: new Date(),
+  };
+  const docEntries = buildDocEntries(options.server, metadataEntries, options.includeOptional);
+  const interfaceName = buildInterfaceName(options.server);
+
+  if (options.mode === 'types') {
+    const source = renderTypesModule({ interfaceName, docs: docEntries, metadata });
+    await writeFile(options.outPath, source);
+    if (options.format === 'json') {
+      console.log(
+        JSON.stringify(
+          {
+            mode: 'types',
+            server: options.server,
+            outPath: options.outPath,
+          },
+          null,
+          2
+        )
+      );
+    } else {
+      console.log(`Emitted TypeScript definitions for ${options.server} → ${options.outPath}`);
+    }
+    return;
+  }
+
+  const typesOutPath = options.typesOutPath ?? deriveTypesOutPath(options.outPath);
+  const relativeImportPath = computeImportPath(options.outPath, typesOutPath);
+  const typesSource = renderTypesModule({ interfaceName, docs: docEntries, metadata });
+  const clientSource = renderClientModule({
+    interfaceName,
+    docs: docEntries,
+    metadata,
+    typesImportPath: relativeImportPath,
+  });
+  await writeFile(typesOutPath, typesSource);
+  await writeFile(options.outPath, clientSource);
+  if (options.format === 'json') {
+    console.log(
+      JSON.stringify(
+        {
+          mode: 'client',
+          server: options.server,
+          clientOutPath: options.outPath,
+          typesOutPath,
+        },
+        null,
+        2
+      )
+    );
+  } else {
+    console.log(`Emitted client + types for ${options.server} → ${options.outPath} / ${typesOutPath}`);
+  }
+}
+
+function parseEmitTsArgs(args: string[]): ParsedEmitTsOptions {
+  const flags: EmitTsFlags = {
+    mode: 'types',
+    includeOptional: false,
+    format: 'text',
+  };
+  const common = extractGeneratorFlags(args, { allowIncludeOptional: true });
+  if (common.includeOptional) {
+    flags.includeOptional = true;
+  }
+  flags.format = consumeOutputFormat(args, {
+    defaultFormat: 'text',
+    allowed: ['text', 'json'],
+    enableRawShortcut: false,
+    jsonShortcutFlag: '--json',
+  }) as EmitTsFlags['format'];
+  let index = 0;
+  while (index < args.length) {
+    const token = args[index];
+    if (!token) {
+      index += 1;
+      continue;
+    }
+    if (token === '--out') {
+      const value = args[index + 1];
+      if (!value) {
+        throw new Error("Flag '--out' requires a path.");
+      }
+      flags.outPath = value;
+      args.splice(index, 2);
+      continue;
+    }
+    if (token === '--types-out') {
+      const value = args[index + 1];
+      if (!value) {
+        throw new Error("Flag '--types-out' requires a path.");
+      }
+      flags.typesOutPath = value;
+      args.splice(index, 2);
+      continue;
+    }
+    if (token === '--mode') {
+      const value = args[index + 1];
+      if (value !== 'types' && value !== 'client') {
+        throw new Error("--mode must be 'types' or 'client'.");
+      }
+      flags.mode = value;
+      args.splice(index, 2);
+      continue;
+    }
+    if (token.startsWith('--')) {
+      throw new Error(`Unknown flag '${token}' for emit-ts.`);
+    }
+    index += 1;
+  }
+
+  const server = args.shift();
+  if (!server) {
+    throw new Error('Usage: mcporter emit-ts <server> --out <file> [--mode types|client]');
+  }
+  const outPath = flags.outPath;
+  if (!outPath) {
+    throw new Error("Flag '--out' is required for emit-ts.");
+  }
+  if (flags.mode === 'client' && !outPath.endsWith('.ts')) {
+    throw new Error('--out should point to a .ts file when --mode client is used.');
+  }
+  if (flags.mode === 'types' && !outPath.endsWith('.ts') && !outPath.endsWith('.d.ts')) {
+    throw new Error('--out should be a .ts or .d.ts file for --mode types.');
+  }
+  return {
+    server,
+    outPath: path.resolve(outPath),
+    mode: flags.mode,
+    includeOptional: flags.includeOptional,
+    typesOutPath: flags.typesOutPath ? path.resolve(flags.typesOutPath) : undefined,
+    format: flags.format,
+  };
+}
+
+function getServerDefinition(runtime: Runtime, selector: string): ServerDefinition {
+  try {
+    return runtime.getDefinition(selector);
+  } catch (error) {
+    const resolved = resolveHttpServerName(runtime, selector);
+    if (resolved) {
+      return runtime.getDefinition(resolved);
+    }
+    if (error instanceof Error) {
+      throw new Error(error.message);
+    }
+    throw error;
+  }
+}
+
+function resolveHttpServerName(runtime: Runtime, selector: string): string | undefined {
+  const target = extractHttpServerTarget(selector);
+  if (!target) {
+    return undefined;
+  }
+  return findServerByHttpUrl(runtime.getDefinitions(), target);
+}
+
+function buildDocEntries(
+  serverName: string,
+  metadataEntries: ToolMetadata[],
+  includeOptional: boolean
+): ToolDocEntry[] {
+  return metadataEntries.map((entry) => {
+    const doc = buildToolDoc({
+      serverName,
+      toolName: entry.tool.name,
+      description: entry.tool.description,
+      outputSchema: entry.tool.outputSchema,
+      options: entry.options,
+      requiredOnly: !includeOptional,
+      colorize: false,
+      defaultReturnType: 'CallResult',
+    });
+    return {
+      toolName: entry.tool.name,
+      methodName: entry.methodName,
+      doc,
+    };
+  });
+}
+
+function buildInterfaceName(serverName: string): string {
+  const cleaned = serverName
+    .split(/[^A-Za-z0-9]+/)
+    .filter(Boolean)
+    .map((segment) => segment.charAt(0).toUpperCase() + segment.slice(1))
+    .join('');
+  const base = cleaned.length > 0 ? cleaned : 'Server';
+  return `${base}Tools`;
+}
+
+function deriveTypesOutPath(tsPath: string): string {
+  const dir = path.dirname(tsPath);
+  const base = path.basename(tsPath, path.extname(tsPath));
+  return path.join(dir, `${base}.d.ts`);
+}
+
+async function writeFile(targetPath: string, contents: string): Promise<void> {
+  await fs.mkdir(path.dirname(targetPath), { recursive: true });
+  await fs.writeFile(targetPath, `${contents}\n`, 'utf8');
+}
+
+function computeImportPath(fromPath: string, typesPath: string): string {
+  const fromDir = path.dirname(fromPath);
+  const relative = path.relative(fromDir, typesPath).replace(/\\/g, '/');
+  const withoutExt = relative.replace(/\.[^.]+$/, '');
+  if (withoutExt.startsWith('.')) {
+    return withoutExt;
+  }
+  return `./${withoutExt}`;
+}
+
+export const __test = {
+  parseEmitTsArgs,
+  buildInterfaceName,
+  deriveTypesOutPath,
+  computeImportPath,
+  buildDocEntries,
+};

package/src/cli/emit-ts-templates.ts

@@ -0,0 +1,161 @@
+import path from 'node:path';
+import type { ServerDefinition } from '../config.js';
+import type { ToolDocModel } from './list-detail-helpers.js';
+
+export interface ToolDocEntry {
+  toolName: string;
+  methodName: string;
+  doc: ToolDocModel;
+}
+
+export interface EmitMetadata {
+  server: ServerDefinition;
+  generatorLabel: string;
+  generatedAt: Date;
+}
+
+export interface EmitTypesTemplateInput {
+  interfaceName: string;
+  docs: ToolDocEntry[];
+  metadata: EmitMetadata;
+}
+
+export interface EmitClientTemplateInput extends EmitTypesTemplateInput {
+  typesImportPath: string;
+}
+
+export function renderTypesModule(input: EmitTypesTemplateInput): string {
+  const lines: string[] = [];
+  lines.push(...renderHeader(input.metadata));
+  lines.push("import type { CallResult } from '@nimrobo/mcporter-remote';");
+  lines.push('');
+  lines.push(`export interface ${input.interfaceName} {`);
+  input.docs.forEach((entry, index) => {
+    lines.push(...renderDocComment(entry.doc.docLines, '  '));
+    const methodSignature = toInterfaceSignature(entry.doc.tsSignature, { wrapInPromise: true });
+    lines.push(`  ${methodSignature}`);
+    if (entry.doc.optionalSummary) {
+      lines.push(`  // ${entry.doc.optionalSummary.replace(/^\/\//, '').trim()}`);
+    }
+    if (index !== input.docs.length - 1) {
+      lines.push('');
+    }
+  });
+  if (input.docs.length === 0) {
+    lines.push('  // No tools reported for this server.');
+  }
+  lines.push('}');
+  lines.push('');
+  return lines.join('\n');
+}
+
+export function renderClientModule(input: EmitClientTemplateInput): string {
+  const lines: string[] = [];
+  lines.push(...renderHeader(input.metadata));
+  lines.push("import { createRuntime, createServerProxy, wrapCallResult } from '@nimrobo/mcporter-remote';");
+  lines.push(`import type { ${input.interfaceName} } from '${input.typesImportPath}';`);
+  lines.push('');
+  lines.push('type RuntimeInstance = Awaited<ReturnType<typeof createRuntime>>;');
+  const clientType = `${input.interfaceName.replace(/Tools$/, 'Client')}`;
+  const factoryName = `create${input.interfaceName.replace(/Tools$/, '')}Client`;
+  const serverName = input.metadata.server.name;
+  lines.push(`export type ${clientType} = ${input.interfaceName} & { close(): Promise<void> };`);
+  lines.push('');
+  lines.push('export interface CreateClientOptions {');
+  lines.push('  runtime?: RuntimeInstance;');
+  lines.push('  configPath?: string;');
+  lines.push('  rootDir?: string;');
+  lines.push('}');
+  lines.push('');
+  lines.push(`export async function ${factoryName}(options: CreateClientOptions = {}): Promise<${clientType}> {`);
+  lines.push('  const runtime = options.runtime ?? (await createRuntime({');
+  lines.push('    configPath: options.configPath,');
+  lines.push('    rootDir: options.rootDir,');
+  lines.push('  }));');
+  lines.push('  const ownsRuntime = !options.runtime;');
+  lines.push(`  const proxy = createServerProxy(runtime, ${JSON.stringify(serverName)});`);
+  lines.push(`  const client: ${clientType} = {`);
+  input.docs.forEach((entry, _index) => {
+    const methodName = entry.doc.tsSignature.match(/^function\s+([^()]+)/)?.[1] ?? entry.toolName;
+    lines.push(`    async ${methodName}(params: Parameters<${input.interfaceName}['${methodName}']>[0]) {`);
+    lines.push(
+      `      const tool = proxy.${entry.methodName} as (args: Parameters<${input.interfaceName}['${methodName}']>[0]) => Promise<unknown>;`
+    );
+    lines.push('      const raw = await tool(params);');
+    lines.push('      return wrapCallResult(raw).callResult;');
+    lines.push('    },');
+    lines.push('');
+  });
+  lines.push('    async close() {');
+  lines.push('      if (ownsRuntime) {');
+  lines.push(`        await runtime.close(${JSON.stringify(serverName)}).catch(() => {});`);
+  lines.push('      }');
+  lines.push('    },');
+  lines.push('  };');
+  lines.push('  return client;');
+  lines.push('}');
+  lines.push('');
+  return lines.join('\n');
+}
+
+function renderHeader(metadata: EmitMetadata): string[] {
+  const lines: string[] = [];
+  const timestamp = metadata.generatedAt.toISOString();
+  lines.push(`// Generated on ${timestamp} by ${metadata.generatorLabel}`);
+  if (metadata.server.description) {
+    lines.push(`// Server: ${metadata.server.name} — ${metadata.server.description}`);
+  } else {
+    lines.push(`// Server: ${metadata.server.name}`);
+  }
+  const source = describeSource(metadata.server);
+  if (source) {
+    lines.push(`// Source: ${source}`);
+  }
+  const transport = describeTransport(metadata.server);
+  if (transport) {
+    lines.push(`// Transport: ${transport}`);
+  }
+  lines.push('');
+  return lines;
+}
+
+function renderDocComment(docLines: string[] | undefined, indent: string): string[] {
+  if (!docLines || docLines.length === 0) {
+    return [];
+  }
+  return docLines.map((line) => `${indent}${line}`);
+}
+
+function toInterfaceSignature(signature: string, options?: { wrapInPromise?: boolean }): string {
+  const trimmed = signature.trim();
+  const match = trimmed.match(/^function\s+([^(]+)\((.*)\)\s*(?::\s*([^;]+))?;?$/);
+  if (!match) {
+    return trimmed.replace(/^function\s+/, '');
+  }
+  const [, name, params, returnTypeRaw] = match;
+  const returnType = (returnTypeRaw ?? 'void').trim();
+  const finalReturn = options?.wrapInPromise ? `Promise<${returnType}>` : returnType;
+  return `${name}(${params}): ${finalReturn};`;
+}
+
+function describeTransport(definition: ServerDefinition): string | undefined {
+  if (definition.command.kind === 'http') {
+    const url = definition.command.url instanceof URL ? definition.command.url.href : String(definition.command.url);
+    return `HTTP ${url}`;
+  }
+  if (definition.command.kind === 'stdio') {
+    const cmd = [definition.command.command, ...(definition.command.args ?? [])].join(' ').trim();
+    return cmd.length > 0 ? `STDIO ${cmd}` : 'STDIO';
+  }
+  return undefined;
+}
+
+function describeSource(definition: ServerDefinition): string | undefined {
+  if (definition.source?.kind === 'import') {
+    return path.normalize(definition.source.path);
+  }
+  if (definition.source?.kind === 'local') {
+    return definition.source.path;
+  }
+  return undefined;
+}

package/src/cli/ephemeral-flags.ts

@@ -0,0 +1,128 @@
+import type { EphemeralServerSpec } from './adhoc-server.js';
+
+interface ExtractOptions {
+  allowPersist?: boolean;
+}
+
+// extractEphemeralServerFlags scans argv for ad-hoc server descriptors (HTTP/STDIO/env/etc.)
+// and removes them so higher-level parsers can focus on command-specific flags.
+export function extractEphemeralServerFlags(
+  args: string[],
+  options: ExtractOptions = {}
+): EphemeralServerSpec | undefined {
+  let spec: EphemeralServerSpec | undefined;
+  const ensureSpec = (): EphemeralServerSpec => {
+    if (!spec) {
+      spec = {};
+    }
+    return spec;
+  };
+
+  const allowPersist = options.allowPersist ?? true;
+  let index = 0;
+  while (index < args.length) {
+    const token = args[index];
+    if (!token) {
+      index += 1;
+      continue;
+    }
+
+    if (token === '--http-url' || token === '--sse') {
+      const value = args[index + 1];
+      if (!value) {
+        throw new Error("Flag '--http-url' requires a value.");
+      }
+      ensureSpec().httpUrl = value;
+      args.splice(index, 2);
+      continue;
+    }
+
+    if (token === '--allow-http' || token === '--insecure') {
+      ensureSpec().allowInsecureHttp = true;
+      args.splice(index, 1);
+      continue;
+    }
+
+    if (token === '--stdio') {
+      const value = args[index + 1];
+      if (!value) {
+        throw new Error("Flag '--stdio' requires a value.");
+      }
+      ensureSpec().stdioCommand = value;
+      args.splice(index, 2);
+      continue;
+    }
+
+    if (token === '--stdio-arg') {
+      const value = args[index + 1];
+      if (!value) {
+        throw new Error("Flag '--stdio-arg' requires a value.");
+      }
+      const current = ensureSpec();
+      current.stdioArgs = [...(current.stdioArgs ?? []), value];
+      args.splice(index, 2);
+      continue;
+    }
+
+    if (token === '--env') {
+      const value = args[index + 1];
+      if (!value || !value.includes('=')) {
+        throw new Error("Flag '--env' requires KEY=value.");
+      }
+      const [key, ...rest] = value.split('=');
+      if (!key) {
+        throw new Error("Flag '--env' requires KEY=value.");
+      }
+      const current = ensureSpec();
+      const envMap = current.env ? { ...current.env } : {};
+      envMap[key] = rest.join('=');
+      current.env = envMap;
+      args.splice(index, 2);
+      continue;
+    }
+
+    if (token === '--cwd') {
+      const value = args[index + 1];
+      if (!value) {
+        throw new Error("Flag '--cwd' requires a value.");
+      }
+      ensureSpec().cwd = value;
+      args.splice(index, 2);
+      continue;
+    }
+
+    if (token === '--name') {
+      const value = args[index + 1];
+      if (!value) {
+        throw new Error("Flag '--name' requires a value.");
+      }
+      ensureSpec().name = value;
+      args.splice(index, 2);
+      continue;
+    }
+
+    if (token === '--description') {
+      const value = args[index + 1];
+      if (!value) {
+        throw new Error("Flag '--description' requires a value.");
+      }
+      ensureSpec().description = value;
+      args.splice(index, 2);
+      continue;
+    }
+
+    if (allowPersist && token === '--persist') {
+      const value = args[index + 1];
+      if (!value) {
+        throw new Error("Flag '--persist' requires a value.");
+      }
+      ensureSpec().persistPath = value;
+      args.splice(index, 2);
+      continue;
+    }
+
+    index += 1;
+  }
+
+  return spec;
+}

package/src/cli/ephemeral-target.ts

@@ -0,0 +1,134 @@
+import type { Runtime } from '../runtime.js';
+import {
+  type EphemeralServerResolution,
+  type EphemeralServerSpec,
+  persistEphemeralServer,
+  resolveEphemeralServer,
+  splitCommandLine,
+} from './adhoc-server.js';
+import { looksLikeHttpUrl, normalizeHttpUrlCandidate } from './http-utils.js';
+import { findServerByHttpUrl } from './server-lookup.js';
+
+interface PrepareEphemeralServerTargetOptions {
+  runtime: Runtime;
+  target?: string;
+  ephemeral?: EphemeralServerSpec;
+  nameHints?: string[];
+  reuseFromSpec?: boolean;
+}
+
+interface PrepareEphemeralServerTargetResult {
+  target?: string;
+  resolution?: EphemeralServerResolution;
+}
+
+export async function prepareEphemeralServerTarget(
+  options: PrepareEphemeralServerTargetOptions
+): Promise<PrepareEphemeralServerTargetResult> {
+  let target = options.target;
+  let spec = options.ephemeral ? { ...options.ephemeral } : undefined;
+
+  const promoteUrlCandidate = (value: string | undefined): string | undefined => {
+    if (!value) {
+      return value;
+    }
+    const normalized = normalizeHttpUrlCandidate(value);
+    if (!normalized) {
+      return value;
+    }
+    const reused = findServerByHttpUrl(options.runtime.getDefinitions(), normalized);
+    if (reused) {
+      return reused;
+    }
+    if (!spec) {
+      spec = { httpUrl: normalized };
+    } else if (!spec.httpUrl) {
+      spec = { ...spec, httpUrl: normalized };
+    }
+    return undefined;
+  };
+
+  target = promoteUrlCandidate(target);
+
+  if (!spec) {
+    const inferredInline = inferInlineStdioSpec(target);
+    if (inferredInline) {
+      spec = inferredInline;
+      target = undefined;
+    }
+  }
+
+  if (spec) {
+    applyNameHints(spec, options.nameHints);
+  }
+
+  if (!spec) {
+    return { target };
+  }
+
+  if (spec.httpUrl) {
+    const normalized = normalizeHttpUrlCandidate(spec.httpUrl);
+    if (normalized) {
+      spec = { ...spec, httpUrl: normalized };
+      if (options.reuseFromSpec) {
+        const reused = findServerByHttpUrl(options.runtime.getDefinitions(), normalized);
+        if (reused) {
+          return { target: reused };
+        }
+      }
+    }
+  }
+
+  const resolution = resolveEphemeralServer(spec);
+  options.runtime.registerDefinition(resolution.definition, { overwrite: true });
+  if (spec.persistPath) {
+    await persistEphemeralServer(resolution, spec.persistPath);
+  }
+  const resolvedTarget = target ?? resolution.name;
+  return { target: resolvedTarget, resolution };
+}
+
+function applyNameHints(spec: EphemeralServerSpec | undefined, hints: string[] | undefined): void {
+  if (!spec || spec.name || !hints) {
+    return;
+  }
+  for (const hint of hints) {
+    if (!hint) {
+      continue;
+    }
+    if (looksLikeHttpUrl(hint)) {
+      continue;
+    }
+    spec.name = hint;
+    break;
+  }
+}
+
+function inferInlineStdioSpec(target: string | undefined): EphemeralServerSpec | undefined {
+  if (!target) {
+    return undefined;
+  }
+  const trimmed = target.trim();
+  if (!trimmed) {
+    return undefined;
+  }
+  if (looksLikeHttpUrl(trimmed)) {
+    return undefined;
+  }
+  if (!trimmed.includes(' ')) {
+    return undefined;
+  }
+  try {
+    const parts = splitCommandLine(trimmed);
+    if (parts.length < 2) {
+      return undefined;
+    }
+    const executable = parts[0]?.split(/[\\/]/).pop();
+    if (executable !== 'npx') {
+      return undefined;
+    }
+    return { stdioCommand: trimmed };
+  } catch {
+    return undefined;
+  }
+}

package/src/cli/errors.ts

@@ -0,0 +1,6 @@
+export class CliUsageError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'CliUsageError';
+  }
+}