agileflow 2.90.7 → 2.92.0

package/lib/result-schema.js

@@ -0,0 +1,363 @@
+/**
+ * result-schema.js - Unified Result<T> type for consistent return values
+ *
+ * Provides standardized Result type with metadata for:
+ * - Consistent success/failure handling
+ * - Error code integration
+ * - Severity and category tracking
+ * - Automatic recovery suggestions
+ *
+ * Usage:
+ *   const { success, failure, createResult, isSuccess } = require('./result-schema');
+ *
+ *   // Success case
+ *   return success(data);
+ *
+ *   // Failure case
+ *   return failure('ENOENT', 'File not found');
+ *
+ *   // Check result
+ *   if (isSuccess(result)) {
+ *     console.log(result.data);
+ *   } else {
+ *     console.error(result.error);
+ *   }
+ */
+
+const { ErrorCodes, Severity, Category, getErrorCode } = require('./error-codes');
+
+/**
+ * @typedef {Object} ResultSuccess<T>
+ * @property {true} ok - Indicates success
+ * @property {T} data - The success data
+ * @property {undefined} error - No error on success
+ * @property {undefined} errorCode - No error code on success
+ */
+
+/**
+ * @typedef {Object} ResultFailure
+ * @property {false} ok - Indicates failure
+ * @property {undefined} data - No data on failure
+ * @property {string} error - Human-readable error message
+ * @property {string} errorCode - Machine-readable error code
+ * @property {string} severity - Error severity (critical, high, medium, low)
+ * @property {string} category - Error category (filesystem, permission, etc.)
+ * @property {boolean} recoverable - Whether the error can be recovered from
+ * @property {string} [suggestedFix] - Suggested fix for the error
+ * @property {string} [autoFix] - Auto-fix action name if available
+ * @property {Object} [context] - Additional context about the error
+ */
+
+/**
+ * @typedef {ResultSuccess<T> | ResultFailure} Result<T>
+ */
+
+/**
+ * Create a success result
+ * @template T
+ * @param {T} data - The success data
+ * @param {Object} [meta] - Optional metadata
+ * @returns {ResultSuccess<T>}
+ */
+function success(data, meta = {}) {
+  return {
+    ok: true,
+    data,
+    ...meta,
+  };
+}
+
+/**
+ * Create a failure result with error code metadata
+ * @param {string} errorCode - Error code (e.g., 'ENOENT', 'ECONFIG')
+ * @param {string} [message] - Optional custom error message
+ * @param {Object} [options] - Additional options
+ * @param {Object} [options.context] - Additional context about the error
+ * @param {Error} [options.cause] - Original error that caused this failure
+ * @returns {ResultFailure}
+ */
+function failure(errorCode, message, options = {}) {
+  const codeData = getErrorCode(errorCode) || ErrorCodes.EUNKNOWN;
+
+  return {
+    ok: false,
+    error: message || codeData.message,
+    errorCode: codeData.code,
+    severity: codeData.severity,
+    category: codeData.category,
+    recoverable: codeData.recoverable,
+    suggestedFix: codeData.suggestedFix,
+    autoFix: codeData.autoFix || null,
+    context: options.context,
+    cause: options.cause,
+  };
+}
+
+/**
+ * Create a failure result from an existing Error object
+ * @param {Error} error - The error object
+ * @param {string} [defaultCode='EUNKNOWN'] - Default error code if none detected
+ * @param {Object} [options] - Additional options
+ * @param {Object} [options.context] - Additional context about the error
+ * @returns {ResultFailure}
+ */
+function failureFromError(error, defaultCode = 'EUNKNOWN', options = {}) {
+  const { getErrorCodeFromError } = require('./error-codes');
+  const codeData = getErrorCodeFromError(error);
+
+  // Use detected code or default
+  const code = codeData.code !== 'EUNKNOWN' ? codeData.code : defaultCode;
+  const finalCodeData = ErrorCodes[code] || ErrorCodes.EUNKNOWN;
+
+  return {
+    ok: false,
+    error: error.message || finalCodeData.message,
+    errorCode: finalCodeData.code,
+    severity: finalCodeData.severity,
+    category: finalCodeData.category,
+    recoverable: finalCodeData.recoverable,
+    suggestedFix: finalCodeData.suggestedFix,
+    autoFix: finalCodeData.autoFix || null,
+    context: options.context,
+    cause: error,
+  };
+}
+
+/**
+ * Create a result from a boolean condition
+ * @template T
+ * @param {boolean} condition - Condition to check
+ * @param {T} data - Data to return on success
+ * @param {string} errorCode - Error code on failure
+ * @param {string} [errorMessage] - Error message on failure
+ * @returns {Result<T>}
+ */
+function fromCondition(condition, data, errorCode, errorMessage) {
+  if (condition) {
+    return success(data);
+  }
+  return failure(errorCode, errorMessage);
+}
+
+/**
+ * Create a result from a Promise
+ * @template T
+ * @param {Promise<T>} promise - Promise to wrap
+ * @param {string} [defaultCode='EUNKNOWN'] - Default error code on rejection
+ * @returns {Promise<Result<T>>}
+ */
+async function fromPromise(promise, defaultCode = 'EUNKNOWN') {
+  try {
+    const data = await promise;
+    return success(data);
+  } catch (error) {
+    return failureFromError(error, defaultCode);
+  }
+}
+
+/**
+ * Create a result from a sync function call
+ * @template T
+ * @param {() => T} fn - Function to execute
+ * @param {string} [defaultCode='EUNKNOWN'] - Default error code on throw
+ * @returns {Result<T>}
+ */
+function fromTry(fn, defaultCode = 'EUNKNOWN') {
+  try {
+    const data = fn();
+    return success(data);
+  } catch (error) {
+    return failureFromError(error, defaultCode);
+  }
+}
+
+/**
+ * Check if a result is successful
+ * @template T
+ * @param {Result<T>} result - Result to check
+ * @returns {boolean}
+ */
+function isSuccess(result) {
+  return result != null && result.ok === true;
+}
+
+/**
+ * Check if a result is a failure
+ * @template T
+ * @param {Result<T>} result - Result to check
+ * @returns {boolean}
+ */
+function isFailure(result) {
+  return result != null && result.ok === false;
+}
+
+/**
+ * Get data from result or throw if failure
+ * @template T
+ * @param {Result<T>} result - Result to unwrap
+ * @param {string} [context] - Context for error message
+ * @returns {T}
+ * @throws {Error} If result is a failure
+ */
+function unwrap(result, context) {
+  if (isSuccess(result)) {
+    return result.data;
+  }
+
+  const prefix = context ? `${context}: ` : '';
+  const error = new Error(`${prefix}${result.error}`);
+  error.errorCode = result.errorCode;
+  error.severity = result.severity;
+  error.category = result.category;
+  error.recoverable = result.recoverable;
+  error.suggestedFix = result.suggestedFix;
+  throw error;
+}
+
+/**
+ * Get data from result or return default value on failure
+ * @template T
+ * @param {Result<T>} result - Result to unwrap
+ * @param {T} defaultValue - Default value on failure
+ * @returns {T}
+ */
+function unwrapOr(result, defaultValue) {
+  if (isSuccess(result)) {
+    return result.data;
+  }
+  return defaultValue;
+}
+
+/**
+ * Transform successful result data
+ * @template T, U
+ * @param {Result<T>} result - Result to transform
+ * @param {(data: T) => U} fn - Transform function
+ * @returns {Result<U>}
+ */
+function map(result, fn) {
+  if (isSuccess(result)) {
+    return success(fn(result.data));
+  }
+  return result;
+}
+
+/**
+ * Chain result-returning operations
+ * @template T, U
+ * @param {Result<T>} result - Result to chain from
+ * @param {(data: T) => Result<U>} fn - Function returning Result
+ * @returns {Result<U>}
+ */
+function flatMap(result, fn) {
+  if (isSuccess(result)) {
+    return fn(result.data);
+  }
+  return result;
+}
+
+/**
+ * Combine multiple results into one
+ * @template T
+ * @param {Result<T>[]} results - Results to combine
+ * @returns {Result<T[]>} Combined result with array of data or first failure
+ */
+function all(results) {
+  const data = [];
+
+  for (const result of results) {
+    if (isFailure(result)) {
+      return result;
+    }
+    data.push(result.data);
+  }
+
+  return success(data);
+}
+
+/**
+ * Get first successful result or last failure
+ * @template T
+ * @param {Result<T>[]} results - Results to check
+ * @returns {Result<T>} First success or last failure
+ */
+function any(results) {
+  let lastFailure = null;
+
+  for (const result of results) {
+    if (isSuccess(result)) {
+      return result;
+    }
+    lastFailure = result;
+  }
+
+  return lastFailure || failure('EUNKNOWN', 'No results provided');
+}
+
+/**
+ * Format a result for logging/display
+ * @template T
+ * @param {Result<T>} result - Result to format
+ * @param {Object} [options] - Format options
+ * @param {boolean} [options.includeData=false] - Include data in output
+ * @param {boolean} [options.includeSuggestion=true] - Include suggested fix
+ * @returns {string}
+ */
+function format(result, options = {}) {
+  const { includeData = false, includeSuggestion = true } = options;
+
+  if (isSuccess(result)) {
+    if (includeData) {
+      return `[OK] ${JSON.stringify(result.data)}`;
+    }
+    return '[OK]';
+  }
+
+  const lines = [`[${result.errorCode}] ${result.error}`];
+  lines.push(`  Severity: ${result.severity} | Category: ${result.category}`);
+
+  if (includeSuggestion && result.suggestedFix) {
+    lines.push(`  Fix: ${result.suggestedFix}`);
+  }
+
+  if (result.autoFix) {
+    lines.push(`  Auto-fix available: npx agileflow doctor --fix`);
+  }
+
+  return lines.join('\n');
+}
+
+module.exports = {
+  // Constructors
+  success,
+  failure,
+  failureFromError,
+
+  // From helpers
+  fromCondition,
+  fromPromise,
+  fromTry,
+
+  // Type guards
+  isSuccess,
+  isFailure,
+
+  // Extractors
+  unwrap,
+  unwrapOr,
+
+  // Transformers
+  map,
+  flatMap,
+
+  // Combinators
+  all,
+  any,
+
+  // Utilities
+  format,
+
+  // Re-export enums for convenience
+  Severity,
+  Category,
+};

