@mandujs/core 0.9.0 → 0.9.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/core",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "description": "Mandu Framework Core - Spec, Generator, Guard, Runtime",
   "type": "module",
   "main": "./src/index.ts",
@@ -45,5 +45,8 @@
     "react": ">=18.0.0",
     "react-dom": ">=18.0.0",
     "zod": ">=3.0.0"
+  },
+  "dependencies": {
+    "ollama": "^0.6.3"
   }
 }

package/src/brain/adapters/ollama.ts

@@ -2,9 +2,11 @@
  * Brain v0.1 - Ollama LLM Adapter
  *
  * Default adapter for local sLLM via Ollama.
- * Recommended models: llama3.2, codellama, mistral
+ * Uses official ollama npm package for reliable API integration.
+ * Recommended models: ministral-3:3b, llama3.2, codellama, mistral
  */
 
+import { Ollama } from "ollama";
 import { BaseLLMAdapter } from "./base";
 import type {
   AdapterConfig,
@@ -23,32 +25,10 @@ import type {
  */
 export const DEFAULT_OLLAMA_CONFIG: AdapterConfig = {
   baseUrl: "http://localhost:11434",
-  model: "ministral-3:3b",
+  model: "ministral-3:3b",  // Mistral's lightweight 3B model (3.0GB)
   timeout: 30000, // 30 seconds
 };
 
-/**
- * Ollama API response types
- */
-interface OllamaTagsResponse {
-  models: Array<{
-    name: string;
-    size: number;
-    modified_at: string;
-  }>;
-}
-
-interface OllamaChatResponse {
-  model: string;
-  message: {
-    role: string;
-    content: string;
-  };
-  done: boolean;
-  eval_count?: number;
-  prompt_eval_count?: number;
-}
-
 /**
  * Ollama LLM Adapter
  *
@@ -57,12 +37,17 @@ interface OllamaChatResponse {
  */
 export class OllamaAdapter extends BaseLLMAdapter {
   readonly name = "ollama";
+  private client: Ollama;
 
   constructor(config: Partial<AdapterConfig> = {}) {
     super({
       ...DEFAULT_OLLAMA_CONFIG,
       ...config,
     });
+
+    this.client = new Ollama({
+      host: this.baseUrl,
+    });
   }
 
   /**
@@ -70,28 +55,8 @@ export class OllamaAdapter extends BaseLLMAdapter {
    */
   async checkStatus(): Promise<AdapterStatus> {
     try {
-      const controller = new AbortController();
-      const timeoutId = setTimeout(
-        () => controller.abort(),
-        this.config.timeout ?? 5000
-      );
-
-      const response = await fetch(`${this.baseUrl}/api/tags`, {
-        signal: controller.signal,
-      });
-
-      clearTimeout(timeoutId);
-
-      if (!response.ok) {
-        return {
-          available: false,
-          model: null,
-          error: `Ollama API error: ${response.status}`,
-        };
-      }
-
-      const data = (await response.json()) as OllamaTagsResponse;
-      const models = data.models || [];
+      const response = await this.client.list();
+      const models = response.models || [];
 
       // Check if configured model is available
       const modelAvailable = models.some(
@@ -122,21 +87,14 @@ export class OllamaAdapter extends BaseLLMAdapter {
         model: this.config.model,
       };
     } catch (error) {
-      if (error instanceof Error && error.name === "AbortError") {
-        return {
-          available: false,
-          model: null,
-          error: "Ollama connection timeout",
-        };
-      }
-
       const errorMessage =
         error instanceof Error ? error.message : "Unknown error";
 
       // Check for common connection errors
       if (
         errorMessage.includes("ECONNREFUSED") ||
-        errorMessage.includes("fetch failed")
+        errorMessage.includes("fetch failed") ||
+        errorMessage.includes("Unable to connect")
       ) {
         return {
           available: false,
@@ -163,47 +121,26 @@ export class OllamaAdapter extends BaseLLMAdapter {
     const { temperature = 0.7, maxTokens = 2048 } = options;
 
     try {
-      const controller = new AbortController();
-      const timeoutId = setTimeout(
-        () => controller.abort(),
-        this.config.timeout ?? 30000
-      );
-
-      const response = await fetch(`${this.baseUrl}/api/chat`, {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json",
+      const response = await this.client.chat({
+        model: this.config.model,
+        messages: messages.map((m) => ({
+          role: m.role,
+          content: m.content,
+        })),
+        stream: false,
+        options: {
+          temperature,
+          num_predict: maxTokens,
         },
-        body: JSON.stringify({
-          model: this.config.model,
-          messages: messages.map((m) => ({
-            role: m.role,
-            content: m.content,
-          })),
-          stream: false,
-          options: {
-            temperature,
-            num_predict: maxTokens,
-          },
-        }),
-        signal: controller.signal,
       });
 
-      clearTimeout(timeoutId);
-
-      if (!response.ok) {
-        const errorText = await response.text();
-        throw new Error(`Ollama API error: ${response.status} - ${errorText}`);
-      }
-
-      const data = (await response.json()) as OllamaChatResponse;
-
       return {
-        content: data.message?.content || "",
+        content: response.message?.content || "",
         usage: {
-          promptTokens: data.prompt_eval_count || 0,
-          completionTokens: data.eval_count || 0,
-          totalTokens: (data.prompt_eval_count || 0) + (data.eval_count || 0),
+          promptTokens: response.prompt_eval_count || 0,
+          completionTokens: response.eval_count || 0,
+          totalTokens:
+            (response.prompt_eval_count || 0) + (response.eval_count || 0),
         },
       };
     } catch (error) {
@@ -215,28 +152,77 @@ export class OllamaAdapter extends BaseLLMAdapter {
   }
 
   /**
-   * Pull a model from Ollama registry
+   * Pull a model from Ollama registry with progress callback
    */
-  async pullModel(modelName?: string): Promise<boolean> {
+  async pullModel(
+    modelName?: string,
+    onProgress?: (status: string, completed?: number, total?: number) => void
+  ): Promise<{ success: boolean; error?: string }> {
     const model = modelName ?? this.config.model;
 
     try {
-      const response = await fetch(`${this.baseUrl}/api/pull`, {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-        },
-        body: JSON.stringify({
-          name: model,
-          stream: false,
-        }),
+      const stream = await this.client.pull({
+        model,
+        stream: true,
       });
 
-      return response.ok;
+      for await (const progress of stream) {
+        if (onProgress && progress.status) {
+          onProgress(
+            progress.status,
+            progress.completed,
+            progress.total
+          );
+        }
+      }
+
+      return { success: true };
+    } catch (error) {
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : "Unknown error",
+      };
+    }
+  }
+
+  /**
+   * Check if Ollama server is reachable
+   */
+  async isServerRunning(): Promise<boolean> {
+    try {
+      await this.client.list();
+      return true;
     } catch {
       return false;
     }
   }
+
+  /**
+   * List all available models
+   */
+  async listModels(): Promise<string[]> {
+    try {
+      const response = await this.client.list();
+      return (response.models || []).map((m) => m.name);
+    } catch {
+      return [];
+    }
+  }
+
+  /**
+   * Generate embeddings for text
+   */
+  async embed(text: string, model?: string): Promise<number[] | null> {
+    try {
+      const response = await this.client.embed({
+        model: model ?? this.config.model,
+        input: text,
+      });
+      return response.embeddings?.[0] ?? null;
+    } catch {
+      return null;
+    }
+  }
 }
 
 /**

package/src/brain/architecture/analyzer.ts

@@ -0,0 +1,541 @@
+/**
+ * Brain v0.2 - Architecture Analyzer
+ *
+ * 프로젝트 아키텍처 규칙을 분석하고 위반을 감지
+ */
+
+import type {
+  ArchitectureConfig,
+  ArchitectureViolation,
+  CheckLocationRequest,
+  CheckLocationResult,
+  CheckImportRequest,
+  CheckImportResult,
+  ProjectStructure,
+  FolderInfo,
+  FolderRule,
+  ImportRule,
+} from "./types";
+import { getBrain } from "../brain";
+import path from "path";
+import fs from "fs/promises";
+
+/**
+ * Mandu 기본 아키텍처 규칙
+ */
+export const DEFAULT_ARCHITECTURE_CONFIG: ArchitectureConfig = {
+  folders: {
+    "spec/": {
+      pattern: "spec/**",
+      description: "스펙 정의 전용. 구현 코드 금지",
+      allowedFiles: ["*.ts", "*.json"],
+      readonly: false,
+    },
+    "spec/slots/": {
+      pattern: "spec/slots/**",
+      description: "Slot 파일 전용",
+      allowedFiles: ["*.slot.ts", "*.client.ts"],
+    },
+    "spec/contracts/": {
+      pattern: "spec/contracts/**",
+      description: "Contract 파일 전용",
+      allowedFiles: ["*.contract.ts"],
+    },
+    "generated/": {
+      pattern: "**/generated/**",
+      description: "자동 생성 파일. 직접 수정 금지",
+      readonly: true,
+    },
+    "apps/server/": {
+      pattern: "apps/server/**",
+      description: "백엔드 로직",
+      allowedFiles: ["*.ts"],
+    },
+    "apps/web/": {
+      pattern: "apps/web/**",
+      description: "프론트엔드 컴포넌트",
+      allowedFiles: ["*.ts", "*.tsx"],
+    },
+  },
+  imports: [
+    {
+      source: "apps/web/**",
+      forbid: ["fs", "child_process", "path", "crypto"],
+      reason: "프론트엔드에서 Node.js 내장 모듈 사용 금지",
+    },
+    {
+      source: "**/generated/**",
+      forbid: ["fs", "child_process"],
+      reason: "Generated 파일에서 시스템 모듈 사용 금지",
+    },
+    {
+      source: "spec/**",
+      forbid: ["react", "react-dom"],
+      reason: "Spec 파일에서 React 사용 금지",
+    },
+  ],
+  layers: [
+    {
+      name: "spec",
+      folders: ["spec/**"],
+      canDependOn: [],
+    },
+    {
+      name: "generated",
+      folders: ["**/generated/**"],
+      canDependOn: ["spec"],
+    },
+    {
+      name: "app",
+      folders: ["apps/**"],
+      canDependOn: ["spec", "generated"],
+    },
+  ],
+  naming: [
+    {
+      folder: "spec/slots/",
+      filePattern: "^[a-z][a-z0-9-]*\\.(slot|client)\\.ts$",
+      description: "Slot 파일은 kebab-case.slot.ts 또는 kebab-case.client.ts",
+      examples: ["users-list.slot.ts", "counter.client.ts"],
+    },
+    {
+      folder: "spec/contracts/",
+      filePattern: "^[a-z][a-z0-9-]*\\.contract\\.ts$",
+      description: "Contract 파일은 kebab-case.contract.ts",
+      examples: ["users.contract.ts", "auth.contract.ts"],
+    },
+  ],
+};
+
+/**
+ * 글로브 패턴을 정규식으로 변환
+ */
+function globToRegex(glob: string): RegExp {
+  const escaped = glob
+    .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+    .replace(/\*\*/g, "§§")
+    .replace(/\*/g, "[^/]*")
+    .replace(/§§/g, ".*")
+    .replace(/\?/g, ".");
+  return new RegExp(`^${escaped}$`);
+}
+
+/**
+ * 경로가 패턴과 매칭되는지 확인
+ */
+function matchesPattern(filePath: string, pattern: string): boolean {
+  const normalizedPath = filePath.replace(/\\/g, "/");
+  const regex = globToRegex(pattern);
+  return regex.test(normalizedPath);
+}
+
+/**
+ * Architecture Analyzer 클래스
+ */
+export class ArchitectureAnalyzer {
+  private config: ArchitectureConfig;
+  private rootDir: string;
+  private projectStructure: ProjectStructure | null = null;
+
+  constructor(rootDir: string, config?: Partial<ArchitectureConfig>) {
+    this.rootDir = rootDir;
+    this.config = {
+      ...DEFAULT_ARCHITECTURE_CONFIG,
+      ...config,
+      folders: {
+        ...DEFAULT_ARCHITECTURE_CONFIG.folders,
+        ...config?.folders,
+      },
+      imports: [
+        ...(DEFAULT_ARCHITECTURE_CONFIG.imports || []),
+        ...(config?.imports || []),
+      ],
+    };
+  }
+
+  /**
+   * 설정 업데이트
+   */
+  updateConfig(config: Partial<ArchitectureConfig>): void {
+    this.config = {
+      ...this.config,
+      ...config,
+    };
+  }
+
+  /**
+   * 현재 설정 반환
+   */
+  getConfig(): ArchitectureConfig {
+    return this.config;
+  }
+
+  /**
+   * 파일 위치 검증
+   */
+  async checkLocation(request: CheckLocationRequest): Promise<CheckLocationResult> {
+    const violations: ArchitectureViolation[] = [];
+    const normalizedPath = request.path.replace(/\\/g, "/");
+
+    // 1. readonly 폴더 검사
+    for (const [key, rule] of Object.entries(this.config.folders || {})) {
+      const folderRule = typeof rule === "string"
+        ? { pattern: key, description: rule }
+        : rule;
+
+      if (folderRule.readonly && matchesPattern(normalizedPath, folderRule.pattern)) {
+        violations.push({
+          ruleId: "READONLY_FOLDER",
+          ruleType: "folder",
+          file: request.path,
+          message: `이 폴더는 수정 금지입니다: ${folderRule.description}`,
+          suggestion: "이 파일은 자동 생성됩니다. bunx mandu generate를 사용하세요.",
+          severity: "error",
+        });
+      }
+    }
+
+    // 2. 네이밍 규칙 검사
+    for (const rule of this.config.naming || []) {
+      if (normalizedPath.startsWith(rule.folder.replace(/\\/g, "/"))) {
+        const fileName = path.basename(normalizedPath);
+        const regex = new RegExp(rule.filePattern);
+
+        if (!regex.test(fileName)) {
+          violations.push({
+            ruleId: "NAMING_CONVENTION",
+            ruleType: "naming",
+            file: request.path,
+            message: `네이밍 규칙 위반: ${rule.description}`,
+            suggestion: `예시: ${rule.examples?.join(", ") || "N/A"}`,
+            severity: "error",
+          });
+        }
+      }
+    }
+
+    // 3. 허용된 파일 타입 검사
+    for (const [key, rule] of Object.entries(this.config.folders || {})) {
+      const folderRule = typeof rule === "string"
+        ? { pattern: key, description: rule }
+        : rule;
+
+      if (matchesPattern(normalizedPath, folderRule.pattern)) {
+        if (folderRule.allowedFiles && folderRule.allowedFiles.length > 0) {
+          const fileName = path.basename(normalizedPath);
+          const isAllowed = folderRule.allowedFiles.some((pattern) => {
+            const regex = globToRegex(pattern);
+            return regex.test(fileName);
+          });
+
+          if (!isAllowed) {
+            violations.push({
+              ruleId: "DISALLOWED_FILE_TYPE",
+              ruleType: "folder",
+              file: request.path,
+              message: `이 폴더에서 허용되지 않는 파일 타입입니다`,
+              suggestion: `허용: ${folderRule.allowedFiles.join(", ")}`,
+              severity: "warning",
+            });
+          }
+        }
+      }
+    }
+
+    // 4. 내용 기반 검사 (content가 제공된 경우)
+    if (request.content) {
+      const importViolations = await this.checkImports({
+        sourceFile: request.path,
+        imports: this.extractImports(request.content),
+      });
+
+      for (const v of importViolations.violations) {
+        violations.push({
+          ruleId: "FORBIDDEN_IMPORT",
+          ruleType: "import",
+          file: request.path,
+          message: v.reason,
+          suggestion: v.suggestion,
+          severity: "error",
+        });
+      }
+    }
+
+    // 5. LLM 제안 (위반이 있는 경우)
+    let suggestion: string | undefined;
+    let recommendedPath: string | undefined;
+
+    if (violations.length > 0) {
+      const brain = getBrain();
+      if (await brain.isLLMAvailable()) {
+        const llmSuggestion = await this.getLLMSuggestion(request, violations);
+        suggestion = llmSuggestion.suggestion;
+        recommendedPath = llmSuggestion.recommendedPath;
+      } else {
+        // 템플릿 기반 제안
+        recommendedPath = this.getTemplateRecommendedPath(request.path);
+      }
+    }
+
+    return {
+      allowed: violations.length === 0,
+      violations,
+      suggestion,
+      recommendedPath,
+    };
+  }
+
+  /**
+   * Import 검증
+   */
+  async checkImports(request: CheckImportRequest): Promise<CheckImportResult> {
+    const violations: Array<{
+      import: string;
+      reason: string;
+      suggestion?: string;
+    }> = [];
+
+    const normalizedSource = request.sourceFile.replace(/\\/g, "/");
+
+    for (const importPath of request.imports) {
+      for (const rule of this.config.imports || []) {
+        if (matchesPattern(normalizedSource, rule.source)) {
+          // 금지된 import 검사
+          if (rule.forbid) {
+            for (const forbidden of rule.forbid) {
+              if (
+                importPath === forbidden ||
+                importPath.startsWith(`${forbidden}/`)
+              ) {
+                violations.push({
+                  import: importPath,
+                  reason: rule.reason || `'${importPath}' import 금지`,
+                  suggestion: this.getImportSuggestion(importPath, normalizedSource),
+                });
+              }
+            }
+          }
+
+          // 허용된 import만 검사 (allow가 정의된 경우)
+          if (rule.allow && rule.allow.length > 0) {
+            const isAllowed = rule.allow.some((allowed) =>
+              matchesPattern(importPath, allowed)
+            );
+            if (!isAllowed) {
+              violations.push({
+                import: importPath,
+                reason: `'${importPath}'는 허용되지 않은 import입니다`,
+                suggestion: `허용된 패턴: ${rule.allow.join(", ")}`,
+              });
+            }
+          }
+        }
+      }
+    }
+
+    return {
+      allowed: violations.length === 0,
+      violations,
+    };
+  }
+
+  /**
+   * 프로젝트 구조 인덱싱
+   */
+  async indexProject(): Promise<ProjectStructure> {
+    const folders = await this.scanFolders(this.rootDir, 0, 3);
+
+    this.projectStructure = {
+      rootDir: this.rootDir,
+      folders,
+      config: this.config,
+      indexedAt: new Date().toISOString(),
+    };
+
+    return this.projectStructure;
+  }
+
+  /**
+   * 프로젝트 구조 반환
+   */
+  async getProjectStructure(): Promise<ProjectStructure> {
+    if (!this.projectStructure) {
+      return this.indexProject();
+    }
+    return this.projectStructure;
+  }
+
+  /**
+   * 코드에서 import 문 추출
+   */
+  private extractImports(content: string): string[] {
+    const imports: string[] = [];
+
+    // ES6 import
+    const importRegex = /import\s+(?:.*\s+from\s+)?['"]([^'"]+)['"]/g;
+    let match;
+    while ((match = importRegex.exec(content)) !== null) {
+      imports.push(match[1]);
+    }
+
+    // require
+    const requireRegex = /require\s*\(\s*['"]([^'"]+)['"]\s*\)/g;
+    while ((match = requireRegex.exec(content)) !== null) {
+      imports.push(match[1]);
+    }
+
+    return imports;
+  }
+
+  /**
+   * 폴더 스캔
+   */
+  private async scanFolders(
+    dir: string,
+    depth: number,
+    maxDepth: number
+  ): Promise<FolderInfo[]> {
+    if (depth >= maxDepth) return [];
+
+    const folders: FolderInfo[] = [];
+
+    try {
+      const entries = await fs.readdir(dir, { withFileTypes: true });
+
+      for (const entry of entries) {
+        if (!entry.isDirectory()) continue;
+        if (entry.name === "node_modules" || entry.name === ".git") continue;
+
+        const fullPath = path.join(dir, entry.name);
+        const relativePath = path.relative(this.rootDir, fullPath).replace(/\\/g, "/");
+
+        // 폴더 설명 찾기
+        let description: string | undefined;
+        for (const [key, rule] of Object.entries(this.config.folders || {})) {
+          const folderRule = typeof rule === "string" ? { pattern: key, description: rule } : rule;
+          if (matchesPattern(relativePath + "/", folderRule.pattern)) {
+            description = folderRule.description;
+            break;
+          }
+        }
+
+        // 파일 수 계산
+        const files = entries.filter((e) => e.isFile());
+
+        folders.push({
+          path: relativePath,
+          description,
+          fileCount: files.length,
+          children: await this.scanFolders(fullPath, depth + 1, maxDepth),
+        });
+      }
+    } catch {
+      // 권한 없는 폴더 무시
+    }
+
+    return folders;
+  }
+
+  /**
+   * Import에 대한 템플릿 제안
+   */
+  private getImportSuggestion(importPath: string, sourceFile: string): string {
+    if (importPath === "fs") {
+      if (sourceFile.includes("apps/web")) {
+        return "프론트엔드에서는 fetch API를 사용하세요";
+      }
+      return "Bun.file() 또는 Bun.write()를 사용하세요";
+    }
+    if (importPath === "child_process") {
+      return "Bun.spawn() 또는 Bun.$를 사용하세요";
+    }
+    if (importPath === "path") {
+      return "import.meta.dir 또는 Bun.pathToFileURL을 사용하세요";
+    }
+    return "다른 모듈을 사용하세요";
+  }
+
+  /**
+   * 템플릿 기반 권장 경로
+   */
+  private getTemplateRecommendedPath(filePath: string): string | undefined {
+    const normalized = filePath.replace(/\\/g, "/");
+    const fileName = path.basename(normalized);
+
+    if (fileName.endsWith(".slot.ts")) {
+      return `spec/slots/${fileName}`;
+    }
+    if (fileName.endsWith(".contract.ts")) {
+      return `spec/contracts/${fileName}`;
+    }
+    if (normalized.includes("generated/")) {
+      return undefined; // generated는 이동 불가
+    }
+
+    return undefined;
+  }
+
+  /**
+   * LLM 기반 제안
+   */
+  private async getLLMSuggestion(
+    request: CheckLocationRequest,
+    violations: ArchitectureViolation[]
+  ): Promise<{ suggestion?: string; recommendedPath?: string }> {
+    const brain = getBrain();
+
+    const prompt = `Mandu Framework 아키텍처 분석:
+
+파일: ${request.path}
+위반 사항:
+${violations.map((v) => `- ${v.message}`).join("\n")}
+
+프로젝트 구조 규칙:
+${JSON.stringify(this.config.folders, null, 2)}
+
+질문:
+1. 이 파일의 올바른 위치는 어디인가요?
+2. 어떻게 수정해야 하나요?
+
+짧고 명확하게 답변하세요 (3줄 이내).`;
+
+    try {
+      const result = await brain.complete([
+        { role: "user", content: prompt },
+      ]);
+
+      // 응답에서 경로 추출 시도
+      const pathMatch = result.content.match(/(?:spec\/|apps\/|packages\/)[^\s,)]+/);
+
+      return {
+        suggestion: result.content,
+        recommendedPath: pathMatch?.[0],
+      };
+    } catch {
+      return {};
+    }
+  }
+}
+
+/**
+ * 글로벌 analyzer 인스턴스
+ */
+let globalAnalyzer: ArchitectureAnalyzer | null = null;
+
+/**
+ * Architecture Analyzer 초기화
+ */
+export function initializeArchitectureAnalyzer(
+  rootDir: string,
+  config?: Partial<ArchitectureConfig>
+): ArchitectureAnalyzer {
+  globalAnalyzer = new ArchitectureAnalyzer(rootDir, config);
+  return globalAnalyzer;
+}
+
+/**
+ * 글로벌 analyzer 반환
+ */
+export function getArchitectureAnalyzer(): ArchitectureAnalyzer | null {
+  return globalAnalyzer;
+}

package/src/brain/architecture/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Brain v0.2 - Architecture Guard
+ *
+ * 프로젝트 아키텍처 규칙 검증 및 코딩 에이전트 피드백
+ */
+
+export * from "./types";
+export * from "./analyzer";

package/src/brain/architecture/types.ts

@@ -0,0 +1,195 @@
+/**
+ * Brain v0.2 - Architecture Guard Types
+ *
+ * 프로젝트 아키텍처 규칙 정의 및 검증을 위한 타입
+ */
+
+/**
+ * 폴더 역할 정의
+ */
+export interface FolderRule {
+  /** 폴더 경로 패턴 (glob) */
+  pattern: string;
+  /** 폴더 설명/역할 */
+  description: string;
+  /** 허용되는 파일 패턴 */
+  allowedFiles?: string[];
+  /** 금지되는 파일 패턴 */
+  forbiddenFiles?: string[];
+  /** 이 폴더에서 허용되는 export */
+  allowedExports?: string[];
+  /** 수정 금지 여부 */
+  readonly?: boolean;
+}
+
+/**
+ * Import 규칙 정의
+ */
+export interface ImportRule {
+  /** 적용 대상 파일 패턴 (glob) */
+  source: string;
+  /** 허용되는 import 패턴 */
+  allow?: string[];
+  /** 금지되는 import 패턴 */
+  forbid?: string[];
+  /** 규칙 설명 */
+  reason?: string;
+}
+
+/**
+ * 레이어 의존성 규칙
+ */
+export interface LayerRule {
+  /** 레이어 이름 */
+  name: string;
+  /** 레이어에 속하는 폴더 패턴 */
+  folders: string[];
+  /** 의존 가능한 레이어 */
+  canDependOn: string[];
+  /** 의존 불가 레이어 */
+  cannotDependOn?: string[];
+}
+
+/**
+ * 네이밍 규칙
+ */
+export interface NamingRule {
+  /** 적용 대상 폴더 패턴 */
+  folder: string;
+  /** 파일명 패턴 (정규식) */
+  filePattern: string;
+  /** 규칙 설명 */
+  description: string;
+  /** 예시 */
+  examples?: string[];
+}
+
+/**
+ * 아키텍처 설정
+ */
+export interface ArchitectureConfig {
+  /** 폴더 규칙 */
+  folders?: Record<string, FolderRule | string>;
+  /** Import 규칙 */
+  imports?: ImportRule[];
+  /** 레이어 규칙 */
+  layers?: LayerRule[];
+  /** 네이밍 규칙 */
+  naming?: NamingRule[];
+  /** 커스텀 규칙 */
+  custom?: CustomRule[];
+}
+
+/**
+ * 커스텀 규칙
+ */
+export interface CustomRule {
+  /** 규칙 ID */
+  id: string;
+  /** 규칙 설명 */
+  description: string;
+  /** 파일 패턴 */
+  pattern: string;
+  /** 검증 조건 (코드에 포함되어야 하는 패턴) */
+  mustContain?: string[];
+  /** 금지 조건 (코드에 포함되면 안 되는 패턴) */
+  mustNotContain?: string[];
+}
+
+/**
+ * 아키텍처 위반
+ */
+export interface ArchitectureViolation {
+  /** 규칙 ID */
+  ruleId: string;
+  /** 규칙 타입 */
+  ruleType: "folder" | "import" | "layer" | "naming" | "custom";
+  /** 위반 파일 경로 */
+  file: string;
+  /** 위반 메시지 */
+  message: string;
+  /** 수정 제안 */
+  suggestion?: string;
+  /** 심각도 */
+  severity: "error" | "warning" | "info";
+  /** 위반 라인 (해당시) */
+  line?: number;
+}
+
+/**
+ * 위치 검증 요청
+ */
+export interface CheckLocationRequest {
+  /** 검사할 파일 경로 */
+  path: string;
+  /** 파일 내용 (선택) */
+  content?: string;
+  /** 파일 타입 */
+  fileType?: "ts" | "tsx" | "js" | "jsx" | "json" | "other";
+}
+
+/**
+ * 위치 검증 결과
+ */
+export interface CheckLocationResult {
+  /** 허용 여부 */
+  allowed: boolean;
+  /** 위반 목록 */
+  violations: ArchitectureViolation[];
+  /** LLM 제안 (활성화시) */
+  suggestion?: string;
+  /** 권장 경로 */
+  recommendedPath?: string;
+}
+
+/**
+ * Import 검증 요청
+ */
+export interface CheckImportRequest {
+  /** 소스 파일 경로 */
+  sourceFile: string;
+  /** 검사할 import 문 */
+  imports: string[];
+}
+
+/**
+ * Import 검증 결과
+ */
+export interface CheckImportResult {
+  /** 모든 import 허용 여부 */
+  allowed: boolean;
+  /** 위반된 import 목록 */
+  violations: Array<{
+    import: string;
+    reason: string;
+    suggestion?: string;
+  }>;
+}
+
+/**
+ * 프로젝트 구조 정보
+ */
+export interface ProjectStructure {
+  /** 루트 디렉토리 */
+  rootDir: string;
+  /** 폴더 트리 */
+  folders: FolderInfo[];
+  /** 아키텍처 설정 */
+  config: ArchitectureConfig;
+  /** 인덱싱 시간 */
+  indexedAt: string;
+}
+
+/**
+ * 폴더 정보
+ */
+export interface FolderInfo {
+  /** 경로 */
+  path: string;
+  /** 역할 설명 */
+  description?: string;
+  /** 파일 수 */
+  fileCount: number;
+  /** 하위 폴더 */
+  children?: FolderInfo[];
+}

package/src/brain/index.ts

@@ -1,9 +1,10 @@
 /**
- * Brain v0.1 - Module Exports
+ * Brain v0.2 - Module Exports
  *
- * Brain handles two responsibilities:
+ * Brain handles three responsibilities:
  * 1. Doctor (error recovery): Guard failure analysis + minimal patch suggestions
  * 2. Watch (error prevention): File change warnings (no blocking)
+ * 3. Architecture (structure enforcement): Project structure validation for coding agents
  */
 
 // Types
@@ -43,3 +44,6 @@ export {
 
 // Doctor
 export * from "./doctor";
+
+// Architecture (v0.2)
+export * from "./architecture";