{"id":34599133,"url":"https://github.com/flyingrobots/image-dump","last_synced_at":"2026-05-25T21:03:18.770Z","repository":{"id":297142285,"uuid":"995295571","full_name":"flyingrobots/image-dump","owner":"flyingrobots","description":"Image CDN for READMEs and documentation - Optimized WebP/PNG/JPEG assets   hosted via raw.githubusercontent.com","archived":false,"fork":false,"pushed_at":"2025-11-05T22:33:32.000Z","size":460277,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-06T00:18:00.706Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/flyingrobots.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/security/README.md","support":null,"governance":null,"roadmap":"docs/ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-06-03T09:08:33.000Z","updated_at":"2025-10-20T00:31:24.000Z","dependencies_parsed_at":"2025-10-20T01:20:43.335Z","dependency_job_id":"042f4860-8e25-4bf5-be00-6b661102effa","html_url":"https://github.com/flyingrobots/image-dump","commit_stats":null,"previous_names":["flyingrobots/image-dump"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/flyingrobots/image-dump","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flyingrobots%2Fimage-dump","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flyingrobots%2Fimage-dump/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flyingrobots%2Fimage-dump/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flyingrobots%2Fimage-dump/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/flyingrobots","download_url":"https://codeload.github.com/flyingrobots/image-dump/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flyingrobots%2Fimage-dump/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28002250,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-12-24T02:00:07.193Z","response_time":83,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-12-24T12:07:29.285Z","updated_at":"2025-12-24T12:07:39.255Z","avatar_url":"https://github.com/flyingrobots.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🖼️ Image Dump\n\n[![Run Tests](https://github.com/flyingrobots/image-dump/actions/workflows/test.yml/badge.svg)](https://github.com/flyingrobots/image-dump/actions/workflows/test.yml)\n[![Optimize Images](https://github.com/flyingrobots/image-dump/actions/workflows/optimize-images.yml/badge.svg)](https://github.com/flyingrobots/image-dump/actions/workflows/optimize-images.yml)\n\nTransform your repository into a high-performance image CDN. Drop images in, get optimized versions out - automatically, securely, and efficiently.\n\n## What is Image Dump?\n\nImage Dump turns any GitHub repository into a powerful image optimization and delivery system. It automatically converts your images to modern formats (WebP, AVIF), applies smart compression, and serves them directly from GitHub's CDN - all while protecting against malicious files and resource abuse.\n\n### Key Benefits\n\n- **🚀 Zero Infrastructure** - Runs entirely on GitHub Actions, no servers needed\n- **🔒 Enterprise Security** - Built-in protection against malicious images and attacks\n- **⚡ Modern Formats** - Automatic WebP/AVIF conversion for 50-80% smaller files\n- **🎯 Smart Optimization** - Different quality settings per image based on your rules\n- **🐳 No Dependencies** - Everything runs in Docker, works anywhere\n\n## Quick Start\n\n1. **Drop images in the `original/` folder**\n2. **Push to GitHub**\n3. **Find optimized versions in `optimized/`**\n\nThat's it! No configuration needed for basic usage.\n\n```bash\n# Run locally (Docker required, nothing else)\nnpm run optimize\n\n# Force reprocess all images\nnpm run optimize:force\n\n# Watch mode for development\nnpm run optimize:watch\n```\n\nThe `optimize` script now opens a [gum](https://github.com/charmbracelet/gum) picker so you can interactively choose which images to cook. Press \u003ckbd\u003espace\u003c/kbd\u003e to toggle selections and \u003ckbd\u003eenter\u003c/kbd\u003e to start the batch. Set `OPTIMIZE_NO_GUM=1` or run in a non-interactive shell to skip the picker and process everything automatically.\n\n## Features\n\n### 🎨 Image Processing\n- Multiple output formats (WebP, AVIF, JPEG, PNG)\n- Configurable quality levels with per-image rules\n- Automatic format selection based on best compression\n- Thumbnail generation with custom dimensions\n- Metadata preservation or stripping\n- Batch processing with progress tracking\n\n### 🔐 Security \u0026 Validation\n- **File Validation** - Magic byte verification ensures files are real images\n- **Size Protection** - Configurable file size and dimension limits\n- **Attack Prevention** - Blocks ZIP bombs, script injections, and polyglot files\n- **Resource Limits** - CPU and memory caps prevent denial of service\n- **EXIF Sanitization** - Removes potentially harmful metadata\n- **Deep Scanning** - Optional steganography detection\n\n### 🚄 Performance\n- Manifest-based hashing prevents reprocessing unchanged files\n- Concurrent processing with controlled parallelism\n- Git LFS support for large files\n- Resume interrupted batches\n- Real-time progress with ETA\n- Docker-based for consistent performance\n- Gum-powered picker for targeted batches\n\n### ⚙️ Configuration\n- `.imagerc` file for project settings\n- Per-directory quality rules\n- Pattern-based quality matching\n- Size-based optimization rules\n- CLI flags for one-off adjustments\n- Environment variable support\n\n## Configuration\n\nCreate `.imagerc` in your project root:\n\n```json\n{\n  \"formats\": [\"webp\", \"avif\", \"original\"],\n  \"quality\": {\n    \"webp\": 85,\n    \"avif\": 80,\n    \"jpeg\": 90\n  },\n  \"outputDir\": \"optimized\",\n  \"generateThumbnails\": true,\n  \"thumbnailWidth\": 200,\n  \"preserveMetadata\": false,\n  \"parallelBatchSize\": 5,\n  \"security\": {\n    \"maxFileSize\": 52428800,\n    \"maxDimensions\": { \"width\": 10000, \"height\": 10000 },\n    \"enableDeepValidation\": true\n  }\n}\n```\n\n### Advanced Quality Rules\n\nApply different settings based on patterns, directories, or image dimensions:\n\n```json\n{\n  \"qualityRules\": [\n    {\n      \"pattern\": \"*-hero.jpg\",\n      \"quality\": { \"webp\": 95, \"avif\": 90 }\n    },\n    {\n      \"directory\": \"products/\",\n      \"quality\": { \"webp\": 85 }\n    },\n    {\n      \"minWidth\": 2000,\n      \"quality\": { \"jpeg\": 95, \"webp\": 90 }\n    }\n  ]\n}\n```\n\n### Security Configuration\n\n```json\n{\n  \"security\": {\n    \"maxFileSize\": 52428800,              // 50MB limit\n    \"allowedFormats\": [\"jpg\", \"jpeg\", \"png\", \"webp\", \"gif\"],\n    \"detectPolyglot\": true,               // Detect hidden file types\n    \"sanitizeExif\": true,                 // Remove GPS data, comments\n    \"resourceLimits\": {\n      \"maxMemory\": 1073741824,            // 1GB memory limit\n      \"maxCpuTime\": 30000,                // 30 second CPU limit\n      \"maxConcurrency\": 5                 // Process 5 images at once\n    }\n  }\n}\n```\n\n## CLI Usage\n\n```bash\n# Basic optimization\nnpm run optimize\n\n# With options\nnpm run optimize -- --quality=95 --format=webp\n\n# Continue after errors\nnpm run optimize -- --continue-on-error\n\n# Resume interrupted batch\nnpm run optimize -- --resume\n\n# Quiet mode (no progress bar)\nnpm run optimize -- --quiet\n\n# Custom config file\nnpm run optimize -- --config=production.imagerc\n```\n\n## Cache Manifest\n\nEach optimization run maintains an `optimized/.image-manifest.json` file that records the SHA-256 digest of every cooked source image and the outputs that were generated. The manifest allows the optimizer to skip work reliably—even if timestamps change—and doubles as a quick audit log of what was produced. Commit it alongside your optimized assets, or delete it to force a full rebuild on the next run.\n\n## GitHub Actions\n\nAutomatic optimization on every push:\n\n```yaml\nname: Optimize Images\non:\n  push:\n    paths:\n      - 'original/**'\n      - '.imagerc'\n\njobs:\n  optimize:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      - uses: actions/setup-node@v4\n      - run: npm ci\n      - run: npm run optimize\n      - uses: stefanzweifel/git-auto-commit-action@v5\n        with:\n          commit_message: 'Optimize images'\n```\n\n## Using Optimized Images\n\n### In Markdown\n```markdown\n![Product](https://raw.githubusercontent.com/username/repo/main/optimized/product.webp)\n```\n\n### In HTML (with fallbacks)\n```html\n\u003cpicture\u003e\n  \u003csource srcset=\"optimized/hero.avif\" type=\"image/avif\"\u003e\n  \u003csource srcset=\"optimized/hero.webp\" type=\"image/webp\"\u003e\n  \u003cimg src=\"optimized/hero.jpg\" alt=\"Hero image\" loading=\"lazy\"\u003e\n\u003c/picture\u003e\n```\n\n### Direct CDN URLs\n```\nhttps://raw.githubusercontent.com/username/repo/main/optimized/image.webp\nhttps://cdn.jsdelivr.net/gh/username/repo@main/optimized/image.webp\n```\n\n## Installation\n\n### As GitHub Template\n1. Click \"Use this template\" on GitHub\n2. Clone your new repository\n3. Start adding images to `original/`\n\n### In Existing Project\n```bash\n# Clone the repo\ngit clone https://github.com/flyingrobots/image-dump.git\ncd image-dump\n\n# Copy core files to your project\ncp -r scripts src package.json docker-compose.yml .dockerignore /your/project/\n\n# Install dependencies (optional - everything runs in Docker)\nnpm install\n```\n\n## Development\n\n```bash\n# First time setup\n./scripts/setup-dev.sh\n\n# Run tests (in Docker, same as CI)\nnpm test\n\n# Watch tests\nnpm run test:watch\n\n# Lint code\nnpm run lint\n\n# Build Docker images\nmake build\n```\n\n### Project Structure\n```\nimage-dump/\n├── original/           # Source images (your input)\n├── optimized/          # Optimized images (output)\n├── scripts/            # CLI and optimization scripts\n├── src/                # Core processing modules\n│   ├── lib/           # Image processing components\n│   └── security/      # Security validation modules\n├── tests/             # Comprehensive test suite\n├── docs/              # Documentation\n└── .github/           # GitHub Actions workflows\n```\n\n## Security Features\n\nImage Dump includes enterprise-grade security out of the box:\n\n### 🛡️ Input Validation\n- Magic byte verification (prevents fake images)\n- File size limits (prevents resource exhaustion)\n- Dimension limits (prevents memory bombs)\n- Format whitelist (only safe formats allowed)\n\n### 🚨 Attack Prevention\n- **ZIP Bomb Detection** - Identifies compressed archives hiding as images\n- **Script Injection** - Blocks SVG files with embedded JavaScript\n- **Polyglot Files** - Detects files trying to be multiple formats\n- **EXIF Exploits** - Sanitizes metadata that could contain malicious code\n\n### 🔒 Resource Protection\n- Memory usage limits per operation\n- CPU time limits to prevent infinite loops\n- Concurrent operation throttling\n- Graceful degradation under load\n\n## Performance\n\nTypical optimization results:\n- **JPEG → WebP**: 25-35% smaller\n- **PNG → WebP**: 50-80% smaller  \n- **Any → AVIF**: 50-85% smaller (with slight quality trade-off)\n\nProcessing speed:\n- ~100-200ms per image (1-2 MP)\n- ~300-500ms per image (5-10 MP)\n- Parallel processing of 5 images by default\n\n## Roadmap\n\n- ✅ **Phase 1-4**: Core features, security, configuration (COMPLETE)\n- 🚧 **Phase 5**: Web UI and REST API\n- 📋 **Phase 6**: VS Code extension, GitHub App\n- 📋 **Phase 7**: AI-powered optimization, CDN integration\n\n## Contributing\n\nWe welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\nAreas we'd love help with:\n- Additional image format support\n- Performance optimizations\n- Security enhancements\n- Documentation improvements\n- Test coverage expansion\n\n## License\n\nMIT - See [LICENSE](LICENSE) for details.\n\n---\n\n\u003cp align=\"center\"\u003e\nBuilt with ❤️ for developers who care about performance\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/flyingrobots/image-dump/issues\"\u003eReport Bug\u003c/a\u003e •\n  \u003ca href=\"https://github.com/flyingrobots/image-dump/discussions\"\u003eDiscussions\u003c/a\u003e •\n  \u003ca href=\"docs/\"\u003eDocumentation\u003c/a\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflyingrobots%2Fimage-dump","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fflyingrobots%2Fimage-dump","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflyingrobots%2Fimage-dump/lists"}