@sylphx/flow 1.0.1 → 1.0.3

package/src/config/servers.ts

@@ -0,0 +1,371 @@
+import type { MCPServerConfigUnion } from '../types.js';
+import { envSecurity, securitySchemas } from '../utils/security.js';
+
+/**
+ * Central MCP server registry for Sylphx Flow
+ * This is the single source of truth for all available MCP servers
+ */
+export interface EnvVarConfig {
+  /** Description of what this environment variable does */
+  description: string;
+  /** Whether this environment variable is required or optional */
+  required: boolean;
+  /** Default value (if any) */
+  default?: string;
+  /** Whether this environment variable contains sensitive data and should be stored as secret */
+  secret?: boolean;
+  /** Async function to fetch choices for list inputs */
+  fetchChoices?: () => Promise<string[]>;
+  /** Environment variables this field depends on */
+  dependsOn?: string[];
+}
+
+export interface MCPServerDefinition {
+  /** Internal identifier used in CLI commands */
+  id: string;
+  /** Display name for the server */
+  name: string;
+  /** Human-readable description */
+  description: string;
+  /** MCP server configuration */
+  config: MCPServerConfigUnion;
+  /** Environment variables configuration */
+  envVars?: Record<string, EnvVarConfig>;
+  /** Server category for grouping */
+  category: 'core' | 'external' | 'ai';
+  /** Whether this server is included by default in init */
+  defaultInInit?: boolean;
+  /** Whether this server is required and cannot be uninstalled */
+  required?: boolean;
+}
+
+/**
+ * Central registry of all available MCP servers
+ * This replaces all hardcoded server lists throughout the codebase
+ */
+export const MCP_SERVER_REGISTRY: Record<string, MCPServerDefinition> = {
+  'sylphx-flow': {
+    id: 'sylphx-flow',
+    name: 'sylphx-flow',
+    description: 'Sylphx Flow MCP server for agent coordination and memory management',
+    config: {
+      type: 'stdio' as const,
+      command: 'sylphx-flow',
+      args: ['mcp', 'start'],
+      env: {
+        OPENAI_API_KEY: '',
+        OPENAI_BASE_URL: 'https://api.openai.com/v1',
+        EMBEDDING_MODEL: 'text-embedding-3-small',
+      },
+    },
+    envVars: {
+      OPENAI_API_KEY: {
+        description: 'OpenAI API key for vector search embeddings',
+        required: false,
+        secret: true,
+      },
+      OPENAI_BASE_URL: {
+        description: 'Base URL for OpenAI-compatible embedding API',
+        required: false,
+        default: 'https://api.openai.com/v1',
+      },
+      EMBEDDING_MODEL: {
+        description: 'Embedding model to use for vector search',
+        required: false,
+        default: 'text-embedding-3-small',
+        dependsOn: ['OPENAI_API_KEY', 'OPENAI_BASE_URL'],
+        fetchChoices: async () => {
+          // Validate environment variables
+          const validatedBaseUrl = envSecurity.getEnvVar(
+            'OPENAI_BASE_URL',
+            'https://api.openai.com/v1'
+          );
+          const validatedApiKey = envSecurity.getEnvVar('OPENAI_API_KEY');
+
+          if (!validatedApiKey) {
+            throw new Error('OPENAI_API_KEY is required to fetch embedding models');
+          }
+
+          // Additional validation for API key format
+          try {
+            securitySchemas.apiKey.parse(validatedApiKey);
+          } catch (_error) {
+            throw new Error('Invalid OPENAI_API_KEY format');
+          }
+
+          const response = await fetch(`${validatedBaseUrl}/models`, {
+            headers: { Authorization: `Bearer ${validatedApiKey}` },
+            timeout: 10000, // Add timeout to prevent hanging
+          });
+
+          if (!response.ok) {
+            throw new Error(`Failed to fetch models: ${response.statusText}`);
+          }
+
+          const data = await response.json();
+          const embeddingModels = data.data
+            .filter((m: { id: string }) => m.id.includes('embedding'))
+            .map((m: { id: string }) => m.id)
+            .sort();
+
+          if (embeddingModels.length === 0) {
+            throw new Error('No embedding models found');
+          }
+
+          return embeddingModels;
+        },
+      },
+    },
+    category: 'core',
+    defaultInInit: true,
+    required: true,
+  },
+
+  'gpt-image': {
+    id: 'gpt-image',
+    name: 'gpt-image-1-mcp',
+    description: 'GPT Image generation MCP server',
+    config: {
+      type: 'stdio' as const,
+      command: 'npx',
+      args: ['@napolab/gpt-image-1-mcp'],
+      env: { OPENAI_API_KEY: '' },
+    },
+    envVars: {
+      OPENAI_API_KEY: {
+        description: 'OpenAI API key for image generation',
+        required: true,
+        secret: true,
+      },
+    },
+    category: 'ai',
+    defaultInInit: false,
+  },
+
+  perplexity: {
+    id: 'perplexity',
+    name: 'perplexity-ask',
+    description: 'Perplexity Ask MCP server for search and queries',
+    config: {
+      type: 'stdio' as const,
+      command: 'npx',
+      args: ['-y', 'server-perplexity-ask'],
+      env: { PERPLEXITY_API_KEY: '' },
+    },
+    envVars: {
+      PERPLEXITY_API_KEY: {
+        description: 'Perplexity API key for search and queries',
+        required: true,
+        secret: true,
+      },
+    },
+    category: 'ai',
+    defaultInInit: false,
+  },
+
+  context7: {
+    id: 'context7',
+    name: 'context7',
+    description: 'Context7 HTTP MCP server for documentation retrieval',
+    config: {
+      type: 'http' as const,
+      url: 'https://mcp.context7.com/mcp',
+    },
+    envVars: {
+      CONTEXT7_API_KEY: {
+        description: 'Context7 API key for enhanced documentation access',
+        required: false,
+        secret: true,
+      },
+    },
+    category: 'external',
+    defaultInInit: true,
+  },
+
+  'gemini-search': {
+    id: 'gemini-search',
+    name: 'gemini-google-search',
+    description: 'Gemini Google Search MCP server',
+    config: {
+      type: 'stdio' as const,
+      command: 'npx',
+      args: ['-y', 'mcp-gemini-google-search'],
+      env: { GEMINI_API_KEY: '', GEMINI_MODEL: 'gemini-2.5-flash' },
+    },
+    envVars: {
+      GEMINI_API_KEY: {
+        description: 'Google Gemini API key for search functionality',
+        required: true,
+        secret: true,
+      },
+      GEMINI_MODEL: {
+        description: 'Gemini model to use for search',
+        required: false,
+        default: 'gemini-2.5-flash',
+      },
+    },
+    category: 'ai',
+    defaultInInit: false,
+  },
+
+  grep: {
+    id: 'grep',
+    name: 'grep',
+    description: 'GitHub grep MCP server for searching GitHub repositories',
+    config: {
+      type: 'http' as const,
+      url: 'https://mcp.grep.app',
+    },
+    category: 'external',
+    defaultInInit: true,
+  },
+};
+
+/**
+ * Type for valid MCP server IDs
+ */
+export type MCPServerID = keyof typeof MCP_SERVER_REGISTRY;
+
+/**
+ * Get all available server IDs
+ */
+export function getAllServerIDs(): MCPServerID[] {
+  return Object.keys(MCP_SERVER_REGISTRY) as MCPServerID[];
+}
+
+/**
+ * Get servers by category
+ */
+export function getServersByCategory(category: MCPServerDefinition['category']): MCPServerID[] {
+  return Object.entries(MCP_SERVER_REGISTRY)
+    .filter(([, server]) => server.category === category)
+    .map(([id]) => id as MCPServerID);
+}
+
+/**
+ * Get servers that are included by default in init
+ */
+export function getDefaultServers(): MCPServerID[] {
+  return Object.entries(MCP_SERVER_REGISTRY)
+    .filter(([, server]) => server.defaultInInit)
+    .map(([id]) => id as MCPServerID);
+}
+
+/**
+ * Get servers that require API keys
+ */
+export function getServersRequiringAPIKeys(): MCPServerID[] {
+  return Object.entries(MCP_SERVER_REGISTRY)
+    .filter(
+      ([, server]) =>
+        server.envVars && Object.values(server.envVars).some((envVar) => envVar.required)
+    )
+    .map(([id]) => id as MCPServerID);
+}
+
+/**
+ * Get servers that have optional API keys
+ */
+export function getServersWithOptionalAPIKeys(): MCPServerID[] {
+  return Object.entries(MCP_SERVER_REGISTRY)
+    .filter(
+      ([, server]) =>
+        server.envVars && Object.values(server.envVars).some((envVar) => !envVar.required)
+    )
+    .map(([id]) => id as MCPServerID);
+}
+
+/**
+ * Get all servers that have any API keys (required or optional)
+ */
+export function getServersWithAnyAPIKeys(): MCPServerID[] {
+  return Object.entries(MCP_SERVER_REGISTRY)
+    .filter(([, server]) => server.envVars && Object.keys(server.envVars).length > 0)
+    .map(([id]) => id as MCPServerID);
+}
+
+/**
+ * Get required environment variables for a server
+ */
+export function getRequiredEnvVars(serverId: MCPServerID): string[] {
+  const server = MCP_SERVER_REGISTRY[serverId];
+  if (!server?.envVars) {
+    return [];
+  }
+
+  return Object.entries(server.envVars)
+    .filter(([, config]) => config.required)
+    .map(([name]) => name);
+}
+
+/**
+ * Get optional environment variables for a server
+ */
+export function getOptionalEnvVars(serverId: MCPServerID): string[] {
+  const server = MCP_SERVER_REGISTRY[serverId];
+  if (!server?.envVars) {
+    return [];
+  }
+
+  return Object.entries(server.envVars)
+    .filter(([, config]) => !config.required)
+    .map(([name]) => name);
+}
+
+/**
+ * Get all environment variables for a server
+ */
+export function getAllEnvVars(serverId: MCPServerID): string[] {
+  const server = MCP_SERVER_REGISTRY[serverId];
+  if (!server?.envVars) {
+    return [];
+  }
+
+  return Object.keys(server.envVars);
+}
+
+/**
+ * Get secret environment variables for a server
+ */
+export function getSecretEnvVars(serverId: MCPServerID): string[] {
+  const server = MCP_SERVER_REGISTRY[serverId];
+  if (!server?.envVars) {
+    return [];
+  }
+
+  return Object.entries(server.envVars)
+    .filter(([, config]) => config.secret)
+    .map(([name]) => name);
+}
+
+/**
+ * Get non-secret environment variables for a server
+ */
+export function getNonSecretEnvVars(serverId: MCPServerID): string[] {
+  const server = MCP_SERVER_REGISTRY[serverId];
+  if (!server?.envVars) {
+    return [];
+  }
+
+  return Object.entries(server.envVars)
+    .filter(([, config]) => !config.secret)
+    .map(([name]) => name);
+}
+
+/**
+ * Validate server ID
+ */
+export function isValidServerID(id: string): id is MCPServerID {
+  return id in MCP_SERVER_REGISTRY;
+}
+
+/**
+ * Get server definition
+ */
+export function getServerDefinition(id: MCPServerID): MCPServerDefinition {
+  const server = MCP_SERVER_REGISTRY[id];
+  if (!server) {
+    throw new Error(`Unknown MCP server: ${id}`);
+  }
+  return server;
+}

