@sparkleideas/shared 3.0.0-alpha.7

package/src/core/config/loader.ts

@@ -0,0 +1,271 @@
+/**
+ * V3 Configuration Loader
+ * Load configuration from various sources
+ */
+
+import { readFile } from 'fs/promises';
+import { join, resolve } from 'path';
+import { existsSync } from 'fs';
+import type { SystemConfig } from './schema.js';
+import { validateSystemConfig, type ValidationResult } from './validator.js';
+import { defaultSystemConfig, mergeWithDefaults } from './defaults.js';
+
+/**
+ * Configuration source type
+ */
+export type ConfigSource = 'file' | 'env' | 'default' | 'merged';
+
+/**
+ * Loaded configuration with metadata
+ */
+export interface LoadedConfig {
+  config: SystemConfig;
+  source: ConfigSource;
+  path?: string;
+  warnings?: string[];
+}
+
+/**
+ * Configuration file names to search for
+ */
+const CONFIG_FILE_NAMES = [
+  '@sparkleideas/claude-flow.config.json',
+  '@sparkleideas/claude-flow.config.js',
+  '@sparkleideas/claude-flow.json',
+  '.@sparkleideas/claude-flow.json',
+];
+
+/**
+ * Find configuration file in directory
+ */
+async function findConfigFile(directory: string): Promise<string | null> {
+  for (const name of CONFIG_FILE_NAMES) {
+    const path = join(directory, name);
+    if (existsSync(path)) {
+      return path;
+    }
+  }
+  return null;
+}
+
+/**
+ * Load configuration from JSON file
+ */
+async function loadJsonConfig(path: string): Promise<unknown> {
+  const content = await readFile(path, 'utf8');
+  return JSON.parse(content);
+}
+
+/**
+ * Load configuration from environment variables
+ */
+function loadEnvConfig(): Partial<SystemConfig> {
+  const config: Partial<SystemConfig> = {};
+
+  // Orchestrator settings
+  if (process.env.CLAUDE_FLOW_MAX_AGENTS) {
+    config.orchestrator = {
+      ...defaultSystemConfig.orchestrator,
+      lifecycle: {
+        ...defaultSystemConfig.orchestrator.lifecycle,
+        maxConcurrentAgents: parseInt(process.env.CLAUDE_FLOW_MAX_AGENTS, 10),
+      },
+    };
+  }
+
+  // Data directory
+  if (process.env.CLAUDE_FLOW_DATA_DIR) {
+    config.orchestrator = {
+      ...config.orchestrator,
+      ...defaultSystemConfig.orchestrator,
+      session: {
+        ...defaultSystemConfig.orchestrator.session,
+        dataDir: process.env.CLAUDE_FLOW_DATA_DIR,
+      },
+    };
+  }
+
+  // Memory type
+  if (process.env.CLAUDE_FLOW_MEMORY_TYPE) {
+    const memoryType = process.env.CLAUDE_FLOW_MEMORY_TYPE as NonNullable<SystemConfig['memory']>['type'];
+    if (['sqlite', '@sparkleideas/agentdb', 'hybrid', 'redis', 'memory'].includes(memoryType)) {
+      config.memory = {
+        ...(defaultSystemConfig.memory ?? { type: 'hybrid' }),
+        type: memoryType,
+      };
+    }
+  }
+
+  // MCP transport
+  const defaultMcp = defaultSystemConfig.mcp ?? { name: '@sparkleideas/claude-flow', version: '3.0.0', transport: { type: 'stdio' as const } };
+  if (process.env.CLAUDE_FLOW_MCP_TRANSPORT) {
+    const transport = process.env.CLAUDE_FLOW_MCP_TRANSPORT as 'stdio' | 'http' | 'websocket';
+    if (['stdio', 'http', 'websocket'].includes(transport)) {
+      config.mcp = {
+        ...defaultMcp,
+        transport: {
+          ...defaultMcp.transport,
+          type: transport,
+        },
+      };
+    }
+  }
+
+  if (process.env.CLAUDE_FLOW_MCP_PORT) {
+    config.mcp = {
+      ...config.mcp,
+      ...defaultMcp,
+      transport: {
+        ...config.mcp?.transport,
+        ...defaultMcp.transport,
+        port: parseInt(process.env.CLAUDE_FLOW_MCP_PORT, 10),
+      },
+    };
+  }
+
+  // Swarm topology
+  const defaultSwarm = defaultSystemConfig.swarm ?? { topology: 'hierarchical-mesh' as const, maxAgents: 20 };
+  if (process.env.CLAUDE_FLOW_SWARM_TOPOLOGY) {
+    const topology = process.env.CLAUDE_FLOW_SWARM_TOPOLOGY as NonNullable<SystemConfig['swarm']>['topology'];
+    if (['hierarchical', 'mesh', 'ring', 'star', 'adaptive', 'hierarchical-mesh'].includes(topology)) {
+      config.swarm = {
+        ...defaultSwarm,
+        topology,
+      };
+    }
+  }
+
+  return config;
+}
+
+/**
+ * Configuration loader class
+ */
+export class ConfigLoader {
+  private searchPaths: string[] = [];
+
+  constructor(additionalPaths?: string[]) {
+    // Default search paths
+    this.searchPaths = [
+      process.cwd(),
+      resolve(process.cwd(), '..'),
+      resolve(process.env.HOME ?? '', '.@sparkleideas/claude-flow'),
+    ];
+
+    if (additionalPaths) {
+      this.searchPaths.push(...additionalPaths);
+    }
+  }
+
+  /**
+   * Load configuration from all sources
+   */
+  async load(): Promise<LoadedConfig> {
+    const warnings: string[] = [];
+
+    // Start with defaults
+    let config: SystemConfig = { ...defaultSystemConfig };
+    let source: ConfigSource = 'default';
+    let path: string | undefined;
+
+    // Try to load from file
+    for (const searchPath of this.searchPaths) {
+      const configPath = await findConfigFile(searchPath);
+      if (configPath) {
+        try {
+          const fileConfig = await loadJsonConfig(configPath);
+          const validation = validateSystemConfig(fileConfig);
+
+          if (validation.success) {
+            config = mergeWithDefaults(validation.data!, defaultSystemConfig) as SystemConfig;
+            source = 'file';
+            path = configPath;
+            break;
+          } else {
+            warnings.push(`Invalid config at ${configPath}: ${validation.errors?.map(e => e.message).join(', ')}`);
+          }
+        } catch (error) {
+          warnings.push(`Failed to load config from ${configPath}: ${(error as Error).message}`);
+        }
+      }
+    }
+
+    // Merge with environment variables
+    const envConfig = loadEnvConfig();
+    if (Object.keys(envConfig).length > 0) {
+      config = this.deepMerge(config, envConfig) as SystemConfig;
+      source = source === 'default' ? 'env' : 'merged';
+    }
+
+    return {
+      config,
+      source,
+      path,
+      warnings: warnings.length > 0 ? warnings : undefined,
+    };
+  }
+
+  /**
+   * Load configuration from specific file
+   */
+  async loadFromFile(filePath: string): Promise<LoadedConfig> {
+    const absolutePath = resolve(filePath);
+    const fileConfig = await loadJsonConfig(absolutePath);
+    const validation = validateSystemConfig(fileConfig);
+
+    if (!validation.success) {
+      throw new Error(`Invalid configuration: ${validation.errors?.map(e => e.message).join(', ')}`);
+    }
+
+    const config = mergeWithDefaults(validation.data!, defaultSystemConfig) as SystemConfig;
+
+    return {
+      config,
+      source: 'file',
+      path: absolutePath,
+    };
+  }
+
+  /**
+   * Deep merge objects
+   */
+  private deepMerge(target: Record<string, unknown>, source: Record<string, unknown>): Record<string, unknown> {
+    const result = { ...target };
+
+    for (const key of Object.keys(source)) {
+      const sourceValue = source[key];
+      const targetValue = target[key];
+
+      if (
+        sourceValue &&
+        typeof sourceValue === 'object' &&
+        !Array.isArray(sourceValue) &&
+        targetValue &&
+        typeof targetValue === 'object' &&
+        !Array.isArray(targetValue)
+      ) {
+        result[key] = this.deepMerge(
+          targetValue as Record<string, unknown>,
+          sourceValue as Record<string, unknown>,
+        );
+      } else if (sourceValue !== undefined) {
+        result[key] = sourceValue;
+      }
+    }
+
+    return result;
+  }
+}
+
+/**
+ * Load configuration (convenience function)
+ */
+export async function loadConfig(options?: { paths?: string[]; file?: string }): Promise<LoadedConfig> {
+  const loader = new ConfigLoader(options?.paths);
+
+  if (options?.file) {
+    return loader.loadFromFile(options.file);
+  }
+
+  return loader.load();
+}

