bunki 0.19.6 → 0.21.1

package/README.md

@@ -8,19 +8,24 @@ Fast static site generator for blogs and documentation built with Bun. Supports
 
 ## Install
 
-Requires **Bun v1.3.0+** (recommended) or Node.js v18+
+Requires **Bun v1.3.14+**. Bun v1.3.14 is the latest stable Bun release currently supported by this project. Bun is the supported runtime for installing, building, testing, and running Bunki.
 
-```bash
-# Install globally with Bun
-bun install -g bunki
+Check your runtime before working on Bunki:
 
-# Or with npm
-npm install -g bunki
+```bash
+bun --version  # should report 1.3.14 or newer
+```
 
-# Or in your project
+```bash
+# Install in your project
 bun install bunki
+
+# Or install the CLI globally with Bun
+bun install -g bunki
 ```
 
+Do not use `npm`, `yarn`, or `pnpm` for Bunki workflows. The CLI, scripts, and test suite are designed for Bun.
+
 ## Quick Start
 
 ```bash
@@ -55,19 +60,22 @@ export default (): SiteConfig => ({
 
   // Optional: Image upload to Cloudflare R2 or S3
   s3: {
-    accessKeyId: process.env.R2_ACCESS_KEY_ID || "",
-    secretAccessKey: process.env.R2_SECRET_ACCESS_KEY || "",
-    bucket: process.env.R2_BUCKET || "",
-    endpoint: process.env.R2_ENDPOINT,
-    region: process.env.R2_REGION || "auto",
-    publicUrl: process.env.R2_PUBLIC_URL || "",
+    accessKeyId: process.env.S3_ACCESS_KEY_ID || "",
+    secretAccessKey: process.env.S3_SECRET_ACCESS_KEY || "",
+    bucket: process.env.S3_BUCKET || "",
+    endpoint: process.env.S3_ENDPOINT,
+    region: process.env.S3_REGION || "auto",
+    publicUrl: process.env.S3_PUBLIC_URL || "",
   },
 });
 ```
 
 ## Content & Frontmatter
 
-Create Markdown files in `content/YYYY/` using either pattern:
+Create Markdown files anywhere under `content/` using either pattern:
+
+- Year folders are a good fit for organizing posts and colocated assets.
+- The published URL year comes from the post date in frontmatter, not the file path.
 
 **Option 1: Single file** (traditional)
 
@@ -466,19 +474,19 @@ Fragments are standard Nunjucks macro files. You can place your own in your site
 
 ### 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.
+The `images:push` command uploads local media (images, SVG, and videos) to Cloudflare R2, AWS S3, or any S3-compatible storage provider. Media files are organized by year in the `assets/` directory and uploaded with their full directory structure preserved.
 
 **Supported formats:**
 
 - **Images:** JPG, JPEG, PNG, GIF, WebP, SVG
-- **Video:** MP4
+- **Video:** MP4, WebM, MOV
 
 ### Directory Structure
 
 Organize images by year and post slug:
 
 ```
-images/
+assets/
 ├── 2023/
 │   ├── post-slug-1/
 │   │   ├── image-1.jpg
@@ -551,7 +559,7 @@ bunki images:push
 
 This command:
 
-1. Scans the `images/` directory recursively
+1. Scans the `assets/` directory recursively by default
 2. Uploads all supported image formats
 3. Preserves the directory structure (year/slug/filename)
 4. Generates public URLs for each image
@@ -560,7 +568,7 @@ This command:
 
 #### `--images <dir>`
 
-Specify a custom images directory (default: `./images`)
+Specify a custom images directory (default: `./assets`)
 
 ```bash
 bunki images:push --images ./assets/images
@@ -612,6 +620,15 @@ This is useful for:
 - Testing uploads for specific years
 - Managing large image collections across multiple uploads
 
+#### `--max-year <year>`
+
+Upload only images up to and including the specified year
+
+```bash
+# Upload only 2023 and older images
+bunki images:push --max-year 2023
+```
+
 #### `--content-assets`
 
 Upload images that are co-located with markdown files instead of the top-level `assets/` directory.
@@ -775,7 +792,7 @@ Check out the making of the vlog:
 **Video Upload Example:**
 
 ```bash
-# Upload all images and videos (including MP4 files)
+# Upload all images and videos (including MP4, WebM, and MOV files)
 bunki images:push
 
 # Upload only 2024 videos and images
@@ -847,9 +864,9 @@ Ensure all required environment variables are set. Check `bunki.config.ts` and y
 
 #### "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`)
+- Verify images exist in `assets/` directory
+- Check that files have supported extensions (.jpg, .jpeg, .png, .gif, .webp)
+- Ensure the directory structure is correct (e.g., `assets/2024/post-slug/image.jpg`)
 
 #### "Unauthorized" or "Access Denied"
 
@@ -966,7 +983,7 @@ export S3_PUBLIC_URL="https://img.example.com"
 4. **Use modern formats** (WebP) for better compression:
    - JPG/PNG for screenshots
    - WebP for photos
-   - SVG for icons/graphics
+   - SVG for icons/graphics in site assets
 
 ## Incremental Builds
 
@@ -1084,7 +1101,7 @@ Version 2.0.0 cache structure:
 
 ### Future Optimizations
 
-Current implementation (v0.18.0) optimizes parsing and CSS processing. Future versions may add:
+Current implementation (v0.21.0) optimizes parsing and CSS processing. Future versions may add:
 
 - Selective page regeneration (only rebuild changed posts)
 - Incremental sitemap/RSS updates
