@djangocfg/imgai 1.0.1

package/README.md

@@ -0,0 +1,187 @@
+# @djangocfg/imgai
+
+AI-powered image generation & management for Next.js projects.
+
+## Features
+
+- 🎨 **AI Image Generation** - Generate images using OpenAI DALL-E 3 or Claude
+- 🔍 **Image Scanner** - Automatically find and catalog all images in your project
+- ⚡ **Config Sync** - Generate TypeScript config with all images for type-safe access
+- 📦 **Batch Processing** - Generate multiple images with concurrent workers
+- 🖼️ **Image Optimization** - Automatic resize and format conversion (WebP, AVIF)
+- 🎯 **Beautiful CLI** - Interactive and command-line interfaces
+
+## Installation
+
+```bash
+pnpm add @djangocfg/imgai
+```
+
+## Quick Start
+
+### Interactive Mode
+
+```bash
+npx imgai
+```
+
+### Generate Single Image
+
+```bash
+npx imgai generate "A beautiful sunset over mountains" --filename sunset --category backgrounds
+```
+
+### Scan & Sync
+
+```bash
+# Scan all images
+npx imgai scan
+
+# Generate images.ts config
+npx imgai sync
+```
+
+### Batch Generate
+
+Create a `prompts.json` file:
+
+```json
+[
+  { "prompt": "Abstract blue waves", "filename": "waves" },
+  { "prompt": "Geometric patterns", "filename": "patterns" },
+  "Simple prompt without filename"
+]
+```
+
+Then run:
+
+```bash
+npx imgai batch prompts.json --category abstract --concurrency 2
+```
+
+## Programmatic Usage
+
+```typescript
+import { createImageAI, generateImage, scanImages, syncImagesConfig } from '@djangocfg/imgai';
+
+// Quick helpers
+const result = await generateImage('A beautiful landscape', {
+  projectRoot: process.cwd(),
+});
+
+const images = await scanImages({
+  projectRoot: process.cwd(),
+});
+
+await syncImagesConfig({
+  projectRoot: process.cwd(),
+});
+
+// Full control
+const { generator, scanner, configGenerator } = createImageAI({
+  projectRoot: process.cwd(),
+  provider: 'openai',
+  size: '1792x1024',
+  quality: 'hd',
+  resize: {
+    width: 800,
+    height: 600,
+    format: 'webp',
+    quality: 85,
+  },
+});
+
+// Generate with enhanced prompt
+const enhanced = await generator.enhancePrompt('A tech company landing page hero');
+const image = await generator.generate({
+  prompt: enhanced.prompt,
+  filename: enhanced.filename,
+  category: 'heroes',
+});
+
+// Batch generate
+const batchResult = await generator.generateBatch({
+  items: [
+    { prompt: 'Image 1', category: 'batch' },
+    { prompt: 'Image 2', category: 'batch' },
+  ],
+  concurrency: 2,
+  onProgress: (current, total, result) => {
+    console.log(`${current}/${total}: ${result.success ? '✓' : '✗'}`);
+  },
+});
+
+// Scan images
+const catalog = await scanner.buildCatalog();
+console.log(`Found ${catalog.count} images`);
+
+// Generate images.ts
+await configGenerator.generate();
+```
+
+## Generated Config (images.ts)
+
+After running `imgai sync`, you get a fully typed `images.ts`:
+
+```typescript
+import { getImage, getImageUrl, getImagesByCategory, hasImage } from '@/core/images';
+
+// Type-safe image access
+const heroImage = getImage('hero-landing');
+const heroUrl = getImageUrl('hero-landing');
+
+// Get all images in category
+const backgroundImages = getImagesByCategory('backgrounds');
+
+// Check if image exists
+if (hasImage('my-image')) {
+  // TypeScript knows it exists
+}
+```
+
+## CLI Commands
+
+```
+imgai [interactive]    Start interactive mode (default)
+imgai generate <prompt> Generate single image
+imgai scan             Scan and list all images
+imgai sync             Generate/update images.ts
+imgai batch <file>     Batch generate from JSON file
+```
+
+## Options
+
+### Generate Options
+
+```
+-f, --filename <name>  Output filename
+-c, --category <name>  Category/folder (default: general)
+-r, --root <path>      Project root directory
+-o, --output <path>    Output directory
+--size <size>          Image size (1024x1024, 1792x1024, 1024x1792)
+--quality <quality>    Image quality (standard, hd)
+--style <style>        Style prefix for prompts
+--resize               Enable resize
+--width <pixels>       Resize width
+--height <pixels>      Resize height
+--format <format>      Output format (webp, jpeg, png, avif)
+```
+
+### Scan Options
+
+```
+-r, --root <path>      Project root directory
+-d, --dirs <dirs>      Directories to scan (comma-separated)
+--no-dimensions        Skip reading image dimensions
+```
+
+## Environment Variables
+
+```bash
+OPENAI_API_KEY=sk-...      # Required for image generation
+ANTHROPIC_API_KEY=sk-ant-... # Optional for prompt enhancement with Claude
+```
+
+## License
+
+MIT