@sylphx/flow 3.18.0 → 3.19.0

package/src/core/project-manager.ts

@@ -4,14 +4,18 @@
  * All projects store data in ~/.sylphx-flow/ isolated by project hash
  */
 
+import { exec } from 'node:child_process';
 import crypto from 'node:crypto';
 import { existsSync } from 'node:fs';
 import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
+import { promisify } from 'node:util';
 import type { Target } from '../types/target.types.js';
 import { targetManager } from './target-manager.js';
 
+const execAsync = promisify(exec);
+
 export interface ProjectPaths {
   sessionFile: string;
   backupsDir: string;
@@ -63,26 +67,20 @@ export class ProjectManager {
    * Initialize Flow directories
    */
   async initialize(): Promise<void> {
-    const dirs = [
-      this.flowHomeDir,
-      path.join(this.flowHomeDir, 'sessions'),
-      path.join(this.flowHomeDir, 'backups'),
-      path.join(this.flowHomeDir, 'secrets'),
-      path.join(this.flowHomeDir, 'templates'),
-    ];
-
-    for (const dir of dirs) {
-      await fs.mkdir(dir, { recursive: true });
-    }
+    await Promise.all([
+      fs.mkdir(path.join(this.flowHomeDir, 'sessions'), { recursive: true }),
+      fs.mkdir(path.join(this.flowHomeDir, 'backups'), { recursive: true }),
+      fs.mkdir(path.join(this.flowHomeDir, 'secrets'), { recursive: true }),
+      fs.mkdir(path.join(this.flowHomeDir, 'templates'), { recursive: true }),
+    ]);
   }
 
   /**
-   * Check if a command is available on the system
+   * Check if a command is available on the system (non-blocking)
    */
   private async isCommandAvailable(command: string): Promise<boolean> {
     try {
-      const { execSync } = await import('node:child_process');
-      execSync(`which ${command}`, { stdio: 'ignore' });
+      await execAsync(`which ${command}`, { timeout: 5000 });
       return true;
     } catch {
       return false;

package/src/core/session-manager.ts

@@ -208,6 +208,34 @@ export class SessionManager {
     }
   }
 
+  /**
+   * Prune old session history files to prevent unbounded accumulation
+   * Keeps the most recent N history entries (sorted by session timestamp in filename)
+   */
+  async cleanupSessionHistory(keepLast: number = 50): Promise<void> {
+    const flowHome = this.projectManager.getFlowHomeDir();
+    const historyDir = path.join(flowHome, 'sessions', 'history');
+
+    if (!existsSync(historyDir)) {
+      return;
+    }
+
+    const files = await fs.readdir(historyDir);
+    const sessionFiles = files
+      .filter((f) => f.endsWith('.json'))
+      .sort() // session-{timestamp}.json sorts chronologically
+      .reverse(); // newest first
+
+    // Delete files beyond keepLast
+    for (const file of sessionFiles.slice(keepLast)) {
+      try {
+        await fs.unlink(path.join(historyDir, file));
+      } catch {
+        // Ignore errors — file might already be deleted
+      }
+    }
+  }
+
   /**
    * Recover from crashed session
    */
@@ -230,37 +258,4 @@ export class SessionManager {
       // File might not exist
     }
   }
-
-  /**
-   * Clean up old session history
-   */
-  async cleanupOldSessions(keepLast: number = 10): Promise<void> {
-    const flowHome = this.projectManager.getFlowHomeDir();
-    const historyDir = path.join(flowHome, 'sessions', 'history');
-
-    if (!existsSync(historyDir)) {
-      return;
-    }
-
-    const files = await fs.readdir(historyDir);
-    const sessions = await Promise.all(
-      files.map(async (file) => {
-        const filePath = path.join(historyDir, file);
-        const data = await fs.readFile(filePath, 'utf-8');
-        const session = JSON.parse(data) as Session;
-        return { file, session };
-      })
-    );
-
-    // Sort by start time (newest first)
-    sessions.sort(
-      (a, b) => new Date(b.session.startTime).getTime() - new Date(a.session.startTime).getTime()
-    );
-
-    // Remove old sessions
-    const toRemove = sessions.slice(keepLast);
-    for (const { file } of toRemove) {
-      await fs.unlink(path.join(historyDir, file));
-    }
-  }
 }

package/src/core/state-detector.ts

@@ -3,7 +3,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { ConfigService } from '../services/config-service.js';
 import type { Target } from '../types/target.types.js';
-import { targetManager } from './target-manager.js';
+import { tryResolveTarget } from './target-resolver.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -43,17 +43,6 @@ export class StateDetector {
     this.projectPath = projectPath;
   }
 
