@sylphx/flow 3.19.0 → 3.20.0

package/src/commands/hook-command.ts

@@ -1,27 +1,50 @@
 #!/usr/bin/env node
 /**
- * Hook command - OS notification for Claude Code startup
+ * Hook command - Claude Code hook handlers
  *
- * Purpose: Send OS-level notifications when Claude Code starts
+ * Purpose: Handle Claude Code lifecycle hooks:
+ * - notification: OS-level notification when Claude Code starts
+ * - session-start: Load durable memory (MEMORY.md + recent daily logs)
  *
  * DESIGN RATIONALE:
- * - Simple notification: Just notify user when Claude Code is ready
- * - Cross-platform: Supports macOS, Linux, and Windows
- * - Non-intrusive: Fails silently if notification system not available
+ * - Each hook type returns content to stdout (Claude Code injects as context)
+ * - Cross-platform notifications (macOS, Linux, Windows)
+ * - SessionStart hook loads cross-session memory at startup
  */
 
 import { exec } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
 import os from 'node:os';
+import path from 'node:path';
 import { promisify } from 'node:util';
 import { Command } from 'commander';
 import { cli } from '../utils/display/cli-output.js';
 
+/**
+ * Hook input from Claude Code via stdin.
+ * Claude Code sends JSON context about the event — we read what we need.
+ */
+interface HookInput {
+  /** Notification message text */
+  message?: string;
+  /** Notification title */
+  title?: string;
+  /** Notification type (permission_prompt, idle_prompt, etc.) */
+  notification_type?: string;
+  /** How the session started (startup, resume, clear, compact) */
+  source?: string;
+  /** Current working directory */
+  cwd?: string;
+}
+
 const execAsync = promisify(exec);
 
 /**
- * Hook types supported
+ * Hook types supported — single source of truth for both type and runtime validation
  */
-type HookType = 'notification';
+const VALID_HOOK_TYPES = ['notification', 'session-start'] as const;
+type HookType = (typeof VALID_HOOK_TYPES)[number];
+const VALID_HOOK_TYPE_SET = new Set<string>(VALID_HOOK_TYPES);
 
 /**
  * Target platforms supported
@@ -32,18 +55,20 @@ type TargetPlatform = 'claude-code';
  * Create the hook command
  */
 export const hookCommand = new Command('hook')
-  .description('Load dynamic system information for Claude Code hooks')
-  .requiredOption('--type <type>', 'Hook type (notification)')
+  .description('Handle Claude Code lifecycle hooks (notification, memory)')
+  .requiredOption('--type <type>', 'Hook type (notification | session-start)')
   .option('--target <target>', 'Target platform (claude-code)', 'claude-code')
   .option('--verbose', 'Show verbose output', false)
   .action(async (options) => {
     try {
-      const hookType = options.type as HookType;
+      const hookType = options.type as string;
       const target = options.target as TargetPlatform;
 
       // Validate hook type
-      if (hookType !== 'notification') {
-        throw new Error(`Invalid hook type: ${hookType}. Must be 'notification'`);
+      if (!VALID_HOOK_TYPE_SET.has(hookType)) {
+        throw new Error(
+          `Invalid hook type: ${hookType}. Must be one of: ${VALID_HOOK_TYPES.join(', ')}`
+        );
       }
 
       // Validate target
@@ -51,8 +76,11 @@ export const hookCommand = new Command('hook')
         throw new Error(`Invalid target: ${target}. Only 'claude-code' is currently supported`);
       }
 
+      // Read hook input from stdin (Claude Code passes JSON context)
+      const hookInput = await readStdinInput();
+
       // Load and display content based on hook type
-      const content = await loadHookContent(hookType, target, options.verbose);
+      const content = await loadHookContent(hookType as HookType, target, hookInput, options.verbose);
 
       // Output the content (no extra formatting, just the content)
       console.log(content);
@@ -72,27 +100,140 @@ export const hookCommand = new Command('hook')
     }
   });
 
