@sylphx/flow 1.0.1 → 1.0.3

package/src/utils/process-manager.ts

@@ -0,0 +1,155 @@
+/**
+ * ProcessManager interface for managing child processes
+ */
+export interface ProcessManager {
+  trackChildProcess(childProcess: any): void;
+  killAllProcesses(): Promise<void>;
+  // Internal for testing - exposed for tests to access state
+  readonly _state?: ProcessManagerState;
+}
+
+/**
+ * Internal state for ProcessManager
+ */
+interface ProcessManagerState {
+  readonly childProcesses: Set<any>;
+  isShuttingDown: boolean;
+  readonly signalHandlers: Map<string, (...args: any[]) => void>;
+}
+
+/**
+ * Create a ProcessManager instance
+ */
+export function createProcessManager(): ProcessManager {
+  const state: ProcessManagerState = {
+    childProcesses: new Set(),
+    isShuttingDown: false,
+    signalHandlers: new Map(),
+  };
+
+  /**
+   * Cleanup signal handlers and reset state (for testing)
+   */
+  const cleanup = (): void => {
+    // Remove signal handlers
+    for (const [signal, handler] of state.signalHandlers.entries()) {
+      process.removeListener(signal as any, handler);
+    }
+    state.signalHandlers.clear();
+
+    // Clear child processes
+    state.childProcesses.clear();
+    state.isShuttingDown = false;
+  };
+
+  /**
+   * Kill all tracked child processes
+   */
+  const killAllProcesses = async (): Promise<void> => {
+    const killPromises = Array.from(state.childProcesses).map(async (childProcess) => {
+      try {
+        if (childProcess && !childProcess.killed) {
+          childProcess.kill('SIGTERM');
+
+          // Force kill if it doesn't stop after 2 seconds
+          setTimeout(() => {
+            if (!childProcess.killed) {
+              childProcess.kill('SIGKILL');
+            }
+          }, 2000);
+        }
+      } catch (_error) {
+        // Silently handle kill errors
+      }
+    });
+
+    await Promise.all(killPromises);
+    state.childProcesses.clear();
+  };
+
+  /**
+   * Setup signal handlers for graceful shutdown
+   */
+  const setupSignalHandlers = (): void => {
+    const shutdown = async (_signal: string) => {
+      if (state.isShuttingDown) {
+        return;
+      }
+      state.isShuttingDown = true;
+
+      await killAllProcesses();
+      process.exit(0);
+    };
+
+    // Create and store signal handlers
+    const sigintHandler = () => shutdown('SIGINT');
+    const sigtermHandler = () => shutdown('SIGTERM');
+    const sighupHandler = () => shutdown('SIGHUP');
+
+    state.signalHandlers.set('SIGINT', sigintHandler);
+    state.signalHandlers.set('SIGTERM', sigtermHandler);
+    state.signalHandlers.set('SIGHUP', sighupHandler);
+
+    // Handle termination signals
+    process.on('SIGINT', sigintHandler);
+    process.on('SIGTERM', sigtermHandler);
+    process.on('SIGHUP', sighupHandler);
+  };
+
+  /**
+   * Track a child process for cleanup on shutdown
+   */
+  const trackChildProcess = (childProcess: any): void => {
+    state.childProcesses.add(childProcess);
+
+    // Remove from tracking when process exits
+    childProcess.on('exit', () => {
+      state.childProcesses.delete(childProcess);
+    });
+  };
+
+  // Setup signal handlers when instance is created
+  setupSignalHandlers();
+
+  const manager: ProcessManager & { _cleanup?: () => void; _state?: ProcessManagerState } = {
+    trackChildProcess,
+    killAllProcesses,
+    _state: state, // Expose state for testing
+  };
+
+  // Expose cleanup for testing
+  (manager as any)._cleanup = cleanup;
+
+  return manager;
+}
+
+// Singleton instance for backward compatibility
+let _processManagerInstance: ProcessManager | null = null;
+
+/**
+ * Get the singleton ProcessManager instance
+ * @deprecated Use createProcessManager() for new code
+ */
+export class ProcessManager {
+  static getInstance(): ProcessManager {
+    if (!_processManagerInstance) {
+      _processManagerInstance = createProcessManager();
+    }
+    return _processManagerInstance;
+  }
+
+  /**
+   * Reset singleton instance (for testing only)
+   * @internal
+   */
+  static resetInstance(): void {
+    if (_processManagerInstance) {
+      // Call cleanup if available
+      const cleanup = (_processManagerInstance as any)._cleanup;
+      if (cleanup) {
+        cleanup();
+      }
+      _processManagerInstance = null;
+    }
+  }
+}