-  /**
-   * Resolve target from ID string to Target object
-   */
-  private resolveTarget(targetId: string): Target | null {
-    const targetOption = targetManager.getTarget(targetId);
-    if (targetOption._tag === 'None') {
-      return null;
-    }
-    return targetOption.value;
-  }
-
   async detect(): Promise<ProjectState> {
     const state: ProjectState = {
       initialized: false,
@@ -95,7 +84,7 @@ export class StateDetector {
       }
 
       // Resolve target to get config
-      const target = state.target ? this.resolveTarget(state.target) : null;
+      const target = state.target ? tryResolveTarget(state.target) : null;
 
       // Check components based on target config
       if (target) {
@@ -376,7 +365,7 @@ export class StateDetector {
     targetId: string
   ): Promise<{ version: string | null; latestVersion: string | null }> {
     try {
-      const target = this.resolveTarget(targetId);
+      const target = tryResolveTarget(targetId);
       if (!target) {
         return { version: null, latestVersion: null };
       }
@@ -428,7 +417,7 @@ export class StateDetector {
 
     // Check required components based on target
     if (state.initialized && state.target) {
-      const target = this.resolveTarget(state.target);
+      const target = tryResolveTarget(state.target);
       // CLI-based targets (category: 'cli') require agents to be installed
       if (target && target.category === 'cli' && !state.components.agents.installed) {
         return true; // CLI target initialized but no agents

package/src/core/target-resolver.ts

@@ -1,27 +1,32 @@
 /**
- * Target Resolver
- * Shared utility for resolving target IDs to Target objects
- * Eliminates duplication across BackupManager and SecretsManager
+ * Target Resolver — Single Source of Truth for target ID → Target resolution
  */
 
 import type { Target } from '../types/target.types.js';
 import { targetManager } from './target-manager.js';
 
 /**
- * Resolve a target from ID string to Target object
+ * Resolve target ID to Target object, returns null if not found
+ */
+export function tryResolveTarget(targetId: string): Target | null {
+  const targetOption = targetManager.getTarget(targetId);
+  return targetOption._tag === 'Some' ? targetOption.value : null;
+}
+
+/**
+ * Resolve target ID to Target object
  * @throws Error if target ID is not found
  */
 export function resolveTarget(targetId: string): Target {
-  const targetOption = targetManager.getTarget(targetId);
-  if (targetOption._tag === 'None') {
+  const target = tryResolveTarget(targetId);
+  if (!target) {
     throw new Error(`Unknown target: ${targetId}`);
   }
-  return targetOption.value;
+  return target;
 }
 
 /**
- * Resolve target, accepting either string ID or Target object
- * Returns the Target object in both cases
+ * Resolve target from either string ID or Target object
  */
 export function resolveTargetOrId(targetOrId: Target | string): Target {
   return typeof targetOrId === 'string' ? resolveTarget(targetOrId) : targetOrId;

package/src/core/template-loader.ts

@@ -30,15 +30,13 @@ export class TemplateLoader {
     const commandsDir = path.join(this.assetsDir, 'slash-commands');
     const skillsDir = path.join(this.assetsDir, 'skills');
     const mcpConfigPath = path.join(this.assetsDir, 'mcp-servers.json');
-    const outputStylesDir = path.join(this.assetsDir, 'output-styles');
 
     // Load all directories in parallel
-    const [agents, commands, skills, mcpServers, singleFiles, rules] = await Promise.all([
+    const [agents, commands, skills, mcpServers, rules] = await Promise.all([
       existsSync(agentsDir) ? this.loadAgents(agentsDir) : [],
       existsSync(commandsDir) ? this.loadCommands(commandsDir) : [],
       existsSync(skillsDir) ? this.loadSkills(skillsDir) : [],
       existsSync(mcpConfigPath) ? this.loadMCPServers(mcpConfigPath) : [],
-      existsSync(outputStylesDir) ? this.loadSingleFiles(outputStylesDir) : [],
       this.loadRules(),
     ]);
 
@@ -48,8 +46,7 @@ export class TemplateLoader {
       skills,
       rules,
       mcpServers,
-      hooks: [],
-      singleFiles,
+      singleFiles: [],
     };
   }
 
@@ -134,11 +131,13 @@ export class TemplateLoader {
   /**
    * Load MCP servers configuration
    */
-  private async loadMCPServers(configPath: string): Promise<Array<{ name: string; config: any }>> {
+  private async loadMCPServers(
+    configPath: string
+  ): Promise<Array<{ name: string; config: Record<string, unknown> }>> {
     const data = await fs.readFile(configPath, 'utf-8');
-    const config = JSON.parse(data);
+    const config = JSON.parse(data) as Record<string, Record<string, unknown>>;
 
-    const servers = [];
+    const servers: Array<{ name: string; config: Record<string, unknown> }> = [];
     for (const [name, serverConfig] of Object.entries(config)) {
       servers.push({ name, config: serverConfig });
     }
@@ -146,31 +145,6 @@ export class TemplateLoader {
     return servers;
   }
 
-  /**
-   * Load single files (parallel loading)
-   */
-  private async loadSingleFiles(
-    singleFilesDir: string
-  ): Promise<Array<{ path: string; content: string }>> {
-    const entries = await fs.readdir(singleFilesDir);
-
-    const results = await Promise.all(
-      entries.map(async (entry) => {
-        const filePath = path.join(singleFilesDir, entry);
-        const stat = await fs.stat(filePath);
-
-        if (!stat.isFile()) {
-          return null;
-        }
-
-        const content = await fs.readFile(filePath, 'utf-8');
-        return { path: entry, content };
-      })
-    );
-
-    return results.filter((r): r is { path: string; content: string } => r !== null);
-  }
-
   /**
    * Get assets directory path
    */

package/src/core/upgrade-manager.ts

@@ -9,7 +9,7 @@ import { CLIError } from '../utils/error-handler.js';
 import { detectPackageManager, getUpgradeCommand } from '../utils/package-manager-detector.js';
 import { createSpinner, log } from '../utils/prompts/index.js';
 import type { ProjectState } from './state-detector.js';
-import { targetManager } from './target-manager.js';
+import { tryResolveTarget } from './target-resolver.js';
 
 const execAsync = promisify(exec);
 
@@ -152,23 +152,12 @@ export class UpgradeManager {
     }
   }
 
-  /**
-   * Resolve target from ID string to Target object
-   */
-  private resolveTarget(targetId: string): Target | null {
-    const targetOption = targetManager.getTarget(targetId);
-    if (targetOption._tag === 'None') {
-      return null;
-    }
-    return targetOption.value;
-  }
-
   async upgradeTarget(state: ProjectState, autoInstall: boolean = false): Promise<boolean> {
     if (!state.target || !state.targetLatestVersion) {
       return false;
     }
 
-    const target = this.resolveTarget(state.target);
+    const target = tryResolveTarget(state.target);
     if (!target) {
       return false;
     }
@@ -263,7 +252,7 @@ export class UpgradeManager {
       const configPath = path.join(this.projectPath, getProjectSettingsFile());
       const config = JSON.parse(await fs.readFile(configPath, 'utf-8'));
       if (config.target) {
-        return this.resolveTarget(config.target);
+        return tryResolveTarget(config.target);
       }
     } catch {
       // Cannot read config
@@ -355,7 +344,7 @@ export class UpgradeManager {
   }
 
   private async getCurrentTargetVersion(targetId: string): Promise<string | null> {
-    const target = this.resolveTarget(targetId);
+    const target = tryResolveTarget(targetId);
     if (!target) {
       return null;
     }

package/src/index.ts

@@ -98,48 +98,19 @@ export async function runCLI(): Promise<void> {
  * Set up global error handlers for uncaught exceptions and unhandled rejections
  */
 function setupGlobalErrorHandling(): void {
-  // Handle uncaught exceptions
-  process.on('uncaughtException', (error) => {
-    console.error('✗ Uncaught Exception:');
-    console.error(`  ${error.message}`);
-    if (process.env.NODE_ENV === 'development') {
-      console.error('  Stack trace:', error.stack);
-    }
-    process.exit(1);
-  });
-
-  // Handle unhandled promise rejections
-  process.on('unhandledRejection', (reason, promise) => {
-    // Ignore AbortError - this is expected when user cancels operations
+  // Handle unhandled promise rejections (non-fatal, log only)
+  process.on('unhandledRejection', (reason) => {
+    // Ignore AbortError — expected when user cancels operations
     if (reason instanceof Error && reason.name === 'AbortError') {
       return;
     }
-
-    // Only log unhandled rejections in development mode
-    // Don't exit the process - let the application handle errors gracefully
     if (process.env.NODE_ENV === 'development' || process.env.DEBUG) {
-      console.error('✗ Unhandled Promise Rejection:');
-      console.error(`  Reason: ${reason}`);
-      console.error('  Promise:', promise);
+      console.error('✗ Unhandled Promise Rejection:', reason);
     }
   });
 
-  // Handle process termination gracefully
-  process.on('SIGINT', () => {
-    console.log('\nSylphx Flow CLI terminated by user');
-    process.exit(0);
-  });
-
-  process.on('SIGTERM', () => {
-    console.log('\nSylphx Flow CLI terminated');
-    process.exit(0);
-  });
-
-  // Ensure clean exit by allowing the event loop to drain
-  process.on('beforeExit', () => {
-    // Node.js will exit automatically after this handler completes
-    // No explicit process.exit() needed
-  });
+  // SIGINT/SIGTERM are handled by CleanupHandler which does async backup restoration.
+  // DO NOT register handlers here — process.exit() would preempt cleanup.
 }
 
 /**

package/src/targets/claude-code.ts

@@ -2,11 +2,8 @@ import { spawn } from 'node:child_process';
 import fsPromises from 'node:fs/promises';
 import path from 'node:path';
 import chalk from 'chalk';
-import { installToDirectory } from '../core/installers/file-installer.js';
-import { createMCPInstaller } from '../core/installers/mcp-installer.js';
 import type { AgentMetadata, FrontMatterMetadata } from '../types/target-config.types.js';
 import type { CommonOptions, MCPServerConfigUnion, SetupResult, Target } from '../types.js';
-import { getAgentsDir } from '../utils/config/paths.js';
 import {
   type ConfigData,
   fileUtils,
@@ -16,9 +13,9 @@ import {
 } from '../utils/config/target-utils.js';
 import { CLIError } from '../utils/error-handler.js';
 import { sanitize } from '../utils/security/security.js';
+import { DEFAULT_CLAUDE_CODE_ENV } from './functional/claude-code-logic.js';
 import {
   detectTargetConfig,
-  setupSlashCommandsTo,
   stripFrontMatter,
   transformMCPConfig as transformMCP,
 } from './shared/index.js';
@@ -70,6 +67,7 @@ export const claudeCodeTarget: Target = {
       createConfigFile: true,
       useSecretFiles: false,
     },
+    supportsMCP: true,
   },
 
   /**
@@ -271,7 +269,7 @@ Please begin your response with a comprehensive summary of all the instructions
         const child = spawn('claude', args, {
           stdio: 'inherit',
           shell: false,
-          env: process.env, // Pass environment variables including ANTHROPIC_BASE_URL and ANTHROPIC_API_KEY
+          env: { ...process.env, ...DEFAULT_CLAUDE_CODE_ENV },
         });
 
         child.on('spawn', () => {
@@ -298,17 +296,17 @@ Please begin your response with a comprehensive summary of all the instructions
         });
       });
     } catch (error: unknown) {
-      const err = error as NodeJS.ErrnoException & { code?: string | number };
-      if (err.code === 'ENOENT') {
-        throw new CLIError('Claude Code not found. Please install it first.', 'CLAUDE_NOT_FOUND');
-      }
-      if (err.code) {
-        throw new CLIError(`Claude Code exited with code ${err.code}`, 'CLAUDE_ERROR');
+      if (error instanceof Error) {
+        const errWithCode = error as Error & { code?: string | number };
+        if (errWithCode.code === 'ENOENT') {
+          throw new CLIError('Claude Code not found. Please install it first.', 'CLAUDE_NOT_FOUND');
+        }
+        if (errWithCode.code !== undefined) {
+          throw new CLIError(`Claude Code exited with code ${errWithCode.code}`, 'CLAUDE_ERROR');
+        }
+        throw new CLIError(`Failed to execute Claude Code: ${error.message}`, 'CLAUDE_ERROR');
       }
-      throw new CLIError(
-        `Failed to execute Claude Code: ${(error as Error).message}`,
-        'CLAUDE_ERROR'
-      );
+      throw new CLIError(`Failed to execute Claude Code: ${String(error)}`, 'CLAUDE_ERROR');
     }
   },
 
@@ -370,10 +368,10 @@ Please begin your response with a comprehensive summary of all the instructions
   transformRulesContent: stripFrontMatter,
 
   /**
-   * Setup hooks for Claude Code
-   * Configure session and prompt hooks for system information display
+   * Apply Claude Code settings (attribution, hooks, env, thinking mode)
+   * Merges Flow defaults into .claude/settings.json, preserving user settings
    */
-  async setupHooks(cwd: string, _options: CommonOptions): Promise<SetupResult> {
+  async applySettings(cwd: string, _options: CommonOptions): Promise<SetupResult> {
     const { processSettings, generateHookCommands } = await import(
       './functional/claude-code-logic.js'
     );
@@ -425,95 +423,6 @@ Please begin your response with a comprehensive summary of all the instructions
       message: 'Configured notification hook',
     };
   },
-
-  /**
-   * Setup agents for Claude Code
-   * Install agents to .claude/agents/ directory with rules appended
-   * Output styles are applied dynamically at runtime based on user settings
-   */
-  async setupAgents(cwd: string, options: CommonOptions): Promise<SetupResult> {
-    const { enhanceAgentContent } = await import('../utils/agent-enhancer.js');
-    const agentsDir = path.join(cwd, this.config.agentDir);
-
-    const results = await installToDirectory(
-      getAgentsDir(),
-      agentsDir,
-      async (content, sourcePath) => {
-        // Extract rules from ORIGINAL content before transformation
-        const { metadata } = await yamlUtils.extractFrontMatter(content);
-        const rules = metadata.rules as string[] | undefined;
-
-        // Transform agent content (converts to Claude Code format, strips unsupported fields)
-        const transformed = await this.transformAgentContent(content, undefined, sourcePath);
-
-        // Enhance with rules only (output styles are applied dynamically at runtime)
-        const enhanced = await enhanceAgentContent(transformed, rules, []);
-
-        return enhanced;
-      },
-      {
-        ...options,
-        showProgress: false, // UI handled by init-command
-      }
-    );
-
-    return { count: results.length };
-  },
-
-  /**
-   * Setup output styles for Claude Code
-   * Output styles are appended to each agent file
-   */
-  async setupOutputStyles(_cwd: string, _options: CommonOptions): Promise<SetupResult> {
-    // Output styles are appended to each agent file during setupAgents
-    // No separate installation needed
-    return {
-      count: 0,
-      message: 'Output styles included in agent files',
-    };
-  },
-
-  /**
-   * Setup rules for Claude Code
-   * Rules are appended to each agent file
-   */
-  async setupRules(_cwd: string, _options: CommonOptions): Promise<SetupResult> {
-    // Rules are appended to each agent file during setupAgents
-    // No separate CLAUDE.md file needed
-    return {
-      count: 0,
-      message: 'Rules included in agent files',
-    };
-  },
-
-  /**
-   * Setup MCP servers for Claude Code
-   * Select, configure, install, and approve MCP servers
-   */
-  async setupMCP(cwd: string, options: CommonOptions): Promise<SetupResult> {
-    const installer = createMCPInstaller(this);
-    const result = await installer.setupMCP({ ...options, quiet: true });
-
-    // Approve servers in Claude Code settings
-    if (result.selectedServers.length > 0 && !options.dryRun) {
-      if (this.approveMCPServers) {
-        await this.approveMCPServers(cwd, result.selectedServers);
-      }
-    }
-
-    return { count: result.selectedServers.length };
-  },
-
-  /**
-   * Setup slash commands for Claude Code
-   * Install slash command templates to .claude/commands/ directory
-   */
-  async setupSlashCommands(cwd: string, options: CommonOptions): Promise<SetupResult> {
-    if (!this.config.slashCommandsDir) {
-      return { count: 0 };
-    }
-    return setupSlashCommandsTo(path.join(cwd, this.config.slashCommandsDir), undefined, options);
-  },
 };
 
 /**