agileflow 2.89.3 → 2.90.1

package/tools/cli/lib/self-update.js

@@ -0,0 +1,148 @@
+/**
+ * AgileFlow CLI - Self-Update Module
+ *
+ * Provides self-update capability for the CLI to ensure users
+ * always run the latest version.
+ *
+ * Usage:
+ *   const { checkSelfUpdate, performSelfUpdate } = require('./lib/self-update');
+ *   await checkSelfUpdate(options, 'update');
+ */
+
+const path = require('path');
+const { spawnSync } = require('node:child_process');
+const semver = require('semver');
+const chalk = require('chalk');
+const { getLatestVersion } = require('./npm-utils');
+const { info } = require('./ui');
+
+/**
+ * Get the local CLI version from package.json
+ * @returns {string} Local CLI version
+ */
+function getLocalVersion() {
+  const packageJson = require(path.join(__dirname, '..', '..', '..', 'package.json'));
+  return packageJson.version;
+}
+
+/**
+ * Check if a self-update is needed
+ * @param {Object} options - Command options
+ * @param {boolean} [options.selfUpdate=true] - Whether self-update is enabled
+ * @param {boolean} [options.selfUpdated=false] - Whether already self-updated
+ * @returns {Promise<{needed: boolean, localVersion: string, latestVersion: string|null}>}
+ */
+async function checkSelfUpdate(options = {}) {
+  const shouldCheck = options.selfUpdate !== false && !options.selfUpdated;
+
+  if (!shouldCheck) {
+    return {
+      needed: false,
+      localVersion: getLocalVersion(),
+      latestVersion: null,
+    };
+  }
+
+  const localVersion = getLocalVersion();
+  const latestVersion = await getLatestVersion('agileflow');
+
+  if (!latestVersion) {
+    return {
+      needed: false,
+      localVersion,
+      latestVersion: null,
+    };
+  }
+
+  const needed = semver.lt(localVersion, latestVersion);
+
+  return {
+    needed,
+    localVersion,
+    latestVersion,
+  };
+}
+
+/**
+ * Perform self-update by re-running with latest CLI version
+ * @param {string} command - Command name to re-run
+ * @param {Object} options - Command options
+ * @param {Object} versionInfo - Version info from checkSelfUpdate
+ * @returns {number} Exit code from spawned process
+ */
+function performSelfUpdate(command, options, versionInfo) {
+  const { localVersion, latestVersion } = versionInfo;
+
+  // Display update notice
+  console.log(chalk.hex('#e8683a').bold('\n  AgileFlow CLI Update\n'));
+  info(`Updating CLI from v${localVersion} to v${latestVersion}...`);
+  console.log(chalk.dim('  Fetching latest version from npm...\n'));
+
+  // Build the command with all current options forwarded
+  const args = ['agileflow@latest', command, '--self-updated'];
+
+  // Forward common options
+  if (options.directory) args.push('-d', options.directory);
+  if (options.force) args.push('--force');
+
+  // Forward command-specific options
+  if (command === 'update' && options.ides) {
+    args.push('--ides', options.ides);
+  }
+
+  const result = spawnSync('npx', args, {
+    stdio: 'inherit',
+    cwd: process.cwd(),
+    shell: process.platform === 'win32',
+  });
+
+  return result.status ?? 0;
+}
+
+/**
+ * Check and perform self-update if needed
+ * Returns true if the caller should exit (because update was performed)
+ * @param {string} command - Command name
+ * @param {Object} options - Command options
+ * @returns {Promise<boolean>} True if caller should exit
+ */
+async function handleSelfUpdate(command, options) {
+  const versionInfo = await checkSelfUpdate(options);
+
+  if (versionInfo.needed) {
+    const exitCode = performSelfUpdate(command, options, versionInfo);
+    process.exit(exitCode);
+    return true; // Never reached, but for type safety
+  }
+
+  return false;
+}
+
+/**
+ * Middleware for self-update check
+ * @param {string} command - Command name
+ * @returns {Function} Middleware function
+ */
+function selfUpdateMiddleware(command) {
+  return async (ctx, next) => {
+    const versionInfo = await checkSelfUpdate(ctx.options);
+
+    if (versionInfo.needed) {
+      const exitCode = performSelfUpdate(command, ctx.options, versionInfo);
+      process.exit(exitCode);
+      return; // Never reached
+    }
+
+    // Store version info in context for later use
+    ctx.versionInfo = versionInfo;
+    await next();
+  };
+}
+
+module.exports = {
+  getLocalVersion,
+  checkSelfUpdate,
+  performSelfUpdate,
+  handleSelfUpdate,
+  selfUpdateMiddleware,
+};

