@mandujs/core 0.18.20 → 0.18.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/core",
-  "version": "0.18.20",
+  "version": "0.18.21",
   "description": "Mandu Framework Core - Spec, Generator, Guard, Runtime",
   "type": "module",
   "main": "./src/index.ts",

package/src/brain/architecture/analyzer.ts

@@ -510,15 +510,13 @@ ${JSON.stringify(this.config.folders, null, 2)}
 짧고 명확하게 답변하세요 (3줄 이내).`;
 
     try {
-      const result = await brain.complete([
-        { role: "user", content: prompt },
-      ]);
+      const result = await brain.generate(prompt);
 
       // 응답에서 경로 추출 시도
-      const pathMatch = result.content.match(/(?:spec\/|\.mandu\/|app\/|src\/|packages\/)[^\s,)]+/);
+      const pathMatch = result.match(/(?:spec\/|\.mandu\/|app\/|src\/|packages\/)[^\s,)]+/);
 
       return {
-        suggestion: result.content,
+        suggestion: result,
         recommendedPath: pathMatch?.[0],
       };
     } catch {

package/src/brain/architecture/types.ts

@@ -39,7 +39,7 @@ export interface ImportRule {
 /**
  * 레이어 의존성 규칙
  */
-export interface LayerRule {
+export interface ArchLayerRule {
   /** 레이어 이름 */
   name: string;
   /** 레이어에 속하는 폴더 패턴 */
@@ -73,17 +73,17 @@ export interface ArchitectureConfig {
   /** Import 규칙 */
   imports?: ImportRule[];
   /** 레이어 규칙 */
-  layers?: LayerRule[];
+  layers?: ArchLayerRule[];
   /** 네이밍 규칙 */
   naming?: NamingRule[];
   /** 커스텀 규칙 */
-  custom?: CustomRule[];
+  custom?: ArchCustomRule[];
 }
 
 /**
  * 커스텀 규칙
  */
-export interface CustomRule {
+export interface ArchCustomRule {
   /** 규칙 ID */
   id: string;
   /** 규칙 설명 */

package/src/brain/doctor/index.ts

@@ -30,7 +30,7 @@ export {
 } from "./patcher";
 
 export {
-  formatViolation,
+  formatDoctorViolation,
   formatPatch,
   printDoctorReport,
   generateJsonReport,

package/src/brain/doctor/reporter.ts

@@ -50,7 +50,7 @@ function color(text: string, colorCode: string): string {
 /**
  * Format a violation for terminal output
  */
-export function formatViolation(violation: GuardViolation): string {
+export function formatDoctorViolation(violation: GuardViolation): string {
   const lines: string[] = [];
 
   const severity = violation.severity || "error";
@@ -137,7 +137,7 @@ export function printDoctorReport(analysis: DoctorAnalysis): void {
     console.log();
 
     for (const violation of violations) {
-      console.log(formatViolation(violation));
+      console.log(formatDoctorViolation(violation));
       console.log();
     }
   }

package/src/bundler/css.ts

@@ -11,6 +11,7 @@
 import { spawn, type Subprocess } from "bun";
 import path from "path";
 import fs from "fs/promises";
+import { watch as fsWatch, type FSWatcher } from "fs";
 
 // ========== Types ==========
 
@@ -223,12 +224,12 @@ export async function startCSSWatch(options: CSSBuildOptions): Promise<CSSWatche
 
   // 출력 파일 워처로 빌드 완료 감지 (stdout 패턴보다 신뢰성 높음, #111)
   // Tailwind CLI stdout 출력 형식은 버전마다 달라질 수 있으므로 파일 변경으로 감지
-  let fsWatcher: ReturnType<typeof fs.watch> | null = null;
+  let fsWatcher: FSWatcher | null = null;
   let lastMtime = 0;
 
   const startFileWatcher = () => {
     try {
-      fsWatcher = fs.watch(outputPath, () => {
+      fsWatcher = fsWatch(outputPath, () => {
         // 연속 이벤트 중복 방지 (50ms 이내 재발생 무시)
         const now = Date.now();
         if (now - lastMtime < 50) return;

package/src/config/validate.ts

@@ -13,7 +13,7 @@ import { readJsonFile } from "../utils/bun";
 function strictWithWarnings<T extends z.ZodRawShape>(
   schema: z.ZodObject<T>,
   schemaName: string
-): z.ZodObject<T> {
+): z.ZodEffects<z.ZodObject<T>> {
   return schema.superRefine((data, ctx) => {
     if (typeof data !== "object" || data === null) return;
 

package/src/contract/client.test.ts

@@ -6,7 +6,8 @@
 
 import { describe, it, expect, mock } from "bun:test";
 import { z } from "zod";
-import { Mandu, createClient, contractFetch } from "./index";
+import { Mandu } from "../index";
+import { createClient, contractFetch } from "./index";
 
 // === Test Contract ===
 const testContract = Mandu.contract({

package/src/contract/define.ts

@@ -126,19 +126,19 @@ export function isContract<T extends ContractDefinition>(
 
 /** Contract에서 Input 타입 추출 */
 export type ContractInput<
-  C extends Contract<any>,
+  C extends ContractMeta<ContractDefinition>,
   K extends keyof C['__endpoints']
 > = C['__endpoints'][K]['input'] extends ZodType<infer T> ? T : never;
 
 /** Contract에서 Output 타입 추출 */
 export type ContractOutput<
-  C extends Contract<any>,
+  C extends ContractMeta<ContractDefinition>,
   K extends keyof C['__endpoints']
 > = C['__endpoints'][K]['output'] extends ZodType<infer T> ? T : never;
 
 /** Contract에서 Params 타입 추출 */
 export type ContractParams<
-  C extends Contract<any>,
+  C extends ContractMeta<ContractDefinition>,
   K extends keyof C['__endpoints']
 > = C['__endpoints'][K]['params'] extends ZodType<infer T> ? T : never;
 

package/src/contract/index.ts

@@ -204,8 +204,5 @@ export const ManduContract = {
   fetch: contractFetch,
 } as const;
 
-/**
- * Alias for backward compatibility within contract module
- * 외부에서는 메인 index.ts의 Mandu를 사용하세요
- */
-export const Mandu = ManduContract;
+// Note: The unified `Mandu` namespace is defined in the main index.ts.
+// ManduContract is available for direct import from this module.

package/src/contract/infer.test.ts

@@ -9,7 +9,8 @@
 
 import { describe, it, expect } from "bun:test";
 import { z } from "zod";
-import { Mandu, type InferContract, type InferQuery, type InferBody, type InferResponse } from "./index";
+import { Mandu } from "../index";
+import type { InferContract, InferQuery, InferBody, InferResponse } from "./index";
 
 // === Test Schemas ===
 const UserSchema = z.object({

package/src/contract/normalize.ts

@@ -146,7 +146,7 @@ export function normalizeSchema<T extends ZodTypeAny>(
     return schema;
   }
 
-  return applyNormalizeMode(schema, opts.mode) as T;
+  return applyNormalizeMode(schema, opts.mode) as unknown as T;
 }
 
 /**

package/src/devtools/client/catchers/error-catcher.ts

@@ -5,7 +5,7 @@
  * 전역 에러를 캐치하여 DevTools로 전달
  */
 
-import type { NormalizedError, ErrorType, Severity } from '../../types';
+import type { NormalizedError, ErrorType, DevToolsSeverity } from '../../types';
 import { getOrCreateHook } from '../../hook';
 import { createErrorEvent } from '../../protocol';
 
@@ -69,7 +69,7 @@ function normalizeError(
   return {
     id: generateErrorId(),
     type,
-    severity: determineSeverity(type, error),
+    severity: determineDevToolsSeverity(type, error),
     message: isError ? error.message : String(error),
     stack: isError ? error.stack : undefined,
     timestamp: Date.now(),
@@ -78,7 +78,7 @@ function normalizeError(
   };
 }
 
-function determineSeverity(type: ErrorType, _error: unknown): Severity {
+function determineDevToolsSeverity(type: ErrorType, _error: unknown): DevToolsSeverity {
   switch (type) {
     case 'runtime':
     case 'unhandled':

package/src/devtools/client/components/kitchen-root.tsx

@@ -7,7 +7,7 @@
 
 import React, { useEffect, useState, useCallback, useMemo } from 'react';
 import { createRoot, type Root } from 'react-dom/client';
-import type { NormalizedError, DevToolsConfig, IslandSnapshot, NetworkRequest, GuardViolation } from '../../types';
+import type { NormalizedError, DevToolsConfig, IslandSnapshot, NetworkRequest, DevToolsGuardViolation } from '../../types';
 import { generateCSSVariables, testIds, zIndex } from '../../design-tokens';
 import { getStateManager, type KitchenState } from '../state-manager';
 import { getOrCreateHook } from '../../hook';
@@ -241,7 +241,7 @@ function KitchenApp({ config }: KitchenAppProps): React.ReactElement | null {
   }, []);
 
   const handleClearGuard = useCallback(() => {
-    getStateManager().clearGuardViolations();
+    getStateManager().clearDevToolsGuardViolations();
   }, []);
 
   const handleRestart = useCallback(async () => {

package/src/devtools/client/components/panel/guard-panel.tsx

@@ -4,7 +4,7 @@
  */
 
 import React, { useMemo } from 'react';
-import type { GuardViolation } from '../../../types';
+import type { DevToolsGuardViolation } from '../../../types';
 import { colors, typography, spacing, borderRadius, animation } from '../../../design-tokens';
 
 // ============================================================================
@@ -130,7 +130,7 @@ const severityStyles: Record<string, { border: string; bg: string; color: string
 // ============================================================================
 
 export interface GuardPanelProps {
-  violations: GuardViolation[];
+  violations: DevToolsGuardViolation[];
   onClear: () => void;
 }
 
@@ -141,7 +141,7 @@ export interface GuardPanelProps {
 export function GuardPanel({ violations, onClear }: GuardPanelProps): React.ReactElement {
   // Group by rule
   const groupedByRule = useMemo(() => {
-    const groups = new Map<string, GuardViolation[]>();
+    const groups = new Map<string, DevToolsGuardViolation[]>();
     for (const v of violations) {
       const existing = groups.get(v.ruleId) ?? [];
       groups.set(v.ruleId, [...existing, v]);

package/src/devtools/client/state-manager.ts

@@ -10,7 +10,7 @@ import type {
   NormalizedError,
   IslandSnapshot,
   NetworkRequest,
-  GuardViolation,
+  DevToolsGuardViolation,
   DevToolsConfig,
   ManduState,
 } from '../types';
@@ -30,7 +30,7 @@ export interface KitchenState {
   errors: NormalizedError[];
   islands: Map<string, IslandSnapshot>;
   networkRequests: Map<string, NetworkRequest>;
-  guardViolations: GuardViolation[];
+  guardViolations: DevToolsGuardViolation[];
 
   // Mandu Character State
   manduState: ManduState;
@@ -78,7 +78,7 @@ export class KitchenStateManager {
   private listeners: Set<StateListener> = new Set();
   private maxErrors = 100;
   private maxNetworkRequests = 200;
-  private maxGuardViolations = 50;
+  private maxDevToolsGuardViolations = 50;
 
   constructor(config?: Partial<DevToolsConfig>) {
     this.state = createInitialState(config);
@@ -104,7 +104,7 @@ export class KitchenStateManager {
     return Array.from(this.state.networkRequests.values());
   }
 
-  getGuardViolations(): GuardViolation[] {
+  getDevToolsGuardViolations(): DevToolsGuardViolation[] {
     return [...this.state.guardViolations];
   }
 
@@ -304,11 +304,11 @@ export class KitchenStateManager {
   // Guard Actions
   // --------------------------------------------------------------------------
 
-  addGuardViolation(violation: GuardViolation): void {
+  addDevToolsGuardViolation(violation: DevToolsGuardViolation): void {
     const guardViolations = [violation, ...this.state.guardViolations];
 
     // 최대 개수 제한
-    if (guardViolations.length > this.maxGuardViolations) {
+    if (guardViolations.length > this.maxDevToolsGuardViolations) {
       guardViolations.pop();
     }
 
@@ -321,7 +321,7 @@ export class KitchenStateManager {
     this.setState({ guardViolations, manduState });
   }
 
-  clearGuardViolations(ruleId?: string): void {
+  clearDevToolsGuardViolations(ruleId?: string): void {
     if (ruleId) {
       const guardViolations = this.state.guardViolations.filter(
         (v) => v.ruleId !== ruleId
@@ -395,11 +395,11 @@ export class KitchenStateManager {
         break;
 
       case 'guard:violation':
-        this.addGuardViolation(event.data as GuardViolation);
+        this.addDevToolsGuardViolation(event.data as DevToolsGuardViolation);
         break;
 
       case 'guard:clear':
-        this.clearGuardViolations((event.data as { ruleId?: string }).ruleId);
+        this.clearDevToolsGuardViolations((event.data as { ruleId?: string }).ruleId);
         break;
 
       case 'hmr:update':

package/src/devtools/index.ts

@@ -16,11 +16,11 @@ export type {
 
   // Error
   ErrorType,
-  Severity,
+  DevToolsSeverity,
   NormalizedError,
 
   // Island
-  HydrationStrategy,
+  DevToolsHydrationStrategy,
   IslandStatus,
   IslandSnapshot,
 
@@ -29,7 +29,7 @@ export type {
   NetworkBodyPolicy,
 
   // Guard
-  GuardViolation,
+  DevToolsGuardViolation,
 
   // AI Context
   CodeContextInfo,
@@ -170,7 +170,7 @@ export {
   createIslandHydrateEndEvent,
   createNetworkRequestEvent,
   createNetworkResponseEvent,
-  createGuardViolationEvent,
+  createDevToolsGuardViolationEvent,
   createHmrUpdateEvent,
   createHmrErrorEvent,
 
@@ -199,12 +199,12 @@ export {
 // ============================================================================
 
 import { getOrCreateHook } from './hook';
-import type { NormalizedError, GuardViolation } from './types';
+import type { NormalizedError, DevToolsGuardViolation } from './types';
 import {
   createErrorEvent,
   createHmrUpdateEvent,
   createHmrErrorEvent,
-  createGuardViolationEvent,
+  createDevToolsGuardViolationEvent,
 } from './protocol';
 
 /**
@@ -261,10 +261,10 @@ export function notifyHmrError(message: string, stack?: string): void {
  * Guard 위반 리포트 (간편 API)
  */
 export function reportGuardViolation(
-  violation: Omit<GuardViolation, 'id' | 'timestamp'>
+  violation: Omit<DevToolsGuardViolation, 'id' | 'timestamp'>
 ): void {
   const hook = getOrCreateHook();
-  hook.emit(createGuardViolationEvent(violation));
+  hook.emit(createDevToolsGuardViolationEvent(violation));
 }
 
 // ============================================================================

package/src/devtools/protocol.ts

@@ -8,7 +8,7 @@ import type {
   NormalizedError,
   IslandSnapshot,
   NetworkRequest,
-  GuardViolation,
+  DevToolsGuardViolation,
 } from './types';
 
 // ============================================================================
@@ -33,7 +33,7 @@ export type KitchenEvents =
   | KitchenEvent<'network:error', { id: string; error: string }>
 
   // Guard events
-  | KitchenEvent<'guard:violation', GuardViolation>
+  | KitchenEvent<'guard:violation', DevToolsGuardViolation>
   | KitchenEvent<'guard:clear', { ruleId?: string }>
 
   // HMR events
@@ -144,8 +144,8 @@ export function createNetworkResponseEvent(
   };
 }
 
-export function createGuardViolationEvent(
-  violation: Omit<GuardViolation, 'id' | 'timestamp'>
+export function createDevToolsGuardViolationEvent(
+  violation: Omit<DevToolsGuardViolation, 'id' | 'timestamp'>
 ): KitchenEvents {
   return {
     type: 'guard:violation',

package/src/devtools/types.ts

@@ -18,12 +18,12 @@ export interface KitchenEvent<T extends string = string, D = unknown> {
 // ============================================================================
 
 export type ErrorType = 'runtime' | 'unhandled' | 'react' | 'network' | 'hmr' | 'guard';
-export type Severity = 'critical' | 'error' | 'warning' | 'info';
+export type DevToolsSeverity = 'critical' | 'error' | 'warning' | 'info';
 
 export interface NormalizedError {
   id: string;
   type: ErrorType;
-  severity: Severity;
+  severity: DevToolsSeverity;
   message: string;
   stack?: string;
   source?: string;
@@ -39,13 +39,13 @@ export interface NormalizedError {
 // Island Types
 // ============================================================================
 
-export type HydrationStrategy = 'load' | 'idle' | 'visible' | 'media' | 'never';
+export type DevToolsHydrationStrategy = 'load' | 'idle' | 'visible' | 'media' | 'never';
 export type IslandStatus = 'ssr' | 'pending' | 'hydrating' | 'hydrated' | 'error';
 
 export interface IslandSnapshot {
   id: string;
   name: string;
-  strategy: HydrationStrategy;
+  strategy: DevToolsHydrationStrategy;
   status: IslandStatus;
   ssrRenderTime?: number;
   hydrateStartTime?: number;
@@ -89,7 +89,7 @@ export interface NetworkBodyPolicy {
 // Guard Types
 // ============================================================================
 
-export interface GuardViolation {
+export interface DevToolsGuardViolation {
   id: string;
   ruleId: string;
   ruleName: string;

package/src/filling/deps.ts

@@ -171,7 +171,10 @@ export function createMockDeps(overrides: Partial<FillingDeps> = {}): FillingDep
       set: asyncNoop,
       delete: asyncNoop,
     },
-    fetch: async () => new Response(),
+    fetch: Object.assign(
+      async (): Promise<Response> => new Response(),
+      { preconnect: (_url: string) => {} }
+    ) as typeof fetch,
     logger: {
       debug: noop,
       info: noop,

package/src/filling/filling.ts

@@ -361,7 +361,7 @@ export class ManduFilling<TLoaderData = unknown> {
       if (error instanceof ValidationError) {
         return ctx.json({ errorType: "LOGIC_ERROR", code: ErrorCode.SLOT_VALIDATION_ERROR, message: "Validation failed", summary: "입력 검증 실패 - 요청 데이터 확인 필요", fix: { file: routeContext ? `spec/slots/${routeContext.routeId}.slot.ts` : "spec/slots/", suggestion: "요청 데이터가 스키마와 일치하는지 확인하세요" }, route: routeContext, errors: error.errors, timestamp: new Date().toISOString() }, 400);
       }
-      const classifier = new ErrorClassifier(null, routeContext);
+      const classifier = new ErrorClassifier(null, routeContext ? { id: routeContext.routeId, pattern: routeContext.pattern } : undefined);
       const manduError = classifier.classify(error);
       console.error(`[Mandu] ${manduError.errorType}:`, manduError.message);
       const response = formatErrorResponse(manduError, { isDev: process.env.NODE_ENV !== "production" });

package/src/guard/index.ts

@@ -272,7 +272,7 @@ export {
   type SlotMetadata,
   type CustomRule,
   type ConstraintViolation,
-  type SlotValidationResult,
+  type SemanticSlotValidationResult,
 } from "./semantic-slots";
 
 // ═══════════════════════════════════════════════════════════════════════════

package/src/guard/presets/index.ts

@@ -11,6 +11,9 @@ import { hexagonalPreset, HEXAGONAL_HIERARCHY } from "./hexagonal";
 import { atomicPreset, ATOMIC_HIERARCHY } from "./atomic";
 import { cqrsPreset, CQRS_HIERARCHY } from "./cqrs";
 
+// Re-export types
+export type { GuardPreset, PresetDefinition } from "../types";
+
 // Re-export
 export { fsdPreset, FSD_HIERARCHY } from "./fsd";
 export { cleanPreset, CLEAN_HIERARCHY } from "./clean";

package/src/guard/semantic-slots.ts

@@ -144,7 +144,7 @@ export interface ConstraintViolation {
 /**
  * 슬롯 검증 결과
  */
-export interface SlotValidationResult {
+export interface SemanticSlotValidationResult {
   /** 유효 여부 */
   valid: boolean;
 
@@ -461,7 +461,7 @@ export async function validateSlotConstraints(
   filePath: string,
   constraints: SlotConstraints,
   rootDir?: string
-): Promise<SlotValidationResult> {
+): Promise<SemanticSlotValidationResult> {
   const violations: ConstraintViolation[] = [];
   const suggestions: string[] = [];
 
@@ -727,9 +727,9 @@ export async function validateSlots(
   totalSlots: number;
   validSlots: number;
   invalidSlots: number;
-  results: SlotValidationResult[];
+  results: SemanticSlotValidationResult[];
 }> {
-  const results: SlotValidationResult[] = [];
+  const results: SemanticSlotValidationResult[] = [];
 
   for (const filePath of slotFiles) {
     // 파일에서 메타데이터 추출 시도

package/src/index.ts

@@ -24,11 +24,19 @@ export * from "./devtools";
 export * from "./paths";
 export * from "./resource";
 
+// ── Resolve export * ambiguities (TS2308) ──
+// When the same name is exported from multiple submodules via `export *`,
+// TypeScript considers them ambiguous. Explicit re-exports resolve this.
+export { formatViolation } from "./guard";
+export { type HttpMethod } from "./filling";
+export { type GuardViolation } from "./guard";
+export { type Severity } from "./guard";
+
 // Consolidated Mandu namespace
 import { ManduFilling, ManduContext, ManduFillingFactory, createSSEConnection } from "./filling";
 import { createContract, defineHandler, defineRoute, createClient, contractFetch, createClientContract, querySchema, bodySchema, apiError } from "./contract";
 import { defineContract, generateAllFromContract, generateOpenAPISpec } from "./contract/define";
-import { island, isIsland, type IslandComponent, type HydrationStrategy } from "./island";
+import { island, isIsland, type IslandComponent, type IslandHydrationStrategy } from "./island";
 import { intent, isIntent, getIntentDocs, generateOpenAPIFromIntent } from "./intent";
 import { initializeHook, reportError, ManduDevTools, getStateManager } from "./devtools";
 import type { ContractDefinition, ContractInstance, ContractSchema } from "./contract";

package/src/island/index.ts

@@ -20,7 +20,7 @@ import { z } from 'zod';
 // ============================================================================
 
 /** 하이드레이션 타이밍 */
-export type HydrationStrategy =
+export type IslandHydrationStrategy =
   | 'load'      // 페이지 로드 즉시
   | 'idle'      // requestIdleCallback
   | 'visible'   // IntersectionObserver
@@ -30,7 +30,7 @@ export type HydrationStrategy =
 /** Island 옵션 */
 export interface IslandOptions<P = unknown> {
   /** 하이드레이션 전략 */
-  hydrate: HydrationStrategy;
+  hydrate: IslandHydrationStrategy;
   /** 미디어 쿼리 (hydrate: 'media' 일 때) */
   media?: string;
   /** SSR 폴백 컴포넌트 */
@@ -44,7 +44,7 @@ export interface IslandOptions<P = unknown> {
 /** Island 컴포넌트 메타데이터 */
 export interface IslandMeta {
   __island: true;
-  __hydrate: HydrationStrategy;
+  __hydrate: IslandHydrationStrategy;
   __media?: string;
   __fallback?: ReactNode;
   __name: string;
@@ -95,7 +95,7 @@ export function getAllIslands(): Map<string, IslandComponent<any>> {
  * });
  */
 export function island<P extends Record<string, unknown>>(
-  strategy: HydrationStrategy,
+  strategy: IslandHydrationStrategy,
   Component: ComponentType<P>
 ): IslandComponent<P>;
 
@@ -105,7 +105,7 @@ export function island<P extends Record<string, unknown>>(
 ): IslandComponent<P>;
 
 export function island<P extends Record<string, unknown>>(
-  strategyOrOptions: HydrationStrategy | IslandOptions<P>,
+  strategyOrOptions: IslandHydrationStrategy | IslandOptions<P>,
   Component: ComponentType<P>
 ): IslandComponent<P> {
   const options: IslandOptions<P> = typeof strategyOrOptions === 'string'
@@ -194,7 +194,7 @@ export function deserializeIslandProps(json: string): Record<string, unknown> {
 export interface IslandPlaceholderProps {
   name: string;
   props: Record<string, unknown>;
-  hydrate: HydrationStrategy;
+  hydrate: IslandHydrationStrategy;
   media?: string;
   fallback?: ReactNode;
 }

package/src/plugins/index.ts

@@ -24,7 +24,7 @@ export type {
   GuardPresetPlugin,
   GuardRule,
   GuardRuleContext,
-  GuardViolation,
+  PluginGuardViolation,
   LayerDefinition,
   ImportInfo,
   ExportInfo,

package/src/plugins/types.ts

@@ -174,7 +174,7 @@ export interface GuardRule {
   name: string;
   description?: string;
   severity: "error" | "warn" | "off";
-  check: (context: GuardRuleContext) => GuardViolation[];
+  check: (context: GuardRuleContext) => PluginGuardViolation[];
 }
 
 /**
@@ -211,7 +211,7 @@ export interface ExportInfo {
 /**
  * Guard 위반
  */
-export interface GuardViolation {
+export interface PluginGuardViolation {
   ruleId: string;
   message: string;
   severity: "error" | "warn";

package/src/router/fs-routes.ts

@@ -21,7 +21,7 @@ import { loadManduConfig } from "../config";
 /**
  * 매니페스트 생성 결과
  */
-export interface GenerateResult {
+export interface FSGenerateResult {
   /** 생성된 매니페스트 */
   manifest: RoutesManifest;
 
@@ -176,7 +176,7 @@ async function resolveScannerConfig(
 export async function generateManifest(
   rootDir: string,
   options: GenerateOptions = {}
-): Promise<GenerateResult> {
+): Promise<FSGenerateResult> {
   const scannerConfig = await resolveScannerConfig(rootDir, options.scanner);
 
   // FS Routes 스캔
@@ -215,7 +215,7 @@ export async function generateManifest(
 /**
  * 라우트 변경 콜백
  */
-export type RouteChangeCallback = (result: GenerateResult) => void | Promise<void>;
+export type RouteChangeCallback = (result: FSGenerateResult) => void | Promise<void>;
 
 /**
  * FS Routes 감시자 인터페이스
@@ -225,7 +225,7 @@ export interface FSRoutesWatcher {
   close(): void;
 
   /** 수동 재스캔 */
-  rescan(): Promise<GenerateResult>;
+  rescan(): Promise<FSGenerateResult>;
 }
 
 /**
@@ -281,7 +281,7 @@ export async function watchFSRoutes(
 
   let debounceTimer: ReturnType<typeof setTimeout> | null = null;
 
-  const triggerRescan = async (): Promise<GenerateResult> => {
+  const triggerRescan = async (): Promise<FSGenerateResult> => {
     const result = await generateManifest(rootDir, generateOptions);
     if (onChange) {
       await onChange(result);

package/src/router/fs-types.ts

@@ -6,7 +6,7 @@
  * @module router/fs-types
  */
 
-import type { RouteKind, HydrationConfig, HttpMethod } from "../spec/schema";
+import type { RouteKind, HydrationConfig, SpecHttpMethod } from "../spec/schema";
 
 // ═══════════════════════════════════════════════════════════════════════════
 // Segment Types
@@ -93,7 +93,7 @@ export interface FSRouteConfig {
   kind: RouteKind;
 
   /** HTTP 메서드 (API 라우트용) */
-  methods?: HttpMethod[];
+  methods?: SpecHttpMethod[];
 
   /** 페이지 컴포넌트 모듈 경로 */
   componentModule?: string;

package/src/router/index.ts

@@ -69,7 +69,7 @@ export {
 export { FSScanner, createFSScanner, scanRoutes } from "./fs-scanner";
 
 // Generator
-export type { GenerateResult, GenerateOptions, RouteChangeCallback, FSRoutesWatcher } from "./fs-routes";
+export type { FSGenerateResult, GenerateOptions, RouteChangeCallback, FSRoutesWatcher } from "./fs-routes";
 
 export {
   fsRouteToRouteSpec,

package/src/runtime/boundary.tsx

@@ -57,7 +57,7 @@ interface ErrorBoundaryState {
  * </LoadingBoundary>
  * ```
  */
