FrequencyAds CLI Library

🎯 Purpose

The CLI library provides a modular, decorator-based architecture for FrequencyAds applications, promoting code reuse, consistency, and maintainability across command-line interfaces through capability composition.

🏗️ Architecture

Core Components

Base Classes

• BaseCommand - Minimal abstract base class with essential CLI functionality
• BaseSubcommand - Abstract base class for modular, reusable subcommands

Decorator System

• @withFileHandling - Adds file path resolution and validation capabilities
• @withDisplayUtilities - Adds consistent formatting, sections, and status messages
• @withProgressTracking - Adds progress indicators and success/failure handling
• @withErrorHandling - Adds context-aware error handling with specialized handlers

Utility Classes

• OutputManager - Output formatting and file saving operations
• FileProcessor - File handling and validation utilities

📦 Key Features

Modular Decorator Architecture

• Capability Composition: Commands get only the functionality they need
• Zero Code Duplication: Methods exist only in decorators, not base classes
• Minimal Base Class: BaseCommand contains only essential functionality
• Type Safety: TypeScript ensures methods exist only when decorators are applied

Decorator Capabilities

• @withFileHandling: File path resolution, validation, and search functionality
• @withDisplayUtilities: Section headers, key-value display, confidence scores
• @withProgressTracking: Spinner management, success/failure messages
• @withErrorHandling: Context-aware error handling with user-friendly suggestions

Object-Oriented Design

• Clean inheritance hierarchy with minimal BaseCommand foundation
• Encapsulation of command-specific logic in derived classes
• Composition pattern for utilities (FileProcessor, OutputManager)

🔧 Usage

Creating a Command with Decorators

import { 
  BaseCommand, 
  CommandContext,
  withFileHandling,
  withDisplayUtilities,
  withProgressTracking
} from '../../../libs/cli-library';

@withProgressTracking  // Adds updateProgress(), showSuccess(), showFailure()
@withDisplayUtilities  // Adds displaySection(), displayData(), displayConfidence()
@withFileHandling      // Adds resolveFilePath()
class MyCommand extends BaseCommand {
  constructor() {
    super('mycommand', 'Description of my command');
    this.setupCommand();
  }
  
  protected setupCommand(): void {
    this.command
      .argument('<file>', 'Input file')
      .option('--format <type>', 'Output format')
      .action(async (file, options) => {
        const context = await this.initializeContext(options);
        await this.executeCommand(async (ctx) => {
          // Decorators provide these methods:
          const filePath = await this.resolveFilePath(file, 'document');
          this.displaySection('Processing File', 'blue');
          this.updateProgress('Processing...');
          this.showSuccess('Complete!');
        });
      });
    
    this.setupSubCommands();
  }
  
  private setupSubCommands(): void {
    // Attach OO subcommands
    const infoSubcommand = new MyInfoSubcommand();
    infoSubcommand.attachTo(this.command);
  }
}

// Export the command
const myCommandInstance = new MyCommand();
export const myCommand = myCommandInstance.getCommand();

Creating a Subcommand with Decorators

import { 
  BaseSubcommand, 
  CommandContext,
  withDisplayUtilities,
  withFileHandling
} from '../../../libs/cli-library';

@withDisplayUtilities  // Adds displaySection(), displayData()
@withFileHandling      // Adds resolveFilePath()
class MyInfoSubcommand extends BaseSubcommand {
  constructor() {
    super('info', 'Show information about the file');
    this.setupCommand();
  }
  
  protected setupCommand(): void {
    this.command
      .argument('<file>', 'File to analyze')
      .action(async (file, options) => {
        const context = await this.initializeContext(options);
        await this.executeCommand(async (ctx) => {
          const filePath = await this.resolveFilePath(file, 'document');
          this.displaySection('File Information', 'blue');
          this.displayData({
            'File Path': filePath,
            'Size': '1.2 MB'
          });
        });
      });
  }
}

Available Decorators

@withFileHandling

// Provides:
resolveFilePath(filePath: string, fileType: 'audio' | 'document' | 'data'): Promise<string>

@withDisplayUtilities

// Provides:
displaySection(title: string, color?: 'blue' | 'green' | 'yellow' | 'red'): void
displayData(data: Record<string, any>, section?: string): void
displayConfidence(confidence: number, label?: string): void

@withProgressTracking

// Provides:
updateProgress(message: string): void
showSuccess(message: string): void  
showFailure(message: string): void

@withErrorHandling

// Provides enhanced error handling with context-aware messages

🎯 Benefits

Zero Code Duplication

• Methods exist only in decorators: No code duplication between base classes and decorators
• Capability composition: Commands get only the functionality they need
• TypeScript enforcement: Compiler prevents calling methods without proper decorators

Maintainability

• Single Responsibility: Each decorator provides one specific capability
• Modular Architecture: Easy to add, remove, or modify capabilities
• Minimal Base Class: BaseCommand contains only essential functionality
• Clear Dependencies: TypeScript shows exactly which capabilities each command uses

Extensibility

• Decorator Pattern: Easy to add new capabilities without touching existing code
• Mix and Match: Apply only the decorators your command needs
• Type Safety: Full IntelliSense support for decorator-provided methods
• Consistent API: Same method signatures across all commands

📁 File Structure

libs/cli-library/
├── classes/
│   ├── base-command.ts           # Minimal abstract base class  
│   └── base-subcommand.ts        # Abstract base class for subcommands
├── decorators/
│   ├── with-file-handling.ts     # File path resolution decorator
│   ├── with-display-utilities.ts # Display formatting decorator
│   ├── with-progress-tracking.ts # Progress management decorator
│   ├── with-error-handling.ts    # Error handling decorator
│   ├── types.ts                  # Decorator capability interfaces
│   └── index.ts                  # Decorator exports
├── modules/
│   ├── file-processor.ts         # File handling utilities
│   └── output-manager.ts         # Output formatting and saving
├── utilities/
│   ├── display-utilities.ts      # Console display functions
│   ├── path-utilities.ts         # File path resolution functions
│   └── error-handling.ts         # Error handling functions
├── utils/
│   └── compose-capabilities.ts   # Functional composition utilities
├── index.ts                      # Library exports and public API
├── package.json                  # Package configuration
└── README.md                     # This documentation

🧪 Integration

To use this library in your FrequencyAds application:

1. Import base classes and decorators from the library
2. Apply decorators to get only the capabilities your command needs
3. Extend BaseCommand with your specific command logic
4. Use FileProcessor and OutputManager for file operations
5. Follow decorator patterns for consistent functionality

Example integration:

import { 
  BaseCommand,
  withFileHandling, 
  withProgressTracking,
  FileProcessor 
} from '../../../libs/cli-library';

@withProgressTracking
@withFileHandling  
class MyAppCommand extends BaseCommand {
  // Your command implementation with decorator-provided methods
}

🚀 Architecture Benefits

For Developers

• Type Safety: IntelliSense shows exactly which methods are available
• Clear Dependencies: Decorators make capabilities explicit
• Reduced Boilerplate: No need to reimplement common functionality
• Consistent API: Same method signatures across all commands

For Maintenance

• Single Source of Truth: Each capability exists in exactly one place
• Easy Testing: Each decorator can be tested independently
• Modular Updates: Change capabilities without affecting base classes
• Clear Separation: Base class handles only essential CLI functionality

This decorator-based architecture provides the foundation for scalable, maintainable CLI development across all FrequencyAds applications.