@sylphx/flow 1.0.1 → 1.0.3

package/src/core/interfaces/service.interface.ts

@@ -0,0 +1,133 @@
+/**
+ * Service interfaces for dependency inversion
+ * Core service contracts
+ *
+ * DESIGN RATIONALE:
+ * - Depend on abstractions, not implementations
+ * - Clear contracts for services
+ * - Enables dependency injection
+ * - Facilitates testing with mocks
+ */
+
+import type { AppError } from '../functional/error-types.js';
+import type { Result } from '../functional/result.js';
+
+/**
+ * Logger interface
+ */
+export interface ILogger {
+  debug(message: string, ...args: any[]): void;
+  info(message: string, ...args: any[]): void;
+  warn(message: string, ...args: any[]): void;
+  error(message: string, ...args: any[]): void;
+}
+
+/**
+ * Configuration service interface
+ */
+export interface IConfigService {
+  /**
+   * Get configuration value
+   */
+  get<T>(key: string): Result<T, AppError>;
+
+  /**
+   * Get configuration value with default
+   */
+  getOrDefault<T>(key: string, defaultValue: T): T;
+
+  /**
+   * Set configuration value
+   */
+  set<T>(key: string, value: T): Result<void, AppError>;
+
+  /**
+   * Check if configuration key exists
+   */
+  has(key: string): boolean;
+
+  /**
+   * Load configuration from file
+   */
+  load(path: string): Promise<Result<void, AppError>>;
+
+  /**
+   * Save configuration to file
+   */
+  save(path: string): Promise<Result<void, AppError>>;
+}
+
+/**
+ * File service interface
+ */
+export interface IFileService {
+  /**
+   * Read file contents
+   */
+  read(path: string): Promise<Result<string, AppError>>;
+
+  /**
+   * Write file contents
+   */
+  write(path: string, content: string): Promise<Result<void, AppError>>;
+
+  /**
+   * Check if file exists
+   */
+  exists(path: string): Promise<Result<boolean, AppError>>;
+
+  /**
+   * Delete file
+   */
+  delete(path: string): Promise<Result<void, AppError>>;
+
+  /**
+   * List files in directory
+   */
+  list(path: string): Promise<Result<string[], AppError>>;
+
+  /**
+   * Create directory
+   */
+  createDir(path: string, recursive?: boolean): Promise<Result<void, AppError>>;
+}
+
+/**
+ * Validation service interface
+ */
+export interface IValidationService<T> {
+  /**
+   * Validate data
+   */
+  validate(data: unknown): Result<T, AppError>;
+
+  /**
+   * Validate and return errors
+   */
+  validateWithErrors(data: unknown): Result<T, string[]>;
+}
+
+/**
+ * Event emitter interface for event-driven architecture
+ */
+export interface IEventEmitter<EventMap extends Record<string, any>> {
+  /**
+   * Emit an event
+   */
+  emit<K extends keyof EventMap>(event: K, data: EventMap[K]): void;
+
+  /**
+   * Subscribe to an event
+   */
+  on<K extends keyof EventMap>(event: K, handler: (data: EventMap[K]) => void): () => void;
+
+  /**
+   * Subscribe to an event once
+   */
+  once<K extends keyof EventMap>(event: K, handler: (data: EventMap[K]) => void): () => void;
+
+  /**
+   * Remove all listeners for an event
+   */
+  removeAllListeners<K extends keyof EventMap>(event: K): void;
+}

package/src/core/interfaces.ts

