@nimrobo/mcporter-remote 0.1.0

package/src/cli/flag-utils.ts

@@ -0,0 +1,29 @@
+export type FlagMap = Partial<Record<string, string>>;
+
+// extractFlags snacks out targeted flags (and their values) from argv in place.
+export function extractFlags(args: string[], keys: readonly string[]): FlagMap {
+  const flags: FlagMap = {};
+  let index = 0;
+  while (index < args.length) {
+    const token = args[index];
+    if (token === undefined || !keys.includes(token)) {
+      index += 1;
+      continue;
+    }
+    const value = args[index + 1];
+    if (value === undefined) {
+      throw new Error(`Flag '${token}' requires a value.`);
+    }
+    flags[token] = value;
+    args.splice(index, 2);
+  }
+  return flags;
+}
+
+// expectValue asserts that a flag is followed by a value.
+export function expectValue(flag: string, value: string | undefined): string {
+  if (value === undefined) {
+    throw new Error(`Flag '${flag}' requires a value.`);
+  }
+  return value;
+}

package/src/cli/generate/artifacts.ts

@@ -0,0 +1,308 @@
+import { execFile } from 'node:child_process';
+import fsSync from 'node:fs';
+import fs from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import type { RolldownPlugin } from 'rolldown';
+import { markExecutable, safeCopyFile } from './fs-helpers.js';
+import { verifyBunAvailable } from './runtime.js';
+
+const localRequire = createRequire(import.meta.url);
+const packageRoot = fileURLToPath(new URL('../../..', import.meta.url));
+// Generated CLIs import commander/mcporter, but end-users run mcporter from directories
+// that often lack node_modules. Pre-resolve those deps to this package so bundling works
+// even in empty temp dirs (fixes #1).
+const BUNDLED_DEPENDENCIES = ['commander', '@nimrobo/mcporter-remote', 'jsonc-parser'] as const;
+const dependencyAliasPlugin = createLocalDependencyAliasPlugin([...BUNDLED_DEPENDENCIES]);
+
+export async function bundleOutput({
+  sourcePath,
+  targetPath,
+  runtimeKind,
+  minify,
+  bundler,
+}: {
+  sourcePath: string;
+  targetPath: string;
+  runtimeKind: 'node' | 'bun';
+  minify: boolean;
+  bundler: 'rolldown' | 'bun';
+}): Promise<string> {
+  if (bundler === 'bun') {
+    return await bundleWithBun({ sourcePath, targetPath, runtimeKind, minify });
+  }
+  return await bundleWithRolldown({ sourcePath, targetPath, runtimeKind, minify });
+}
+
+async function bundleWithRolldown({
+  sourcePath,
+  targetPath,
+  runtimeKind,
+  minify,
+}: {
+  sourcePath: string;
+  targetPath: string;
+  runtimeKind: 'node' | 'bun';
+  minify: boolean;
+}): Promise<string> {
+  let rolldownImpl: typeof import('rolldown')['rolldown'];
+  try {
+    ({ rolldown: rolldownImpl } = await import('rolldown'));
+  } catch (error) {
+    const message =
+      'Rolldown bundling is unavailable in this build of mcporter; rerun with --bundler bun or install mcporter via npm (Node.js) to use the Rolldown bundler.';
+    if (error instanceof Error) {
+      error.message = `${message}\n\n${error.message}`;
+      throw error;
+    }
+    throw new Error(message);
+  }
+  const absTarget = path.resolve(targetPath);
+  await fs.mkdir(path.dirname(absTarget), { recursive: true });
+  const plugins = dependencyAliasPlugin ? [dependencyAliasPlugin] : undefined;
+  const bundle = await rolldownImpl({
+    input: sourcePath,
+    treeshake: false,
+    plugins,
+    onLog(level, log, handler) {
+      if (typeof (log as { code?: string }).code === 'string' && (log as { code?: string }).code === 'EVAL') {
+        return;
+      }
+      handler(level, log);
+    },
+  });
+  await bundle.write({
+    file: absTarget,
+    format: runtimeKind === 'bun' ? 'esm' : 'cjs',
+    sourcemap: false,
+    minify,
+  });
+  await markExecutable(absTarget);
+  return absTarget;
+}
+
+async function bundleWithBun({
+  sourcePath,
+  targetPath,
+  runtimeKind,
+  minify,
+}: {
+  sourcePath: string;
+  targetPath: string;
+  runtimeKind: 'node' | 'bun';
+  minify: boolean;
+}): Promise<string> {
+  const absTarget = path.resolve(targetPath);
+  await fs.mkdir(path.dirname(absTarget), { recursive: true });
+  const bunBin = await verifyBunAvailable();
+  const tmpRoot = path.join(packageRoot, 'tmp');
+  await fs.mkdir(tmpRoot, { recursive: true });
+  const stagingDir = await fs.mkdtemp(path.join(tmpRoot, 'bundle-'));
+  const stagingEntry = path.join(stagingDir, path.basename(sourcePath));
+  // Copy the template into the package tree so Bun sees our node_modules deps even when the
+  // CLI runs from an empty working directory.
+  await safeCopyFile(sourcePath, stagingEntry);
+  await ensureBundlerDeps(stagingDir);
+  try {
+    const args = ['build', stagingEntry, '--outfile', absTarget, '--target', runtimeKind === 'bun' ? 'bun' : 'node'];
+    if (minify) {
+      args.push('--minify');
+    }
+    await new Promise<void>((resolve, reject) => {
+      execFile(bunBin, args, { cwd: packageRoot, env: process.env }, (error) => {
+        if (error) {
+          reject(error);
+          return;
+        }
+        resolve();
+      });
+    });
+  } finally {
+    await fs.rm(stagingDir, { recursive: true, force: true }).catch(() => {});
+  }
+  await markExecutable(absTarget);
+  return absTarget;
+}
+
+export async function compileBundleWithBun(bundlePath: string, outputPath: string): Promise<void> {
+  const bunBin = await verifyBunAvailable();
+  await new Promise<void>((resolve, reject) => {
+    execFile(
+      bunBin,
+      ['build', bundlePath, '--compile', '--outfile', outputPath],
+      { cwd: process.cwd(), env: process.env },
+      (error) => {
+        if (error) {
+          reject(error);
+          return;
+        }
+        resolve();
+      }
+    );
+  });
+
+  await markExecutable(outputPath);
+}
+
+export function resolveBundleTarget({
+  bundle,
+  compile,
+  outputPath,
+}: {
+  bundle?: boolean | string;
+  compile?: boolean | string;
+  outputPath: string;
+}): string {
+  if (typeof bundle === 'string') {
+    return bundle;
+  }
+  if (bundle) {
+    throw new Error('--bundle requires an explicit output path when used with --compile.');
+  }
+  if (typeof compile === 'string') {
+    const ext = path.extname(compile);
+    const base = ext ? path.join(path.dirname(compile), path.basename(compile, ext)) : compile;
+    return `${base}.js`;
+  }
+  if (compile) {
+    const tmpDir = path.join(process.cwd(), 'tmp', 'mcporter-cli-bundles');
+    const baseName = path.basename(outputPath, path.extname(outputPath)) || 'bundle';
+    return path.join(tmpDir, `${baseName}-${Date.now()}.bundle.js`);
+  }
+  throw new Error('--compile requires an explicit bundle target.');
+}
+
+export function computeCompileTarget(
+  compileOption: boolean | string | undefined,
+  _bundlePath: string,
+  serverName: string
+): string {
+  if (typeof compileOption === 'string') {
+    return compileOption;
+  }
+  const baseName = sanitizeFileName(serverName) || 'mcporter-cli';
+  return resolveUniquePath(process.cwd(), baseName);
+}
+
+function createLocalDependencyAliasPlugin(specifiers: string[]): RolldownPlugin | undefined {
+  const resolvedEntries = specifiers
+    .map((specifier) => ({ specifier, path: resolveLocalDependency(specifier) }))
+    .filter((entry): entry is { specifier: string; path: string } => Boolean(entry.path));
+  if (resolvedEntries.length === 0) {
+    return undefined;
+  }
+  return {
+    name: 'mcporter-local-deps',
+    resolveId(source) {
+      const match = resolvedEntries.find((entry) => entry.specifier === source);
+      if (match) {
+        return match.path;
+      }
+      return null;
+    },
+  };
+}
+
+function resolveLocalDependency(specifier: string): string | undefined {
+  try {
+    if (specifier === 'jsonc-parser') {
+      const pkgJsonPath = localRequire.resolve('jsonc-parser/package.json');
+      const pkgDir = path.dirname(pkgJsonPath);
+      try {
+        const pkg = JSON.parse(fsSync.readFileSync(pkgJsonPath, 'utf8')) as { module?: string };
+        if (pkg.module) {
+          const esmEntry = path.join(pkgDir, pkg.module);
+          if (fsSync.existsSync(esmEntry)) {
+            return esmEntry;
+          }
+        }
+      } catch {
+        // Fall back to Node's resolution below if we can't parse or locate the module entry.
+      }
+    }
+    return localRequire.resolve(specifier);
+  } catch {
+    if (specifier === '@nimrobo/mcporter-remote') {
+      // During development or unpublished builds there may not be an installed entry,
+      // so fall back to the files inside the repo that represent the published surface.
+      const fallbacks = [
+        path.join(packageRoot, 'dist', 'index.js'),
+        path.join(packageRoot, 'dist', 'index.mjs'),
+        path.join(packageRoot, 'src', 'index.ts'),
+        path.join(packageRoot, 'src', 'index.js'),
+      ];
+      for (const candidate of fallbacks) {
+        if (fsSync.existsSync(candidate)) {
+          return candidate;
+        }
+      }
+    }
+  }
+  return undefined;
+}
+
+async function ensureBundlerDeps(stagingDir: string): Promise<void> {
+  const nodeModulesDir = path.join(stagingDir, 'node_modules');
+  await fs.mkdir(nodeModulesDir, { recursive: true });
+  await Promise.all(
+    BUNDLED_DEPENDENCIES.map(async (specifier) => {
+      const sourceDir = resolveDependencyDirectory(specifier);
+      if (!sourceDir) {
+        return;
+      }
+      const target = path.join(nodeModulesDir, specifier);
+      await fs.mkdir(path.dirname(target), { recursive: true });
+      await linkOrCopyDependency(sourceDir, target);
+    })
+  );
+}
+
+function resolveDependencyDirectory(specifier: (typeof BUNDLED_DEPENDENCIES)[number]): string | undefined {
+  try {
+    if (specifier === '@nimrobo/mcporter-remote') {
+      return packageRoot;
+    }
+    const pkgPath = localRequire.resolve(path.join(specifier, 'package.json'));
+    return path.dirname(pkgPath);
+  } catch {
+    return undefined;
+  }
+}
+
+async function linkOrCopyDependency(sourceDir: string, targetDir: string): Promise<void> {
+  try {
+    await fs.symlink(sourceDir, targetDir, 'dir');
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code === 'EEXIST') {
+      return;
+    }
+    if (code === 'ENOENT') {
+      return;
+    }
+    if (code === 'EPERM' || code === 'EACCES') {
+      await fs.cp(sourceDir, targetDir, { recursive: true });
+      return;
+    }
+    throw error;
+  }
+}
+
+function sanitizeFileName(input: string): string {
+  const slug = input
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-');
+  return slug.replace(/^-+|-+$/g, '');
+}
+
+function resolveUniquePath(directory: string, baseName: string): string {
+  let attempt = path.join(directory, baseName);
+  let suffix = 1;
+  while (fsSync.existsSync(attempt)) {
+    attempt = path.join(directory, `${baseName}-${suffix}`);
+    suffix += 1;
+  }
+  return attempt;
+}

