@princevish/font-converter-cli/README.md

A powerful CLI tool to convert WOFF and WOFF2 fonts to TTF format with recursive directory scanning support

# Font Converter CLI

A powerful command-line tool to convert WOFF and WOFF2 font files to TTF format with support for recursive directory scanning.

## Features

- ✅ Convert WOFF to TTF
- ✅ Convert WOFF2 to TTF  
- ✅ Single file conversion
- ✅ Batch directory conversion
- ✅ **Recursive subdirectory scanning**
- ✅ Maintains directory structure in output
- ✅ Comprehensive file validation
- ✅ Detailed error handling
- ✅ Verbose logging option
- ✅ Font validation using FontKit
- ✅ Cross-platform support (Windows, macOS, Linux)

## Quick Start

```bash
# Install globally from npm
npm install -g @princevish/font-converter-cli

# Or install locally for development
npm install

# Convert a single font file
font-converter-cli convert input.woff

# Batch convert with recursive search
font-converter-cli batch ./fonts --recursive --verbose

# Get help
font-converter-cli --help
```

## Installation

### Global Installation (Recommended)

```bash
# Install globally from npm
npm install -g @princevish/font-converter-cli

# Verify installation
font-converter-cli --version
font-converter-cli --help
```

### Local Development Installation

```bash
# Clone repository
git clone https://github.com/princevish/font-converter-cli.git
cd font-converter-cli

# Install dependencies
npm install

# Test the CLI
node bin/cli.js --help

# Link for global use (optional)
npm link
```

### Requirements

- **Node.js**: >= 14.0.0
- **npm**: >= 6.0.0
- **Operating System**: Windows, macOS, or Linux

## Usage

### Basic Commands

#### Convert a Single Font File

```bash
# Convert WOFF to TTF
font-converter-cli convert input.woff

# Convert WOFF2 to TTF
font-converter-cli convert input.woff2

# Specify output file
font-converter-cli convert input.woff -o output.ttf

# Enable verbose logging
font-converter-cli convert input.woff --verbose
```

#### Batch Convert Multiple Files

```bash
# Convert all WOFF/WOFF2 files in a directory
font-converter-cli batch ./fonts

# Specify output directory
font-converter-cli batch ./fonts -o ./converted

# Search subdirectories recursively
font-converter-cli batch ./fonts -o ./converted --recursive

# Enable verbose logging
font-converter-cli batch ./fonts --verbose
```

### Command Line Options

#### `convert` command

Convert a single font file from WOFF or WOFF2 to TTF.

```bash
font-converter-cli convert <input> [options]
```

**Arguments:**
- `<input>` - Path to the input font file (WOFF or WOFF2)

**Options:**
- `-o, --output <output>` - Specify output TTF file path (default: same directory as input)
- `-v, --verbose` - Enable verbose logging
- `-h, --help` - Display help for the convert command

**Examples:**
```bash
# Basic conversion
font-converter-cli convert myFont.woff

# With custom output path
font-converter-cli convert myFont.woff -o ./converted/myFont.ttf

# With verbose output
font-converter-cli convert myFont.woff2 --verbose
```

#### `batch` command

Convert multiple font files in a directory.

```bash
font-converter-cli batch <directory> [options]
```

**Arguments:**
- `<directory>` - Directory containing WOFF/WOFF2 files

**Options:**
- `-o, --output-dir <dir>` - Output directory for converted TTF files (default: same as input)
- `-r, --recursive` - Search subdirectories recursively for font files
- `-v, --verbose` - Enable verbose logging
- `-h, --help` - Display help for the batch command

**Examples:**
```bash
# Convert all fonts in current directory
font-converter-cli batch .

# Convert with output directory
font-converter-cli batch ./source-fonts -o ./converted-fonts

# Recursive search in subdirectories
font-converter-cli batch ./fonts --recursive --verbose

# Verbose batch conversion
font-converter-cli batch ./fonts --verbose
```

### Global Options

- `-V, --version` - Display version number
- `-h, --help` - Display help information

## Common Use Cases

### 1. Web Font Migration
Convert web fonts to TTF for desktop applications:
```bash
font-converter-cli batch ./web-assets/fonts --recursive -o ./desktop-fonts --verbose
```

### 2. Development Workflow
Convert downloaded fonts for local development:
```bash
font-converter-cli convert downloaded-font.woff2 -o ./src/assets/fonts/font.ttf
```

### 3. Font Library Organization
Process complex font directory structures:
```bash
# Your fonts are organized like this:
# fonts/
# ├── family1/
# │   ├── woff/
# │   └── woff2/
# ├── family2/
# │   ├── woff/
# │   └── woff2/
# └── ...

# Convert all with preserved structure:
font-converter-cli batch ./fonts --recursive -o ./converted-fonts
```

### 4. Selective Conversion
Convert specific font formats or families:
```bash
# Convert only WOFF files from one family
font-converter-cli batch ./fonts/poppins/woff -o ./converted

# Convert only WOFF2 files from one family
font-converter-cli batch ./fonts/poppins/woff2 -o ./converted
```

## Supported Formats

