vibecodingmachine-core 2026.1.3-2209 → 2026.1.23-1010

package/src/health-tracking/json-storage.js

@@ -0,0 +1,276 @@
+/**
+ * JSON File Storage Adapter
+ *
+ * Implements StorageInterface with atomic writes and backup handling
+ * for IDE health data persistence.
+ *
+ * @module json-storage
+ */
+
+const fs = require('fs-extra');
+const path = require('path');
+const os = require('os');
+const { StorageInterface } = require('./storage-interface');
+const { FileSystemError, ValidationError } = require('./errors');
+const { validateHealthData } = require('./validators');
+
+/**
+ * Default storage file location
+ */
+const DEFAULT_STORAGE_FILE = path.join(
+  os.homedir(),
+  '.config',
+  'vibecodingmachine',
+  'ide-health.json'
+);
+
+/**
+ * Default health data structure
+ */
+const DEFAULT_HEALTH_DATA = {
+  version: '1.0.0',
+  lastUpdated: new Date().toISOString(),
+  ides: {},
+  timeoutConfig: {
+    mode: 'fixed',
+    defaultTimeout: 1800000, // 30 minutes
+    bufferPercentage: 0.4, // 40%
+    minSamplesForAdaptive: 10,
+    ewmaAlpha: 0.3,
+  },
+  defaultRequirement: null,
+};
+
+/**
+ * JSON file storage adapter with atomic writes
+ * @implements {StorageInterface}
+ */
+class JSONStorage extends StorageInterface {
+  /**
+   * @param {Object} options - Configuration options
+   * @param {string} [options.storageFile] - Path to storage file
+   */
+  constructor(options = {}) {
+    super();
+    this.storageFile = options.storageFile || DEFAULT_STORAGE_FILE;
+    this.backupFile = `${this.storageFile}.bak`;
+  }
+
+  /**
+   * Read data from storage
+   * @returns {Promise<Object>} The stored data object
+   * @throws {FileSystemError} If read operation fails
+   */
+  async read() {
+    try {
+      // Ensure storage directory exists
+      await fs.ensureDir(path.dirname(this.storageFile));
+
+      // Check if storage file exists
+      const fileExists = await this.exists();
+
+      if (!fileExists) {
+        // Return default data structure if file doesn't exist
+        return JSON.parse(JSON.stringify(DEFAULT_HEALTH_DATA));
+      }
+
+      // Read file content
+      const content = await fs.readFile(this.storageFile, 'utf8');
+
+      // Parse JSON
+      let data;
+      try {
+        data = JSON.parse(content);
+      } catch (parseError) {
+        // Attempt to restore from backup on parse error
+        console.warn(`Failed to parse health data, attempting backup restore: ${parseError.message}`);
+        const backupExists = await fs.pathExists(this.backupFile);
+
+        if (backupExists) {
+          await this.restore(this.backupFile);
+          const backupContent = await fs.readFile(this.storageFile, 'utf8');
+          data = JSON.parse(backupContent);
+        } else {
+          throw new FileSystemError(
+            'Failed to parse health data and no backup available',
+            this.storageFile,
+            'read',
+            parseError
+          );
+        }
+      }
+
+      // Validate data structure
+      try {
+        validateHealthData(data);
+      } catch (validationError) {
+        throw new FileSystemError(
+          `Health data validation failed: ${validationError.message}`,
+          this.storageFile,
+          'read',
+          validationError
+        );
+      }
+
+      // Run migrations if needed
+      data = await this._runMigrations(data);
+
+      return data;
+    } catch (error) {
+      if (error instanceof FileSystemError) {
+        throw error;
+      }
+      throw new FileSystemError(
+        `Failed to read health data: ${error.message}`,
+        this.storageFile,
+        'read',
+        error
+      );
+    }
+  }
+
+  /**
+   * Write data to storage atomically
+   * @param {Object} data - The data to write
+   * @returns {Promise<void>}
+   * @throws {FileSystemError} If write operation fails
+   * @throws {ValidationError} If data is invalid
+   */
+  async write(data) {
+    try {
+      // Validate data before writing
+      validateHealthData(data);
+
+      // Update lastUpdated timestamp
+      data.lastUpdated = new Date().toISOString();
+
+      // Ensure storage directory exists
+      await fs.ensureDir(path.dirname(this.storageFile));
+
+      // Create backup if file exists
+      const fileExists = await this.exists();
+      if (fileExists) {
+        await this.backup();
+      }
+
+      // Atomic write: write to temp file first
+      const tempFile = `${this.storageFile}.tmp`;
+      await fs.writeJson(tempFile, data, { spaces: 2 });
+
+      // Rename temp file to target (atomic operation)
+      await fs.rename(tempFile, this.storageFile);
+    } catch (error) {
+      if (error instanceof ValidationError) {
+        throw error;
+      }
+      throw new FileSystemError(
+        `Failed to write health data: ${error.message}`,
+        this.storageFile,
+        'write',
+        error
+      );
+    }
+  }
+
+  /**
+   * Check if storage file exists
+   * @returns {Promise<boolean>} True if storage exists
+   */
+  async exists() {
+    return fs.pathExists(this.storageFile);
+  }
+
+  /**
+   * Create backup of current storage
+   * @returns {Promise<string>} Path to backup file
+   * @throws {FileSystemError} If backup creation fails
+   */
+  async backup() {
+    try {
+      const fileExists = await this.exists();
+
+      if (!fileExists) {
+        return null;
+      }
+
+      await fs.copy(this.storageFile, this.backupFile, { overwrite: true });
+      return this.backupFile;
+    } catch (error) {
+      throw new FileSystemError(
+        `Failed to create backup: ${error.message}`,
+        this.storageFile,
+        'backup',
+        error
+      );
+    }
+  }
+
+  /**
+   * Restore from backup file
+   * @param {string} backupPath - Path to backup file
+   * @returns {Promise<void>}
+   * @throws {FileSystemError} If restore operation fails
+   */
+  async restore(backupPath) {
+    try {
+      const backupExists = await fs.pathExists(backupPath);
+
+      if (!backupExists) {
+        throw new FileSystemError(
+          'Backup file does not exist',
+          backupPath,
+          'restore'
+        );
+      }
+
+      await fs.copy(backupPath, this.storageFile, { overwrite: true });
+    } catch (error) {
+      if (error instanceof FileSystemError) {
+        throw error;
+      }
+      throw new FileSystemError(
+        `Failed to restore from backup: ${error.message}`,
+        backupPath,
+        'restore',
+        error
+      );
+    }
+  }
+
+  /**
+   * Run migrations on data if schema version changed
+   * @private
+   * @param {Object} data - The data to migrate
+   * @returns {Promise<Object>} Migrated data
+   */
+  async _runMigrations(data) {
+    // No migrations needed yet - schema is at version 1.0.0
+    // Future migrations will be added here when schema changes
+
+    // Example migration pattern:
+    // if (data.version === '1.0.0') {
+    //   data = this._migrateFrom1_0_0To1_1_0(data);
+    //   data.version = '1.1.0';
+    // }
+
+    return data;
+  }
+
+  /**
+   * Get default health data structure
+   * @returns {Object} Default health data
+   */
+  static getDefaultData() {
+    return JSON.parse(JSON.stringify(DEFAULT_HEALTH_DATA));
+  }
+
+  /**
+   * Get default storage file path
+   * @returns {string} Default storage file path
+   */
+  static getDefaultStorageFile() {
+    return DEFAULT_STORAGE_FILE;
+  }
+}
+
+module.exports = { JSONStorage, DEFAULT_STORAGE_FILE, DEFAULT_HEALTH_DATA };

