@ibalzam/codejitsu-core 0.1.0 → 0.2.1

package/modules/config/src/types.ts

@@ -0,0 +1,203 @@
+/**
+ * Unified Codejitsu config — the shape of `codejitsu.config.ts` at site root.
+ *
+ * One config drives every module. Each top-level module key (`blog`, `seo`,
+ * `images`, `llms`, `deploy`) is optional: omit it to disable that module,
+ * or include it (even as `{}`) to enable with defaults. Set `enabled: false`
+ * to explicitly disable while keeping the section for documentation.
+ */
+export interface CodejitsuConfig {
+  /** Site-wide identity and metadata, used by multiple modules. */
+  site: SiteConfig;
+
+  blog?: BlogConfig | false;
+  seo?: SeoConfig | false;
+  images?: ImagesConfig | false;
+  llms?: LlmsConfig | false;
+  deploy?: DeployConfig | false;
+}
+
+export interface SiteConfig {
+  /** Absolute site URL, no trailing slash. e.g. 'https://example.com'. */
+  url: string;
+  /** Brand name. e.g. 'Pearl Remodeling'. */
+  name: string;
+  /** Appended to <title> tags. e.g. ' — Pearl Remodeling'. */
+  titleSuffix?: string;
+  /** Default author when blog posts don't specify one. */
+  defaultAuthor?: string;
+  /** Default OG image (relative path or absolute URL). */
+  defaultOgImage?: string;
+  /** HTML lang attribute. e.g. 'en-US', 'en'. */
+  locale?: string;
+  /** Optional structured business info for Organization / LocalBusiness schema. */
+  business?: BusinessInfo;
+}
+
+export interface BusinessInfo {
+  legalName?: string;
+  telephone?: string;
+  email?: string;
+  /** Used for LocalBusiness schema and contact pages. */
+  address?: PostalAddress;
+  geo?: { latitude: number; longitude: number };
+  /** Social profile URLs. */
+  sameAs?: string[];
+  /** e.g. '$$', '$$$'. */
+  priceRange?: string;
+  /** Service areas. Strings (city names) or objects. */
+  areaServed?: string[];
+  /** License number for licensed trades. */
+  license?: string;
+  /** Schema.org type override, e.g. 'HVACBusiness', 'HomeAndConstructionBusiness'. */
+  schemaType?: string;
+}
+
+export interface PostalAddress {
+  streetAddress?: string;
+  addressLocality: string;
+  addressRegion?: string;
+  postalCode?: string;
+  addressCountry: string;
+}
+
+export interface BlogConfig {
+  enabled?: boolean;
+  /**
+   * 'collection' — use Astro Content Collections (recommended for Astro sites).
+   * 'fs' — read .md files directly via gray-matter (for non-Astro projects).
+   * Defaults to 'collection' if the site has astro as a dep; otherwise 'fs'.
+   */
+  mode?: 'collection' | 'fs';
+  /** For 'fs' mode: where the .md files live. Default 'content/blog'. */
+  contentDir?: string;
+  /** For 'collection' mode: name of the Astro CC. Default 'blog'. */
+  collectionName?: string;
+  /** Frontmatter field for the post date. Default 'date'. Pearl uses 'pubDate'. */
+  dateField?: string;
+  /** Frontmatter field for draft state. Default null (no draft support). Pearl uses 'draft'. */
+  draftField?: string | null;
+  /** Category definitions for /blog/category/[slug] pages. */
+  categories?: BlogCategory[];
+}
+
+export interface BlogCategory {
+  slug: string;
+  tag: string;
+  title: string;
+  subtitle: string;
+  metaDescription: string;
+}
+
+export interface SeoConfig {
+  enabled?: boolean;
+  sitemap?: {
+    /** Regex patterns to exclude from the sitemap. */
+    excludePatterns?: RegExp[];
+    /**
+     * Site-specific priority rules, evaluated before defaults.
+     * First matching pattern wins.
+     */
+    priorityRules?: Array<{
+      pattern: RegExp;
+      priority: number;
+      changefreq?: 'always' | 'hourly' | 'daily' | 'weekly' | 'monthly' | 'yearly' | 'never';
+    }>;
+  };
+  /**
+   * Default schemas to inject site-wide when not overridden per-page.
+   * e.g. always-on Organization or LocalBusiness on every page.
+   */
+  defaultSchemas?: ('organization' | 'localBusiness' | 'website')[];
+}
+
+export interface ImagesConfig {
+  enabled?: boolean;
+  /** Source dir for the recursive optimizer. Default 'public/images'. */
+  sourceDir?: string;
+  /** Thumbnail output dir. Set to null to disable thumb generation. Default null. */
+  thumbDir?: string | null;
+  defaultQuality?: number;
+  defaultMaxSize?: number;
+  thumbSize?: number;
+  thumbQuality?: number;
+  /**
+   * Per-file rule overrides. Key = path relative to sourceDir without extension.
+   * e.g. 'logos/logo': { maxWidth: 329, quality: 35, generateAvif: true }
+   */
+  specialRules?: Record<string, SpecialRule>;
+  /**
+   * Blog-post image automation. Replaces hand-maintained title→slug maps.
+   * If set, the optimizer scans `contentDir` for post filenames and looks for
+   * matching source images in `sourceImageDir`, optimizing them into `outputDir`.
+   */
+  autoBlogImages?: {
+    contentDir: string;
+    sourceImageDir: string;
+    outputDir: string;
+    width: number;
+    height?: number | null;
+    quality?: number;
+  };
+}
+
+export interface SpecialRule {
+  maxWidth?: number | null;
+  maxHeight?: number | null;
+  quality?: number;
+  smartSubsample?: boolean;
+  generateAvif?: boolean;
+  optimizePng?: boolean;
+}
+
+export interface LlmsConfig {
+  enabled?: boolean;
+  /**
+   * 'config' — sections are listed explicitly in this config (simplest sites).
+   * 'content-scan' — modules scan content dirs to enumerate URLs (pearl pattern).
+   * Default 'config'.
+   */
+  mode?: 'config' | 'content-scan';
+
+  /** One-line tagline appended to the title in the output. */
+  tagline?: string;
+  /** Short "About" paragraph (used in llms.txt). */
+  about?: string;
+  /** Longer "About" content (used in llms-full.txt; falls back to `about`). */
+  aboutFull?: string;
+  /** Sections for 'config' mode. Ignored in 'content-scan' mode. */
+  sections?: LlmsSection[];
+  /** "For AI Assistants" block content (both modes). */
+  aiGuidance?: string;
+
+  /** Blog directory (auto-included in both modes). */
+  blogDir?: string;
+  blogLimit?: number;
+  blogFullLimit?: number;
+
+  /** Settings for 'content-scan' mode. */
+  contentScan?: {
+    servicesDir?: string;
+    locationsDir?: string;
+    pagesDir?: string;
+  };
+}
+
+export interface LlmsSection {
+  title: string;
+  description?: string;
+  items: LlmsSectionItem[];
+}
+
+export interface LlmsSectionItem {
+  title: string;
+  description: string;
+  url: string;
+  fullDescription?: string;
+}
+
+export interface DeployConfig {
+  enabled?: boolean;
+  /** Cloudflare Pages project name. Used for documentation only. */
+  cloudflarePagesName?: string;
+}