### Input Formats
- **WOFF** (.woff) - Web Open Font Format
- **WOFF2** (.woff2) - Web Open Font Format 2.0

### Output Format
- **TTF** (.ttf) - TrueType Font

## Examples

### Single File Conversion

```bash
# Convert a WOFF file
$ font-converter-cli convert OpenSans-Regular.woff
✅ Successfully converted to: OpenSans-Regular.ttf

# Convert with verbose output
$ font-converter-cli convert OpenSans-Bold.woff2 --verbose
Detected format: woff2
Input file size: 45623 bytes
Converting WOFF2 to TTF...
Font family: Open Sans
Font style: Bold
Number of glyphs: 937
Output file size: 87234 bytes
✅ Successfully converted to: OpenSans-Bold.ttf
```

### Batch Conversion

```bash
# Convert all fonts in a directory
$ font-converter-cli batch ./web-fonts --verbose
Found 5 font files to convert
Converting: OpenSans-Regular.woff
✅ OpenSans-Regular.woff -> OpenSans-Regular.ttf
Converting: OpenSans-Bold.woff
✅ OpenSans-Bold.woff -> OpenSans-Bold.ttf
Converting: OpenSans-Italic.woff2
✅ OpenSans-Italic.woff2 -> OpenSans-Italic.ttf
Converting: OpenSans-BoldItalic.woff2
✅ OpenSans-BoldItalic.woff2 -> OpenSans-BoldItalic.ttf
Converting: Roboto-Regular.woff
✅ Roboto-Regular.woff -> Roboto-Regular.ttf
✅ Successfully converted 5 files
```

### Recursive Directory Search

```bash
# Convert fonts from nested directories
$ font-converter-cli batch ./fonts --recursive --verbose
Recursive mode: searching subdirectories
Found 78 font files to convert
Files found in subdirectories:
  poppins/woff/poppins-regular.woff
  poppins/woff2/poppins-bold.woff2
  roboto/woff/roboto-medium.woff
  ...
Converting: poppins/woff/poppins-regular.woff
✅ poppins/woff/poppins-regular.woff -> poppins/woff/poppins-regular.ttf
Converting: poppins/woff2/poppins-bold.woff2
✅ poppins/woff2/poppins-bold.woff2 -> poppins/woff2/poppins-bold.ttf
...
✅ Successfully converted 31 files
⚠️  Failed to convert 47 files
```

### Error Handling

The tool provides detailed error messages for various scenarios:

```bash
# File not found
$ font-converter-cli convert nonexistent.woff
❌ Conversion failed: Validation failed: File not found: nonexistent.woff

# Invalid format
$ font-converter-cli convert document.pdf
❌ Conversion failed: Validation failed: Unsupported file extension: .pdf. Supported formats: .woff, .woff2

# Permission denied
$ font-converter-cli convert protected.woff -o /system/fonts/
❌ Conversion failed: Validation failed: Permission denied: cannot write to /system/fonts/
```

## Technical Details

### Dependencies

- **commander** - Command line argument parsing and CLI interface
- **fontkit** - Font parsing, validation, and metadata extraction
- **wawoff2** - High-performance WOFF2 decompression

### Conversion Algorithms

#### WOFF to TTF Process:
1. ✅ **Signature Validation** - Verifies WOFF magic number (0x774F4646)
2. ✅ **Header Parsing** - Extracts font metadata and table information
3. ✅ **Decompression** - Uses zlib to decompress table data
4. ✅ **TTF Reconstruction** - Rebuilds proper TTF structure with correct offsets
5. ✅ **Validation** - Verifies output integrity with FontKit

#### WOFF2 to TTF Process:
1. ✅ **Signature Validation** - Verifies WOFF2 magic number (0x774F4632)
2. ✅ **Modern Decompression** - Uses Brotli algorithm via wawoff2 library
3. ✅ **Binary Processing** - Handles complex WOFF2 transformations
4. ✅ **TTF Output** - Produces standard TTF format
5. ✅ **Quality Assurance** - FontKit validation ensures font integrity

### Performance Characteristics

- **File Size**: Handles fonts from 100 bytes to 50MB
- **Batch Processing**: Efficiently processes large font collections
- **Memory Usage**: Optimized for minimal memory footprint
- **Error Recovery**: Graceful handling of corrupted or invalid fonts
- **Cross-Platform**: Works on Windows, macOS, and Linux

### Font Validation

The tool performs comprehensive validation at multiple stages:

1. **Pre-Conversion Validation**:
   - File existence and permissions
   - File size constraints (100 bytes - 50MB)
   - Format signature validation
   - Path security checks

2. **Post-Conversion Validation**:
   - Font structure integrity using FontKit
   - Glyph count verification
   - Font metadata extraction (family name, style, etc.)
   - Output file size validation

3. **Error Handling**:
   - Detailed error messages with context
   - Non-destructive operation (original files preserved)
   - Batch processing continues on individual failures
   - Exit codes for automation integration

## Troubleshooting

### Common Issues

#### "No WOFF or WOFF2 files found"
**Problem**: The CLI can't find font files in the specified directory.

