@mandujs/core 0.9.41 → 0.9.43

package/src/devtools/index.ts

@@ -0,0 +1,439 @@
+/**
+ * Mandu Kitchen DevTools
+ * AI-Native Developer Tools for Mandu Framework
+ *
+ * @version 1.1.0
+ * @description "만두를 찌듯 편안하게 디버깅한다"
+ */
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type {
+  // Core
+  KitchenEvent,
+
+  // Error
+  ErrorType,
+  Severity,
+  NormalizedError,
+
+  // Island
+  HydrationStrategy,
+  IslandStatus,
+  IslandSnapshot,
+
+  // Network
+  NetworkRequest,
+  NetworkBodyPolicy,
+
+  // Guard
+  GuardViolation,
+
+  // AI Context
+  CodeContextInfo,
+  AIContextPayload,
+
+  // Redaction
+  RedactPattern,
+
+  // Persistence
+  PreserveLogConfig,
+
+  // Worker
+  WorkerPolicy,
+  WorkerTask,
+
+  // Config
+  Position,
+  Theme,
+  DevToolsConfig,
+
+  // Plugin
+  KitchenAPI,
+  KitchenPanelPlugin,
+
+  // Meta
+  MetaLogType,
+  KitchenMetaLog,
+
+  // Character
+  ManduState,
+  ManduCharacterData,
+} from './types';
+
+export { MANDU_CHARACTERS } from './types';
+
+// ============================================================================
+// Design Tokens
+// ============================================================================
+
+export {
+  colors,
+  typography,
+  spacing,
+  borderRadius,
+  borderWidth,
+  shadows,
+  animation,
+  zIndex,
+  breakpoints,
+  ManduDesignTokens,
+  generateCSSVariables,
+  testIds,
+  type TestId,
+} from './design-tokens';
+
+// ============================================================================
+// Client
+// ============================================================================
+
+export {
+  // State
+  KitchenStateManager,
+  getStateManager,
+  resetStateManager,
+  type KitchenState,
+  type StateListener,
+
+  // Error Catching
+  ErrorCatcher,
+  getErrorCatcher,
+  initializeErrorCatcher,
+  destroyErrorCatcher,
+
+  // Network Proxy
+  NetworkProxy,
+  getNetworkProxy,
+  initializeNetworkProxy,
+  destroyNetworkProxy,
+
+  // Filters
+  removeComments,
+  handleStrings,
+  redactBuiltInSecrets,
+  redactCustomPatterns,
+  truncate,
+  applyContextFilters,
+  sanitizeStackTrace,
+  sanitizeErrorMessage,
+  type FilterOptions,
+
+  // Persistence
+  PersistenceManager,
+  getPersistenceManager,
+  initializePersistence,
+  destroyPersistence,
+
+  // Components
+  ManduCharacter,
+  ManduBadge,
+  ErrorOverlay,
+  mountKitchen,
+  unmountKitchen,
+  isKitchenMounted,
+  type ManduCharacterProps,
+  type ManduBadgeProps,
+  type ErrorOverlayProps,
+} from './client';
+
+// ============================================================================
+// Initialization
+// ============================================================================
+
+export {
+  initManduKitchen,
+  destroyManduKitchen,
+  autoInit,
+  type KitchenInstance,
+} from './init';
+
+// ============================================================================
+// Protocol
+// ============================================================================
+
+export type { KitchenEvents } from './protocol';
+
+export {
+  // Type guards
+  isErrorEvent,
+  isIslandEvent,
+  isNetworkEvent,
+  isGuardEvent,
+  isHmrEvent,
+
+  // Event factories
+  createErrorEvent,
+  createIslandRegisterEvent,
+  createIslandHydrateStartEvent,
+  createIslandHydrateEndEvent,
+  createNetworkRequestEvent,
+  createNetworkResponseEvent,
+  createGuardViolationEvent,
+  createHmrUpdateEvent,
+  createHmrErrorEvent,
+
+  // Constants
+  DEVTOOLS_VERSION,
+  DEFAULT_CONFIG,
+  ALLOWED_HEADERS,
+  BLOCKED_HEADERS,
+} from './protocol';
+
+// ============================================================================
+// Hook
+// ============================================================================
+
+export {
+  createDevtoolsHook,
+  getOrCreateHook,
+  getHook,
+  initializeHook,
+  type ManduDevtoolsHook,
+  type EventSink,
+} from './hook';
+
+// ============================================================================
+// Convenience Functions
+// ============================================================================
+
+import { getOrCreateHook } from './hook';
+import type { NormalizedError, GuardViolation } from './types';
+import {
+  createErrorEvent,
+  createHmrUpdateEvent,
+  createHmrErrorEvent,
+  createGuardViolationEvent,
+} from './protocol';
+
+/**
+ * 에러 리포트 (간편 API)
+ *
+ * @example
+ * ```typescript
+ * import { reportError } from '@mandu/core/devtools';
+ *
+ * try {
+ *   // ...
+ * } catch (e) {
+ *   reportError(e);
+ * }
+ * ```
+ */
+export function reportError(
+  error: Error | string,
+  options?: Partial<Omit<NormalizedError, 'id' | 'timestamp' | 'message'>>
+): void {
+  const hook = getOrCreateHook();
+  const message = typeof error === 'string' ? error : error.message;
+  const stack = typeof error === 'string' ? undefined : error.stack;
+
+  hook.emit(
+    createErrorEvent({
+      type: options?.type ?? 'runtime',
+      severity: options?.severity ?? 'error',
+      message,
+      stack,
+      url: typeof window !== 'undefined' ? window.location.href : '',
+      ...options,
+    })
+  );
+}
+
+/**
+ * HMR 업데이트 알림 (간편 API)
+ */
+export function notifyHmrUpdate(routeId: string): void {
+  const hook = getOrCreateHook();
+  hook.emit(createHmrUpdateEvent(routeId));
+}
+
+/**
+ * HMR 에러 알림 (간편 API)
+ */
+export function notifyHmrError(message: string, stack?: string): void {
+  const hook = getOrCreateHook();
+  hook.emit(createHmrErrorEvent(message, stack));
+}
+
+/**
+ * Guard 위반 리포트 (간편 API)
+ */
+export function reportGuardViolation(
+  violation: Omit<GuardViolation, 'id' | 'timestamp'>
+): void {
+  const hook = getOrCreateHook();
+  hook.emit(createGuardViolationEvent(violation));
+}
+
+// ============================================================================
+// DevTools API (for external use)
+// ============================================================================
+
+/**
+ * DevTools 공개 API
+ * window.ManduDevTools로 접근 가능
+ */
+export const ManduDevTools = {
+  /**
+   * 로그 출력
+   */
+  log(level: 'info' | 'warn' | 'error', message: string, data?: unknown): void {
+    const hook = getOrCreateHook();
+    hook.emit({
+      type: 'log',
+      timestamp: Date.now(),
+      data: { level, message, data },
+    });
+  },
+
+  /**
+   * 에러 리포트
+   */
+  reportError,
+
+  /**
+   * 타이머 시작
+   */
+  time(label: string): void {
+    if (typeof performance !== 'undefined') {
+      performance.mark(`mandu-time-${label}`);
+    }
+  },
+
+  /**
+   * 타이머 종료 및 시간 반환
+   */
+  timeEnd(label: string): number {
+    if (typeof performance !== 'undefined') {
+      const markName = `mandu-time-${label}`;
+      try {
+        performance.measure(`mandu-measure-${label}`, markName);
+        const entries = performance.getEntriesByName(`mandu-measure-${label}`);
+        const duration = entries[entries.length - 1]?.duration ?? 0;
+        performance.clearMarks(markName);
+        performance.clearMeasures(`mandu-measure-${label}`);
+        return duration;
+      } catch {
+        return 0;
+      }
+    }
+    return 0;
+  },
+
+  /**
+   * DevTools 토글
+   */
+  toggle(): void {
+    const hook = getOrCreateHook();
+    hook.emit({
+      type: 'devtools:toggle',
+      timestamp: Date.now(),
+      data: {},
+    });
+  },
+
+  /**
+   * DevTools 열기
+   */
+  open(): void {
+    const hook = getOrCreateHook();
+    hook.emit({
+      type: 'devtools:open',
+      timestamp: Date.now(),
+      data: {},
+    });
+  },
+
+  /**
+   * DevTools 닫기
+   */
+  close(): void {
+    const hook = getOrCreateHook();
+    hook.emit({
+      type: 'devtools:close',
+      timestamp: Date.now(),
+      data: {},
+    });
+  },
+
+  /**
+   * 에러 목록 클리어
+   */
+  clearErrors(): void {
+    const hook = getOrCreateHook();
+    hook.emit({
+      type: 'error:clear',
+      timestamp: Date.now(),
+      data: {},
+    });
+  },
+};
+
+// 브라우저 환경에서 전역 객체에 등록
+if (typeof window !== 'undefined') {
+  (window as Window & { ManduDevTools?: typeof ManduDevTools }).ManduDevTools =
+    ManduDevTools;
+}
+
+// ============================================================================
+// v1.1: Server Module (Source Context Provider)
+// ============================================================================
+
+export {
+  SourceContextProvider,
+  SourcemapParser,
+  createViteMiddleware,
+  manduSourceContextPlugin,
+  type SourceContextRequest,
+  type SourceContextResponse,
+  type SourceContextProviderOptions,
+  type SourcemapPosition,
+  type SourcemapParseResult,
+} from './server';
+
+// ============================================================================
+// v1.1: Worker Module (Redaction Worker)
+// ============================================================================
+
+export {
+  // Redaction Worker
+  redactText,
+  truncateText,
+  BUILT_IN_SECRET_PATTERNS,
+  PII_PATTERNS,
+  type WorkerRequest,
+  type WorkerResponse,
+
+  // Worker Manager
+  WorkerManager,
+  getWorkerManager,
+  initializeWorkerManager,
+  destroyWorkerManager,
+  type WorkerStatus,
+  type WorkerManagerOptions,
+} from './worker';
+
+// ============================================================================
+// v1.1: AI Module (Context Builder, MCP Connector)
+// ============================================================================
+
+export {
+  // Context Builder
+  AIContextBuilder,
+  getContextBuilder,
+  resetContextBuilder,
+  type ContextBuilderOptions,
+  type UserAction,
+
+  // MCP Connector
+  MCPConnector,
+  getMCPConnector,
+  destroyMCPConnector,
+  type MCPConnectorOptions,
+  type MCPMessage,
+  type AnalysisRequest,
+  type AnalysisResponse,
+  type MCPConnectionStatus,
+} from './ai';