package/src/core/config/schema.ts

@@ -0,0 +1,188 @@
+/**
+ * V3 Configuration Schemas
+ * Zod schemas for all configuration types
+ */
+
+import { z } from 'zod';
+
+/**
+ * Agent configuration schema
+ */
+export const AgentConfigSchema = z.object({
+  id: z.string().min(1),
+  name: z.string().min(1),
+  type: z.string().min(1),
+  capabilities: z.array(z.string()).default([]),
+  maxConcurrentTasks: z.number().int().min(1).default(5),
+  priority: z.number().int().min(0).max(100).default(50),
+  timeout: z.number().int().positive().optional(),
+  retryPolicy: z.object({
+    maxRetries: z.number().int().min(0).default(3),
+    backoffMs: z.number().int().positive().default(1000),
+    backoffMultiplier: z.number().positive().default(2),
+  }).optional(),
+  resources: z.object({
+    maxMemoryMb: z.number().int().positive().optional(),
+    maxCpuPercent: z.number().min(0).max(100).optional(),
+  }).optional(),
+  metadata: z.record(z.unknown()).optional(),
+});
+
+/**
+ * Task configuration schema
+ */
+export const TaskConfigSchema = z.object({
+  type: z.string().min(1),
+  description: z.string().min(1),
+  priority: z.number().int().min(0).max(100).default(50),
+  timeout: z.number().int().positive().optional(),
+  assignedAgent: z.string().optional(),
+  input: z.record(z.unknown()).optional(),
+  metadata: z.object({
+    requiredCapabilities: z.array(z.string()).optional(),
+    retryCount: z.number().int().min(0).optional(),
+    maxRetries: z.number().int().min(0).optional(),
+    critical: z.boolean().optional(),
+    parentTaskId: z.string().optional(),
+    childTaskIds: z.array(z.string()).optional(),
+    tags: z.array(z.string()).optional(),
+  }).optional(),
+});
+
+/**
+ * Swarm configuration schema
+ */
+export const SwarmConfigSchema = z.object({
+  topology: z.enum(['hierarchical', 'mesh', 'ring', 'star', 'adaptive', 'hierarchical-mesh']),
+  maxAgents: z.number().int().positive().default(20),
+  autoScale: z.object({
+    enabled: z.boolean().default(false),
+    minAgents: z.number().int().min(0).default(1),
+    maxAgents: z.number().int().positive().default(20),
+    scaleUpThreshold: z.number().min(0).max(1).default(0.8),
+    scaleDownThreshold: z.number().min(0).max(1).default(0.3),
+  }).optional(),
+  coordination: z.object({
+    consensusRequired: z.boolean().default(false),
+    timeoutMs: z.number().int().positive().default(10000),
+    retryPolicy: z.object({
+      maxRetries: z.number().int().min(0).default(3),
+      backoffMs: z.number().int().positive().default(500),
+    }),
+  }).optional(),
+  communication: z.object({
+    protocol: z.enum(['events', 'messages', 'shared-memory']).default('events'),
+    batchSize: z.number().int().positive().default(10),
+    flushIntervalMs: z.number().int().positive().default(100),
+  }).optional(),
+  metadata: z.record(z.unknown()).optional(),
+});
+
+/**
+ * Memory configuration schema
+ */
+export const MemoryConfigSchema = z.object({
+  type: z.enum(['sqlite', '@sparkleideas/agentdb', 'hybrid', 'redis', 'memory']).default('hybrid'),
+  path: z.string().optional(),
+  maxSize: z.number().int().positive().optional(),
+  ttlMs: z.number().int().positive().optional(),
+  sqlite: z.object({
+    filename: z.string().optional(),
+    inMemory: z.boolean().default(false),
+    wal: z.boolean().default(true),
+  }).optional(),
+  @sparkleideas/agentdb: z.object({
+    dimensions: z.number().int().positive().default(1536),
+    indexType: z.enum(['hnsw', 'flat', 'ivf']).default('hnsw'),
+    efConstruction: z.number().int().positive().default(200),
+    m: z.number().int().positive().default(16),
+    quantization: z.enum(['none', 'scalar', 'product']).default('none'),
+  }).optional(),
+  redis: z.object({
+    host: z.string().default('localhost'),
+    port: z.number().int().positive().default(6379),
+    password: z.string().optional(),
+    db: z.number().int().min(0).default(0),
+    keyPrefix: z.string().default('@sparkleideas/claude-flow:'),
+  }).optional(),
+  hybrid: z.object({
+    vectorThreshold: z.number().int().positive().default(100),
+  }).optional(),
+});
+
+/**
+ * MCP server configuration schema
+ */
+export const MCPServerConfigSchema = z.object({
+  name: z.string().min(1).default('@sparkleideas/claude-flow'),
+  version: z.string().min(1).default('3.0.0'),
+  transport: z.object({
+    type: z.enum(['stdio', 'http', 'websocket']).default('stdio'),
+    port: z.number().int().positive().optional(),
+    host: z.string().optional(),
+    path: z.string().optional(),
+  }),
+  capabilities: z.object({
+    tools: z.boolean().default(true),
+    resources: z.boolean().default(true),
+    prompts: z.boolean().default(true),
+    logging: z.boolean().default(true),
+    experimental: z.record(z.boolean()).optional(),
+  }).optional(),
+});
+
+/**
+ * Orchestrator configuration schema
+ */
+export const OrchestratorConfigSchema = z.object({
+  session: z.object({
+    persistSessions: z.boolean().default(true),
+    dataDir: z.string().default('./data'),
+    sessionRetentionMs: z.number().int().positive().default(3600000),
+  }),
+  health: z.object({
+    checkInterval: z.number().int().positive().default(30000),
+    historyLimit: z.number().int().positive().default(100),
+    degradedThreshold: z.number().int().min(0).default(1),
+    unhealthyThreshold: z.number().int().min(0).default(2),
+  }),
+  lifecycle: z.object({
+    maxConcurrentAgents: z.number().int().positive().default(20),
+    spawnTimeout: z.number().int().positive().default(30000),
+    terminateTimeout: z.number().int().positive().default(10000),
+    maxSpawnRetries: z.number().int().min(0).default(3),
+  }),
+});
+
+/**
+ * Full system configuration schema
+ */
+export const SystemConfigSchema = z.object({
+  orchestrator: OrchestratorConfigSchema,
+  memory: MemoryConfigSchema.optional(),
+  mcp: MCPServerConfigSchema.optional(),
+  swarm: SwarmConfigSchema.optional(),
+});
+
+/**
+ * Export schema types
+ * Using z.output to get post-default types (fields with defaults are required in output)
+ */
+export type AgentConfig = z.output<typeof AgentConfigSchema>;
+export type TaskConfig = z.output<typeof TaskConfigSchema>;
+export type SwarmConfig = z.output<typeof SwarmConfigSchema>;
+export type MemoryConfig = z.output<typeof MemoryConfigSchema>;
+export type MCPServerConfig = z.output<typeof MCPServerConfigSchema>;
+export type OrchestratorConfig = z.output<typeof OrchestratorConfigSchema>;
+export type SystemConfig = z.output<typeof SystemConfigSchema>;
+
+/**
+ * Input types (for validation before defaults are applied)
+ */
+export type AgentConfigInput = z.input<typeof AgentConfigSchema>;
+export type TaskConfigInput = z.input<typeof TaskConfigSchema>;
+export type SwarmConfigInput = z.input<typeof SwarmConfigSchema>;
+export type MemoryConfigInput = z.input<typeof MemoryConfigSchema>;
+export type MCPServerConfigInput = z.input<typeof MCPServerConfigSchema>;
+export type OrchestratorConfigInput = z.input<typeof OrchestratorConfigSchema>;
+export type SystemConfigInput = z.input<typeof SystemConfigSchema>;

