GIA/artifacts/frontend_asset_playbook.md

Frontend Asset Vendoring Playbook

This is the repeatable process used in GIA to self-host third-party frontend assets, pin versions, record provenance, and keep template SRI hashes maintainable.

Goals

• Avoid runtime CDN dependencies for core UI assets.
• Pin exact upstream versions and package integrity in source control.
• Record provenance, license, and SRI for each third-party asset.
• Keep a simple manifest-driven workflow that can be copied into other projects.

Files

• tools/frontend_assets/package.json
  • Exact npm dependency pins for vendored frontend libraries.
• tools/frontend_assets/package-lock.json
  • npm lockfile integrity and tarball resolution source of truth.
• tools/frontend_assets/asset-manifest.json
  • Maps upstream package files and URL bundles into local core/static/ targets.
• scripts/vendor_frontend_assets.py
  • Copies npm assets, downloads non-npm bundles, computes local SHA-256 and SRI SHA-512, and emits inventory reports.
• artifacts/frontend_libraries.md
  • Human-readable inventory with versions, licenses, official URLs, tarballs, upstream integrity, and local SHA/SRI.
• artifacts/frontend_libraries.json
  • Machine-readable inventory for template updates and audits.

Standard Workflow

1. Add or update exact versions in tools/frontend_assets/package.json.
2. Confirm each package is the official distribution, not a typosquat or community fork.
3. Update tools/frontend_assets/asset-manifest.json with the exact files to vendor.
4. Run npm install --ignore-scripts in tools/frontend_assets/.
5. Run ./genv/bin/python scripts/vendor_frontend_assets.py.
6. Copy the emitted sri_sha512 values into template tags in core/templates/base.html.
7. Restart the stack so collectstatic republishes the new files.
8. Verify in the browser that assets load from local static URLs with no CDN fallbacks.

Provenance Rules

• Prefer official project docs or official extension listings before trusting npm search results.
• For Bulma extensions, treat https://bulma.io/extensions/ as the discovery source and verify the linked package/repo matches the npm package name.
• Confirm npm metadata matches the expected project:
  • homepage
  • repository
  • maintainers
  • license
  • publish recency
• Keep exact versions in package.json; do not use ranges.
• Use package-lock.json as the immutable record of tarball URLs and upstream integrity.
• If a library is not safely available from npm, vendor it from the official upstream URL as a url_bundle.
• Do not silently substitute a “free” or differently-scoped package if the templates rely on another asset family.

GIA Decisions

• Font Awesome:
  • GIA templates use icon classes that are not safely replaceable with @fortawesome/fontawesome-free.
  • The existing Font Awesome Pro site-assets v6.1.1 bundle is self-hosted under core/static/vendor/fontawesome/ instead.
• jQuery:
  • Latest npm is 4.x, but GIA stays on 3.7.1 to avoid breaking older plugins.
• Bulma extensions:
  • bulma-calendar, bulma-tagsinput, bulma-switch, bulma-slider, and bulma-tooltip were matched against Bulma's official extensions page before pinning.
  • bulma-calendar and bulma-tooltip are deprecated on npm, but Bulma still points to the Wikiki ecosystem for these extensions, so they were kept and documented instead of replaced ad hoc.

Theme Strategy

• core/static/css/gia-theme.css is now the project override layer instead of an inline <style> block in base.html.
• This is the low-friction step that works with the current stack immediately.
• If we want a true Bulma theme build later, add sass to tools/frontend_assets, create a gia-bulma.scss entrypoint that sets Bulma theme variables before importing Bulma, and vendor the compiled output through the same manifest process.

Commands

cd /code/xf/GIA/tools/frontend_assets
npm install --ignore-scripts

cd /code/xf/GIA
./genv/bin/python scripts/vendor_frontend_assets.py
bash ./scripts/quadlet/manage.sh restart
./genv/bin/python manage.py check

Verification Checklist

• core/templates/base.html only references local static URLs for vendored libraries.
• Each included stylesheet/script in base.html has an integrity="sha512-..." attribute.
• Browser network panel shows local asset hits and no unexpected CDN requests.
• artifacts/frontend_libraries.md reflects the exact deployed asset set.