@mandujs/core 0.8.2 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/core",
-  "version": "0.8.2",
+  "version": "0.9.0",
   "description": "Mandu Framework Core - Spec, Generator, Guard, Runtime",
   "type": "module",
   "main": "./src/index.ts",
@@ -13,6 +13,14 @@
   "files": [
     "src/**/*"
   ],
+  "scripts": {
+    "test": "bun test",
+    "test:hydration": "bun test tests/hydration",
+    "test:watch": "bun test --watch"
+  },
+  "devDependencies": {
+    "@happy-dom/global-registrator": "^15.0.0"
+  },
   "keywords": [
     "mandu",
     "framework",

package/src/brain/adapters/base.ts

@@ -0,0 +1,120 @@
+/**
+ * Brain v0.1 - Base LLM Adapter Interface
+ *
+ * Defines the interface for LLM adapters.
+ * Brain works without LLM (template-based), LLM only improves suggestion quality.
+ */
+
+import type {
+  AdapterConfig,
+  AdapterStatus,
+  ChatMessage,
+  CompletionOptions,
+  CompletionResult,
+} from "../types";
+
+/**
+ * Base LLM Adapter Interface
+ *
+ * Implementations:
+ * - OllamaAdapter: Local sLLM via Ollama
+ * - (Future) OpenAIAdapter, AnthropicAdapter, etc.
+ */
+export interface LLMAdapter {
+  /**
+   * Adapter name (e.g., "ollama", "openai")
+   */
+  readonly name: string;
+
+  /**
+   * Check if the adapter is available and configured
+   */
+  checkStatus(): Promise<AdapterStatus>;
+
+  /**
+   * Complete a chat conversation
+   */
+  complete(
+    messages: ChatMessage[],
+    options?: CompletionOptions
+  ): Promise<CompletionResult>;
+
+  /**
+   * Generate a simple completion (convenience method)
+   */
+  generate(prompt: string, options?: CompletionOptions): Promise<string>;
+}
+
+/**
+ * Base adapter implementation with common functionality
+ */
+export abstract class BaseLLMAdapter implements LLMAdapter {
+  abstract readonly name: string;
+  protected config: AdapterConfig;
+
+  constructor(config: AdapterConfig) {
+    this.config = config;
+  }
+
+  abstract checkStatus(): Promise<AdapterStatus>;
+  abstract complete(
+    messages: ChatMessage[],
+    options?: CompletionOptions
+  ): Promise<CompletionResult>;
+
+  /**
+   * Simple generation (wraps complete with a single user message)
+   */
+  async generate(prompt: string, options?: CompletionOptions): Promise<string> {
+    const result = await this.complete(
+      [{ role: "user", content: prompt }],
+      options
+    );
+    return result.content;
+  }
+
+  /**
+   * Get the configured model name
+   */
+  get model(): string {
+    return this.config.model;
+  }
+
+  /**
+   * Get the configured base URL
+   */
+  get baseUrl(): string {
+    return this.config.baseUrl;
+  }
+}
+
+/**
+ * No-op adapter for when LLM is not available
+ * Returns empty results, allowing Brain to fall back to template-based analysis
+ */
+export class NoopAdapter implements LLMAdapter {
+  readonly name = "noop";
+
+  async checkStatus(): Promise<AdapterStatus> {
+    return {
+      available: false,
+      model: null,
+      error: "No LLM adapter configured",
+    };
+  }
+
+  async complete(): Promise<CompletionResult> {
+    return {
+      content: "",
+      usage: {
+        promptTokens: 0,
+        completionTokens: 0,
+        totalTokens: 0,
+      },
+    };
+  }
+
+  async generate(): Promise<string> {
+    return "";
+  }
+}

package/src/brain/adapters/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Brain v0.1 - LLM Adapters
+ *
+ * Export all adapter implementations and utilities.
+ */
+
+export * from "./base";
+export * from "./ollama";

package/src/brain/adapters/ollama.ts

@@ -0,0 +1,249 @@
+/**
+ * Brain v0.1 - Ollama LLM Adapter
+ *
+ * Default adapter for local sLLM via Ollama.
+ * Recommended models: llama3.2, codellama, mistral
+ */
+
+import { BaseLLMAdapter } from "./base";
+import type {
+  AdapterConfig,
+  AdapterStatus,
+  ChatMessage,
+  CompletionOptions,
+  CompletionResult,
+} from "../types";
+
+/**
+ * Default Ollama configuration
+ *
+ * Ministral 3B: 저사양 PC에서도 동작하는 경량 모델
+ * - 2GB VRAM 이하에서도 CPU 모드로 동작
+ * - 코드 분석/제안에 충분한 성능
+ */
+export const DEFAULT_OLLAMA_CONFIG: AdapterConfig = {
+  baseUrl: "http://localhost:11434",
+  model: "ministral-3:3b",
+  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
+ *
+ * Connects to a local Ollama instance for sLLM inference.
+ * Falls back gracefully if Ollama is not available.
+ */
+export class OllamaAdapter extends BaseLLMAdapter {
+  readonly name = "ollama";
+
+  constructor(config: Partial<AdapterConfig> = {}) {
+    super({
+      ...DEFAULT_OLLAMA_CONFIG,
+      ...config,
+    });
+  }
+
+  /**
+   * Check if Ollama is running and the model is available
+   */
+  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 || [];
+
+      // Check if configured model is available
+      const modelAvailable = models.some(
+        (m) =>
+          m.name === this.config.model ||
+          m.name.startsWith(`${this.config.model}:`)
+      );
+
+      if (!modelAvailable) {
+        // Check if any model is available
+        if (models.length > 0) {
+          return {
+            available: true,
+            model: models[0].name,
+            error: `Configured model '${this.config.model}' not found. Using '${models[0].name}' instead.`,
+          };
+        }
+
+        return {
+          available: false,
+          model: null,
+          error: `No models available. Run: ollama pull ${this.config.model}`,
+        };
+      }
+
+      return {
+        available: true,
+        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")
+      ) {
+        return {
+          available: false,
+          model: null,
+          error: "Ollama is not running. Start with: ollama serve",
+        };
+      }
+
+      return {
+        available: false,
+        model: null,
+        error: `Ollama check failed: ${errorMessage}`,
+      };
+    }
+  }
+
+  /**
+   * Complete a chat conversation using Ollama's chat API
+   */
+  async complete(
+    messages: ChatMessage[],
+    options: CompletionOptions = {}
+  ): Promise<CompletionResult> {
+    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",
+        },
+        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 || "",
+        usage: {
+          promptTokens: data.prompt_eval_count || 0,
+          completionTokens: data.eval_count || 0,
+          totalTokens: (data.prompt_eval_count || 0) + (data.eval_count || 0),
+        },
+      };
+    } catch (error) {
+      if (error instanceof Error && error.name === "AbortError") {
+        throw new Error("Ollama request timeout");
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Pull a model from Ollama registry
+   */
+  async pullModel(modelName?: string): Promise<boolean> {
+    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,
+        }),
+      });
+
+      return response.ok;
+    } catch {
+      return false;
+    }
+  }
+}
+
+/**
+ * Create an Ollama adapter with optional configuration
+ */
+export function createOllamaAdapter(
+  config?: Partial<AdapterConfig>
+): OllamaAdapter {
+  return new OllamaAdapter(config);
+}

