pulp-image 0.1.6 → 0.1.8

package/CHANGELOG.md

@@ -0,0 +1,53 @@
+# Changelog
+
+All notable changes to Pulp Image will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/), and this project adheres to [Semantic Versioning](https://semver.org/).
+
+---
+
+## [Unreleased]
+
+See [Roadmap](ROADMAP.md) for upcoming features (v0.2.0: UI Redesign, Rotate, Flip, Grayscale, Auto-Orient).
+
+---
+
+## [0.1.8] - 2026-01-13
+
+### Changed
+- Streamlined README with quick links and features grid
+- Added public roadmap and changelog
+- Updated project slogan
+
+---
+
+## [0.1.7] - 2026-01-12
+
+### Added
+- Auto suffix option to add dimensions to filenames
+- Custom suffix support for output filenames
+- Rename patterns with tokens {name}, {ext}, {index} (UI only)
+
+### Fixed
+- Minor bug fixes and improvements
+
+---
+
+## [0.1.0] - Initial Release
+
+### Added
+- **CLI Tool**: Full command-line interface for image processing
+- **Browser UI**: Launch with `pulp ui`, works offline, no uploads
+- **Format Conversion**: PNG, JPG, WebP, AVIF, GIF, TIFF
+- **Resize**: By width, height, or exact dimensions
+- **Quality Control**: Compression quality 1-100
+- **Lossless Mode**: For WebP and AVIF
+- **Transparency Handling**: Flatten with custom background color
+- **Batch Processing**: Process entire folders
+- **Custom Output Directory**: Save files anywhere
+- **Overwrite Protection**: Skip or overwrite existing files
+- **Delete Originals**: Remove source files after processing (CLI only)
+
+---
+
+*For upcoming features, see the [Roadmap](ROADMAP.md).*

package/README.md

@@ -1,303 +1,92 @@
 # pulp-image
 
-A powerful, safety-first CLI tool for processing images with resize, format conversion, and optimization.
+Full-featured image processing CLI with a browser UI. 100% local.
 
 ![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
+**[Website](https://pulp.run)** · **[CLI Docs](https://pulp.run/cli.html)** · **[UI Docs](https://pulp.run/ui.html)** · **[Roadmap](ROADMAP.md)** · **[Changelog](CHANGELOG.md)**
 
-Install pulp-image globally using npm:
+---
 
-```bash
-npm install -g pulp-image
-```
-
-This is a global CLI. Installing with `-g` makes the `pulp` command available system-wide.
-
-### Requirements
-
-- Node.js >= 18.0.0
-- npm (comes with Node.js)
-
-## Quick Start
+## Features
 
-```bash
-# Resize an image
-pulp image.png --width 800
+| | | |
+|:--|:--|:--|
+| 🖼️ **Resize** | 🔄 **Convert Formats** | 📦 **Batch Process** |
+| 🎨 **Transparency** | ⚡ **Quality Control** | 🛡️ **Safety-First** |
+| 🌐 **Browser UI** | 📁 **Custom Output** | 🏷️ **Auto Naming** |
 
-# Convert format
-pulp image.png --format webp
+---
 
-# Process all images in a directory
-pulp ./images --format webp --out ./output
-```
+## Installation
 
-## Usage
+### CLI (npm)
 
 ```bash
-pulp [input] [options]
+npm install -g pulp-image
 ```
 
-### 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.
+Requires Node.js >= 18.0.0
 
-#### 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)
+### Portable UI (No Install)
 
-**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
+Download the portable UI for your platform. No Node.js or npm required:
 
-**Note:** Resize operations do NOT affect compression. Resizing only changes image dimensions. Compression/quality is determined by the format and quality settings.
+**[Download Latest Release](https://github.com/rebelliongeeks/pulp-image/releases/latest)**
 
-#### 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
+## Quick Start
 
 ```bash
-# Resize by width (preserves aspect ratio)
+# Resize an image
 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)
+# Convert to WebP
 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
+# Batch process a folder
 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
+# High quality JPG
+pulp image.png --format jpg --quality 95
 
-```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
+For all options, run `pulp --help` or see the [CLI documentation](https://pulp.run/cli.html).
 
-```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):
+## Browser UI
 
-- **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
+Launch the browser-based interface:
 
-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
+pulp ui
 ```
 
-## Statistics and Reporting
+Opens at `http://localhost:3000`. All processing happens locally, no uploads.
 
-pulp-image provides detailed statistics:
+See the [UI documentation](https://pulp.run/ui.html) for details.
 
-- **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%)
-```
+## Roadmap
 
-## Browser UI
-
-pulp-image includes a web-based interface for easy image processing:
+See the full [Roadmap](ROADMAP.md) for upcoming features.
 
-```bash
-pulp ui
-```
-
-This starts a local web server. Open your browser and navigate to:
-
-```
-http://localhost:3000
-```
+**Coming soon:**
+- UI Redesign with dark mode
+- Rotate, Flip, Grayscale
+- Blur, Sharpen, Normalize
+- Cropping & Visual Crop Tool
+- Watermarks
+- User Presets
 
-The browser UI provides a user-friendly interface for processing images with all the same features available in the CLI.
+---
 
 ## License
 
@@ -305,4 +94,4 @@ MIT
 
 ## Author
 
-Rebellion Geeks
+[Rebellion Geeks](https://github.com/rebelliongeeks)

package/ROADMAP.md

@@ -0,0 +1,133 @@
+# Roadmap
+
+> Full-featured image processing CLI with a browser UI. 100% local.
+
+---
+
+## ✅ v0.1.x (Current)
+
+| Feature | Description |
+|---------|-------------|
+| ~~**Format Conversion**~~ | ~~Convert between PNG, JPG, WebP, AVIF, GIF, TIFF~~ |
+| ~~**Resize**~~ | ~~Resize by width, height, or both with auto aspect ratio~~ |
+| ~~**Quality Control**~~ | ~~Adjust compression quality (1-100)~~ |
+| ~~**Lossless Mode**~~ | ~~Preserve full quality for WebP and AVIF~~ |
+| ~~**Transparency Handling**~~ | ~~Flatten transparent areas with custom background color~~ |
+| ~~**Custom Output Directory**~~ | ~~Save processed files to any folder~~ |
+| ~~**Auto Suffix**~~ | ~~Add dimensions to filename automatically~~ |
+| ~~**Rename Patterns**~~ | ~~Use tokens like {name}, {ext}, {index} for output names (UI)~~ |
+| ~~**Batch Processing**~~ | ~~Process entire folders at once~~ |
+| ~~**Delete Originals**~~ | ~~Remove source files after processing (CLI only)~~ |
+| ~~**Browser-Based UI**~~ | ~~Full-featured interface, works offline, no uploads~~ |
+
+---
+
+## 🚧 v0.2.0
+
+| Feature | Description |
+|---------|-------------|
+| **UI Redesign** | Modern tabbed interface with dark mode |
+| **Rotate** | Rotate images by 90°, 180°, 270°, or custom angle |
+| **Flip / Mirror** | Flip vertically or horizontally |
+| **Grayscale** | Convert images to black and white |
+| **Auto-Orient** | Fix photos that appear sideways or upside down |
+
+---
+
+## 📋 v0.3.0
+
+| Feature | Description |
+|---------|-------------|
+| **Blur** | Soften images with adjustable intensity |
+| **Sharpen** | Enhance detail and clarity |
+| **Normalize** | Auto-adjust contrast for better exposure |
+| **Brightness** | Adjust overall brightness |
+| **Saturation** | Adjust color intensity |
+| **Gamma Correction** | Adjust brightness curve |
+| **Hue Shift** | Rotate colors on the color wheel |
+| **Negate / Invert** | Invert all colors (negative effect) |
+| **Tint** | Apply color overlay |
+
+---
+
+## 📋 v0.4.0
+
+| Feature | Description |
+|---------|-------------|
+| **Trim Whitespace** | Auto-remove uniform borders from images |
+| **Crop by Coordinates** | Crop to specific pixel coordinates |
+| **Visual Crop Tool** | Drag-and-drop crop selection (UI) |
+| **Aspect Ratio Crop** | Crop to common ratios (16:9, 4:3, 1:1) |
+| **Blur Region** | Blur faces or sensitive areas for privacy |
+| **Pixelate Region** | Pixelate specific areas for censoring |
+
+---
+
+## 📋 v0.5.0
+
+| Feature | Description |
+|---------|-------------|
+| **Add Padding** | Add space around image with custom color |
+| **Add Border** | Add visible frame around image |
+
+---
+
+## 📋 v0.6.0
+
+| Feature | Description |
+|---------|-------------|
+| **Image Watermark** | Add logo or image overlay |
+| **Watermark Position** | Place in corners, center, or custom coordinates |
+| **Watermark Opacity** | Adjust transparency (0-100%) |
+| **Watermark Scale** | Size relative to image or absolute pixels |
+| **Watermark Tile** | Repeat watermark across entire image |
+
+---
+
+## 📋 v0.7.0
+
+| Feature | Description |
+|---------|-------------|
+| **Save Preset** | Save current settings as named preset |
+| **Load Preset** | Apply saved presets |
+| **Built-in Presets** | Ready-to-use presets (web, thumbnail, social media) |
+| **Export/Import Presets** | Share presets between devices or users |
+
+---
+
+## 📋 v0.8.0
+
+| Feature | Description |
+|---------|-------------|
+| **Multi-Format Export** | Export same image to multiple formats at once |
+| **Multi-Size Export** | Export same image at multiple sizes at once |
+| **Progressive JPEG** | Enable progressive loading (blurry to sharp) |
+| **PNG Compression** | Fine-tune PNG compression level |
+| **WebP/AVIF Effort** | Control encoding effort for smaller files |
+
+---
+
+## 🎯 v1.0.0 (Stable Release)
+
+- All features from v0.2.0 through v0.8.0 complete
+- Comprehensive documentation
+- Stable CLI (no breaking changes)
+
+---
+
+## 🔮 Future (v1.1.0+)
+
+These features may be added after the stable release:
+
+| Feature | Description |
+|---------|-------------|
+| **Preserve Metadata** | Keep original EXIF data instead of stripping |
+| **Custom ICC Profile** | Embed specific color profiles |
+| **Median Filter** | Reduce noise while preserving edges |
+| **Pure Black & White** | Convert to only black and white pixels (stencil effect) |
+| **Animated GIF/WebP** | Process animated images |
+| **Extract Frame** | Get single frame from animation |
+
+---
+
+*No fixed release dates. Features ship when ready.*

package/bin/pulp.js

@@ -26,7 +26,7 @@ const banner = getBanner(pkg.version);
 
 program
   .name('pulp')
-  .description('A CLI tool for processing images with resize, format conversion, and optimization')
+  .description('Full-featured image processing CLI with a browser UI. 100% local.')
   .version(pkg.version)  
   .addHelpText('before', chalk.cyan(banner))
   .argument('[input]', 'Input file or directory')

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pulp-image",
-  "version": "0.1.6",
-  "description": "A CLI tool for processing images with resize, format conversion, and optimization",
+  "version": "0.1.8",
+  "description": "Full-featured image processing CLI with a browser UI. 100% local.",
   "type": "module",
   "main": "bin/pulp.js",
   "bin": {
@@ -15,7 +15,15 @@
     "resize",
     "convert",
     "optimize",
-    "cli"
+    "cli",
+    "ui",
+    "browser",
+    "local",
+    "batch",
+    "webp",
+    "avif",
+    "png",
+    "jpg"
   ],
   "author": "Rebellion Geeks",
   "license": "MIT",

package/src/uiServer.js

@@ -243,11 +243,18 @@ export async function startUIServer(port = 3000) {
   // API endpoint to open folder in file manager
   app.post('/api/open-folder', async (req, res) => {
     try {
-      const { path } = req.body;
-      if (!path) {
+      let { path: folderPath } = req.body;
+      if (!folderPath) {
         return res.status(400).json({ error: 'Path required' });
       }
       
+      // Expand ~ to home directory
+      if (folderPath.startsWith('~')) {
+        folderPath = join(homedir(), folderPath.slice(1));
+      }
+      // Resolve to absolute path
+      folderPath = resolve(folderPath);
+      
       // Determine OS and use appropriate command
       const platform = process.platform;
       let command;
@@ -255,13 +262,13 @@ export async function startUIServer(port = 3000) {
       
       if (platform === 'darwin') {
         // macOS
-        command = `open "${path}"`;
+        command = `open "${folderPath}"`;
       } else if (platform === 'win32') {
         // Windows - use explorer to open in foreground
-        command = `explorer "${path}"`;
+        command = `explorer "${folderPath}"`;
       } else {
         // Linux and others - suppress stderr to avoid Wayland/Gnome noise
-        command = `xdg-open "${path}" 2>/dev/null || true`;
+        command = `xdg-open "${folderPath}" 2>/dev/null || true`;
         // Use shell to properly handle stderr redirection
         options = { shell: '/bin/bash' };
       }
@@ -271,7 +278,7 @@ export async function startUIServer(port = 3000) {
         if (platform === 'linux' || (platform !== 'darwin' && platform !== 'win32')) {
           // Use spawn with stderr redirected instead of execAsync for better control
           await new Promise((resolve, reject) => {
-            const child = spawn('xdg-open', [path], {
+            const child = spawn('xdg-open', [folderPath], {
               stdio: ['ignore', 'ignore', 'ignore'], // Suppress all output
               detached: true
             });
@@ -288,17 +295,16 @@ export async function startUIServer(port = 3000) {
         console.error('Error opening folder:', execError);
         res.status(500).json({ 
           error: 'Could not open folder automatically.',
-          path: path // Include path so UI can display it
+          path: folderPath // Include path so UI can display it
         });
       }
       
     } catch (error) {
       // Don't expose raw errors to user
       console.error('Error opening folder:', error);
-      const { path } = req.body;
       res.status(500).json({ 
         error: 'Could not open folder automatically.',
-        path: path || null // Include path if available
+        path: req.body?.path || null // Include path if available
       });
     }
   });