@humain/terminal 0.0.2 → 0.0.3-beta.0

package/dist/humain/mcp-adapter/vendor/json-schema-validator.ts

@@ -0,0 +1,69 @@
+import { Ajv } from "ajv";
+import Ajv2020Import from "ajv/dist/2020.js";
+import addFormatsImport from "ajv-formats";
+import { AjvJsonSchemaValidator } from "@modelcontextprotocol/client/validators/ajv";
+import type {
+  JsonSchemaType,
+  JsonSchemaValidator,
+  jsonSchemaValidator as JsonSchemaValidatorProvider,
+} from "@modelcontextprotocol/client";
+
+// ajv-formats types target its bundled ajv; the runtime accepts both instances.
+const addFormats = addFormatsImport as unknown as (instance: Ajv) => void;
+
+type SchemaDialect =
+  | { status: "unstamped" }
+  | { status: "stamped"; uri: string };
+
+const DRAFT_07_SCHEMA_URIS: ReadonlySet<string> = new Set([
+  "http://json-schema.org/draft-07/schema",
+  "https://json-schema.org/draft-07/schema",
+]);
+const DRAFT_2020_12_SCHEMA_URIS: ReadonlySet<string> = new Set([
+  "https://json-schema.org/draft/2020-12/schema",
+]);
+
+function schemaDialect(schema: JsonSchemaType): SchemaDialect {
+  if (!("$schema" in schema) || typeof schema.$schema !== "string") {
+    return { status: "unstamped" };
+  }
+  return {
+    status: "stamped",
+    uri: schema.$schema.endsWith("#") ? schema.$schema.slice(0, -1) : schema.$schema,
+  };
+}
+
+export function createJsonSchemaValidator(): JsonSchemaValidatorProvider {
+  let draft07Validator: AjvJsonSchemaValidator | undefined;
+  let draft2020Validator: AjvJsonSchemaValidator | undefined;
+
+  return {
+    getValidator<T>(schema: JsonSchemaType): JsonSchemaValidator<T> {
+      const dialect = schemaDialect(schema);
+      if (dialect.status === "unstamped" || DRAFT_2020_12_SCHEMA_URIS.has(dialect.uri)) {
+        draft2020Validator ??= (() => {
+          const Ajv2020 = Ajv2020Import as unknown as typeof Ajv;
+          const ajv = new Ajv2020({ strict: false, allErrors: true });
+          addFormats(ajv);
+          return new AjvJsonSchemaValidator(ajv);
+        })();
+        return draft2020Validator.getValidator<T>(schema);
+      }
+      if (!DRAFT_07_SCHEMA_URIS.has(dialect.uri)) {
+        throw new Error(`Unsupported JSON Schema dialect: ${dialect.uri}`);
+      }
+
+      draft07Validator ??= (() => {
+        const ajv = new Ajv({
+          strict: false,
+          validateFormats: true,
+          validateSchema: false,
+          allErrors: true,
+        });
+        addFormats(ajv);
+        return new AjvJsonSchemaValidator(ajv);
+      })();
+      return draft07Validator.getValidator<T>(schema);
+    },
+  };
+}

package/dist/humain/mcp-adapter/vendor/lifecycle.ts

