@shohojdhara/atomix 0.4.7 → 0.4.9

package/scripts/cli/commands/clean.js

@@ -0,0 +1,109 @@
+/**
+ * Atomix CLI Clean Command
+ * Safely clean build artifacts and cache files
+ */
+
+import { logger } from '../utils/logger.js';
+import { AtomixCLIError } from '../utils/error.js';
+import { cacheManager } from '../utils/cache-manager.js';
+
+/**
+ * Action logic for cleaning build artifacts
+ * @param {object} options - Command options
+ * @param {boolean} options.all - Clean node_modules as well
+ * @param {boolean} options.cache - Only clean cache directories
+ * @param {boolean} options.dryRun - Preview without deleting
+ * @param {boolean} options.verbose - Show detailed output
+ */
+export async function cleanAction(options) {
+  const spinner = logger.spinner('Analyzing project...').start();
+  
+  try {
+    // Step 1: Identify what can be cleaned
+    spinner.text = 'Scanning for cleanable files...';
+    const targets = await cacheManager.identifyTargets(options);
+    
+    // Filter out protected files
+    const safeTargets = targets.filter(target => {
+      if (cacheManager.isProtected(target.path)) {
+        logger.debug(`Skipping protected file: ${target.path}`);
+        return false;
+      }
+      return true;
+    });
+
+    // Step 2: Handle empty state
+    if (safeTargets.length === 0) {
+      spinner.succeed('Nothing to clean! Your project is already tidy.');
+      return;
+    }
+
+    // Step 3: Calculate total size
+    const totalSize = await cacheManager.calculateSize(safeTargets);
+    const formattedSize = cacheManager.formatBytes(totalSize);
+
+    // Step 4: Handle dry-run mode
+    if (options.dryRun || process.env.ATOMIX_DRY_RUN === 'true') {
+      spinner.stop();
+      cacheManager.displayDryRun(safeTargets);
+      logger.info(
+        `\nℹ️  Total size: ${formattedSize}\n` +
+        `⚠️  Run without --dry-run to actually delete these files.`
+      );
+      return;
+    }
+
+    // Step 5: Perform cleanup
+    spinner.text = `Cleaning ${safeTargets.length} item(s)...`;
+    
+    let successCount = 0;
+    let errorCount = 0;
+    const errors = [];
+
+    for (const target of safeTargets) {
+      try {
+        if (options.verbose) {
+          logger.info(`Removing: ${target.relativePath}`);
+        }
+        
+        await cacheManager.deletePath(target.path, options);
+        successCount++;
+      } catch (error) {
+        errorCount++;
+        errors.push({
+          path: target.relativePath,
+          error: error.message
+        });
+        logger.debug(`Failed to delete ${target.path}: ${error.message}`);
+      }
+    }
+
+    // Step 6: Report results
+    if (errorCount > 0) {
+      spinner.warn(`Cleanup completed with ${errorCount} warning(s)`);
+      
+      if (options.verbose && errors.length > 0) {
+        logger.warn('\nWarnings:');
+        errors.forEach(err => {
+          logger.warn(`  • ${err.path}: ${err.error}`);
+        });
+      }
+    } else {
+      spinner.succeed(`Cleanup completed! Removed ${successCount} item(s) (${formattedSize})`);
+    }
+
+  } catch (error) {
+    spinner.fail('Cleanup failed');
+    
+    // Re-throw as AtomixCLIError with helpful suggestions
+    throw new AtomixCLIError(
+      error.message,
+      'FILESYSTEM_ERROR',
+      [
+        'Check if you have write permissions for the target directories',
+        'Ensure no files are locked by another process',
+        'Try running with --verbose to see which file caused the issue'
+      ]
+    );
+  }
+}

package/scripts/cli/commands/doctor.js