package/src/devtools/init.ts

@@ -0,0 +1,266 @@
+/**
+ * Mandu Kitchen DevTools - Initialization
+ * @version 1.1.0
+ *
+ * 통합 초기화 함수
+ */
+
+import type { DevToolsConfig } from './types';
+import { initializeHook } from './hook';
+import {
+  mountKitchen,
+  unmountKitchen,
+  initializeErrorCatcher,
+  destroyErrorCatcher,
+  initializeNetworkProxy,
+  destroyNetworkProxy,
+  initializePersistence,
+  destroyPersistence,
+  getStateManager,
+  getPersistenceManager,
+} from './client';
+import { initializeWorkerManager, destroyWorkerManager } from './worker';
+import { getContextBuilder, resetContextBuilder, getMCPConnector, destroyMCPConnector } from './ai';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface KitchenInstance {
+  /** DevTools 언마운트 및 정리 */
+  destroy: () => void;
+  /** 상태 관리자 접근 */
+  getState: () => any;
+  /** 에러 리포트 */
+  reportError: (error: Error | string) => void;
+  /** DevTools 열기 */
+  open: () => void;
+  /** DevTools 닫기 */
+  close: () => void;
+  /** DevTools 토글 */
+  toggle: () => void;
+}
+
+// ============================================================================
+// Initialization
+// ============================================================================
+
+let isInitialized = false;
+
+/**
+ * Mandu Kitchen DevTools 초기화
+ *
+ * @example
+ * ```typescript
+ * import { initManduKitchen } from '@mandu/core/devtools';
+ *
+ * // 앱 시작 시 초기화
+ * const kitchen = initManduKitchen({
+ *   position: 'bottom-right',
+ *   features: {
+ *     errorOverlay: true,
+ *     networkMonitor: true,
+ *   },
+ * });
+ *
+ * // 나중에 정리
+ * kitchen.destroy();
+ * ```
+ */
+export function initManduKitchen(config: DevToolsConfig = {}): KitchenInstance {
+  // Production 환경에서는 noop 반환
+  if (typeof process !== 'undefined' && process.env?.NODE_ENV === 'production') {
+    return createNoopInstance();
+  }
+
+  // 브라우저 환경이 아니면 noop 반환
+  if (typeof window === 'undefined') {
+    return createNoopInstance();
+  }
+
+  // 이미 초기화되었으면 기존 인스턴스 반환
+  if (isInitialized) {
+    console.warn('[Mandu Kitchen] Already initialized. Call destroy() first to reinitialize.');
+    return createInstance();
+  }
+
+  // 비활성화 설정이면 noop 반환
+  if (config.enabled === false) {
+    return createNoopInstance();
+  }
+
+  // 초기화 시작
+  try {
+    // 1. Hook 초기화
+    initializeHook();
+
+    // 2. Error Catcher 초기화
+    if (config.features?.errorOverlay !== false) {
+      initializeErrorCatcher();
+    }
+
+    // 3. Network Proxy 초기화
+    if (config.features?.networkMonitor !== false) {
+      initializeNetworkProxy({
+        bodyPolicy: {
+          collectBody: config.network?.collectBody ?? false,
+          optInPolicy: {
+            maxBytes: config.network?.bodyMaxBytes ?? 10_000,
+            applyPIIFilter: true,
+            applySecretFilter: true,
+            allowedContentTypes: ['application/json', 'text/plain', 'text/event-stream'],
+          },
+        },
+      });
+    }
+
+    // 4. Persistence 초기화
+    if (config.persistence?.enabled !== false) {
+      const persistence = initializePersistence(config.persistence);
+
+      // 저장된 이벤트 복원
+      const savedEvents = persistence.loadEvents();
+      if (savedEvents.length > 0) {
+        const stateManager = getStateManager(config);
+        for (const event of savedEvents) {
+          stateManager.handleEvent(event);
+        }
+      }
+    }
+
+    // 5. v1.1: Worker Manager 초기화 (백그라운드, 실패해도 계속)
+    initializeWorkerManager().catch((err) => {
+      console.warn('[Mandu Kitchen] Worker initialization failed, using main thread fallback:', err);
+    });
+
+    // 6. v1.1: AI Context Builder 초기화
+    const contextBuilder = getContextBuilder({ config });
+
+    // 7. UI 마운트
+    mountKitchen(config);
+
+    isInitialized = true;
+
+    console.log('[Mandu Kitchen] DevTools v1.1 initialized 🥟');
+
+    return createInstance();
+  } catch (error) {
+    console.error('[Mandu Kitchen] Initialization failed:', error);
+    return createNoopInstance();
+  }
+}
+
+/**
+ * DevTools 정리
+ */
+export function destroyManduKitchen(): void {
+  if (!isInitialized) return;
+
+  try {
+    // UI 언마운트
+    unmountKitchen();
+
+    // v1.0 모듈 정리
+    destroyErrorCatcher();
+    destroyNetworkProxy();
+    destroyPersistence();
+
+    // v1.1 모듈 정리
+    destroyWorkerManager();
+    resetContextBuilder();
+    destroyMCPConnector();
+
+    isInitialized = false;
+
+    console.log('[Mandu Kitchen] DevTools destroyed');
+  } catch (error) {
+    console.error('[Mandu Kitchen] Cleanup failed:', error);
+  }
+}
+
+// ============================================================================
+// Instance Factories
+// ============================================================================
+
+function createInstance(): KitchenInstance {
+  return {
+    destroy: destroyManduKitchen,
+
+    getState: () => getStateManager().getState(),
+
+    reportError: (error: Error | string) => {
+      const stateManager = getStateManager();
+      const message = typeof error === 'string' ? error : error.message;
+      const stack = typeof error === 'string' ? undefined : error.stack;
+
+      stateManager.addError({
+        id: `manual-${Date.now()}`,
+        type: 'runtime',
+        severity: 'error',
+        message,
+        stack,
+        timestamp: Date.now(),
+        url: window.location.href,
+      });
+    },
+
+    open: () => getStateManager().open(),
+    close: () => getStateManager().close(),
+    toggle: () => getStateManager().toggle(),
+  };
+}
+
+function createNoopInstance(): KitchenInstance {
+  return {
+    destroy: () => {},
+    getState: () => ({} as any),
+    reportError: () => {},
+    open: () => {},
+    close: () => {},
+    toggle: () => {},
+  };
+}
+
+// ============================================================================
+// Auto-initialization (optional)
+// ============================================================================
+
+/**
+ * 자동 초기화 (script 태그로 로드 시)
+ *
+ * HTML에서 사용:
+ * <script src="mandu-kitchen.js" data-auto-init data-position="bottom-left"></script>
+ */
+export function autoInit(): void {
+  if (typeof document === 'undefined') return;
+
+  // DOMContentLoaded 이후에 실행
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', () => {
+      checkAndInit();
+    });
+  } else {
+    checkAndInit();
+  }
+}
+
+function checkAndInit(): void {
+  // data-auto-init 속성이 있는 script 태그 찾기
+  const script = document.querySelector('script[data-mandu-kitchen-auto-init]');
+  if (!script) return;
+
+  const config: DevToolsConfig = {};
+
+  // data 속성에서 설정 읽기
+  const position = script.getAttribute('data-position');
+  if (position) {
+    config.position = position as DevToolsConfig['position'];
+  }
+
+  const theme = script.getAttribute('data-theme');
+  if (theme) {
+    config.theme = theme as DevToolsConfig['theme'];
+  }
+
+  initManduKitchen(config);
+}