From a5f6603e61762d9f11073a851a08ed42f7c838ae Mon Sep 17 00:00:00 2001
From: Vincent Koc <vincentkoc@ieee.org>
Date: Sun, 26 Apr 2026 19:05:09 -0700
Subject: [PATCH] fix(release): clarify control ui build requirement

---
 scripts/release-check.ts   | 35 ++++++++++++++++++++++++-----------
 test/release-check.test.ts | 27 +++++++++++++++++++++++++++
 2 files changed, 51 insertions(+), 11 deletions(-)

diff --git a/scripts/release-check.ts b/scripts/release-check.ts
index ea039f7d2fc..7f598ada691 100755
--- a/scripts/release-check.ts
+++ b/scripts/release-check.ts
@@ -590,6 +590,27 @@ export function collectMissingPackPaths(paths: Iterable<string>): string[] {
     .toSorted((left, right) => left.localeCompare(right));
 }
 
+export function resolveMissingPackBuildHint(missing: readonly string[]): string | null {
+  const needsControlUiBuild = missing.includes("dist/control-ui/index.html");
+  const needsRuntimeBuild = missing.some(
+    (path) =>
+      path !== "dist/control-ui/index.html" &&
+      (path === "dist/build-info.json" || path.startsWith("dist/")),
+  );
+
+  if (!needsControlUiBuild && !needsRuntimeBuild) {
+    return null;
+  }
+
+  if (needsControlUiBuild && needsRuntimeBuild) {
+    return "release-check: build and Control UI artifacts are missing. Run `pnpm build && pnpm ui:build` before `pnpm release:check`.";
+  }
+  if (needsControlUiBuild) {
+    return "release-check: Control UI artifacts are missing. Run `pnpm ui:build` before `pnpm release:check`.";
+  }
+  return "release-check: build artifacts are missing. Run `pnpm build` before `pnpm release:check`.";
+}
+
 export function collectForbiddenPackPaths(paths: Iterable<string>): string[] {
   return [...paths]
     .filter(
@@ -817,17 +838,9 @@ async function main() {
       for (const path of missing) {
         console.error(`  - ${path}`);
       }
-      if (
-        missing.some(
-          (path) =>
-            path === "dist/build-info.json" ||
-            path === "dist/control-ui/index.html" ||
-            path.startsWith("dist/"),
-        )
-      ) {
-        console.error(
-          "release-check: build artifacts are missing. Run `pnpm build` before `pnpm release:check`.",
-        );
+      const buildHint = resolveMissingPackBuildHint(missing);
+      if (buildHint) {
+        console.error(buildHint);
       }
     }
     if (forbidden.length > 0) {
diff --git a/test/release-check.test.ts b/test/release-check.test.ts
index a92d5449646..f3fae32e6cf 100644
--- a/test/release-check.test.ts
+++ b/test/release-check.test.ts
@@ -21,6 +21,7 @@ import {
   createPackedBundledPluginPostinstallEnv,
   PACKED_CLI_SMOKE_COMMANDS,
   packageNameFromSpecifier,
+  resolveMissingPackBuildHint,
 } from "../scripts/release-check.ts";
 import { PACKAGE_DIST_INVENTORY_RELATIVE_PATH } from "../src/infra/package-dist-inventory.ts";
 import { bundledDistPluginFile, bundledPluginFile } from "./helpers/bundled-plugin-paths.js";
@@ -585,6 +586,32 @@ describe("collectMissingPackPaths", () => {
   });
 });
 
+describe("resolveMissingPackBuildHint", () => {
+  it("points missing runtime build artifacts at pnpm build", () => {
+    expect(resolveMissingPackBuildHint(["dist/build-info.json"])).toBe(
+      "release-check: build artifacts are missing. Run `pnpm build` before `pnpm release:check`.",
+    );
+  });
+
+  it("points missing Control UI artifacts at pnpm ui:build", () => {
+    expect(resolveMissingPackBuildHint(["dist/control-ui/index.html"])).toBe(
+      "release-check: Control UI artifacts are missing. Run `pnpm ui:build` before `pnpm release:check`.",
+    );
+  });
+
+  it("points combined runtime and Control UI misses at both build commands", () => {
+    expect(
+      resolveMissingPackBuildHint(["dist/build-info.json", "dist/control-ui/index.html"]),
+    ).toBe(
+      "release-check: build and Control UI artifacts are missing. Run `pnpm build && pnpm ui:build` before `pnpm release:check`.",
+    );
+  });
+
+  it("does not emit a build hint for unrelated packed paths", () => {
+    expect(resolveMissingPackBuildHint(["scripts/npm-runner.mjs"])).toBeNull();
+  });
+});
+
 describe("collectPackUnpackedSizeErrors", () => {
   it("accepts pack results within the unpacked size budget", () => {
     expect(