@@ -0,0 +1,88 @@
+/**
+ * Atomix CLI Doctor Command
+ * Diagnostic tool to verify the environment and project health
+ */
+
+import { logger } from '../utils/logger.js';
+import { checkRuntimes, checkProjectStructure, checkConfig, checkPermissions, checkPlugins, checkTokens } from '../utils/diagnostics.js';
+import chalk from 'chalk';
+
+/** Short descriptions for each doctor check (for --explain) */
+const DOCTOR_CHECK_DESCRIPTIONS = {
+  'Node.js': 'Ensures Node.js >= 18.0.0 for CLI and build compatibility.',
+  'NPM': 'Ensures npm >= 8.0.0 for package management.',
+  'Directory: src': 'Required project directory for application source.',
+  'Directory: scripts/cli': 'Required only for Atomix monorepo development (internal).',
+  'Directory: themes (Recommended)': 'Optional; recommended for custom themes.',
+  'Directory: docs (Recommended)': 'Optional; recommended for documentation.',
+  'Configuration': 'Looks for atomix.config.ts or atomix.config.js in project root.',
+  'Permissions: .': 'Read/write access to project root.',
+  'Permissions: src': 'Read/write access to src directory.',
+  'Plugins': 'Reports plugins registered in atomix.config.',
+  'Tokens': 'Design token discovery: src/styles/01-settings/_settings.*.scss (optional).'
+};
+
+/**
+ * Action for the `atomix doctor` command
+ * @param {object} options - Command options (--explain)
+ */
+export async function doctorAction(options = {}) {
+  if (options.explain) {
+    console.log(chalk.bold.cyan('Atomix doctor checks:\n'));
+    for (const [name, desc] of Object.entries(DOCTOR_CHECK_DESCRIPTIONS)) {
+      console.log(chalk.bold(name));
+      console.log(chalk.gray(`  ${desc}\n`));
+    }
+    console.log(chalk.gray('Run `atomix doctor` (without --explain) to run the checks.'));
+    return;
+  }
+
+  const spinner = logger.spinner('Running diagnostics...').start();
+
+  try {
+    const runtimes = await checkRuntimes();
+    const structure = await checkProjectStructure();
+    const config = await checkConfig();
+    const permissions = await checkPermissions();
+    const plugins = await checkPlugins();
+    const tokens = await checkTokens();
+
+    spinner.stop();
+
+    logger.box('Atomix Diagnostic Report', {
+      borderColor: 'cyan',
+      padding: 1,
+      margin: 1
+    });
+
+    const allResults = [...runtimes, ...structure, ...config, ...permissions, ...plugins, ...tokens];
+    let issuesFound = false;
+
+    for (const result of allResults) {
+      const icon = result.status === 'pass' ? chalk.green('✓') : 
+                   result.status === 'warn' ? chalk.yellow('!') : 
+                   chalk.red('❌');
+      
+      const statusText = result.status.toUpperCase();
+      const nameText = chalk.bold(result.name);
+      const messageText = chalk.gray(result.message);
+
+      console.log(`${icon} [${statusText}] ${nameText}: ${messageText}`);
+
+      if (result.status !== 'pass' && result.suggestion) {
+        issuesFound = true;
+        console.log(chalk.blue(`   💡 Suggestion: ${result.suggestion}`));
+      }
+    }
+
+    if (!issuesFound) {
+      console.log(chalk.bold.green('\n🎉 Your environment is healthy! Everything is ready for Atomix.'));
+    } else {
+      console.log(chalk.bold.yellow('\n⚠️ Some issues or suggestions were found. Review the report above.'));
+    }
+
+  } catch (error) {
+    spinner.fail('Diagnostic failed');
+    throw error;
+  }
+}

package/scripts/cli/commands/generate.js