-export function LoadingBoundary({ fallback, children }: LoadingBoundaryProps): JSX.Element {
+export function LoadingBoundary({ fallback, children }: LoadingBoundaryProps): React.ReactElement {
   return <Suspense fallback={fallback}>{children}</Suspense>;
 }
 
@@ -127,7 +127,7 @@ export class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundarySt
 /**
  * 기본 로딩 컴포넌트
  */
-export function DefaultLoading(): JSX.Element {
+export function DefaultLoading(): React.ReactElement {
   return (
     <div
       style={{
@@ -146,7 +146,7 @@ export function DefaultLoading(): JSX.Element {
 /**
  * 기본 에러 컴포넌트
  */
-export function DefaultError({ error, resetError }: ErrorFallbackProps): JSX.Element {
+export function DefaultError({ error, resetError }: ErrorFallbackProps): React.ReactElement {
   return (
     <div
       style={{
@@ -220,7 +220,7 @@ export function PageBoundary({
   errorComponent,
   children,
   onError,
-}: PageBoundaryProps): JSX.Element {
+}: PageBoundaryProps): React.ReactElement {
   const LoadingFallback = loadingComponent ?? <DefaultLoading />;
   const ErrorFallback = errorComponent ?? DefaultError;
 

package/src/runtime/server.ts

@@ -1,5 +1,5 @@
 import type { Server } from "bun";
-import type { RoutesManifest } from "../spec/schema";
+import type { RoutesManifest, HydrationConfig } from "../spec/schema";
 import type { BundleManifest } from "../bundler/types";
 import type { ManduFilling } from "../filling/filling";
 import { ManduContext } from "../filling/context";
@@ -304,7 +304,7 @@ export interface ServerOptions {
 }
 
 export interface ManduServer {
-  server: Server;
+  server: Server<undefined>;
   router: Router;
   /** 이 서버 인스턴스의 레지스트리 */
   registry: ServerRegistry;
@@ -659,7 +659,7 @@ async function wrapWithLayouts(
   for (let i = layouts.length - 1; i >= 0; i--) {
     const Layout = layouts[i];
     if (Layout) {
-      wrapped = React.createElement(Layout, { params }, wrapped);
+      wrapped = React.createElement(Layout, { params, children: wrapped });
     }
   }
 
@@ -916,14 +916,14 @@ async function loadPageData(
   if (loader) {
     try {
       const module = await loader();
-      const exported = module.default;
+      const exported: unknown = module.default;
       const component = typeof exported === "function"
-        ? exported
-        : exported?.component ?? exported;
-      registry.registerRouteComponent(route.id, component);
+        ? (exported as RouteComponent)
+        : (exported as any)?.component ?? exported;
+      registry.registerRouteComponent(route.id, component as RouteComponent);
 
       // filling이 있으면 loader 실행
-      const filling = typeof exported === "object" ? exported?.filling : null;
+      const filling = typeof exported === "object" && exported !== null ? (exported as any)?.filling : null;
       if (filling?.hasLoader?.()) {
         const ctx = new ManduContext(req, params);
         loaderData = await filling.executeLoader(ctx);
@@ -948,7 +948,7 @@ async function loadPageData(
  * SSR 렌더링 (Streaming/Non-streaming)
  */
 async function renderPageSSR(
-  route: { id: string; pattern: string; layoutChain?: string[]; streaming?: boolean; hydration?: unknown },
+  route: { id: string; pattern: string; layoutChain?: string[]; streaming?: boolean; hydration?: HydrationConfig },
   params: Record<string, string>,
   loaderData: unknown,
   url: string,
@@ -1041,7 +1041,7 @@ async function renderPageSSR(
 async function handlePageRoute(
   req: Request,
   url: URL,
-  route: { id: string; pattern: string; layoutChain?: string[]; streaming?: boolean; hydration?: unknown },
+  route: { id: string; pattern: string; layoutChain?: string[]; streaming?: boolean; hydration?: HydrationConfig },
   params: Record<string, string>,
   registry: ServerRegistry
 ): Promise<Result<Response>> {
@@ -1084,7 +1084,7 @@ async function handleRequestInternal(
 
   // 0. CORS Preflight 요청 처리
   if (settings.cors && isPreflightRequest(req)) {
-    const corsOptions = settings.cors === true ? {} : settings.cors;
+    const corsOptions: CorsOptions = typeof settings.cors === 'object' ? settings.cors : {};
     return ok(handlePreflightRequest(req, corsOptions));
   }
 
@@ -1092,7 +1092,7 @@ async function handleRequestInternal(
   const staticResponse = await serveStaticFile(pathname, settings);
   if (staticResponse) {
     if (settings.cors && isCorsRequest(req)) {
-      const corsOptions = settings.cors === true ? {} : settings.cors;
+      const corsOptions: CorsOptions = typeof settings.cors === 'object' ? settings.cors : {};
       return ok(applyCorsToResponse(staticResponse, req, corsOptions));
     }
     return ok(staticResponse);
@@ -1158,7 +1158,7 @@ function startBunServerWithFallback(options: {
   port: number;
   hostname?: string;
   fetch: (req: Request) => Promise<Response>;
-}): { server: Server; port: number; attempts: number } {
+}): { server: Server<undefined>; port: number; attempts: number } {
   const { port: startPort, hostname, fetch } = options;
   let lastError: unknown = null;
 

package/src/runtime/ssr.ts

@@ -184,7 +184,7 @@ export function renderToHTML(element: ReactElement, options: SSROptions = {}): s
   // CSS 링크 태그 생성
   // - cssPath가 string이면 해당 경로 사용
   // - cssPath가 false 또는 undefined이면 링크 미삽입 (404 방지)
-  const cssLinkTag = cssPath && cssPath !== false
+  const cssLinkTag = cssPath
     ? `<link rel="stylesheet" href="${escapeHtmlAttr(`${cssPath}${isDev ? `?t=${Date.now()}` : ""}`)}">`
     : "";
 

package/src/runtime/streaming-ssr.ts

@@ -378,7 +378,7 @@ function generateHTMLShell(options: StreamingSSROptions): string {
   // CSS 링크 태그 생성
   // - cssPath가 string이면 해당 경로 사용
   // - cssPath가 false 또는 undefined이면 링크 미삽입 (404 방지)
-  const cssLinkTag = cssPath && cssPath !== false
+  const cssLinkTag = cssPath
     ? `<link rel="stylesheet" href="${escapeHtmlAttr(`${cssPath}${isDev ? `?t=${Date.now()}` : ""}`)}">`
     : "";
 
@@ -748,7 +748,7 @@ export async function renderToStream(
 
   async function readWithTimeout(): Promise<ReadableStreamReadResult<Uint8Array> | null> {
     if (!deadline) {
-      return reader.read();
+      return reader.read() as Promise<ReadableStreamReadResult<Uint8Array>>;
     }
 
     const remaining = deadline - Date.now();
@@ -763,8 +763,8 @@ export async function renderToStream(
 
     const readPromise = reader
       .read()
-      .then((result) => ({ kind: "read" as const, result }))
-      .catch((error) => ({ kind: "error" as const, error }));
+      .then((result) => ({ kind: "read" as const, result: result as ReadableStreamReadResult<Uint8Array> }))
+      .catch((error: unknown) => ({ kind: "error" as const, error }));
 
     const result = await Promise.race([readPromise, timeoutPromise]);
 

package/src/seo/integration/ssr.ts

@@ -119,12 +119,12 @@ export function resolveSEOSync(staticMetadata: Metadata): SEOResult {
     } else if ('absolute' in staticMetadata.title) {
       resolvedTitle = {
         absolute: staticMetadata.title.absolute,
-        template: staticMetadata.title.template || null,
+        template: staticMetadata.title.template ?? null,
       }
     } else if ('default' in staticMetadata.title) {
       resolvedTitle = {
         absolute: staticMetadata.title.default,
-        template: staticMetadata.title.template || null,
+        template: staticMetadata.title.template ?? null,
       }
     }
   }

package/src/seo/render/basic.ts

@@ -212,7 +212,9 @@ export function renderIcons(metadata: ResolvedMetadata): string {
 
   // icon
   for (const icon of icons.icon) {
-    const attrs = [`rel="icon"`, `href="${escapeHtml(urlToString(icon.url))}"`]
+    const iconUrl = urlToString(icon.url)
+    if (!iconUrl) continue
+    const attrs = [`rel="icon"`, `href="${escapeHtml(iconUrl)}"`]
     if (icon.type) attrs.push(`type="${escapeHtml(icon.type)}"`)
     if (icon.sizes) attrs.push(`sizes="${escapeHtml(icon.sizes)}"`)
     tags.push(`<link ${attrs.join(' ')} />`)
@@ -220,19 +222,25 @@ export function renderIcons(metadata: ResolvedMetadata): string {
 
   // apple-touch-icon
   for (const icon of icons.apple) {
-    const attrs = [`rel="apple-touch-icon"`, `href="${escapeHtml(urlToString(icon.url))}"`]
+    const iconUrl = urlToString(icon.url)
+    if (!iconUrl) continue
+    const attrs = [`rel="apple-touch-icon"`, `href="${escapeHtml(iconUrl)}"`]
     if (icon.sizes) attrs.push(`sizes="${escapeHtml(icon.sizes)}"`)
     tags.push(`<link ${attrs.join(' ')} />`)
   }
 
   // shortcut icon
   for (const icon of icons.shortcut) {
-    tags.push(`<link rel="shortcut icon" href="${escapeHtml(urlToString(icon.url))}" />`)
+    const iconUrl = urlToString(icon.url)
+    if (!iconUrl) continue
+    tags.push(`<link rel="shortcut icon" href="${escapeHtml(iconUrl)}" />`)
   }
 
   // other icons
   for (const icon of icons.other) {
-    const attrs = [`href="${escapeHtml(urlToString(icon.url))}"`]
+    const iconUrl = urlToString(icon.url)
+    if (!iconUrl) continue
+    const attrs = [`href="${escapeHtml(iconUrl)}"`]
     if (icon.rel) attrs.push(`rel="${escapeHtml(icon.rel)}"`)
     if (icon.type) attrs.push(`type="${escapeHtml(icon.type)}"`)
     if (icon.sizes) attrs.push(`sizes="${escapeHtml(icon.sizes)}"`)

package/src/seo/render/opengraph.ts

@@ -69,9 +69,11 @@ export function renderOpenGraph(metadata: ResolvedMetadata): string {
   // Images
   if (openGraph.images) {
     for (const image of openGraph.images) {
-      tags.push(og('image', urlToString(image.url)))
+      const imageUrl = urlToString(image.url)
+      if (imageUrl) tags.push(og('image', imageUrl))
       if (image.secureUrl) {
-        tags.push(og('image:secure_url', urlToString(image.secureUrl)))
+        const secureUrl = urlToString(image.secureUrl)
+        if (secureUrl) tags.push(og('image:secure_url', secureUrl))
       }
       if (image.type) {
         tags.push(og('image:type', image.type))
@@ -91,9 +93,11 @@ export function renderOpenGraph(metadata: ResolvedMetadata): string {
   // Videos
   if (openGraph.videos) {
     for (const video of openGraph.videos) {
-      tags.push(og('video', urlToString(video.url)))
+      const videoUrl = urlToString(video.url)
+      if (videoUrl) tags.push(og('video', videoUrl))
       if (video.secureUrl) {
-        tags.push(og('video:secure_url', urlToString(video.secureUrl)))
+        const secureUrl = urlToString(video.secureUrl)
+        if (secureUrl) tags.push(og('video:secure_url', secureUrl))
       }
       if (video.type) {
         tags.push(og('video:type', video.type))
@@ -110,9 +114,11 @@ export function renderOpenGraph(metadata: ResolvedMetadata): string {
   // Audio
   if (openGraph.audio) {
     for (const audio of openGraph.audio) {
-      tags.push(og('audio', urlToString(audio.url)))
+      const audioUrl = urlToString(audio.url)
+      if (audioUrl) tags.push(og('audio', audioUrl))
       if (audio.secureUrl) {
-        tags.push(og('audio:secure_url', urlToString(audio.secureUrl)))
+        const secureUrl = urlToString(audio.secureUrl)
+        if (secureUrl) tags.push(og('audio:secure_url', secureUrl))
       }
       if (audio.type) {
         tags.push(og('audio:type', audio.type))

package/src/seo/render/twitter.ts

@@ -68,14 +68,15 @@ export function renderTwitter(metadata: ResolvedMetadata): string {
   if (tw.images) {
     for (let i = 0; i < tw.images.length; i++) {
       const image = tw.images[i]
+      const imageUrl = urlToString(image.url)
       if (i === 0) {
-        tags.push(twitter('image', urlToString(image.url)))
+        if (imageUrl) tags.push(twitter('image', imageUrl))
         if (image.alt) {
           tags.push(twitter('image:alt', image.alt))
         }
       } else {
         // Multiple images (for galleries)
-        tags.push(twitter(`image${i}`, urlToString(image.url)))
+        if (imageUrl) tags.push(twitter(`image${i}`, imageUrl))
         if (image.alt) {
           tags.push(twitter(`image${i}:alt`, image.alt))
         }

package/src/spec/schema.ts

@@ -2,8 +2,8 @@ import { z } from "zod";
 
 // ========== Hydration 설정 ==========
 
-export const HydrationStrategy = z.enum(["none", "island", "full", "progressive"]);
-export type HydrationStrategy = z.infer<typeof HydrationStrategy>;
+export const SpecHydrationStrategy = z.enum(["none", "island", "full", "progressive"]);
+export type SpecHydrationStrategy = z.infer<typeof SpecHydrationStrategy>;
 
 export const HydrationPriority = z.enum(["immediate", "visible", "idle", "interaction"]);
 export type HydrationPriority = z.infer<typeof HydrationPriority>;
@@ -16,7 +16,7 @@ export const HydrationConfig = z.object({
    * - full: 전체 페이지 hydrate
    * - progressive: 점진적 hydrate
    */
-  strategy: HydrationStrategy,
+  strategy: SpecHydrationStrategy,
 
   /**
    * Hydration 우선순위
@@ -56,8 +56,8 @@ export type LoaderConfig = z.infer<typeof LoaderConfig>;
 export const RouteKind = z.enum(["page", "api"]);
 export type RouteKind = z.infer<typeof RouteKind>;
 
-export const HttpMethod = z.enum(["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD"]);
-export type HttpMethod = z.infer<typeof HttpMethod>;
+export const SpecHttpMethod = z.enum(["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD"]);
+export type SpecHttpMethod = z.infer<typeof SpecHttpMethod>;
 
 export const RouteSpec = z
   .object({
@@ -66,7 +66,7 @@ export const RouteSpec = z
     kind: RouteKind,
 
     // HTTP 메서드 (API용)
-    methods: z.array(HttpMethod).optional(),
+    methods: z.array(SpecHttpMethod).optional(),
 
     // 서버 모듈 (generated route handler)
     module: z.string().min(1, "module 경로는 필수입니다"),

package/src/utils/hasher.ts

@@ -25,7 +25,7 @@ export interface HashOptions {
   exclude?: string[];
 }
 
-export interface NormalizeOptions {
+export interface HashNormalizeOptions {
   /** 제외할 키 패턴 */
   exclude?: string[];
   /** Date를 ISO 문자열로 변환 (기본값: true) */
@@ -59,7 +59,7 @@ export interface NormalizeOptions {
  */
 export function normalizeForHash(
   value: unknown,
-  options: NormalizeOptions = {},
+  options: HashNormalizeOptions = {},
   seen: WeakSet<object> = new WeakSet()
 ): unknown {
   const {

package/src/utils/index.ts

@@ -14,7 +14,7 @@ export {
   isHashable,
   getHashInfo,
   type HashOptions,
-  type NormalizeOptions,
+  type HashNormalizeOptions,
 } from "./hasher.js";
 
 // Diff

package/src/watcher/watcher.ts

@@ -157,8 +157,8 @@ export class FileWatcher {
       this.processFileEvent("delete", filePath);
     });
 
-    this.chokidarWatcher.on("error", (error) => {
-      console.error(`[Watch] Error:`, error.message);
+    this.chokidarWatcher.on("error", (error: unknown) => {
+      console.error(`[Watch] Error:`, error instanceof Error ? error.message : String(error));
     });
 
     this._active = true;