package/modules/images/CLAUDE.md

@@ -1,39 +1,62 @@
 # Images module — instructions for Claude
 
-When the user asks to **set up codejitsu/core/images** (or "wire up the image pipeline", "convert PNGs to WebP"), do the following.
+When the user asks to **set up codejitsu/core/images** (or "wire up the image pipeline", "convert PNGs to WebP", "automate blog images"), do the following.
 
 ## What this module provides
 
-Two complementary layers:
+Three layers — use whichever you need:
 
-1. **Astro sharp service** (runtime, automatic) — handles `<Image>` imports and `<Picture>` components inside `.astro` files. Configured in `astro.config.mjs`.
-2. **Pre-pass CLI** (`npx codejitsu-optimize-images`) — recursively converts every `.png`/`.jpg`/`.jpeg` in `public/images/` to `.webp` (plus thumbnails). For images referenced by URL (in HTML strings, CSS `background-image`, or `<img src>` outside Astro processing).
+1. **Astro sharp service** (runtime, automatic) — `<Image>` / `<Picture>` in `.astro` files. Configured in `astro.config.mjs`.
+2. **`codejitsu-optimize-images` CLI** — recursive PNG/JPG → WebP pre-pass for `public/` (general site assets, logos, hero images). Per-file `specialRules` overrides.
+3. **`autoBlogImages` mode** — given a content collection of `<slug>.md` files and a source-image directory with `<slug>.<ext>` files, emits optimized WebPs to an output dir. Replaces hand-maintained title→slug maps.
 
