@sylphx/flow 1.0.1 → 1.0.3

package/src/utils/index.ts

@@ -0,0 +1,78 @@
+/**
+ * Centralized utility exports
+ * Provides both legacy organization and new feature-based organization
+ */
+
+// ============================================================================
+// FEATURE-BASED ORGANIZATION (Removed - migrated to domains/ and services/)
+// ============================================================================
+// Features now organized in:
+// - src/domains/ for domain-specific logic
+// - src/services/ for shared infrastructure
+
+// ============================================================================
+// LEGACY ORGANIZATION (Backward Compatibility)
+// ============================================================================
+// Direct exports for backward compatibility - @deprecated
+
+export * from './cache-storage.js';
+export * from './database-errors.js';
+// Database utilities
+export * from './drizzle-storage.js';
+// Error handling
+export * from './error-handler.js';
+// File operations
+export * from './file-operations.js';
+// JSONC utilities
+export * from './jsonc.js';
+// Logger utilities
+export * from './logger.js';
+export * from './memory-storage.js';
+// Path utilities
+export * from './paths.js';
+// Security utilities
+export * from './security.js';
+export * from './simplified-errors.js';
+// Target configuration
+export * from './target-config.js';
+
+// Search and indexing - moved to services/search/
+
+// Command builder
+export * from './command-builder.js';
+// Console UI utilities
+export * from './console-ui.js';
+// Prompt utilities
+export * from './prompts.js';
+// Secret utilities
+export * from './secret-utils.js';
+// Template engine
+export * from './template-engine.js';
+
+// Embeddings and TF-IDF - moved to services/search/
+
+// Help utilities
+export * from './help.js';
+
+// Target utilities
+export * from './target-utils.js';
+
+// Migration examples - removed (obsolete)
+// Test utilities - removed (obsolete)
+
+// Shared utilities
+export * from '../shared/index.js';
+
+// Base indexer - moved to services/search/
+
+// LanceDB vector storage
+export * from './lancedb-vector-storage.js';
+// Separated storage
+export * from './separated-storage.js';
+// Settings utilities
+export * from './settings.js';
+
+// Target config types
+export * from './target-config.js';
+// Vector storage
+export * from './vector-storage.js';

package/src/utils/jsonc.ts

