@nimrobo/mcporter-remote 0.1.0

package/src/cli/timeouts.ts

@@ -0,0 +1,67 @@
+const DEFAULT_LIST_TIMEOUT_MS = 30_000;
+const DEFAULT_CALL_TIMEOUT_MS = 60_000;
+
+// parseTimeout reads timeout values from strings while honoring defaults.
+export function parseTimeout(raw: string | undefined, fallback: number): number {
+  if (!raw) {
+    return fallback;
+  }
+  const parsed = Number.parseInt(raw, 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    return fallback;
+  }
+  return parsed;
+}
+
+export const LIST_TIMEOUT_MS = parseTimeout(process.env.MCPORTER_LIST_TIMEOUT, DEFAULT_LIST_TIMEOUT_MS);
+
+// resolveCallTimeout decides the call timeout based on environment overrides.
+export function resolveCallTimeout(override?: number): number {
+  if (typeof override === 'number' && Number.isFinite(override) && override > 0) {
+    return override;
+  }
+  return parseTimeout(process.env.MCPORTER_CALL_TIMEOUT, DEFAULT_CALL_TIMEOUT_MS);
+}
+
+// withTimeout races a promise against a timeout to avoid hangs.
+export function withTimeout<T>(promise: Promise<T>, timeoutMs: number): Promise<T> {
+  // Race the original promise with a timeout to keep CLI responsive.
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+    return promise;
+  }
+  return new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      reject(new Error('Timeout'));
+    }, timeoutMs);
+
+    promise.then(
+      (value) => {
+        clearTimeout(timer);
+        resolve(value);
+      },
+      (error) => {
+        clearTimeout(timer);
+        reject(error);
+      }
+    );
+  });
+}
+
+export function consumeTimeoutFlag(
+  args: string[],
+  index: number,
+  options?: { flagName?: string; missingValueMessage?: string }
+): number {
+  const flagName = options?.flagName ?? '--timeout';
+  const missingValueMessage = options?.missingValueMessage ?? `Flag '${flagName}' requires a value.`;
+  const value = args[index + 1];
+  if (!value) {
+    throw new Error(missingValueMessage);
+  }
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    throw new Error(`${flagName} must be a positive integer (milliseconds).`);
+  }
+  args.splice(index, 2);
+  return parsed;
+}

package/src/cli/tool-cache.ts

@@ -0,0 +1,43 @@
+import type { Runtime } from '../runtime.js';
+import { buildToolMetadata, type ToolMetadata } from './generate/tools.js';
+
+interface LoadToolMetadataOptions {
+  includeSchema?: boolean;
+  autoAuthorize?: boolean;
+}
+
+const runtimeCache = new WeakMap<Runtime, Map<string, Promise<ToolMetadata[]>>>();
+
+function cacheKey(serverName: string, options: LoadToolMetadataOptions): string {
+  const includeSchema = options.includeSchema !== false;
+  const autoAuthorize = options.autoAuthorize !== false;
+  return `${serverName}::schema:${includeSchema ? '1' : '0'}::auth:${autoAuthorize ? '1' : '0'}`;
+}
+
+export async function loadToolMetadata(
+  runtime: Runtime,
+  serverName: string,
+  options: LoadToolMetadataOptions = {}
+): Promise<ToolMetadata[]> {
+  const key = cacheKey(serverName, options);
+  let cache = runtimeCache.get(runtime);
+  if (!cache) {
+    cache = new Map();
+    runtimeCache.set(runtime, cache);
+  }
+  const existing = cache.get(key);
+  if (existing) {
+    return existing;
+  }
+  const includeSchema = options.includeSchema !== false;
+  const autoAuthorize = options.autoAuthorize !== false;
+  const promise = runtime
+    .listTools(serverName, { includeSchema, autoAuthorize })
+    .then((tools) => tools.map((tool) => buildToolMetadata(tool)))
+    .catch((error) => {
+      cache?.delete(key);
+      throw error;
+    });
+  cache.set(key, promise);
+  return promise;
+}

package/src/cli/transport-utils.ts

@@ -0,0 +1,10 @@
+import type { ServerDefinition } from '../config.js';
+
+export function formatTransportSummary(definition: ServerDefinition): string {
+  if (definition.command.kind === 'http') {
+    const url = definition.command.url instanceof URL ? definition.command.url.href : String(definition.command.url);
+    return `HTTP ${url}`;
+  }
+  const rendered = [definition.command.command, ...(definition.command.args ?? [])].join(' ').trim();
+  return `STDIO ${rendered}`;
+}

package/src/cli-metadata.ts