package/src/config/targets.ts

@@ -0,0 +1,126 @@
+/**
+ * Target registry - functional implementation with composition
+ * Pure functions operating on immutable data
+ */
+
+import type { Option } from '../core/functional/option.js';
+import { none, some } from '../core/functional/option.js';
+import { claudeCodeTarget } from '../targets/claude-code.js';
+import { opencodeTarget } from '../targets/opencode.js';
+import type { Target } from '../types.js';
+
+/**
+ * All available targets
+ * Lazy-initialized to avoid circular dependencies
+ */
+let cachedTargets: readonly Target[] | null = null;
+
+const initializeTargets = (): readonly Target[] => {
+  if (cachedTargets) {
+    return cachedTargets;
+  }
+
+  cachedTargets = Object.freeze([opencodeTarget, claudeCodeTarget]);
+
+  return cachedTargets;
+};
+
+/**
+ * Get all targets
+ */
+export const getAllTargets = (): readonly Target[] => initializeTargets();
+
+/**
+ * Get implemented targets only
+ */
+export const getImplementedTargets = (): readonly Target[] =>
+  getAllTargets().filter((target) => target.isImplemented);
+
+/**
+ * Get all target IDs
+ */
+export const getAllTargetIDs = (): readonly string[] => getAllTargets().map((target) => target.id);
+
+/**
+ * Get implemented target IDs
+ */
+export const getImplementedTargetIDs = (): readonly string[] =>
+  getImplementedTargets().map((target) => target.id);
+
+/**
+ * Get target by ID
+ * Returns Option type for explicit null handling
+ */
+export const getTarget = (id: string): Option<Target> => {
+  const target = getAllTargets().find((t) => t.id === id);
+  return target ? some(target) : none;
+};
+
+/**
+ * Get target by ID (unsafe - throws if not found)
+ * Use getTarget() for safer alternative with Option type
+ */
+export const getTargetUnsafe = (id: string): Target => {
+  const target = getAllTargets().find((t) => t.id === id);
+  if (!target) {
+    throw new Error(`Target not found: ${id}`);
+  }
+  return target;
+};
+
+/**
+ * Get default target
+ * Returns Option type for explicit null handling
+ */
+export const getDefaultTarget = (): Option<Target> => {
+  const target = getAllTargets().find((t) => t.isDefault);
+  return target ? some(target) : none;
+};
+
+/**
+ * Get default target (unsafe - throws if not found)
+ * Use getDefaultTarget() for safer alternative with Option type
+ */
+export const getDefaultTargetUnsafe = (): Target => {
+  const target = getAllTargets().find((t) => t.isDefault);
+  if (!target) {
+    throw new Error('No default target configured');
+  }
+  return target;
+};
+
+/**
+ * Get targets that support MCP servers
+ */
+export const getTargetsWithMCPSupport = (): readonly Target[] =>
+  getImplementedTargets().filter((target) => !!target.setupMCP);
+
+/**
+ * Get targets that support command execution (agent running)
+ */
+export const getTargetsWithCommandSupport = (): readonly Target[] =>
+  getImplementedTargets().filter((target) => !!target.executeCommand);
+
+/**
+ * Check if target is implemented
+ */
+export const isTargetImplemented = (id: string): boolean => {
+  const target = getAllTargets().find((t) => t.id === id);
+  return target?.isImplemented ?? false;
+};
+
+/**
+ * Utility type for target IDs
+ */
+export type TargetID = ReturnType<typeof getAllTargetIDs>[number];
+
+/**
+ * Legacy aliases for backward compatibility
+ * @deprecated Use getAllTargets() instead
+ */
+export const ALL_TARGETS = getAllTargets;
+
+/**
+ * @deprecated Use getImplementedTargets() instead
+ */
+export const IMPLEMENTED_TARGETS = getImplementedTargets;