@@ -0,0 +1,147 @@
+import { isServerDisabled, type ServerDefinition } from "./types.ts";
+import type { McpServerManager } from "./server-manager.ts";
+import { hasPendingAuth } from "./mcp-auth-flow.ts";
+import { logger } from "./logger.ts";
+import { formatTerminalError, sanitizeTerminalText } from "./utils.ts";
+
+export type ReconnectCallback = (serverName: string) => void;
+export type ReconnectFailureCallback = (serverName: string, error: unknown) => void;
+
+export class McpLifecycleManager {
+  private keepAliveServers = new Map<string, ServerDefinition>();
+  private allServers = new Map<string, ServerDefinition>();
+  private serverSettings = new Map<string, { idleTimeout?: number }>();
+  private globalIdleTimeout = 10 * 60 * 1000;
+  private healthCheckInterval: NodeJS.Timeout | undefined;
+  private onReconnect: ReconnectCallback | undefined;
+  private onReconnectFailure: ReconnectFailureCallback | undefined;
+  private onIdleShutdown: ((serverName: string) => void) | undefined;
+  private activeHealthCheck: Promise<void> | undefined;
+  private shutdownPromise: Promise<void> | undefined;
+  private stopped = false;
+  private removeHealthAbortListener: (() => void) | undefined;
+
+  constructor(
+    private readonly manager: McpServerManager,
+    private readonly hasPendingAuthForServer = hasPendingAuth,
+  ) {}
+
+  setReconnectCallback(callback: ReconnectCallback): void {
+    this.onReconnect = callback;
+  }
+
+  setReconnectFailureCallback(callback: ReconnectFailureCallback): void {
+    this.onReconnectFailure = callback;
+  }
+
+  markKeepAlive(name: string, definition: ServerDefinition): void {
+    if (isServerDisabled(definition)) return;
+    this.keepAliveServers.set(name, definition);
+  }
+
+  registerServer(name: string, definition: ServerDefinition, settings?: { idleTimeout?: number }): void {
+    if (isServerDisabled(definition)) return;
+    this.allServers.set(name, definition);
+    if (settings?.idleTimeout !== undefined) this.serverSettings.set(name, settings);
+  }
+
+  setGlobalIdleTimeout(minutes: number): void {
+    this.globalIdleTimeout = minutes * 60 * 1000;
+  }
+
+  setIdleShutdownCallback(callback: (serverName: string) => void): void {
+    this.onIdleShutdown = callback;
+  }
+
+  startHealthChecks(signalOrInterval?: AbortSignal | number, maybeIntervalMs = 30000): void {
+    const signal = typeof signalOrInterval === "number" ? undefined : signalOrInterval;
+    const intervalMs = typeof signalOrInterval === "number" ? signalOrInterval : maybeIntervalMs;
+    this.stopped = false;
+    if (signal?.aborted) {
+      this.stopped = true;
+      return;
+    }
+    const stop = () => {
+      this.stopped = true;
+      if (this.healthCheckInterval) clearInterval(this.healthCheckInterval);
+      this.healthCheckInterval = undefined;
+    };
+    signal?.addEventListener("abort", stop, { once: true });
+    this.removeHealthAbortListener = () => signal?.removeEventListener("abort", stop);
+    this.healthCheckInterval = setInterval(() => {
+      if (this.stopped || signal?.aborted || this.activeHealthCheck) return;
+      const check = this.checkConnections(signal)
+        .catch(error => {
+          console.error(`MCP: Health check failed: ${formatTerminalError(error)}`);
+        })
+        .finally(() => {
+          if (this.activeHealthCheck === check) this.activeHealthCheck = undefined;
+        });
+      this.activeHealthCheck = check;
+    }, intervalMs);
+    this.healthCheckInterval.unref();
+  }
+
+  private async checkConnections(signal?: AbortSignal): Promise<void> {
+    if (this.stopped || signal?.aborted) return;
+    for (const [name, definition] of this.keepAliveServers) {
+      if (isServerDisabled(definition)) continue;
+      const connection = this.manager.getConnection(name);
+      if (!connection || connection.status !== "connected") {
+        if (this.hasPendingAuthForServer(name)) {
+          logger.debug(`Skipping reconnect for ${name} while OAuth authorization is pending`);
+          continue;
+        }
+        try {
+          await this.manager.connect(name, definition, signal);
+          if (this.stopped || signal?.aborted) return;
+          logger.debug(`Reconnected to ${name}`);
+          this.onReconnect?.(name);
+        } catch (error) {
+          if (this.stopped || signal?.aborted) return;
+          this.onReconnectFailure?.(name, error);
+          const message = error instanceof Error ? error.message : String(error);
+          console.error(`MCP: Failed to reconnect to ${name}: ${sanitizeTerminalText(message)}`);
+        }
+      }
+    }
+
+    for (const [name] of this.allServers) {
+      if (this.keepAliveServers.has(name)) continue;
+      const timeout = this.getIdleTimeout(name);
+      if (timeout > 0 && this.manager.isIdle(name, timeout)) {
+        await this.manager.close(name);
+        if (this.stopped || signal?.aborted) return;
+        this.onIdleShutdown?.(name);
+      }
+    }
+  }
+
+  private getIdleTimeout(name: string): number {
+    const perServer = this.serverSettings.get(name)?.idleTimeout;
+    if (perServer !== undefined) return perServer * 60 * 1000;
+    return this.globalIdleTimeout;
+  }
+
+  async gracefulShutdown(): Promise<void> {
+    if (this.shutdownPromise) return this.shutdownPromise;
+    this.shutdownPromise = this.shutdownOnce();
+    return this.shutdownPromise;
+  }
+
+  private async shutdownOnce(): Promise<void> {
+    this.stopped = true;
+    if (this.healthCheckInterval) clearInterval(this.healthCheckInterval);
+    this.healthCheckInterval = undefined;
+    this.removeHealthAbortListener?.();
+    this.removeHealthAbortListener = undefined;
+    await this.activeHealthCheck;
+    this.activeHealthCheck = undefined;
+    this.onReconnect = undefined;
+    this.onReconnectFailure = undefined;
+    this.onIdleShutdown = undefined;
+    if (typeof this.manager.closeAll === "function") {
+      await this.manager.closeAll();
+    }
+  }
+}

package/dist/humain/mcp-adapter/vendor/logger.ts