-Both layers are needed. Astro's service can't reach files referenced by URL; the pre-pass can't add the responsive variants Astro generates.
+All three read from the **single `codejitsu.config.ts`** at site root.
 
 ## Wiring it into a site
 
-### 1. Configure Astro
+### 1. Configure Astro sharp service
 
 In `astro.config.mjs`:
 
 ```ts
-export default defineConfig({
-  // ...
-  image: {
-    service: { entrypoint: 'astro/assets/services/sharp' },
-    defaults: { quality: 82, format: 'webp' },
-  },
-});
+image: {
+  service: { entrypoint: 'astro/assets/services/sharp' },
+  defaults: { quality: 82, format: 'webp' },
+},
 ```
 
-### 2. Copy the optimizer config
+### 2. Configure the CLI in `codejitsu.config.ts`
 
-Copy `templates/codejitsu-images.config.mjs` → site root. Edit `specialRules` for any images that need special handling (logo, OG share images, hero images that need aggressive compression).
+```ts
+import { defineConfig } from '@ibalzam/codejitsu-core/config';
 
-### 3. Wire the pre-pass into the build
+export default defineConfig({
+  site: { url: '...', name: '...' },
+  images: {
+    // General optimizer — scan a dir, convert every PNG/JPG to WebP.
+    sourceDir: 'public/assets/images',
+    defaultQuality: 82,
+    defaultMaxSize: 1376,
+
+    specialRules: {
+      'logos/logo': { maxWidth: 400, quality: 35, generateAvif: true },
+      'sharing/og-default': { maxWidth: 1200, maxHeight: 630, quality: 85, optimizePng: true },
+    },
+
+    // Blog image automation — one image per post slug.
+    autoBlogImages: {
+      contentDir: 'src/content/blog',
+      sourceImageDir: 'private/blog-source-images',   // not committed
+      outputDir: 'public/assets/images/blog',
+      width: 1376,
+      height: null,                                    // preserve aspect ratio
+      quality: 82,
+    },
+  },
+});
+```
 
-In the site's `package.json`:
+### 3. Wire into prebuild
 
 ```json
 {
@@ -44,34 +67,28 @@ In the site's `package.json`:
 }
 ```
 
-If the site already has a `prebuild` script, chain: `"prebuild": "codejitsu-optimize-images && existing-script"`.
-
-### 4. Run once
-
-```bash
-npm run prebuild
-```
-
-Every PNG/JPG in `public/images/` now has a `.webp` sibling. References in HTML/CSS should use the `.webp` filename.
+### 4. Workflow for new blog images (with autoBlogImages)
 
-## How to reference images in templates
+1. Generate or save the source image (any size, any format).
+2. **Name it after the post slug** — e.g. `backyard-patio-ideas-henderson-summer-heat.png`.
+3. Place it in `images.autoBlogImages.sourceImageDir`.
+4. Run `npm run prebuild` (or just `npm run build` — it runs prebuild first).
+5. The optimized WebP appears at `<outputDir>/<slug>.webp`. Commit it.
 