+/**
+ * Read JSON input from stdin (non-blocking, returns empty object if no input)
+ * Claude Code sends event context as JSON on stdin for all hook types.
+ */
+async function readStdinInput(): Promise<HookInput> {
+  // stdin is not a TTY when piped from Claude Code
+  if (process.stdin.isTTY) {
+    return {};
+  }
+
+  return new Promise((resolve) => {
+    let data = '';
+    process.stdin.setEncoding('utf-8');
+    process.stdin.on('data', (chunk) => {
+      data += chunk;
+    });
+    process.stdin.on('end', () => {
+      if (!data.trim()) {
+        resolve({});
+        return;
+      }
+      try {
+        resolve(JSON.parse(data) as HookInput);
+      } catch {
+        resolve({});
+      }
+    });
+    // Safety timeout — don't hang if stdin never closes
+    setTimeout(() => resolve({}), 1000);
+  });
+}
+
 /**
  * Load content for a specific hook type and target
  */
 async function loadHookContent(
   hookType: HookType,
   _target: TargetPlatform,
+  input: HookInput,
   verbose: boolean = false
 ): Promise<string> {
-  if (hookType === 'notification') {
-    return await sendNotification(verbose);
+  switch (hookType) {
+    case 'notification':
+      return await sendNotification(input, verbose);
+    case 'session-start':
+      return await loadSessionStartContent(verbose);
+  }
+}
+
+/**
+ * Read a file and return its contents, or empty string if not found
+ */
+async function readFileIfExists(filePath: string): Promise<string> {
+  try {
+    return await readFile(filePath, 'utf-8');
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * Format a date as YYYY-MM-DD
+ */
+function formatDate(date: Date): string {
+  const year = date.getFullYear();
+  const month = String(date.getMonth() + 1).padStart(2, '0');
+  const day = String(date.getDate()).padStart(2, '0');
+  return `${year}-${month}-${day}`;
+}
+
+/**
+ * Load memory files for session start:
+ * - MEMORY.md (curated long-term memory)
+ * - memory/{today}.md (today's daily log)
+ * - memory/{yesterday}.md (yesterday's daily log)
+ *
+ * Returns concatenated content to stdout for Claude Code context injection
+ */
+async function loadSessionStartContent(verbose: boolean): Promise<string> {
+  const cwd = process.cwd();
+  const sections: string[] = [];
+
+  // Load MEMORY.md
+  const memoryPath = path.join(cwd, 'MEMORY.md');
+  const memoryContent = await readFileIfExists(memoryPath);
+  if (memoryContent.trim()) {
+    sections.push(`## MEMORY.md\n${memoryContent.trim()}`);
+    if (verbose) {
+      cli.info('Loaded MEMORY.md');
+    }
+  }
+
+  // Calculate today and yesterday dates
+  const today = new Date();
+  const yesterday = new Date(today);
+  yesterday.setDate(yesterday.getDate() - 1);
+
+  const todayStr = formatDate(today);
+  const yesterdayStr = formatDate(yesterday);
+
+  // Load today's daily log
+  const todayPath = path.join(cwd, 'memory', `${todayStr}.md`);
+  const todayContent = await readFileIfExists(todayPath);
+  if (todayContent.trim()) {
+    sections.push(`## memory/${todayStr}.md\n${todayContent.trim()}`);
+    if (verbose) {
+      cli.info(`Loaded memory/${todayStr}.md`);
+    }
+  }
+
+  // Load yesterday's daily log
+  const yesterdayPath = path.join(cwd, 'memory', `${yesterdayStr}.md`);
+  const yesterdayContent = await readFileIfExists(yesterdayPath);
+  if (yesterdayContent.trim()) {
+    sections.push(`## memory/${yesterdayStr}.md\n${yesterdayContent.trim()}`);
+    if (verbose) {
+      cli.info(`Loaded memory/${yesterdayStr}.md`);
+    }
+  }
+
+  if (verbose && sections.length === 0) {
+    cli.info('No memory files found');
   }
 
-  return '';
+  return sections.join('\n\n');
 }
 
 /**
- * Send OS-level notification
+ * Send OS-level notification using event data from Claude Code.
+ * Falls back to generic message when stdin input is missing.
  */
-async function sendNotification(verbose: boolean): Promise<string> {
-  const title = '🔮 Sylphx Flow';
-  const message = 'Claude Code is ready';
+async function sendNotification(input: HookInput, verbose: boolean): Promise<string> {
+  const title = input.title || '🔮 Sylphx Flow';
+  const message = input.message || 'Claude Code is ready';
   const platform = os.platform();
 
   if (verbose) {

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

package/src/core/cleanup-handler.ts

@@ -16,12 +16,15 @@
 import { existsSync } from 'node:fs';
 import fs from 'node:fs/promises';
 import path from 'node:path';
+import createDebug from 'debug';
 import type { BackupManager } from './backup-manager.js';
 import type { GitStashManager } from './git-stash-manager.js';
 import type { ProjectManager } from './project-manager.js';
 import type { SecretsManager } from './secrets-manager.js';
 import type { SessionManager } from './session-manager.js';
 
+const debug = createDebug('flow:cleanup');
+
 export class CleanupHandler {
   private projectManager: ProjectManager;
   private sessionManager: SessionManager;
@@ -132,8 +135,8 @@ export class CleanupHandler {
         await this.gitStashManager.popSettingsChanges(session.projectPath);
         await this.secretsManager.clearSecrets(this.currentProjectHash);
       }
-    } catch (_error) {
-      // Silent fail - recovery will happen on next startup
+    } catch (error) {
+      debug('signal cleanup failed:', error);
     }
   }
 
@@ -156,8 +159,8 @@ export class CleanupHandler {
         await this.gitStashManager.popSettingsChanges(session.projectPath);
         await this.secretsManager.clearSecrets(projectHash);
         await this.backupManager.cleanupOldBackups(projectHash, 3);
-      } catch (_error) {
-        // Silent fail - don't interrupt startup
+      } catch (error) {
+        debug('startup recovery failed for session:', error);
       }
     }
 
@@ -168,8 +171,8 @@ export class CleanupHandler {
           this.sessionManager.cleanupSessionHistory(50),
           this.cleanupOrphanedProjects(),
         ]);
-      } catch {
-        // Non-fatal
+      } catch (error) {
+        debug('periodic cleanup failed:', error);
       }
       await this.updateCleanupTimestamp();
     }
@@ -185,7 +188,6 @@ export class CleanupHandler {
       const hoursSinceLastCleanup = (Date.now() - stat.mtimeMs) / (1000 * 60 * 60);
       return hoursSinceLastCleanup >= 24;
     } catch {
-      // Marker doesn't exist — first run or deleted
       return true;
     }
   }
