@nimrobo/mcporter-remote 0.1.0

package/src/cli/list-doc-comments.ts

@@ -0,0 +1,129 @@
+import type { GeneratedOption } from './generate/tools.js';
+import { cyanText, extraDimText, yellowText } from './terminal.js';
+
+const DEFAULT_WRAP_WIDTH = 100;
+
+export function buildDocComment(
+  description: string | undefined,
+  options: GeneratedOption[],
+  opts?: { colorize?: boolean }
+): string[] | undefined {
+  const colorize = opts?.colorize !== false;
+  const descriptionLines = description?.split(/\r?\n/) ?? [];
+  const paramDocs = options.filter((option) => option.description);
+  if (descriptionLines.every((line) => line.trim().length === 0) && paramDocs.length === 0) {
+    return undefined;
+  }
+  const tint = colorize ? extraDimText : (value: string): string => value;
+  const highlightParam = colorize ? (value: string): string => yellowText(value) : (value: string): string => value;
+  const highlightName = colorize ? (value: string): string => cyanText(value) : (value: string): string => value;
+  const lines: string[] = [];
+  lines.push(tint('/**'));
+  let hasDescription = false;
+  for (const line of descriptionLines) {
+    const trimmed = line.trimEnd();
+    if (trimmed.trim().length > 0) {
+      const wrapped = wrapCommentText(trimmed);
+      for (const segment of wrapped) {
+        lines.push(tint(` * ${segment}`));
+      }
+      hasDescription = true;
+    }
+  }
+  if (hasDescription && paramDocs.length > 0) {
+    lines.push(tint(' *'));
+  }
+  for (const option of paramDocs) {
+    const optionLines = formatParamDoc(option, DEFAULT_WRAP_WIDTH, {
+      colorize,
+      highlightParam,
+      highlightName,
+    });
+    lines.push(...optionLines);
+  }
+  lines.push(tint(' */'));
+  return lines;
+}
+
+function formatParamDoc(
+  option: GeneratedOption,
+  wrapWidth: number,
+  config: {
+    colorize: boolean;
+    highlightParam: (value: string) => string;
+    highlightName: (value: string) => string;
+  }
+): string[] {
+  const { colorize, highlightParam, highlightName } = config;
+  const descriptionLines = option.description?.split(/\r?\n/) ?? [''];
+  const optionalSuffix = option.required ? '' : '?';
+  const plainLabel = `@param ${option.property}${optionalSuffix}`;
+  const continuationPrefix = colorize
+    ? extraDimText(` * ${' '.repeat(plainLabel.length + 1)}`)
+    : ` * ${' '.repeat(plainLabel.length + 1)}`;
+  const rendered: string[] = [];
+  descriptionLines.forEach((entry, index) => {
+    const suffix = entry.trimEnd();
+    if (index === 0) {
+      const lineParts = [
+        colorize ? extraDimText(' * ') : ' * ',
+        highlightParam('@param '),
+        highlightName(`${option.property}${optionalSuffix}`),
+      ];
+      if (suffix.length > 0) {
+        const wrapped = wrapCommentText(suffix, wrapWidth - plainLabel.length - 1);
+        if (wrapped.length > 0) {
+          lineParts.push(colorize ? extraDimText(` ${wrapped[0]}`) : ` ${wrapped[0]}`);
+          rendered.push(lineParts.join(''));
+          for (const continuation of wrapped.slice(1)) {
+            rendered.push(`${continuationPrefix}${colorize ? extraDimText(continuation) : continuation}`);
+          }
+          return;
+        }
+      }
+      rendered.push(lineParts.join(''));
+      return;
+    }
+    if (suffix.length > 0) {
+      const wrapped = wrapCommentText(suffix, wrapWidth - plainLabel.length - 1);
+      if (wrapped.length === 0) {
+        return;
+      }
+      const [first, ...rest] = wrapped;
+      if (!first) {
+        return;
+      }
+      rendered.push(`${continuationPrefix}${colorize ? extraDimText(first) : first}`);
+      for (const segment of rest) {
+        rendered.push(`${continuationPrefix}${colorize ? extraDimText(segment) : segment}`);
+      }
+    }
+  });
+  return rendered;
+}
+
+export function wrapCommentText(text: string, width = DEFAULT_WRAP_WIDTH): string[] {
+  if (!text) {
+    return [];
+  }
+  const words = text.split(/\s+/).filter(Boolean);
+  if (words.length === 0) {
+    return [];
+  }
+  const lines: string[] = [];
+  let current = words[0] ?? '';
+  for (let index = 1; index < words.length; index += 1) {
+    const word = words[index];
+    if (!word) {
+      continue;
+    }
+    if (`${current} ${word}`.length > width) {
+      lines.push(current);
+      current = word;
+    } else {
+      current += ` ${word}`;
+    }
+  }
+  lines.push(current);
+  return lines;
+}