-- **In Astro `<Image>` / `<Picture>`:** import from `src/assets/` or `~/assets/`. Astro processes them. Format defaults to WebP.
-- **In raw `<img>` / CSS `background-image`:** reference the `.webp` file directly. Don't reference `.png` if a `.webp` exists.
-- **OG / share images:** these are referenced by absolute URL on a CDN. Set `optimizePng: true` in `specialRules` so the original PNG is also compressed (Facebook scrapers sometimes prefer PNG over WebP).
+The CLI warns about post slugs with no matching source image. No more hand-edited maps.
 
 ## What must NOT be done
 
-- **Don't reference `.png` in production HTML when the same image exists as `.webp`.** The `<img src="/images/x.png">` should be `<img src="/images/x.webp">`. Checklist enforces this.
-- **Don't commit the generated `.webp` files... actually, DO commit them.** They're build artifacts but committing avoids forcing CI to install sharp. (Re-evaluate if `public/images` grows huge.)
-- **Don't run the optimizer manually expecting it to skip already-converted files.** Sharp re-processes each run; this is intentional (so quality changes propagate). Re-running is cheap because outputs are written to siblings, not appended.
-- **Don't put the optimizer in a `postinstall` hook.** Building on every `npm install` is annoying.
-- **Don't add raw PNG/JPG to `src/assets/` for Astro `<Image>` use.** Astro handles those fine; the pre-pass is only for `public/`.
+- **Don't keep an old `codejitsu-images.config.mjs` file around.** v0.2.0 hard-broke it; only `codejitsu.config.ts` is read.
+- **Don't reference `.png` in production HTML when a `.webp` exists** at the same path. The Astro `<Image>` component handles it; raw `<img src>` must point to the `.webp`.
+- **Don't put source images for `autoBlogImages` inside `public/`.** They get served. Use a sibling dir like `private/blog-source-images/` (and add it to `.gitignore` if the sources are heavy / AI-generated).
+- **Don't run the optimizer expecting it to skip up-to-date general files.** Only `autoBlogImages` does mtime-based skipping. The general optimizer re-processes every file (so quality changes propagate). Re-running is cheap.
+- **Don't put `autoBlogImages.sourceImageDir` and `outputDir` to the same place.** That'd recursively re-optimize outputs.
 
 ## Verify
 
-- [ ] `astro.config.mjs` has `image.defaults: { format: 'webp' }`.
-- [ ] `codejitsu-images.config.mjs` exists at site root.
-- [ ] `package.json` calls `codejitsu-optimize-images` in `prebuild`.
-- [ ] Every `.png`/`.jpg` in `public/images/` has a `.webp` sibling after build.
+- [ ] `codejitsu.config.ts` has an `images` section.
+- [ ] `prebuild` script in `package.json` runs `codejitsu-optimize-images`.
+- [ ] Every PNG/JPG in `images.sourceDir` has a `.webp` sibling after build.
+- [ ] If `autoBlogImages` is configured: every `.md` in `contentDir` has a matching `.webp` in `outputDir`.
 - [ ] No `<img src="*.png">` in built HTML where a `.webp` sibling exists.

package/modules/images/bin/optimize.mjs

@@ -1,44 +1,52 @@
 #!/usr/bin/env node
 import path from 'path';
-import { existsSync } from 'fs';
-import { pathToFileURL } from 'url';
+import { loadConfig, isModuleEnabled } from '../../config/src/load.mjs';
 import { optimizeImages } from '../src/optimize.mjs';
+import { autoBlogImages } from '../src/auto-blog.mjs';
 
 const cwd = process.cwd();
-const configCandidates = [
-  'codejitsu-images.config.mjs',
-  'codejitsu-images.config.js',
-];
 