@@ -0,0 +1,158 @@
+/**
+ * JSONC (JSON with Comments) utilities
+ * Provides functions to parse and stringify JSONC files while preserving comments
+ */
+
+import { readFile, writeFile } from 'node:fs/promises';
+
+/**
+ * Parse JSONC content (JSON with Comments)
+ * @param content - The JSONC string to parse
+ * @returns The parsed JavaScript object
+ */
+export function parseJSONC(content: string): unknown {
+  try {
+    // Remove single-line comments (//) but not inside strings
+    let cleaned = removeComments(content);
+
+    // Remove trailing commas before closing brackets/braces
+    cleaned = cleaned.replace(/,(\s*[}\]])/g, '$1');
+
+    return JSON.parse(cleaned);
+  } catch (error) {
+    throw new Error(
+      `Failed to parse JSONC: ${error instanceof Error ? error.message : 'Unknown error'}`
+    );
+  }
+}
+
+/**
+ * Remove comments from JSON content while preserving strings
+ */
+function removeComments(content: string): string {
+  let result = '';
+  let inString = false;
+  let inSingleLineComment = false;
+  let inMultiLineComment = false;
+  let escapeNext = false;
+
+  for (let i = 0; i < content.length; i++) {
+    const char = content[i];
+    const nextChar = content[i + 1];
+
+    if (escapeNext) {
+      result += char;
+      escapeNext = false;
+      continue;
+    }
+
+    if (char === '\\' && inString) {
+      result += char;
+      escapeNext = true;
+      continue;
+    }
+
+    if (inString) {
+      if (char === '"') {
+        inString = false;
+      }
+      result += char;
+      continue;
+    }
+
+    if (inSingleLineComment) {
+      if (char === '\n') {
+        inSingleLineComment = false;
+        result += char;
+      }
+      continue;
+    }
+
+    if (inMultiLineComment) {
+      if (char === '*' && nextChar === '/') {
+        inMultiLineComment = false;
+        i++; // Skip the '/'
+      }
+      continue;
+    }
+
+    if (char === '"') {
+      inString = true;
+      result += char;
+      continue;
+    }
+
+    if (char === '/' && nextChar === '/') {
+      inSingleLineComment = true;
+      i++; // Skip the second '/'
+      continue;
+    }
+
+    if (char === '/' && nextChar === '*') {
+      inMultiLineComment = true;
+      i++; // Skip the '*'
+      continue;
+    }
+
+    result += char;
+  }
+
+  return result;
+}
+
+/**
+ * Stringify an object to JSON format with optional schema
+ * @param obj - The object to stringify
+ * @param schema - Optional schema URL to include
+ * @param indent - Indentation spaces (default: 2)
+ * @returns The formatted JSON string
+ */
+export function stringifyJSONC(obj: Record<string, unknown>, schema?: string, indent = 2): string {
+  const config = { ...obj };
+
+  // Add schema if provided and not already present
+  if (schema && !config.$schema) {
+    config.$schema = schema;
+  }
+
+  const json = JSON.stringify(config, null, indent);
+
+  // Add helpful comments for MCP configuration
+  if (config.mcp && Object.keys(config.mcp).length > 0) {
+    return json.replace(
+      /(\s*)"mcp": {/,
+      `$1// MCP (Model Context Protocol) server configuration
+$1// See https://modelcontextprotocol.io for more information
+$1"mcp": {`
+    );
+  }
+
+  return json;
+}
+
+/**
+ * Read and parse a JSONC file
+ * @param filePath - Path to the JSONC file
+ * @returns The parsed object
+ */
+export async function readJSONCFile(filePath: string): Promise<any> {
+  const content = await readFile(filePath, 'utf8');
+  return parseJSONC(content);
+}
+
+/**
+ * Write an object to a JSONC file
+ * @param filePath - Path to the JSONC file
+ * @param obj - The object to write
+ * @param schema - Optional schema URL
+ * @param indent - Indentation spaces
+ */
+export async function writeJSONCFile(
+  filePath: string,
+  obj: Record<string, unknown>,
+  schema?: string,
+  indent = 2
+): Promise<void> {
+  const content = stringifyJSONC(obj, schema, indent);
+  await writeFile(filePath, content, 'utf8');
+}

package/src/utils/logger.ts

@@ -0,0 +1,396 @@
+/**
+ * Centralized logging utility for Sylphx Flow
+ * Provides structured logging with different levels and output formats
+ */
+
+import { randomUUID } from 'node:crypto';
+import chalk from 'chalk';
+
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+export interface LogEntry {
+  id: string;
+  timestamp: string;
+  level: LogLevel;
+  message: string;
+  context?: Record<string, unknown>;
+  error?: {
+    name: string;
+    message: string;
+    stack?: string;
+    code?: string;
+  };
+  module?: string;
+  function?: string;
+}
+
+export interface LoggerConfig {
+  level: LogLevel;
+  format: 'json' | 'pretty' | 'simple';
+  includeTimestamp: boolean;
+  includeContext: boolean;
+  colors: boolean;
+  module?: string;
+}
+
+const LEVEL_PRIORITY: Record<LogLevel, number> = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+};
+
+const LEVEL_COLORS: Record<LogLevel, (text: string) => string> = {
+  debug: chalk.gray,
+  info: chalk.blue,
+  warn: chalk.yellow,
+  error: chalk.red,
+};
+
+const LEVEL_SYMBOLS: Record<LogLevel, string> = {
+  debug: '🔍',
+  info: 'ℹ',
+  warn: '⚠',
+  error: '✗',
+};
+
+/**
+ * Logger interface for dependency injection and testing
+ */
+export interface Logger {
+  child(context: Record<string, unknown>): Logger;
+  module(moduleName: string): Logger;
+  setLevel(level: LogLevel): void;
+  updateConfig(config: Partial<LoggerConfig>): void;
+  debug(message: string, context?: Record<string, unknown>): void;
+  info(message: string, context?: Record<string, unknown>): void;
+  warn(message: string, context?: Record<string, unknown>): void;
+  error(message: string, error?: Error, context?: Record<string, unknown>): void;
+  time<T>(fn: () => Promise<T>, label: string, context?: Record<string, unknown>): Promise<T>;
+  timeSync<T>(fn: () => T, label: string, context?: Record<string, unknown>): T;
+}
+
+/**
+ * Internal state for logger instance
+ */
+interface LoggerState {
+  config: LoggerConfig;
+  context?: Record<string, unknown>;
+}
+
+/**
+ * Options for creating a logger instance
+ */
+interface CreateLoggerOptions {
+  config?: Partial<LoggerConfig>;
+  context?: Record<string, unknown>;
+}
+
+/**
+ * Create a logger instance with the specified configuration and context
+ */
+export function createLogger(options: Partial<LoggerConfig> | CreateLoggerOptions = {}): Logger {
+  // Handle both old style (config object) and new style (options with config and context)
+  const isOptionsStyle = 'config' in options || 'context' in options;
+  const config = isOptionsStyle
+    ? (options as CreateLoggerOptions).config || {}
+    : (options as Partial<LoggerConfig>);
+  const initialContext = isOptionsStyle ? (options as CreateLoggerOptions).context : undefined;
+
+  const state: LoggerState = {
+    config: {
+      level: 'info',
+      format: 'pretty',
+      includeTimestamp: true,
+      includeContext: true,
+      colors: true,
+      ...config,
+    },
+    context: initialContext,
+  };
+
+  /**
+   * Check if a log level should be output
+   */
+  const shouldLog = (level: LogLevel): boolean => {
+    return LEVEL_PRIORITY[level] >= LEVEL_PRIORITY[state.config.level];
+  };
+
+  /**
+   * Create a log entry
+   */
+  const createLogEntry = (
+    level: LogLevel,
+    message: string,
+    error?: Error,
+    additionalContext?: Record<string, unknown>
+  ): LogEntry => {
+    const entry: LogEntry = {
+      id: randomUUID(),
+      timestamp: new Date().toISOString(),
+      level,
+      message,
+      module: state.context?.module,
+      function: state.context?.function,
+    };
+
+    // Merge contexts
+    if (state.config.includeContext) {
+      entry.context = { ...state.context, ...additionalContext };
+    }
+
+    // Add error information if provided
+    if (error) {
+      entry.error = {
+        name: error.name,
+        message: error.message,
+        stack: error.stack,
+      };
+
+      // Add error code if it's a CLIError
+      if ('code' in error && typeof error.code === 'string') {
+        entry.error.code = error.code;
+      }
+    }
+
+    return entry;
+  };
+
+  /**
+   * Format a log entry for output
+   */
+  const formatEntry = (entry: LogEntry): string => {
+    switch (state.config.format) {
+      case 'json':
+        return JSON.stringify(entry);
+
+      case 'simple': {
+        const levelStr = entry.level.toUpperCase().padEnd(5);
+        const moduleStr = entry.module ? `[${entry.module}] ` : '';
+        return `${levelStr} ${moduleStr}${entry.message}`;
+      }
+      default: {
+        const parts: string[] = [];
+
+        // Timestamp
+        if (state.config.includeTimestamp) {
+          const time = new Date(entry.timestamp).toLocaleTimeString();
+          parts.push(chalk.gray(time));
+        }
+
+        // Level symbol and name
+        const colorFn = state.config.colors ? LEVEL_COLORS[entry.level] : (s: string) => s;
+        parts.push(
+          `${colorFn(LEVEL_SYMBOLS[entry.level])} ${colorFn(entry.level.toUpperCase().padEnd(5))}`
+        );
+
+        // Module
+        if (entry.module) {
+          parts.push(chalk.cyan(`[${entry.module}]`));
+        }
+
+        // Function
+        if (entry.function) {
+          parts.push(chalk.gray(`${entry.function}()`));
+        }
+
+        // Message
+        parts.push(entry.message);
+
+        let result = parts.join(' ');
+
+        // Context
+        if (entry.context && Object.keys(entry.context).length > 0) {
+          const contextStr = JSON.stringify(entry.context, null, 2);
+          result += `\n${chalk.gray('  Context: ')}${chalk.gray(contextStr)}`;
+        }
+
+        // Error details
+        if (entry.error) {
+          result += `\n${chalk.red('  Error: ')}${chalk.red(entry.error.message)}`;
+          if (entry.error.code) {
+            result += `\n${chalk.red('  Code: ')}${chalk.red(entry.error.code)}`;
+          }
+          if (entry.error.stack) {
+            result += `\n${chalk.gray(entry.error.stack)}`;
+          }
+        }
+
+        return result;
+      }
+    }
+  };
+
+  /**
+   * Internal logging method
+   */
+  const logInternal = (
+    level: LogLevel,
+    message: string,
+    error?: Error,
+    additionalContext?: Record<string, any>
+  ): void => {
+    if (!shouldLog(level)) {
+      return;
+    }
+
+    const entry = createLogEntry(level, message, error, additionalContext);
+    const formatted = formatEntry(entry);
+
+    // Output to appropriate stream
+    if (level === 'error') {
+      console.error(formatted);
+    } else {
+      console.log(formatted);
+    }
+  };
+
+  /**
+   * Create a child logger with additional context
+   */
+  const child = (context: Record<string, unknown>): Logger => {
+    return createLogger({
+      config: state.config,
+      context: { ...state.context, ...context },
+    });
+  };
+
+  /**
+   * Create a logger for a specific module
+   */
+  const module = (moduleName: string): Logger => {
+    return child({ module: moduleName });
+  };
+
+  /**
+   * Set the log level
+   */
+  const setLevel = (level: LogLevel): void => {
+    state.config.level = level;
+  };
+
+  /**
+   * Update logger configuration
+   */
+  const updateConfig = (config: Partial<LoggerConfig>): void => {
+    state.config = { ...state.config, ...config };
+  };
+
+  /**
+   * Debug level logging
+   */
+  const debug = (message: string, context?: Record<string, unknown>): void => {
+    logInternal('debug', message, undefined, context);
+  };
+
+  /**
+   * Info level logging
+   */
+  const info = (message: string, context?: Record<string, unknown>): void => {
+    logInternal('info', message, undefined, context);
+  };
+
+  /**
+   * Warning level logging
+   */
+  const warn = (message: string, context?: Record<string, unknown>): void => {
+    logInternal('warn', message, undefined, context);
+  };
+
+  /**
+   * Error level logging
+   */
+  const error = (message: string, errorObj?: Error, context?: Record<string, unknown>): void => {
+    logInternal('error', message, errorObj, context);
+  };
+
+  /**
+   * Log function execution with timing
+   */
+  const time = async <T>(
+    fn: () => Promise<T>,
+    label: string,
+    context?: Record<string, unknown>
+  ): Promise<T> => {
+    const start = Date.now();
+    debug(`Starting ${label}`, context);
+
+    try {
+      const result = await fn();
+      const duration = Date.now() - start;
+      info(`Completed ${label}`, { ...context, duration: `${duration}ms` });
+      return result;
+    } catch (caughtError) {
+      const duration = Date.now() - start;
+      error(`Failed ${label}`, caughtError as Error, { ...context, duration: `${duration}ms` });
+      throw caughtError;
+    }
+  };
+
+  /**
+   * Log function execution (sync) with timing
+   */
+  const timeSync = <T>(fn: () => T, label: string, context?: Record<string, unknown>): T => {
+    const start = Date.now();
+    debug(`Starting ${label}`, context);
+
+    try {
+      const result = fn();
+      const duration = Date.now() - start;
+      info(`Completed ${label}`, { ...context, duration: `${duration}ms` });
+      return result;
+    } catch (caughtError) {
+      const duration = Date.now() - start;
+      error(`Failed ${label}`, caughtError as Error, { ...context, duration: `${duration}ms` });
+      throw caughtError;
+    }
+  };
+
+  return {
+    child,
+    module,
+    setLevel,
+    updateConfig,
+    debug,
+    info,
+    warn,
+    error,
+    time,
+    timeSync,
+  };
+}
+
+// Default logger instance
+export const logger = createLogger();
+
+// Environment-based configuration
+if (process.env.NODE_ENV === 'production') {
+  logger.updateConfig({
+    level: 'info',
+    format: 'json',
+    colors: false,
+  });
+} else if (process.env.DEBUG) {
+  logger.updateConfig({
+    level: 'debug',
+  });
+}
+
+// Export convenience functions
+export const log = {
+  debug: (message: string, context?: Record<string, unknown>) => logger.debug(message, context),
+  info: (message: string, context?: Record<string, unknown>) => logger.info(message, context),
+  warn: (message: string, context?: Record<string, unknown>) => logger.warn(message, context),
+  error: (message: string, error?: Error, context?: Record<string, unknown>) =>
+    logger.error(message, error, context),
+  time: <T>(fn: () => Promise<T>, label: string, context?: Record<string, unknown>) =>
+    logger.time(fn, label, context),
+  timeSync: <T>(fn: () => T, label: string, context?: Record<string, unknown>) =>
+    logger.timeSync(fn, label, context),
+  child: (context: Record<string, unknown>) => logger.child(context),
+  module: (moduleName: string) => logger.module(moduleName),
+  setLevel: (level: LogLevel) => logger.setLevel(level),
+  updateConfig: (config: Partial<LoggerConfig>) => logger.updateConfig(config),
+};
+
+export default logger;