Re-theme

artifacts/frontend_asset_playbook.md

@@ -0,0 +1,87 @@
+# 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.