package/src/cli/generate/definition.ts

@@ -0,0 +1,325 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import type { CliArtifactMetadata } from '../../cli-metadata.js';
+import { type HttpCommand, loadServerDefinitions, type ServerDefinition, type StdioCommand } from '../../config.js';
+import type { Runtime, ServerToolInfo } from '../../runtime.js';
+import { createRuntime } from '../../runtime.js';
+import { extractHttpServerTarget, normalizeHttpUrl } from '../http-utils.js';
+
+export interface ResolvedServer {
+  definition: ServerDefinition;
+  name: string;
+}
+
+type DefinitionInput =
+  | ServerDefinition
+  | (Record<string, unknown> & {
+      name: string;
+      command?: unknown;
+      args?: unknown;
+    });
+
+export async function fileExists(filePath: string): Promise<boolean> {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function ensureInvocationDefaults(
+  invocation: CliArtifactMetadata['invocation'],
+  definition: ServerDefinition
+): CliArtifactMetadata['invocation'] {
+  const serverRef = invocation.serverRef ?? definition.name;
+  const configPath =
+    invocation.configPath ??
+    (definition.source && definition.source.kind === 'local' ? definition.source.path : undefined);
+  return {
+    ...invocation,
+    serverRef,
+    configPath,
+  };
+}
+
+export async function resolveServerDefinition(
+  serverRef: string,
+  configPath?: string,
+  rootDir?: string
+): Promise<ResolvedServer> {
+  const trimmed = serverRef.trim();
+
+  if (trimmed.startsWith('{') && trimmed.endsWith('}')) {
+    // Allow callers to inline a JSON server definition (used by tests + CLI).
+    const parsed = JSON.parse(trimmed) as ServerDefinition & { name: string };
+    if (!parsed.name) {
+      throw new Error("Inline server definition must include a 'name' field.");
+    }
+    return { definition: normalizeDefinition(parsed), name: parsed.name };
+  }
+
+  const possiblePath = path.resolve(trimmed);
+  try {
+    const buffer = await fs.readFile(possiblePath, 'utf8');
+    const parsed = JSON.parse(buffer) as {
+      mcpServers?: Record<string, unknown>;
+    };
+    if (!parsed.mcpServers || typeof parsed.mcpServers !== 'object') {
+      throw new Error(`Config file ${possiblePath} does not contain mcpServers.`);
+    }
+    const entries = Object.entries(parsed.mcpServers);
+    if (entries.length === 0) {
+      throw new Error(`Config file ${possiblePath} does not define any servers.`);
+    }
+    const first = entries[0];
+    if (!first) {
+      throw new Error(`Config file ${possiblePath} does not define any servers.`);
+    }
+    const [name, value] = first;
+    return {
+      definition: normalizeDefinition({
+        name,
+        ...(value as Record<string, unknown>),
+      }),
+      name,
+    };
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') {
+      throw error;
+    }
+  }
+
+  const definitions = await loadServerDefinitions({
+    configPath,
+    rootDir,
+  });
+  const matchByName = definitions.find((def) => def.name === trimmed);
+  if (matchByName) {
+    return { definition: matchByName, name: matchByName.name };
+  }
+
+  const httpTarget = extractHttpServerTarget(trimmed);
+  if (httpTarget) {
+    const normalizedTarget = normalizeHttpUrl(httpTarget);
+    if (normalizedTarget) {
+      const matchByUrl = definitions.find((def) => {
+        if (def.command.kind !== 'http') {
+          return false;
+        }
+        const normalizedDefinitionUrl = normalizeHttpUrl(def.command.url);
+        return normalizedDefinitionUrl === normalizedTarget;
+      });
+      if (matchByUrl) {
+        return { definition: matchByUrl, name: matchByUrl.name };
+      }
+    }
+  }
+
+  throw new Error(
+    `Unknown MCP server '${trimmed}'. Provide a name from config, a JSON file, inline JSON, or an HTTP URL that matches a configured server.`
+  );
+}
+
+export async function fetchTools(
+  definition: ServerDefinition,
+  serverName: string,
+  configPath?: string,
+  rootDir?: string
+): Promise<{ tools: ServerToolInfo[]; derivedDescription?: string }> {
+  // Reuse the runtime helper so bundle builds and CLI generation share the same discovery path.
+  const runtime = await createRuntime({
+    configPath,
+    rootDir,
+    servers: configPath ? undefined : [definition],
+  });
+  try {
+    const tools = await runtime.listTools(serverName, { includeSchema: true });
+    const derivedDescription = definition.description
+      ? undefined
+      : await deriveDefinitionDescription(runtime, serverName);
+    return { tools, derivedDescription };
+  } finally {
+    await runtime.close(serverName).catch(() => {});
+  }
+}
+
+async function deriveDefinitionDescription(runtime: Runtime, serverName: string): Promise<string | undefined> {
+  try {
+    const context = await runtime.connect(serverName);
+    const instructions =
+      typeof context.client.getInstructions === 'function' ? context.client.getInstructions() : undefined;
+    const serverInfo =
+      typeof context.client.getServerVersion === 'function' ? context.client.getServerVersion() : undefined;
+    const derived = pickDescription(instructions, serverInfo);
+    return derived;
+  } catch {
+    // Ignore metadata lookup failures; fallback description will be used instead.
+    return undefined;
+  }
+}
+
+function pickDescription(
+  instructions: unknown,
+  serverInfo: { title?: unknown; name?: unknown } | undefined
+): string | undefined {
+  const ordered = [instructions, serverInfo?.title, serverInfo?.name];
+  for (const candidate of ordered) {
+    if (typeof candidate === 'string') {
+      const trimmed = candidate.trim();
+      if (trimmed.length > 0) {
+        return trimmed;
+      }
+    }
+  }
+  return undefined;
+}
+
+export function normalizeDefinition(def: DefinitionInput): ServerDefinition {
+  if (isServerDefinition(def)) {
+    return def;
+  }
+
+  const name = def.name;
+  if (typeof name !== 'string' || name.trim().length === 0) {
+    throw new Error('Server definition must include a name.');
+  }
+
+  const description = typeof def.description === 'string' ? def.description : undefined;
+  const env = toStringRecord(def.env);
+  const auth = typeof def.auth === 'string' ? def.auth : undefined;
+  const tokenCacheDir = typeof def.tokenCacheDir === 'string' ? def.tokenCacheDir : undefined;
+  const clientName = typeof def.clientName === 'string' ? def.clientName : undefined;
+  const headers = toStringRecord((def as Record<string, unknown>).headers);
+
+  const commandValue = def.command;
+  if (isCommandSpec(commandValue)) {
+    return {
+      name,
+      description,
+      command: normalizeCommand(commandValue, headers),
+      env,
+      auth,
+      tokenCacheDir,
+      clientName,
+    };
+  }
+  if (typeof commandValue === 'string' && commandValue.trim().length > 0) {
+    return {
+      name,
+      description,
+      command: toCommandSpec(commandValue, getStringArray(def.args), headers ? { headers } : undefined),
+      env,
+      auth,
+      tokenCacheDir,
+      clientName,
+    };
+  }
+  if (Array.isArray(commandValue) && commandValue.length > 0) {
+    const [first, ...rest] = commandValue;
+    if (typeof first !== 'string' || !rest.every((entry) => typeof entry === 'string')) {
+      throw new Error('Command array must contain only strings.');
+    }
+    return {
+      name,
+      description,
+      command: toCommandSpec(first, rest as string[], headers ? { headers } : undefined),
+      env,
+      auth,
+      tokenCacheDir,
+      clientName,
+    };
+  }
+  throw new Error('Server definition must include command information.');
+}
+
+function isServerDefinition(value: unknown): value is ServerDefinition {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+  const record = value as Record<string, unknown>;
+  if (typeof record.name !== 'string') {
+    return false;
+  }
+  return isCommandSpec(record.command);
+}
+
+function isCommandSpec(value: unknown): value is ServerDefinition['command'] {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+  const candidate = value as { kind?: unknown };
+  if (candidate.kind === 'http') {
+    return 'url' in candidate;
+  }
+  if (candidate.kind === 'stdio') {
+    return 'command' in candidate;
+  }
+  return false;
+}
+
+function normalizeCommand(
+  command: ServerDefinition['command'],
+  headers?: Record<string, string>
+): ServerDefinition['command'] {
+  if (command.kind === 'http') {
+    const urlValue = command.url;
+    const url = urlValue instanceof URL ? urlValue : new URL(String(urlValue));
+    const mergedHeaders = command.headers ? (headers ? { ...command.headers, ...headers } : command.headers) : headers;
+    const normalized: HttpCommand = {
+      kind: 'http',
+      url,
+      ...(mergedHeaders ? { headers: mergedHeaders } : {}),
+    };
+    return normalized;
+  }
+  return {
+    kind: 'stdio',
+    command: command.command,
+    args: [...command.args],
+    cwd: command.cwd ?? process.cwd(),
+  };
+}
+
+function toCommandSpec(
+  command: string,
+  args?: string[],
+  extra?: { headers?: Record<string, string> }
+): ServerDefinition['command'] {
+  if (command.startsWith('http://') || command.startsWith('https://')) {
+    const httpCommand: HttpCommand = {
+      kind: 'http',
+      url: new URL(command),
+      ...(extra?.headers ? { headers: extra.headers } : {}),
+    };
+    return httpCommand;
+  }
+  const stdio: StdioCommand = {
+    kind: 'stdio',
+    command,
+    args: args ?? [],
+    cwd: process.cwd(),
+  };
+  return stdio;
+}
+
+function getStringArray(value: unknown): string[] | undefined {
+  if (!Array.isArray(value)) {
+    return undefined;
+  }
+  const entries = value.filter((item): item is string => typeof item === 'string');
+  return entries.length > 0 ? entries : undefined;
+}
+
+function toStringRecord(value: unknown): Record<string, string> | undefined {
+  if (typeof value !== 'object' || value === null) {
+    return undefined;
+  }
+  const result: Record<string, string> = {};
+  for (const [key, entry] of Object.entries(value)) {
+    if (typeof entry === 'string') {
+      result[key] = entry;
+    }
+  }
+  return Object.keys(result).length > 0 ? result : undefined;
+}

