# 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

```bash
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.