@sylphx/flow 1.0.1 → 1.0.3

package/src/core/installers/file-installer.ts

@@ -0,0 +1,303 @@
+/**
+ * Composable file installer - shared installation logic
+ * Used by targets through composition
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import type { CommonOptions, ProcessResult } from '../../shared/index.js';
+import { clearObsoleteFiles, collectFiles, getLocalFileInfo } from '../../shared/index.js';
+
+export interface InstallOptions extends CommonOptions {
+  /** Custom file extension */
+  extension?: string;
+  /** Whether to flatten directory structure */
+  flatten?: boolean;
+  /** Show progress messages */
+  showProgress?: boolean;
+}
+
+export type FileTransformFn = (content: string, sourcePath?: string) => Promise<string>;
+
+/**
+ * Collect files from source directory
+ */
+async function collectSourceFiles(sourceDir: string, extension: string): Promise<string[]> {
+  if (!fs.existsSync(sourceDir)) {
+    return [];
+  }
+
+  const allFiles: string[] = [];
+
+  // Collect files directly in root
+  const rootFiles = fs
+    .readdirSync(sourceDir, { withFileTypes: true })
+    .filter((dirent) => dirent.isFile() && dirent.name.endsWith(extension))
+    .map((dirent) => dirent.name);
+
+  allFiles.push(...rootFiles);
+
+  // Collect files from subdirectories (excluding 'archived')
+  const subdirs = fs
+    .readdirSync(sourceDir, { withFileTypes: true })
+    .filter((dirent) => dirent.isDirectory() && dirent.name !== 'archived')
+    .map((dirent) => dirent.name);
+
+  for (const subdir of subdirs) {
+    const subdirPath = path.join(sourceDir, subdir);
+    const files = await collectFiles(subdirPath, [extension]);
+    allFiles.push(...files.map((file) => path.join(subdir, file)));
+  }
+
+  return allFiles;
+}
+
+/**
+ * Install files from source directory to target directory
+ */
+export async function installToDirectory(
+  sourceDir: string,
+  targetDir: string,
+  transform: FileTransformFn,
+  options: InstallOptions = {}
+): Promise<ProcessResult[]> {
+  const results: ProcessResult[] = [];
+
+  // Collect source files
+  const files = await collectSourceFiles(sourceDir, options.extension || '.md');
+
+  if (files.length === 0) {
+    return results;
+  }
+
+  // Clear obsolete files if requested
+  if (options.clear && fs.existsSync(targetDir)) {
+    const expectedFiles = new Set(
+      files.map((file) => {
+        if (options.flatten) {
+          const parsed = path.parse(file);
+          const baseName = parsed.name;
+          const dir = parsed.dir;
+          const flatName = dir ? `${dir.replace(/[/\\]/g, '-')}-${baseName}` : baseName;
+          return `${flatName}${options.extension || '.md'}`;
+        }
+        return file;
+      })
+    );
+
+    clearObsoleteFiles(targetDir, expectedFiles, [options.extension || '.md'], results);
+  }
+
+  // Create target directory
+  fs.mkdirSync(targetDir, { recursive: true });
+
+  if (options.showProgress && !options.quiet) {
+    console.log(
+      `Installing ${files.length} file${files.length > 1 ? 's' : ''} to ${targetDir.replace(`${process.cwd()}/`, '')}`
+    );
+    console.log('');
+  }
+
+  if (options.dryRun) {
+    if (!options.quiet) {
+      console.log('✓ Dry run completed - no files were modified');
+    }
+    return results;
+  }
+
+  // Process files in parallel
+  const processPromises = files.map(async (file) => {
+    const sourcePath = path.join(sourceDir, file);
+    const targetPath = path.join(targetDir, file);
+
+    // Ensure target directory exists
+    const targetFileDir = path.dirname(targetPath);
+    if (!fs.existsSync(targetFileDir)) {
+      fs.mkdirSync(targetFileDir, { recursive: true });
+    }
+
+    const localInfo = await getLocalFileInfo(targetPath);
+
+    // Read and transform content
+    let content = fs.readFileSync(sourcePath, 'utf8');
+    content = await transform(content, file);
+
+    const localProcessed = localInfo ? await transform(localInfo.content, file) : '';
+    const contentChanged = !localInfo || localProcessed !== content;
+
+    if (contentChanged) {
+      fs.writeFileSync(targetPath, content, 'utf8');
+      results.push({
+        file,
+        status: localInfo ? 'updated' : 'added',
+        action: localInfo ? 'Updated' : 'Created',
+      });
+    } else {
+      results.push({
+        file,
+        status: 'current',
+        action: 'Already current',
+      });
+    }
+  });
+
+  await Promise.all(processPromises);
+
+  return results;
+}
+
+/**
+ * Append files from source directory to a single target file
+ */
+export async function appendToFile(
+  sourceDir: string,
+  targetFile: string,
+  transform: FileTransformFn,
+  options: InstallOptions = {}
+): Promise<void> {
+  // Collect source files
+  const files = await collectSourceFiles(sourceDir, options.extension || '.md');
+
+  if (files.length === 0) {
+    return;
+  }
+
+  if (options.dryRun) {
+    if (!options.quiet) {
+      console.log(
+        `Dry run: Would append ${files.length} file${files.length > 1 ? 's' : ''} to ${targetFile.replace(`${process.cwd()}/`, '')}`
+      );
+    }
+    return;
+  }
+
+  // Read existing file content
+  let existingContent = '';
+  if (fs.existsSync(targetFile)) {
+    existingContent = fs.readFileSync(targetFile, 'utf8');
+  }
+
+  // Build appended content
+  let appendContent = '';
+  for (const file of files) {
+    const sourcePath = path.join(sourceDir, file);
+    let content = fs.readFileSync(sourcePath, 'utf8');
+    content = await transform(content, file);
+    appendContent += `${content}\n\n`;
+  }
+
+  // Write combined content
+  fs.writeFileSync(targetFile, existingContent + appendContent, 'utf8');
+
+  if (options.showProgress && !options.quiet) {
+    console.log(
+      `Appended ${files.length} file${files.length > 1 ? 's' : ''} to ${targetFile.replace(`${process.cwd()}/`, '')}`
+    );
+  }
+}
+
+/**
+ * Install a single file from source to target
+ */
+export async function installFile(
+  sourceFile: string,
+  targetFile: string,
+  transform: FileTransformFn,
+  options: InstallOptions = {}
+): Promise<void> {
+  if (options.dryRun) {
+    if (!options.quiet) {
+      console.log(`Dry run: Would install file to ${targetFile.replace(`${process.cwd()}/`, '')}`);
+    }
+    return;
+  }
+
+  if (!fs.existsSync(sourceFile)) {
+    if (!options.quiet) {
+      console.warn(`Source file not found: ${sourceFile}`);
+    }
+    return;
+  }
+
+  // Ensure target directory exists
+  const targetDir = path.dirname(targetFile);
+  fs.mkdirSync(targetDir, { recursive: true });
+
+  // Check if file already exists and is up to date
+  const localInfo = await getLocalFileInfo(targetFile);
+  let content = fs.readFileSync(sourceFile, 'utf8');
+  content = await transform(content);
+
+  if (localInfo && localInfo.content === content) {
+    if (!options.quiet) {
+      console.log(`File already current: ${targetFile.replace(`${process.cwd()}/`, '')}`);
+    }
+    return;
+  }
+
+  // Write file
+  fs.writeFileSync(targetFile, content, 'utf8');
+
+  if (options.showProgress && !options.quiet) {
+    const action = localInfo ? 'Updated' : 'Created';
+    console.log(`${action} file: ${targetFile.replace(`${process.cwd()}/`, '')}`);
+  }
+}
+
+/**
+ * File installer interface for backward compatibility
+ */
+export interface FileInstaller {
+  installToDirectory(
+    sourceDir: string,
+    targetDir: string,
+    transform: FileTransformFn,
+    options?: InstallOptions
+  ): Promise<ProcessResult[]>;
+  appendToFile(
+    sourceDir: string,
+    targetFile: string,
+    transform: FileTransformFn,
+    options?: InstallOptions
+  ): Promise<void>;
+  installFile(
+    sourceFile: string,
+    targetFile: string,
+    transform: FileTransformFn,
+    options?: InstallOptions
+  ): Promise<void>;
+}
+
+/**
+ * Composable file installer
+ * Handles copying files from source to destination with optional transformation
+ * @deprecated Use standalone functions (installToDirectory, appendToFile, installFile) for new code
+ */
+export class FileInstaller {
+  async installToDirectory(
+    sourceDir: string,
+    targetDir: string,
+    transform: FileTransformFn,
+    options: InstallOptions = {}
+  ): Promise<ProcessResult[]> {
+    return installToDirectory(sourceDir, targetDir, transform, options);
+  }
+
+  async appendToFile(
+    sourceDir: string,
+    targetFile: string,
+    transform: FileTransformFn,
+    options: InstallOptions = {}
+  ): Promise<void> {
+    return appendToFile(sourceDir, targetFile, transform, options);
+  }
+
+  async installFile(
+    sourceFile: string,
+    targetFile: string,
+    transform: FileTransformFn,
+    options: InstallOptions = {}
+  ): Promise<void> {
+    return installFile(sourceFile, targetFile, transform, options);
+  }
+}