package/src/core/agent-loader.ts

@@ -0,0 +1,141 @@
+/**
+ * Agent Loader
+ * Loads agent definitions from markdown files with front matter
+ */
+
+import { readFile, readdir, access } from 'node:fs/promises';
+import { join, parse, relative, dirname } from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import matter from 'gray-matter';
+import type { Agent, AgentMetadata } from '../types/agent.types.js';
+
+/**
+ * Load a single agent from a markdown file
+ */
+export async function loadAgentFromFile(
+  filePath: string,
+  isBuiltin: boolean = false,
+  agentId?: string
+): Promise<Agent | null> {
+  try {
+    const content = await readFile(filePath, 'utf-8');
+    const { data, content: systemPrompt } = matter(content);
+
+    // Validate front matter
+    if (!data.name || typeof data.name !== 'string') {
+      console.error(`Agent file ${filePath} missing required 'name' field`);
+      return null;
+    }
+
+    const metadata: AgentMetadata = {
+      name: data.name,
+      description: data.description || '',
+    };
+
+    // Get agent ID from parameter or filename
+    const id = agentId || parse(filePath).name;
+
+    return {
+      id,
+      metadata,
+      systemPrompt: systemPrompt.trim(),
+      isBuiltin,
+      filePath,
+    };
+  } catch (error) {
+    console.error(`Failed to load agent from ${filePath}:`, error);
+    return null;
+  }
+}
+
+/**
+ * Load all agents from a directory (recursively)
+ */
+export async function loadAgentsFromDirectory(dirPath: string, isBuiltin: boolean = false): Promise<Agent[]> {
+  try {
+    // Read directory recursively to support subdirectories
+    const files = await readdir(dirPath, { recursive: true, withFileTypes: true });
+
+    // Filter for .md files and calculate agent IDs from relative paths
+    const agentFiles = files
+      .filter((f) => f.isFile() && f.name.endsWith('.md'))
+      .map((f) => {
+        const fullPath = join(f.parentPath || f.path, f.name);
+        // Calculate relative path from dirPath and remove .md extension
+        const relativePath = relative(dirPath, fullPath).replace(/\.md$/, '');
+        return { fullPath, agentId: relativePath };
+      });
+
+    const agents = await Promise.all(
+      agentFiles.map(({ fullPath, agentId }) => loadAgentFromFile(fullPath, isBuiltin, agentId))
+    );
+
+    return agents.filter((agent): agent is Agent => agent !== null);
+  } catch (error) {
+    // Directory doesn't exist or can't be read
+    return [];
+  }
+}
+
+/**
+ * Get system agents path (bundled with the app)
+ */
+export async function getSystemAgentsPath(): Promise<string> {
+  // Get the directory of the current module (cross-platform)
+  const currentFile = fileURLToPath(import.meta.url);
+  const currentDir = dirname(currentFile);
+
+  // In production (dist), assets are at dist/assets/agents
+  // In development (src), go up to project root: src/core -> project root
+  const distPath = join(currentDir, '..', 'assets', 'agents');
+  const devPath = join(currentDir, '..', '..', 'assets', 'agents');
+
+  // Check which one exists (try dist first, then dev)
+  try {
+    await access(distPath);
+    return distPath;
+  } catch {
+    return devPath;
+  }
+}
+
+/**
+ * Get all agent search paths
+ */
+export function getAgentSearchPaths(cwd: string): string[] {
+  const globalPath = join(homedir(), '.sylphx-flow', 'agents');
+  const projectPath = join(cwd, '.sylphx-flow', 'agents');
+
+  return [globalPath, projectPath];
+}
+
+/**
+ * Load all available agents from all sources
+ */
+export async function loadAllAgents(cwd: string, targetAgentDir?: string): Promise<Agent[]> {
+  const systemPath = await getSystemAgentsPath();
+  const [globalPath, projectPath] = getAgentSearchPaths(cwd);
+
+  let allAgentPaths = [systemPath, globalPath, projectPath];
+
+  // If a target-specific agent directory is provided, add it with highest priority
+  if (targetAgentDir) {
+    const targetPath = join(cwd, targetAgentDir); // Assuming targetAgentDir is relative to cwd
+    allAgentPaths.push(targetPath);
+  }
+
+  // Load agents from all paths
+  const loadedAgentsPromises = allAgentPaths.map(path => loadAgentsFromDirectory(path, path === systemPath));
+  const loadedAgentsArrays = await Promise.all(loadedAgentsPromises);
+
+  // Flatten and deduplicate
+  const agentMap = new Map<string, Agent>();
+  for (const agentArray of loadedAgentsArrays) {
+    for (const agent of agentArray) {
+      agentMap.set(agent.id, agent);
+    }
+  }
+
+  return Array.from(agentMap.values());
+}