maskweaver 0.9.4 → 0.9.5

package/dist/shared/image.js

@@ -1,20 +1,6 @@
-/**
- * @maskweaver/shared - Image Normalization Utilities
- *
- * LLM Vision API를 위한 이미지 정규화 유틸리티
- * 모든 주요 LLM (OpenAI, Claude, Gemini, Kimi)이 지원하는 포맷으로 변환
- *
- * 지원 포맷: JPEG, PNG, WebP, GIF (모든 LLM 공통)
- * 권장 설정: JPEG (최대 호환성), 2048x2048 이하
- */
 import * as fs from "node:fs";
 import * as path from "node:path";
-// ============================================================================
-// Constants
-// ============================================================================
-/** Universally supported formats across all major LLMs */
 const SUPPORTED_FORMATS = ["jpeg", "jpg", "png", "webp", "gif"];
-/** MIME type mappings */
 const MIME_TYPES = {
     jpeg: "image/jpeg",
     jpg: "image/jpeg",
@@ -22,25 +8,18 @@ const MIME_TYPES = {
     webp: "image/webp",
     gif: "image/gif",
 };
-/** Maximum dimensions by LLM (using most restrictive for safety) */
 const LLM_LIMITS = {
-    maxDimension: 2048, // Safe for all LLMs
-    maxFileSize: 20 * 1024 * 1024, // 20MB (OpenAI limit)
-    kimiMaxDimension: 4096, // Kimi allows up to 4K
-    claudeMaxDimension: 8000, // Claude allows up to 8000x8000
+    maxDimension: 2048,
+    maxFileSize: 20 * 1024 * 1024,
+    kimiMaxDimension: 4096,
+    claudeMaxDimension: 8000,
 };
-// ============================================================================
-// Image Detection (Pure JS - no dependencies)
-// ============================================================================
-/** Detect image format from magic bytes */
 function detectFormat(buffer) {
     if (buffer.length < 12)
         return null;
-    // JPEG: FF D8 FF
     if (buffer[0] === 0xff && buffer[1] === 0xd8 && buffer[2] === 0xff) {
         return "jpeg";
     }
-    // PNG: 89 50 4E 47 0D 0A 1A 0A
     if (buffer[0] === 0x89 &&
         buffer[1] === 0x50 &&
         buffer[2] === 0x4e &&
@@ -51,7 +30,6 @@ function detectFormat(buffer) {
         buffer[7] === 0x0a) {
         return "png";
     }
-    // WebP: RIFF....WEBP
     if (buffer[0] === 0x52 &&
         buffer[1] === 0x49 &&
         buffer[2] === 0x46 &&
@@ -62,7 +40,6 @@ function detectFormat(buffer) {
         buffer[11] === 0x50) {
         return "webp";
     }
-    // GIF: GIF87a or GIF89a
     if (buffer[0] === 0x47 &&
         buffer[1] === 0x49 &&
         buffer[2] === 0x46 &&
@@ -71,16 +48,13 @@ function detectFormat(buffer) {
         buffer[5] === 0x61) {
         return "gif";
     }
-    // BMP: BM
     if (buffer[0] === 0x42 && buffer[1] === 0x4d) {
         return "bmp";
     }
-    // TIFF: II or MM
     if ((buffer[0] === 0x49 && buffer[1] === 0x49) ||
         (buffer[0] === 0x4d && buffer[1] === 0x4d)) {
         return "tiff";
     }
-    // HEIC/HEIF: ftyp followed by heic, heix, mif1, etc.
     if (buffer[4] === 0x66 &&
         buffer[5] === 0x74 &&
         buffer[6] === 0x79 &&
@@ -92,25 +66,21 @@ function detectFormat(buffer) {
     }
     return null;
 }
-/** Get PNG dimensions (width, height) from header */
 function getPngDimensions(buffer) {
-    // PNG IHDR chunk starts at byte 8, width at 16, height at 20
     if (buffer.length < 24)
         return null;
     if (buffer[12] !== 0x49 || buffer[13] !== 0x48)
-        return null; // 'IH'
+        return null;
     const width = buffer.readUInt32BE(16);
     const height = buffer.readUInt32BE(20);
     return { width, height };
 }
-/** Get JPEG dimensions (more complex due to variable structure) */
 function getJpegDimensions(buffer) {
-    let offset = 2; // Skip SOI marker
+    let offset = 2;
     while (offset < buffer.length - 1) {
         if (buffer[offset] !== 0xff)
             return null;
         const marker = buffer[offset + 1];
-        // SOF markers (Start of Frame)
         if (marker >= 0xc0 &&
             marker <= 0xcf &&
             marker !== 0xc4 &&
@@ -122,7 +92,6 @@ function getJpegDimensions(buffer) {
             const width = buffer.readUInt16BE(offset + 7);
             return { width, height };
         }
-        // Skip to next marker
         if (marker === 0xd8 || marker === 0xd9) {
             offset += 2;
         }
@@ -136,7 +105,6 @@ function getJpegDimensions(buffer) {
     }
     return null;
 }
-/** Get image info without external dependencies */
 export function getImageInfo(input) {
     const buffer = typeof input === "string" ? fs.readFileSync(input) : input;
     const format = detectFormat(buffer);
@@ -157,29 +125,21 @@ export function getImageInfo(input) {
         hasAlpha: format === "png" || format === "webp",
     };
 }
-// ============================================================================
-// Normalization Logic
-// ============================================================================
-/** Check if format is supported by all LLMs */
 export function isSupported(format) {
     return SUPPORTED_FORMATS.includes(format.toLowerCase());
 }
-/** Check if image needs conversion */
 export function needsConversion(info, options) {
     const reasons = [];
     const maxDim = options?.maxDimension ?? LLM_LIMITS.maxDimension;
-    // Format not supported
     if (!isSupported(info.format)) {
         reasons.push(`Format '${info.format}' not supported by all LLMs`);
     }
-    // Too large
     if (info.width && info.width > maxDim) {
         reasons.push(`Width ${info.width}px exceeds max ${maxDim}px`);
     }
     if (info.height && info.height > maxDim) {
         reasons.push(`Height ${info.height}px exceeds max ${maxDim}px`);
     }
-    // File too big
     if (info.sizeBytes > LLM_LIMITS.maxFileSize) {
         reasons.push(`File size ${(info.sizeBytes / 1024 / 1024).toFixed(1)}MB exceeds 20MB limit`);
     }
@@ -188,28 +148,6 @@ export function needsConversion(info, options) {
         reasons,
     };
 }
-/**
- * Normalize an image for LLM Vision API compatibility
- *
- * This is the main entry point. It will:
- * 1. Detect image format
- * 2. Check if conversion is needed
- * 3. Convert if necessary (requires sharp)
- * 4. Return base64-encoded result
- *
- * @example
- * ```typescript
- * import { normalizeImage } from 'maskweaver/shared';
- *
- * // From file path
- * const result = await normalizeImage('/path/to/screenshot.png');
- * console.log(result.base64); // Use in LLM API
- *
- * // From buffer
- * const buffer = fs.readFileSync('/path/to/image.bmp');
- * const result = await normalizeImage(buffer, { format: 'jpeg' });
- * ```
- */
 export async function normalizeImage(input, options) {
     const buffer = typeof input === "string" ? fs.readFileSync(input) : input;
     const originalPath = typeof input === "string" ? input : undefined;
@@ -219,7 +157,6 @@ export async function normalizeImage(input, options) {
         throw new Error("Unable to detect image format. File may be corrupted or unsupported.");
     }
     const checkResult = needsConversion(info, options);
-    // If no conversion needed, return as-is
     if (!checkResult.needsConversion) {
         return {
             base64: buffer.toString("base64"),
@@ -228,14 +165,10 @@ export async function normalizeImage(input, options) {
             converted: false,
         };
     }
-    // Conversion needed - try to use sharp if available
     warnings.push(...checkResult.reasons);
     try {
-        // Dynamic import to avoid hard dependency
-        // eslint-disable-next-line @typescript-eslint/no-require-imports
         const sharp = await (async () => {
             try {
-                // Use Function constructor to avoid static analysis
                 const importFn = new Function('modulePath', 'return import(modulePath)');
                 return await importFn('sharp');
             }
@@ -244,9 +177,7 @@ export async function normalizeImage(input, options) {
             }
         })();
         if (!sharp) {
-            // No sharp available - return with warnings
             if (isSupported(info.format)) {
-                // Format is OK, just size issues - return anyway with warning
                 warnings.push("Image may be too large. Install 'sharp' for automatic resizing.");
                 return {
                     base64: buffer.toString("base64"),
@@ -260,12 +191,10 @@ export async function normalizeImage(input, options) {
                 throw new Error(`Image format '${info.format}' requires conversion. Install 'sharp' package: npm install sharp`);
             }
         }
-        // Use sharp for conversion
         const targetFormat = options?.format ?? "jpeg";
         const maxDim = options?.maxDimension ?? LLM_LIMITS.maxDimension;
         const quality = options?.quality ?? 85;
         let pipeline = sharp.default(buffer);
-        // Resize if needed
         if ((info.width && info.width > maxDim) ||
             (info.height && info.height > maxDim)) {
             pipeline = pipeline.resize(maxDim, maxDim, {
@@ -273,7 +202,6 @@ export async function normalizeImage(input, options) {
                 withoutEnlargement: true,
             });
         }
-        // Convert format
         if (targetFormat === "jpeg") {
             pipeline = pipeline.jpeg({ quality });
         }
@@ -299,22 +227,9 @@ export async function normalizeImage(input, options) {
         throw new Error(`Image conversion failed: ${error}`);
     }
 }
-/**
- * Normalize image and save to file
- *
- * @example
- * ```typescript
- * const outputPath = await normalizeImageToFile(
- *   '/path/to/screenshot.bmp',
- *   '/path/to/output.jpg',
- *   { format: 'jpeg', quality: 90 }
- * );
- * ```
- */
 export async function normalizeImageToFile(input, outputPath, options) {
     const result = await normalizeImage(input, options);
     const buffer = Buffer.from(result.base64, "base64");
-    // Ensure directory exists
     const dir = path.dirname(outputPath);
     if (!fs.existsSync(dir)) {
         fs.mkdirSync(dir, { recursive: true });
@@ -322,15 +237,11 @@ export async function normalizeImageToFile(input, outputPath, options) {
     fs.writeFileSync(outputPath, buffer);
     return outputPath;
 }
-/**
- * Quick check if an image file is LLM-compatible without loading full file
- */
 export function isLLMCompatible(filePath) {
     const issues = [];
     if (!fs.existsSync(filePath)) {
         return { compatible: false, format: null, issues: ["File not found"] };
     }
-    // Read only first 24 bytes for format detection
     const fd = fs.openSync(filePath, "r");
     const header = Buffer.alloc(24);
     fs.readSync(fd, header, 0, 24, 0);
@@ -352,15 +263,6 @@ export function isLLMCompatible(filePath) {
         issues,
     };
 }
-/**
- * Create LLM-ready image data URL
- *
- * @example
- * ```typescript
- * const dataUrl = await createImageDataUrl('/path/to/image.png');
- * // Returns: "data:image/png;base64,iVBORw0KGgo..."
- * ```
- */
 export async function createImageDataUrl(input, options) {
     const result = await normalizeImage(input, options);
     return `data:${result.mimeType};base64,${result.base64}`;

package/dist/shared/index.d.ts

@@ -1,8 +1,3 @@
-/**
- * @maskweaver/shared
- *
- * Common types, errors, and configuration for Maskweaver
- */
 export type { Result, HealthCheckResult, LogLevel, FeatureStatus, } from "./types.js";
 export { MaskweaverError, ConfigError, ProviderError, StorageError, ValidationError, } from "./errors.js";
 export type { MemoryProviderType, VerifyMode, ReviewerType, RetrospectDepth, ContextConfig, MemoryConfig, RetrospectConfig, VerifyConfig, FeaturesConfig, MemoryProviderConfigs, VerifyConfigOptions, LoggingConfig, MaskweaverConfig, } from "./config.js";

package/dist/shared/index.js

@@ -1,11 +1,4 @@
-/**
- * @maskweaver/shared
- *
- * Common types, errors, and configuration for Maskweaver
- */
-// Errors
 export { MaskweaverError, ConfigError, ProviderError, StorageError, ValidationError, } from "./errors.js";
 export { DEFAULT_CONFIG } from "./config.js";
 export { normalizeImage, normalizeImageToFile, getImageInfo, isSupported, needsConversion, isLLMCompatible, createImageDataUrl, } from "./image.js";
-// Agent generation from pool config
 export { generatePoolAgentFiles, generatePoolAgentFilesFromConfig, writeDefaultRuntimeConfig, writeDefaultPluginConfig, findUserGlobalConfig, DEFAULT_RUNTIME_CONFIG_TEMPLATE, DEFAULT_PLUGIN_CONFIG_TEMPLATE, } from "./generate-agents.js";

package/dist/shared/model-registry.d.ts

@@ -1,108 +1,46 @@
-/**
- * Model Registry
- *
- * Manages the pool of available AI models with:
- * - Concurrency tracking (max N simultaneous uses per model)
- * - Capability-based matching (task → best model)
- * - Tier-based fallback (if preferred model is full, find similar)
- * - Cost-aware scheduling (prefer cheaper models for simple tasks)
- *
- * "The art of programming is the art of organizing complexity." - Dijkstra
- *
- * @author Mask Weaver
- */
 import type { ModelPoolEntry, ModelTier, ModelCapability } from './config.js';
-/** Runtime state for a model in the pool */
 export interface ModelSlot {
-    /** The model definition from config */
     entry: ModelPoolEntry;
-    /** Current number of active uses */
     activeCount: number;
-    /** Whether this model has available slots */
     available: boolean;
-    /** Remaining available slots */
     remainingSlots: number;
 }
-/** Options for acquiring a model */
 export interface AcquireOptions {
-    /** Preferred tier (flash/human/premium) */
     tier?: ModelTier;
-    /** Required capabilities (at least one must match) */
     capabilities?: ModelCapability[];
-    /** Prefer lower cost when multiple models match */
     preferCheap?: boolean;
-    /** Specific model ID to request */
     modelId?: string;
 }
-/** Result of a model acquisition attempt */
 export interface AcquireResult {
-    /** Whether a model was successfully acquired */
     success: boolean;
-    /** The acquired model slot (if success) */
     slot?: ModelSlot;
-    /** The agent name to use (e.g., "dummy-gemini-flash") */
     agentName?: string;
-    /** Reason for failure (if not success) */
     reason?: string;
-    /** Suggested alternative if primary choice unavailable */
     suggestion?: string;
 }
-/** Snapshot of all model statuses */
 export interface RegistryStatus {
-    /** All model slots with their current state */
     models: ModelSlot[];
-    /** Total capacity across all models */
     totalCapacity: number;
-    /** Currently in use */
     totalActive: number;
-    /** Available slots */
     totalAvailable: number;
 }
 export declare class ModelRegistry {
     private pool;
     private activeCountMap;
     constructor(pool: ModelPoolEntry[]);
-    /**
-     * Acquire a model from the pool.
-     *
-     * Selection strategy:
-     * 1. If modelId specified → try that exact model
-     * 2. Filter by tier preference
-     * 3. Filter by required capabilities
-     * 4. Among candidates, pick best available (cost-aware)
-     * 5. If no match in preferred tier, try fallback tiers
-     */
     acquire(options?: AcquireOptions): AcquireResult;
-    /**
-     * Release a model back to the pool.
-     * Must be called when a task using this model completes.
-     */
     release(modelId: string): boolean;
-    /** Get the current status of all models in the pool */
     getStatus(): RegistryStatus;
-    /** Get available models for a specific tier */
     getAvailableForTier(tier: ModelTier): ModelSlot[];
-    /** Get all models with a specific capability */
     getModelsWithCapability(capability: ModelCapability): ModelSlot[];
-    /** Get the total concurrency available for a tier (including fallbacks) */
     getTierConcurrency(tier: ModelTier): {
         total: number;
         available: number;
         models: string[];
     };
-    /** Get the pool entries */
     getPool(): ModelPoolEntry[];
-    /** Get the agent name for a pool entry */
     getAgentName(entry: ModelPoolEntry): string;
-    /**
-     * Recommend the best model for a task based on its capabilities.
-     * Does NOT acquire — just suggests.
-     */
     recommend(options?: AcquireOptions): ModelPoolEntry | null;
-    /**
-     * Compute maximum parallelism for a set of tasks.
-     * Given N tasks of different tiers, returns how many can run simultaneously.
-     */
     computeMaxParallelism(taskTiers: ModelTier[]): number;
     private getSlot;
     private tryAcquire;
@@ -110,16 +48,6 @@ export declare class ModelRegistry {
     private sortCandidates;
     private suggestWait;
 }
-/**
- * Get the global model registry.
- * Lazily initialized from maskweaver.config.json.
- */
 export declare function getModelRegistry(basePath?: string): ModelRegistry;
-/**
- * Reset the registry (for testing or config reload).
- */
 export declare function resetModelRegistry(): void;
-/**
- * Create a fresh registry from explicit pool entries.
- */
 export declare function createModelRegistry(pool: ModelPoolEntry[]): ModelRegistry;