(hamilton) 01/01: Add frontend build step to UI release process

[sk...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

skrawcz pushed a commit to branch stefan/fix-ui-frontend-build
in repository https://gitbox.apache.org/repos/asf/hamilton.git

commit 8380900e69cb2af1ec6a82f72074775f1040cc0e
Author: Stefan Krawczyk <st...@cs.stanford.edu>
AuthorDate: Wed May 27 22:12:25 2026 -0700

    Add frontend build step to UI release process
    
    The UI wheel must include compiled frontend assets (hamilton_ui/build/).
    This directory is gitignored and only exists after npm run build.
    
    - apache_release_helper.py: automatically runs npm install + npm run build
      and copies output to hamilton_ui/build/ before flit build for the UI package
    - verify-sub-packages.md: documents manual frontend build steps
    - verify_ui.sh: notes that source tarball build is backend-only;
      functional tests use the pre-compiled wheel from SVN
---
 scripts/apache_release_helper.py         | 28 ++++++++++++++++++++++++++++
 scripts/verify-sub-packages.md           | 22 ++++++++++++++++++++++
 scripts/verify-sub-packages/verify_ui.sh |  7 ++++++-
 3 files changed, 56 insertions(+), 1 deletion(-)

diff --git a/scripts/apache_release_helper.py b/scripts/apache_release_helper.py
index 08ea342d..d078f0e9 100644
--- a/scripts/apache_release_helper.py
+++ b/scripts/apache_release_helper.py
@@ -320,6 +320,34 @@ def create_release_artifacts(package_config: dict, version) -> list[str]:
         if os.path.exists("dist"):
             shutil.rmtree("dist")
 
+        # For the UI package, build the frontend before packaging.
+        if package_name == "apache-hamilton-ui":
+            print("Building UI frontend (npm install + npm run build)...")
+            frontend_dir = os.path.join(original_dir, "ui", "frontend")
+            build_target = os.path.join("hamilton_ui", "build")
+            try:
+                subprocess.run(
+                    ["npm", "install", "--prefix", frontend_dir],
+                    check=True,
+                )
+                subprocess.run(
+                    ["npm", "run", "build", "--prefix", frontend_dir],
+                    check=True,
+                )
+                # Copy built assets to hamilton_ui/build/
+                if os.path.exists(build_target):
+                    shutil.rmtree(build_target)
+                # Vite outputs to frontend/dist/, CRA outputs to frontend/build/
+                frontend_build = os.path.join(frontend_dir, "dist")
+                if not os.path.exists(frontend_build):
+                    frontend_build = os.path.join(frontend_dir, "build")
+                shutil.copytree(frontend_build, build_target)
+                print(f"Frontend built and copied to {build_target}")
+            except (subprocess.CalledProcessError, FileNotFoundError) as e:
+                print(f"Error building frontend: {e}")
+                print("Ensure Node.js and npm are installed.")
+                return None
+
         # Use flit build to create the source distribution.
         try:
             subprocess.run(
diff --git a/scripts/verify-sub-packages.md b/scripts/verify-sub-packages.md
index f0147428..c7d5cb9a 100644
--- a/scripts/verify-sub-packages.md
+++ b/scripts/verify-sub-packages.md
@@ -79,6 +79,28 @@ See `examples/hamilton_ui/` — the same example above.
 
 ## apache-hamilton-ui
 
+### Building from source (requires Node.js + npm)
+
+The UI package includes compiled frontend assets. When building from source,
+you must build the frontend first:
+
+```bash
+cd ui/frontend
+npm install
+npm run build
+
+# Copy built assets to the backend package
+rm -rf ../backend/hamilton_ui/build
+cp -r dist/ ../backend/hamilton_ui/build/
+
+# Now build the wheel
+cd ../backend
+flit build --no-use-vcs
+```
+
+The release script (`scripts/apache_release_helper.py --package ui`) handles
+this automatically.
+
 ### Install and verify
 
 ```bash
diff --git a/scripts/verify-sub-packages/verify_ui.sh b/scripts/verify-sub-packages/verify_ui.sh
index 0d6fa1ef..feedca1c 100755
--- a/scripts/verify-sub-packages/verify_ui.sh
+++ b/scripts/verify-sub-packages/verify_ui.sh
@@ -116,8 +116,13 @@ build_dir="/tmp/build-ui-$$"
 mkdir -p "$build_dir"
 tar xzf "$ARTIFACTS_DIR/$SRC_TAR" -C "$build_dir"
 src_dir=$(ls -d ${build_dir}/*/ | head -1)
+
+# Note: The UI source tarball does not include compiled frontend assets.
+# The release script builds the frontend (npm run build) before flit build.
+# Here we verify the backend builds correctly; the wheel from SVN includes
+# the pre-compiled frontend and is what's tested in step 6.
 if (cd "$src_dir" && flit build --no-use-vcs) 2>&1 | grep -q "Built wheel"; then
-    echo "  ✓ Built from source successfully"
+    echo "  ✓ Built from source successfully (backend only, frontend is pre-compiled in wheel)"
 else
     echo "  ✗ Build from source failed"
     rm -rf "$build_dir"