package/src/cli/list-format.ts

@@ -0,0 +1,150 @@
+import type { ServerDefinition, ServerSource } from '../config.js';
+import type { ConnectionIssue } from '../error-classifier.js';
+import { analyzeConnectionError } from '../error-classifier.js';
+import type { ServerToolInfo } from '../runtime.js';
+import { formatPathForDisplay } from './path-utils.js';
+import { dimText, extraDimText, redText, yellowText } from './terminal.js';
+
+export type StatusCategory = 'ok' | 'auth' | 'offline' | 'http' | 'error';
+
+export type ListSummaryResult =
+  | {
+      status: 'ok';
+      server: ServerDefinition;
+      tools: ServerToolInfo[];
+      durationMs: number;
+    }
+  | {
+      status: 'error';
+      server: ServerDefinition;
+      error: unknown;
+      durationMs: number;
+    };
+
+export function renderServerListRow(
+  result: ListSummaryResult,
+  timeoutMs: number,
+  options: { verbose?: boolean } = {}
+): {
+  line: string;
+  summary: string;
+  category: StatusCategory;
+  authCommand?: string;
+  issue?: ConnectionIssue;
+} {
+  const description = result.server.description ? dimText(` — ${result.server.description}`) : '';
+  const durationLabel = dimText(`${(result.durationMs / 1000).toFixed(1)}s`);
+  const sourceSuffix = formatSourceSuffix(result.server.sources ?? result.server.source, false, {
+    verbose: options.verbose,
+  });
+  const prefix = `- ${result.server.name}${description}`;
+
+  if (result.status === 'ok') {
+    const toolSuffix =
+      result.tools.length === 0
+        ? 'no tools reported'
+        : `${result.tools.length === 1 ? '1 tool' : `${result.tools.length} tools`}`;
+    return {
+      line: `${prefix} (${toolSuffix}, ${durationLabel})${sourceSuffix}`,
+      summary: toolSuffix,
+      category: 'ok',
+    };
+  }
+
+  const timeoutSeconds = Math.round(timeoutMs / 1000);
+  const advice = classifyListError(result.error, result.server.name, timeoutSeconds);
+  return {
+    line: `${prefix} (${advice.colored}, ${durationLabel})${sourceSuffix}`,
+    summary: advice.summary,
+    category: advice.category,
+    authCommand: advice.authCommand,
+    issue: advice.issue,
+  };
+}
+
+export function truncateForSpinner(text: string, maxLength = 72): string {
+  if (text.length <= maxLength) {
+    return text;
+  }
+  return `${text.slice(0, Math.max(0, maxLength - 1))}…`;
+}
+
+export function formatSourceSuffix(
+  sourceOrSources: ServerSource | readonly ServerSource[] | undefined,
+  inline = false,
+  options: { verbose?: boolean } = {}
+): string {
+  const sources = Array.isArray(sourceOrSources) ? [...sourceOrSources] : sourceOrSources ? [sourceOrSources] : [];
+  if (sources.length === 0) {
+    return '';
+  }
+  const verbose = options.verbose ?? false;
+  if (!verbose) {
+    const primary = sources[0];
+    if (primary.kind !== 'import') {
+      return '';
+    }
+    const formatted = formatPathForDisplay(primary.path);
+    const tinted = extraDimText(inline ? formatted : `[source: ${formatted}]`);
+    return inline ? tinted : ` ${tinted}`;
+  }
+  // When verbose, show every contributing source (primary first) so duplicates are discoverable.
+  const [primary, ...alternates] = sources;
+  const primaryLabel = buildSourceLabel(primary, { primary: true });
+  const altLabels = alternates.map((entry) => {
+    const shadowedByLocal = primary.kind === 'local' && entry.kind !== 'local';
+    return buildSourceLabel(entry, { shadowReason: shadowedByLocal ? 'shadowed by local' : 'shadowed' });
+  });
+  const label =
+    altLabels.length === 0 ? `source: ${primaryLabel}` : `sources: ${[primaryLabel, ...altLabels].join(' · ')}`;
+  const tinted = extraDimText(inline ? label : `[${label}]`);
+  return inline ? tinted : ` ${tinted}`;
+}
+
+function buildSourceLabel(source: ServerSource, options: { primary?: boolean; shadowReason?: string }): string {
+  const base = formatPathForDisplay(source.path);
+  const tags: string[] = [];
+  if (options.primary) {
+    tags.push('primary');
+  }
+  if (options.shadowReason) {
+    tags.push(options.shadowReason);
+  }
+  if (source.importKind) {
+    tags.push(source.importKind);
+  }
+  return tags.length === 0 ? base : `${base} (${tags.join(', ')})`;
+}
+
+export function classifyListError(
+  error: unknown,
+  serverName: string,
+  _timeoutSeconds: number,
+  options?: { authCommand?: string }
+): {
+  colored: string;
+  summary: string;
+  category: StatusCategory;
+  authCommand?: string;
+  issue: ConnectionIssue;
+} {
+  const issue = analyzeConnectionError(error);
+  if (issue.kind === 'auth') {
+    const authCommand = options?.authCommand ?? `mcporter auth ${serverName}`;
+    const note = yellowText(`auth required — run '${authCommand}'`);
+    return { colored: note, summary: 'auth required', category: 'auth', authCommand, issue };
+  }
+  if (issue.kind === 'offline') {
+    const note = redText('offline — unable to reach server');
+    return { colored: note, summary: 'offline', category: 'offline', issue };
+  }
+  if (issue.kind === 'http') {
+    const statusText = issue.statusCode ? `HTTP ${issue.statusCode}` : 'HTTP error';
+    const detail = issue.rawMessage && issue.rawMessage !== String(issue.statusCode) ? ` — ${issue.rawMessage}` : '';
+    const note = redText(`${statusText}${detail}`);
+    return { colored: note, summary: statusText.toLowerCase(), category: 'http', issue };
+  }
+  const rawMessage = issue.rawMessage || 'unknown error';
+  const note = redText(rawMessage);
+  return { colored: note, summary: rawMessage, category: 'error', issue };
+}