@@ -0,0 +1,129 @@
+/**
+ * Core service interfaces for dependency injection
+ */
+
+// Logger interface
+export interface ILogger {
+  info(message: string, ...args: unknown[]): void;
+  warn(message: string, ...args: unknown[]): void;
+  error(message: string, error?: Error | unknown, ...args: unknown[]): void;
+  debug(message: string, ...args: unknown[]): void;
+  success(message: string, ...args: unknown[]): void;
+}
+
+// Configuration interface
+export interface IConfiguration {
+  get<T = unknown>(key: string, defaultValue?: T): T;
+  getRequired<T = unknown>(key: string): T;
+  has(key: string): boolean;
+  set(key: string, value: unknown): void;
+  reload(): Promise<void>;
+}
+
+// Database connection interface
+export interface IDatabaseConnection {
+  connect(): Promise<void>;
+  disconnect(): Promise<void>;
+  healthCheck(): Promise<{ healthy: boolean; error?: string }>;
+  execute(sql: string, params?: unknown[]): Promise<DatabaseQueryResult>;
+}
+
+// Database query result
+export interface DatabaseQueryResult {
+  rows: Record<string, unknown>[];
+  rowCount: number;
+  command: string;
+}
+
+// Storage interface for memory and cache
+export interface IStorage<T = unknown> {
+  initialize(): Promise<void>;
+  get(key: string, namespace?: string): Promise<T | null>;
+  set(key: string, value: T, namespace?: string): Promise<void>;
+  delete(key: string, namespace?: string): Promise<void>;
+  clear(namespace?: string): Promise<void>;
+  list(namespace?: string): Promise<string[]>;
+  healthCheck(): Promise<{ healthy: boolean; error?: string }>;
+}
+
+// Search service interface
+export interface ISearchService {
+  initialize(): Promise<void>;
+  searchCodebase(query: string, options?: SearchOptions): Promise<SearchResult[]>;
+  searchKnowledge(query: string, options?: SearchOptions): Promise<SearchResult[]>;
+  getStatus(): Promise<SearchServiceStatus>;
+}
+
+// Search options
+export interface SearchOptions {
+  limit?: number;
+  offset?: number;
+  filters?: Record<string, unknown>;
+  sortBy?: string;
+  sortOrder?: 'asc' | 'desc';
+}
+
+// Search result
+export interface SearchResult {
+  id: string;
+  content: string;
+  score: number;
+  metadata: Record<string, unknown>;
+}
+
+// Search service status
+export interface SearchServiceStatus {
+  indexed: number;
+  total: number;
+  lastIndexed: string;
+  healthy: boolean;
+}
+
+// Target manager interface
+export interface ITargetManager {
+  getTarget(id: string): Target | null;
+  getAllTargets(): Target[];
+  registerTarget(target: Target): void;
+}
+
+// Target definition
+export interface Target {
+  id: string;
+  name: string;
+  type: string;
+  config: Record<string, unknown>;
+  enabled: boolean;
+}
+
+// Embedding provider interface
+export interface IEmbeddingProvider {
+  name: string;
+  embed(text: string): Promise<number[]>;
+  isAvailable(): Promise<boolean>;
+}
+
+// MCP service interface
+export interface IMCPService {
+  initialize(): Promise<void>;
+  installServers(serverIds: string[], options?: MCPServerInstallOptions): Promise<void>;
+  getAvailableServers(): MCPServerInfo[];
+  getInstalledServers(): MCPServerInfo[];
+}
+
+// MCP server installation options
+export interface MCPServerInstallOptions {
+  force?: boolean;
+  autoStart?: boolean;
+  config?: Record<string, unknown>;
+}
+
+// MCP server information
+export interface MCPServerInfo {
+  id: string;
+  name: string;
+  version: string;
+  description?: string;
+  installed: boolean;
+  enabled: boolean;
+  config?: Record<string, unknown>;
+}

package/src/core/loop-controller.ts

