build: media-library - Implement the image migration pipeline #291

Build Summary

Build and test the responsive image optimization pipeline for GitHub + Netlify approach.

Additional Context

Evaluate build-time generation of approved responsive derivatives under the planning baseline. Final tooling, formats and integration require approved inputs and implementation permission.

Acceptance Criteria

• Implement agreed deduplication, original/derivative handling and verified mappings.
• Generate approved responsive formats/widths while preserving originals.
• Agree output counts and performance targets before benchmarking.
• Demonstrate repeatable builds, valid outputs, failure handling and measured performance.
• Replace references only with verified mappings and explicit permission; demonstrate rollback.

Dependencies

Dependency-role clarification: #280 supplies evaluation, #281 supplies design, #289 supplies final schema approval, #290 supplies configuration evidence and #291 supplies implementation evidence. These descriptions do not create blocking relationships.

• Blocked by: content-model: media-library - Define the asset catalogue and provenance model #279 (catalogue schema finalized), research: media-library - Evaluate media storage and publishing workflows #280 (infrastructure ready)
• Related: bug: assets - Restore original Figma artwork #7 (asset quality validation)

Deliverables

• Sharp/ImageMin build script (TypeScript/Node)
• Netlify build config with optimization pipeline
• Performance metrics (build time, output file sizes)
• Asset reference mapping update guide
• Maintenance documentation

References

• Storage Comparison § Option 2: .github/reports/toa-media-library/STORAGE-PROVIDER-COMPARISON.md
• Strategy Report § 5: .github/reports/toa-media-library/MEDIA-LIBRARY-STRATEGY-REPORT.md

Immediate next steps

Confirm recovered inputs, final schema, approved infrastructure and migration design. Agree widths/formats, original preservation, mappings, failure handling and performance criteria before implementation.

Evidence required

Reviewed pipeline/build integration, repeatable outputs and failure tests, measured results, approved mappings/reference changes, regression checks and exercised rollback.

Current status — 19 October 2026

Backlog. Extraction, asset-validation and catalogue-update scripts are implemented, but they are not the responsive migration pipeline. Sharp’s presence and runtime Canvas processing do not establish an integrated asset build. The build command remains vite build.

Definition of Ready (DoR)

• Pipeline outcome and proposed variants are documented.
• Input contracts, infrastructure, approvals and permitted parallel work are agreed.

Definition of Done (DoD)

• Implementation, mapping, rollback and regression checks have recorded results.
• Reviewed implementation is merged with maintenance guidance and applicable changelog handling.

Confirmed planning boundary — 18 October 2026

Planning approval does not authorise implementation or reference replacement; retain explicit permissions, verified mappings and rollback safeguards.

Specification references

Historical update correction — 19 October 2026: PR #297 closed without merging. Related specification material nevertheless entered develop through separate integration and successor work; this does not establish delivery approval.

• Specification
• Plan
• Tasks

Draft specification/planning references at revision 02aee367; not evidence of approval, completed recovery or implementation. Task correspondences below describe relevant scope, not exclusive ownership or completed work.

Explicit downstream implementation scope, excluded from this definition package. T007 provides context only; no task delivers the migration pipeline.

✅ Update (2026-10-17): Specification consolidation complete (PR #296 + #297 merged). Current references available on develop branch:

• Specification
• Audit Reports
• All planning docs

Branch instructions

• Repository: lightspeedwp/ThisOneTimeOnAcidCom.
• Implementing target: this image-pipeline issue. The first bounded contribution is an offline pipeline, not another documentation-only contribution. Automatic build integration and protected reference replacement remain separately gated.
• Branch state: proposed new branch, not created. The complete returned branch listing contains no matching proposed branch. Searches found no migration-titled PR or verified implementing PR for GitHub issue 291. Historical PR296 and its surviving mixed-scope branch are not verified reuse candidates. Refresh before implementation; stop for a reuse decision if matching work appears.
• Proposed branch: build/media-library-image-pipeline.
• Starting point and PR base: refreshed develop, checked at 4ecdb26d9655a48bf000a7c89da2f70383edce87 (D), not production main.
• Naming policy: local validator authorises build; local guide documents build-system work. Older root-guide claims of no prefix list conflict with these sources. Syntax inspected, not executed.
• PR template proposal: shared Chore template. Local script maps build to chore, but local workflow lacks a build case and selects pr_default.md, absent from the inspected canonical directory. Obtain maintainer agreement on manual template selection/classification before PR creation; no label, prefix, template or managed-workflow repair included.
• Parent context: retain existing coordination hierarchy. Withhold parent identifiers/links from branches, PRs, commits and coding prompts while association effects remain unverified. Never use the parent as a native development or closing target.
• Allowed closing targets: none authorised for this partial contribution. Review any future issue-reference syntax or native association separately; this appendix does not authorise a PR association or establish safe contextual-link behaviour.
• Constraints: planning only. No branches, PRs, repository edits, installations, hooks, tests, builds, recovery, extraction, uploads, migration, configuration, merge or deployment authorised.

Expected file changes

Provisional implementation plan conditional on approved inputs and separate implementation permission. Existing files/directories inspected at D; new destinations proposed and absent. Exact algorithms and output contract remain decisions, not approved architecture.

No moves or deletions. Evaluate already-declared Sharp first; tooling choice is unresolved. No ImageMin, schema-validator dependency, adapter framework or lockfile change is proposed. Additional dependencies/files/operations require a revised preview and approval.

Dependencies and evidence gates

• Consume reviewed evaluation, migration design, final catalogue contract, recovered-input validation and infrastructure evidence. Existing issue plans are guidance, not completed prerequisites.
• Resolve widths/formats/quality, original handling, deduplication semantics, mapping identity, output destination/counts, performance thresholds, failure policy and parallel-work boundaries before implementation. Runtime image presets are not approved pipeline requirements.
• Formal schema uses snake_case while recovery consumers use camelCase. Agree compatibility first; schema, catalogues and existing recovery scripts remain read-only in this subset.
• Spec 002 excludes responsive/build implementation from its definition package; checked tasks and historical approval claims do not authorise this work. Existing runtime Canvas optimiser remains unchanged.
• Nested Netlify configuration exists; root configuration does not. Verify effective deployment settings through infrastructure work before proposing integration edits.

After separate execution approval, plan focused Jest coverage through npm run test:unit -- --runInBand, applicable build checks and representative-output inspection. Record revision, commands, versions, failures, repeatability, measured sizes/time and unknowns. No tests or commands have been run in this audit.

Full acceptance still requires a revised exact build/Netlify integration plan, measured performance, verified mapping/reference changes with explicit protected-reference permission, regression checks and exercised rollback. This first contribution cannot close the whole issue.

Preserve images, logos, figma asset imports/references, protected fallback component, Supabase artefacts, attribution, changelog, task-list and managed workflows. No catalogue rewrites or tracked generated assets included. Changelog treatment requires maintainer disposition; no protected edit or exemption label is authorised automatically.

Exclude credentials, private account information and restricted recovery material from publicly synced content. This description approval changes no status, ownership, labels, relationships, hierarchy, prior plans or PR associations and grants no implementation or execution authority.