@mandujs/core 0.18.20 → 0.18.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/core",
-  "version": "0.18.20",
+  "version": "0.18.22",
   "description": "Mandu Framework Core - Spec, Generator, Guard, Runtime",
   "type": "module",
   "main": "./src/index.ts",
@@ -8,6 +8,8 @@
   "exports": {
     ".": "./src/index.ts",
     "./client": "./src/client/index.ts",
+    "./plugins": "./src/plugins/index.ts",
+    "./error": "./src/error/index.ts",
     "./*": "./src/*"
   },
   "files": [

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/analyzer.ts

@@ -224,6 +224,7 @@ export function generateTemplatePatches(
               file: violation.file,
               description: violation.suggestion,
               type: "modify",
+              content: "",
               confidence: 0.4,
             });
           }

package/src/brain/doctor/index.ts

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

package/src/brain/doctor/patcher.ts

@@ -66,7 +66,7 @@ export function deduplicatePatches(patches: PatchSuggestion[]): PatchSuggestion[
   const result: PatchSuggestion[] = [];
 
   for (const patch of patches) {
-    const key = `${patch.file}:${patch.type}:${patch.command || ""}`;
+    const key = `${patch.file}:${patch.type}:${patch.type === "command" ? patch.command : ""}`;
     if (!seen.has(key)) {
       seen.add(key);
       result.push(patch);
@@ -103,8 +103,10 @@ export function generatePatchDescription(patch: PatchSuggestion): string {
     case "delete":
       return `[파일 삭제] ${patch.file}\n  설명: ${patch.description}\n  신뢰도: ${confidenceLabel}`;
 
-    default:
-      return `[${patch.type}] ${patch.file}\n  설명: ${patch.description}`;
+    default: {
+      const _exhaustive: never = patch;
+      return `[unknown] ${(_exhaustive as PatchSuggestion).file}\n  설명: ${(_exhaustive as PatchSuggestion).description}`;
+    }
   }
 }
 
@@ -229,12 +231,14 @@ export async function applyPatch(
         }
       }
 
-      default:
+      default: {
+        const _exhaustive: never = patch;
         return {
           applied: false,
-          patch,
-          error: `Unknown patch type: ${patch.type}`,
+          patch: _exhaustive as PatchSuggestion,
+          error: `Unknown patch type`,
         };
+      }
     }
   } catch (error) {
     return {

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();
     }
   }
@@ -210,7 +210,7 @@ export function generateJsonReport(analysis: DoctorAnalysis): string {
         file: p.file,
         type: p.type,
         description: p.description,
-        command: p.command,
+        ...(p.type === "command" ? { command: p.command } : {}),
         confidence: p.confidence,
       })),
       nextCommand: analysis.nextCommand,