package/src/health-tracking/storage-interface.js

@@ -0,0 +1,63 @@
+/**
+ * Storage Interface for IDE Health Data
+ *
+ * Abstract interface for persisting health tracking data.
+ * Implementations must provide atomic read/write operations.
+ *
+ * @module storage-interface
+ */
+
+/**
+ * Base storage interface that all storage adapters must implement
+ * @interface StorageInterface
+ */
+class StorageInterface {
+  /**
+   * Read data from storage
+   * @returns {Promise<Object>} The stored data object
+   * @throws {FileSystemError} If read operation fails
+   */
+  async read() {
+    throw new Error('Method not implemented: read()');
+  }
+
+  /**
+   * Write data to storage atomically
+   * @param {Object} data - The data to write
+   * @returns {Promise<void>}
+   * @throws {FileSystemError} If write operation fails
+   * @throws {ValidationError} If data is invalid
+   */
+  async write(data) {
+    throw new Error('Method not implemented: write()');
+  }
+
+  /**
+   * Check if storage file exists
+   * @returns {Promise<boolean>} True if storage exists
+   */
+  async exists() {
+    throw new Error('Method not implemented: exists()');
+  }
+
+  /**
+   * Create backup of current storage
+   * @returns {Promise<string>} Path to backup file
+   * @throws {FileSystemError} If backup creation fails
+   */
+  async backup() {
+    throw new Error('Method not implemented: backup()');
+  }
+
+  /**
+   * Restore from backup file
+   * @param {string} backupPath - Path to backup file
+   * @returns {Promise<void>}
+   * @throws {FileSystemError} If restore operation fails
+   */
+  async restore(backupPath) {
+    throw new Error('Method not implemented: restore()');
+  }
+}
+
+module.exports = { StorageInterface };