package/src/core/installers/mcp-installer.ts

@@ -0,0 +1,213 @@
+/**
+ * Composable MCP installer - shared MCP installation logic
+ * Used by targets through composition
+ */
+
+import chalk from 'chalk';
+import inquirer from 'inquirer';
+import ora from 'ora';
+import { MCP_SERVER_REGISTRY, type MCPServerID } from '../../config/servers.js';
+import { createMCPService } from '../../services/mcp-service.js';
+import type { Target } from '../../types.js';
+
+export interface MCPInstallResult {
+  selectedServers: MCPServerID[];
+  serverConfigsMap: Record<MCPServerID, Record<string, string>>;
+}
+
+/**
+ * MCP Installer interface
+ */
+export interface MCPInstaller {
+  selectServers(options?: { quiet?: boolean }): Promise<MCPServerID[]>;
+  configureServers(
+    selectedServers: MCPServerID[],
+    options?: { quiet?: boolean }
+  ): Promise<Record<MCPServerID, Record<string, string>>>;
+  installServers(
+    selectedServers: MCPServerID[],
+    serverConfigsMap: Record<MCPServerID, Record<string, string>>,
+    options?: { quiet?: boolean }
+  ): Promise<void>;
+  setupMCP(options?: { quiet?: boolean; dryRun?: boolean }): Promise<MCPInstallResult>;
+}
+
+/**
+ * Create an MCP installer instance
+ * Handles server selection, configuration, and installation
+ *
+ * @param target - Target configuration object (dependency injection)
+ */
+export function createMCPInstaller(target: Target): MCPInstaller {
+  const mcpService = createMCPService({ target });
+
+  /**
+   * Prompt user to select MCP servers
+   */
+  const selectServers = async (options: { quiet?: boolean } = {}): Promise<MCPServerID[]> => {
+    const allServers = mcpService.getAllServerIds();
+    const installedServers = await mcpService.getInstalledServerIds();
+
+    if (!options.quiet) {
+      console.log(chalk.cyan.bold('━━━ Configure MCP Tools ━━━\n'));
+    }
+
+    // Show server selection
+    const serverSelectionAnswer = await inquirer.prompt([
+      {
+        type: 'checkbox',
+        name: 'selectedServers',
+        message: 'Select MCP tools to install:',
+        choices: allServers.map((id) => {
+          const server = MCP_SERVER_REGISTRY[id];
+          const isInstalled = installedServers.includes(id);
+          return {
+            name: `${server.name} - ${server.description}`,
+            value: id,
+            checked: server.required || isInstalled || server.defaultInInit || false,
+            disabled: server.required ? '(required)' : false,
+          };
+        }),
+      },
+    ]);
+
+    let selectedServers = serverSelectionAnswer.selectedServers as MCPServerID[];
+
+    // Ensure all required servers are included
+    const requiredServers = allServers.filter((id) => MCP_SERVER_REGISTRY[id].required);
+    selectedServers = [...new Set([...requiredServers, ...selectedServers])];
+
+    return selectedServers;
+  };
+
+  /**
+   * Configure selected servers
+   */
+  const configureServers = async (
+    selectedServers: MCPServerID[],
+    options: { quiet?: boolean } = {}
+  ): Promise<Record<MCPServerID, Record<string, string>>> => {
+    const serversNeedingConfig = selectedServers.filter((id) => {
+      const server = MCP_SERVER_REGISTRY[id];
+      return server.envVars && Object.keys(server.envVars).length > 0;
+    });
+
+    const serverConfigsMap: Record<MCPServerID, Record<string, string>> = {};
+
+    if (serversNeedingConfig.length > 0) {
+      if (!options.quiet) {
+        console.log(chalk.cyan.bold('\n━━━ Server Configuration ━━━\n'));
+      }
+
+      const collectedEnv: Record<string, string> = {};
+      for (const serverId of serversNeedingConfig) {
+        const configValues = await mcpService.configureServer(serverId, collectedEnv);
+        serverConfigsMap[serverId] = configValues;
+      }
+    }
+
+    return serverConfigsMap;
+  };
+
+  /**
+   * Install servers with configuration
+   */
+  const installServers = async (
+    selectedServers: MCPServerID[],
+    serverConfigsMap: Record<MCPServerID, Record<string, string>>,
+    options: { quiet?: boolean } = {}
+  ): Promise<void> => {
+    if (selectedServers.length === 0) {
+      return;
+    }
+
+    // Only show spinner if not in quiet mode
+    const spinner = options.quiet
+      ? null
+      : ora({
+          text: `Installing ${selectedServers.length} MCP server${selectedServers.length > 1 ? 's' : ''}`,
+          color: 'cyan',
+        }).start();
+
+    try {
+      await mcpService.installServers(selectedServers, serverConfigsMap);
+      if (spinner) {
+        spinner.succeed(
+          chalk.green(
+            `Installed ${chalk.cyan(selectedServers.length)} MCP server${selectedServers.length > 1 ? 's' : ''}`
+          )
+        );
+      }
+    } catch (error) {
+      if (spinner) {
+        spinner.fail(chalk.red('Failed to install MCP servers'));
+      }
+      throw error;
+    }
+  };
+
+  /**
+   * Full MCP setup workflow: select, configure, and install
+   */
+  const setupMCP = async (
+    options: { quiet?: boolean; dryRun?: boolean } = {}
+  ): Promise<MCPInstallResult> => {
+    // Select servers
+    const selectedServers = await selectServers(options);
+
+    if (selectedServers.length === 0) {
+      return { selectedServers: [], serverConfigsMap: {} };
+    }
+
+    // Configure servers
+    const serverConfigsMap = await configureServers(selectedServers, options);
+
+    // Install servers
+    if (!options.dryRun) {
+      await installServers(selectedServers, serverConfigsMap, options);
+    }
+
+    return { selectedServers, serverConfigsMap };
+  };
+
+  return {
+    selectServers,
+    configureServers,
+    installServers,
+    setupMCP,
+  };
+}
+
+/**
+ * @deprecated Use createMCPInstaller() for new code
+ */
+export class MCPInstaller {
+  private installer: ReturnType<typeof createMCPInstaller>;
+
+  constructor(target: Target) {
+    this.installer = createMCPInstaller(target);
+  }
+
+  async selectServers(options: { quiet?: boolean } = {}): Promise<MCPServerID[]> {
+    return this.installer.selectServers(options);
+  }
+
+  async configureServers(
+    selectedServers: MCPServerID[],
+    options: { quiet?: boolean } = {}
+  ): Promise<Record<MCPServerID, Record<string, string>>> {
+    return this.installer.configureServers(selectedServers, options);
+  }
+
+  async installServers(
+    selectedServers: MCPServerID[],
+    serverConfigsMap: Record<MCPServerID, Record<string, string>>,
+    options: { quiet?: boolean } = {}
+  ): Promise<void> {
+    return this.installer.installServers(selectedServers, serverConfigsMap, options);
+  }
+
+  async setupMCP(options: { quiet?: boolean; dryRun?: boolean } = {}): Promise<MCPInstallResult> {
+    return this.installer.setupMCP(options);
+  }
+}

