@oletizi/audio-tools/modules/audiotools-config/src/types.ts

Monorepo for hardware sampler utilities and format parsers

/**
 * Type definitions for the audio-tools unified configuration system.
 *
 * This module provides TypeScript interfaces for the shared configuration
 * used across all audio-tools packages (backup, export, and future tools).
 *
 * @module audiotools-config/types
 */

/**
 * Main audio-tools configuration structure.
 *
 * This is the root configuration object stored in `~/.audiotools/config.json`.
 * It contains settings for all audio-tools and is extensible for future tools.
 *
 * @example
 * ```typescript
 * const config: AudioToolsConfig = {
 *   version: '1.0',
 *   backup: {
 *     backupRoot: '~/.audiotools/backup',
 *     sources: [...]
 *   },
 *   export: {
 *     outputRoot: '~/.audiotools/sampler-export/extracted',
 *     formats: ['sfz', 'decentsampler'],
 *     skipUnchanged: true,
 *     enabledSources: ['pi-scsi2']
 *   }
 * };
 * ```
 */
export interface AudioToolsConfig {
  /** Configuration schema version */
  version: string;

  /** Backup tool configuration */
  backup?: BackupConfig;

  /** Export tool configuration */
  export?: ExportConfig;

  /** Extensibility: future tools can add their config sections */
  [key: string]: any;
}

/**
 * Backup source definition.
 *
 * Represents a single backup source (remote SSH host or local media).
 * Each source has a unique name and can be independently enabled/disabled.
 *
 * @example
 * ```typescript
 * // Remote backup source
 * const remoteSource: BackupSource = {
 *   name: 'pi-scsi2',
 *   type: 'remote',
 *   source: 'pi-scsi2.local:~/images/',
 *   device: 'images',
 *   sampler: 's5000',
 *   enabled: true
 * };
 *
 * // Local backup source with UUID tracking
 * const localSource: BackupSource = {
 *   name: 'sd-card',
 *   type: 'local',
 *   source: '/Volumes/AKAI_SD',
 *   device: 'sd-card',
 *   sampler: 's5000',
 *   enabled: true,
 *   volumeUUID: '12345678-1234-1234-1234-123456789012',
 *   volumeLabel: 'AKAI_SD',
 *   lastSeen: '2025-10-09T14:30:00.000Z',
 *   registeredAt: '2025-10-09T14:00:00.000Z'
 * };
 * ```
 */
export interface BackupSource {
  /** Unique identifier for this source (used in CLI and export config) */
  name: string;

  /** Source type: 'remote' for SSH/PiSCSI, 'local' for SD cards/USB drives */
  type: 'remote' | 'local';

  /**
   * Source path.
   * - For remote: SSH path in format 'host:path' (e.g., 'pi-scsi2.local:~/images/')
   * - For local: absolute path to mounted volume (e.g., '/Volumes/AKAI_SD')
   */
  source: string;

  /** Device/volume name for organization (e.g., 'images', 'floppy', 'sd-card') */
  device: string;

  /** Optional: Sampler model this source is associated with (e.g., 's5000', 's3000xl') */
  sampler?: string;

  /** Whether this source is enabled for backup operations */
  enabled: boolean;

  /**
   * Volume UUID - Primary device identifier
   *
   * Used to recognize the same physical device across remounts, even if mount
   * path changes. On macOS, obtained via diskutil. On Linux, via blkid.
   *
   * Some older FAT32 volumes may not have a UUID - use volumeSerial as fallback.
   *
   * @example "12345678-1234-1234-1234-123456789012"
   */
  volumeUUID?: string;

  /**
   * Volume label - Human-readable device name
   *
   * The volume label as it appears in the filesystem. Useful for user display
   * but not reliable as an identifier (users can rename volumes).
   *
   * @example "SDCARD", "S5000_BACKUP", "MY_USB"
   */
  volumeLabel?: string;

  /**
   * Volume serial number - Fallback identifier
   *
   * Used when volumeUUID is not available (e.g., older FAT32 volumes).
   * On Linux, this is the PARTUUID from blkid.
   *
   * @example "12345678-02"
   */
  volumeSerial?: string;

