Skip to content

File Watching & Real-time Development Integration

Overview

Implement file watching and real-time development integration tools that enhance the developer experience by providing immediate feedback on migration changes and automating common development tasks. This creates a smooth, responsive development workflow.

Claude Agent Success Criteria

A Claude agent should be able to:

  • ✅ Monitor migration file changes and provide real-time feedback
  • ✅ Automatically validate migrations as they're edited
  • ✅ Integrate with development workflows and provide notifications
  • ✅ Support long-running watch processes with proper resource management

Detailed Acceptance Criteria

1. Migration File Watching Tool

Implement watch_migrations MCP tool:

{
  name: "watch_migrations",
  description: "Watch migration files for changes and provide real-time validation",
  inputSchema: {
    type: "object",
    properties: {
      projectPath: {
        type: "string",
        description: "Path to the Graphile Migrate project"
      },
      autoValidate: {
        type: "boolean",
        description: "Automatically validate changes (default: true)"
      },
      notificationLevel: {
        type: "string",
        enum: ["error", "warning", "info"],
        description: "Minimum notification level (default: warning)"
      }
    },
    required: ["projectPath"]
  }
}

Watch Events:

interface WatchEvent {
  timestamp: Date;
  type: 'file_changed' | 'file_created' | 'file_deleted' | 'validation_result' | 'error';
  file: string;
  details: {
    size?: number;
    validation?: ValidationResult;
    error?: string;
    suggestions?: string[];
  };
}

interface WatchSession {
  id: string;
  projectPath: string;
  started: Date;
  filesWatched: string[];
  eventsGenerated: number;
  lastActivity: Date;
  status: 'active' | 'paused' | 'stopped';
}
  • Monitor current.sql and migration directories
  • Detect file creation, modification, and deletion
  • Debounce rapid changes to avoid spam
  • Provide real-time validation feedback
  • Support multiple concurrent watch sessions

2. Real-time Validation Integration

Create validation pipeline that triggers on file changes:

interface RealtimeValidator {
  validateOnChange(file: string, content: string): Promise<ValidationResult>;
  getQuickFeedback(content: string): Promise<QuickValidation>;
  suggestFixes(issues: ValidationIssue[]): Promise<FixSuggestion[]>;
}

interface QuickValidation {
  syntaxValid: boolean;
  hasIdempotencyIssues: boolean;
  estimatedComplexity: 'low' | 'medium' | 'high';
  quickSuggestions: string[];
  warningCount: number;
  errorCount: number;
}

Validation Pipeline:

  • Syntax validation (SQL parsing)
  • Idempotency pattern checking
  • Performance impact estimation
  • Best practices validation
  • Security concern detection

3. Development Workflow Integration

Implement workflow helpers and automation:

{
  name: "development_workflow_status",
  description: "Get current development workflow status and suggestions",
  inputSchema: {
    type: "object",
    properties: {
      projectPath: {
        type: "string",
        description: "Path to the Graphile Migrate project"
      }
    },
    required: ["projectPath"]
  }
}

Workflow Status:

interface WorkflowStatus {
  success: boolean;
  data: {
    project: {
      name: string;
      lastActivity: Date;
      currentPhase: 'development' | 'testing' | 'ready_to_commit' | 'committed';
    };
    currentMigration: {
      exists: boolean;
      valid: boolean;
      lastModified: Date;
      estimatedReadiness: number; // 0-100%
      blockers: string[];
    };
    recommendations: {
      nextSteps: string[];
      potentialIssues: string[];
      optimizations: string[];
    };
    automation: {
      watchActive: boolean;
      lastValidation: Date;
      shadowDatabaseReady: boolean;
    };
  };
}
  • Track development phase and progress
  • Suggest next steps in workflow
  • Identify blockers and issues
  • Provide automation status
  • Support workflow customization

4. Notification and Feedback System

Implement comprehensive notification system:

interface NotificationSystem {
  notify(level: NotificationLevel, message: string, details?: any): void;
  subscribe(callback: NotificationCallback): string;
  unsubscribe(subscriptionId: string): void;
  getHistory(since?: Date): Notification[];
}

interface Notification {
  id: string;
  timestamp: Date;
  level: 'info' | 'warning' | 'error' | 'success';
  category: 'validation' | 'file_change' | 'database' | 'performance' | 'security';
  title: string;
  message: string;
  actionable: boolean;
  actions?: NotificationAction[];
}