package/src/core/config/validator.ts

@@ -0,0 +1,209 @@
+/**
+ * V3 Configuration Validator
+ * Validation logic using Zod schemas
+ */
+
+import { z, type ZodError } from 'zod';
+import {
+  AgentConfigSchema,
+  TaskConfigSchema,
+  SwarmConfigSchema,
+  MemoryConfigSchema,
+  MCPServerConfigSchema,
+  OrchestratorConfigSchema,
+  SystemConfigSchema,
+  type AgentConfig,
+  type TaskConfig,
+  type SwarmConfig,
+  type MemoryConfig,
+  type MCPServerConfig,
+  type OrchestratorConfig,
+  type SystemConfig,
+} from './schema.js';
+
+/**
+ * Validation result
+ */
+export interface ValidationResult<T> {
+  success: boolean;
+  data?: T;
+  errors?: ValidationError[];
+}
+
+/**
+ * Validation error
+ */
+export interface ValidationError {
+  path: string;
+  message: string;
+  code: string;
+}
+
+/**
+ * Convert Zod error to validation errors
+ */
+function zodErrorToValidationErrors(error: ZodError): ValidationError[] {
+  return error.errors.map((e) => ({
+    path: e.path.join('.'),
+    message: e.message,
+    code: e.code,
+  }));
+}
+
+/**
+ * Generic validation function
+ * Uses parse + try/catch to get output types with defaults applied
+ */
+function validate<TInput, TOutput>(
+  schema: z.ZodType<TOutput, z.ZodTypeDef, TInput>,
+  data: unknown
+): ValidationResult<TOutput> {
+  try {
+    const parsed = schema.parse(data);
+    return {
+      success: true,
+      data: parsed,
+    };
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      return {
+        success: false,
+        errors: zodErrorToValidationErrors(error),
+      };
+    }
+    throw error;
+  }
+}
+
+/**
+ * Validate agent configuration
+ */
+export function validateAgentConfig(data: unknown): ValidationResult<AgentConfig> {
+  return validate(AgentConfigSchema, data);
+}
+
+/**
+ * Validate task configuration
+ */
+export function validateTaskConfig(data: unknown): ValidationResult<TaskConfig> {
+  return validate(TaskConfigSchema, data);
+}
+
+/**
+ * Validate swarm configuration
+ */
+export function validateSwarmConfig(data: unknown): ValidationResult<SwarmConfig> {
+  return validate(SwarmConfigSchema, data);
+}
+
+/**
+ * Validate memory configuration
+ */
+export function validateMemoryConfig(data: unknown): ValidationResult<MemoryConfig> {
+  return validate(MemoryConfigSchema, data);
+}
+
+/**
+ * Validate MCP server configuration
+ */
+export function validateMCPServerConfig(data: unknown): ValidationResult<MCPServerConfig> {
+  return validate(MCPServerConfigSchema, data);
+}
+
+/**
+ * Validate orchestrator configuration
+ */
+export function validateOrchestratorConfig(data: unknown): ValidationResult<OrchestratorConfig> {
+  return validate(OrchestratorConfigSchema, data);
+}
+
+/**
+ * Validate full system configuration
+ */
+export function validateSystemConfig(data: unknown): ValidationResult<SystemConfig> {
+  return validate(SystemConfigSchema, data);
+}
+
+/**
+ * Configuration validator class
+ */
+export class ConfigValidator {
+  /**
+   * Validate and throw on error
+   */
+  static validateOrThrow<TInput, TOutput>(
+    schema: z.ZodType<TOutput, z.ZodTypeDef, TInput>,
+    data: unknown,
+    configName: string
+  ): TOutput {
+    const result = validate(schema, data);
+
+    if (!result.success) {
+      const errorMessages = result.errors
+        ?.map((e) => `  - ${e.path}: ${e.message}`)
+        .join('\n');
+      throw new Error(`Invalid ${configName} configuration:\n${errorMessages}`);
+    }
+
+    return result.data!;
+  }
+
+  /**
+   * Validate agent config or throw
+   */
+  static validateAgentOrThrow(data: unknown): AgentConfig {
+    return this.validateOrThrow(AgentConfigSchema, data, 'agent');
+  }
+
+  /**
+   * Validate task config or throw
+   */
+  static validateTaskOrThrow(data: unknown): TaskConfig {
+    return this.validateOrThrow(TaskConfigSchema, data, 'task');
+  }
+
+  /**
+   * Validate swarm config or throw
+   */
+  static validateSwarmOrThrow(data: unknown): SwarmConfig {
+    return this.validateOrThrow(SwarmConfigSchema, data, 'swarm');
+  }
+
+  /**
+   * Validate memory config or throw
+   */
+  static validateMemoryOrThrow(data: unknown): MemoryConfig {
+    return this.validateOrThrow(MemoryConfigSchema, data, 'memory');
+  }
+
+  /**
+   * Validate MCP server config or throw
+   */
+  static validateMCPServerOrThrow(data: unknown): MCPServerConfig {
+    return this.validateOrThrow(MCPServerConfigSchema, data, 'MCP server');
+  }
+
+  /**
+   * Validate orchestrator config or throw
+   */
+  static validateOrchestratorOrThrow(data: unknown): OrchestratorConfig {
+    return this.validateOrThrow(OrchestratorConfigSchema, data, 'orchestrator');
+  }
+
+  /**
+   * Validate system config or throw
+   */
+  static validateSystemOrThrow(data: unknown): SystemConfig {
+    return this.validateOrThrow(SystemConfigSchema, data, 'system');
+  }
+
+  /**
+   * Check if data matches schema
+   */
+  static isValid<TInput, TOutput>(
+    schema: z.ZodType<TOutput, z.ZodTypeDef, TInput>,
+    data: unknown
+  ): boolean {
+    return validate(schema, data).success;
+  }
+}