@@ -0,0 +1,164 @@
+import { spawn } from 'node:child_process';
+import fs from 'node:fs/promises';
+import type { ServerDefinition, ServerSource } from './config.js';
+
+export type CliArtifactKind = 'template' | 'bundle' | 'binary';
+
+export interface SerializedServerDefinition {
+  readonly name: string;
+  readonly description?: string;
+  readonly command:
+    | {
+        kind: 'http';
+        url: string;
+        headers?: Record<string, string>;
+      }
+    | {
+        kind: 'stdio';
+        command: string;
+        args: string[];
+        cwd: string;
+      };
+  readonly env?: Record<string, string>;
+  readonly auth?: string;
+  readonly tokenCacheDir?: string;
+  readonly clientName?: string;
+  readonly oauthRedirectUrl?: string;
+  readonly oauthScope?: string;
+}
+
+export interface CliArtifactMetadata {
+  readonly schemaVersion: 1;
+  readonly generatedAt: string;
+  readonly generator: {
+    readonly name: string;
+    readonly version: string;
+  };
+  readonly server: {
+    readonly name: string;
+    readonly source?: ServerSource;
+    readonly definition: SerializedServerDefinition;
+  };
+  readonly artifact: {
+    readonly path: string;
+    readonly kind: CliArtifactKind;
+  };
+  readonly invocation: {
+    serverRef?: string;
+    configPath?: string;
+    rootDir?: string;
+    runtime: 'node' | 'bun';
+    bundler?: 'rolldown' | 'bun';
+    outputPath?: string;
+    bundle?: boolean | string;
+    compile?: boolean | string;
+    timeoutMs: number;
+    minify: boolean;
+    includeTools?: string[];
+    excludeTools?: string[];
+  };
+}
+
+// metadataPathForArtifact derives the metadata file path for a given artifact output path.
+export function metadataPathForArtifact(artifactPath: string): string {
+  return `${artifactPath}.metadata.json`;
+}
+
+// readCliMetadata loads metadata for a generated CLI artifact, preferring the embedded
+// inspect command and falling back to legacy sidecar files.
+export async function readCliMetadata(artifactPath: string): Promise<CliArtifactMetadata> {
+  const legacyPath = metadataPathForArtifact(artifactPath);
+  try {
+    const buffer = await fs.readFile(legacyPath, 'utf8');
+    return JSON.parse(buffer) as CliArtifactMetadata;
+  } catch (error) {
+    if (!isErrno(error, 'ENOENT')) {
+      throw error;
+    }
+  }
+  return await readMetadataFromCli(artifactPath);
+}
+
+async function readMetadataFromCli(artifactPath: string): Promise<CliArtifactMetadata> {
+  return await new Promise<CliArtifactMetadata>((resolve, reject) => {
+    const child = spawn(artifactPath, ['__mcporter_inspect'], {
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.setEncoding('utf8');
+    child.stdout.on('data', (data) => {
+      stdout += String(data);
+    });
+    child.stderr.setEncoding('utf8');
+    child.stderr.on('data', (data) => {
+      stderr += String(data);
+    });
+    child.on('error', (error) => reject(error));
+    child.on('close', (code) => {
+      if (code !== 0) {
+        reject(
+          new Error(
+            `Failed to inspect CLI artifact at ${artifactPath}${
+              stderr ? `: ${stderr.trim()}` : ''
+            } (exit code ${code ?? -1})`
+          )
+        );
+        return;
+      }
+      try {
+        const parsed = JSON.parse(stdout) as CliArtifactMetadata;
+        resolve(parsed);
+      } catch (error) {
+        reject(
+          new Error(
+            `Unable to parse embedded metadata from ${artifactPath}: ${
+              error instanceof Error ? error.message : String(error)
+            }`
+          )
+        );
+      }
+    });
+  });
+}
+
+function isErrno(error: unknown, code: string): error is NodeJS.ErrnoException {
+  return Boolean(error && typeof error === 'object' && (error as NodeJS.ErrnoException).code === code);
+}
+
+// serializeDefinition converts an in-memory server definition into the metadata-friendly JSON form.
+export function serializeDefinition(definition: ServerDefinition): SerializedServerDefinition {
+  if (definition.command.kind === 'http') {
+    return {
+      name: definition.name,
+      description: definition.description,
+      command: {
+        kind: 'http',
+        url: definition.command.url.toString(),
+        headers: definition.command.headers,
+      },
+      env: definition.env,
+      auth: definition.auth,
+      tokenCacheDir: definition.tokenCacheDir,
+      clientName: definition.clientName,
+      oauthRedirectUrl: definition.oauthRedirectUrl,
+      oauthScope: definition.oauthScope,
+    };
+  }
+  return {
+    name: definition.name,
+    description: definition.description,
+    command: {
+      kind: 'stdio',
+      command: definition.command.command,
+      args: [...definition.command.args],
+      cwd: definition.command.cwd,
+    },
+    env: definition.env,
+    auth: definition.auth,
+    tokenCacheDir: definition.tokenCacheDir,
+    clientName: definition.clientName,
+    oauthRedirectUrl: definition.oauthRedirectUrl,
+    oauthScope: definition.oauthScope,
+  };
+}

package/src/cli.ts

@@ -0,0 +1,234 @@
+#!/usr/bin/env node
+import { handleAuth, printAuthHelp } from './cli/auth-command.js';
+import { printCallHelp, handleCall as runHandleCall } from './cli/call-command.js';
+import { buildGlobalContext } from './cli/cli-factory.js';
+import { inferCommandRouting } from './cli/command-inference.js';
+import { handleConfigCli } from './cli/config-command.js';
+import { handleDaemonCli } from './cli/daemon-command.js';
+import { handleEmitTs } from './cli/emit-ts-command.js';
+import { CliUsageError } from './cli/errors.js';
+import { handleGenerateCli } from './cli/generate-cli-runner.js';
+import { consumeHelpTokens, isHelpToken, isVersionToken, printHelp, printVersion } from './cli/help-output.js';
+import { handleInspectCli } from './cli/inspect-cli-command.js';
+import { handleList, printListHelp } from './cli/list-command.js';
+import { logError, logInfo } from './cli/logger-context.js';
+import { DEBUG_HANG, dumpActiveHandles, terminateChildProcesses } from './cli/runtime-debug.js';
+import { resolveConfigPath } from './config.js';
+import { DaemonClient } from './daemon/client.js';
+import { createKeepAliveRuntime } from './daemon/runtime-wrapper.js';
+import { isKeepAliveServer } from './lifecycle.js';
+import { createRuntime } from './runtime.js';
+
+export { handleAuth, printAuthHelp } from './cli/auth-command.js';
+export { parseCallArguments } from './cli/call-arguments.js';
+export { handleCall } from './cli/call-command.js';
+export { handleGenerateCli } from './cli/generate-cli-runner.js';
+export { handleInspectCli } from './cli/inspect-cli-command.js';
+export { extractListFlags, handleList } from './cli/list-command.js';
+export { resolveCallTimeout } from './cli/timeouts.js';
+
+export async function runCli(argv: string[]): Promise<void> {
+  const args = [...argv];
+  if (args.length === 0) {
+    printHelp();
+    process.exit(1);
+    return;
+  }
+
+  const context = buildGlobalContext(args);
+  if ('exit' in context) {
+    process.exit(context.code);
+    return;
+  }
+  const { globalFlags, runtimeOptions } = context;
+  const command = args.shift();
+
+  if (!command) {
+    printHelp();
+    process.exit(1);
+    return;
+  }
+
+  if (isHelpToken(command)) {
+    printHelp();
+    process.exitCode = 0;
+    return;
+  }
+
+  if (isVersionToken(command)) {
+    await printVersion();
+    return;
+  }
+
+  // Early-exit command handlers that don't require runtime inference.
+  if (command === 'generate-cli') {
+    await handleGenerateCli(args, globalFlags);
+    return;
+  }
+  if (command === 'inspect-cli') {
+    await handleInspectCli(args);
+    return;
+  }
+  const rootOverride = globalFlags['--root'];
+  const configPath = runtimeOptions.configPath ?? globalFlags['--config'];
+  const configResolution = resolveConfigPath(globalFlags['--config'], rootOverride ?? process.cwd());
+  const configPathResolved = configPath ?? configResolution.path;
+  // Only pass configPath to runtime options if it was explicitly provided (via --config flag or env var).
+  // If not explicit, let loadConfigLayers handle the default resolution to avoid ENOENT on missing config.
+  const runtimeOptionsWithPath = {
+    ...runtimeOptions,
+    configPath: configResolution.explicit ? configPathResolved : runtimeOptions.configPath,
+  };
+
+  if (command === 'daemon') {
+    await handleDaemonCli(args, {
+      configPath: configPathResolved,
+      configExplicit: configResolution.explicit,
+      rootDir: rootOverride,
+    });
+    return;
+  }
+
+  if (command === 'config') {
+    await handleConfigCli(
+      {
+        loadOptions: { configPath, rootDir: rootOverride },
+        invokeAuth: (authArgs) => invokeAuthCommand(runtimeOptionsWithPath, authArgs),
+      },
+      args
+    );
+    return;
+  }
+
+  if (command === 'emit-ts') {
+    const runtime = await createRuntime(runtimeOptionsWithPath);
+    try {
+      await handleEmitTs(runtime, args);
+    } finally {
+      await runtime.close().catch(() => {});
+    }
+    return;
+  }
+
+  const baseRuntime = await createRuntime(runtimeOptionsWithPath);
+  const keepAliveServers = new Set(
+    baseRuntime
+      .getDefinitions()
+      .filter(isKeepAliveServer)
+      .map((entry) => entry.name)
+  );
+  const daemonClient =
+    keepAliveServers.size > 0
+      ? new DaemonClient({
+          configPath: configResolution.path,
+          configExplicit: configResolution.explicit,
+          rootDir: rootOverride,
+        })
+      : null;
+  const runtime = createKeepAliveRuntime(baseRuntime, { daemonClient, keepAliveServers });
+
+  const inference = inferCommandRouting(command, args, runtime.getDefinitions());
+  if (inference.kind === 'abort') {
+    process.exitCode = inference.exitCode;
+    return;
+  }
+  const resolvedCommand = inference.command;
+  const resolvedArgs = inference.args;
+
+  try {
+    if (resolvedCommand === 'list') {
+      if (consumeHelpTokens(resolvedArgs)) {
+        printListHelp();
+        process.exitCode = 0;
+        return;
+      }
+      await handleList(runtime, resolvedArgs);
+      return;
+    }
+
+    if (resolvedCommand === 'call') {
+      if (consumeHelpTokens(resolvedArgs)) {
+        printCallHelp();
+        process.exitCode = 0;
+        return;
+      }
+      await runHandleCall(runtime, resolvedArgs);
+      return;
+    }
+
+    if (resolvedCommand === 'auth') {
+      if (consumeHelpTokens(resolvedArgs)) {
+        printAuthHelp();
+        process.exitCode = 0;
+        return;
+      }
+      await handleAuth(runtime, resolvedArgs);
+      return;
+    }
+  } finally {
+    const closeStart = Date.now();
+    if (DEBUG_HANG) {
+      logInfo('[debug] beginning runtime.close()');
+      dumpActiveHandles('before runtime.close');
+    }
+    try {
+      await runtime.close();
+      if (DEBUG_HANG) {
+        const duration = Date.now() - closeStart;
+        logInfo(`[debug] runtime.close() completed in ${duration}ms`);
+        dumpActiveHandles('after runtime.close');
+      }
+    } catch (error) {
+      if (DEBUG_HANG) {
+        logError('[debug] runtime.close() failed', error);
+      }
+    } finally {
+      terminateChildProcesses('runtime.finally');
+      // By default we force an exit after cleanup so Node doesn't hang on lingering stdio handles
+      // (see typescript-sdk#579/#780/#1049). Opt out by exporting MCPORTER_NO_FORCE_EXIT=1.
+      const disableForceExit = process.env.MCPORTER_NO_FORCE_EXIT === '1';
+      if (DEBUG_HANG) {
+        dumpActiveHandles('after terminateChildProcesses');
+        if (!disableForceExit || process.env.MCPORTER_FORCE_EXIT === '1') {
+          process.exit(0);
+        }
+      } else {
+        const scheduleExit = () => {
+          if (!disableForceExit || process.env.MCPORTER_FORCE_EXIT === '1') {
+            process.exit(0);
+          }
+        };
+        setImmediate(scheduleExit);
+      }
+    }
+  }
+  printHelp(`Unknown command '${resolvedCommand}'.`);
+  process.exit(1);
+}
+
+// main parses CLI flags and dispatches to list/call commands.
+async function main(): Promise<void> {
+  await runCli(process.argv.slice(2));
+}
+
+if (process.env.MCPORTER_DISABLE_AUTORUN !== '1') {
+  main().catch((error) => {
+    if (error instanceof CliUsageError) {
+      logError(error.message);
+      process.exit(1);
+      return;
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    logError(message, error instanceof Error ? error : undefined);
+    process.exit(1);
+  });
+}
+
+async function invokeAuthCommand(runtimeOptions: Parameters<typeof createRuntime>[0], args: string[]): Promise<void> {
+  const runtime = await createRuntime(runtimeOptions);
+  try {
+    await handleAuth(runtime, args);
+  } finally {
+    await runtime.close().catch(() => {});
+  }
+}