interface NotificationAction {
  label: string;
  action: string;
  parameters?: any;
}
  • Support multiple notification levels
  • Categorize notifications by type
  • Provide actionable notifications with suggested fixes
  • Maintain notification history
  • Support subscription-based notifications

5. Performance and Resource Management

Implement efficient file watching with resource management:

interface WatchManager {
  startWatching(projectPath: string, options: WatchOptions): Promise<WatchSession>;
  stopWatching(sessionId: string): Promise<void>;
  pauseWatching(sessionId: string): Promise<void>;
  resumeWatching(sessionId: string): Promise<void>;
  getActiveSessions(): WatchSession[];
  getResourceUsage(): ResourceUsage;
}

interface ResourceUsage {
  memoryMB: number;
  cpuPercent: number;
  fileHandles: number;
  activeSessions: number;
  eventsPerSecond: number;
}
  • Implement efficient file watching (using native OS APIs)
  • Monitor resource usage and provide warnings
  • Support session management and cleanup
  • Implement intelligent throttling for high-activity projects
  • Provide performance metrics and monitoring

Testing Requirements

Unit Tests

  • Test file watching logic and event generation
  • Test validation pipeline and feedback generation
  • Test notification system and subscriptions
  • Test resource management and cleanup

Integration Tests

  • Test with real file system changes
  • Test long-running watch sessions
  • Test resource usage under load
  • Test integration with validation tools

Performance Tests

  • Test with high-frequency file changes
  • Test memory usage over extended periods
  • Test notification throughput and latency
  • Test concurrent watch session handling

Claude Agent Guidance

Typical Watch Workflow

// 1. Start watching migration files
const watchSession = await tools.watch_migrations({
  projectPath: "/path/to/project",
  autoValidate: true,
  notificationLevel: "warning"
});

// 2. Get development workflow status
const status = await tools.development_workflow_status({
  projectPath: "/path/to/project"
});

// 3. Monitor notifications and respond to changes
// (This would typically be handled by the Claude agent automatically)

How to Verify Success

# Test file watching
node -e "
const watch = require('./dist/tools/watch-migrations');
watch.startWatching('/path/to/project').then(console.log);
"

# Test in terminal - make changes to current.sql and observe notifications
echo 'CREATE TABLE test();' >> migrations/current.sql

Expected Behavior

  • File changes should trigger immediate validation
  • Notifications should be clear and actionable
  • Watch sessions should be stable and efficient
  • Resource usage should remain reasonable

Error Handling Examples

  • Permission Denied: "Cannot watch directory: insufficient file system permissions."
  • Too Many Files: "File watching limit reached. Consider excluding large directories."
  • Resource Exhaustion: "Watch session paused: high resource usage detected."

Definition of Done

  • File watching works reliably across platforms
  • Real-time validation provides immediate feedback
  • Notification system delivers actionable messages
  • Resource usage remains within acceptable bounds
  • Integration tests pass with real file changes
  • >80% test coverage maintained
  • Performance metrics meet requirements
  • CLAUDE.md updated with watching examples

Estimated Effort

2-3 days

Dependencies

  • Issue #1 (closed): Setup MCP Server Foundation
  • Issue #4 (closed): Idempotency Analysis & Migration Safety Validation

Technical Notes for Claude Agents

Key Files to Create

  • src/tools/watch-migrations.ts - File watching tool
  • src/tools/workflow-status.ts - Development workflow status
  • src/watch/file-monitor.ts - File system monitoring
  • src/watch/validator.ts - Real-time validation
  • src/watch/notifications.ts - Notification system
  • src/watch/resource-manager.ts - Resource management

File Watching Strategy

  • Use platform-native file watching APIs (inotify, FSEvents, etc.)
  • Implement debouncing to avoid excessive events
  • Support recursive directory watching
  • Handle symbolic links and mounted directories
  • Provide fallback polling for unsupported file systems

Cross-Platform Considerations

  • Test on macOS, Linux, and Windows
  • Handle different path separators correctly
  • Account for file system case sensitivity
  • Support different file encodings
  • Handle file locking and permission differences

Performance Optimization

  • Use efficient data structures for tracking changes
  • Implement intelligent throttling for high-activity periods
  • Minimize memory allocation for event handling
  • Cache validation results for unchanged content
  • Provide configurable resource limits