package/src/brain/brain.ts

@@ -0,0 +1,324 @@
+/**
+ * Brain v0.1 - Main Brain Class
+ *
+ * Brain handles two responsibilities:
+ * 1. Doctor (error recovery): Guard failure analysis + minimal patch suggestions
+ * 2. Watch (error prevention): File change warnings (no blocking)
+ *
+ * Core Principles:
+ * - Works without LLM (template-based), LLM only improves suggestion quality
+ * - Never blocks operations - only warns and suggests
+ * - Brain failure doesn't affect Core functionality (isolation)
+ * - Auto-apply is disabled by default (experimental flag)
+ */
+
+import type {
+  BrainConfig,
+  BrainPolicy,
+  EnvironmentInfo,
+  AdapterStatus,
+} from "./types";
+import { DEFAULT_BRAIN_POLICY } from "./types";
+import { type LLMAdapter, NoopAdapter } from "./adapters/base";
+import { createOllamaAdapter } from "./adapters/ollama";
+import { SessionMemory, getSessionMemory } from "./memory";
+import {
+  detectEnvironment,
+  shouldEnableBrain,
+  isolatedBrainExecution,
+} from "./permissions";
+
+/**
+ * Brain status
+ */
+export interface BrainStatus {
+  /** Whether Brain is enabled */
+  enabled: boolean;
+  /** LLM adapter status */
+  adapter: AdapterStatus;
+  /** Environment info */
+  environment: EnvironmentInfo;
+  /** Memory status */
+  memory: {
+    hasData: boolean;
+    sessionDuration: number;
+    idleTime: number;
+  };
+}
+
+/**
+ * Brain initialization options
+ */
+export interface BrainInitOptions {
+  /** Custom configuration */
+  config?: Partial<BrainConfig>;
+  /** Custom policy */
+  policy?: Partial<BrainPolicy>;
+  /** Custom adapter (for testing) */
+  adapter?: LLMAdapter;
+}
+
+/**
+ * Main Brain class
+ *
+ * Singleton pattern - use Brain.getInstance() to get the instance.
+ */
+export class Brain {
+  private static instance: Brain | null = null;
+
+  private config: BrainConfig;
+  private policy: BrainPolicy;
+  private adapter: LLMAdapter;
+  private memory: SessionMemory;
+  private environment: EnvironmentInfo;
+  private _enabled: boolean;
+  private _initialized: boolean = false;
+
+  private constructor(options: BrainInitOptions = {}) {
+    // Detect environment
+    this.environment = detectEnvironment();
+
+    // Set up policy
+    this.policy = {
+      ...DEFAULT_BRAIN_POLICY,
+      ...options.policy,
+    };
+
+    // Set up config
+    this.config = {
+      enabled: true,
+      autoApply: false, // Disabled by default
+      maxRetries: 3,
+      watch: {
+        debounceMs: 300,
+      },
+      ...options.config,
+    };
+
+    // Set up adapter
+    if (options.adapter) {
+      this.adapter = options.adapter;
+    } else if (this.config.adapter) {
+      this.adapter = createOllamaAdapter(this.config.adapter);
+    } else {
+      // Default: Ollama with default settings
+      this.adapter = createOllamaAdapter();
+    }
+
+    // Get session memory
+    this.memory = getSessionMemory();
+
+    // Initially disabled until initialized
+    this._enabled = false;
+  }
+
+  /**
+   * Get the singleton Brain instance
+   */
+  static getInstance(options?: BrainInitOptions): Brain {
+    if (!Brain.instance) {
+      Brain.instance = new Brain(options);
+    }
+    return Brain.instance;
+  }
+
+  /**
+   * Reset the singleton instance (for testing)
+   */
+  static resetInstance(): void {
+    Brain.instance = null;
+  }
+
+  /**
+   * Initialize Brain (async operations like checking adapter)
+   */
+  async initialize(): Promise<boolean> {
+    if (this._initialized) {
+      return this._enabled;
+    }
+
+    // Check adapter status
+    const adapterStatus = await this.checkAdapterStatus();
+    this.environment.modelAvailable = adapterStatus.available;
+
+    // Determine if Brain should be enabled
+    this._enabled = shouldEnableBrain(this.policy, this.environment);
+
+    this._initialized = true;
+
+    return this._enabled;
+  }
+
+  /**
+   * Check if Brain is enabled
+   */
+  get enabled(): boolean {
+    return this._enabled;
+  }
+
+  /**
+   * Check if Brain has been initialized
+   */
+  get initialized(): boolean {
+    return this._initialized;
+  }
+
+  /**
+   * Get the current adapter
+   */
+  getAdapter(): LLMAdapter {
+    return this.adapter;
+  }
+
+  /**
+   * Get the session memory
+   */
+  getMemory(): SessionMemory {
+    return this.memory;
+  }
+
+  /**
+   * Check adapter status
+   */
+  async checkAdapterStatus(): Promise<AdapterStatus> {
+    const { result } = await isolatedBrainExecution(
+      () => this.adapter.checkStatus(),
+      { available: false, model: null, error: "Check failed" }
+    );
+    return result;
+  }
+
+  /**
+   * Get full Brain status
+   */
+  async getStatus(): Promise<BrainStatus> {
+    const adapterStatus = await this.checkAdapterStatus();
+
+    return {
+      enabled: this._enabled,
+      adapter: adapterStatus,
+      environment: this.environment,
+      memory: {
+        hasData: this.memory.hasData(),
+        sessionDuration: this.memory.getSessionDuration(),
+        idleTime: this.memory.getIdleTime(),
+      },
+    };
+  }
+
+  /**
+   * Check if LLM is available for enhanced analysis
+   */
+  async isLLMAvailable(): Promise<boolean> {
+    const status = await this.checkAdapterStatus();
+    return status.available;
+  }
+
+  /**
+   * Execute a Brain operation with isolation
+   *
+   * Wraps operations to ensure Brain failures don't affect Core.
+   */
+  async execute<T>(
+    operation: () => Promise<T>,
+    fallback: T
+  ): Promise<{ result: T; error?: Error }> {
+    if (!this._enabled) {
+      return { result: fallback };
+    }
+
+    return isolatedBrainExecution(operation, fallback);
+  }
+
+  /**
+   * Generate a completion using the LLM adapter
+   *
+   * Returns empty string if LLM is not available.
+   */
+  async generate(prompt: string): Promise<string> {
+    if (!this._enabled) {
+      return "";
+    }
+
+    const { result } = await isolatedBrainExecution(
+      () => this.adapter.generate(prompt),
+      ""
+    );
+
+    return result;
+  }
+
+  /**
+   * Disable Brain
+   */
+  disable(): void {
+    this._enabled = false;
+  }
+
+  /**
+   * Enable Brain (only if conditions allow)
+   */
+  enable(): boolean {
+    const canEnable = shouldEnableBrain(this.policy, this.environment);
+    if (canEnable) {
+      this._enabled = true;
+    }
+    return this._enabled;
+  }
+
+  /**
+   * Get configuration
+   */
+  getConfig(): Readonly<BrainConfig> {
+    return { ...this.config };
+  }
+
+  /**
+   * Get policy
+   */
+  getPolicy(): Readonly<BrainPolicy> {
+    return { ...this.policy };
+  }
+
+  /**
+   * Get environment info
+   */
+  getEnvironment(): Readonly<EnvironmentInfo> {
+    return { ...this.environment };
+  }
+}
+
+/**
+ * Get or create the Brain instance
+ *
+ * Convenience function for accessing the singleton.
+ */
+export function getBrain(options?: BrainInitOptions): Brain {
+  return Brain.getInstance(options);
+}
+
+/**
+ * Initialize Brain and return its enabled status
+ *
+ * Convenience function for initialization.
+ */
+export async function initializeBrain(
+  options?: BrainInitOptions
+): Promise<boolean> {
+  const brain = getBrain(options);
+  return brain.initialize();
+}
+
+/**
+ * Check if Brain is available and enabled
+ *
+ * Safe check that handles uninitialized state.
+ */
+export function isBrainEnabled(): boolean {
+  try {
+    const brain = Brain.getInstance();
+    return brain.enabled;
+  } catch {
+    return false;
+  }
+}