@sylphx/flow 3.19.0 → 3.20.0

package/src/core/project-manager.ts

@@ -12,6 +12,7 @@ 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);
@@ -109,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;
   }
 
   /**
@@ -126,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 = {};
@@ -187,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);
   }
 
   /**

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/upgrade-manager.ts

@@ -5,7 +5,7 @@ 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';

package/src/index.ts

@@ -126,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';
   }
 
   /**

package/src/services/config-service.ts

@@ -11,6 +11,7 @@ import {
   getProjectSettingsFile,
   USER_SETTINGS_FILE,
 } from '../config/constants.js';
+import { readJsonFileSafe } from '../utils/files/file-operations.js';
 
 /**
  * User configuration (sensitive data, saved to home directory)
@@ -102,13 +103,8 @@ export class ConfigService {
   /**
    * Load user global settings (mainly for API keys)
    */
-  static async loadHomeSettings(): Promise<UserSettings> {
-    try {
-      const content = await fs.readFile(USER_SETTINGS_FILE, 'utf-8');
-      return JSON.parse(content);
-    } catch {
-      return {};
-    }
+  static loadHomeSettings(): Promise<UserSettings> {
+    return readJsonFileSafe<UserSettings>(USER_SETTINGS_FILE, {});
   }
 
   /**
@@ -154,14 +150,8 @@ export class ConfigService {
   /**
    * Load project-level settings
    */
-  static async loadProjectSettings(cwd: string = process.cwd()): Promise<ProjectSettings> {
-    try {
-      const configPath = getProjectSettingsFile(cwd);
-      const content = await fs.readFile(configPath, 'utf-8');
-      return JSON.parse(content);
-    } catch {
-      return {};
-    }
+  static loadProjectSettings(cwd: string = process.cwd()): Promise<ProjectSettings> {
+    return readJsonFileSafe<ProjectSettings>(getProjectSettingsFile(cwd), {});
   }
 
   /**
@@ -186,14 +176,8 @@ export class ConfigService {
   /**
    * Load project-local settings (overrides everything)
    */
-  static async loadLocalSettings(cwd: string = process.cwd()): Promise<RuntimeChoices> {
-    try {
-      const configPath = getProjectLocalSettingsFile(cwd);
-      const content = await fs.readFile(configPath, 'utf-8');
-      return JSON.parse(content);
-    } catch {
-      return {};
-    }
+  static loadLocalSettings(cwd: string = process.cwd()): Promise<RuntimeChoices> {
+    return readJsonFileSafe<RuntimeChoices>(getProjectLocalSettingsFile(cwd), {});
   }
 
   /**

package/src/services/index.ts

@@ -10,4 +10,4 @@ export {
   installServers,
   listAvailableServers,
   validateServerConfiguration,
-} from './mcp-service';
+} from './mcp-service.js';

package/src/targets/claude-code.ts

@@ -11,7 +11,7 @@ import {
   pathUtils,
   yamlUtils,
 } from '../utils/config/target-utils.js';
-import { CLIError } from '../utils/error-handler.js';
+import { CLIError } from '../utils/errors.js';
 import { sanitize } from '../utils/security/security.js';
 import { DEFAULT_CLAUDE_CODE_ENV } from './functional/claude-code-logic.js';
 import {
@@ -37,6 +37,11 @@ interface ProcessExitError extends Error {
   code: number | null;
 }
 
+/** Type guard for Node.js errors with errno/code properties */
+function isNodeError(error: unknown): error is NodeJS.ErrnoException {
+  return error instanceof Error && 'code' in error;
+}
+
 /**
  * Claude Code target - composition approach with all original functionality
  */
@@ -296,16 +301,18 @@ Please begin your response with a comprehensive summary of all the instructions
         });
       });
     } catch (error: unknown) {
-      if (error instanceof Error) {
-        const errWithCode = error as Error & { code?: string | number };
-        if (errWithCode.code === 'ENOENT') {
+      if (isNodeError(error)) {
+        if (error.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');
+        if (error.code !== undefined) {
+          throw new CLIError(`Claude Code exited with code ${error.code}`, 'CLAUDE_ERROR');
         }
         throw new CLIError(`Failed to execute Claude Code: ${error.message}`, 'CLAUDE_ERROR');
       }
+      if (error instanceof Error) {
+        throw new CLIError(`Failed to execute Claude Code: ${error.message}`, 'CLAUDE_ERROR');
+      }
       throw new CLIError(`Failed to execute Claude Code: ${String(error)}`, 'CLAUDE_ERROR');
     }
   },
@@ -331,8 +338,7 @@ Please begin your response with a comprehensive summary of all the instructions
         const content = await fsPromises.readFile(settingsPath, 'utf8');
         settings = JSON.parse(content);
       } catch (error: unknown) {
-        const err = error as NodeJS.ErrnoException;
-        if (err.code !== 'ENOENT') {
+        if (!isNodeError(error) || error.code !== 'ENOENT') {
           throw error;
         }
         // File doesn't exist, will create new

package/src/targets/functional/claude-code-logic.ts

@@ -66,6 +66,7 @@ const DEFAULT_CLAUDE_CODE_SETTINGS: Partial<ClaudeCodeSettings> = {
 
 export interface HookConfig {
   notificationCommand?: string;
+  sessionStartCommand?: string;
 }
 
 /**
@@ -75,15 +76,16 @@ export interface HookConfig {
 export const generateHookCommands = async (targetId: string): Promise<HookConfig> => {
   return {
     notificationCommand: `sylphx-flow hook --type notification --target ${targetId}`,
+    sessionStartCommand: `sylphx-flow hook --type session-start --target ${targetId}`,
   };
 };
 
 /**
  * Default hook commands (fallback)
- * Simplified to only include notification hook
  */
 const DEFAULT_HOOKS: HookConfig = {
   notificationCommand: 'sylphx-flow hook --type notification --target claude-code',
+  sessionStartCommand: 'sylphx-flow hook --type session-start --target claude-code',
 };
 
 /**
@@ -94,17 +96,19 @@ export const processSettings = (
   hookConfig: HookConfig = DEFAULT_HOOKS
 ): Result<string, ConfigError> => {
   const notificationCommand = hookConfig.notificationCommand || DEFAULT_HOOKS.notificationCommand!;
+  const sessionStartCommand = hookConfig.sessionStartCommand || DEFAULT_HOOKS.sessionStartCommand!;
 
   const hookConfiguration: ClaudeCodeSettings['hooks'] = {
     Notification: [
       {
         matcher: '',
-        hooks: [
-          {
-            type: 'command',
-            command: notificationCommand,
-          },
-        ],
+        hooks: [{ type: 'command', command: notificationCommand }],
+      },
+    ],
+    SessionStart: [
+      {
+        matcher: '',
+        hooks: [{ type: 'command', command: sessionStartCommand }],
       },
     ],
   };

package/src/targets/opencode.ts

@@ -2,8 +2,13 @@ import chalk from 'chalk';
 import { MCP_SERVER_REGISTRY } from '../config/servers.js';
 import type { AgentMetadata } from '../types/target-config.types.js';
 import type { MCPServerConfigUnion, Target } from '../types.js';
-import { fileUtils, generateHelpText, yamlUtils } from '../utils/config/target-utils.js';
-import { CLIError } from '../utils/error-handler.js';
+import {
+  type ConfigData,
+  fileUtils,
+  generateHelpText,
+  yamlUtils,
+} from '../utils/config/target-utils.js';
+import { CLIError } from '../utils/errors.js';
 import { secretUtils } from '../utils/security/secret-utils.js';
 import {
   detectTargetConfig,
@@ -11,6 +16,49 @@ import {
   transformMCPConfig as transformMCP,
 } from './shared/index.js';
 
+/** OpenCode configuration data with MCP config */
+interface OpenCodeConfigData extends ConfigData {
+  mcp?: Record<string, unknown>;
+}
+
+/**
+ * Convert secret environment variables in a single MCP server config to file references
+ */
+async function convertServerSecrets(
+  cwd: string,
+  serverId: string,
+  serverConfig: Record<string, unknown>
+): Promise<void> {
+  if (!serverConfig || typeof serverConfig !== 'object' || !('environment' in serverConfig)) {
+    return;
+  }
+
+  const envVars = serverConfig.environment as Record<string, string>;
+  if (!envVars || typeof envVars !== 'object') {
+    return;
+  }
+
+  const serverDef = Object.values(MCP_SERVER_REGISTRY).find((s) => s.name === serverId);
+  if (!serverDef?.envVars) {
+    return;
+  }
+
+  const secretEnvVars: Record<string, string> = {};
+  const nonSecretEnvVars: Record<string, string> = {};
+
+  for (const [key, value] of Object.entries(envVars)) {
+    const envConfig = serverDef.envVars[key];
+    if (envConfig?.secret && value && !secretUtils.isFileReference(value)) {
+      secretEnvVars[key] = value;
+    } else {
+      nonSecretEnvVars[key] = value;
+    }
+  }
+
+  const convertedSecrets = await secretUtils.convertSecretsToFileReferences(cwd, secretEnvVars);
+  serverConfig.environment = { ...nonSecretEnvVars, ...convertedSecrets };
+}
+
 /**
  * OpenCode target - composition approach with all original functionality
  */
@@ -92,11 +140,14 @@ export const opencodeTarget: Target = {
   /**
    * Read OpenCode configuration with structure normalization
    */
-  async readConfig(cwd: string): Promise<any> {
+  async readConfig(cwd: string): Promise<OpenCodeConfigData> {
     const config = await fileUtils.readConfig(opencodeTarget.config, cwd);
 
     // Resolve any file references in the configuration
-    const resolvedConfig = await secretUtils.resolveFileReferences(cwd, config);
+    const resolvedConfig = (await secretUtils.resolveFileReferences(
+      cwd,
+      config
+    )) as OpenCodeConfigData;
 
     // Ensure the config has the expected structure
     if (!resolvedConfig.mcp) {
@@ -110,46 +161,17 @@ export const opencodeTarget: Target = {
    * Write OpenCode configuration with structure normalization
    */
   async writeConfig(cwd: string, config: Record<string, unknown>): Promise<void> {
-    // Ensure the config has the expected structure for OpenCode
     if (!config.mcp) {
       config.mcp = {};
     }
 
-    // Convert secrets to file references if secret files are enabled
     if (opencodeTarget.config.installation?.useSecretFiles) {
-      // Process each MCP server's environment variables
-      for (const [serverId, serverConfig] of Object.entries(config.mcp || {})) {
-        if (serverConfig && typeof serverConfig === 'object' && 'environment' in serverConfig) {
-          const envVars = serverConfig.environment as Record<string, string>;
-          if (envVars && typeof envVars === 'object') {
-            // Find the corresponding server definition to get secret env vars
-            const serverDef = Object.values(MCP_SERVER_REGISTRY).find((s) => s.name === serverId);
-            if (serverDef?.envVars) {
-              // Separate secret and non-secret variables
-              const secretEnvVars: Record<string, string> = {};
-              const nonSecretEnvVars: Record<string, string> = {};
-
-              for (const [key, value] of Object.entries(envVars)) {
-                const envConfig = serverDef.envVars[key];
-                if (envConfig?.secret && value && !secretUtils.isFileReference(value)) {
-                  secretEnvVars[key] = value;
-                } else {
-                  nonSecretEnvVars[key] = value;
-                }
-              }
-
-              // Convert only secret variables
-              const convertedSecrets = await secretUtils.convertSecretsToFileReferences(
-                cwd,
-                secretEnvVars
-              );
-
-              // Merge back
-              serverConfig.environment = { ...nonSecretEnvVars, ...convertedSecrets };
-            }
-          }
-        }
-      }
+      const mcpServers = config.mcp as Record<string, Record<string, unknown>>;
+      await Promise.all(
+        Object.entries(mcpServers).map(([serverId, serverConfig]) =>
+          convertServerSecrets(cwd, serverId, serverConfig)
+        )
+      );
     }
 
     await fileUtils.writeConfig(opencodeTarget.config, cwd, config);