@@ -197,8 +199,8 @@ export class CleanupHandler {
     const markerPath = path.join(this.projectManager.getFlowHomeDir(), '.last-cleanup');
     try {
       await fs.writeFile(markerPath, new Date().toISOString());
-    } catch {
-      // Non-fatal
+    } catch (error) {
+      debug('failed to update cleanup timestamp:', error);
     }
   }
 
@@ -259,7 +261,8 @@ export class CleanupHandler {
       try {
         const entries = await fs.readdir(dir, { withFileTypes: true });
         return entries.filter((e) => e.isDirectory()).map((e) => e.name);
-      } catch {
+      } catch (error) {
+        debug('failed to scan directory %s: %O', dir, error);
         return [];
       }
     };
@@ -292,7 +295,8 @@ export class CleanupHandler {
       const manifestPath = path.join(paths.backupsDir, sessions[0].name, 'manifest.json');
       const manifest = JSON.parse(await fs.readFile(manifestPath, 'utf-8'));
       return manifest.projectPath || null;
-    } catch {
+    } catch (error) {
+      debug('failed to read backup manifest for %s: %O', projectHash, error);
       return null;
     }
   }
@@ -306,22 +310,22 @@ export class CleanupHandler {
     // Remove backups directory
     try {
       await fs.rm(paths.backupsDir, { recursive: true, force: true });
-    } catch {
-      // Ignore errors
+    } catch (error) {
+      debug('failed to remove backups for %s: %O', projectHash, error);
     }
 
     // Remove secrets directory
     try {
       await fs.rm(paths.secretsDir, { recursive: true, force: true });
-    } catch {
-      // Ignore errors
+    } catch (error) {
+      debug('failed to remove secrets for %s: %O', projectHash, error);
     }
 
     // Remove session file if exists
     try {
       await fs.unlink(paths.sessionFile);
     } catch {
-      // File might not exist
+      // Expected: file may not exist
     }
   }
 }

