diff --git a/README.md b/README.md index 1999e460..74daddcf 100644 --- a/README.md +++ b/README.md @@ -17,6 +17,7 @@ Copy the struts2-bootstrap-plugin.jar into your WEB-INF/lib path. ### Versions and compatibility | `struts2-bootstrap` version | `struts2` version | `Java` version | |-----------------------------|--------------------|----------------| +| `6.1.1` | version >= `7.2.2` | Java 17 | | `6.0.0` | version >= `7.0.0` | Java 17 | | `5.0.6` | version >= `6.7.0` | Java 8 | | `5.0.5` | version >= `6.6.0` | Java 7 | @@ -31,7 +32,7 @@ Copy the struts2-bootstrap-plugin.jar into your WEB-INF/lib path. com.jgeppert.struts2.bootstrap struts2-bootstrap-plugin - 6.0.0 + 6.1.1 ... diff --git a/docs/superpowers/plans/2026-07-06-webjars-plugin-consumer.md b/docs/superpowers/plans/2026-07-06-webjars-plugin-consumer.md new file mode 100644 index 00000000..2c27d78d --- /dev/null +++ b/docs/superpowers/plans/2026-07-06-webjars-plugin-consumer.md @@ -0,0 +1,318 @@ +# WebJars Plugin Consumer Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Replace the struts2-bootstrap plugin's ~2000 manually-vendored Bootstrap and bootstrap-icons files with `org.webjars` dependencies, served via Struts core's new `<@s.webjar>` mechanism. + +**Architecture:** Bootstrap CSS/JS and bootstrap-icons come from WebJar JARs on the classpath; `head.ftl` resolves their URLs through the Struts `<@s.webjar>` FreeMarker macro (which emits `/static/webjars///`, served by Struts' static-content pipeline). The plugin keeps only its own custom `validation.js`/`validation.min.js` vendored. Version bumps become one-line `pom.xml` changes (auto-updatable via the repo's Renovate). + +**Tech Stack:** Struts 7.2.2 (WebJars support, WW-5640/PR #1765), Maven, FreeMarker templates, `org.webjars:bootstrap`, `org.webjars.npm:bootstrap-icons`. + +## Global Constraints + +- **Struts floor:** 7.2.2 (the release containing WebJars support). Until 7.2.2 is published, build against `7.2.2-SNAPSHOT` (see Prerequisites). +- **Java:** 17. +- **Target asset versions:** Bootstrap `5.3.8`, bootstrap-icons `1.13.1`. +- **Keep vendored:** `template/bootstrap/js/validation.js` and `validation.min.js` (the plugin's own script — NOT a WebJar). Everything else Bootstrap/icons is deleted. +- **Drop** the `?s2b=${version}` cache-buster on WebJar-served links (version is already in the resolved path). Keep it only on the still-vendored `validation.js` link. +- **`head.ftl` is Maven resource-filtered** (`struts2-bootstrap-plugin/pom.xml` filters exactly this one file so `${version}` is injected). Do not break that filtering. +- **Commit convention:** `: ` (no JIRA ticket in this repo). Branch off, never commit to `release/*`. +- **Delivered Struts API:** macro `<@s.webjar path="/"/>` emits the resolved URL string; captured via FreeMarker `<#assign … >…`. Constants `struts.webjars.enabled` (default `true`), `struts.webjars.allowlist` (empty = all). +- **Verified WebJar layouts (from Maven Central):** + - `org.webjars:bootstrap:5.3.8` → `META-INF/resources/webjars/bootstrap/5.3.8/css/bootstrap[.min].css`, `js/bootstrap.bundle[.min].js` (no `dist/` nesting). + - `org.webjars.npm:bootstrap-icons:1.13.1` → `.../bootstrap-icons/1.13.1/font/bootstrap-icons[.min].css` + `font/fonts/bootstrap-icons.woff2`. The icons CSS uses a relative `./fonts/…` font-face URL that resolves correctly when served from its `font/` dir — **no path rewriting needed**. + +## Prerequisites + +- **Struts 7.2.2 must be resolvable.** If it is already released to Maven Central, no extra config is needed. If not yet released, temporarily add the Apache snapshots repository to the **root** `pom.xml` and set `struts2.version` to `7.2.2-SNAPSHOT`: + +```xml + + + apache-snapshots + https://repository.apache.org/content/repositories/snapshots/ + false + true + + +``` + +Remove this repository block (and switch `7.2.2-SNAPSHOT` → `7.2.2`) before the plugin release. + +## File Structure + +- `pom.xml` (root) — bump `struts2.version`; add WebJar version properties + `dependencyManagement` entries. +- `struts2-bootstrap-plugin/pom.xml` — declare the two WebJar dependencies. +- `struts2-bootstrap-plugin/src/main/resources/template/bootstrap/head.ftl` — resolve Bootstrap/icons URLs via `<@s.webjar>`. +- `struts2-bootstrap-plugin/src/main/resources/template/bootstrap/css/**`, `js/bootstrap*.*`, `bootstrap-icons/**` — **deleted** (vendored assets removed; `validation.*` kept). +- `README.md` — compatibility table + install snippet. + +--- + +### Task 1: Add WebJar dependencies and raise the Struts floor to 7.2.2 + +**Files:** +- Modify: `pom.xml` (root) — `` (line ~67) and `` (lines 224-250) +- Modify: `struts2-bootstrap-plugin/pom.xml` — `` (lines 67-91) + +**Interfaces:** +- Produces: WebJar artifacts on the plugin's compile/runtime classpath (`org.webjars:bootstrap:5.3.8`, `org.webjars.npm:bootstrap-icons:1.13.1`) and Struts `7.2.2`, consumed by Task 2's `head.ftl` and Task 5's runtime verification. + +- [ ] **Step 1: Bump `struts2.version` in root `pom.xml`** + +Change line 67 from: + +```xml + 7.2.1 +``` + +to (use `7.2.2-SNAPSHOT` per Prerequisites if 7.2.2 is not yet released): + +```xml + 7.2.2 +``` + +- [ ] **Step 2: Add WebJar version properties in root `pom.xml`** + +Immediately after the `struts2.version` line, add: + +```xml + 5.3.8 + 1.13.1 +``` + +- [ ] **Step 3: Add WebJar `dependencyManagement` entries in root `pom.xml`** + +Inside `` (before the closing `` at line 249), add: + +```xml + + org.webjars + bootstrap + ${webjars-bootstrap.version} + + + org.webjars.npm + bootstrap-icons + ${webjars-bootstrap-icons.version} + +``` + +- [ ] **Step 4: Declare the WebJar dependencies in `struts2-bootstrap-plugin/pom.xml`** + +Inside `` (after the `struts2-core` dependency, ~line 76), add: + +```xml + + org.webjars + bootstrap + + + org.webjars.npm + bootstrap-icons + +``` + +- [ ] **Step 5: Verify resolution** + +Run: `mvn -q -pl struts2-bootstrap-plugin -am dependency:tree -Dincludes=org.webjars:bootstrap,org.webjars.npm:bootstrap-icons,org.apache.struts:struts2-core` + +Expected: output lists `org.webjars:bootstrap:jar:5.3.8`, `org.webjars.npm:bootstrap-icons:jar:1.13.1`, and `org.apache.struts:struts2-core:jar:7.2.2` (or `:7.2.2-SNAPSHOT`) with no resolution errors. + +- [ ] **Step 6: Commit** + +```bash +git add pom.xml struts2-bootstrap-plugin/pom.xml +git commit -m "build: add bootstrap/bootstrap-icons webjars, require struts 7.2.2" +``` + +--- + +### Task 2: Resolve Bootstrap/icons URLs via `<@s.webjar>` in `head.ftl` + +**Files:** +- Modify: `struts2-bootstrap-plugin/src/main/resources/template/bootstrap/head.ftl` (full rewrite of the logic below the license header) + +**Interfaces:** +- Consumes: the WebJar classpath from Task 1 and Struts' `<@s.webjar>` macro. +- Produces: rendered `