@@ -0,0 +1,218 @@
+/**
+ * Atomix CLI Generate Command
+ * Orchestrates component generation with validation, hooks, and error handling
+ */
+
+import inquirer from 'inquirer';
+import { logger } from '../utils/logger.js';
+import { AtomixCLIError } from '../utils/error.js';
+import { generator, COMPLEXITY_LEVELS, COMPONENT_FEATURES } from '../internal/generator.js';
+import { filesystem } from '../internal/filesystem.js';
+import { validateComponentName } from '../utils/validation.js';
+import { hookManager } from '../internal/hooks.js';
+import { validateComponent } from '../internal/validator.js';
+
+/**
+ * Action logic for generating components
+ * @param {string} type - Component type (component, token, etc.)
+ * @param {string} name - Component name
+ * @param {Object} options - CLI options
+ */
+export async function generateAction(type, name, options) {
+  let config = {
+    name,
+    complexity: options.complexity || 'medium',
+    features: determineFeatures(options),
+    outputPath: options.path || './src/components'
+  };
+
+  if (options.interactive) {
+    config = await promptInteractive();
+    if (!config) return;
+  }
+
+  // Pre-generation hook
+  try {
+    config = await hookManager.trigger('preGenerate', config);
+  } catch (error) {
+    throw new AtomixCLIError(
+      `Pre-generation hook failed: ${error.message}`,
+      'HOOK_EXECUTION_FAILED',
+      [
+        'Check preGenerate hook implementation',
+        'Verify hook returns valid configuration object',
+        'Review hook logs with ATOMIX_DEBUG=true'
+      ]
+    );
+  }
+
+  const spinner = logger.spinner(`Generating ${type}: ${config.name}...`).start();
+
+  try {
+    // Validation
+    const nameValidation = await validateComponentName(config.name);
+    if (!nameValidation.isValid) {
+      throw new AtomixCLIError(
+        nameValidation.error,
+        'INVALID_NAME',
+        [
+          'Use PascalCase (e.g., MyComponent, Button)',
+          'Start with a letter (not numbers)',
+          'Avoid special characters except letters and numbers'
+        ]
+      );
+    }
+
+    const pathValidation = filesystem.validatePath(config.outputPath);
+    if (!pathValidation.isValid) {
+      throw new AtomixCLIError(
+        pathValidation.error,
+        'INVALID_PATH',
+        [
+          'Ensure path is within project root',
+          'Check you have write permissions for target directory',
+          'Use absolute path or path relative to current directory'
+        ]
+      );
+    }
+
+    // Execution
+    let path;
+    if (options.prompt) {
+      path = await generator.generateAIComponent(config.name, options.prompt, {
+        ...config,
+        logger: { debug: (msg) => logger.debug(msg) }
+      });
+    } else {
+      path = await generator.generateComponent(config.name, {
+        ...config,
+        logger: { debug: (msg) => logger.debug(msg) }
+      });
+    }
+
+    spinner.succeed(`Generated component ${config.name} at ${path}`);
+
+    if (options.validate) {
+      let report = await generator.validate(config.name, path);
+      // Component-scoped A11y and token validation (Phase 2: design system creator)
+      if (type === 'component') {
+        const componentReport = await validateComponent(config.name, process.cwd());
+        const componentIssues = componentReport.issues.map(
+          (i) => (typeof i === 'string' ? i : `[${i.type}] ${i.file}: ${i.message}`)
+        );
+        report.issues = [...report.issues, ...componentIssues];
+        report.valid = report.valid && componentReport.valid;
+      }
+
+      // Validation hook
+      try {
+        report = await hookManager.trigger('onValidate', report);
+      } catch (error) {
+        logger.warn(`Validation hook failed: ${error.message}`);
+      }
+
+      if (!report.valid) {
+        logger.warn('Validation found issues:');
+        report.issues.forEach((i) => logger.info(`  - ${i}`));
+      }
+    }
+
+    // Post-build hook (using generated path as asset)
+    try {
+      await hookManager.trigger('postBuild', [path]);
+    } catch (error) {
+      logger.warn(`Post-build hook failed: ${error.message}`);
+    }
+
+    logger.box(`🎉 Component ${config.name} ready!\nRun: atomix validate component ${config.name}`);
+
+  } catch (error) {
+    spinner.fail('Generation failed');
+    
+    // Enhance error context for known error types
+    if (error.code === 'TEMPLATE_NOT_FOUND') {
+      error.suggestions.push('Run `atomix doctor` to check template availability');
+    } else if (error.code === 'FRAMEWORK_DETECTION_FAILED') {
+      error.suggestions.push('Initialize project with `npm init` or `yarn init`');
+    } else if (error.code === 'FILE_WRITE_FAILED') {
+      error.suggestions.push('Check disk space and file permissions');
+    }
+    
+    throw error;
+  }
+}
+
+/**
+ * Determine which features to enable based on CLI options
+ * @param {Object} options - CLI options
+ * @returns {string[]} Array of feature names
+ */
+function determineFeatures(options) {
+  const features = [];
+  
+  // Default features (always enabled unless explicitly disabled)
+  if (options.storybook !== false) {
+    features.push('storybook');
+  }
+  
+  if (options.hook !== false) {
+    features.push('hook');
+  }
+  
+  if (options.styles !== false) {
+    features.push('styles');
+  }
+  
+  // Optional features (enabled by flag)
+  if (options.tests === true) {
+    features.push('tests');
+  }
+  
+  return features;
+}
+
+/**
+ * Interactive mode handler
+ * Prompts user for component configuration
+ * @returns {Promise<Object>} Configuration object
+ */
+async function promptInteractive() {
+  logger.info('🎨 Interactive Component Generator');
+  
+  const answers = await inquirer.prompt([
+    {
+      type: 'input',
+      name: 'name',
+      message: 'Component name (PascalCase):',
+      validate: async (val) => {
+        const result = await validateComponentName(val);
+        return result.isValid || `Invalid: ${result.error}. Use PascalCase (e.g., MyComponent)`;
+      }
+    },
+    {
+      type: 'list',
+      name: 'complexity',
+      message: 'Complexity level:',
+      choices: Object.keys(COMPLEXITY_LEVELS).map(k => ({
+        name: k.toLowerCase(),
+        value: k.toLowerCase()
+      })),
+      default: 'medium'
+    },
+    {
+      type: 'checkbox',
+      name: 'features',
+      message: 'Select features:',
+      choices: Object.keys(COMPONENT_FEATURES).map(k => ({
+        name: `${k.toLowerCase()}${COMPONENT_FEATURES[k].default ? ' (default)' : ''}`,
+        value: COMPONENT_FEATURES[k].name,
+        checked: COMPONENT_FEATURES[k].default
+      }))
+    }
+  ]);
+
+  return {
+    ...answers,
+    outputPath: './src/components'
+  };
+}