-const defaults = {
-  sourceDir: path.join(cwd, 'public/images'),
-  thumbDir: path.join(cwd, 'public/images/thumbs'),
-  defaultQuality: 75,
-  defaultMaxSize: 1200,
-  thumbSize: 400,
-  thumbQuality: 70,
-  specialRules: {},
-};
+let config;
+try {
+  config = await loadConfig(cwd);
+} catch (err) {
+  console.error(`[codejitsu-optimize-images] ${err.message}`);
+  process.exit(1);
+}
 
-let userConfig = {};
-for (const name of configCandidates) {
-  const p = path.join(cwd, name);
-  if (existsSync(p)) {
-    userConfig = (await import(pathToFileURL(p).href)).default ?? {};
-    console.log(`Loaded config: ${name}`);
-    break;
-  }
+if (!isModuleEnabled(config, 'images')) {
+  console.log('[codejitsu-optimize-images] images module disabled; skipping.');
+  process.exit(0);
 }
 
-const config = {
-  ...defaults,
-  ...userConfig,
-  sourceDir: userConfig.sourceDir
-    ? path.resolve(cwd, userConfig.sourceDir)
-    : defaults.sourceDir,
-  thumbDir: userConfig.thumbDir
-    ? path.resolve(cwd, userConfig.thumbDir)
-    : defaults.thumbDir,
-};
+const images = config.images;
+
+// 1. General recursive optimizer (if sourceDir configured).
+if (images.sourceDir) {
+  console.log(`[codejitsu-optimize-images] Scanning ${images.sourceDir}…`);
+  await optimizeImages({
+    sourceDir: path.resolve(cwd, images.sourceDir),
+    thumbDir: images.thumbDir ? path.resolve(cwd, images.thumbDir) : null,
+    defaultQuality: images.defaultQuality,
+    defaultMaxSize: images.defaultMaxSize,
+    thumbSize: images.thumbSize,
+    thumbQuality: images.thumbQuality,
+    specialRules: images.specialRules,
+  });
+}
+
+// 2. Blog-image auto-processing (if configured).
+if (images.autoBlogImages) {
+  const a = images.autoBlogImages;
+  console.log(`[codejitsu-optimize-images] Auto blog images: ${a.contentDir} → ${a.outputDir}`);
+  await autoBlogImages({
+    contentDir: path.resolve(cwd, a.contentDir),
+    sourceImageDir: path.resolve(cwd, a.sourceImageDir),
+    outputDir: path.resolve(cwd, a.outputDir),
+    width: a.width,
+    height: a.height,
+    quality: a.quality,
+  });
+}
 
-await optimizeImages(config);
+console.log('[codejitsu-optimize-images] Done.');

package/modules/images/checklist.md

@@ -1,23 +1,31 @@
 # Images module — checklist
 
-## Astro
+## Setup
 
 - [ ] `astro.config.mjs` has `image.service: { entrypoint: 'astro/assets/services/sharp' }`.
 - [ ] `astro.config.mjs` has `image.defaults: { quality: 82, format: 'webp' }` (or justified deviation).
+- [ ] `codejitsu.config.ts` has an `images` section.
+- [ ] `package.json` calls `codejitsu-optimize-images` in `prebuild` (or `build`).
 
-## Pre-pass
+## General optimization
 
-- [ ] `codejitsu-images.config.mjs` exists at site root.
-- [ ] `package.json` calls `codejitsu-optimize-images` in `prebuild` (or `build`).
-- [ ] Every PNG/JPG in `public/images/` has a `.webp` sibling.
+- [ ] Every PNG/JPG under `images.sourceDir` has a `.webp` sibling after build.
+- [ ] Critical files have `specialRules` entries (logo, OG images, hero images).
+
+## Blog automation (if configured)
+
+- [ ] Every `.md` filename in `autoBlogImages.contentDir` has a matching `.webp` in `outputDir`.
+- [ ] `autoBlogImages.sourceImageDir` is not inside `public/` (sources shouldn't ship to browsers).
+- [ ] `autoBlogImages.sourceImageDir` is in `.gitignore` if sources are heavy or AI-generated.
+- [ ] No "missing source" warnings from the last `codejitsu-optimize-images` run (or, if any, they're for posts intentionally without images).
 
 ## Production HTML
 
 - [ ] No `<img src>` references `.png` or `.jpg` where a `.webp` exists for the same path.
 - [ ] CSS `background-image` URLs reference `.webp`.
-- [ ] OG / Twitter share images have both PNG (for legacy scrapers) and WebP variants; the `og:image` meta tag points to the PNG (more compatible).
+- [ ] OG / Twitter share images: PNG (for legacy scrapers) AND WebP variants; the `og:image` meta tag points to the PNG (more compatible).
 
 ## Sizes
 
-- [ ] No single image in `public/images/` is > 500KB. If so, it has a `specialRules` entry tuning quality/dimensions.
+- [ ] No single image in production `public/` is > 500KB. If so, it has a `specialRules` entry tuning quality/dimensions.
 - [ ] Hero images have `width` and `height` attributes set (CLS).

package/modules/images/src/auto-blog.mjs

@@ -0,0 +1,112 @@
+import sharp from 'sharp';
+import { readdir, mkdir, stat } from 'fs/promises';
+import { existsSync } from 'fs';
+import { join, parse } from 'path';
+
+/**
+ * Auto-process blog post images based on filename-as-slug convention.
+ *
+ * For every .md file in `contentDir`, looks for a matching source image
+ * (`<slug>.png`, `<slug>.jpg`, `<slug>.jpeg`, `<slug>.webp`) in `sourceImageDir`.
+ * If found, emits an optimized WebP to `<outputDir>/<slug>.webp`.
+ *
+ * Skips when the output is newer than the source (incremental builds).
+ * Warns about slugs with no matching source image.
+ *
+ * @param {object} config
+ * @param {string} config.contentDir       Where .md posts live, e.g. 'src/content/blog'.
+ * @param {string} config.sourceImageDir   Where source images live (one per slug).
+ * @param {string} config.outputDir        Where to write WebPs.
+ * @param {number} config.width
+ * @param {number|null} [config.height]    Null = preserve aspect ratio.
+ * @param {number} [config.quality=82]
+ */
+export async function autoBlogImages(config) {
+  const {
+    contentDir,
+    sourceImageDir,
+    outputDir,
+    width,
+    height = null,
+    quality = 82,
+  } = config;
+
+  if (!existsSync(contentDir)) {
+    console.log(`autoBlogImages: contentDir ${contentDir} doesn't exist; skipping.`);
+    return;
+  }
+  if (!existsSync(sourceImageDir)) {
+    console.log(`autoBlogImages: sourceImageDir ${sourceImageDir} doesn't exist; skipping.`);
+    return;
+  }
+  if (!existsSync(outputDir)) {
+    await mkdir(outputDir, { recursive: true });
+  }
+
+  const slugs = await collectSlugs(contentDir);
+  const exts = ['png', 'jpg', 'jpeg', 'webp'];
+
+  let processed = 0;
+  let skipped = 0;
+  const missing = [];
+
+  for (const slug of slugs) {
+    let sourcePath = null;
+    for (const ext of exts) {
+      const candidate = join(sourceImageDir, `${slug}.${ext}`);
+      if (existsSync(candidate)) {
+        sourcePath = candidate;
+        break;
+      }
+    }
+
+    if (!sourcePath) {
+      missing.push(slug);
+      continue;
+    }
+
+    const outputPath = join(outputDir, `${slug}.webp`);
+
+    if (existsSync(outputPath)) {
+      const [srcStat, outStat] = await Promise.all([stat(sourcePath), stat(outputPath)]);
+      if (outStat.mtimeMs >= srcStat.mtimeMs) {
+        skipped++;
+        continue;
+      }
+    }
+
+    const fit = height ? 'cover' : 'inside';
+    await sharp(sourcePath)
+      .resize(width, height, { fit, withoutEnlargement: true, position: 'center' })
+      .webp({ quality, effort: 6 })
+      .toFile(outputPath);
+    console.log(`✓ ${slug}.webp (from ${parse(sourcePath).base}, q=${quality})`);
+    processed++;
+  }
+
+  console.log(
+    `autoBlogImages: ${processed} processed, ${skipped} up-to-date, ${missing.length} missing source.`
+  );
+  if (missing.length > 0) {
+    console.warn('  Missing source images for slugs:');
+    for (const slug of missing) console.warn(`    - ${slug}`);
+    console.warn(
+      `  Place an image named <slug>.{png,jpg,jpeg,webp} in ${sourceImageDir} to fix.`
+    );
+  }
+}
+
+async function collectSlugs(dir) {
+  const slugs = [];
+  async function walk(d) {
+    for (const entry of await readdir(d, { withFileTypes: true })) {
+      const full = join(d, entry.name);
+      if (entry.isDirectory()) await walk(full);
+      else if (entry.isFile() && entry.name.endsWith('.md')) {
+        slugs.push(entry.name.replace(/\.md$/, ''));
+      }
+    }
+  }
+  await walk(dir);
+  return slugs;
+}

package/modules/images/src/index.ts

@@ -1,21 +1,6 @@
-export interface SpecialRule {
-  maxWidth?: number | null;
-  maxHeight?: number | null;
-  quality?: number;
-  smartSubsample?: boolean;
-  generateAvif?: boolean;
-  optimizePng?: boolean;
-}
-
-export interface OptimizeImagesConfig {
-  sourceDir: string;
-  thumbDir?: string;
-  defaultQuality?: number;
-  defaultMaxSize?: number;
-  thumbSize?: number;
-  thumbQuality?: number;
-  specialRules?: Record<string, SpecialRule>;
-}
+export type { ImagesConfig, SpecialRule } from '../../config/src/types.js';
 
 // @ts-expect-error - .mjs file resolved by Node at runtime
 export { optimizeImages } from './optimize.mjs';
+// @ts-expect-error - .mjs file resolved by Node at runtime
+export { autoBlogImages } from './auto-blog.mjs';

package/modules/images/src/optimize.mjs

@@ -4,26 +4,25 @@ import { existsSync } from 'fs';
 import { join, dirname, parse, relative } from 'path';
 
 /**
- * Recursively converts JPG/JPEG/PNG → WebP under `sourceDir`, writing
- * matching thumbnails under `thumbDir`. Per-file rules can override
- * defaults (quality, dimensions, AVIF generation, in-place PNG optimization).
+ * General recursive PNG/JPG → WebP optimizer.
+ *
+ * Walks `sourceDir` recursively. For every .jpg/.jpeg/.png, emits a .webp sibling.
+ * Per-file overrides via `specialRules`. Optional thumbnail generation.
  *
  * @param {object} config
- * @param {string} config.sourceDir          Absolute path to source images.
- * @param {string} config.thumbDir           Absolute path to write thumbnails (skipped if same as sourceDir).
+ * @param {string} config.sourceDir
+ * @param {string|null} [config.thumbDir]    Null = no thumbs.
  * @param {number} [config.defaultQuality=75]
  * @param {number} [config.defaultMaxSize=1200]
  * @param {number} [config.thumbSize=400]
  * @param {number} [config.thumbQuality=70]
  * @param {Record<string, SpecialRule>} [config.specialRules]
  *   Key = path relative to sourceDir without extension (e.g. 'logos/logo').
- *   Each rule: { maxWidth?, maxHeight?, quality?, smartSubsample?,
- *                generateAvif?, optimizePng? }.
  */
 export async function optimizeImages(config) {
   const {
     sourceDir,
-    thumbDir,
+    thumbDir = null,
     defaultQuality = 75,
     defaultMaxSize = 1200,
     thumbSize = 400,
@@ -109,5 +108,4 @@ export async function optimizeImages(config) {
   }
 
   await processDir(sourceDir);
-  console.log('\nDone.');
 }