feat(assets): generalise compression script across all asset categories

[wab]

Parent

#32 (asset pipeline migration milestone)

Problem

scripts/compress-team-photos.js (introduced in #41) only walks assets/team/*.{jpg,jpeg}. The other asset categories — assets/clients/, assets/posts/<slug>/, assets/stories/, assets/jobs/, assets/tools/, assets/legal/ — receive arbitrary-sized images from non-tech contributors and have no automated optimisation step.

Doing this before #36 (push cleaned assets to new store) avoids pushing un-optimised bytes to the new blob store and re-doing the work later.

What to build

Rename / generalise to scripts/optimize-assets.js:

• Walks assets/**/*.{jpg,jpeg,png,webp}
• Per-extension pipeline:
  • JPEG: resize to fit configurable max dimension (default 1600x1600), quality 80, mozjpeg encoder
  • PNG: skip unless above threshold; if above, run through sharp.png({ quality, compressionLevel: 9, palette: true }) and only keep the result if smaller than original (size-regression guard)
  • WebP: quality 80
• Per-directory overrides via a small config map:
  • team/ → max 800x800 (portrait avatars)
  • clients/ → max 400x400 (logos)
  • posts/, stories/ → max 1600x1600 (blog covers / story images)
  • default → 1600x1600
• Dry-run by default, --write executes (atomic write-then-rename, already in the existing script)
• Per-file output: category/file before → after (saved X%) or skip (under threshold) / skip (no gain)
• Summary: total before / after / saved, broken down by extension

Keep the existing scripts/compress-team-photos.js callable as a thin wrapper or delete it once the generalised version covers the same case.

Acceptance criteria

• scripts/optimize-assets.js walks all of assets/** and handles .jpg, .jpeg, .png, .webp
• Per-directory size limits applied
• PNG quantisation skipped when output ≥ input (no regressions)
• Dry-run shows what would change; --write performs atomic in-place rewrite
• Visual smoke check on 1 file per category (HITL gate — maintainer confirms quality)
• Total assets/ size reduced (target: ≥ 30% global, but the win is on the long tail of large blog images, not the already-compressed team/)
• One atomic commit with conventional message

Blocks

• feat(blob): push cleaned posts/assets/ to new website-blob store #36 (push to new store) — to avoid migrating un-optimised assets

Blocked by

• feat(assets): compress oversized team photos before blob migration #41 (current narrow script lands first, gives us a working baseline to generalise from)

Notes

DX follow-up from #41 — raised because future non-tech contributors will push arbitrary-sized images across all categories, not just team photos. Pair with the CI auto-fix issue for the full DX story.

[wab]

This was generated by AI during triage.

Agent Brief

Category: enhancement
Summary: Generalise the team-photo compression script into an optimize-assets.js that walks all of assets/**, with per-directory size rules and per-extension pipelines. Replace the narrow team-only script — do not keep it as a wrapper.

Current behavior:
A narrow script under scripts/ walks only assets/team/*.{jpg,jpeg}, resizes to 800x800, re-encodes JPEG at quality 80, supports dry-run by default and --write for atomic in-place rewrite. It uses sharp (devDependency) and atomic write-then-rename. The other asset categories (assets/clients/, assets/posts/<slug>/, assets/stories/, assets/jobs/, assets/tools/, assets/legal/) receive arbitrary-sized images and have no automated optimisation. Concrete fat targets on disk today: assets/posts/ ~16 MB (long tail of PNG/JPG), assets/clients/ ~6.8 MB (one PNG at 2.2 MB, several others >400 KB). The repo has no SVG or GIF files — coverage of .jpg/.jpeg/.png/.webp is sufficient.

Desired behavior:
A single scripts/optimize-assets.js walks all of assets/** and optimises every file in place. Per-extension pipeline + per-directory size override map. Dry-run by default with a per-file before → after (saved X%) line and a summary; --write performs the atomic in-place rewrite (write to <file>.tmp-<pid>, then rename(), with unlink cleanup on error). Files that already compress to ≥ their original size are skipped (no-gain guard). Files under the configured threshold are skipped (under-threshold guard).

Key interfaces / contracts:

• CLI (matches the convention of the sibling scripts in scripts/):

  • node scripts/optimize-assets.js → dry-run
  • node scripts/optimize-assets.js --write → in-place rewrite
  • node scripts/optimize-assets.js --threshold-kb <n> → override the global skip threshold (default: see config map below)

• Per-extension pipeline (via sharp):

  • .jpg / .jpeg — resize to fit max dimensions for the directory, withoutEnlargement: true, .rotate() before resize (bake EXIF orientation), .jpeg({ quality: 80, mozjpeg: true })
  • .png — only process if file size ≥ threshold; run .png({ quality: 80, compressionLevel: 9, palette: true }); if the encoded buffer is ≥ original size, skip (size-regression guard) and log skip (no gain)
  • .webp — .webp({ quality: 80 }), same no-gain guard

• Per-directory override map — a small in-file Map/object keyed by the top-level directory under assets/:

  • team/ → max 800×800, threshold 400 KB
  • clients/ → max 400×400, threshold 100 KB
  • posts/ → max 1600×1600, threshold 200 KB
  • stories/ → max 1600×1600, threshold 200 KB
  • default (jobs/, tools/, legal/, anything else) → max 1600×1600, threshold 400 KB

• Output format — per file: category/file before → after (saved X%) or skip (under threshold) / skip (no gain). Summary at the end: total before, total after, total saved (MB + %), breakdown by extension and by top-level directory.

• Atomic write — must reuse the writeFile(<file>.tmp-<pid>) → rename → unlink(tmp).catch(() => {}) pattern already established in the sibling script.

Acceptance criteria:

• scripts/optimize-assets.js walks all of assets/** and handles .jpg, .jpeg, .png, .webp (case-insensitive extension match)
• Per-directory size limits applied via the documented config map
• PNG quantisation skipped when output ≥ input (no regressions)
• Dry-run produces no filesystem changes; --write performs atomic in-place rewrite with no .tmp-* residue on success
• Summary breakdown by extension AND by top-level directory
• Visual smoke check on 1 file per category (team, clients, posts, stories) — HITL gate, maintainer confirms quality before the --write commit lands
• Total assets/ size reduced by ≥ 30% (target is conservative; actual win on posts/ + clients/ is expected much higher)
• scripts/compress-team-photos.js is deleted in the same commit / PR as optimize-assets.js lands — no thin wrapper, single entry point
• Two atomic commits with conventional messages: one feat(scripts): … for the script (+ delete the old one), one chore(assets): … for the binary rewrite

Out of scope:

• CI auto-fix on PRs (tracked separately in ci(assets): auto-fix image compression on PRs touching posts/assets/ #46 — that issue is blocked by this one)
• SVG / GIF support (none in the repo today)
• AVIF transcoding or format conversion (only same-extension re-encode)
• Frontmatter / markdown URL changes (none needed — pathnames preserved)
• Changes to upload-assets.js or any blob-store-side behaviour

[wab]

This was generated by AI during triage.

Clarification — HITL gate becomes a PR review gate (option 2)

Resolving an ambiguity in the original brief: the script execution model is full-write with rollback via revert, not sample-then-stop. The agent should produce both commits on the PR branch — including the binary rewrite. The maintainer reviews the diff on the PR; if a category looks bad, the binary commit is reverted and the agent re-runs with different parameters.

Replaces these acceptance criteria

Remove:

• Visual smoke check on 1 file per category (team, clients, posts, stories) — HITL gate, maintainer confirms quality before the --write commit lands

Add:

• Agent runs node scripts/optimize-assets.js (dry-run) first and posts the full output as a PR comment so the maintainer can see projected savings before reviewing the binary diff
• Agent then runs node scripts/optimize-assets.js --write and commits the result as a separate chore(assets): commit on the PR branch
• No .tmp-* residue in any subdirectory of assets/ after the --write run
• HITL gate is the PR review itself — maintainer inspects the binary diff (GitHub renders image diffs side-by-side) and reverts the chore(assets): commit on the branch if a category looks degraded; the agent does NOT need to export samples or pause before the --write step

Why

Sample-then-stop (export 1 file per category to /tmp/) adds export plumbing that's hard to review and pollutes the agent's workflow. Full-write on a feature branch keeps everything inside the PR — GitHub's image diff renderer is the inspection surface. Revert is one-click via git revert or the GitHub UI.

The PR must be opened as draft until the maintainer confirms quality, then promoted to ready-for-review.

Unchanged

All other parts of the agent brief stand: the per-extension pipeline, the per-directory config map, the atomic write pattern, the deletion of compress-team-photos.js, and the explicit out-of-scope items.

[wab]

This was generated by AI during triage.

Clarification — add --paths flag for scoped runs

The script must support being invoked on an explicit list of files (for use by the CI workflow in #46), not just walk all of assets/**.

Add to "Key interfaces / contracts" — CLI section

• node scripts/optimize-assets.js --paths <comma-separated-paths> → restrict processing to the given list of files. Paths are repo-relative (e.g. assets/posts/foo/cover.png,assets/team/jane-doe.jpg). Files not under assets/ are rejected with a clear error. Files matching the list but not matching the extension allowlist are silently skipped. Files in the list that don't exist on disk are reported as a warning but do not fail the run (covers the edge case of a file deleted in the PR).
• The --paths flag is compatible with --write and --threshold-kb. When absent, the script walks all of assets/** (current behaviour).
• The per-directory config map (size limits, thresholds) applies based on the path's top-level directory regardless of how the file was discovered (walk vs --paths).

Add to acceptance criteria

• --paths accepts a comma-separated list of repo-relative paths and restricts processing to that set
• Paths outside assets/ produce an error and exit non-zero
• Paths in the list that don't exist on disk produce a warning but do not fail the run
• When --paths is omitted, behaviour is unchanged from the rest of the brief (full walk of assets/**)

Why

The CI workflow in #46 will pass the list of files actually changed in the PR. Without --paths, the workflow re-processes all ~150 files in assets/ on every PR — cheap thanks to the no-gain guard, but unnecessary I/O and wall-clock time.

Unchanged: everything else in the original brief and the previous clarification.