@puntoycoma/bulki 2.0.0

package/README.md

@@ -0,0 +1,329 @@
+# @puntoycoma/bulki
+
+Ultra-fast, free, open-source CLI image optimizer with interactive mode, AI editor integration, and automation tools.
+
+Built on [Sharp](https://sharp.pixelplumbing.com/) (libvips). Compress, resize, and convert JPEG, PNG, WebP, GIF, and AVIF images in bulk.
+
+## Why bulki?
+
+- **Fast** — Powered by Sharp/libvips, 4-5x faster than ImageMagick
+- **Interactive** — Run `bulki` with no arguments for a guided experience
+- **AI-ready** — Built-in MCP server for Claude Code, Cursor, Windsurf, and Cline
+- **Automated** — Git hooks, watch mode, and CI/CD integration
+- **Lightweight** — Minimal dependencies, 15 KB package size
+- **Free** — MIT licensed, no API keys, no accounts, runs 100% locally
+
+## Installation
+
+```bash
+npm install -g @puntoycoma/bulki
+```
+
+## Quick start
+
+### Interactive mode
+
+Just run `bulki` with no arguments:
+
+```bash
+bulki
+```
+
+You get a guided menu with presets and custom options — no commands to memorize.
+
+### CLI mode
+
+```bash
+# Compress all images in a directory
+bulki compress ./photos
+
+# Convert to WebP with quality 80
+bulki compress ./photos -f webp -q 80
+
+# Resize to max 1920px width
+bulki compress ./photos -r 1920
+
+# Compress a single file
+bulki compress ./photo.png -q 85 -f avif
+```
+
+## Features
+
+### Compress images
+
+Optimize images with full control over format, quality, and dimensions.
+
+```bash
+bulki compress <path> [options]
+```
+
+| Option | Alias | Description | Default |
+|--------|-------|-------------|---------|
+| `--quality <n>` | `-q` | Output quality (1-100) | `70` |
+| `--format <fmt>` | `-f` | Convert to: `jpeg`, `png`, `webp`, `gif`, `avif` | original |
+| `--resize <width>` | `-r` | Max width in pixels | original |
+| `--destination <path>` | `-d` | Output base directory | `.` |
+| `--output-folder <name>` | `-o` | Output folder name | `bulki-output` |
+| `--concurrency <n>` | | Parallel operations (1-32) | auto |
+| `--exclude <patterns...>` | | Directory names to skip | none |
+| `--dry-run` | | Preview without writing files | `false` |
+| `--verbose` | | Show per-file details | `false` |
+| `--json` | | Machine-readable JSON output | `false` |
+| `--max-size <size>` | | Fail if output exceeds limit | none |
+
+#### Examples
+
+```bash
+# Optimize for web: WebP, quality 80, max 1920px
+bulki compress ./assets -f webp -q 80 -r 1920
+
+# Preview what would be processed
+bulki compress ./uploads --dry-run
+
+# CI/CD: fail if any image exceeds 200 KB
+bulki compress ./public --max-size 200kb
+
+# JSON output for scripts and automation
+bulki compress ./images --json
+```
+
+#### JSON output
+
+Use `--json` for machine-readable output:
+
+```json
+{
+  "files": [
+    {
+      "input": "/path/to/photo.jpg",
+      "output": "/path/to/bulki-output/photo.webp",
+      "originalSize": 2400000,
+      "newSize": 680000,
+      "reduction": 72,
+      "format": "webp",
+      "duration": 45
+    }
+  ],
+  "summary": {
+    "totalFiles": 1,
+    "totalOriginalSize": 2400000,
+    "totalNewSize": 680000,
+    "totalReduction": 72,
+    "duration": 120,
+    "errors": 0
+  },
+  "errors": []
+}
+```
+
+#### Size budget
+
+Prevent oversized images in your project:
+
+```bash
+# Fail if any optimized image exceeds 200 KB
+bulki compress ./assets --max-size 200kb
+
+# Combined with JSON for CI pipelines
+bulki compress ./public --max-size 500kb --json
+```
+
+Exit code is `1` if any file exceeds the budget — perfect for CI checks.
+
+### Pipe (stdin/stdout)
+
+Process images through Unix pipes:
+
+```bash
+bulki pipe -f <format> [-q quality] [-r width]
+```
+
+#### Examples
+
+```bash
+# Download and optimize in one command
+curl -s https://example.com/photo.jpg | bulki pipe -f webp -q 80 > photo.webp
+
+# Convert format on the fly
+cat input.png | bulki pipe -f avif -q 70 > output.avif
+
+# Chain with other tools
+cat photo.jpg | bulki pipe -f webp -r 800 | aws s3 cp - s3://bucket/photo.webp
+```
+
+#### Use cases
+
+- **CI/CD pipelines** — optimize images during build without temp files
+- **Webhooks** — receive image, optimize, forward in one stream
+- **Scripts** — compose with curl, aws, gsutil, or any Unix tool
+
+### Watch mode
+
+Monitor a directory and auto-optimize new images:
+
+```bash
+bulki watch <directory> [options]
+```
+
+#### Examples
+
+```bash
+# Watch a folder and convert new images to WebP
+bulki watch ./uploads -f webp -q 80
+
+# Watch with resize
+bulki watch ./photos -r 1920 -q 85 -d ./optimized
+```
+
+#### Use cases
+
+- **Photographers** — drop photos from camera, get optimized versions automatically
+- **Designers** — export from Figma/Sketch, images optimize on save
+- **Local servers** — monitor an upload directory
+
+### Git hook
+
+Auto-optimize images on every commit:
+
+```bash
+# Install the pre-commit hook
+bulki hook install
+
+# Remove it
+bulki hook uninstall
+```
+
+Once installed, every time you `git commit` an image file (JPEG, PNG, WebP, GIF, AVIF), bulki optimizes it automatically before the commit completes.
+
+#### Use cases
+
+- **Teams** — no one commits unoptimized images, ever
+- **CI savings** — smaller images = faster builds and deploys
+- **Repo health** — keep your repository lean without manual work
+
+### MCP Server (AI editor integration)
+
+bulki exposes an MCP (Model Context Protocol) server so AI coding assistants can optimize images directly.
+
+```bash
+bulki mcp
+```
+
+This starts a local MCP server (no API key, no internet required) that provides two tools:
+
+| Tool | Description |
+|------|-------------|
+| `compress` | Optimize images in a file or directory |
+| `detect` | Check if a file is an image and identify its format |
+
+#### Setup with Claude Code
+
+Add to your Claude Code MCP config (`~/.claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "bulki": {
+      "command": "npx",
+      "args": ["@puntoycoma/bulki", "mcp"]
+    }
+  }
+}
+```
+
+Then in Claude Code, you can say:
+
+> "Optimize all images in the project for web"
+
+And Claude will call bulki directly.
+
+#### Setup with Cursor
+
+Add to `.cursor/mcp.json` in your project:
+
+```json
+{
+  "mcpServers": {
+    "bulki": {
+      "command": "npx",
+      "args": ["@puntoycoma/bulki", "mcp"]
+    }
+  }
+}
+```
+
+#### Use cases
+
+- **Claude Code** — "compress all PNG files to WebP"
+- **Cursor** — "optimize the images in /public"
+- **Windsurf / Cline** — any MCP-compatible AI editor
+- **Custom agents** — build your own tools with bulki as a backend
+
+## Supported formats
+
+| Format | Compress | Convert to | Convert from |
+|--------|----------|------------|--------------|
+| JPEG | yes | yes | yes |
+| PNG | yes | yes | yes |
+| WebP | yes | yes | yes |
+| GIF | yes | yes | yes |
+| AVIF | yes | yes | yes |
+
+## Output structure
+
+Optimized images are saved preserving the original folder structure:
+
+```
+photos/                    bulki-output/
+  vacation/         ->       vacation/
+    beach.jpg                  beach.jpg
+    sunset.png                 sunset.png
+  profile.png                profile.png
+```
+
+## Integration examples
+
+### GitHub Actions
+
+```yaml
+- name: Optimize images
+  run: npx @puntoycoma/bulki compress ./public -f webp -q 80 --max-size 500kb
+```
+
+### npm scripts
+
+```json
+{
+  "scripts": {
+    "optimize": "bulki compress ./src/assets -f webp -q 80",
+    "optimize:check": "bulki compress ./public --max-size 200kb --dry-run"
+  }
+}
+```
+
+### Pre-commit (manual setup)
+
+```bash
+# In your project
+bulki hook install
+```
+
+## Backward compatibility
+
+The `gio` command from the original `gab-images-optimizer` package still works:
+
+```bash
+gio compress ./photos -q 80
+```
+
+## Requirements
+
+- Node.js >= 20
+
+## License
+
+MIT
+
+## Contributing
+
+Issues and PRs welcome at [github.com/PuntoyComaTech/bulki](https://github.com/PuntoyComaTech/bulki).

package/dist/bin/bulki.js

@@ -0,0 +1,331 @@
+#!/usr/bin/env node
+import {
+  VALID_FORMATS,
+  buildJsonOutput,
+  collectImageFiles,
+  detectFormat,
+  formatFileResult,
+  formatSummary,
+  getFormatOptions,
+  hookCommand,
+  optimizeImage,
+  parseSize,
+  processPool,
+  validateOptions,
+  watchCommand
+} from "../chunk-OMZC5IWI.js";
+
+// src/bin/bulki.ts
+import { createRequire as createRequire2 } from "module";
+import { Command as Command4 } from "commander";
+
+// src/commands/compress.ts
+import path from "path";
+import { Command } from "commander";
+
+// src/output/progress.ts
+function createProgressBar(total) {
+  let current = 0;
+  return {
+    tick() {
+      current++;
+      const percent = Math.round(current / total * 100);
+      const barWidth = Math.max(0, Math.min(process.stdout.columns || 40, 40) - 20);
+      const filled = Math.round(current / total * barWidth);
+      const empty = barWidth - filled;
+      const bar = `[${"=".repeat(filled)}${" ".repeat(empty)}] ${percent}% ${current}/${total}`;
+      process.stdout.write(`\r${bar}`);
+      if (current === total) process.stdout.write("\n");
+    }
+  };
+}
+
+// src/commands/compress.ts
+var compressCommand = new Command("compress").description("Compress images in a file or directory").argument("<path>", "File or directory to process").option("-q, --quality <n>", "Output quality (1-100)", (v) => parseInt(v, 10), 70).option("-f, --format <fmt>", "Output format (jpeg, png, webp, gif, avif)").option("-r, --resize <width>", "Resize to width (px)", (v) => parseInt(v, 10)).option("-d, --destination <path>", "Destination directory", ".").option("-o, --output-folder <name>", "Output subfolder name", "bulki-output").option("--concurrency <n>", "Number of parallel operations", (v) => parseInt(v, 10)).option("--exclude <patterns...>", "Directory names to exclude").option("--dry-run", "Show what would be processed without writing files").option("--verbose", "Show per-file output").option("--json", "Output results as JSON").option("--max-size <size>", "Maximum file size budget (e.g., 200kb, 1mb)").action(async (inputPath, opts) => {
+  let options;
+  try {
+    options = validateOptions(opts);
+  } catch (err) {
+    console.error(err.message);
+    process.exit(1);
+  }
+  const resolvedPath = path.resolve(inputPath);
+  let filePaths;
+  let isDirectory;
+  try {
+    const collected = await collectImageFiles(resolvedPath, options.exclude);
+    filePaths = collected.files;
+    isDirectory = collected.isDirectory;
+  } catch {
+    console.error(`Path not found: ${resolvedPath}`);
+    process.exit(1);
+  }
+  if (filePaths.length === 0) {
+    console.log("No images found to process.");
+    return;
+  }
+  if (options.dryRun) {
+    console.log(`Would process ${filePaths.length} image(s)`);
+    for (const f of filePaths) console.log(`  ${path.basename(f.path)}`);
+    return;
+  }
+  const sourcePath = isDirectory ? resolvedPath : path.dirname(resolvedPath);
+  const startTime = performance.now();
+  const progress = !options.verbose && !options.json ? createProgressBar(filePaths.length) : null;
+  const errors = [];
+  const jsonErrors = [];
+  const processedResults = await processPool(
+    filePaths,
+    async (file) => {
+      try {
+        const result = await optimizeImage(file.path, {
+          ...options,
+          sourcePath,
+          detectedFormat: file.format
+        });
+        if (options.verbose && !options.json) {
+          console.log(formatFileResult(result));
+        }
+        progress?.tick();
+        return result;
+      } catch (err) {
+        errors.push(err);
+        jsonErrors.push({ file: file.path, message: err.message });
+        progress?.tick();
+        return null;
+      }
+    },
+    options.concurrency
+  );
+  const validResults = processedResults.filter((r) => r !== null);
+  const totalDuration = performance.now() - startTime;
+  if (options.json) {
+    const output = buildJsonOutput(validResults, jsonErrors, totalDuration);
+    if (options.maxSize) {
+      for (const file of output.files) {
+        if (file.newSize > options.maxSize) {
+          file.exceeded = true;
+        }
+      }
+    }
+    console.log(JSON.stringify(output));
+  } else {
+    console.log(formatSummary(validResults, errors, totalDuration));
+  }
+  if (validResults.length === 0 && errors.length > 0) {
+    process.exit(1);
+  }
+  const maxSize = options.maxSize;
+  if (maxSize) {
+    const exceeded = validResults.filter((r) => r.newSize > maxSize);
+    if (exceeded.length > 0) {
+      if (!options.json) {
+        for (const r of exceeded) {
+          console.warn(`File exceeds size budget: ${r.outputPath}`);
+        }
+      }
+      process.exit(1);
+    }
+  }
+});
+
+// src/commands/mcp.ts
+import { createRequire } from "module";
+import path2 from "path";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { Command as Command2 } from "commander";
+import { z } from "zod";
+var require2 = createRequire(import.meta.url);
+var { version } = require2("../../package.json");
+var mcpCommand = new Command2("mcp").description("Start MCP server for AI editor integration (Claude Code, Cursor, etc.)").action(async () => {
+  const server = new McpServer({
+    name: "bulki",
+    version
+  });
+  server.tool(
+    "compress",
+    "Compress and optimize images. Supports JPEG, PNG, WebP, GIF, AVIF.",
+    {
+      path: z.string().describe("File or directory path to compress"),
+      quality: z.number().min(1).max(100).default(70).describe("Output quality (1-100)"),
+      format: z.enum(["jpeg", "png", "webp", "gif", "avif"]).optional().describe("Output format (omit to keep original)"),
+      resize: z.number().positive().optional().describe("Max width in pixels"),
+      destination: z.string().default(".").describe("Output directory"),
+      outputFolder: z.string().default("bulki-output").describe("Output folder name"),
+      maxSize: z.string().optional().describe("Max file size budget (e.g., 200kb, 1mb)")
+    },
+    async (params) => {
+      if (params.outputFolder.includes("/") || params.outputFolder.includes("\\") || params.outputFolder.includes("..")) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({
+                error: "Invalid outputFolder: must be a simple directory name"
+              })
+            }
+          ]
+        };
+      }
+      const resolvedPath = path2.resolve(params.path);
+      let filePaths;
+      let isDirectory;
+      try {
+        const collected = await collectImageFiles(resolvedPath, []);
+        filePaths = collected.files;
+        isDirectory = collected.isDirectory;
+      } catch {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({ error: `Path not found: ${resolvedPath}` })
+            }
+          ]
+        };
+      }
+      if (filePaths.length === 0) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({ files: [], summary: { totalFiles: 0 } })
+            }
+          ]
+        };
+      }
+      const sourcePath = isDirectory ? resolvedPath : path2.dirname(resolvedPath);
+      const startTime = performance.now();
+      const results = [];
+      const errors = [];
+      let maxSizeBytes;
+      if (params.maxSize) {
+        try {
+          maxSizeBytes = parseSize(params.maxSize);
+        } catch (err) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify({ error: err.message })
+              }
+            ]
+          };
+        }
+      }
+      for (const file of filePaths) {
+        try {
+          const result = await optimizeImage(file.path, {
+            quality: params.quality,
+            format: params.format,
+            resize: params.resize,
+            destination: params.destination,
+            outputFolder: params.outputFolder,
+            concurrency: 1,
+            exclude: [],
+            dryRun: false,
+            verbose: false,
+            json: false,
+            sourcePath,
+            detectedFormat: file.format
+          });
+          results.push(result);
+        } catch (err) {
+          errors.push({ file: file.path, message: err.message });
+        }
+      }
+      const totalDuration = performance.now() - startTime;
+      const output = buildJsonOutput(results, errors, totalDuration);
+      if (maxSizeBytes !== void 0) {
+        for (const file of output.files) {
+          if (file.newSize > maxSizeBytes) {
+            file.exceeded = true;
+          }
+        }
+      }
+      return { content: [{ type: "text", text: JSON.stringify(output, null, 2) }] };
+    }
+  );
+  server.tool(
+    "detect",
+    "Detect if a file is an image and identify its format",
+    {
+      path: z.string().describe("Path to the file")
+    },
+    async (params) => {
+      const resolvedPath = path2.resolve(params.path);
+      const format = await detectFormat(resolvedPath);
+      const result = format ? { format, isImage: true } : { format: null, isImage: false };
+      return { content: [{ type: "text", text: JSON.stringify(result) }] };
+    }
+  );
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+});
+
+// src/commands/pipe.ts
+import { Command as Command3 } from "commander";
+import sharp from "sharp";
+var pipeCommand = new Command3("pipe").description("Read image from stdin, write optimized image to stdout").requiredOption("-f, --format <fmt>", "Output format (jpeg, png, webp, gif, avif)").option("-q, --quality <n>", "Quality (1-100)", (v) => parseInt(v, 10), 70).option("-r, --resize <width>", "Resize to width (px)", (v) => parseInt(v, 10)).action(async (opts) => {
+  const MAX_INPUT_SIZE = 100 * 1024 * 1024;
+  const chunks = [];
+  let totalSize = 0;
+  for await (const chunk of process.stdin) {
+    totalSize += chunk.length;
+    if (totalSize > MAX_INPUT_SIZE) {
+      process.stderr.write("Error: input exceeds 100 MB limit\n");
+      process.exit(1);
+    }
+    chunks.push(chunk);
+  }
+  const input = Buffer.concat(chunks);
+  if (input.length === 0) {
+    process.stderr.write("Error: no input received on stdin\n");
+    process.exit(1);
+  }
+  const format = opts.format;
+  const quality = opts.quality;
+  const resize = opts.resize;
+  if (!VALID_FORMATS.includes(format)) {
+    process.stderr.write(`Error: invalid format "${format}"
+`);
+    process.exit(1);
+  }
+  const outputFormat = format === "jpg" ? "jpeg" : format;
+  const formatOptions = getFormatOptions(quality);
+  try {
+    let pipeline = sharp(input);
+    if (resize) {
+      pipeline = pipeline.resize(resize);
+    }
+    pipeline = pipeline.toFormat(
+      outputFormat,
+      formatOptions[outputFormat] ?? {}
+    );
+    const outputBuffer = await pipeline.toBuffer();
+    process.stdout.write(outputBuffer);
+  } catch (err) {
+    process.stderr.write(`Error: ${err.message}
+`);
+    process.exit(1);
+  }
+});
+
+// src/bin/bulki.ts
+var require3 = createRequire2(import.meta.url);
+var { version: version2 } = require3("../../package.json");
+if (process.argv.length <= 2) {
+  const { runInteractive } = await import("../interactive-LGL325GZ.js");
+  await runInteractive();
+} else {
+  const program = new Command4();
+  program.name("bulki").description("Ultra-fast CLI image optimizer").version(version2);
+  program.addCommand(compressCommand);
+  program.addCommand(hookCommand);
+  program.addCommand(mcpCommand);
+  program.addCommand(pipeCommand);
+  program.addCommand(watchCommand);
+  program.parse();
+}
+//# sourceMappingURL=bulki.js.map