package/lib/result.js

@@ -0,0 +1,210 @@
+/**
+ * result.js - Unified Result Schema for AgileFlow
+ *
+ * Provides consistent result objects across modules with type helpers.
+ *
+ * Standard Result Schema:
+ *   { ok: boolean, data?: any, error?: string|Error }
+ *
+ * Extended fields (context-specific):
+ *   - found: boolean (for lookup operations)
+ *   - applied: number (for batch operations)
+ *   - cleaned: number (for cleanup operations)
+ *   - path: string (for file operations)
+ *   - status: string (for state operations)
+ *
+ * Usage:
+ *   const { ok, err, Result } = require('./result');
+ *
+ *   // Success
+ *   return ok({ path: '/saved/file.json' });
+ *
+ *   // Failure
+ *   return err('File not found');
+ *
+ *   // With data
+ *   return ok({ data: parsedConfig });
+ *
+ *   // Type checking
+ *   if (Result.isOk(result)) { ... }
+ */
+
+/**
+ * Create a success result
+ *
+ * @param {Object} [extras={}] - Additional fields to include
+ * @returns {{ ok: true } & Object} Success result
+ *
+ * @example
+ * ok() // { ok: true }
+ * ok({ data: config }) // { ok: true, data: config }
+ * ok({ path: '/file.json', created: true }) // { ok: true, path: '/file.json', created: true }
+ */
+function ok(extras = {}) {
+  return { ok: true, ...extras };
+}
+
+/**
+ * Create a failure result
+ *
+ * @param {string|Error} error - Error message or Error object
+ * @param {Object} [extras={}] - Additional fields to include
+ * @returns {{ ok: false, error: string } & Object} Failure result
+ *
+ * @example
+ * err('Not found') // { ok: false, error: 'Not found' }
+ * err(new Error('Failed')) // { ok: false, error: 'Failed' }
+ * err('Invalid', { code: 'EINVAL' }) // { ok: false, error: 'Invalid', code: 'EINVAL' }
+ */
+function err(error, extras = {}) {
+  const message = error instanceof Error ? error.message : String(error);
+  return { ok: false, error: message, ...extras };
+}
+
+/**
+ * Result utilities for type checking and manipulation
+ */
+const Result = {
+  /**
+   * Check if result is success
+   * @param {Object} result - Result to check
+   * @returns {boolean}
+   */
+  isOk(result) {
+    return Boolean(result && result.ok === true);
+  },
+
+  /**
+   * Check if result is failure
+   * @param {Object} result - Result to check
+   * @returns {boolean}
+   */
+  isErr(result) {
+    return Boolean(result && result.ok === false);
+  },
+
+  /**
+   * Unwrap result data or throw on error
+   * @param {Object} result - Result to unwrap
+   * @param {string} [context] - Context for error message
+   * @returns {any} The data field or the result without ok field
+   * @throws {Error} If result is not ok
+   */
+  unwrap(result, context = '') {
+    if (!Result.isOk(result)) {
+      const prefix = context ? `${context}: ` : '';
+      throw new Error(`${prefix}${result.error || 'Unknown error'}`);
+    }
+    return result.data !== undefined ? result.data : result;
+  },
+
+  /**
+   * Unwrap result data or return default value
+   * @param {Object} result - Result to unwrap
+   * @param {any} defaultValue - Value to return on error
+   * @returns {any}
+   */
+  unwrapOr(result, defaultValue) {
+    if (!Result.isOk(result)) {
+      return defaultValue;
+    }
+    return result.data !== undefined ? result.data : result;
+  },
+
+  /**
+   * Map over successful result
+   * @param {Object} result - Result to map
+   * @param {Function} fn - Function to apply to data
+   * @returns {Object} Mapped result or original error
+   */
+  map(result, fn) {
+    if (!Result.isOk(result)) {
+      return result;
+    }
+    try {
+      const data = result.data !== undefined ? result.data : result;
+      const mapped = fn(data);
+      return ok({ data: mapped });
+    } catch (e) {
+      return err(e);
+    }
+  },
+
+  /**
+   * Convert legacy { success: true/false } to standard { ok: true/false }
+   * @param {Object} legacyResult - Legacy result object
+   * @returns {Object} Standardized result
+   */
+  fromLegacy(legacyResult) {
+    if (legacyResult.success !== undefined) {
+      const { success, ...rest } = legacyResult;
+      return { ok: success, ...rest };
+    }
+    return legacyResult;
+  },
+
+  /**
+   * Convert standard result to legacy format for backwards compatibility
+   * @param {Object} result - Standard result object
+   * @returns {Object} Legacy result with success field
+   */
+  toLegacy(result) {
+    if (result.ok !== undefined) {
+      const { ok: isOk, ...rest } = result;
+      return { success: isOk, ...rest };
+    }
+    return result;
+  },
+};
+
+/**
+ * Async result helpers
+ */
+const AsyncResult = {
+  /**
+   * Wrap an async function to return Result
+   * @param {Function} fn - Async function to wrap
+   * @returns {Function} Wrapped function returning Result
+   *
+   * @example
+   * const safeRead = AsyncResult.wrap(fs.promises.readFile);
+   * const result = await safeRead('file.txt');
+   * if (Result.isOk(result)) { console.log(result.data); }
+   */
+  wrap(fn) {
+    return async (...args) => {
+      try {
+        const data = await fn(...args);
+        return ok({ data });
+      } catch (e) {
+        return err(e);
+      }
+    };
+  },
+
+  /**
+   * Execute multiple async operations and collect results
+   * @param {Array<Promise>} promises - Promises to execute
+   * @returns {Promise<Object>} Result with all settled results
+   */
+  async all(promises) {
+    try {
+      const results = await Promise.all(promises);
+      const allOk = results.every(r => Result.isOk(r));
+      if (allOk) {
+        return ok({ data: results });
+      }
+      const errors = results.filter(r => Result.isErr(r)).map(r => r.error);
+      return err(errors.join('; '), { partial: results });
+    } catch (e) {
+      return err(e);
+    }
+  },
+};
+
+module.exports = {
+  ok,
+  err,
+  Result,
+  AsyncResult,
+};

package/lib/session-registry.js

@@ -155,6 +155,11 @@ class SessionRegistry extends EventEmitter {
    * @returns {Object} Registry data
    */
   loadSync() {
+    // Return cached data if within TTL (performance optimization)
+    if (this._cache && Date.now() - this._cacheTime < this.cacheTTL) {
+      return this._cache;
+    }
+
     this._ensureDir();
     const result = this._jsonFile.readSync();
 
@@ -167,6 +172,14 @@ class SessionRegistry extends EventEmitter {
     return this._createDefaultRegistry();
   }
 
+  /**
+   * Invalidate cache (call after external modifications)
+   */
+  invalidateCache() {
+    this._cache = null;
+    this._cacheTime = 0;
+  }
+
   /**
    * Save registry
    * @param {Object} registry - Registry data to save