# @magmonium/cli

A powerful and extensible asset compilation tool that can be shared across multiple projects. This tool **intelligently processes all files** in your `mag_assets/` folder - compiling when possible, copying when needed.

## Project Structure

This tool follows a simple but powerful convention:

- **Source files** go in `mag_assets/` folders
- **Compiled files** are output to `assets/` folders
- Files are **automatically compiled** if a compiler exists, otherwise **copied directly**

```
project/
├── mag_assets/          # Source files (tracked in Git)
│   ├── icons/          # SVG source files → compiled to JSON
│   ├── styles/         # SCSS/CSS source files → compiled
│   ├── i18n/          # Translation source files → compiled
│   ├── images/        # Image files → copied as-is
│   ├── docs/          # Documentation → copied as-is
│   └── ...            # Any other files → copied as-is
├── assets/             # Compiled files (ignored in Git)
│   ├── icons/         # Compiled SVG assets
│   ├── styles/        # Compiled CSS/SCSS
│   ├── i18n/         # Compiled translations
│   ├── images/       # Copied images
│   ├── docs/         # Copied documentation
│   └── ...           # All other copied files
└── mag-build.config.js # Build configuration (optional)
```

## Quick Start

### One Command Does Everything

```bash
# Install globally
npm install -g @magmonium/cli

# Build everything from mag_assets/ to assets/
mag-build build

# That's it! The tool will:
# ✅ Compile SVG files to JSON + sprite sheets
# ✅ Compile SCSS/CSS files to optimized CSS
# ✅ Compile translation files to flattened JSON + TypeScript definitions
# ✅ Copy all other files (images, docs, etc.) as-is
```

### Local Installation

```bash
# Install as dependency
npm install @magmonium/cli

# Add to package.json
{
  "scripts": {
    "build": "mag-build build",
    "dev": "mag-build build --watch"
  }
}

# Run
npm run build
```

## Features

- 🚀 **One Command**: Single `build` command handles everything intelligently
- 🎨 **SVG Compilation**: Convert SVG files to JSON with sprite sheet generation
- 🎭 **Theme Compilation**: Process TypeScript/SCSS/CSS theme files into JSON and CSS formats
- 🌍 **Translation Compilation**: Handle i18n files with TypeScript definitions
- 📁 **Smart Copying**: Copy files that don't need compilation automatically
- 👀 **Watch Mode**: Real-time compilation on file changes
- 🔧 **Zero Config**: Works out of the box with sensible defaults
- 🔧 **Configurable**: Optional config file for advanced customization
- 📦 **NPM Package**: Easy installation and sharing across projects
- 🌐 **Global CLI**: Can be installed globally for system-wide access
-
-
- 📋 **Tabs Compilation**: Process tab configurations with smart navs/options reference resolution

## CLI Commands

```bash
# Build everything (compile + copy)
mag-build build

# Watch for changes
mag-build build --watch

# Only copy files (skip compilation)
mag-build build --copy-only
```

## Package.json Integration

### Simple Setup (Recommended)

```json
{
  "scripts": {
    "build": "mag-build build",
    "dev": "mag-build build --watch"
  }
}
```

### Complete Setup

```json
{
  "scripts": {
    "build": "mag-build build",
    "dev": "mag-build build --watch",
    "copy": "mag-build build --copy-only"
  }
}
```

## Configuration (Optional)

The tool works perfectly with **zero configuration**, but you can customize it:

```javascript
// mag-build.config.js
module.exports = {
  svg: {
    inputPaths: ['./mag_assets/icons'],
    outputPath: './assets',
    spriteSheet: true,
    optimize: true,
  },
  theme: {
    inputPaths: ['./mag_assets/theme'],
    outputPath: './assets/theme',
    format: 'json',
    generateCSS: true,
  },
  i18n: {
    inputPaths: ['./mag_assets/i18n'],
    outputPath: './assets/i18n',
    defaultLocale: 'en',
    supportedLocales: ['en', 'es', 'fr'],
  },
  copy: {
    inputPaths: ['./mag_assets'],
    outputPath: './assets',
    patterns: ['**/*.png', '**/*.jpg', '**/*.pdf'], // Specific files only
    exclude: ['**/*.svg', '**/*.scss', '**/*.json'], // Exclude compiled files
    overwrite: true,
  },
};
```

## How It Works

1. **Scans** `mag_assets/` for all files
2. **Compiles** files with matching compilers:
   - `.svg` files → JSON + sprite sheets
   - `.scss`, `.sass`, `.css` files → optimized CSS
   - `.json`, `.yaml`, `.yml` translation files → flattened JSON + TypeScript definitions
3. **Copies** all other files directly to `assets/`
4. **Maintains** directory structure automatically

## File Type Handling

| File Type                     | Action  | Output                                       |
| ----------------------------- | ------- | -------------------------------------------- |
| `*.svg`                       | Compile | JSON + sprite sheet                          |
| `*.ts` (in theme/)            | Compile | JSON + CSS (from TypeScript themes)          |
| `*.scss`, `*.sass`, `*.css`   | Compile | Optimized CSS                                |
| `*.json`, `*.yaml` (in i18n/) | Compile | Flattened JSON + TypeScript definitions      |
| `*.yaml`, `*.yml` (in tabs/)  | Compile | Tab configurations with reference resolution |
| `*.yaml`, `*.yml` (in navs/)  | Compile | Navigation options for tab references        |
| `*.png`, `*.jpg`, `*.gif`     | Copy    | Unchanged                                    |
| `*.md`, `*.txt`, `*.pdf`      | Copy    | Unchanged                                    |
| All other files               | Copy    | Unchanged                                    |