@@ -1093,14 +1110,17 @@ Current implementation (v0.18.0) optimizes parsing and CSS processing. Future ve
 ## CLI Commands
 
 ```bash
-bunki init [--config FILE]                    # Initialize new site
-bunki new <TITLE> [--tags TAG1,TAG2]          # Create new post
-bunki generate [--config FILE]                # Build static site (full)
-bunki generate --incremental                  # Build with caching (3x faster)
-bunki validate [--config FILE]                # Validate frontmatter
-bunki serve [--port 3000]                     # Start dev server
-bunki css [--watch]                           # Process CSS
-bunki images:push [--domain DOMAIN]           # Upload images to cloud
+bunki init [--config FILE]                                              # Initialize new site
+bunki new <TITLE> [--tags TAG1,TAG2]                                    # Create new post
+bunki generate [--config FILE] [--content DIR] [--output DIR] [--templates DIR]
+bunki generate --incremental                                            # Enable incremental builds
+bunki validate [--config FILE] [--dir DIR]                              # Validate markdown files for parsing errors
+bunki validate:media [--content-dir DIR]                                # Validate media files
+bunki serve [--output DIR] [--port 3000]                                # Start dev server
+bunki css [--config FILE] [--output DIR] [--watch]                      # Process CSS
+bunki images:push [--domain DOMAIN] [--images DIR] [--output-json FILE]
+  [--min-year YEAR] [--max-year YEAR] [--content-assets] [--content-assets-dir DIR]
+                                                                        # Upload media to S3-compatible storage
 ```
 
 ## Output Structure
@@ -1202,7 +1222,7 @@ site-generator.ts (orchestrator)
 - **JSON-LD Structured Data**: Automatic Schema.org markup (BlogPosting, WebSite, Organization, BreadcrumbList)
 - **Pagination**: Configurable posts per page with reusable pagination utilities
 - **Archives**: Year-based and tag-based organization
-- **Modular Architecture**: Single responsibility modules with comprehensive test coverage (424 tests)
+- **Modular Architecture**: Single responsibility modules with comprehensive test coverage
 
 ## Development
 
@@ -1215,9 +1235,21 @@ bun run build              # Build distribution
 bun test                   # Run test suite
 bun test:coverage          # Test coverage report
 bun run typecheck          # TypeScript validation
-bun run format             # Prettier formatting
+bun run format             # Biome formatting
 ```
 
+## Continuous Integration
+
+GitHub Actions runs the same Bun-first workflow used locally:
+
+- **CI**: typecheck, Biome linting, coverage tests, build, and an example site generation smoke test.
+- **Compatibility Tests**: verifies the minimum supported Bun version (`1.3.14`) and the latest Bun release.
+- **Coverage**: generates LCOV coverage and uploads it to Coveralls.
+- **PR Coverage Comment**: posts LCOV coverage feedback on pull requests.
+- **Publish to npm**: runs tests and builds first, then publishes on version tags, `[publish]` commits, or manual dispatch with `force-publish`.
+
+Shared workflow setup lives in `.github/actions/setup-bun/action.yml`, which installs Bun, restores the Bun package cache, and runs `bun install --frozen-lockfile`.
+
 ## Project Structure
 
 ```
@@ -1247,7 +1279,7 @@ bunki/
 │       ├── json-ld.ts         # JSON-LD schema generation
 │       ├── image-uploader.ts  # Image upload logic
 │       └── s3-uploader.ts     # S3/R2 client
-├── test/                       # Test suite (424 tests, mirrors src/)
+├── test/                       # Test suite (mirrors src/)
 │   ├── utils/
 │   │   ├── markdown/          # Modular tests (NEW)
 │   │   │   ├── constants.test.ts   (25 tests)

package/dist/cli/commands/css.d.ts

@@ -1,4 +1,4 @@
-import { Command } from "commander";
+import type { Command } from "commander";
 import { loadConfig } from "../../config";
 import { getDefaultCSSConfig, processCSS, watchCSS } from "../../utils/css-processor";
 interface CssDeps {

package/dist/cli/commands/generate.d.ts

@@ -1,4 +1,4 @@
-import { Command } from "commander";
+import type { Command } from "commander";
 import { loadConfig } from "../../config";
 import { SiteGenerator } from "../../site-generator";
 interface GenerateDeps {

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

@@ -1,4 +1,4 @@
-import { Command } from "commander";
+import type { Command } from "commander";
 import { uploadImages } from "../../utils/image-uploader";
 interface ImagesPushDeps {
     uploadImages: typeof uploadImages;

package/dist/cli/commands/init.d.ts

@@ -1,4 +1,4 @@
-import { Command } from "commander";
+import type { Command } from "commander";
 import { createDefaultConfig } from "../../config";
 import { ensureDir } from "../../utils/file-utils";
 type WriteFileFn = (filePath: string, data: string) => Promise<number>;

package/dist/cli/commands/new-post.d.ts

@@ -1,4 +1,4 @@
-import { Command } from "commander";
+import type { Command } from "commander";
 type WriteFileFn = (filePath: string, data: string) => Promise<number>;
 interface NewDeps {
     writeFile: WriteFileFn;

package/dist/cli/commands/serve.d.ts

@@ -1,4 +1,4 @@
-import { Command } from "commander";
+import type { Command } from "commander";
 import { startServer } from "../../server";
 interface ServeDeps {
     startServer: typeof startServer;

package/dist/cli/commands/validate-media.d.ts

@@ -1,7 +1,6 @@
-import { Command } from "commander";
+import type { Command } from "commander";
 export declare function handleValidateMediaCommand(options: {
     contentDir?: string;
-    fix?: boolean;
 }, deps?: {
     logger: Console;
     exit: (code: number) => never;

package/dist/cli/commands/validate.d.ts

@@ -1,2 +1,2 @@
-import { Command } from "commander";
+import type { Command } from "commander";
 export declare function registerValidateCommand(program: Command): void;