package/scripts/cli/commands/init.js

@@ -0,0 +1,73 @@
+/**
+ * Atomix CLI Init Command
+ */
+
+import inquirer from 'inquirer';
+import { logger } from '../utils/logger.js';
+import { wizard } from '../internal/wizard.js';
+import { isNonInteractive } from '../utils/helpers.js';
+import { AtomixCLIError, ErrorCategory } from '../utils/error.js';
+
+const DEFAULT_PROJECT_TYPE = 'react';
+const DEFAULT_FEATURES = ['typescript', 'storybook', 'testing'];
+
+/**
+ * Action logic for the init command
+ * @param {object} options - Command options (--yes, --type)
+ */
+export async function initAction(options = {}) {
+  const useDefaults = options.yes || options.type || isNonInteractive();
+  let projectType = (options.type || '').toLowerCase();
+  const validTypes = ['react', 'nextjs', 'vanilla'];
+  if (options.type && !validTypes.includes(projectType)) {
+    throw new AtomixCLIError(
+      `Invalid --type: ${options.type}. Use one of: ${validTypes.join(', ')}`,
+      ErrorCategory.VALIDATION,
+      ['Example: atomix init --type react']
+    );
+  }
+  if (!projectType) projectType = DEFAULT_PROJECT_TYPE;
+
+  logger.info('🎨 Atomix Design System Setup Wizard');
+
+  try {
+    let answers;
+    if (useDefaults) {
+      answers = {
+        projectType,
+        features: DEFAULT_FEATURES
+      };
+      if (options.type) logger.info(`Using project type: ${projectType}`);
+    } else {
+      answers = await inquirer.prompt([
+        {
+          type: 'list',
+          name: 'projectType',
+          message: 'What type of project are you building?',
+          choices: ['react', 'nextjs', 'vanilla'],
+          default: projectType
+        },
+        {
+          type: 'checkbox',
+          name: 'features',
+          message: 'Select features:',
+          choices: ['typescript', 'storybook', 'testing']
+        }
+      ]);
+    }
+
+    const spinner = logger.spinner('Setting up project...').start();
+
+    await wizard.initProject(answers.projectType, {
+      ...answers,
+      logger: { debug: (msg) => logger.debug(msg) }
+    });
+
+    spinner.succeed('Project initialized successfully');
+
+    logger.box('✨ Setup Complete!\nRun: npm run dev');
+  } catch (error) {
+    logger.error(`Setup failed: ${error.message}`);
+    throw error;
+  }
+}