package/src/utils/prompts.ts

@@ -0,0 +1,120 @@
+/**
+ * Modern CLI prompts with progressive output
+ */
+
+import { createInterface } from 'node:readline';
+import chalk from 'chalk';
+
+export async function ask(question: string, defaultValue?: string): Promise<string> {
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  const prompt = defaultValue
+    ? `${chalk.cyan('❯')} ${question} ${chalk.gray(`(${defaultValue})`)}: `
+    : `${chalk.cyan('❯')} ${question}: `;
+
+  return new Promise((resolve) => {
+    rl.question(prompt, (answer) => {
+      rl.close();
+      resolve(answer.trim() || defaultValue || '');
+    });
+  });
+}
+
+export async function askSecret(question: string): Promise<string> {
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  const prompt = `${chalk.cyan('❯')} ${question}: `;
+
+  return new Promise((resolve) => {
+    // Hide input for secrets
+    const stdin = process.stdin;
+    const _onData = (char: Buffer) => {
+      const str = char.toString('utf8');
+      if (str === '\n' || str === '\r' || str === '\r\n') {
+        (stdin as any).removeListener('data', _onData);
+        process.stdout.write('\n');
+        rl.close();
+      } else {
+        process.stdout.write('•');
+      }
+    };
+
+    process.stdout.write(prompt);
+    let input = '';
+    stdin.on('data', (char) => {
+      const str = char.toString('utf8');
+      if (str === '\n' || str === '\r' || str === '\r\n') {
+        process.stdout.write('\n');
+        rl.close();
+        resolve(input);
+      } else if (str === '\x7f' || str === '\b') {
+        // Backspace
+        if (input.length > 0) {
+          input = input.slice(0, -1);
+          process.stdout.write('\b \b');
+        }
+      } else {
+        input += str;
+        process.stdout.write('•');
+      }
+    });
+    stdin.setRawMode(true);
+    stdin.resume();
+  }).finally(() => {
+    const stdin = process.stdin;
+    stdin.setRawMode(false);
+    stdin.pause();
+  });
+}
+
+export async function select<T extends string>(question: string, choices: T[]): Promise<T> {
+  console.log(`${chalk.cyan('❯')} ${question}`);
+  choices.forEach((choice, index) => {
+    console.log(chalk.gray(`  ${index + 1}. ${choice}`));
+  });
+
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  return new Promise((resolve) => {
+    rl.question(chalk.cyan(`  Select (1-${choices.length}): `), (answer) => {
+      rl.close();
+      const index = Number.parseInt(answer.trim(), 10) - 1;
+      if (index >= 0 && index < choices.length) {
+        resolve(choices[index]);
+      } else {
+        resolve(choices[0]);
+      }
+    });
+  });
+}
+
+export async function confirm(question: string, defaultValue = true): Promise<boolean> {
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  const defaultText = defaultValue ? 'Y/n' : 'y/N';
+  const prompt = `${chalk.cyan('❯')} ${question} ${chalk.gray(`(${defaultText})`)}: `;
+
+  return new Promise((resolve) => {
+    rl.question(prompt, (answer) => {
+      rl.close();
+      const input = answer.trim().toLowerCase();
+      if (input) {
+        resolve(input === 'y' || input === 'yes');
+      } else {
+        resolve(defaultValue);
+      }
+    });
+  });
+}