## Tabs Compilation

The tabs compiler processes YAML files in the `mag_assets/tabs/` directory and generates JSON tab configurations with intelligent reference resolution.

### Basic Tab Configuration

```yaml
# mag_assets/tabs/main-tabs.yaml
id: main-tabs
label: Main Navigation Tabs
orientation: horizontal
variant: underline
size: md
colorScheme: blue
isLazy: true
defaultIndex: 0
tabs:
  - id: home-tab
    label: Home
    icon:
      name: home
      color: blue
    link: /home
    description: Home page tab
  - id: about-tab
    label: About
    icon:
      name: info
      color: green
    link: /about
    description: About page tab
```

### Smart Reference Resolution (navs → options fallback)

The tabs compiler intelligently resolves tab references with a **navs-first, options-fallback** strategy:

1. **Primary**: Looks in `mag_assets/navs/` directory first
2. **Fallback**: Falls back to `mag_assets/options/` directory if not found in navs

#### Navigation Items (navs/)

```yaml
# mag_assets/navs/store-navs.yml
- - id: products
    label: Products
    icon:
      name: package
      color: blue
    link: /store/products
    description: Browse all products
  - id: categories
    label: Categories
    icon:
      name: grid
      color: green
    link: /store/categories
    description: Product categories
```

#### Tab Configuration with References

**File-Level Reference (Recommended):**

```yaml
# mag_assets/tabs/store-tabs.yaml
id: store-tabs
label: Store Navigation
tabs: store # References entire store.yml file
color: mm # Additional styling properties
variant: pills
align: center
```

**Individual References:**

```yaml
# mag_assets/tabs/mixed-tabs.yaml
id: mixed-tabs
label: Mixed Navigation
tabs:
  - '@store-navs:products' # Resolves from navs directory (primary)
  - '@store-options:deals' # Falls back to options directory
  - id: inline-tab
    label: Custom Tab
    link: /custom
```

#### Generated Output

```json
{
  "id": "store-tabs",
  "label": "Store Navigation",
  "tabs": [
    {
      "id": "products",
      "label": "Products",
      "icon": { "name": "package", "color": "blue" },
      "link": "/store/products",
      "description": "Browse all products"
    },
    {
      "id": "deals",
      "label": "Special Deals",
      "icon": { "name": "percent", "color": "red" },
      "link": "/store/deals",
      "description": "Limited time offers"
    },
    {
      "id": "inline-tab",
      "label": "Custom Tab",
      "link": "/custom"
    }
  ]
}
```

### Reference Formats

- `tabs: filename` - References entire file from navs/ first, then options/ (file-level reference)
- `@filename:option-id` - References an option by ID from the specified file
- `@filename:0:2` - References using array indices (advanced usage)
- `filename` - References all options from the specified file

### Configuration Properties

Tab configurations support the following properties:

```yaml
id: string # Required: Unique identifier
label: string # Required: Display label
tabs: string | array # Required: File reference or tab array
orientation: horizontal | vertical # Optional: Tab layout
variant: default | underline | pills | enclosed | soft-rounded # Optional: Visual style
size: sm | md | lg # Optional: Size variation
colorScheme: string # Optional: Color scheme
color: string # Optional: Custom color
align: left | center | right # Optional: Alignment
isLazy: boolean # Optional: Lazy loading
defaultIndex: number # Optional: Default active tab
onChange: string # Optional: Change handler
```

### Directory Structure

```
mag_assets/
├── tabs/           # Tab configurations
│   ├── main-tabs.yaml
│   └── store-tabs.yaml
├── navs/           # Navigation items (primary source)
│   ├── main-navs.yml
│   └── store-navs.yml
└── options/        # General options (fallback source)
    ├── store-options.yml
    └── form-options.yml
```

### Benefits

- **Simple File References**: Use `tabs: filename` for clean, simple configuration
- **Logical Separation**: Keep navigation items separate from general options
- **Smart Fallback**: Automatically falls back to options if navs don't exist
- **Backward Compatible**: Existing `@options:...` references continue to work
- **Flexible**: Supports file-level references, individual references, and inline definitions
- **Enhanced Styling**: Additional properties like `color` and `align` for custom styling

## Using in Multiple Projects

### Global Installation (Recommended)

```bash
# Install once globally
npm install -g @magmonium/cli

# Use in any project
cd ~/project-a && mag-build build
cd ~/project-b && mag-build build
```

### Project-Specific Installation

```bash
# Install per project
npm install @magmonium/cli

# Use with npx
npx mag-build build
```

## Benefits

1. **Zero Mental Overhead**: Just run `build` and everything works
2. **Intelligent Processing**: Compiles when possible, copies otherwise
3. **No Configuration Required**: Works out of the box with sensible defaults
4. **Clear Separation**: Source files (`mag_assets/`) vs generated files (`assets/`)
5. **Version Control Friendly**: Only source files are tracked
6. **Build Process Consistency**: Same `mag_assets/` → `assets/` workflow everywhere
7. **Flexibility**: Handles any file type - compiles or copies as appropriate

## Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for your changes
4. Ensure all tests pass
5. Submit a pull request

## License

MIT License - see LICENSE file for details.