@@ -0,0 +1,169 @@
+/**
+ * Centralized logging for MCP UI operations.
+ * Provides structured, contextual logs with levels.
+ */
+
+export type LogLevel = "debug" | "info" | "warn" | "error";
+
+export interface LogContext {
+  server?: string;
+  session?: string;
+  tool?: string;
+  uri?: string;
+  [key: string]: unknown;
+}
+
+export interface LogEntry {
+  level: LogLevel;
+  message: string;
+  context?: LogContext;
+  error?: Error;
+  timestamp: Date;
+}
+
+type LogHandler = (entry: LogEntry) => void;
+
+const LEVEL_PRIORITY: Record<LogLevel, number> = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+};
+
+const LEVEL_PREFIX: Record<LogLevel, string> = {
+  debug: "[MCP-UI:DEBUG]",
+  info: "[MCP-UI]",
+  warn: "[MCP-UI:WARN]",
+  error: "[MCP-UI:ERROR]",
+};
+
+class Logger {
+  private minLevel: LogLevel = "info";
+  private handlers: LogHandler[] = [];
+  private defaultContext: LogContext = {};
+
+  setLevel(level: LogLevel): void {
+    this.minLevel = level;
+  }
+
+  setDefaultContext(context: LogContext): void {
+    this.defaultContext = context;
+  }
+
+  addHandler(handler: LogHandler): void {
+    this.handlers.push(handler);
+  }
+
+  clearHandlers(): void {
+    this.handlers = [];
+  }
+
+  private shouldLog(level: LogLevel): boolean {
+    return LEVEL_PRIORITY[level] >= LEVEL_PRIORITY[this.minLevel];
+  }
+
+  private emit(level: LogLevel, message: string, context?: LogContext, error?: Error): void {
+    if (!this.shouldLog(level)) return;
+
+    const entry: LogEntry = {
+      level,
+      message,
+      context: { ...this.defaultContext, ...context },
+      ...(error !== undefined ? { error } : {}),
+      timestamp: new Date(),
+    };
+
+    // Default console output
+    const prefix = LEVEL_PREFIX[level];
+    const contextStr = formatContext(entry.context);
+    const fullMessage = contextStr ? `${prefix} ${message} ${contextStr}` : `${prefix} ${message}`;
+
+    if (level === "error") {
+      console.error(fullMessage, error ?? "");
+    } else if (level === "warn") {
+      console.warn(fullMessage);
+    } else if (level === "debug") {
+      console.debug(fullMessage);
+    } else {
+      console.log(fullMessage);
+    }
+
+    // Custom handlers
+    for (const handler of this.handlers) {
+      try {
+        handler(entry);
+      } catch {
+        // Ignore handler errors
+      }
+    }
+  }
+
+  debug(message: string, context?: LogContext): void {
+    this.emit("debug", message, context);
+  }
+
+  info(message: string, context?: LogContext): void {
+    this.emit("info", message, context);
+  }
+
+  warn(message: string, context?: LogContext): void {
+    this.emit("warn", message, context);
+  }
+
+  error(message: string, error?: Error, context?: LogContext): void {
+    this.emit("error", message, context, error);
+  }
+
+  /**
+   * Create a child logger with additional default context.
+   */
+  child(context: LogContext): ChildLogger {
+    return new ChildLogger(this, context);
+  }
+}
+
+class ChildLogger {
+  constructor(
+    private parent: Logger,
+    private context: LogContext
+  ) {}
+
+  debug(message: string, context?: LogContext): void {
+    this.parent.debug(message, { ...this.context, ...context });
+  }
+
+  info(message: string, context?: LogContext): void {
+    this.parent.info(message, { ...this.context, ...context });
+  }
+
+  warn(message: string, context?: LogContext): void {
+    this.parent.warn(message, { ...this.context, ...context });
+  }
+
+  error(message: string, error?: Error, context?: LogContext): void {
+    this.parent.error(message, error, { ...this.context, ...context });
+  }
+
+  child(context: LogContext): ChildLogger {
+    return new ChildLogger(this.parent, { ...this.context, ...context });
+  }
+}
+
+function formatContext(context?: LogContext): string {
+  if (!context || Object.keys(context).length === 0) return "";
+  const parts: string[] = [];
+  for (const [key, value] of Object.entries(context)) {
+    if (value !== undefined && value !== null) {
+      parts.push(`${key}=${typeof value === "string" ? value : JSON.stringify(value)}`);
+    }
+  }
+  return parts.length > 0 ? `(${parts.join(", ")})` : "";
+}
+
+// Singleton instance
+export const logger = new Logger();
+
+// Enable debug mode via environment variable
+if (process.env.MCP_UI_DEBUG === "1" || process.env.MCP_UI_DEBUG === "true") {
+  logger.setLevel("debug");
+}