package/tools/cli/lib/validation-middleware.js

@@ -0,0 +1,491 @@
+/**
+ * AgileFlow CLI - Validation Middleware
+ *
+ * Provides middleware layer for input validation that runs
+ * before command action handlers.
+ *
+ * Usage:
+ *   const { withValidation, schemas } = require('./lib/validation-middleware');
+ *   module.exports = {
+ *     name: 'mycommand',
+ *     validate: {
+ *       directory: schemas.path,
+ *       ide: schemas.ide,
+ *     },
+ *     action: withValidation(async (options) => { ... })
+ *   };
+ */
+
+const path = require('path');
+const { validatePath, isValidStoryId, isValidEpicId } = require('../../../lib/validate');
+const { IdeRegistry } = require('./ide-registry');
+
+/**
+ * Validation schema definition
+ * @typedef {Object} ValidationSchema
+ * @property {string} type - Schema type (path, ide, storyId, epicId, string, number)
+ * @property {boolean} [required=false] - Whether the field is required
+ * @property {*} [default] - Default value if not provided
+ * @property {Function} [validate] - Custom validation function
+ * @property {string} [errorMessage] - Custom error message
+ */
+
+/**
+ * Validation result
+ * @typedef {Object} ValidationResult
+ * @property {boolean} ok - Whether validation passed
+ * @property {Object} [data] - Validated and transformed data
+ * @property {string[]} [errors] - List of validation errors
+ */
+
+/**
+ * Pre-defined validation schemas for common types
+ */
+const schemas = {
+  /**
+   * Path schema - validates directory/file paths
+   * Automatically resolves to absolute path and validates against traversal
+   */
+  path: {
+    type: 'path',
+    required: false,
+    default: '.',
+    errorMessage: 'Invalid path',
+  },
+
+  /**
+   * Required path schema
+   */
+  pathRequired: {
+    type: 'path',
+    required: true,
+    errorMessage: 'Path is required',
+  },
+
+  /**
+   * IDE schema - validates IDE name against registry
+   */
+  ide: {
+    type: 'ide',
+    required: false,
+    errorMessage: 'Invalid IDE name',
+  },
+
+  /**
+   * Required IDE schema
+   */
+  ideRequired: {
+    type: 'ide',
+    required: true,
+    errorMessage: 'IDE name is required',
+  },
+
+  /**
+   * Story ID schema - validates US-XXXX format
+   */
+  storyId: {
+    type: 'storyId',
+    required: false,
+    errorMessage: 'Invalid story ID (expected US-XXXX)',
+  },
+
+  /**
+   * Required story ID schema
+   */
+  storyIdRequired: {
+    type: 'storyId',
+    required: true,
+    errorMessage: 'Story ID is required (expected US-XXXX)',
+  },
+
+  /**
+   * Epic ID schema - validates EP-XXXX format
+   */
+  epicId: {
+    type: 'epicId',
+    required: false,
+    errorMessage: 'Invalid epic ID (expected EP-XXXX)',
+  },
+
+  /**
+   * Required epic ID schema
+   */
+  epicIdRequired: {
+    type: 'epicId',
+    required: true,
+    errorMessage: 'Epic ID is required (expected EP-XXXX)',
+  },
+
+  /**
+   * String schema with optional length constraints
+   * @param {Object} options - Schema options
+   * @returns {ValidationSchema}
+   */
+  string: (options = {}) => ({
+    type: 'string',
+    required: options.required || false,
+    minLength: options.minLength,
+    maxLength: options.maxLength,
+    pattern: options.pattern,
+    errorMessage: options.errorMessage || 'Invalid string value',
+  }),
+
+  /**
+   * Number schema with optional range constraints
+   * @param {Object} options - Schema options
+   * @returns {ValidationSchema}
+   */
+  number: (options = {}) => ({
+    type: 'number',
+    required: options.required || false,
+    min: options.min,
+    max: options.max,
+    integer: options.integer || false,
+    errorMessage: options.errorMessage || 'Invalid number value',
+  }),
+
+  /**
+   * Boolean schema
+   */
+  boolean: {
+    type: 'boolean',
+    required: false,
+    errorMessage: 'Invalid boolean value',
+  },
+
+  /**
+   * Enum schema
+   * @param {string[]} values - Allowed values
+   * @param {Object} options - Schema options
+   * @returns {ValidationSchema}
+   */
+  enum: (values, options = {}) => ({
+    type: 'enum',
+    values,
+    required: options.required || false,
+    errorMessage: options.errorMessage || `Invalid value (expected: ${values.join(', ')})`,
+  }),
+};
+
+/**
+ * Validate a single field against its schema
+ * @param {string} fieldName - Name of the field
+ * @param {*} value - Value to validate
+ * @param {ValidationSchema} schema - Schema to validate against
+ * @param {string} baseDir - Base directory for path validation
+ * @returns {ValidationResult}
+ */
+function validateField(fieldName, value, schema, baseDir) {
+  const errors = [];
+
+  // Check required
+  if (schema.required && (value === undefined || value === null || value === '')) {
+    return {
+      ok: false,
+      errors: [schema.errorMessage || `${fieldName} is required`],
+    };
+  }
+
+  // Return default if not provided
+  if (value === undefined || value === null || value === '') {
+    return {
+      ok: true,
+      data: schema.default,
+    };
+  }
+
+  // Validate by type
+  switch (schema.type) {
+    case 'path': {
+      // Convert to string if not already
+      const pathValue = String(value);
+
+      // Resolve path relative to current directory
+      const resolvedPath = path.resolve(pathValue);
+
+      // Validate path is within safe bounds
+      const pathResult = validatePath(pathValue, baseDir, {
+        allowSymlinks: false,
+        mustExist: false,
+      });
+
+      if (!pathResult.ok) {
+        return {
+          ok: false,
+          errors: [pathResult.error?.message || schema.errorMessage || 'Invalid path'],
+        };
+      }
+
+      return {
+        ok: true,
+        data: resolvedPath,
+      };
+    }
+
+    case 'ide': {
+      // Normalize IDE name to lowercase before validation
+      const normalizedIde = String(value).toLowerCase();
+      const validation = IdeRegistry.validate(normalizedIde);
+      if (!validation.ok) {
+        return {
+          ok: false,
+          errors: [validation.error || schema.errorMessage],
+        };
+      }
+      return {
+        ok: true,
+        data: normalizedIde,
+      };
+    }
+
+    case 'storyId': {
+      // Normalize story ID to uppercase before validation
+      const normalizedStoryId = String(value).toUpperCase();
+      if (!isValidStoryId(normalizedStoryId)) {
+        return {
+          ok: false,
+          errors: [schema.errorMessage || 'Invalid story ID (expected US-XXXX)'],
+        };
+      }
+      return {
+        ok: true,
+        data: normalizedStoryId,
+      };
+    }
+
+    case 'epicId': {
+      // Normalize epic ID to uppercase before validation
+      const normalizedEpicId = String(value).toUpperCase();
+      if (!isValidEpicId(normalizedEpicId)) {
+        return {
+          ok: false,
+          errors: [schema.errorMessage || 'Invalid epic ID (expected EP-XXXX)'],
+        };
+      }
+      return {
+        ok: true,
+        data: normalizedEpicId,
+      };
+    }
+
+    case 'string': {
+      if (typeof value !== 'string') {
+        return {
+          ok: false,
+          errors: [schema.errorMessage || `${fieldName} must be a string`],
+        };
+      }
+
+      if (schema.minLength && value.length < schema.minLength) {
+        return {
+          ok: false,
+          errors: [`${fieldName} must be at least ${schema.minLength} characters`],
+        };
+      }
+
+      if (schema.maxLength && value.length > schema.maxLength) {
+        return {
+          ok: false,
+          errors: [`${fieldName} must be at most ${schema.maxLength} characters`],
+        };
+      }
+
+      if (schema.pattern && !schema.pattern.test(value)) {
+        return {
+          ok: false,
+          errors: [schema.errorMessage || `${fieldName} has invalid format`],
+        };
+      }
+
+      return {
+        ok: true,
+        data: value,
+      };
+    }
+
+    case 'number': {
+      const num = parseFloat(value);
+
+      if (isNaN(num)) {
+        return {
+          ok: false,
+          errors: [schema.errorMessage || `${fieldName} must be a number`],
+        };
+      }
+
+      if (schema.integer && !Number.isInteger(num)) {
+        return {
+          ok: false,
+          errors: [`${fieldName} must be an integer`],
+        };
+      }
+
+      if (schema.min !== undefined && num < schema.min) {
+        return {
+          ok: false,
+          errors: [`${fieldName} must be at least ${schema.min}`],
+        };
+      }
+
+      if (schema.max !== undefined && num > schema.max) {
+        return {
+          ok: false,
+          errors: [`${fieldName} must be at most ${schema.max}`],
+        };
+      }
+
+      return {
+        ok: true,
+        data: num,
+      };
+    }
+
+    case 'boolean': {
+      const boolValue = value === true || value === 'true' || value === '1';
+      return {
+        ok: true,
+        data: boolValue,
+      };
+    }
+
+    case 'enum': {
+      if (!schema.values.includes(value)) {
+        return {
+          ok: false,
+          errors: [schema.errorMessage || `Invalid value for ${fieldName}`],
+        };
+      }
+      return {
+        ok: true,
+        data: value,
+      };
+    }
+
+    default:
+      // Unknown type - pass through
+      return {
+        ok: true,
+        data: value,
+      };
+  }
+}
+
+/**
+ * Validate all fields in options against their schemas
+ * @param {Object} options - Command options
+ * @param {Object} validationSchemas - Schema definitions
+ * @param {string} [baseDir=process.cwd()] - Base directory for path validation
+ * @returns {ValidationResult}
+ */
+function validateOptions(options, validationSchemas, baseDir = process.cwd()) {
+  const errors = [];
+  const validatedData = { ...options };
+
+  for (const [fieldName, schema] of Object.entries(validationSchemas)) {
+    const value = options[fieldName];
+    const result = validateField(fieldName, value, schema, baseDir);
+
+    if (!result.ok) {
+      errors.push(...result.errors);
+    } else {
+      validatedData[fieldName] = result.data;
+    }
+  }
+
+  if (errors.length > 0) {
+    return { ok: false, errors };
+  }
+
+  return { ok: true, data: validatedData };
+}
+
+/**
+ * Create a validation wrapper for command actions
+ * @param {Function} action - Original command action
+ * @param {Object} validationSchemas - Schema definitions
+ * @returns {Function} Wrapped action with validation
+ */
+function createValidationWrapper(action, validationSchemas) {
+  return async function validatedAction(...args) {
+    // Get options from the last argument (Commander.js pattern)
+    const options = args[args.length - 1];
+
+    // Validate options
+    const result = validateOptions(options, validationSchemas);
+
+    if (!result.ok) {
+      const { ErrorHandler } = require('./error-handler');
+      const handler = new ErrorHandler('validation');
+
+      // Format errors nicely
+      const errorList = result.errors.map(e => `  • ${e}`).join('\n');
+      handler.warning(
+        'Input validation failed',
+        `Please fix the following:\n${errorList}`,
+        'Check command help with --help'
+      );
+      return;
+    }
+
+    // Replace options with validated data
+    args[args.length - 1] = { ...options, ...result.data };
+
+    // Call original action
+    return action.apply(this, args);
+  };
+}
+
+/**
+ * Decorator to add validation to a command action
+ * @param {Object} validationSchemas - Schema definitions
+ * @returns {Function} Decorator function
+ */
+function withValidation(validationSchemas) {
+  return function (action) {
+    return createValidationWrapper(action, validationSchemas);
+  };
+}
+
+/**
+ * Shorthand to wrap an action directly with schemas
+ * @param {Function} action - Action function
+ * @param {Object} validationSchemas - Schema definitions
+ * @returns {Function} Wrapped action
+ */
+function validated(action, validationSchemas) {
+  return createValidationWrapper(action, validationSchemas);
+}
+
+/**
+ * Validate path argument automatically
+ * Use as middleware before any path-based command
+ * @param {string} pathValue - Path value from options
+ * @param {string} fieldName - Name of the path field
+ * @returns {ValidationResult}
+ */
+function validatePathArgument(pathValue, fieldName = 'path') {
+  return validateField(fieldName, pathValue, schemas.path, process.cwd());
+}
+
+/**
+ * Format validation errors for display
+ * @param {string[]} errors - List of errors
+ * @returns {string} Formatted error message
+ */
+function formatValidationErrors(errors) {
+  if (errors.length === 1) {
+    return errors[0];
+  }
+  return errors.map((e, i) => `${i + 1}. ${e}`).join('\n');
+}
+
+module.exports = {
+  schemas,
+  validateField,
+  validateOptions,
+  createValidationWrapper,
+  withValidation,
+  validated,
+  validatePathArgument,
+  formatValidationErrors,
+};