pulp-image 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Rebellion Geeks
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,332 @@
+# pulp-image
+
+A powerful, safety-first CLI tool for processing images with resize, format conversion, and optimization.
+
+![Version](https://img.shields.io/badge/version-0.1.0-blue)
+![License](https://img.shields.io/badge/license-MIT-green)
+![Node](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)
+
+## Features
+
+- 🖼️ **Resize images** with aspect ratio preservation
+- 🔄 **Convert formats** (PNG, JPG, WebP, AVIF)
+- 📦 **Batch process** entire directories
+- 🛡️ **Safety-first** defaults (no overwrites, no accidental deletions)
+- 📊 **Detailed statistics** and summary reports
+- 🎨 **Transparency handling** with customizable backgrounds
+- ⚡ **Optimization** with quality and lossless options
+
+## Installation
+
+### From GitHub
+
+1. **Clone or download the repository:**
+   ```bash
+   git clone https://github.com/rebelliongeeks/pulp-image.git
+   cd pulp-image
+   ```
+
+2. **Install dependencies:**
+   ```bash
+   npm install
+   ```
+
+3. **Link the CLI globally:**
+   ```bash
+   npm link
+   ```
+
+   This will make the `pulp` command available globally on your system.
+
+### Alternative: Install directly from GitHub
+
+You can also install directly from GitHub without cloning:
+
+```bash
+npm install -g github:rebelliongeeks/pulp-image
+```
+
+### Global Installation (Persistent)
+
+If you want the `pulp` command to work even after deleting the project folder, use global installation instead of `npm link`:
+
+```bash
+npm install -g .
+```
+
+This copies the files to your global npm directory, so the command persists even if you delete the source folder.
+
+**Note:** `npm link` creates a symlink (breaks if you delete the folder). `npm install -g` copies files (persists after deletion).
+
+### Requirements
+
+- Node.js >= 18.0.0
+- npm (comes with Node.js)
+
+## Quick Start
+
+```bash
+# Resize an image
+pulp image.png --width 800
+
+# Convert format
+pulp image.png --format webp
+
+# Process all images in a directory
+pulp ./images --format webp --out ./output
+```
+
+## Usage
+
+```bash
+pulp [input] [options]
+```
+
+### Arguments
+
+- `[input]` - Input file or directory (required)
+
+### Common Options
+
+#### Resize
+- `-w, --width <number>` - Output width in pixels (preserves aspect ratio if height not specified)
+- `-h, --height <number>` - Output height in pixels (preserves aspect ratio if width not specified)
+
+#### Format
+- `-f, --format <format>` - Output format: `png`, `jpg`, `webp`, or `avif`
+
+#### Output
+- `-o, --out <dir>` - Output directory (default: `./pulp-image-results`)
+  - **Why use --out?** This keeps your original files safe and organizes processed images in a dedicated folder. The output directory is created automatically if it doesn't exist.
+
+#### Quality
+- `--quality <number>` - Quality for lossy formats (1-100). Defaults: JPG=80, WebP=80, AVIF=50
+- `--lossless` - Use lossless compression where supported (PNG, WebP, AVIF)
+
+**Compression Behavior:**
+- **PNG**: Always lossless (no quality setting available)
+- **JPG**: Always lossy, default quality 80 (does not support lossless)
+- **WebP**: Lossy by default (quality 80), can use `--lossless` for lossless compression
+- **AVIF**: Lossy by default (quality 50), can use `--lossless` for lossless compression
+
+**Note:** Resize operations do NOT affect compression. Resizing only changes image dimensions. Compression/quality is determined by the format and quality settings.
+
+#### Transparency
+- `--background <color>` - Background color for flattening transparency (hex format, default: `#ffffff`)
+- `--alpha-mode <mode>` - Alpha handling: `flatten` (default) or `error`
+
+#### Safety
+- `--overwrite` - Overwrite existing output files (default: skip existing files)
+- `--delete-original` - Delete original files after successful processing (only if paths differ)
+
+#### Other
+- `-v, --verbose` - Show detailed per-file processing information
+- `--help` - Display help information
+- `--version` - Show version number
+
+## Examples
+
+### Resize Images
+
+```bash
+# Resize by width (preserves aspect ratio)
+pulp image.png --width 800
+
+# Resize by height (preserves aspect ratio)
+pulp image.png --height 600
+
+# Resize to exact dimensions
+pulp image.png --width 800 --height 600
+```
+
+### Format Conversion
+
+```bash
+# Convert PNG to WebP (preserves transparency)
+pulp image.png --format webp
+
+# Convert PNG to JPG (flattens transparency to white)
+pulp image.png --format jpg
+
+# Convert with custom background color
+pulp image.png --format jpg --background "#ff0000"
+
+# Convert to lossless WebP
+pulp image.png --format webp --lossless
+```
+
+### Suffix Options
+
+```bash
+# Auto suffix (adds size to filename)
+pulp image.png --width 800 --auto-suffix
+# Output: image-800w.png
+
+# Custom suffix
+pulp image.png --suffix "optimized"
+# Output: image-optimized.png
+
+# Combined suffixes (auto first, custom second)
+pulp image.png --width 800 --auto-suffix --suffix "thumb"
+# Output: image-800w-thumb.png
+```
+
+### Batch Processing
+
+```bash
+# Process all images in a directory
+pulp ./images --format webp --out ./output
+
+# Resize all images with auto-suffix
+pulp ./images --width 800 --auto-suffix --out ./output
+
+# Verbose mode (shows per-file details)
+pulp ./images --format webp --out ./output --verbose
+
+# Overwrite existing files
+pulp ./images --format webp --out ./output --overwrite
+```
+
+### Safety Features
+
+```bash
+# Safe processing (output to separate directory)
+pulp image.png --format webp --out ./pulp-image-results
+
+# Overwrite existing output files
+pulp image.png --format webp --out ./pulp-image-results --overwrite
+
+# Delete original after successful processing
+pulp image.png --format webp --out ./pulp-image-results --delete-original
+```
+
+## Safety Features
+
+pulp-image is designed with safety in mind:
+
+- **No overwrites by default** - Existing output files are skipped unless `--overwrite` is used
+- **Delete original safety** - Only deletes after successful processing and only if input/output paths differ
+- **Same path protection** - Prevents accidental in-place overwrites
+- **Batch resilience** - Continues processing even if individual files fail
+- **Clear error messages** - Helpful guidance when something goes wrong
+
+## Output Directory (--out)
+
+The `--out` option specifies where processed images are saved. Here's why it's useful:
+
+- **Keeps originals safe** - Your source files remain untouched
+- **Organizes outputs** - All processed images in one place
+- **Prevents accidents** - No risk of overwriting originals
+- **Default location** - Uses `./pulp-image-results` if not specified
+- **Auto-creation** - Creates the directory if it doesn't exist
+
+Example:
+```bash
+# Process images and save to ./output directory
+pulp ./images --format webp --out ./output
+
+# Your originals in ./images remain safe
+# Processed images go to ./output
+```
+
+## Supported Formats
+
+### Input Formats
+- PNG
+- JPG/JPEG
+- WebP
+- AVIF
+
+### Output Formats
+- PNG
+- JPG
+- WebP
+- AVIF
+
+## Compression & Quality
+
+### Default Compression Behavior
+
+Each format has different default compression behavior:
+
+- **PNG**: Always lossless (no quality setting available)
+- **JPG**: Always lossy, default quality 80 (does not support lossless)
+- **WebP**: Lossy by default (quality 80), supports lossless with `--lossless`
+- **AVIF**: Lossy by default (quality 50), supports lossless with `--lossless`
+
+**Important:** Resize operations do NOT affect compression. Resizing only changes image dimensions. Compression/quality is determined by the format and quality settings.
+
+### Using Lossless Compression
+
+```bash
+# Lossless WebP
+pulp image.png --format webp --lossless
+
+# Lossless AVIF
+pulp image.png --format avif --lossless
+
+# PNG is already lossless (no flag needed)
+pulp image.jpg --format png
+```
+
+### Custom Quality Settings
+
+```bash
+# High quality JPG
+pulp image.png --format jpg --quality 95
+
+# Lower quality WebP (smaller file)
+pulp image.png --format webp --quality 60
+
+# Custom AVIF quality
+pulp image.png --format avif --quality 70
+```
+
+## Transparency Handling
+
+When converting images with transparency to formats that don't support it (like JPG):
+
+- **Default behavior**: Flattens transparency onto white background
+- **Custom background**: Use `--background "#color"` to specify a color
+- **Error mode**: Use `--alpha-mode error` to fail instead of flattening
+
+Example:
+```bash
+# Flatten transparency to red background
+pulp image.png --format jpg --background "#ff0000"
+
+# Fail if transparency exists
+pulp image.png --format jpg --alpha-mode error
+```
+
+## Statistics and Reporting
+
+pulp-image provides detailed statistics:
+
+- **Per-file stats**: Original size, final size, bytes saved, percent saved
+- **Batch summary**: Total files processed, total sizes, overall savings
+- **Skipped files**: Count and reasons (in verbose mode)
+- **Failed files**: Count and errors (in verbose mode)
+
+Example output:
+```
+✓ Processed: 7 file(s)
+  Total original size: 10.07 MB
+  Total final size:    821.78 KB
+  Total saved:         9.26 MB (92.03%)
+```
+
+## Interactive Documentation
+
+For a beautiful interactive documentation with examples, open:
+```
+docs/index.html
+```
+
+## License
+
+MIT
+
+## Author
+
+Rebellion Geeks

package/bin/pulp.js

@@ -0,0 +1,251 @@
+#!/usr/bin/env node
+
+import { readFileSync } from 'fs';
+import { dirname, resolve } from 'path';
+import { fileURLToPath } from 'url';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const pkg = JSON.parse(
+  readFileSync(resolve(__dirname, '../package.json'), 'utf-8')
+);
+
+
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { banner } from '../src/banner.js';
+import { formatBytes } from '../src/stats.js';
+import { planTasks } from '../src/planTasks.js';
+import { Reporter } from '../src/reporter.js';
+import { runJob } from '../src/runJob.js';
+import { startUIServer } from '../src/uiServer.js';
+import { statSync, existsSync } from 'fs';
+
+const program = new Command();
+
+program
+  .name('pulp')
+  .description('A CLI tool for processing images with resize, format conversion, and optimization')
+  .version(pkg.version)  
+  .addHelpText('before', chalk.cyan(banner))
+  .argument('[input]', 'Input file or directory')
+  .option('-w, --width <number>', 'Output width in pixels')
+  .option('-h, --height <number>', 'Output height in pixels')
+  .option('-f, --format <format>', 'Output format (png, jpg, webp, avif)')
+  .option('-o, --out <dir>', 'Output directory (default: ./pulp-image-results). Creates directory if it doesn\'t exist. Keeps originals safe by saving processed images separately.')
+  .option('--suffix <text>', 'Custom suffix to add before extension')
+  .option('--auto-suffix', 'Automatically add size-based suffix')
+  .option('--quality <number>', 'Quality for lossy formats (1-100). Defaults: JPG=80, WebP=80, AVIF=50')
+  .option('--lossless', 'Use lossless compression where supported (PNG, WebP, AVIF). Note: PNG is always lossless. JPG does not support lossless.')
+  .option('--background <color>', 'Background color for transparency flattening', '#ffffff')
+  .option('--alpha-mode <mode>', 'Alpha handling: flatten or error', 'flatten')
+  .option('--overwrite', 'Overwrite existing output files')
+  .option('--delete-original', 'Delete original files after processing')
+  .option('-v, --verbose', 'Verbose output')
+  .addHelpText('after', `
+Examples:
+  $ pulp image.png --format webp --quality 95
+  $ pulp image.png --width 800
+  $ pulp image.png --format webp --out ./output
+  $ pulp image.png --format jpg --quality 95
+  $ pulp image.png --format webp --quality 60
+  $ pulp image.png --width 800 --height 600 --auto-suffix
+  $ pulp ./images --format webp --out ./output --verbose
+  $ pulp image.png --format jpg --background "#ff0000"
+  $ pulp image.png --format avif --quality 70
+  $ pulp ./images --width 800 --auto-suffix --suffix "thumb" --out ./pulp-image-results
+
+About --out:
+  The --out option specifies where processed images are saved (default: ./pulp-image-results).
+  This keeps your original files safe and organizes outputs in a dedicated folder.
+  The output directory is created automatically if it doesn't exist.
+
+Compression Behavior:
+  PNG: Always lossless (no quality setting)
+  JPG: Always lossy, default quality 80 (does not support lossless)
+  WebP: Lossy by default (quality 80), use --lossless for lossless
+  AVIF: Lossy by default (quality 50), use --lossless for lossless
+  Note: Resize does not affect compression - it only changes dimensions.
+
+  `)
+  .action(async (input, options) => {
+    // Display banner
+    console.log(chalk.cyan(banner));
+    
+    // Normalize config
+    const config = {
+      input: input || null,
+      width: options.width ? parseInt(options.width, 10) : null,
+      height: options.height ? parseInt(options.height, 10) : null,
+      format: options.format || null,
+      out: options.out || './pulp-image-results',
+      suffix: options.suffix || null,
+      autoSuffix: options.autoSuffix || false,
+      quality: options.quality ? parseInt(options.quality, 10) : null,
+      lossless: options.lossless || false,
+      background: options.background || '#ffffff',
+      alphaMode: options.alphaMode || 'flatten',
+      overwrite: options.overwrite || false,
+      deleteOriginal: options.deleteOriginal || false,
+      verbose: options.verbose || false
+    };
+    
+    if (!input) {
+      console.log(chalk.yellow('\nNo input specified. Use --help for usage information.'));
+      process.exit(1);
+    }
+    
+    // Resolve input path
+    const inputPath = resolve(input);
+    
+    if (!existsSync(inputPath)) {
+      console.error(chalk.red(`\nError: Input not found: ${inputPath}`));
+      process.exit(1);
+    }
+    
+    const inputStats = statSync(inputPath);
+    const isDirectory = inputStats.isDirectory();
+    const isFile = inputStats.isFile();
+    
+    if (!isFile && !isDirectory) {
+      console.error(chalk.red(`\nError: Input must be a file or directory: ${inputPath}`));
+      process.exit(1);
+    }
+    
+    // Handle directory planning for display (before runJob)
+    if (isDirectory) {
+      let tasks;
+      try {
+        tasks = planTasks(inputPath);
+      } catch (error) {
+        console.error(chalk.red(`\nError reading directory: ${error.message}`));
+        process.exit(1);
+      }
+      
+      if (tasks.length === 0) {
+        console.log(chalk.yellow(`\nNo supported image files found in: ${inputPath}`));
+        process.exit(0);
+      }
+      
+      console.log(chalk.gray(`\nFound ${tasks.length} image file(s) to process...\n`));
+    }
+    
+    // Use runJob for orchestration (no terminal output from runJob)
+    let results;
+    try {
+      if (isFile && config.verbose) {
+        console.log(chalk.gray(`\nProcessing: ${inputPath}`));
+      }
+      
+      results = await runJob(inputPath, config);
+    } catch (error) {
+      console.error(chalk.red(`\nError: ${error.message}`));
+      if (config.verbose) {
+        console.error(error);
+      }
+      process.exit(1);
+    }
+    
+    // Display results exactly as before
+    if (isFile) {
+      // Single file: show detailed result or skip/error
+      if (results.processed.length > 0) {
+        const result = results.processed[0];
+        console.log(chalk.green(`\n✓ Processed: ${result.outputPath}`));
+        console.log(chalk.gray(`  Original: ${formatBytes(result.originalSize)} (${result.metadata.width}x${result.metadata.height})`));
+        console.log(chalk.gray(`  Final:    ${formatBytes(result.finalSize)}`));
+        console.log(chalk.gray(`  Saved:    ${formatBytes(result.bytesSaved)} (${result.percentSaved}%)`));
+        
+        if (result.deleteError) {
+          console.log(chalk.yellow(`  Warning: Failed to delete original: ${result.deleteError}`));
+        }
+      } else if (results.skipped.length > 0) {
+        const skipped = results.skipped[0];
+        console.log(chalk.yellow(`\n⚠ Skipped: ${skipped.filePath}`));
+        console.log(chalk.gray(`  Reason: ${skipped.reason}`));
+      } else if (results.failed.length > 0) {
+        const failed = results.failed[0];
+        console.error(chalk.red(`\n✗ Error: ${failed.error}`));
+        if (config.verbose) {
+          console.error(failed);
+        }
+      }
+    } else {
+      // Directory: show per-file results in verbose mode, then summary
+      if (config.verbose) {
+        // Reconstruct reporter for per-file display
+        const reporter = new Reporter();
+        results.processed.forEach(r => reporter.recordProcessed(r));
+        results.skipped.forEach(s => reporter.recordSkipped(s.filePath, s.reason));
+        results.failed.forEach(f => reporter.recordFailed(f.filePath, new Error(f.error)));
+        
+        // Show per-file results
+        results.processed.forEach(result => {
+          reporter.printFileResult(result, true);
+        });
+        
+        // Show skipped files
+        results.skipped.forEach(({ filePath, reason }) => {
+          console.log(chalk.yellow(`⚠ Skipped: ${filePath}`));
+          console.log(chalk.gray(`  Reason: ${reason}`));
+        });
+        
+        // Show failed files
+        results.failed.forEach(({ filePath, error }) => {
+          console.error(chalk.red(`✗ Failed: ${filePath}`));
+          console.error(chalk.gray(`  Error: ${error}`));
+        });
+      } else {
+        // Non-verbose: just show failures
+        results.failed.forEach(({ filePath, error }) => {
+          console.error(chalk.red(`✗ Failed: ${filePath}`));
+        });
+      }
+    }
+    
+    // Print summary for batch processing or if there were issues
+    if (isDirectory || results.skipped.length > 0 || results.failed.length > 0) {
+      const reporter = new Reporter();
+      results.processed.forEach(r => reporter.recordProcessed(r));
+      results.skipped.forEach(s => reporter.recordSkipped(s.filePath, s.reason));
+      results.failed.forEach(f => reporter.recordFailed(f.filePath, new Error(f.error)));
+      reporter.printSummary(config.verbose);
+    }
+  });
+
+// UI command
+program
+  .command('ui')
+  .description('Start the browser-based UI')
+  .option('-p, --port <number>', 'Port to run server on', '3000')
+  .action(async (options) => {
+    const port = parseInt(options.port || '3000', 10);
+    
+    if (isNaN(port) || port < 1 || port > 65535) {
+      console.error(chalk.red(`\nError: Invalid port number: ${options.port}`));
+      process.exit(1);
+    }
+    
+    try {
+      const { server } = await startUIServer(port);
+      
+      // Handle graceful shutdown
+      const shutdown = () => {
+        console.log(chalk.gray('\n\nShutting down server...'));
+        server.close(() => {
+          console.log(chalk.green('Server stopped.'));
+          process.exit(0);
+        });
+      };
+      
+      process.on('SIGINT', shutdown);
+      process.on('SIGTERM', shutdown);
+      
+    } catch (error) {
+      console.error(chalk.red(`\nError starting UI server: ${error.message}`));
+      process.exit(1);
+    }
+  });
+
+program.parse();
+

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "pulp-image",
+  "version": "0.1.0",
+  "description": "A CLI tool for processing images with resize, format conversion, and optimization",
+  "type": "module",
+  "main": "bin/pulp.js",
+  "bin": {
+    "pulp": "./bin/pulp.js"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "image",
+    "resize",
+    "convert",
+    "optimize",
+    "cli"
+  ],
+  "author": "Rebellion Geeks",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rebelliongeeks/pulp-image.git"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "chalk": "^5.6.2",
+    "commander": "^14.0.2",
+    "express": "^4.18.2",
+    "multer": "^2.0.2",
+    "open": "^8.4.2",
+    "sharp": "^0.34.5"
+  }
+}

package/src/banner.js

@@ -0,0 +1,10 @@
+export const banner = `
+╔════════════════════════════════════════╗
+║                                        ║
+║         pulp-image v0.1.0              ║
+║                                        ║
+║     Image processing made simple       ║
+║                                        ║
+╚════════════════════════════════════════╝
+`;
+