@sylphx/flow 3.18.0 → 3.19.1

package/src/core/project-manager.ts

@@ -4,14 +4,19 @@
  * 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 { readJsonFileSafe } from '../utils/files/file-operations.js';
 import { targetManager } from './target-manager.js';
 
+const execAsync = promisify(exec);
+
 export interface ProjectPaths {
   sessionFile: string;
   backupsDir: string;
@@ -63,26 +68,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;
@@ -111,16 +110,11 @@ export class ProjectManager {
     projectHash: string
   ): Promise<'claude-code' | 'opencode' | undefined> {
     const prefsPath = path.join(this.flowHomeDir, 'project-preferences.json');
-    if (!existsSync(prefsPath)) {
-      return undefined;
-    }
-
-    try {
-      const prefs = JSON.parse(await fs.readFile(prefsPath, 'utf-8'));
-      return prefs.projects?.[projectHash]?.target;
-    } catch {
-      return undefined;
-    }
+    const prefs = await readJsonFileSafe<{ projects?: Record<string, { target?: string }> }>(
+      prefsPath,
+      {}
+    );
+    return prefs.projects?.[projectHash]?.target as 'claude-code' | 'opencode' | undefined;
   }
 
   /**
@@ -128,15 +122,10 @@ export class ProjectManager {
    */
   async saveProjectTargetPreference(projectHash: string, target: string): Promise<void> {
     const prefsPath = path.join(this.flowHomeDir, 'project-preferences.json');
-    let prefs: { projects: Record<string, { target?: string }> } = { projects: {} };
-
-    if (existsSync(prefsPath)) {
-      try {
-        prefs = JSON.parse(await fs.readFile(prefsPath, 'utf-8'));
-      } catch {
-        // Use default
-      }
-    }
+    const prefs = await readJsonFileSafe<{ projects: Record<string, { target?: string }> }>(
+      prefsPath,
+      { projects: {} }
+    );
 
     if (!prefs.projects) {
       prefs.projects = {};
@@ -189,16 +178,10 @@ export class ProjectManager {
     // If both are installed, use global default
     if (installed.claudeCode && installed.opencode) {
       const globalSettingsPath = path.join(this.flowHomeDir, 'settings.json');
-      if (existsSync(globalSettingsPath)) {
-        try {
-          const settings = JSON.parse(await fs.readFile(globalSettingsPath, 'utf-8'));
-          if (settings.defaultTarget) {
-            await this.saveProjectTargetPreference(projectHash, settings.defaultTarget);
-            return settings.defaultTarget;
-          }
-        } catch {
-          // Fall through
-        }
+      const settings = await readJsonFileSafe<{ defaultTarget?: string }>(globalSettingsPath, {});
+      if (settings.defaultTarget) {
+        await this.saveProjectTargetPreference(projectHash, settings.defaultTarget);
+        return settings.defaultTarget;
       }
 
       // Both installed, no global default, use claude-code

package/src/core/secrets-manager.ts

@@ -8,6 +8,7 @@ import { existsSync } from 'node:fs';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import type { Target } from '../types/target.types.js';
+import { readJsonFileSafe } from '../utils/files/file-operations.js';
 import type { ProjectManager } from './project-manager.js';
 import { resolveTargetOrId } from './target-resolver.js';
 
@@ -60,20 +61,26 @@ export class SecretsManager {
       const mcpServers = config[mcpPath] as Record<string, unknown> | undefined;
       if (mcpServers) {
         for (const [serverName, serverConfig] of Object.entries(mcpServers)) {
-          const server = serverConfig as any;
+          if (typeof serverConfig !== 'object' || serverConfig === null) {
+            continue;
+          }
+          const server = serverConfig as Record<string, unknown>;
 
           // Extract env vars (sensitive) - handle both 'env' and 'environment' keys
-          const envVars = server.env || server.environment;
-          if (envVars && Object.keys(envVars).length > 0) {
+          const envVars = (server.env || server.environment) as Record<string, string> | undefined;
+          if (envVars && typeof envVars === 'object' && Object.keys(envVars).length > 0) {
             secrets.servers[serverName] = {
               env: envVars,
             };
           }
 
           // Extract args (may contain secrets) - handle both 'args' and 'command' array
-          const args =
-            server.args || (Array.isArray(server.command) ? server.command.slice(1) : undefined);
-          if (args && Array.isArray(args) && args.length > 0) {
+          const args = Array.isArray(server.args)
+            ? server.args
+            : Array.isArray(server.command)
+              ? (server.command as string[]).slice(1)
+              : undefined;
+          if (args && args.length > 0) {
             if (!secrets.servers[serverName]) {
               secrets.servers[serverName] = {};
             }
@@ -105,20 +112,10 @@ export class SecretsManager {
   /**
    * Load secrets from storage
    */
-  async loadSecrets(projectHash: string): Promise<MCPSecrets | null> {
+  loadSecrets(projectHash: string): Promise<MCPSecrets | null> {
     const paths = this.projectManager.getProjectPaths(projectHash);
     const secretsPath = path.join(paths.secretsDir, 'mcp-env.json');
-
-    if (!existsSync(secretsPath)) {
-      return null;
-    }
-
-    try {
-      const data = await fs.readFile(secretsPath, 'utf-8');
-      return JSON.parse(data);
-    } catch {
-      return null;
-    }
+    return readJsonFileSafe<MCPSecrets | null>(secretsPath, null);
   }
 
   /**

package/src/core/session-manager.ts

@@ -8,6 +8,7 @@ import { existsSync } from 'node:fs';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import type { Target } from '../types/target.types.js';
+import { readJsonFileSafe } from '../utils/files/file-operations.js';
 import type { ProjectManager } from './project-manager.js';
 
 export interface Session {
@@ -143,14 +144,9 @@ export class SessionManager {
   /**
    * Get active session for a project
    */
-  async getActiveSession(projectHash: string): Promise<Session | null> {
-    try {
-      const paths = this.projectManager.getProjectPaths(projectHash);
-      const data = await fs.readFile(paths.sessionFile, 'utf-8');
-      return JSON.parse(data);
-    } catch {
-      return null;
-    }
+  getActiveSession(projectHash: string): Promise<Session | null> {
+    const paths = this.projectManager.getProjectPaths(projectHash);
+    return readJsonFileSafe<Session | null>(paths.sessionFile, null);
   }
 
   /**
@@ -208,6 +204,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 +254,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-manager.ts

@@ -8,7 +8,7 @@ import {
   getTargetsWithMCPSupport,
   isTargetImplemented,
 } from '../config/targets.js';
-import { getOrElse, isSome } from '../core/functional/option.js';
+import { isSome, match } from '../core/functional/option.js';
 import { projectSettings } from '../utils/config/settings.js';
 import { promptSelect } from '../utils/prompts/index.js';
 
@@ -85,9 +85,12 @@ export function createTargetManager(): TargetManager {
       message: 'Select target platform:',
       options: availableTargets.map((id) => {
         const targetOption = getTarget(id);
-        const target = getOrElse({ id, name: id } as any)(targetOption);
+        const label = match(
+          (t: ReturnType<typeof getAllTargets>[number]) => t.name || id,
+          () => id
+        )(targetOption);
         return {
-          label: target.name || id,
+          label,
           value: id,
         };
       }),

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

@@ -5,11 +5,11 @@ import { promisify } from 'node:util';
 import chalk from 'chalk';
 import { getProjectSettingsFile } from '../config/constants.js';
 import type { Target } from '../types/target.types.js';
-import { CLIError } from '../utils/error-handler.js';
+import { CLIError } from '../utils/errors.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.
 }
 
 /**
@@ -155,7 +126,7 @@ function handleCommandError(error: unknown): void {
 
     // Handle Commander.js specific errors
     if (error.name === 'CommanderError') {
-      const commanderError = error as any;
+      const commanderError = error as Error & { code?: string; exitCode?: number };
 
       // Don't exit for help or version commands - they should already be handled
       if (commanderError.code === 'commander.help' || commanderError.code === 'commander.version') {

package/src/services/auto-upgrade.ts

@@ -10,6 +10,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { promisify } from 'node:util';
+import { readJsonFileSafe } from '../utils/files/file-operations.js';
 import { getUpgradeCommand } from '../utils/package-manager-detector.js';
 
 const __filename = fileURLToPath(import.meta.url);
@@ -91,13 +92,8 @@ export class AutoUpgrade {
   /**
    * Read version info from disk
    */
-  private async readVersionInfo(): Promise<VersionInfo | null> {
-    try {
-      const data = await fs.readFile(VERSION_FILE, 'utf-8');
-      return JSON.parse(data);
-    } catch {
-      return null;
-    }
+  private readVersionInfo(): Promise<VersionInfo | null> {
+    return readJsonFileSafe<VersionInfo | null>(VERSION_FILE, null);
   }
 
   /**
@@ -127,13 +123,9 @@ export class AutoUpgrade {
    * Get current Flow version from package.json
    */
   private async getCurrentVersion(): 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';
   }
 
   /**