package/src/core/interfaces/index.ts

@@ -0,0 +1,22 @@
+/**
+ * Core interfaces for dependency inversion
+ * All abstractions in one place
+ *
+ * DESIGN RATIONALE:
+ * - Single source of truth for contracts
+ * - Enables dependency injection
+ * - Facilitates testing
+ * - Clear separation of interface and implementation
+ */
+
+// Re-export commonly used types from existing interfaces
+export type {
+  CoreService,
+  FileProcessor,
+  IDatabaseConnection,
+  ILogger,
+  InitializationOptions,
+  TargetManager,
+} from '../interfaces.js';
+export * from './repository.interface.js';
+export * from './service.interface.js';

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

@@ -0,0 +1,91 @@
+/**
+ * Repository interface for dependency inversion
+ * Abstracts data access implementation
+ *
+ * DESIGN RATIONALE:
+ * - Depend on abstractions, not concrete implementations
+ * - Enables testing with in-memory implementations
+ * - Separates interface from implementation
+ * - Clear contract for data access
+ */
+
+import type { DatabaseError } from '../functional/error-types.js';
+import type { Result } from '../functional/result.js';
+
+/**
+ * Query options for filtering, sorting, pagination
+ */
+export interface QueryOptions {
+  limit?: number;
+  offset?: number;
+  orderBy?: string;
+  orderDirection?: 'ASC' | 'DESC';
+  where?: Record<string, any>;
+}
+
+/**
+ * Paginated result wrapper
+ */
+export interface PaginatedResult<T> {
+  items: T[];
+  total: number;
+  page: number;
+  pageSize: number;
+  hasNext: boolean;
+  hasPrevious: boolean;
+}
+
+/**
+ * Generic repository interface
+ * All operations return Result for explicit error handling
+ */
+export interface IRepository<T, ID = string | number> {
+  /**
+   * Find entity by ID
+   */
+  findById(id: ID): Promise<Result<T | null, DatabaseError>>;
+
+  /**
+   * Find multiple entities with filtering and sorting
+   */
+  findMany(options?: QueryOptions): Promise<Result<T[], DatabaseError>>;
+
+  /**
+   * Find entities with pagination
+   */
+  findPaginated(
+    page: number,
+    pageSize: number,
+    options?: Omit<QueryOptions, 'limit' | 'offset'>
+  ): Promise<Result<PaginatedResult<T>, DatabaseError>>;
+
+  /**
+   * Create a new entity
+   */
+  create(data: Partial<T>): Promise<Result<T, DatabaseError>>;
+
+  /**
+   * Update an existing entity
+   */
+  update(id: ID, data: Partial<T>): Promise<Result<T | null, DatabaseError>>;
+
+  /**
+   * Delete an entity
+   */
+  delete(id: ID): Promise<Result<boolean, DatabaseError>>;
+
+  /**
+   * Count entities matching criteria
+   */
+  count(options?: { where?: Record<string, any> }): Promise<Result<number, DatabaseError>>;
+
+  /**
+   * Check if entity exists
+   */
+  exists(id: ID): Promise<Result<boolean, DatabaseError>>;
+}
+
+/**
+ * Factory function type for creating repositories
+ */
+export type RepositoryFactory<T, ID = string | number> = (tableName: string) => IRepository<T, ID>;