apexcss-cli 0.1.0

package/README.md

@@ -0,0 +1,284 @@
+# @apexcss/cli
+
+ApexCSS CLI - A powerful build tool for with automatic framework detection and seamless integration.
+
+## What is ApexCSS CLI?
+
+ApexCSS CLI helps you build and customize your own CSS utility framework. It provides:
+
+- **Automatic Framework Detection** - Detects your project setup (React, Vue, Next.js, etc.) and configures accordingly
+- **Layered CSS Generation** - Build only what you need (base, utilities, themes)
+- **Watch Mode** - Automatically rebuild on configuration changes
+- **Smart Configuration** - TypeScript/JavaScript config files with validation
+- **Framework Integration** - Automatically adds CSS imports to your framework's entry file
+
+## Installation
+
+```bash
+npm install -g @apexcss/cli
+# or use without installing
+npx @apexcss/cli <command>
+```
+
+## Quick Start
+
+```bash
+# 1. Initialize with automatic framework detection
+apexcss init
+
+# 2. Build your CSS
+apexcss build
+
+# 3. During development, watch for changes
+apexcss watch
+```
+
+## Automatic Framework Detection
+
+ApexCSS CLI automatically detects your project framework and configures the integration:
+
+| Framework | Detection Method | Auto-Import |
+|-----------|-----------------|-------------|
+| Next.js | `next` in dependencies | ✅ Added to globals.css |
+| React | `react` in dependencies | ✅ Added to main entry file |
+| Vue | `vue` in dependencies | ✅ Added to main.ts/js |
+| Angular | `@angular/core` in dependencies | ✅ Added to styles.css |
+| Svelte | `svelte` in dependencies | ✅ Added to main entry file |
+| Astro | `astro` in dependencies | ✅ Added to Layout.astro |
+| Nuxt | `nuxt` in dependencies | ✅ Instructions for nuxt.config.ts |
+| Vanilla | Default fallback | ✅ Added to main.js/ts |
+
+Run `apexcss doctor` to see what was detected in your project.
+
+## Usage
+
+### Initialize Configuration
+
+```bash
+# Interactive mode with prompts
+apexcss init
+
+# Skip interactive prompts
+apexcss init --interactive=false
+
+# Specify framework explicitly
+apexcss init --framework=react
+
+# Custom output directory
+apexcss init --output=./src/styles
+```
+
+### Build CSS
+
+```bash
+# Build complete CSS (base + utilities + themes)
+apexcss build
+
+# Build specific layers only
+apexcss build --layer base
+apexcss build --layer utilities
+apexcss build --layer themes
+apexcss build --layer base,themes
+
+# Production build with minification
+apexcss build --minify
+
+# Generate source maps
+apexcss build --sourcemap
+
+# Output as SCSS instead of CSS
+apexcss build --format=scss
+```
+
+### Watch Mode
+
+```bash
+# Watch config file for changes and auto-rebuild
+apexcss watch
+
+# Watch with custom config path
+apexcss watch --config=./custom.config.js
+```
+
+### Diagnostics
+
+```bash
+# Run system diagnostics
+apexcss doctor
+```
+
+## CLI Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-c, --config <path>` | Config file path | `./apex.config.js` |
+| `-o, --output <dir>` | Output directory | `./dist/` |
+| `-l, --layer <layers>` | Build specific layers | `all` |
+| `--minify` | Minify output CSS | `false` |
+| `--sourcemap` | Generate source maps | `false` |
+| `--format <format>` | Output format | `css` |
+| `--framework` | Specify framework | `auto-detect` |
+| `--interactive` | Interactive prompts | `true` |
+| `--import` | Add imports to entry files | `true` |
+
+## Configuration
+
+Create an `apex.config.js` file in your project root:
+
+```javascript
+export default {
+  // Feature toggles - enable/disable utility categories
+  features: {
+    display: true,
+    flexbox: true,
+    grid: true,
+    positioning: true,
+    visibility: true,
+    spacing: true,
+    typography: true,
+    colors: true,
+    backgrounds: true,
+    borders: true,
+    shadows: true,
+    opacity: true,
+    transitions: true,
+    transforms: true,
+    animations: true
+  },
+
+  // Breakpoints
+  breakpoints: {
+    sm: '320px',
+    md: '768px',
+    lg: '1024px',
+    xl: '1280px'
+  },
+
+  // Custom colors using OKLCH color space
+  colors: {
+    primary: {
+      hue: 250,
+      chroma: 0.2,
+      lightnessScale: {
+        50: 96, 100: 90, 200: 85, 300: 78, 400: 70,
+        500: 65, 600: 55, 700: 45, 800: 35, 900: 25, 950: 18
+      }
+    },
+    secondary: {
+      hue: 180,
+      chroma: 0.15,
+      lightnessScale: {
+        50: 96, 100: 90, 200: 85, 300: 78, 400: 70,
+        500: 65, 600: 55, 700: 45, 800: 35, 900: 25, 950: 18
+      }
+    }
+  },
+
+  // Spacing scale
+  spacing: {
+    '0': '0px',
+    '1': '0.25rem',
+    '2': '0.5rem',
+    '4': '1rem',
+    '8': '2rem',
+    '16': '4rem'
+  }
+};
+```
+
+## Peer Dependencies
+
+This CLI requires `apexcss` to be installed in your project:
+
+```bash
+npm install apexcss
+```
+
+Optional peer dependencies:
+- `vite` - For building CSS (recommended)
+- `sass` - For SCSS support
+
+## Development
+
+### Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/chris-briddock/apex-cli.git
+cd apex-cli
+
+# Install dependencies
+npm install
+```
+
+### Testing
+
+```bash
+# Run all tests
+npm test
+
+# Run tests with coverage (LCOV report)
+npm run test:coverage
+
+# View coverage as text in terminal
+npm run test:coverage:text
+
+# Generate HTML coverage report
+npm run test:coverage:html
+# Then open coverage/index.html in your browser
+
+# Run tests in watch mode
+npm run test:watch
+
+# Run unit tests only
+npm run test:unit
+```
+
+### Code Quality
+
+```bash
+# Run ESLint
+npm run lint
+
+# Fix auto-fixable linting issues
+npm run lint:fix
+```
+
+### Coverage Summary
+
+Current test coverage:
+
+| Module | Statements | Branches | Functions | Lines |
+|--------|-----------|----------|-----------|-------|
+| cli/utils/config-loader.js | 99% | 95% | 100% | 99% |
+| cli/utils/logger.js | 100% | 100% | 100% | 100% |
+| cli/utils/framework-detector.js | 95% | 94% | 100% | 95% |
+| cli/commands/doctor.js | 82% | 79% | 100% | 82% |
+| cli/commands/watch.js | 67% | 100% | 83% | 67% |
+| cli/commands/build.js | 54% | 100% | 67% | 54% |
+| cli/commands/init.js | 41% | 96% | 50% | 41% |
+
+**Total: 76% statements, 92% branches, 86% functions**
+
+## How It Works
+
+1. **Initialization** (`apexcss init`):
+   - Detects your project framework from package.json
+   - Creates a starter config file (apex.config.js)
+   - Optionally adds CSS import to your framework's entry file
+   - Sets up .gitignore for output directory
+
+2. **Build Process** (`apexcss build`):
+   - Reads your configuration
+   - Generates SCSS based on enabled features
+   - Uses Vite to compile CSS (if available)
+   - Outputs minified CSS (with optional source maps)
+
+3. **Watch Mode** (`apexcss watch`):
+   - Monitors your config file for changes
+   - Automatically rebuilds on change
+   - Handles concurrent changes gracefully
+
+## License
+
+MIT

package/bin/apexcss.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+
+/**
+ * ApexCSS CLI
+ *
+ * Usage:
+ *   apexcss init              Initialize configuration
+ *   apexcss build             Build custom CSS
+ *   apexcss watch             Watch for changes
+ *   apexcss doctor            Check system setup
+ *
+ * Options:
+ *   -c, --config <path>       Config file path (default: ./apex.config.js)
+ *   -o, --output <dir>        Output directory (default: ./src/apexcss/)
+ *   --minify                  Minify output CSS
+ *   --sourcemap               Generate source maps
+ *   -v, --version             Show version
+ *   -h, --help                Show help
+ */
+
+import { cli } from '../cli/index.js';
+
+cli(process.argv);

package/cli/commands/build.js

@@ -0,0 +1,376 @@
+/**
+ * Build command - Generate custom CSS from configuration
+ */
+
+import { writeFileSync, existsSync, mkdirSync, cpSync, rmSync, readFileSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadConfig } from '../utils/config-loader.js';
+import { logger } from '../utils/logger.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Import the config builder
+import { generateSCSS } from '../utils/config-builder.js';
+
+/**
+ * Valid layer names
+ */
+const VALID_LAYERS = ['base', 'utilities', 'themes'];
+
+/**
+ * Parse layers option and return array of layers to build
+ * @param {string} layersOption - Comma-separated layer names or 'all'
+ * @returns {string[]} - Array of layer names
+ */
+export function parseLayers(layersOption) {
+  if (!layersOption || layersOption === 'all') {
+    return ['base', 'utilities', 'themes'];
+  }
+
+  const requested = layersOption.split(',').map(l => l.trim().toLowerCase());
+  const invalid = requested.filter(l => !VALID_LAYERS.includes(l));
+
+  if (invalid.length > 0) {
+    throw new Error(`Invalid layer(s): ${invalid.join(', ')}. Valid options: ${VALID_LAYERS.join(', ')}`);
+  }
+
+  return requested;
+}
+
+/**
+ * Generate entry SCSS content based on selected layers
+ * @param {string[]} layers - Array of layer names to include
+ * @returns {string} - SCSS content for entry file
+ */
+export function generateLayerEntry(layers) {
+  const lines = [
+    '// ============================================================================',
+    '// ApexCSS - Layered Build Entry Point',
+    '// ============================================================================',
+    '// Auto-generated based on --layer option',
+    '// ============================================================================',
+    ''
+  ];
+
+  // Always include config
+  lines.push('@use \'config\';');
+
+  // Include selected layers
+  for (const layer of layers) {
+    lines.push(`@use '${layer}';`);
+  }
+
+  lines.push('', '// ============================================================================', '// End of Entry Point', '// ============================================================================', '');
+
+  return lines.join('\n');
+}
+
+/**
+ * Get source directories needed for selected layers
+ * @param {string[]} layers - Array of layer names
+ * @returns {string[]} - Array of source directory names
+ */
+export function getSourceEntriesForLayers(layers) {
+  const entries = new Set(['config']);
+
+  for (const layer of layers) {
+    entries.add(layer);
+    switch (layer) {
+    case 'utilities':
+      entries.add('mixins');
+      entries.add('plugins');
+      break;
+    case 'base':
+      entries.add('mixins');
+      break;
+    case 'themes':
+      entries.add('mixins');
+      break;
+    }
+  }
+
+  return Array.from(entries);
+}
+
+/**
+ * Setup build environment
+ * @param {string} outputDir - Output directory path
+ * @returns {string} - Temp directory path
+ */
+export function setupBuildEnvironment(outputDir) {
+  const tempDir = resolve(outputDir, '.apexcss-build');
+  if (existsSync(tempDir)) {
+    rmSync(tempDir, { recursive: true });
+  }
+  mkdirSync(tempDir, { recursive: true });
+  return tempDir;
+}
+
+/**
+ * Determine source directory
+ * @param {string} cwd - Current working directory
+ * @returns {string} - Source directory path
+ */
+export function determineSourceDir(cwd) {
+  // Look for apexcss source in user's node_modules
+  const nodeModulesSrcDir = resolve(cwd, 'node_modules', 'apexcss', 'src');
+
+  if (!existsSync(nodeModulesSrcDir)) {
+    throw new Error(
+      'Could not find ApexCSS source files. ' +
+      'Please ensure apexcss is installed: npm install apexcss'
+    );
+  }
+
+  return nodeModulesSrcDir;
+}
+
+/**
+ * Write configuration files to temp directory
+ * @param {string} tempDir - Temp directory path
+ * @param {string} scssContent - SCSS content to write
+ */
+export function writeConfigFiles(tempDir, scssContent) {
+  const configDir = resolve(tempDir, 'config');
+  mkdirSync(configDir, { recursive: true });
+  writeFileSync(resolve(configDir, '_custom-config.scss'), scssContent);
+  writeFileSync(
+    resolve(configDir, '_index.scss'),
+    '// Auto-generated config entry\n@forward \'custom-config\';\n'
+  );
+}
+
+/**
+ * Find generated CSS file in temp directory
+ * @param {string} tempDir - Temp directory path
+ * @returns {string | undefined} - CSS file path or undefined
+ */
+export function findGeneratedCss(tempDir) {
+  const candidates = ['apex.css', 'style.css'];
+  for (const file of candidates) {
+    const fullPath = resolve(tempDir, file);
+    if (existsSync(fullPath)) {
+      return fullPath;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Copy source map if generated
+ * @param {string} tempDir - Temp directory path
+ * @param {string} outputDir - Output directory path
+ */
+export function copySourceMap(tempDir, outputDir) {
+  const mapPath = resolve(tempDir, 'apex.css.map');
+  if (existsSync(mapPath)) {
+    const mapContent = readFileSync(mapPath, 'utf-8');
+    writeFileSync(resolve(outputDir, 'apex.css.map'), mapContent);
+    logger.success('Source map generated');
+  }
+}
+
+/**
+ * Build CSS from configuration
+ * @param {object} options - Command options
+ * @returns {Promise<void>}
+ */
+export async function buildCommand(options) {
+  const cwd = process.cwd();
+  const startTime = Date.now();
+
+  logger.header('Building ApexCSS');
+  logger.newline();
+
+  // Load configuration
+  logger.info('Loading configuration...');
+  const config = loadConfig(options.configPath);
+
+  // Resolve output directory
+  const outputDir = resolve(cwd, options.outputDir);
+
+  // Ensure output directory exists
+  if (!existsSync(outputDir)) {
+    mkdirSync(outputDir, { recursive: true });
+  }
+
+  // Generate SCSS from config
+  logger.info('Generating SCSS configuration...');
+  const scssContent = generateSCSS(config);
+
+  // Determine source directory
+  const sourceDir = determineSourceDir(cwd);
+
+  if (!existsSync(sourceDir)) {
+    throw new Error(
+      'Could not find ApexCSS source files. ' +
+      'Please ensure apexcss is installed: npm install apexcss'
+    );
+  }
+
+  // Parse layers option
+  const layers = parseLayers(options.layers);
+  logger.info(`Building layers: ${layers.join(', ')}`);
+
+  // Setup build environment
+  const tempDir = setupBuildEnvironment(outputDir);
+
+  // Copy source files to temp directory based on selected layers
+  logger.info('Preparing build environment...');
+  copySourceFiles(sourceDir, tempDir, layers);
+
+  // Write custom config
+  writeConfigFiles(tempDir, scssContent);
+
+  // Generate layer-specific entry file
+  const entryContent = generateLayerEntry(layers);
+  writeFileSync(resolve(tempDir, 'apex-entry.scss'), entryContent);
+
+  // Build using Vite programmatically
+  logger.info('Compiling CSS...');
+
+  try {
+    await runViteBuild(tempDir, options, outputDir, layers, scssContent);
+
+    const duration = Date.now() - startTime;
+    logger.newline();
+    logger.success(`Build completed in ${duration}ms`);
+
+  } catch (error) {
+    // Clean up temp directory on error
+    if (existsSync(tempDir)) {
+      rmSync(tempDir, { recursive: true });
+    }
+    throw error;
+  }
+}
+
+/**
+ * Run Vite build
+ * @param {string} tempDir - Temp directory path
+ * @param {object} options - Build options
+ * @param {string} outputDir - Output directory path
+ * @param {string[]} layers - Array of layer names
+ * @param {string} scssContent - SCSS content
+ * @returns {Promise<void>}
+ */
+async function runViteBuild(tempDir, options, outputDir, layers, scssContent) {
+  const { build } = await import('vite');
+  const cwd = process.cwd();
+
+  // Look for postcss config in user's project
+  const userPostcssConfig = resolve(cwd, 'postcss.config.js');
+  const apexcssPostcssConfig = resolve(cwd, 'node_modules', 'apexcss', 'postcss.config.js');
+
+  let postcssConfig;
+  if (existsSync(userPostcssConfig)) {
+    postcssConfig = userPostcssConfig;
+  } else if (existsSync(apexcssPostcssConfig)) {
+    postcssConfig = apexcssPostcssConfig;
+  } else {
+    postcssConfig = undefined;
+  }
+
+  await build({
+    configFile: false,
+    css: {
+      postcss: postcssConfig
+    },
+    build: {
+      cssCodeSplit: false,
+      sourcemap: options.sourcemap,
+      minify: options.minify ? 'esbuild' : false,
+      outDir: tempDir,
+      rollupOptions: {
+        input: {
+          apex: resolve(tempDir, 'apex-entry.scss')
+        },
+        output: {
+          entryFileNames: '[name].js',
+          assetFileNames: () => '[name][extname]'
+        }
+      }
+    }
+  });
+
+  // Get output filenames based on layers
+  const { filename, description } = getOutputFilenames(layers);
+
+  // Copy CSS from temp to output
+  const generatedCssPath = findGeneratedCss(tempDir);
+  const finalCssPath = resolve(outputDir, `${filename}.css`);
+
+  if (!generatedCssPath) {
+    throw new Error('CSS file was not generated');
+  }
+
+  const cssContent = readFileSync(generatedCssPath, 'utf-8');
+  writeFileSync(finalCssPath, cssContent);
+
+  // Calculate file size
+  const contentBytes = Buffer.byteLength(cssContent, 'utf8');
+  const sizeKB = (contentBytes / 1024).toFixed(2);
+
+  const filePath = logger.path(`${filename}.css`);
+  logger.success(`Built: ${filePath} (${sizeKB} KB) [${description}]`);
+
+  // Copy source map if generated
+  if (options.sourcemap) {
+    const mapSource = resolve(tempDir, 'apex.css.map');
+    const mapDest = resolve(outputDir, `${filename}.css.map`);
+    if (existsSync(mapSource)) {
+      const mapContent = readFileSync(mapSource, 'utf-8');
+      writeFileSync(mapDest, mapContent);
+      logger.success('Source map generated');
+    }
+  }
+
+  // Output SCSS if requested
+  if (options.format === 'scss' || options.format === 'both') {
+    writeFileSync(resolve(outputDir, `${filename}.scss`), scssContent);
+    const scssPath = logger.path(`${filename}.scss`);
+    logger.success(`Generated: ${scssPath}`);
+  }
+
+  // Clean up temp directory
+  rmSync(tempDir, { recursive: true });
+}
+
+/**
+ * Copy source files to temp directory
+ * @param {string} sourceDir - Source directory
+ * @param {string} tempDir - Temp directory
+ * @param {string[]} layers - Array of layer names to include
+ */
+function copySourceFiles(sourceDir, tempDir, layers) {
+  const entries = getSourceEntriesForLayers(layers);
+
+  for (const entry of entries) {
+    const sourcePath = resolve(sourceDir, entry);
+    const destPath = resolve(tempDir, entry);
+
+    if (existsSync(sourcePath)) {
+      cpSync(sourcePath, destPath, { recursive: true });
+    }
+  }
+}
+
+/**
+ * Generate filenames based on selected layers
+ * @param {string[]} layers - Array of layer names
+ * @returns {object} - Object with filename and description
+ */
+function getOutputFilenames(layers) {
+  if (layers.length === 3) {
+    return { filename: 'apex', description: 'complete framework' };
+  }
+
+  if (layers.length === 1) {
+    return { filename: layers[0], description: `${layers[0]} layer` };
+  }
+
+  const layerSuffix = layers.join('-');
+  return { filename: layerSuffix, description: `${layers.join(' + ')} layers` };
+}