package/src/health-tracking/validators.js

@@ -0,0 +1,277 @@
+/**
+ * Validation Utilities for IDE Health Data
+ *
+ * @module validators
+ */
+
+const { ValidationError } = require('./errors');
+
+/**
+ * Validates IDE health data structure according to schema
+ * @param {Object} data - The health data to validate
+ * @throws {ValidationError} If validation fails
+ */
+function validateHealthData(data) {
+  if (!data || typeof data !== 'object') {
+    throw new ValidationError('Health data must be an object', 'data', data);
+  }
+
+  // Validate version
+  if (!data.version || typeof data.version !== 'string') {
+    throw new ValidationError('Version must be a string', 'version', data.version);
+  }
+
+  // Validate lastUpdated
+  if (!data.lastUpdated || typeof data.lastUpdated !== 'string') {
+    throw new ValidationError('lastUpdated must be an ISO 8601 string', 'lastUpdated', data.lastUpdated);
+  }
+
+  // Validate ides object
+  if (!data.ides || typeof data.ides !== 'object') {
+    throw new ValidationError('ides must be an object', 'ides', data.ides);
+  }
+
+  // Validate each IDE record
+  for (const [ideId, ideRecord] of Object.entries(data.ides)) {
+    validateIDEHealthRecord(ideRecord, ideId);
+  }
+
+  // Validate timeoutConfig
+  if (data.timeoutConfig) {
+    validateTimeoutConfiguration(data.timeoutConfig);
+  }
+
+  // Validate defaultRequirement (optional)
+  if (data.defaultRequirement !== null && data.defaultRequirement !== undefined) {
+    validateDefaultRequirement(data.defaultRequirement);
+  }
+}
+
+/**
+ * Validates IDE health record structure
+ * @param {Object} record - The IDE health record to validate
+ * @param {string} ideId - IDE identifier for error messages
+ * @throws {ValidationError} If validation fails
+ */
+function validateIDEHealthRecord(record, ideId) {
+  if (!record || typeof record !== 'object') {
+    throw new ValidationError(`IDE health record for ${ideId} must be an object`, 'record', record);
+  }
+
+  // Validate successCount
+  if (typeof record.successCount !== 'number' || record.successCount < 0) {
+    throw new ValidationError(`successCount must be >= 0 for ${ideId}`, 'successCount', record.successCount);
+  }
+
+  // Validate failureCount
+  if (typeof record.failureCount !== 'number' || record.failureCount < 0) {
+    throw new ValidationError(`failureCount must be >= 0 for ${ideId}`, 'failureCount', record.failureCount);
+  }
+
+  // Validate responseTimes array
+  if (!Array.isArray(record.responseTimes)) {
+    throw new ValidationError(`responseTimes must be an array for ${ideId}`, 'responseTimes', record.responseTimes);
+  }
+
+  if (record.responseTimes.length > 50) {
+    throw new ValidationError(`responseTimes array exceeds max 50 entries for ${ideId}`, 'responseTimes.length', record.responseTimes.length);
+  }
+
+  // Validate ewma
+  if (typeof record.ewma !== 'number' || record.ewma < 0) {
+    throw new ValidationError(`ewma must be >= 0 for ${ideId}`, 'ewma', record.ewma);
+  }
+
+  // Validate lastSuccess (nullable)
+  if (record.lastSuccess !== null && typeof record.lastSuccess !== 'string') {
+    throw new ValidationError(`lastSuccess must be null or ISO 8601 string for ${ideId}`, 'lastSuccess', record.lastSuccess);
+  }
+
+  // Validate lastFailure (nullable)
+  if (record.lastFailure !== null && typeof record.lastFailure !== 'string') {
+    throw new ValidationError(`lastFailure must be null or ISO 8601 string for ${ideId}`, 'lastFailure', record.lastFailure);
+  }
+
+  // Validate consecutiveFailures
+  if (typeof record.consecutiveFailures !== 'number' || record.consecutiveFailures < 0) {
+    throw new ValidationError(`consecutiveFailures must be >= 0 for ${ideId}`, 'consecutiveFailures', record.consecutiveFailures);
+  }
+
+  // Validate currentTimeout (5 minutes minimum = 300000ms)
+  if (typeof record.currentTimeout !== 'number' || record.currentTimeout < 300000) {
+    throw new ValidationError(`currentTimeout must be >= 300000 (5 minutes) for ${ideId}`, 'currentTimeout', record.currentTimeout);
+  }
+
+  // Validate interactions array
+  if (!Array.isArray(record.interactions)) {
+    throw new ValidationError(`interactions must be an array for ${ideId}`, 'interactions', record.interactions);
+  }
+
+  if (record.interactions.length > 100) {
+    throw new ValidationError(`interactions array exceeds max 100 entries for ${ideId}`, 'interactions.length', record.interactions.length);
+  }
+
+  // Validate each interaction
+  record.interactions.forEach((interaction, index) => {
+    validateInteractionRecord(interaction, `${ideId}[${index}]`);
+  });
+}
+
+/**
+ * Validates interaction record structure
+ * @param {Object} interaction - The interaction record to validate
+ * @param {string} context - Context for error messages
+ * @throws {ValidationError} If validation fails
+ */
+function validateInteractionRecord(interaction, context) {
+  if (!interaction || typeof interaction !== 'object') {
+    throw new ValidationError(`Interaction at ${context} must be an object`, 'interaction', interaction);
+  }
+
+  // Validate timestamp
+  if (!interaction.timestamp || typeof interaction.timestamp !== 'string') {
+    throw new ValidationError(`timestamp must be ISO 8601 string at ${context}`, 'timestamp', interaction.timestamp);
+  }
+
+  // Validate outcome
+  const validOutcomes = ['success', 'failure', 'quota'];
+  if (!validOutcomes.includes(interaction.outcome)) {
+    throw new ValidationError(`outcome must be one of ${validOutcomes.join(', ')} at ${context}`, 'outcome', interaction.outcome);
+  }
+
+  // Validate responseTime (nullable)
+  if (interaction.responseTime !== null && (typeof interaction.responseTime !== 'number' || interaction.responseTime < 0)) {
+    throw new ValidationError(`responseTime must be null or >= 0 at ${context}`, 'responseTime', interaction.responseTime);
+  }
+
+  // Validate timeoutUsed
+  if (typeof interaction.timeoutUsed !== 'number' || interaction.timeoutUsed < 0) {
+    throw new ValidationError(`timeoutUsed must be >= 0 at ${context}`, 'timeoutUsed', interaction.timeoutUsed);
+  }
+
+  // Validate continuationPromptsDetected
+  if (typeof interaction.continuationPromptsDetected !== 'number' || interaction.continuationPromptsDetected < 0) {
+    throw new ValidationError(`continuationPromptsDetected must be >= 0 at ${context}`, 'continuationPromptsDetected', interaction.continuationPromptsDetected);
+  }
+
+  // Validate requirementId (nullable)
+  if (interaction.requirementId !== null && typeof interaction.requirementId !== 'string') {
+    throw new ValidationError(`requirementId must be null or string at ${context}`, 'requirementId', interaction.requirementId);
+  }
+
+  // Validate errorMessage (nullable)
+  if (interaction.errorMessage !== null && typeof interaction.errorMessage !== 'string') {
+    throw new ValidationError(`errorMessage must be null or string at ${context}`, 'errorMessage', interaction.errorMessage);
+  }
+}
+
+/**
+ * Validates timeout configuration structure
+ * @param {Object} config - The timeout configuration to validate
+ * @throws {ValidationError} If validation fails
+ */
+function validateTimeoutConfiguration(config) {
+  if (!config || typeof config !== 'object') {
+    throw new ValidationError('Timeout configuration must be an object', 'timeoutConfig', config);
+  }
+
+  // Validate mode
+  const validModes = ['adaptive', 'fixed'];
+  if (!validModes.includes(config.mode)) {
+    throw new ValidationError(`mode must be one of ${validModes.join(', ')}`, 'mode', config.mode);
+  }
+
+  // Validate defaultTimeout (5 minutes minimum)
+  if (typeof config.defaultTimeout !== 'number' || config.defaultTimeout < 300000) {
+    throw new ValidationError('defaultTimeout must be >= 300000 (5 minutes)', 'defaultTimeout', config.defaultTimeout);
+  }
+
+  // Validate bufferPercentage (20% to 100%)
+  if (typeof config.bufferPercentage !== 'number' || config.bufferPercentage < 0.2 || config.bufferPercentage > 1.0) {
+    throw new ValidationError('bufferPercentage must be between 0.2 and 1.0', 'bufferPercentage', config.bufferPercentage);
+  }
+
+  // Validate minSamplesForAdaptive (5 to 50)
+  if (typeof config.minSamplesForAdaptive !== 'number' || config.minSamplesForAdaptive < 5 || config.minSamplesForAdaptive > 50) {
+    throw new ValidationError('minSamplesForAdaptive must be between 5 and 50', 'minSamplesForAdaptive', config.minSamplesForAdaptive);
+  }
+
+  // Validate ewmaAlpha (0 to 1, exclusive)
+  if (typeof config.ewmaAlpha !== 'number' || config.ewmaAlpha <= 0 || config.ewmaAlpha >= 1) {
+    throw new ValidationError('ewmaAlpha must be between 0 and 1 (exclusive)', 'ewmaAlpha', config.ewmaAlpha);
+  }
+}
+
+/**
+ * Validates default requirement structure
+ * @param {Object} defaultReq - The default requirement to validate
+ * @throws {ValidationError} If validation fails
+ */
+function validateDefaultRequirement(defaultReq) {
+  if (!defaultReq || typeof defaultReq !== 'object') {
+    throw new ValidationError('Default requirement must be an object', 'defaultRequirement', defaultReq);
+  }
+
+  // Validate text (non-empty)
+  if (typeof defaultReq.text !== 'string' || defaultReq.text.trim().length === 0) {
+    throw new ValidationError('Default requirement text must be non-empty string', 'text', defaultReq.text);
+  }
+
+  // Validate maxIterations (nullable, 0 = unlimited)
+  if (defaultReq.maxIterations !== null && (typeof defaultReq.maxIterations !== 'number' || defaultReq.maxIterations < 0)) {
+    throw new ValidationError('maxIterations must be null or >= 0', 'maxIterations', defaultReq.maxIterations);
+  }
+
+  // Validate currentIteration
+  if (typeof defaultReq.currentIteration !== 'number' || defaultReq.currentIteration < 0) {
+    throw new ValidationError('currentIteration must be >= 0', 'currentIteration', defaultReq.currentIteration);
+  }
+
+  // Validate consecutiveFailures
+  if (typeof defaultReq.consecutiveFailures !== 'number' || defaultReq.consecutiveFailures < 0) {
+    throw new ValidationError('consecutiveFailures must be >= 0', 'consecutiveFailures', defaultReq.consecutiveFailures);
+  }
+
+  // Validate status
+  const validStatuses = ['pending', 'active', 'paused', 'completed', 'stopped'];
+  if (!validStatuses.includes(defaultReq.status)) {
+    throw new ValidationError(`status must be one of ${validStatuses.join(', ')}`, 'status', defaultReq.status);
+  }
+
+  // Validate lastProcessed (nullable)
+  if (defaultReq.lastProcessed !== null && typeof defaultReq.lastProcessed !== 'string') {
+    throw new ValidationError('lastProcessed must be null or ISO 8601 string', 'lastProcessed', defaultReq.lastProcessed);
+  }
+}
+
+/**
+ * Validates IDE identifier
+ * @param {string} ideId - IDE identifier to validate
+ * @throws {ValidationError} If validation fails
+ */
+function validateIdeId(ideId) {
+  if (!ideId || typeof ideId !== 'string' || ideId.trim().length === 0) {
+    throw new ValidationError('IDE identifier must be non-empty string', 'ideId', ideId);
+  }
+}
+
+/**
+ * Validates response time value
+ * @param {number} responseTime - Response time in milliseconds
+ * @throws {ValidationError} If validation fails
+ */
+function validateResponseTime(responseTime) {
+  if (typeof responseTime !== 'number' || responseTime < 0) {
+    throw new ValidationError('Response time must be >= 0', 'responseTime', responseTime);
+  }
+}
+
+module.exports = {
+  validateHealthData,
+  validateIDEHealthRecord,
+  validateInteractionRecord,
+  validateTimeoutConfiguration,
+  validateDefaultRequirement,
+  validateIdeId,
+  validateResponseTime,
+};