package/src/cli/generate/flag-parser.ts

@@ -0,0 +1,50 @@
+export interface GeneratorCommonFlags {
+  runtime?: 'node' | 'bun';
+  timeout?: number;
+  includeOptional?: boolean;
+}
+
+interface ExtractOptions {
+  allowIncludeOptional?: boolean;
+}
+
+export function extractGeneratorFlags(args: string[], options: ExtractOptions = {}): GeneratorCommonFlags {
+  const result: GeneratorCommonFlags = {};
+  let index = 0;
+  while (index < args.length) {
+    const token = args[index];
+    if (!token) {
+      index += 1;
+      continue;
+    }
+    if (token === '--runtime') {
+      const value = args[index + 1];
+      if (value !== 'node' && value !== 'bun') {
+        throw new Error("--runtime must be 'node' or 'bun'.");
+      }
+      result.runtime = value;
+      args.splice(index, 2);
+      continue;
+    }
+    if (token === '--timeout') {
+      const raw = args[index + 1];
+      if (!raw) {
+        throw new Error("Flag '--timeout' requires a value.");
+      }
+      const parsed = Number.parseInt(raw, 10);
+      if (!Number.isFinite(parsed) || parsed <= 0) {
+        throw new Error('--timeout must be a positive integer.');
+      }
+      result.timeout = parsed;
+      args.splice(index, 2);
+      continue;
+    }
+    if (options.allowIncludeOptional && (token === '--include-optional' || token === '--all-parameters')) {
+      result.includeOptional = true;
+      args.splice(index, 1);
+      continue;
+    }
+    index += 1;
+  }
+  return result;
+}