  /**
   * Last seen timestamp - When device was last detected
   *
   * ISO 8601 timestamp of the last time this physical device was detected.
   * Updated each time the device is successfully identified during backup.
   *
   * @example "2025-10-09T14:30:00.000Z"
   */
  lastSeen?: string;

  /**
   * Registration timestamp - When device was first added
   *
   * ISO 8601 timestamp of when this device was first registered in the config.
   * Never changes after initial registration.
   *
   * @example "2025-10-09T14:30:00.000Z"
   */
  registeredAt?: string;

  /**
   * Backup path - Actual filesystem location where backups are stored
   *
   * Absolute path to the directory where this source's backups are written.
   * Automatically populated after the first successful backup. This eliminates
   * the need for discovery logic - export reads this path directly.
   *
   * Structure examples:
   * - Local source: `~/.audiotools/backup/{sampler}/{device}`
   * - Remote source: `~/.audiotools/backup/{hostname}/{device}`
   *
   * @example "/Users/orion/.audiotools/backup/s3k/hard-drive"
   * @example "/Users/orion/.audiotools/backup/pi-scsi2/images"
   */
  backupPath?: string;
}

/**
 * Backup configuration.
 *
 * Contains all backup-related settings including the backup root directory
 * and the list of configured sources.
 *
 * @example
 * ```typescript
 * const backupConfig: BackupConfig = {
 *   backupRoot: '~/.audiotools/backup',
 *   sources: [
 *     {
 *       name: 'pi-scsi2',
 *       type: 'remote',
 *       source: 'pi-scsi2.local:~/images/',
 *       device: 'images',
 *       enabled: true
 *     }
 *   ]
 * };
 * ```
 */
export interface BackupConfig {
  /** Root directory for all backups (contains subdirectories per source) */
  backupRoot: string;

  /** List of configured backup sources */
  sources: BackupSource[];
}

/**
 * Export configuration.
 *
 * Contains settings for disk image extraction and sample format conversion.
 * Controls which sources to export and what output formats to generate.
 *
 * @example
 * ```typescript
 * const exportConfig: ExportConfig = {
 *   outputRoot: '~/.audiotools/sampler-export/extracted',
 *   formats: ['sfz', 'decentsampler'],
 *   skipUnchanged: true,
 *   enabledSources: ['pi-scsi2', 'sd-card']
 * };
 * ```
 */
export interface ExportConfig {
  /** Root directory for exported/extracted content */
  outputRoot: string;

  /**
   * Output formats to generate during conversion.
   * - 'sfz': SFZ sampler format
   * - 'decentsampler': DecentSampler format
   */
  formats: ('sfz' | 'decentsampler')[];

  /**
   * Whether to skip extraction of unchanged disk images.
   * Uses modification time and checksum to detect changes.
   */
  skipUnchanged: boolean;

  /**
   * List of source names (from BackupConfig.sources) that are enabled for export.
   * Allows independent control of which sources to back up vs. export.
   */
  enabledSources: string[];
}

/**
 * Auto-discovered backup result.
 *
 * Represents a backup directory discovered during automatic scanning.
 * Used by the configuration wizard to import existing backups.
 *
 * @example
 * ```typescript
 * const discovered: DiscoveredBackup = {
 *   sampler: 's5000',
 *   device: 'images',
 *   path: '~/.audiotools/backup/s5000/images',
 *   fileCount: 15,
 *   totalSize: 3221225472, // 3 GB in bytes
 *   lastModified: new Date('2024-10-07T12:00:00Z'),
 *   inferredType: 'remote'
 * };
 * ```
 */
export interface DiscoveredBackup {
  /** Inferred sampler model (from directory structure or metadata) */
  sampler: string;

  /** Device/volume name (from directory structure) */
  device: string;

  /** Absolute path to the backup directory */
  path: string;

  /** Number of files in this backup */
  fileCount: number;

  /** Total size of all files in bytes */
  totalSize: number;

  /** Last modification time of the most recent file */
  lastModified: Date;

  /**
   * Inferred source type based on directory structure or naming.
   * - 'remote': Likely from SSH/PiSCSI backup
   * - 'local': Likely from local media backup
   */
  inferredType: 'remote' | 'local';
}