bunki 0.6.1 → 0.7.0

package/README.md

@@ -4,7 +4,7 @@
 [![Coverage Status](https://coveralls.io/repos/github/kahwee/bunki/badge.svg?branch=main)](https://coveralls.io/github/kahwee/bunki?branch=main)
 [![npm version](https://badge.fury.io/js/bunki.svg)](https://badge.fury.io/js/bunki)
 
-Fast static site generator for blogs and documentation built with Bun. Supports Markdown + frontmatter, tags, year-based archives, pagination, RSS feeds, sitemaps, secure HTML sanitization, syntax highlighting, PostCSS pipelines, image uploads (S3/R2), and Nunjucks templating.
+Fast static site generator for blogs and documentation built with Bun. Supports Markdown + frontmatter, tags, year-based archives, pagination, RSS feeds, sitemaps, secure HTML sanitization, syntax highlighting, PostCSS pipelines, media uploads (images & videos to S3/R2), incremental uploads with year filtering, and Nunjucks templating.
 
 ## Install
 
@@ -124,22 +124,411 @@ CSS is processed automatically during `bunki generate`.
 
 ## Image Management
 
-Upload images to Cloudflare R2 or S3:
+### Overview
+
+The `images:push` command uploads local media (images and videos) to Cloudflare R2, AWS S3, or any S3-compatible storage provider. Media files are organized by year in the `images/` directory and uploaded with their full directory structure preserved.
+
+**Supported formats:**
+
+- **Images:** JPG, JPEG, PNG, GIF, WebP, SVG
+- **Video:** MP4
+
+### Directory Structure
+
+Organize images by year and post slug:
+
+```
+images/
+├── 2023/
+│   ├── post-slug-1/
+│   │   ├── image-1.jpg
+│   │   └── image-2.png
+│   └── post-slug-2/
+│       └── photo.webp
+├── 2024/
+│   └── travel-guide/
+│       ├── paris-1.jpg
+│       ├── london-2.jpg
+│       ├── tokyo-3.png
+│       └── travel-vlog.mp4
+└── 2025/
+    └── new-post/
+        ├── screenshot.jpg
+        └── demo-video.mp4
+```
+
+The directory structure is preserved when uploading to cloud storage.
+
+### Configuration
+
+Add S3/R2 configuration to `bunki.config.ts`:
+
+```typescript
+import { SiteConfig } from "bunki";
+
+export default (): SiteConfig => ({
+  title: "My Blog",
+  // ... other config
+
+  // Image upload configuration
+  s3: {
+    accessKeyId: process.env.S3_ACCESS_KEY_ID || "",
+    secretAccessKey: process.env.S3_SECRET_ACCESS_KEY || "",
+    bucket: process.env.S3_BUCKET || "",
+    endpoint: process.env.S3_ENDPOINT, // Optional: for R2, etc.
+    region: process.env.S3_REGION || "auto",
+    publicUrl: process.env.S3_PUBLIC_URL || "",
+  },
+});
+```
+
+### Environment Variables
+
+Set these in your `.env` file or export them in your shell:
+
+```bash
+# Required
+export S3_ACCESS_KEY_ID="your-access-key"
+export S3_SECRET_ACCESS_KEY="your-secret-key"
+export S3_BUCKET="your-bucket-name"
+export S3_PUBLIC_URL="https://cdn.example.com"
+
+# Optional (for Cloudflare R2 or custom endpoints)
+export S3_ENDPOINT="https://r2.cloudflarestorage.com"
+export S3_REGION="auto"
+
+# Optional (custom domain per bucket)
+export S3_CUSTOM_DOMAIN_YOUR_BUCKET="cdn.example.com"
+```
+
+### Basic Usage
+
+Upload all images:
+
+```bash
+bunki images:push
+```
+
+This command:
+
+1. Scans the `images/` directory recursively
+2. Uploads all supported image formats
+3. Preserves the directory structure (year/slug/filename)
+4. Generates public URLs for each image
+
+### Command Options
+
+#### `--images <dir>`
+
+Specify a custom images directory (default: `./images`)
+
+```bash
+bunki images:push --images ./assets/images
+```
+
+#### `--domain <domain>`
+
+Set a custom domain for bucket identification (optional)
+
+```bash
+bunki images:push --domain my-blog
+```
+
+#### `--output-json <file>`
+
+Export a JSON mapping of filenames to their public URLs
+
+```bash
+bunki images:push --output-json image-urls.json
+```
+
+This creates a JSON file with the structure:
+
+```json
+{
+  "2023/post-slug/image.jpg": "https://cdn.example.com/2023/post-slug/image.jpg",
+  "2024/travel/paris.jpg": "https://cdn.example.com/2024/travel/paris.jpg"
+}
+```
+
+#### `--min-year <year>`
+
+Upload only images from the specified year onwards
+
+```bash
+# Upload only 2023 and 2024 images (skip 2021, 2022)
+bunki images:push --min-year 2023
+
+# Upload only 2024 and newer images
+bunki images:push --min-year 2024
+
+# Upload from 2022 onwards (all images in this example)
+bunki images:push --min-year 2022
+```
+
+This is useful for:
+
+- Incremental uploads (upload only new images)
+- Testing uploads for specific years
+- Managing large image collections across multiple uploads
+
+### Complete Examples
+
+#### Cloudflare R2 Setup
+
+1. **Create R2 bucket and API token** in Cloudflare dashboard
+
+2. **Set environment variables:**
+
+```bash
+export S3_ACCESS_KEY_ID="your-r2-api-token-id"
+export S3_SECRET_ACCESS_KEY="your-r2-api-token-secret"
+export S3_BUCKET="my-blog-images"
+export S3_ENDPOINT="https://r2.cloudflarestorage.com"
+export S3_REGION="auto"
+export S3_PUBLIC_URL="https://cdn.example.com"
+```
+
+3. **Upload images:**
+
+```bash
+bunki images:push --output-json image-urls.json
+```
+
+#### AWS S3 Setup
+
+1. **Create S3 bucket and IAM user** in AWS Console
+
+2. **Set environment variables:**
+
+```bash
+export S3_ACCESS_KEY_ID="AKIAIOSFODNN7EXAMPLE"
+export S3_SECRET_ACCESS_KEY="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
+export S3_BUCKET="my-blog-bucket"
+export S3_REGION="us-east-1"
+export S3_PUBLIC_URL="https://my-blog-bucket.s3.amazonaws.com"
+```
+
+3. **Upload images:**
+
+```bash
+bunki images:push
+```
+
+#### Incremental Upload (Year-Based)
+
+If you have thousands of images and want to upload them incrementally:
+
+```bash
+# First, upload all 2023 images
+bunki images:push --min-year 2023 --max-year 2023
+
+# Next, upload 2024 images
+bunki images:push --min-year 2024 --max-year 2024
+
+# Finally, upload 2025 images
+bunki images:push --min-year 2025
+```
+
+### Using Uploaded Images in Markdown
+
+After uploading, reference images in your Markdown posts:
+
+```markdown
+---
+title: "Paris Trip"
+date: 2024-06-15T10:00:00
+tags: [travel, france]
+---
+
+# My Trip to Paris
+
+![Eiffel Tower at sunset](https://cdn.example.com/2024/paris-trip/eiffel-tower.jpg)
+
+![Louvre Museum](https://cdn.example.com/2024/paris-trip/louvre.jpg)
+
+## Evening Stroll
+
+The Parisian streets at night are magical.
+
+![Seine River at night](https://cdn.example.com/2024/paris-trip/seine-night.jpg)
+```
+
+### Using Uploaded Videos in Markdown
+
+Upload MP4 videos alongside your images and embed them in your posts:
+
+```markdown
+---
+title: "Travel Vlog"
+date: 2024-06-15T10:00:00
+tags: [travel, video]
+---
+
+# My Paris Adventure
+
+Watch my trip to Paris:
+
+<video controls width="640" height="360">
+  <source src="https://cdn.example.com/2024/paris-trip/travel-vlog.mp4" type="video/mp4">
+  Your browser does not support HTML5 video.
+</video>
+
+## Behind the Scenes
+
+Check out the making of the vlog:
+
+<video controls width="640" height="360">
+  <source src="https://cdn.example.com/2024/paris-trip/behind-scenes.mp4" type="video/mp4">
+  Your browser does not support HTML5 video.
+</video>
+```
+
+**Video Upload Example:**
+
+```bash
+# Upload all images and videos (including MP4 files)
+bunki images:push
+
+# Upload only 2024 videos and images
+bunki images:push --min-year 2024
+
+# Preview what would be uploaded without actually uploading
+BUNKI_DRY_RUN=true bunki images:push --min-year 2024
+```
+
+**Video File Organization:**
+
+Keep videos organized the same way as images for consistency:
+
+```
+images/
+├── 2024/
+│   └── travel-vlog/
+│       ├── intro.mp4
+│       ├── highlights.mp4
+│       ├── thumbnail.jpg
+│       └── poster.jpg
+└── 2025/
+    └── tutorial/
+        ├── part-1.mp4
+        ├── part-2.mp4
+        └── preview.jpg
+```
+
+**Video Tips:**
+
+1. **File Size**: Keep MP4 files optimized (under 50MB recommended)
+   - Use tools like FFmpeg to compress before uploading
+   - Example: `ffmpeg -i input.mp4 -crf 28 output.mp4`
+
+2. **Format & Codec**:
+   - Use H.264 video codec for best compatibility
+   - Use AAC audio codec
+   - Container: MP4 (.mp4 extension)
+
+3. **Video Dimensions**:
+   - Keep 16:9 aspect ratio for web
+   - Common resolutions: 640x360, 1280x720, 1920x1080
+
+4. **Hosting**:
+   - MP4s benefit from CDN caching via S3/R2
+   - Cloudflare R2 provides excellent video delivery
+   - AWS S3 with CloudFront for additional acceleration
+
+### Dry Run Mode
+
+Test the upload process without actually uploading:
+
+```bash
+# Preview what would be uploaded (no actual upload)
+BUNKI_DRY_RUN=true bunki images:push
+```
+
+This shows:
+
+- Which images would be uploaded
+- The directory structure that would be created
+- Generated public URLs
+
+### Troubleshooting
+
+#### "Missing S3 configuration"
+
+Ensure all required environment variables are set. Check `bunki.config.ts` and your `.env` file.
+
+#### "No image files found"
+
+- Verify images exist in `images/` directory
+- Check that files have supported extensions (.jpg, .png, .gif, .webp, .svg)
+- Ensure the directory structure is correct (e.g., `images/2024/post-slug/image.jpg`)
+
+#### "Unauthorized" or "Access Denied"
+
+- Verify S3 credentials (access key and secret key)
+- Check that the IAM user/API token has S3 permissions
+- Confirm the bucket name is correct
+
+#### "Invalid bucket name"
+
+- S3 bucket names must be globally unique
+- Use only lowercase letters, numbers, and hyphens
+- Bucket names must be 3-63 characters long
+
+### Advanced Configuration
+
+#### Custom Domain per Bucket
+
+If you have multiple S3 buckets with different custom domains:
 
 ```bash
-# Set up environment variables first
-cat > .env << EOF
-R2_ACCESS_KEY_ID=...
-R2_SECRET_ACCESS_KEY=...
-R2_BUCKET=...
-R2_PUBLIC_URL=https://cdn.example.com
-EOF
+export S3_CUSTOM_DOMAIN_MY_BUCKET="cdn1.example.com"
+export S3_CUSTOM_DOMAIN_BACKUP_BUCKET="cdn2.example.com"
+```
+
+The bucket name is converted to uppercase and hyphens to underscores for the environment variable name.
+
+#### Direct CDN URLs
+
+Configure public URLs with custom domains:
+
+```typescript
+// bunki.config.ts
+s3: {
+  // ... other config
+  publicUrl: "https://img.example.com",
+}
+```
+
+Or via environment variable:
 
-# Upload images
-bunki images:push --images ./images --output-json image-map.json
+```bash
+export S3_PUBLIC_URL="https://img.example.com"
 ```
 
-Supported formats: JPG, PNG, GIF, WebP, SVG
+### Performance Tips
+
+1. **Use year-based filtering** for large image collections:
+
+   ```bash
+   bunki images:push --min-year 2024  # Only newest images
+   ```
+
+2. **Organize by post slug** for better directory structure:
+
+   ```
+   images/2024/post-title/image.jpg
+   images/2024/post-title/photo.jpg
+   ```
+
+3. **Compress images before uploading** to save storage:
+   - Use tools like `imagemin` or built-in OS utilities
+   - Aim for 500KB or smaller per image
+
+4. **Use modern formats** (WebP) for better compression:
+   - JPG/PNG for screenshots
+   - WebP for photos
+   - SVG for icons/graphics
 
 ## CLI Commands
 
@@ -177,7 +566,8 @@ dist/
 - **Performance**: Static files, optional gzip, optimized output
 - **Templating**: Nunjucks with custom filters and macros
 - **Styling**: Built-in PostCSS support for modern CSS frameworks
-- **Images**: Direct S3/R2 uploads with URL mapping
+- **Media Management**: Direct S3/R2 uploads for images and MP4 videos with URL mapping
+- **Incremental Uploads**: Year-based filtering (`--min-year`) for large media collections
 - **SEO**: Automatic RSS feeds, sitemaps, meta tags
 - **Pagination**: Configurable posts per page
 - **Archives**: Year-based and tag-based organization
@@ -216,7 +606,21 @@ bunki/
 
 ## Changelog
 
-### v0.5.3 (Current)
+### v0.7.0 (Current)
+
+- **Media uploads**: Added MP4 video support alongside image uploads
+- **Incremental uploads**: Year-based filtering with `--min-year` option
+- **Enhanced documentation**: Comprehensive video upload guide with examples
+- **Test coverage**: Added 10+ tests for image/video uploader functionality
+- **Fixed timestamps**: Stable dates in test fixtures to prevent flipping
+
+### v0.6.1
+
+- Version bump and welcome date stabilization
+- Test formatting improvements
+- Code style consistency updates
+
+### v0.5.3
 
 - Modularized CLI commands with dependency injection
 - Enhanced test coverage (130+ tests, 539+ assertions)

package/dist/cli/commands/images-push.d.ts

@@ -9,6 +9,7 @@ export declare function handleImagesPushCommand(options: {
     domain?: string;
     images: string;
     outputJson?: string;
+    minYear?: string;
 }, deps?: ImagesPushDeps): Promise<void>;
 export declare function registerImagesPushCommand(program: Command): Command;
 export {};

package/dist/cli.js

@@ -28255,7 +28255,14 @@ async function processCSS(options2) {
 }
 function runPostCSS(inputPath, outputPath, configPath, projectRoot, verbose) {
   return new Promise((resolve, reject) => {
-    const args = ["postcss", inputPath, "-o", outputPath, "--config", configPath];
+    const args = [
+      "postcss",
+      inputPath,
+      "-o",
+      outputPath,
+      "--config",
+      configPath
+    ];
     const postcss = spawn("bunx", args, {
       stdio: verbose ? "inherit" : ["ignore", "pipe", "pipe"],
       cwd: projectRoot
@@ -33595,8 +33602,11 @@ class S3Uploader {
       }
     }
   }
-  async uploadImages(imagesDir) {
+  async uploadImages(imagesDir, minYear) {
     console.log(`[S3] Uploading all images from ${imagesDir} to bucket ${this.s3Config.bucket}...`);
+    if (minYear) {
+      console.log(`[S3] Filtering images from year ${minYear} onwards`);
+    }
     const imageUrls = {};
     try {
       console.log(`[S3] Checking if directory exists: ${imagesDir}`);
@@ -33639,8 +33649,19 @@ class S3Uploader {
         cwd: imagesDir,
         absolute: false
       })) {
-        console.log(`[S3] Found image file: ${file}`);
-        files.push(file);
+        if (minYear) {
+          const yearMatch = file.match(/^(\d{4})\//);
+          if (yearMatch) {
+            const fileYear = parseInt(yearMatch[1], 10);
+            if (fileYear >= minYear) {
+              console.log(`[S3] Found image file: ${file}`);
+              files.push(file);
+            }
+          }
+        } else {
+          console.log(`[S3] Found image file: ${file}`);
+          files.push(file);
+        }
       }
       const imageFiles = files;
       if (imageFiles.length === 0) {
@@ -33715,8 +33736,11 @@ async function uploadImages(options2 = {}) {
       };
     }
     console.log(`Uploading images from ${imagesDir} to bucket ${s3Config.bucket}`);
+    if (options2.minYear) {
+      console.log(`Filtering images from year ${options2.minYear} onwards`);
+    }
     const uploader = createUploader(s3Config);
-    const imageUrlMap = await uploader.uploadImages(imagesDir);
+    const imageUrlMap = await uploader.uploadImages(imagesDir, options2.minYear);
     if (options2.outputJson) {
       const outputFile = path8.resolve(options2.outputJson);
       await Bun.write(outputFile, JSON.stringify(imageUrlMap, null, 2));
@@ -33734,7 +33758,7 @@ Image upload completed successfully!`);
     return imageUrlMap;
   } catch (error) {
     console.error("Error uploading images:", error);
-    process.exit(1);
+    throw error;
   }
 }
 
@@ -33749,7 +33773,8 @@ async function handleImagesPushCommand(options2, deps = defaultDeps3) {
     await deps.uploadImages({
       domain: options2.domain,
       images: options2.images,
-      outputJson: options2.outputJson
+      outputJson: options2.outputJson,
+      minYear: options2.minYear ? parseInt(options2.minYear, 10) : undefined
     });
   } catch (error) {
     deps.logger.error("Error uploading images:", error);
@@ -33757,7 +33782,7 @@ async function handleImagesPushCommand(options2, deps = defaultDeps3) {
   }
 }
 function registerImagesPushCommand(program2) {
-  return program2.command("images:push").description("Upload images to S3-compatible storage").option("-d, --domain <domain>", "Domain name for bucket identification (defaults to domain in bunki.config.ts)").option("-i, --images <dir>", "Images directory path", DEFAULT_IMAGES_DIR).option("--output-json <file>", "Output URL mapping to JSON file").action(async (options2) => {
+  return program2.command("images:push").description("Upload images to S3-compatible storage").option("-d, --domain <domain>", "Domain name for bucket identification (defaults to domain in bunki.config.ts)").option("-i, --images <dir>", "Images directory path", DEFAULT_IMAGES_DIR).option("--output-json <file>", "Output URL mapping to JSON file").option("--min-year <year>", "Only upload images from the specified year onwards (e.g., 2023 uploads 2023, 2024, etc.)").action(async (options2) => {
     await handleImagesPushCommand(options2);
   });
 }
@@ -34234,7 +34259,7 @@ function getDefaultCss() {
 function getSamplePost() {
   return `---
 title: Welcome to Bunki
-date: ${new Date().toISOString()}
+date: 2025-01-15T12:00:00Z
 tags: [getting-started, bunki]
 ---
 

package/dist/index.js

@@ -30815,7 +30815,14 @@ async function processCSS(options2) {
 }
 function runPostCSS(inputPath, outputPath, configPath, projectRoot, verbose) {
   return new Promise((resolve, reject) => {
-    const args = ["postcss", inputPath, "-o", outputPath, "--config", configPath];
+    const args = [
+      "postcss",
+      inputPath,
+      "-o",
+      outputPath,
+      "--config",
+      configPath
+    ];
     const postcss = spawn("bunx", args, {
       stdio: verbose ? "inherit" : ["ignore", "pipe", "pipe"],
       cwd: projectRoot
@@ -31502,8 +31509,11 @@ class S3Uploader {
       }
     }
   }
-  async uploadImages(imagesDir) {
+  async uploadImages(imagesDir, minYear) {
     console.log(`[S3] Uploading all images from ${imagesDir} to bucket ${this.s3Config.bucket}...`);
+    if (minYear) {
+      console.log(`[S3] Filtering images from year ${minYear} onwards`);
+    }
     const imageUrls = {};
     try {
       console.log(`[S3] Checking if directory exists: ${imagesDir}`);
@@ -31546,8 +31556,19 @@ class S3Uploader {
         cwd: imagesDir,
         absolute: false
       })) {
-        console.log(`[S3] Found image file: ${file}`);
-        files.push(file);
+        if (minYear) {
+          const yearMatch = file.match(/^(\d{4})\//);
+          if (yearMatch) {
+            const fileYear = parseInt(yearMatch[1], 10);
+            if (fileYear >= minYear) {
+              console.log(`[S3] Found image file: ${file}`);
+              files.push(file);
+            }
+          }
+        } else {
+          console.log(`[S3] Found image file: ${file}`);
+          files.push(file);
+        }
       }
       const imageFiles = files;
       if (imageFiles.length === 0) {
@@ -31622,8 +31643,11 @@ async function uploadImages(options2 = {}) {
       };
     }
     console.log(`Uploading images from ${imagesDir} to bucket ${s3Config.bucket}`);
+    if (options2.minYear) {
+      console.log(`Filtering images from year ${options2.minYear} onwards`);
+    }
     const uploader = createUploader(s3Config);
-    const imageUrlMap = await uploader.uploadImages(imagesDir);
+    const imageUrlMap = await uploader.uploadImages(imagesDir, options2.minYear);
     if (options2.outputJson) {
       const outputFile = path7.resolve(options2.outputJson);
       await Bun.write(outputFile, JSON.stringify(imageUrlMap, null, 2));
@@ -31641,7 +31665,7 @@ Image upload completed successfully!`);
     return imageUrlMap;
   } catch (error) {
     console.error("Error uploading images:", error);
-    process.exit(1);
+    throw error;
   }
 }
 export {

package/dist/types.d.ts

@@ -146,9 +146,10 @@ export interface ImageUploader {
     /**
      * Upload all images from a directory
      * @param imagesDir Directory containing images to upload
+     * @param minYear Optional minimum year to filter (e.g., 2023 uploads 2023, 2024, etc.)
      * @returns Record of image filenames to their public URLs
      */
-    uploadImages(imagesDir: string): Promise<Record<string, string>>;
+    uploadImages(imagesDir: string, minYear?: number): Promise<Record<string, string>>;
 }
 /**
  * S3 configuration type
@@ -169,4 +170,5 @@ export interface ImageUploadOptions {
     domain?: string;
     images?: string;
     outputJson?: string;
+    minYear?: number;
 }

package/dist/utils/s3-uploader.d.ts

@@ -13,7 +13,7 @@ export declare class S3Uploader implements Uploader, ImageUploader {
      * @returns The public URL for the file
      */
     private getPublicUrl;
-    uploadImages(imagesDir: string): Promise<Record<string, string>>;
+    uploadImages(imagesDir: string, minYear?: number): Promise<Record<string, string>>;
 }
 /**
  * Create an S3 uploader

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bunki",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "An opinionated static site generator built with Bun featuring PostCSS integration and modern web development workflows",
   "main": "dist/index.js",
   "module": "dist/index.mjs",