package/src/utils/search-tool-builder.ts

@@ -0,0 +1,214 @@
+/**
+ * Unified search tool builder
+ * Creates consistent search and status tools for indexers
+ */
+
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import type { BaseIndexer } from '../services/search/base-indexer.js';
+import { searchDocuments } from '../services/search/tfidf.js';
+
+export interface SearchToolConfig {
+  indexer: BaseIndexer;
+  toolName: string; // e.g., 'search_knowledge', 'search_codebase'
+  statusToolName: string; // e.g., 'get_knowledge_status', 'get_indexing_status'
+  description: string;
+  searchDescription: string;
+  examples: string[];
+}
+
+/**
+ * Build search tool with consistent pattern
+ */
+export function buildSearchTool(server: McpServer, config: SearchToolConfig) {
+  const { indexer, toolName, statusToolName, description, searchDescription } = config;
+
+  // Register search tool
+  server.registerTool(
+    toolName,
+    {
+      description: `${description}
+
+${searchDescription}
+
+**Performance:**
+- First search: ~1-5s (indexing time)
+- Subsequent searches: <100ms (cached)
+- Background indexing: Starts automatically on server startup
+
+**Status:**
+- Use \`${statusToolName}\` to check indexing progress
+- If indexing in progress, returns progress message`,
+      inputSchema: {
+        query: z.string().describe('Search query'),
+        limit: z.number().optional().describe('Maximum results (default: 5, max: 20)'),
+        categories: z.array(z.string()).optional().describe('Filter by categories (optional)'),
+      },
+    },
+    async (args) => {
+      try {
+        const query = args.query as string;
+        const limit = Math.min((args.limit as number) || 5, 20);
+        const categories = args.categories as string[] | undefined;
+
+        // Check if indexing is in progress
+        const status = indexer.getStatus();
+        if (status.isIndexing) {
+          const elapsed = Math.round((Date.now() - status.startTime) / 1000);
+          return {
+            content: [
+              {
+                type: 'text',
+                text: `⏳ Indexing in progress...\n\n**Status:**\n- Progress: ${status.progress}%\n- Items indexed: ${status.indexedItems}/${status.totalItems}\n- Elapsed time: ${elapsed}s\n\n*Please wait and try again. Use \`${statusToolName}\` to check progress.*`,
+              },
+            ],
+          };
+        }
+
+        // Check for errors
+        if (status.error) {
+          return {
+            content: [
+              {
+                type: 'text',
+                text: `✗ Indexing failed: ${status.error}\n\nPlease check the error and try again.`,
+              },
+            ],
+            isError: true,
+          };
+        }
+
+        // Perform search
+        const startTime = Date.now();
+        const index = await indexer.loadIndex();
+        const indexTime = Date.now() - startTime;
+
+        const searchStartTime = Date.now();
+        const results = searchDocuments(query, index, {
+          limit: limit * 2,
+          minScore: 0.01,
+        });
+        const searchTime = Date.now() - searchStartTime;
+
+        // Filter by categories if specified
+        let filtered = results;
+        if (categories && categories.length > 0) {
+          filtered = results.filter((result) => {
+            // Extract scheme/protocol from URI (e.g., 'knowledge' from 'knowledge://path')
+            const category = result.uri.split('://')[0];
+            return categories.includes(category);
+          });
+        }
+
+        const finalResults = filtered.slice(0, limit);
+
+        if (finalResults.length === 0) {
+          return {
+            content: [
+              {
+                type: 'text',
+                text: `No results found for query: "${query}"\n\nTry:\n- Broader search terms\n- Different keywords\n- Check available categories`,
+              },
+            ],
+          };
+        }
+
+        // Build response
+        const resultTexts = finalResults.map((item, index) => {
+          const filePath = item.uri.replace(/^(knowledge|file):\/\//, '');
+          let text = `## ${index + 1}. ${filePath}\n`;
+          text += `**Relevance**: ${(item.score * 100).toFixed(0)}%\n`;
+          text += `**Matched terms**: ${item.matchedTerms.join(', ')}\n\n`;
+          return text;
+        });
+
+        const summary = `Found ${finalResults.length} result(s) for "${query}":\n\n`;
+        const stats = `\n---\n\n**Stats:**\n- Total items: ${index.totalDocuments}\n- Index time: ${indexTime}ms\n- Search time: ${searchTime}ms\n`;
+
+        return {
+          content: [
+            {
+              type: 'text',
+              text: summary + resultTexts.join('\n---\n\n') + stats,
+            },
+          ],
+        };
+      } catch (error: unknown) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        console.error(`[ERROR] ${toolName} failed:`, error);
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `✗ Search error: ${errorMessage}`,
+            },
+          ],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  // Register status tool
+  server.registerTool(
+    statusToolName,
+    {
+      description: `Get indexing status for ${toolName}.
+
+Shows:
+- Whether indexing is in progress
+- Progress percentage
+- Number of items indexed
+- Any errors`,
+      inputSchema: {},
+    },
+    async () => {
+      const status = indexer.getStatus();
+
+      if (status.isIndexing) {
+        const elapsed = Math.round((Date.now() - status.startTime) / 1000);
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `⏳ **Indexing in Progress**\n\n- Progress: ${status.progress}%\n- Items indexed: ${status.indexedItems}/${status.totalItems}\n- Elapsed time: ${elapsed}s`,
+            },
+          ],
+        };
+      }
+
+      if (status.error) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `✗ **Indexing Failed**\n\nError: ${status.error}`,
+            },
+          ],
+          isError: true,
+        };
+      }
+
+      if (indexer.isReady()) {
+        const stats = await indexer.getStats();
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `✓ **Index Ready**\n\n- Total items: ${stats?.totalDocuments || 0}\n- Unique terms: ${stats?.uniqueTerms || 0}\n- Status: Ready for search`,
+            },
+          ],
+        };
+      }
+
+      return {
+        content: [
+          {
+            type: 'text',
+            text: '⚠️ **Not Indexed**\n\nIndexing will start automatically on first search.',
+          },
+        ],
+      };
+    }
+  );
+}