@@ -0,0 +1,200 @@
+/**
+ * Loop Controller - Simple continuous execution
+ *
+ * Core concept: Keep executing the same task with context persistence
+ * - First run: Fresh start
+ * - Subsequent runs: Auto-continue (builds on previous work)
+ * - Stop: Manual (Ctrl+C) or max-runs limit
+ *
+ * Use case: "Keep working on X until I stop you"
+ */
+
+import chalk from 'chalk';
+import type { FlowOptions } from '../commands/flow-command.js';
+
+export interface LoopOptions {
+  enabled: boolean;
+  interval: number;          // Wait time in seconds between runs (0 = no wait)
+  maxRuns?: number;          // Optional max iterations (default: infinite)
+}
+
+export interface LoopResult {
+  exitCode: number;
+  error?: Error;
+}
+
+export interface LoopState {
+  iteration: number;
+  startTime: Date;
+  successCount: number;
+  errorCount: number;
+}
+
+/**
+ * Controller for loop execution mode
+ */
+export class LoopController {
+  private state: LoopState;
+  private shouldStop: boolean = false;
+
+  constructor() {
+    this.state = {
+      iteration: 0,
+      startTime: new Date(),
+      successCount: 0,
+      errorCount: 0,
+    };
+
+    // Handle graceful shutdown
+    this.setupSignalHandlers();
+  }
+
+  /**
+   * Execute task in loop mode
+   * Simple: Keep running same task until manual stop or max-runs
+   */
+  async run(
+    executor: () => Promise<LoopResult>,
+    options: LoopOptions
+  ): Promise<void> {
+    console.log(chalk.cyan.bold('\n━━━ 🔄 Loop Mode Activated\n'));
+    console.log(chalk.dim(`  Wait time: ${options.interval}s`));
+    console.log(chalk.dim(`  Max runs: ${options.maxRuns || '∞'}`));
+    console.log(chalk.dim(`  Stop: Ctrl+C or max-runs limit\n`));
+
+    while (this.shouldContinue(options)) {
+      this.state.iteration++;
+
+      try {
+        await this.executeIteration(executor, options);
+      } catch (error) {
+        this.handleError(error as Error);
+      }
+
+      // Wait for next iteration
+      if (this.shouldContinue(options)) {
+        await this.waitForNextRun(options);
+      }
+    }
+
+    this.printSummary();
+  }
+
+  /**
+   * Execute single iteration
+   * Simple: Run task, track success/error, continue
+   */
+  private async executeIteration(
+    executor: () => Promise<LoopResult>,
+    options: LoopOptions
+  ): Promise<void> {
+    const maxDisplay = options.maxRuns || '∞';
+    console.log(
+      chalk.cyan(
+        `\n🔄 Loop iteration ${this.state.iteration}/${maxDisplay}`
+      )
+    );
+    console.log(chalk.dim(`Started: ${new Date().toLocaleTimeString()}\n`));
+
+    const result = await executor();
+
+    // Update state (just count success/error)
+    if (result.error || result.exitCode !== 0) {
+      this.state.errorCount++;
+      console.log(chalk.yellow(`\n⚠️  Task encountered error (continuing...)`));
+    } else {
+      this.state.successCount++;
+    }
+  }
+
+  /**
+   * Handle execution error
+   * Simple: Log and continue (resilient)
+   */
+  private handleError(error: Error): void {
+    this.state.errorCount++;
+    console.error(chalk.yellow('\n⚠️  Error occurred - continuing to next iteration'));
+    console.error(chalk.dim(`Error: ${error.message}\n`));
+  }
+
+  /**
+   * Wait for next iteration
+   */
+  private async waitForNextRun(options: LoopOptions): Promise<void> {
+    const maxDisplay = options.maxRuns || '∞';
+    const progress = `${this.state.iteration}/${maxDisplay}`;
+
+    console.log(
+      chalk.dim(
+        `\n⏳ Waiting ${options.interval}s until next run... (completed: ${progress})`
+      )
+    );
+
+    // Countdown display (optional, can be removed if too verbose)
+    const startTime = Date.now();
+    const endTime = startTime + options.interval * 1000;
+
+    while (Date.now() < endTime && !this.shouldStop) {
+      await this.sleep(1000);
+
+      const remaining = Math.ceil((endTime - Date.now()) / 1000);
+      if (remaining > 0 && remaining % 10 === 0) {
+        process.stdout.write(chalk.dim(`\r⏳ ${remaining}s remaining...`));
+      }
+    }
+
+    if (!this.shouldStop) {
+      process.stdout.write('\r' + ' '.repeat(50) + '\r'); // Clear line
+    }
+  }
+
+  /**
+   * Check if should continue looping
+   * Simple: Stop only on manual interrupt or max-runs
+   */
+  private shouldContinue(options: LoopOptions): boolean {
+    if (this.shouldStop) return false;
+    if (options.maxRuns && this.state.iteration >= options.maxRuns) return false;
+    return true;
+  }
+
+  /**
+   * Print execution summary
+   */
+  private printSummary(): void {
+    const duration = Date.now() - this.state.startTime.getTime();
+    const minutes = Math.floor(duration / 60000);
+    const seconds = Math.floor((duration % 60000) / 1000);
+
+    console.log(chalk.cyan.bold('\n━━━ 🏁 Loop Summary\n'));
+    console.log(`  Total iterations: ${this.state.iteration}`);
+    console.log(
+      `  Successful: ${chalk.green(this.state.successCount.toString())}`
+    );
+    console.log(`  Errors: ${chalk.red(this.state.errorCount.toString())}`);
+    console.log(`  Duration: ${minutes}m ${seconds}s`);
+    console.log();
+  }
+
+  /**
+   * Setup signal handlers for graceful shutdown
+   */
+  private setupSignalHandlers(): void {
+    const handler = () => {
+      console.log(
+        chalk.yellow('\n\n⚠️  Interrupt received - finishing current iteration...')
+      );
+      this.shouldStop = true;
+    };
+
+    process.on('SIGINT', handler);
+    process.on('SIGTERM', handler);
+  }
+
+  /**
+   * Sleep helper
+   */
+  private sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+}