package/src/cli/list-output.ts

@@ -0,0 +1,224 @@
+import type { ServerDefinition } from '../config.js';
+import type { ToolMetadata } from './generate/tools.js';
+import type { SerializedConnectionIssue } from './json-output.js';
+import { formatErrorMessage, serializeConnectionIssue } from './json-output.js';
+import { buildToolDoc } from './list-detail-helpers.js';
+import type { ListSummaryResult, StatusCategory } from './list-format.js';
+import { classifyListError } from './list-format.js';
+import { boldText, extraDimText } from './terminal.js';
+import { formatTransportSummary } from './transport-utils.js';
+
+export interface ToolDetailResult {
+  examples: string[];
+  optionalOmitted: boolean;
+}
+
+export interface ListJsonServerEntry {
+  name: string;
+  status: StatusCategory;
+  durationMs: number;
+  description?: string;
+  transport?: string;
+  source?: ServerDefinition['source'];
+  sources?: ServerDefinition['sources'];
+  tools?: Array<{
+    name: string;
+    description?: string;
+    inputSchema?: unknown;
+    outputSchema?: unknown;
+  }>;
+  issue?: SerializedConnectionIssue;
+  authCommand?: string;
+  error?: string;
+}
+
+export function printSingleServerHeader(
+  definition: ReturnType<Awaited<ReturnType<typeof import('../runtime.js')['createRuntime']>>['getDefinition']>,
+  toolCount: number | undefined,
+  durationMs: number | undefined,
+  transportSummary: string,
+  sourcePath: string | undefined,
+  options?: { printSummaryNow?: boolean }
+): string {
+  const prefix = boldText(definition.name);
+  if (definition.description) {
+    console.log(`${prefix} - ${extraDimText(definition.description)}`);
+  } else {
+    console.log(prefix);
+  }
+  const summaryParts: string[] = [];
+  summaryParts.push(
+    extraDimText(typeof toolCount === 'number' ? `${toolCount} tool${toolCount === 1 ? '' : 's'}` : 'tools unavailable')
+  );
+  if (typeof durationMs === 'number') {
+    summaryParts.push(extraDimText(`${durationMs}ms`));
+  }
+  if (transportSummary) {
+    summaryParts.push(extraDimText(transportSummary));
+  }
+  if (sourcePath) {
+    summaryParts.push(sourcePath);
+  }
+  const summaryLine = `  ${summaryParts.join(extraDimText(' · '))}`;
+  if (options?.printSummaryNow === false) {
+    console.log('');
+  } else {
+    console.log(summaryLine);
+    console.log('');
+  }
+  return summaryLine;
+}
+
+export function printToolDetail(
+  definition: ReturnType<Awaited<ReturnType<typeof import('../runtime.js')['createRuntime']>>['getDefinition']>,
+  metadata: ToolMetadata,
+  includeSchema: boolean,
+  requiredOnly: boolean
+): ToolDetailResult {
+  const exampleOptions = buildExampleOptions(definition);
+  const doc = buildToolDoc({
+    serverName: definition.name,
+    toolName: metadata.tool.name,
+    description: metadata.tool.description,
+    outputSchema: metadata.tool.outputSchema,
+    options: metadata.options,
+    requiredOnly,
+    colorize: true,
+    callSelector: exampleOptions?.selector,
+    wrapExampleExpression: exampleOptions?.wrapExpression,
+  });
+  if (doc.docLines) {
+    for (const line of doc.docLines) {
+      console.log(`  ${line}`);
+    }
+  }
+  console.log(`  ${doc.signature}`);
+  if (doc.optionalSummary && requiredOnly) {
+    console.log(`  ${doc.optionalSummary}`);
+  }
+  if (includeSchema && metadata.tool.inputSchema) {
+    console.log(indent(JSON.stringify(metadata.tool.inputSchema, null, 2), '      '));
+  }
+  console.log('');
+  return {
+    examples: doc.examples,
+    optionalOmitted: doc.hiddenOptions.length > 0,
+  };
+}
+
+function buildExampleOptions(
+  definition: ReturnType<Awaited<ReturnType<typeof import('../runtime.js')['createRuntime']>>['getDefinition']>
+): { selector?: string; wrapExpression?: boolean } | undefined {
+  if (definition.source?.kind !== 'local' || definition.source.path !== '<adhoc>') {
+    return undefined;
+  }
+  if (definition.command.kind === 'http') {
+    const url = definition.command.url instanceof URL ? definition.command.url.href : String(definition.command.url);
+    return { selector: url, wrapExpression: true };
+  }
+  return undefined;
+}
+
+export function createEmptyStatusCounts(): Record<StatusCategory, number> {
+  return {
+    ok: 0,
+    auth: 0,
+    offline: 0,
+    http: 0,
+    error: 0,
+  };
+}
+
+export function summarizeStatusCounts(entries: ListJsonServerEntry[]): Record<StatusCategory, number> {
+  const counts = createEmptyStatusCounts();
+  entries.forEach((entry) => {
+    counts[entry.status] = (counts[entry.status] ?? 0) + 1;
+  });
+  return counts;
+}
+
+export function buildJsonListEntry(
+  result: ListSummaryResult,
+  timeoutSeconds: number,
+  options: { includeSchemas: boolean; includeSources?: boolean }
+): ListJsonServerEntry {
+  if (result.status === 'ok') {
+    return {
+      name: result.server.name,
+      status: 'ok',
+      durationMs: result.durationMs,
+      description: result.server.description,
+      transport: formatTransportSummary(
+        result.server as ReturnType<
+          Awaited<ReturnType<typeof import('../runtime.js')['createRuntime']>>['getDefinition']
+        >
+      ),
+      source: result.server.source,
+      sources: options.includeSources ? result.server.sources : undefined,
+      tools: result.tools.map((tool) => ({
+        name: tool.name,
+        description: tool.description,
+        inputSchema: options.includeSchemas ? tool.inputSchema : undefined,
+        outputSchema: options.includeSchemas ? tool.outputSchema : undefined,
+      })),
+    };
+  }
+  const authCommand = buildAuthCommandHint(
+    result.server as ReturnType<Awaited<ReturnType<typeof import('../runtime.js')['createRuntime']>>['getDefinition']>
+  );
+  const advice = classifyListError(result.error, result.server.name, timeoutSeconds, { authCommand });
+  return {
+    name: result.server.name,
+    status: advice.category,
+    durationMs: result.durationMs,
+    description: result.server.description,
+    transport: formatTransportSummary(
+      result.server as ReturnType<Awaited<ReturnType<typeof import('../runtime.js')['createRuntime']>>['getDefinition']>
+    ),
+    source: result.server.source,
+    sources: options.includeSources ? result.server.sources : undefined,
+    issue: serializeConnectionIssue(advice.issue),
+    authCommand: advice.authCommand,
+    error: formatErrorMessage(result.error),
+  };
+}
+
+export function createUnknownResult(server: ServerDefinition): ListSummaryResult {
+  return {
+    status: 'error',
+    server,
+    error: new Error('Unknown server result'),
+    durationMs: 0,
+  };
+}
+
+export function buildAuthCommandHint(
+  definition: ReturnType<Awaited<ReturnType<typeof import('../runtime.js')['createRuntime']>>['getDefinition']>
+): string {
+  if (definition.source?.kind === 'local' && definition.source.path === '<adhoc>') {
+    if (definition.command.kind === 'http') {
+      const url = definition.command.url instanceof URL ? definition.command.url.href : String(definition.command.url);
+      return `mcporter auth ${url}`;
+    }
+    if (definition.command.kind === 'stdio') {
+      const parts = [definition.command.command, ...(definition.command.args ?? [])];
+      const rendered = parts.map(quoteCommandSegment).join(' ').trim();
+      return rendered.length > 0 ? `mcporter auth --stdio ${rendered}` : 'mcporter auth --stdio';
+    }
+  }
+  return `mcporter auth ${definition.name}`;
+}
+
+function indent(text: string, pad: string): string {
+  return text
+    .split('\n')
+    .map((line) => pad + line)
+    .join('\n');
+}
+
+function quoteCommandSegment(segment: string): string {
+  if (/^[A-Za-z0-9_./:-]+$/.test(segment)) {
+    return segment;
+  }
+  return JSON.stringify(segment);
+}