**Solutions**:
```bash
# If fonts are in subdirectories, use --recursive
node bin/cli.js batch ./fonts --recursive

# Check if files have correct extensions (.woff or .woff2)
ls ./fonts/  # or dir fonts\ on Windows

# Target specific subdirectory
node bin/cli.js batch ./fonts/font-family/woff
```

#### "WOFF2 decompression failed"
**Problem**: WOFF2 file might be corrupted or use an unsupported variant.

**Solutions**:
```bash
# Try converting individual files to isolate the issue
node bin/cli.js convert problem-font.woff2 --verbose

# Check file integrity
file problem-font.woff2  # On Linux/macOS
```

#### "Permission denied"
**Problem**: Insufficient permissions to read input or write output.

**Solutions**:
```bash
# Ensure you have read permissions on input directory
chmod +r ./fonts/* # Linux/macOS

# Ensure write permissions on output directory
mkdir -p ./output && chmod +w ./output

# Or specify a different output directory
node bin/cli.js batch ./fonts -o ~/Desktop/converted-fonts
```

#### "File too large" or "File too small"
**Problem**: Font file size is outside supported range (100 bytes - 50MB).

**Solutions**:
- Files smaller than 100 bytes are likely corrupted
- Files larger than 50MB may be invalid or contain multiple fonts
- Use `ls -lh` (Linux/macOS) or `dir` (Windows) to check file sizes

### Performance Tips

1. **Use verbose mode** to monitor progress: `--verbose`
2. **Process in smaller batches** if you have thousands of fonts
3. **Use SSD storage** for faster I/O operations
4. **Close other applications** if processing very large font collections

### Getting Help

```bash
# General help
node bin/cli.js --help

# Command-specific help
node bin/cli.js convert --help
node bin/cli.js batch --help

# Version information
node bin/cli.js --version
```

## Error Codes

The CLI uses standard exit codes for automation integration:

- `0` - ✅ **Success** - All operations completed successfully
- `1` - ❌ **Conversion failure** - Font conversion process failed
- `1` - ❌ **Validation failure** - Input validation failed
- `1` - ❌ **File system error** - I/O or permission errors

## Changelog

### v1.0.0 (Latest)
- ✅ Initial release with WOFF and WOFF2 support
- ✅ Single file and batch conversion
- ✅ **NEW**: Recursive directory scanning with `--recursive` flag
- ✅ **NEW**: Directory structure preservation in output
- ✅ **IMPROVED**: Enhanced WOFF2 support with wawoff2 library
- ✅ Comprehensive error handling and validation
- ✅ FontKit integration for quality assurance
- ✅ Cross-platform compatibility
- ✅ Verbose logging and detailed progress reporting

## Roadmap

### Planned Features
- 📅 **GUI Version** - Electron-based desktop application
- 📅 **Watch Mode** - Automatic conversion on file changes
- 📅 **Configuration Files** - JSON/YAML config for batch settings
- 📅 **Plugin System** - Custom conversion pipelines
- 📅 **Font Optimization** - Size reduction and glyph subsetting
- 📅 **Metadata Preservation** - Font licensing and attribution info
- 📅 **Format Detection** - Auto-detect optimal output format
- 📅 **Progress Bar** - Visual progress indication for large batches

## License

ISC License

## Contributing

We welcome contributions! Here's how you can help:

### Development Setup

```bash
# Clone the repository
git clone <repository-url>
cd font-converter

# Install dependencies
npm install

# Run tests
npm test

# Test CLI locally
node bin/cli.js --help
```

### Contribution Guidelines

1. **Fork the repository** and create a feature branch
2. **Write tests** for new functionality
3. **Follow existing code style** and conventions
4. **Update documentation** including README and examples
5. **Test thoroughly** on different platforms if possible
6. **Submit a pull request** with clear description

### Areas for Contribution

- 🐛 **Bug fixes** - Report and fix issues
- ✨ **New features** - Implement roadmap items
- 📝 **Documentation** - Improve guides and examples
- 🧪 **Testing** - Add test cases and improve coverage
- 🌍 **Localization** - Add support for other languages
- 🚀 **Performance** - Optimize conversion algorithms

### Reporting Issues

When reporting bugs, please include:
- Operating system and Node.js version
- Font file details (format, size, source)
- Complete error message or output
- Steps to reproduce the issue
- Sample font files if possible (and permissible)

## Support

### Documentation
- 📚 **README** - Complete usage guide (this document)
- 📜 **Examples** - See `examples/` directory for more samples
- 🚀 **CLI Help** - Use `--help` flag with any command

### Community
- 💬 **Issues** - Report bugs and request features
- 📬 **Discussions** - Ask questions and share tips
- 👥 **Contributors** - Join our development community

### Commercial Support
- 🏢 **Enterprise** - Custom features and priority support available
- 📞 **Consulting** - Font workflow optimization and integration
- 🎆 **Training** - Team workshops on font management

For issues, questions, or contributions, please visit the project repository.

---

**Made with ❤️ for the web development community**

*Font Converter CLI - Transform your font workflows with confidence*