@sylphx/flow 3.19.0 → 3.19.1

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # @sylphx/flow
 
+## 3.19.1 (2026-02-07)
+
+### 🐛 Bug Fixes
+
+- add missing .js extensions to barrel exports ([54c4bb1](https://github.com/SylphxAI/flow/commit/54c4bb1bba79eb5b2e0d8ba06a7bf1486be5302c))
+- replace silent catch blocks with debug logging ([fe5a646](https://github.com/SylphxAI/flow/commit/fe5a646c180e87242034228c2472d1a0a1bd8dda))
+
+### ♻️ Refactoring
+
+- rename AgentMetadata to AgentDefinition in agent.types.ts ([01c16c9](https://github.com/SylphxAI/flow/commit/01c16c984b3e7ec7d318016e018d7db957ea140a))
+- extract readJsonFileSafe for repeated JSON-read-with-fallback pattern ([22088ed](https://github.com/SylphxAI/flow/commit/22088ed4d24cbfda2dc70f77dd2ae3e6f1ac111e))
+- remove unused functional modules and fix config barrel exports ([2f9f5b2](https://github.com/SylphxAI/flow/commit/2f9f5b242b9d9149630f8d933db788f862a8cebb))
+- extract convertServerSecrets from opencode writeConfig ([af7eac7](https://github.com/SylphxAI/flow/commit/af7eac7211d9067580a476683610da7f73c962e0))
+- extract health check functions from doctorCommand ([7debe50](https://github.com/SylphxAI/flow/commit/7debe50559c25c4e2ee2486eb1bfc329c32b178c))
+- extract tryJoinExistingSession and createNewSession from flow-executor ([5e25da8](https://github.com/SylphxAI/flow/commit/5e25da895e9bc216865f1e9810c21effd0878322))
+- extract selectTarget and loadAgent from executeFlowV2 ([9735cf0](https://github.com/SylphxAI/flow/commit/9735cf04c1ef43f6842b5ac5deafc3b0e04aecbb))
+
+### 💅 Styles
+
+- **flow:** format package.json with biome (tabs → spaces) ([7aeac4c](https://github.com/SylphxAI/flow/commit/7aeac4cf1d946ec3af82ae20b6215482d989a38f))
+
+### 🔧 Chores
+
+- remove 35 unused dependencies ([55318b0](https://github.com/SylphxAI/flow/commit/55318b0f3215bf47d1875bd07b9fcdad094620c4))
+
 ## 3.19.0 (2026-02-07)
 
 Performance, stability, and test coverage overhaul

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@sylphx/flow",
-	"version": "3.19.0",
+	"version": "3.19.1",
 	"description": "One CLI to rule them all. Unified orchestration layer for AI coding assistants. Auto-detection, auto-installation, auto-upgrade.",
 	"type": "module",
 	"bin": {
@@ -26,11 +26,9 @@
 	},
 	"dependencies": {
 		"@clack/prompts": "^0.9.0",
-		"boxen": "^8.0.1",
 		"chalk": "^5.6.2",
 		"commander": "^14.0.2",
 		"debug": "^4.4.3",
-		"gradient-string": "^3.0.0",
 		"gray-matter": "^4.0.3",
 		"pino": "^9.0.0",
 		"pino-pretty": "^11.0.0",

package/src/commands/flow/execute-v2.ts

@@ -3,11 +3,15 @@
  * Minimal, modern CLI output design
  */
 
-import fs from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import chalk from 'chalk';
+import createDebug from 'debug';
 import { FlowExecutor } from '../../core/flow-executor.js';
+import { readJsonFileSafe } from '../../utils/files/file-operations.js';
+
+const debug = createDebug('flow:execute');
+
 import { targetManager } from '../../core/target-manager.js';
 import { AutoUpgrade } from '../../services/auto-upgrade.js';
 import { GlobalConfigService } from '../../services/global-config.js';
@@ -15,8 +19,7 @@ import { TargetInstaller } from '../../services/target-installer.js';
 import type { RunCommandOptions } from '../../types.js';
 import { extractAgentInstructions, loadAgentContent } from '../../utils/agent-enhancer.js';
 import { showAttachSummary, showHeader } from '../../utils/display/banner.js';
-import { CLIError } from '../../utils/error-handler.js';
-import { UserCancelledError } from '../../utils/errors.js';
+import { CLIError, UserCancelledError } from '../../utils/errors.js';
 import { log, promptConfirm, promptSelect } from '../../utils/prompts/index.js';
 import { ensureTargetInstalled, promptForTargetSelection } from '../../utils/target-selection.js';
 import { resolvePrompt } from './prompt.js';
@@ -29,13 +32,9 @@ const __dirname = path.dirname(__filename);
  * Get Flow version from package.json
  */
 async function getFlowVersion(): Promise<string> {
-  try {
-    const packageJsonPath = path.join(__dirname, '..', '..', '..', 'package.json');
-    const packageJson = JSON.parse(await fs.readFile(packageJsonPath, 'utf-8'));
-    return packageJson.version;
-  } catch {
-    return 'unknown';
-  }
+  const packageJsonPath = path.join(__dirname, '..', '..', '..', 'package.json');
+  const pkg = await readJsonFileSafe<{ version?: string }>(packageJsonPath, {});
+  return pkg.version ?? 'unknown';
 }
 
 /**
@@ -138,6 +137,106 @@ function executeTargetCommand(
   return target.executeCommand(systemPrompt, userPrompt, options);
 }
 
+/**
+ * Select target based on user settings, installed targets, and prompts
+ */
+async function selectTarget(
+  installedTargets: string[],
+  settings: import('../../services/global-config.js').GlobalSettings,
+  configService: GlobalConfigService,
+  targetInstaller: TargetInstaller
+): Promise<string | null> {
+  if (settings.defaultTarget === 'ask-every-time') {
+    const targetId = await promptForTargetSelection(
+      installedTargets,
+      'Select AI CLI:',
+      'execution'
+    );
+    const installed = await ensureTargetInstalled(targetId, targetInstaller, installedTargets);
+    if (!installed) {
+      process.exit(1);
+    }
+    return targetId;
+  }
+
+  if (!settings.defaultTarget) {
+    if (installedTargets.length === 1) {
+      const targetId = installedTargets[0];
+      settings.defaultTarget = targetId as 'claude-code' | 'opencode';
+      await configService.saveSettings(settings);
+      return targetId;
+    }
+
+    const targetId = await promptForTargetSelection(
+      installedTargets,
+      'Select AI CLI:',
+      'execution'
+    );
+    const installed = await ensureTargetInstalled(targetId, targetInstaller, installedTargets);
+    if (!installed) {
+      process.exit(1);
+    }
+
+    const rememberChoice = await promptConfirm({
+      message: 'Remember this choice?',
+      initialValue: true,
+    });
+    if (rememberChoice) {
+      settings.defaultTarget = targetId as 'claude-code' | 'opencode';
+      await configService.saveSettings(settings);
+    }
+    return targetId;
+  }
+
+  // User has a specific target preference
+  const targetId = settings.defaultTarget;
+  if (!installedTargets.includes(targetId)) {
+    const installation = targetInstaller.getInstallationInfo(targetId);
+    log.warn(`${installation?.name} not installed`);
+    const installed = await targetInstaller.install(targetId, true);
+    if (!installed) {
+      log.error('Cannot proceed: installation failed');
+      process.exit(1);
+    }
+  }
+  return targetId;
+}
+
+/**
+ * Load agent and build system prompt
+ */
+async function loadAgent(
+  options: FlowOptions,
+  settings: import('../../services/global-config.js').GlobalSettings,
+  configService: GlobalConfigService
+): Promise<{ agent: string; systemPrompt: string }> {
+  const flowConfig = await configService.loadFlowConfig();
+  let agent = options.agent || settings.defaultAgent || 'builder';
+
+  if (!flowConfig.agents[agent]?.enabled) {
+    const enabledAgents = await configService.getEnabledAgents();
+    agent = enabledAgents.length > 0 ? enabledAgents[0] : 'builder';
+  }
+
+  const [enabledRules, enabledOutputStyles] = await Promise.all([
+    configService.getEnabledRules(),
+    configService.getEnabledOutputStyles(),
+  ]);
+
+  const agentContent = await loadAgentContent(
+    agent,
+    options.agentFile,
+    enabledRules,
+    enabledOutputStyles
+  );
+  const agentInstructions = extractAgentInstructions(agentContent);
+
+  return {
+    agent,
+    systemPrompt: `AGENT INSTRUCTIONS:\n${agentInstructions}`,
+  };
+}
+
 /**
  * Main flow execution with attach mode (V2) - Minimal output design
  */
@@ -158,79 +257,12 @@ export async function executeFlowV2(
     getFlowVersion(),
   ]);
 
-  let selectedTargetId: string | null = null;
-
-  const isAskEveryTime = settings.defaultTarget === 'ask-every-time';
-  const hasNoSetting = !settings.defaultTarget;
-  const hasSpecificTarget = settings.defaultTarget && settings.defaultTarget !== 'ask-every-time';
-
-  if (isAskEveryTime) {
-    // User explicitly wants to be asked every time
-    selectedTargetId = await promptForTargetSelection(
-      installedTargets,
-      'Select AI CLI:',
-      'execution'
-    );
-
-    const installed = await ensureTargetInstalled(
-      selectedTargetId,
-      targetInstaller,
-      installedTargets
-    );
-
-    if (!installed) {
-      process.exit(1);
-    }
-  } else if (hasNoSetting) {
-    // No setting - use auto-detection or prompt
-    if (installedTargets.length === 1) {
-      // Single target: auto-select and save silently
-      selectedTargetId = installedTargets[0];
-      settings.defaultTarget = selectedTargetId as 'claude-code' | 'opencode';
-      await configService.saveSettings(settings);
-    } else {
-      // Multiple targets: prompt and ask to remember
-      selectedTargetId = await promptForTargetSelection(
-        installedTargets,
-        'Select AI CLI:',
-        'execution'
-      );
-
-      const installed = await ensureTargetInstalled(
-        selectedTargetId,
-        targetInstaller,
-        installedTargets
-      );
-
-      if (!installed) {
-        process.exit(1);
-      }
-
-      const rememberChoice = await promptConfirm({
-        message: 'Remember this choice?',
-        initialValue: true,
-      });
-
-      if (rememberChoice) {
-        settings.defaultTarget = selectedTargetId as 'claude-code' | 'opencode';
-        await configService.saveSettings(settings);
-      }
-    }
-  } else if (hasSpecificTarget) {
-    // User has a specific target preference
-    selectedTargetId = settings.defaultTarget;
-
-    if (!installedTargets.includes(selectedTargetId)) {
-      const installation = targetInstaller.getInstallationInfo(selectedTargetId);
-      log.warn(`${installation?.name} not installed`);
-      const installed = await targetInstaller.install(selectedTargetId, true);
-
-      if (!installed) {
-        log.error('Cannot proceed: installation failed');
-        process.exit(1);
-      }
-    }
-  }
+  const selectedTargetId = await selectTarget(
+    installedTargets,
+    settings,
+    configService,
+    targetInstaller
+  );
 
   // Get target name for header
   const targetInstallation = targetInstaller.getInstallationInfo(selectedTargetId);
@@ -239,63 +271,34 @@ export async function executeFlowV2(
   // Show minimal header
   showHeader(version, targetName);
 
-  // Step 2: Start background auto-upgrade (non-blocking)
+  // Start background auto-upgrade (non-blocking)
   new AutoUpgrade().start();
 
-  // Create executor
   const executor = new FlowExecutor();
 
-  // Step 3: Execute attach mode lifecycle
   try {
     // Attach Flow environment (backup → attach → register cleanup)
     const attachResult = await executor.execute(projectPath, {
       verbose: options.verbose,
       skipBackup: false,
       skipSecrets: false,
-      skipProjectDocs: true, // Use /init command for project docs
+      skipProjectDocs: true,
       merge: options.merge || false,
     });
 
-    // Show attach summary
     showAttachSummary(attachResult);
 
-    const targetId = selectedTargetId;
-
     // Provider selection (Claude Code only, silent unless prompting)
-    if (targetId === 'claude-code') {
+    if (selectedTargetId === 'claude-code') {
       await selectProvider(configService);
     }
 
-    // Determine which agent to use
-    const flowConfig = await configService.loadFlowConfig();
-    let agent = options.agent || settings.defaultAgent || 'builder';
-
-    // Check if agent is enabled (silent fallback)
-    if (!flowConfig.agents[agent]?.enabled) {
-      const enabledAgents = await configService.getEnabledAgents();
-      agent = enabledAgents.length > 0 ? enabledAgents[0] : 'builder';
-    }
-
-    // Load agent content (parallel fetch rules and styles)
-    const [enabledRules, enabledOutputStyles] = await Promise.all([
-      configService.getEnabledRules(),
-      configService.getEnabledOutputStyles(),
-    ]);
-
-    const agentContent = await loadAgentContent(
-      agent,
-      options.agentFile,
-      enabledRules,
-      enabledOutputStyles
-    );
-    const agentInstructions = extractAgentInstructions(agentContent);
-
-    const systemPrompt = `AGENT INSTRUCTIONS:\n${agentInstructions}`;
+    // Load agent and build prompts
+    const { agent, systemPrompt } = await loadAgent(options, settings, configService);
     const userPrompt = prompt?.trim() || '';
 
-    // Prepare run options
     const runOptions: RunCommandOptions = {
-      target: targetId,
+      target: selectedTargetId,
       verbose: options.verbose || false,
       dryRun: options.dryRun || false,
       agent,
@@ -305,30 +308,25 @@ export async function executeFlowV2(
       continue: options.continue,
     };
 
-    // Step 4: Execute command
-    await executeTargetCommand(targetId, systemPrompt, userPrompt, runOptions);
-
-    // Step 5: Cleanup (silent)
+    await executeTargetCommand(selectedTargetId, systemPrompt, userPrompt, runOptions);
     await executor.cleanup(projectPath);
   } catch (error) {
-    // Handle user cancellation gracefully
     if (error instanceof UserCancelledError) {
       log.warn('Cancelled');
       try {
         await executor.cleanup(projectPath);
-      } catch {
-        // Silent cleanup failure
+      } catch (cleanupError) {
+        debug('cleanup after cancel failed:', cleanupError);
       }
       process.exit(0);
     }
 
     console.error(chalk.red('\n  Error:'), error);
 
-    // Ensure cleanup even on error
     try {
       await executor.cleanup(projectPath);
-    } catch {
-      // Silent cleanup failure
+    } catch (cleanupError) {
+      debug('cleanup after error failed:', cleanupError);
     }
 
     throw error;

package/src/commands/flow-command.ts

@@ -81,6 +81,53 @@ export const statusCommand = new Command('status')
     }
   });
 
+async function checkClaudeCodeInstalled(): Promise<boolean> {
+  console.log('检查 Claude Code 安装...');
+  try {
+    const { exec } = await import('node:child_process');
+    const { promisify } = await import('node:util');
+    const execAsync = promisify(exec);
+    await execAsync('which claude');
+    console.log(chalk.green('  ✓ Claude Code 已安装'));
+    return true;
+  } catch {
+    console.log(chalk.red('  ✗ Claude Code 未安装'));
+    console.log(chalk.dim('    运行: npm install -g @anthropic-ai/claude-code'));
+    return false;
+  }
+}
+
+async function checkConfiguration(
+  state: Awaited<ReturnType<StateDetector['detect']>>,
+  fix: boolean
+): Promise<boolean> {
+  console.log('\n检查配置...');
+  if (state.corrupted) {
+    console.log(chalk.red('  ✗ 配置损坏'));
+    if (fix) {
+      console.log(chalk.yellow('  🔄 正在修复...'));
+      await executeFlow(undefined, { sync: true });
+      console.log(chalk.green('  ✓ 已修复'));
+    }
+    return false;
+  }
+  if (state.initialized) {
+    console.log(chalk.green('  ✓ 配置正常'));
+    return true;
+  }
+  console.log(chalk.yellow('  ⚠ 项目未初始化'));
+  return false;
+}
+
+function checkComponents(state: Awaited<ReturnType<StateDetector['detect']>>): void {
+  console.log('\n检查组件...');
+  for (const [name, component] of Object.entries(state.components)) {
+    const status = component.installed ? chalk.green('✓') : chalk.red('✗');
+    const count = 'count' in component && component.count ? ` (${component.count})` : '';
+    console.log(`  ${status} ${name}${count}`);
+  }
+}
+
 /**
  * Doctor command - diagnose and fix issues
  */
@@ -94,49 +141,12 @@ export const doctorCommand = new Command('doctor')
     const detector = new StateDetector();
     const state = await detector.detect();
 
-    let issuesFound = false;
-
-    // Check 1: Claude Code installation
-    console.log('检查 Claude Code 安装...');
-    try {
-      const { exec } = await import('node:child_process');
-      const { promisify } = await import('node:util');
-      const execAsync = promisify(exec);
-      await execAsync('which claude');
-      console.log(chalk.green('  ✓ Claude Code 已安装'));
-    } catch {
-      console.log(chalk.red('  ✗ Claude Code 未安装'));
-      console.log(chalk.dim('    运行: npm install -g @anthropic-ai/claude-code'));
-      issuesFound = true;
-    }
-
-    // Check 2: Configuration
-    console.log('\n检查配置...');
-    if (state.corrupted) {
-      console.log(chalk.red('  ✗ 配置损坏'));
-      issuesFound = true;
-
-      if (options.fix) {
-        console.log(chalk.yellow('  🔄 正在修复...'));
-        await executeFlow(undefined, { sync: true } as FlowOptions);
-        console.log(chalk.green('  ✓ 已修复'));
-      }
-    } else if (state.initialized) {
-      console.log(chalk.green('  ✓ 配置正常'));
-    } else {
-      console.log(chalk.yellow('  ⚠ 项目未初始化'));
-      issuesFound = true;
-    }
+    const installOk = await checkClaudeCodeInstalled();
+    const configOk = await checkConfiguration(state, options.fix);
+    checkComponents(state);
 
-    // Check 3: Components
-    console.log('\n检查组件...');
-    Object.entries(state.components).forEach(([name, component]) => {
-      const status = component.installed ? chalk.green('✓') : chalk.red('✗');
-      const count = 'count' in component && component.count ? ` (${component.count})` : '';
-      console.log(`  ${status} ${name}${count}`);
-    });
+    const issuesFound = !installOk || !configOk;
 
-    // Summary
     console.log(`\n${chalk.bold('结果:')}`);
     if (!issuesFound) {
       console.log(chalk.green('✓ 所有检查通过'));
@@ -241,7 +251,7 @@ export const quickstartCommand = new Command('quickstart')
 
     if (tryNow) {
       console.log(chalk.dim('\nLaunching Flow...\n'));
-      await executeFlow('describe this codebase briefly', { agent: 'builder' } as FlowOptions);
+      await executeFlow('describe this codebase briefly', { agent: 'builder' });
     } else {
       console.log(chalk.green("\n✨ You're ready to go!\n"));
       console.log(chalk.dim('  Run: sylphx-flow "your first task"\n'));

package/src/config/index.ts

@@ -1,27 +1,7 @@
 /**
  * Configuration modules barrel export
- * Centralized access to configuration-related functionality
  */
 
-// Rules configuration
 export * from './rules.js';
-export {
-  getDefaultRules,
-  loadRuleConfiguration,
-  validateRuleConfiguration,
-} from './rules.js';
-// MCP server configurations
 export * from './servers.js';
-export {
-  configureServer,
-  getServerConfigurations,
-  validateServerConfiguration,
-} from './servers.js';
-// Target configurations
 export * from './targets.js';
-// Re-export commonly used configuration functions with better naming
-export {
-  configureTargetDefaults,
-  getTargetDefaults,
-  validateTargetConfiguration,
-} from './targets.js';

package/src/core/agent-loader.ts

@@ -8,7 +8,7 @@ import { homedir } from 'node:os';
 import { dirname, join, parse, relative } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import matter from 'gray-matter';
-import type { Agent, AgentMetadata } from '../types/agent.types.js';
+import type { Agent, AgentDefinition } from '../types/agent.types.js';
 
 /**
  * Load a single agent from a markdown file
@@ -28,7 +28,7 @@ export async function loadAgentFromFile(
       return null;
     }
 
-    const metadata: AgentMetadata = {
+    const metadata: AgentDefinition = {
       name: data.name,
       description: data.description || '',
     };

package/src/core/attach-manager.ts

@@ -10,6 +10,7 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import { MCP_SERVER_REGISTRY, type MCPServerID } from '../config/servers.js';
 import { GlobalConfigService } from '../services/global-config.js';
+import type { MCPServerConfigUnion } from '../types/mcp.types.js';
 import type { Target } from '../types/target.types.js';
 import { attachItemsToDir, attachRulesFile } from './attach/index.js';
 import type { BackupManifest } from './backup-manager.js';
@@ -320,7 +321,10 @@ export class AttachManager {
     // Add Flow MCP servers
     for (const server of mcpServers) {
       // Transform the server config for this target
-      const transformedConfig = target.transformMCPConfig(server.config as any, server.name);
+      const transformedConfig = target.transformMCPConfig(
+        server.config as MCPServerConfigUnion,
+        server.name
+      );
 
       if (mcpContainer[server.name]) {
         // Conflict: user has same MCP server