Educates Upgrade Theme Libraries

Educates Workshop Theme Libraries Upgrade Protocol

Refresh the third-party browser libraries vendored into the workshop dashboard theme. These assets are committed directly into the repository and have no build-time fetcher — this skill is how they are updated: it re-downloads a library from its upstream source and writes the files back into the tree.

If $ARGUMENTS names a specific library (e.g. bootstrap, jquery), update only that one. With no argument, check all six for newer upstream versions and report what's available before changing anything.

Canonical location

All libraries live under one directory (the educates dashboard theme's static assets):

workshop-images/base-environment/opt/eduk8s/etc/themes/educates/static/static/libraries/

Call this $LIB below. The target filenames are version-agnostic (no version in the path), so an upgrade overwrites the existing files in place — no renaming or git rm of old files is needed (except Font Awesome / Bootstrap if upstream ever changes which files ship).

Libraries, sources, and target files

Two shapes: zip subset (download a release zip, extract a few files, stripping the zip's top-level folder) and single file (download one JS file directly). Versions shown are the current committed ones — confirm against the tree before bumping (see "Finding current versions").

For the two zip-subset libraries, only the files listed above are kept; the rest of the release archive is discarded.

Keep aligned with the renderer and gateway apps

These same libraries are also npm dependencies of the two bundled apps in the base environment — workshop-images/base-environment/opt/renderer and .../opt/gateway — which compile them into their own JavaScript via esbuild. The vendored theme copy and the npm-bundled copy must stay on the same version, or the dashboard's static assets drift from what the apps ship.

Whenever you change a vendored library version here, update the matching npm dependency in each app's package.json that declares it, and vice versa:

The package.json versions are caret ranges (e.g. "bootstrap": "^5.3.2"). Set the range to the version you vendored (^<VER>), then refresh the lockfile and rebuild so the bundle matches:

cd workshop-images/base-environment/opt/<app>   # renderer and/or gateway
npm install        # updates package-lock.json to the new version

The app bundle is produced by scripts/compile.sh (tsc + esbuild); it runs during the base-environment image build, so a make image-base-environment (or running compile.sh in the app dir) is what proves the new version compiles and bundles cleanly.

Finding current versions

The committed minified files carry a version banner in their first line(s):

LIB=workshop-images/base-environment/opt/eduk8s/etc/themes/educates/static/static/libraries
head -c 200 "$LIB/bootstrap/css/bootstrap.min.css"      # "Bootstrap v5.3.8"
head -c 120 "$LIB/jquery/jquery.min.js"                  # "jQuery v3.7.1"
head -c 200 "$LIB/font-awesome/css/all.min.css"          # "Font Awesome Free 6.5.1"
head -c 200 "$LIB/underscore/underscore-umd-min.js"      # underscore version
head -c 200 "$LIB/js-yaml/js-yaml.min.js"
head -c 200 "$LIB/jsonform/jsonform.min.js"

Finding the latest upstream version

• bootstrap: latest release at https://github.com/twbs/bootstrap/releases (use the latest stable v5.x, not a beta/alpha).
• font-awesome: latest "Free for Web" release at https://github.com/FortAwesome/Font-Awesome/releases (the asset named fontawesome-free-<ver>-web.zip).
• jquery / underscore / jsonform / js-yaml: the npm version. Check https://www.npmjs.com/package/<name> (or https://registry.npmjs.org/<name>/latest). jsDelivr serves any published npm version at the URL pattern above.

Use WebFetch to read the releases/npm page and pick the latest stable version. For major-version bumps, read the changelog for breaking changes and flag them to the user before proceeding.

Update process

Set up the path and a scratch dir:

LIB=workshop-images/base-environment/opt/eduk8s/etc/themes/educates/static/static/libraries
TMP=$(mktemp -d)

Single-file libraries (jquery, underscore, jsonform, js-yaml)

Just overwrite the file from the versioned jsDelivr URL. Example (jquery → <VER>):

curl -fsSL "https://cdn.jsdelivr.net/npm/jquery@<VER>/dist/jquery.min.js" -o "$LIB/jquery/jquery.min.js"

Use the matching URL + target from the table for underscore, jsonform, js-yaml. Always use curl -f so a 404 (bad version/path) fails loudly instead of writing an error page into the asset.