package/scripts/cli/commands/migrate.js

@@ -0,0 +1,106 @@
+/**
+ * Atomix CLI - Migrate Command
+ * Handles migrations from Tailwind, Bootstrap, and other frameworks
+ */
+
+import { resolve } from 'path';
+import { stat } from 'fs/promises';
+import chalk from 'chalk';
+import { logger } from '../utils/logger.js';
+import { migrateTailwind, migrateBootstrap } from '../migration-tools.js';
+import { AtomixCLIError, ErrorCategory } from '../utils/error.js';
+
+/**
+ * Ensure source is a directory; throw AtomixCLIError otherwise
+ */
+async function ensureSourceIsDirectory(source) {
+  const absolute = resolve(process.cwd(), source);
+  let st;
+  try {
+    st = await stat(absolute);
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      throw new AtomixCLIError(
+        `Source not found: ${source}`,
+        ErrorCategory.INVALID_PATH,
+        ['Source must be a directory. Pass the project root (e.g. . or ./my-app).', 'Check that the path exists.']
+      );
+    }
+    throw err;
+  }
+  if (!st.isDirectory()) {
+    throw new AtomixCLIError(
+      `Source is not a directory: ${source}`,
+      ErrorCategory.INVALID_PATH,
+      ['Source must be the project root directory (e.g. . or ./my-tailwind-app).', 'Do not pass a file path (e.g. package.json).']
+    );
+  }
+  return absolute;
+}
+
+/**
+ * Migrate action handler
+ */
+export async function migrateAction(type, source, options) {
+  await ensureSourceIsDirectory(source);
+
+  logger.info(chalk.blue(`🚀 Starting migration: ${type} from ${source}...`));
+
+  try {
+    let report;
+
+    switch (type.toLowerCase()) {
+      case 'tailwind':
+        report = await migrateTailwind(source, options);
+        break;
+      case 'bootstrap':
+        report = await migrateBootstrap(source, options);
+        break;
+      default:
+        throw new AtomixCLIError(
+          `Unsupported migration type: ${type}. Use tailwind or bootstrap.`,
+          ErrorCategory.VALIDATION,
+          ['Example: atomix migrate tailwind .']
+        );
+    }
+
+    // Display Migration Report
+    displayMigrationReport(report);
+
+  } catch (error) {
+    if (error instanceof AtomixCLIError) throw error;
+    throw new AtomixCLIError(
+      error.message || 'Migration failed',
+      ErrorCategory.FILESYSTEM,
+      ['Check source path and permissions. Run with --dry-run to preview.']
+    );
+  }
+}
+
+/**
+ * Display migration report in a clean format
+ */
+function displayMigrationReport(report) {
+  console.log('\n' + chalk.bold.underline('Migration Report'));
+  console.log(`${chalk.green('✔')} Files processed: ${report.filesProcessed}`);
+  console.log(`${chalk.green('✔')} Classes replaced: ${report.classesReplaced}`);
+
+  if (report.warnings.length > 0) {
+    console.log('\n' + chalk.yellow.bold('Warnings:'));
+    const uniqueWarnings = [...new Set(report.warnings.map(w => `${w.file}: ${w.class}`))];
+    uniqueWarnings.slice(0, 10).forEach(w => console.log(`  ${chalk.yellow('!')} ${w}`));
+    if (uniqueWarnings.length > 10) {
+      console.log(`  ... and ${uniqueWarnings.length - 10} more`);
+    }
+  }
+
+  if (report.errors.length > 0) {
+    console.log('\n' + chalk.red.bold('Errors:'));
+    report.errors.slice(0, 10).forEach(e => console.log(`  ${chalk.red('✘')} ${e.file}: ${e.error}`));
+    if (report.errors.length > 10) {
+      console.log(`  ... and ${report.errors.length - 10} more`);
+    }
+  }
+
+  console.log('\n' + chalk.green.bold('Migration completed successfully! 🎉'));
+}