package/src/utils/secret-utils.ts

@@ -0,0 +1,179 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+/**
+ * Secret management utilities for handling {file:} syntax and .secrets directory
+ */
+export const secretUtils = {
+  /**
+   * Get the secrets directory path
+   */
+  getSecretsDir(cwd: string): string {
+    return path.join(cwd, '.secrets');
+  },
+
+  /**
+   * Ensure secrets directory exists
+   */
+  async ensureSecretsDir(cwd: string): Promise<void> {
+    const secretsDir = secretUtils.getSecretsDir(cwd);
+    await fs.mkdir(secretsDir, { recursive: true });
+  },
+
+  /**
+   * Write a secret to a file in .secrets directory
+   */
+  async writeSecret(cwd: string, key: string, value: string): Promise<string> {
+    await secretUtils.ensureSecretsDir(cwd);
+
+    const secretFile = path.join('.secrets', key);
+    const secretPath = path.join(cwd, secretFile);
+
+    await fs.writeFile(secretPath, value.trim(), 'utf8');
+    return secretFile;
+  },
+
+  /**
+   * Read a secret from a file
+   */
+  async readSecret(cwd: string, secretFile: string): Promise<string> {
+    const secretPath = path.resolve(cwd, secretFile);
+
+    try {
+      return await fs.readFile(secretPath, 'utf8');
+    } catch (error) {
+      throw new Error(`Failed to read secret file ${secretFile}: ${error}`);
+    }
+  },
+
+  /**
+   * Convert a secret key to {file:} reference format
+   */
+  toFileReference(key: string): string {
+    return `{file:.secrets/${key}}`;
+  },
+
+  /**
+   * Check if a value is a file reference
+   */
+  isFileReference(value: string): boolean {
+    return value.startsWith('{file:') && value.endsWith('}');
+  },
+
+  /**
+   * Extract file path from {file:} reference
+   */
+  extractFilePath(reference: string): string {
+    if (!secretUtils.isFileReference(reference)) {
+      throw new Error(`Invalid file reference: ${reference}`);
+    }
+
+    return reference.slice(6, -1); // Remove {file: prefix and } suffix
+  },
+
+  /**
+   * Resolve file references in an object recursively
+   */
+  async resolveFileReferences(cwd: string, obj: any): Promise<any> {
+    if (typeof obj === 'string' && secretUtils.isFileReference(obj)) {
+      const filePath = secretUtils.extractFilePath(obj);
+      return await secretUtils.readSecret(cwd, filePath);
+    }
+
+    if (Array.isArray(obj)) {
+      return Promise.all(obj.map((item) => secretUtils.resolveFileReferences(cwd, item)));
+    }
+
+    if (obj && typeof obj === 'object') {
+      const resolved: any = {};
+      for (const [key, value] of Object.entries(obj)) {
+        resolved[key] = await secretUtils.resolveFileReferences(cwd, value);
+      }
+      return resolved;
+    }
+
+    return obj;
+  },
+
+  /**
+   * Convert secret values to file references in environment variables
+   */
+  async convertSecretsToFileReferences(
+    cwd: string,
+    envVars: Record<string, string>
+  ): Promise<Record<string, string>> {
+    const result: Record<string, string> = {};
+
+    for (const [key, value] of Object.entries(envVars)) {
+      if (value && !secretUtils.isFileReference(value)) {
+        // Write the secret to a file and create file reference
+        const _secretFile = await secretUtils.writeSecret(cwd, key, value);
+        result[key] = secretUtils.toFileReference(key);
+      } else {
+        result[key] = value;
+      }
+    }
+
+    return result;
+  },
+
+  /**
+   * Save multiple secrets to files
+   */
+  async saveSecrets(cwd: string, secrets: Record<string, string>): Promise<void> {
+    for (const [key, value] of Object.entries(secrets)) {
+      await secretUtils.writeSecret(cwd, key, value);
+    }
+  },
+
+  /**
+   * Load all secrets from .secrets directory
+   */
+  async loadSecrets(cwd: string): Promise<Record<string, string>> {
+    const secretsDir = secretUtils.getSecretsDir(cwd);
+    const secrets: Record<string, string> = {};
+
+    try {
+      const files = await fs.readdir(secretsDir);
+
+      for (const file of files) {
+        const filePath = path.join(secretsDir, file);
+        const stat = await fs.stat(filePath);
+
+        if (stat.isFile()) {
+          const content = await fs.readFile(filePath, 'utf8');
+          secrets[file] = content.trim();
+        }
+      }
+    } catch (_error) {
+      // Directory doesn't exist or can't be read
+      // Return empty secrets object
+    }
+
+    return secrets;
+  },
+
+  /**
+   * Add .secrets to .gitignore if not already present
+   */
+  async addToGitignore(cwd: string): Promise<void> {
+    const gitignorePath = path.join(cwd, '.gitignore');
+
+    try {
+      let gitignoreContent = '';
+      try {
+        gitignoreContent = await fs.readFile(gitignorePath, 'utf8');
+      } catch {
+        // .gitignore doesn't exist, create it
+      }
+
+      const lines = gitignoreContent.split('\n').map((line) => line.trim());
+      if (!lines.includes('.secrets') && !lines.includes('.secrets/')) {
+        gitignoreContent += `${gitignoreContent && !gitignoreContent.endsWith('\n') ? '\n' : ''}.secrets/\n`;
+        await fs.writeFile(gitignorePath, gitignoreContent, 'utf8');
+      }
+    } catch (error) {
+      console.warn('Warning: Could not update .gitignore:', error);
+    }
+  },
+};