@@ -281,7 +281,7 @@ export function generateDoctorMarkdownReport(analysis: DoctorAnalysis): string {
       lines.push(`- **대상**: \`${p.file}\``);
       lines.push(`- **신뢰도**: ${confidenceLabel}`);
 
-      if (p.command) {
+      if (p.type === "command") {
         lines.push("");
         lines.push("```bash");
         lines.push(p.command);

package/src/brain/types.ts

@@ -73,25 +73,29 @@ export interface AdapterConfig {
 // ========== Doctor Types ==========
 
 /**
- * Patch suggestion from Doctor
+ * Patch suggestion from Doctor (discriminated union by type)
+ *
+ * type별로 필요한 필드가 타입 레벨에서 강제됨:
+ * - add: content 필수
+ * - modify: content 필수, line optional
+ * - delete: file + confidence만 필요
+ * - command: command 필수
  */
-export interface PatchSuggestion {
+interface PatchSuggestionBase {
   /** Target file path */
   file: string;
   /** Description of the change */
   description: string;
-  /** Type of patch */
-  type: "add" | "modify" | "delete" | "command";
-  /** Content to add/modify (for add/modify types) */
-  content?: string;
-  /** Line number to modify (for modify type) */
-  line?: number;
-  /** Command to run (for command type) */
-  command?: string;
   /** Confidence level (0-1) */
   confidence: number;
 }
 
+export type PatchSuggestion =
+  | (PatchSuggestionBase & { type: "add"; content: string })
+  | (PatchSuggestionBase & { type: "modify"; content: string; line?: number })
+  | (PatchSuggestionBase & { type: "delete" })
+  | (PatchSuggestionBase & { type: "command"; command: string });
+
 /**
  * Doctor analysis result
  */

package/src/bundler/build.ts

@@ -929,14 +929,15 @@ async function buildRuntime(
       outputPath: `/.mandu/client/${outputName}`,
       errors: [],
     };
-  } catch (error: any) {
+  } catch (error: unknown) {
     // 예외 발생 시에도 디버깅을 위해 소스 파일을 남겨둠
     const extra: string[] = [];
-    if (error?.errors && Array.isArray(error.errors)) {
-      extra.push(...error.errors.map((e: any) => String(e?.message || e)));
+    const errObj = error as Record<string, unknown> | null;
+    if (errObj && Array.isArray(errObj.errors)) {
+      extra.push(...errObj.errors.map((e: unknown) => String((e as Record<string, unknown>)?.message || e)));
     }
-    if (error?.logs && Array.isArray(error.logs)) {
-      extra.push(...error.logs.map((l: any) => String(l?.message || l)));
+    if (errObj && Array.isArray(errObj.logs)) {
+      extra.push(...errObj.logs.map((l: unknown) => String((l as Record<string, unknown>)?.message || l)));
     }
 
     return {
@@ -1328,19 +1329,18 @@ export async function buildClientBundles(
   }
 
   // 3-4. Runtime, Router, Vendor, DevTools 번들 병렬 빌드 (서로 독립적)
-  const buildPromises: Promise<any>[] = [
-    buildRuntime(outDir, options),
-    buildRouterRuntime(outDir, options),
-    buildVendorShims(outDir, options),
-  ];
-
-  // DevTools 번들은 dev 모드에서만 빌드
   const isDev = env === "development";
-  if (isDev) {
-    buildPromises.push(buildDevtoolsBundle(outDir, options));
-  }
-
-  const [runtimeResult, routerResult, vendorResult, devtoolsResult] = await Promise.all(buildPromises);
+  const runtimePromise = buildRuntime(outDir, options);
+  const routerPromise = buildRouterRuntime(outDir, options);
+  const vendorPromise = buildVendorShims(outDir, options);
+  const devtoolsPromise = isDev ? buildDevtoolsBundle(outDir, options) : null;
+
+  const [runtimeResult, routerResult, vendorResult, devtoolsResult] = await Promise.all([
+    runtimePromise,
+    routerPromise,
+    vendorPromise,
+    devtoolsPromise,
+  ]);
 
   if (!runtimeResult.success) {
     errors.push(...runtimeResult.errors.map((e: string) => `[Runtime] ${e}`));

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/bundler/dev.ts

@@ -396,7 +396,7 @@ export interface HMRMessage {
  * HMR WebSocket 서버 생성
  */
 export function createHMRServer(port: number): HMRServer {
-  const clients = new Set<any>();
+  const clients = new Set<{ send: (data: string) => void; close: () => void }>();
   const hmrPort = port + PORTS.HMR_OFFSET;
   let restartHandler: (() => Promise<void>) | null = null;
 

package/src/client/island.ts

@@ -3,8 +3,8 @@
  * Hydration을 위한 클라이언트 사이드 컴포넌트 정의
  */
 
-import type { ReactNode } from "react";
-import { getServerData as getGlobalServerData } from "./window-state";
+import type { ReactNode } from "react";
+import { getServerData as getGlobalServerData } from "./window-state";
 
 /**
  * Island 정의 타입
@@ -118,12 +118,12 @@ export function island<TServerData, TSetupResult = TServerData>(
  * SSR 데이터에 안전하게 접근하는 훅
  * 서버 데이터가 없는 경우 fallback 반환
  */
-export function useServerData<T>(key: string, fallback: T): T {
-  if (typeof window === "undefined") return fallback;
-
-  const data = getGlobalServerData<T>(key);
-  return data === undefined ? fallback : data;
-}
+export function useServerData<T>(key: string, fallback: T): T {
+  if (typeof window === "undefined") return fallback;
+
+  const data = getGlobalServerData<T>(key);
+  return data === undefined ? fallback : data;
+}
 
 /**
  * Hydration 상태를 추적하는 훅
@@ -171,7 +171,7 @@ export function useIslandEvent<T = unknown>(
   handler: (data: T) => void
 ): IslandEventHandle<T>["emit"] & IslandEventHandle<T> {
   if (typeof window === "undefined") {
-    const noop = (() => {}) as IslandEventHandle<T>["emit"] & IslandEventHandle<T>;
+    const noop = (() => {}) as unknown as IslandEventHandle<T>["emit"] & IslandEventHandle<T>;
     noop.emit = noop;
     noop.cleanup = () => {};
     return noop;
@@ -473,6 +473,7 @@ export interface PartialGroup {
  * ```
  */
 export function createPartialGroup(): PartialGroup {
+  // React ComponentType variance requires `any` for heterogeneous component storage
   const partials = new Map<string, CompiledPartial<any>>();
 
   return {

package/src/client/router.ts

@@ -421,7 +421,7 @@ export function cleanupRouter(): void {
 
   window.removeEventListener("popstate", handlePopState);
   document.removeEventListener("click", handleLinkClick);
-  listeners.clear();
+  listeners.current.clear();
   initialized = false;
 }
 

package/src/config/mcp-ref.ts

@@ -17,7 +17,7 @@
  */
 
 import { z } from "zod";
-import { withMetadata, withMetadataMultiple } from "./metadata.js";
+import { withMetadata, withMetadataMultiple, getMetadata, hasMetadata } from "./metadata.js";
 import {
   SCHEMA_REFERENCE,
   SENSITIVE_FIELD,
@@ -313,7 +313,7 @@ export function createMcpServerSchemaWithSecrets() {
  * 스키마가 MCP 서버 참조인지 확인
  */
 export function isMcpServerRef(schema: z.ZodType): boolean {
-  const ref = (schema as any)[SCHEMA_REFERENCE] as SchemaReferenceMetadata | undefined;
+  const ref = getMetadata(schema, SCHEMA_REFERENCE);
   return ref?.type === "mcpServer";
 }
 
@@ -321,7 +321,7 @@ export function isMcpServerRef(schema: z.ZodType): boolean {
  * 스키마에서 MCP 서버 이름 추출
  */
 export function getMcpServerName(schema: z.ZodType): string | undefined {
-  const ref = (schema as any)[SCHEMA_REFERENCE] as SchemaReferenceMetadata | undefined;
+  const ref = getMetadata(schema, SCHEMA_REFERENCE);
   return ref?.type === "mcpServer" ? ref.name : undefined;
 }
 
@@ -329,20 +329,20 @@ export function getMcpServerName(schema: z.ZodType): string | undefined {
  * 스키마가 민감 필드인지 확인
  */
 export function isSensitiveField(schema: z.ZodType): boolean {
-  return SENSITIVE_FIELD in (schema as any);
+  return hasMetadata(schema, SENSITIVE_FIELD);
 }
 
 /**
  * 스키마가 보호된 필드인지 확인
  */
 export function isProtectedField(schema: z.ZodType): boolean {
-  return PROTECTED_FIELD in (schema as any);
+  return hasMetadata(schema, PROTECTED_FIELD);
 }
 
 /**
  * 스키마가 환경 변수 기반인지 확인
  */
 export function isEnvBasedField(schema: z.ZodType): boolean {
-  const source = (schema as any)[FIELD_SOURCE] as FieldSourceMetadata | undefined;
+  const source = getMetadata(schema, FIELD_SOURCE);
   return source?.source === "env";
 }

package/src/config/metadata.test.ts

@@ -228,7 +228,7 @@ describe("runtimeInjected", () => {
     const schema = runtimeInjected(z.string());
     const { RUNTIME_INJECTED } = require("./symbols.js");
 
-    expect((schema as any)[RUNTIME_INJECTED]).toBe(true);
+    expect((schema as unknown as Record<symbol, unknown>)[RUNTIME_INJECTED]).toBe(true); // accessing runtime-injected symbol
   });
 });
 

package/src/config/metadata.ts

@@ -31,6 +31,20 @@ import {
   VALIDATION_CONTEXT,
 } from "./symbols.js";
 
+// ============================================
+// 타입 안전한 Symbol 프로퍼티 접근 유틸리티
+// ============================================
+
+/**
+ * SchemaRecord: Zod 스키마를 symbol 키 접근 가능한 레코드로 변환.
+ * `as any` 캐스팅을 이 한 곳에서만 수행하여 나머지 코드의 타입 안전성을 보장.
+ */
+type SchemaRecord = Record<symbol, unknown>;
+
+function asRecord(schema: z.ZodType): SchemaRecord {
+  return schema as unknown as SchemaRecord;
+}
+
 // ============================================
 // 메타데이터 부착
 // ============================================
@@ -60,7 +74,7 @@ export function withMetadata<
   key: K,
   value: SymbolMetadataMap[K]
 ): T {
-  (schema as any)[key] = value;
+  asRecord(schema)[key] = value;
   return schema;
 }
 
@@ -79,8 +93,9 @@ export function withMetadataMultiple<T extends z.ZodType>(
   schema: T,
   entries: Array<[symbol, unknown]>
 ): T {
+  const record = asRecord(schema);
   for (const [key, value] of entries) {
-    (schema as any)[key] = value;
+    record[key] = value;
   }
   return schema;
 }
@@ -100,14 +115,14 @@ export function getMetadata<K extends keyof SymbolMetadataMap>(
   schema: z.ZodType,
   key: K
 ): SymbolMetadataMap[K] | undefined {
-  return (schema as any)[key];
+  return asRecord(schema)[key] as SymbolMetadataMap[K] | undefined;
 }
 
 /**
  * 스키마에 특정 메타데이터가 있는지 확인
  */
 export function hasMetadata(schema: z.ZodType, key: symbol): boolean {
-  return key in (schema as any);
+  return key in asRecord(schema);
 }
 
 /**
@@ -116,15 +131,16 @@ export function hasMetadata(schema: z.ZodType, key: symbol): boolean {
 export function getAllMetadata(
   schema: z.ZodType
 ): Partial<SymbolMetadataMap> {
-  const result: Partial<SymbolMetadataMap> = {};
+  const result = {} as Record<symbol, unknown>;
+  const record = asRecord(schema);
 
   for (const sym of ALL_METADATA_SYMBOLS) {
-    if (sym in (schema as any)) {
-      (result as any)[sym] = (schema as any)[sym];
+    if (sym in record) {
+      result[sym] = record[sym];
     }
   }
 
-  return result;
+  return result as Partial<SymbolMetadataMap>;
 }
 
 // ============================================
@@ -138,7 +154,7 @@ export function removeMetadata<T extends z.ZodType>(
   schema: T,
   key: symbol
 ): T {
-  delete (schema as any)[key];
+  delete asRecord(schema)[key];
   return schema;
 }
 
@@ -146,9 +162,10 @@ export function removeMetadata<T extends z.ZodType>(
  * 스키마에서 모든 mandu 메타데이터 제거
  */
 export function clearAllMetadata<T extends z.ZodType>(schema: T): T {
+  const record = asRecord(schema);
   for (const sym of ALL_METADATA_SYMBOLS) {
-    if (sym in (schema as any)) {
-      delete (schema as any)[sym];
+    if (sym in record) {
+      delete record[sym];
     }
   }
   return schema;
@@ -165,9 +182,11 @@ export function copyMetadata<T extends z.ZodType>(
   from: z.ZodType,
   to: T
 ): T {
+  const fromRecord = asRecord(from);
+  const toRecord = asRecord(to);
   for (const sym of ALL_METADATA_SYMBOLS) {
-    if (sym in (from as any)) {
-      (to as any)[sym] = (from as any)[sym];
+    if (sym in fromRecord) {
+      toRecord[sym] = fromRecord[sym];
     }
   }
   return to;
@@ -273,7 +292,7 @@ export function getManduSymbolKeys(obj: object): symbol[] {
  * 스키마에 메타데이터가 있는지 확인
  */
 export function hasAnyMetadata(schema: z.ZodType): boolean {
-  return getManduSymbolKeys(schema as any).length > 0;
+  return getManduSymbolKeys(schema as object).length > 0;
 }
 
 /**
@@ -283,10 +302,11 @@ export function serializeMetadata(
   schema: z.ZodType
 ): Record<string, unknown> {
   const result: Record<string, unknown> = {};
+  const record = asRecord(schema);
 
-  for (const sym of getManduSymbolKeys(schema as any)) {
+  for (const sym of getManduSymbolKeys(schema as object)) {
     const name = sym.description ?? sym.toString();
-    result[name] = (schema as any)[sym];
+    result[name] = record[sym];
   }
 
   return result;

package/src/config/symbols.ts

@@ -133,7 +133,7 @@ export const ALL_METADATA_SYMBOLS = [
  * 심볼이 mandu 메타데이터 심볼인지 확인
  */
 export function isManduMetadataSymbol(sym: symbol): boolean {
-  return ALL_METADATA_SYMBOLS.includes(sym as any);
+  return (ALL_METADATA_SYMBOLS as readonly symbol[]).includes(sym);
 }
 
 /**

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;
 
@@ -156,6 +156,22 @@ export interface ValidationResult {
   source?: string;
 }
 
+/**
+ * Assertion function: narrows unknown config to ValidatedManduConfig or throws.
+ *
+ * Useful in code paths that receive untrusted config objects and need
+ * to guarantee the type after the call without a separate null-check.
+ */
+export function assertValidConfig(cfg: unknown): asserts cfg is ValidatedManduConfig {
+  const result = ManduConfigSchema.safeParse(cfg);
+  if (!result.success) {
+    const messages = result.error.errors.map(
+      (e) => `${e.path.join(".")}: ${e.message}`
+    );
+    throw new Error(`Invalid ManduConfig:\n  ${messages.join("\n  ")}`);
+  }
+}
+
 /**
  * 설정 파일 검증
  */

package/src/content/content.test.ts

@@ -345,8 +345,8 @@ describe("LoaderContext", () => {
       data: { title: "Hello", count: 5 },
     });
 
-    expect(valid.title).toBe("Hello");
-    expect(valid.count).toBe(5);
+    expect((valid as Record<string, unknown>).title).toBe("Hello");
+    expect((valid as Record<string, unknown>).count).toBe(5);
 
     // Invalid data should throw
     await expect(
@@ -370,7 +370,7 @@ describe("LoaderContext", () => {
       data: { anything: "goes" },
     });
 
-    expect(data.anything).toBe("goes");
+    expect((data as Record<string, unknown>).anything).toBe("goes");
   });
 
   test("generateDigest creates hash", () => {

package/src/content/loaders/file.ts

@@ -39,6 +39,7 @@ function parseJson(content: string, filePath: string): unknown {
 async function parseYaml(content: string, filePath: string): Promise<unknown> {
   try {
     // yaml 패키지 동적 로드
+    // @ts-ignore dynamic optional import
     const yaml = await import("yaml").catch(() => null);
 
     if (!yaml) {
@@ -64,7 +65,9 @@ async function parseYaml(content: string, filePath: string): Promise<unknown> {
 async function parseToml(content: string, filePath: string): Promise<unknown> {
   try {
     // @iarna/toml 또는 toml 패키지 동적 로드
+    // @ts-ignore dynamic optional import
     const toml = await import("@iarna/toml").catch(() =>
+      // @ts-ignore dynamic optional import
       import("toml").catch(() => null)
     );
 

package/src/content/loaders/glob.ts

@@ -46,6 +46,7 @@ async function parseFrontmatter(
 
   try {
     // yaml 동적 로드
+    // @ts-ignore dynamic optional import
     const yaml = await import("yaml").catch(() => null);
 
     if (!yaml) {

package/src/contract/client-safe.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect } from "vitest";
+import { describe, it, expect } from "bun:test";
 import { z } from "zod";
 import { Mandu, createClientContract } from "../index";
 

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({