package/src/core/flow-executor.ts

@@ -8,7 +8,11 @@ import { existsSync } from 'node:fs';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import chalk from 'chalk';
+import createDebug from 'debug';
 import type { Target } from '../types/target.types.js';
+
+const debug = createDebug('flow:executor');
+
 import { AttachManager } from './attach-manager.js';
 import { BackupManager } from './backup-manager.js';
 import { CleanupHandler } from './cleanup-handler.js';
@@ -55,70 +59,62 @@ export class FlowExecutor {
   }
 
   /**
-   * Execute complete flow with attach mode (with multi-session support)
-   * Returns summary for caller to display
+   * Try to join an existing session. Returns summary if joined, null otherwise.
    */
-  async execute(
+  private async tryJoinExistingSession(
     projectPath: string,
-    options: FlowExecutorOptions = {}
-  ): Promise<{
-    joined: boolean;
-    agents?: number;
-    commands?: number;
-    skills?: number;
-    mcp?: number;
-  }> {
-    // Initialize Flow directories
-    await this.projectManager.initialize();
-
-    // Step 1: Crash recovery on startup
-    await this.cleanupHandler.recoverOnStartup();
-
-    // Step 2: Get project hash and paths
-    const projectHash = this.projectManager.getProjectHash(projectPath);
-    const target = await this.projectManager.detectTarget(projectPath);
-
-    if (options.verbose) {
-      console.log(chalk.dim(`Project: ${projectPath}`));
-      console.log(chalk.dim(`Hash: ${projectHash}`));
-      console.log(chalk.dim(`Target: ${target}\n`));
-    }
-
-    // Check for existing session
+    projectHash: string,
+    target: string,
+    verbose?: boolean
+  ): Promise<{ joined: true } | null> {
     const existingSession = await this.sessionManager.getActiveSession(projectHash);
+    if (!existingSession) {
+      return null;
+    }
 
-    if (existingSession) {
-      // Verify attached files still exist before joining
-      const targetObj = resolveTargetOrId(target);
-      const agentsDir = path.join(projectPath, targetObj.config.agentDir);
-      const filesExist = existsSync(agentsDir) && (await fs.readdir(agentsDir)).length > 0;
-
-      if (filesExist) {
-        // Joining existing session - silent
-        await this.sessionManager.startSession(
-          projectPath,
-          projectHash,
-          target,
-          existingSession.backupPath
-        );
-        this.cleanupHandler.registerCleanupHooks(projectHash);
-        return { joined: true };
-      }
+    const targetObj = resolveTargetOrId(target);
+    const agentsDir = path.join(projectPath, targetObj.config.agentDir);
+    const filesExist = existsSync(agentsDir) && (await fs.readdir(agentsDir)).length > 0;
+
+    if (filesExist) {
+      await this.sessionManager.startSession(
+        projectPath,
+        projectHash,
+        target,
+        existingSession.backupPath
+      );
+      this.cleanupHandler.registerCleanupHooks(projectHash);
+      return { joined: true };
+    }
 
-      // Files missing - invalidate session and re-attach
-      if (options.verbose) {
-        console.log(chalk.dim('Session files missing, re-attaching...'));
-      }
-      await this.sessionManager.endSession(projectHash);
+    if (verbose) {
+      console.log(chalk.dim('Session files missing, re-attaching...'));
     }
+    await this.sessionManager.endSession(projectHash);
+    return null;
+  }
 
-    // First session — run independent setup steps in parallel
+  /**
+   * Create a new session: backup, extract secrets, attach templates
+   */
+  private async createNewSession(
+    projectPath: string,
+    projectHash: string,
+    target: string,
+    options: FlowExecutorOptions
+  ): Promise<{
+    agents: number;
+    commands: number;
+    skills: number;
+    mcp: number;
+  }> {
+    // Run independent setup steps in parallel
     await Promise.all([
       options.skipProjectDocs ? Promise.resolve() : this.ensureProjectDocs(projectPath),
       this.gitStashManager.stashSettingsChanges(projectPath),
     ]);
 
-    // Backup and extract secrets in parallel (both read project config, neither writes)
+    // Backup and extract secrets in parallel
     const [backup] = await Promise.all([
       this.backupManager.createBackup(projectPath, projectHash, target),
       options.skipSecrets
@@ -132,7 +128,6 @@ export class FlowExecutor {
             }),
     ]);
 
-    // Start session
     const { session } = await this.sessionManager.startSession(
       projectPath,
       projectHash,
@@ -143,7 +138,6 @@ export class FlowExecutor {
 
     this.cleanupHandler.registerCleanupHooks(projectHash);
 
-    // Clear and attach (silent)
     if (!options.merge) {
       await this.clearUserSettings(projectPath, target);
     }
@@ -157,22 +151,19 @@ export class FlowExecutor {
 
     const attachResult = await this.attachManager.attach(projectPath, target, templates, manifest);
 
-    // Apply target-specific settings (attribution, hooks, env, thinking mode)
-    // Non-fatal: CLI can still run without these settings
+    // Apply target-specific settings (non-fatal)
     const targetObj = resolveTargetOrId(target);
     if (targetObj.applySettings) {
       try {
         await targetObj.applySettings(projectPath, {});
-      } catch {
-        // Settings are optional — agents/commands/MCP already attached
+      } catch (error) {
+        debug('applySettings failed:', error);
       }
     }
 
     await this.backupManager.updateManifest(projectHash, session.sessionId, manifest);
 
-    // Return summary for caller to display
     return {
-      joined: false,
       agents: attachResult.agentsAdded.length,
       commands: attachResult.commandsAdded.length,
       skills: attachResult.skillsAdded.length,
@@ -180,6 +171,46 @@ export class FlowExecutor {
     };
   }
 
+  /**
+   * Execute complete flow with attach mode (with multi-session support)
+   * Returns summary for caller to display
+   */
+  async execute(
+    projectPath: string,
+    options: FlowExecutorOptions = {}
+  ): Promise<{
+    joined: boolean;
+    agents?: number;
+    commands?: number;
+    skills?: number;
+    mcp?: number;
+  }> {
+    await this.projectManager.initialize();
+    await this.cleanupHandler.recoverOnStartup();
+
+    const projectHash = this.projectManager.getProjectHash(projectPath);
+    const target = await this.projectManager.detectTarget(projectPath);
+
+    if (options.verbose) {
+      console.log(chalk.dim(`Project: ${projectPath}`));
+      console.log(chalk.dim(`Hash: ${projectHash}`));
+      console.log(chalk.dim(`Target: ${target}\n`));
+    }
+
+    const joinResult = await this.tryJoinExistingSession(
+      projectPath,
+      projectHash,
+      target,
+      options.verbose
+    );
+    if (joinResult) {
+      return joinResult;
+    }
+
+    const result = await this.createNewSession(projectPath, projectHash, target, options);
+    return { joined: false, ...result };
+  }
+
   /**
    * Clear user settings in replace mode
    * This ensures a clean slate for Flow's configuration
@@ -255,8 +286,8 @@ export class FlowExecutor {
           if (content.includes('Sylphx Flow') || content.includes('Silent Execution Style')) {
             await fs.unlink(filePath);
           }
-        } catch {
-          // Ignore errors - file might not be readable
+        } catch (error) {
+          debug('failed to clean legacy file %s: %O', fileName, error);
         }
       }
     }

package/src/core/functional/index.ts

@@ -1,19 +1,8 @@
 /**
  * Functional programming utilities
  * Core abstractions for composable, type-safe error handling
- *
- * PRINCIPLES:
- * - Pure functions (no side effects)
- * - Explicit error handling (no exceptions in business logic)
- * - Composable through map/flatMap
- * - Type-safe (leverages TypeScript's type system)
  */
 
-export * from './async.js';
-export * from './either.js';
-export * from './error-handler.js';
 export * from './error-types.js';
 export * from './option.js';
-export * from './pipe.js';
 export * from './result.js';
-export * from './validation.js';

package/src/core/index.ts

@@ -3,4 +3,4 @@
  * Centralized access to core system components
  */
 
-export { targetManager } from './target-manager';
+export { targetManager } from './target-manager.js';