@woodsportal/hubspot-kit 5.0.3 → 5.0.4-beta.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@woodsportal/hubspot-kit",
-  "version": "5.0.3",
+  "version": "5.0.4-beta.0",
   "packageManager": "pnpm@10.12.1",
   "description": "WoodsCLI — HubSpot CMS dev kit by WoodsPortal. wp CLI, Vite presets, module-config overlay, and theme/module build pipelines.",
   "type": "module",
@@ -52,7 +52,7 @@
     "build": "tsup",
     "dev": "tsup --watch",
     "typecheck": "tsc --noEmit",
-    "test": "node --import tsx --test 'src/lib/**/*.test.ts' 'src/cli/**/*.test.ts' 'src/schema/**/*.test.ts' 'src/vite/**/*.test.ts' 'scripts/portal-build-id.test.mjs' 'scripts/resolve-consumer-dep.test.mjs' 'scripts/wp-cli-smoke.test.mjs' 'scripts/vite/ensure-dev-kit-shims.test.mjs' 'scripts/vite/consumer-react-aliases.test.mjs' 'scripts/vite/resolve-from-project-root.test.mjs' 'scripts/tailwind/prefix-plugin.test.mjs' && vitest run src/dev-module-config/__tests__/normalize-repeater-items.test.ts src/dev-module-config/__tests__/module-config-transform.test.ts src/dev-module-config/__tests__/flatten-visible-fields.test.ts src/dev-module-config/__tests__/drill-down-panels.test.ts",
+    "test": "node --import tsx --test 'src/lib/**/*.test.ts' 'src/cli/**/*.test.ts' 'src/schema/**/*.test.ts' 'src/vite/**/*.test.ts' 'scripts/portal-build-id.test.mjs' 'scripts/cdn-release-artifacts.test.mjs' 'scripts/hubspot-module-postbuild.test.mjs' 'scripts/resolve-consumer-dep.test.mjs' 'scripts/wp-cli-smoke.test.mjs' 'scripts/vite/ensure-dev-kit-shims.test.mjs' 'scripts/vite/consumer-react-aliases.test.mjs' 'scripts/vite/resolve-from-project-root.test.mjs' 'scripts/tailwind/prefix-plugin.test.mjs' && vitest run src/dev-module-config/__tests__/normalize-repeater-items.test.ts src/dev-module-config/__tests__/module-config-transform.test.ts src/dev-module-config/__tests__/flatten-visible-fields.test.ts src/dev-module-config/__tests__/drill-down-panels.test.ts",
     "test:examples": "node examples/smoke/run-matrix.mjs --tier static",
     "test:dist-pack": "node --test scripts/dist-cli-pack-smoke.test.mjs",
     "lint": "eslint src",

package/scripts/build-cdn.mjs

@@ -19,7 +19,35 @@ import {
 } from './portal-subprocess-stdio.mjs'
 import { spawnViteSync } from './resolve-vite-spawn.mjs'
 
+import { existsSync, mkdirSync, readdirSync, rmSync } from 'node:fs'
+
+/** Drop versioned CDN outputs from prior builds on the same worker. */
+function purgeStaleCdnArtifacts(cdnDir, buildId) {
+  if (!existsSync(cdnDir)) {
+    mkdirSync(cdnDir, { recursive: true })
+    return
+  }
+
+  for (const entry of readdirSync(cdnDir)) {
+    if (entry === 'assets') continue
+    const full = resolve(cdnDir, entry)
+    if (entry.endsWith('.js') || entry.endsWith('.css') || entry === 'manifest.json' || entry === 'n.json') {
+      rmSync(full, { force: true })
+      continue
+    }
+    if (entry === 'chunks') {
+      rmSync(full, { recursive: true, force: true })
+    }
+  }
+
+  if (buildId) {
+    console.log(`[build-cdn] purged prior dist/cdn artifacts before buildId ${buildId}`)
+  }
+}
+
+
 const root = findProjectRoot()
+const cdnDir = resolve(root, 'dist/cdn')
 
 const mode = resolvePortalViteMode()
 
@@ -31,6 +59,8 @@ const env = envForPortalBuild(mode, root, {
   VITE_DATADOG_RUM_ENABLED: defaultDatadogFlag(mode),
 })
 
+purgeStaleCdnArtifacts(cdnDir, env.MODULE_BUILD_ID ?? env.PORTAL_BUILD_ID)
+
 function runWithEnv(config, buildMode) {
   const result = spawnViteSync(
     root,

package/scripts/cdn-release-artifacts.mjs

@@ -0,0 +1,76 @@
+/**
+ * Resolve vendor/app/css filenames for the active CDN build id.
+ * Prevents stale dist/cdn artifacts from an older build id winning .find(name === 'vendor').
+ */
+
+/**
+ * @param {string} buildId
+ * @param {string} file
+ */
+export function cdnArtifactMatchesBuildId(buildId, file) {
+  return String(file).includes(buildId)
+}
+
+/**
+ * @param {string} role vendor | app
+ * @param {string} buildId
+ */
+export function expectedCdnScriptBasename(role, buildId) {
+  return `${role}.${buildId}.js`
+}
+
+/** @param {string} buildId */
+export function expectedCdnAppCssBasename(buildId) {
+  return `app.${buildId}.css`
+}
+
+/**
+ * @param {{ buildId: string, scripts?: Array<{ name?: string, file?: string }>, styles?: Array<{ name?: string, file?: string }> }} manifest
+ */
+export function resolveCdnPrimaryScripts(manifest) {
+  const buildId = manifest.buildId?.trim()
+  if (!buildId) {
+    throw new Error('manifest.json missing buildId')
+  }
+
+  const vendorExpected = expectedCdnScriptBasename('vendor', buildId)
+  const appExpected = expectedCdnScriptBasename('app', buildId)
+  const appCssExpected = expectedCdnAppCssBasename(buildId)
+
+  const vendor = manifest.scripts?.find((s) => s.file === vendorExpected)
+  const app = manifest.scripts?.find((s) => s.file === appExpected)
+  const appCss =
+    manifest.styles?.find((s) => s.file === appCssExpected) ??
+    manifest.styles?.find((s) => s.name === 'app' && s.file?.includes(buildId))
+
+  if (!vendor?.file || !app?.file) {
+    const vendorCandidates = (manifest.scripts ?? [])
+      .filter((s) => s.name === 'vendor')
+      .map((s) => s.file)
+      .join(', ')
+    const appCandidates = (manifest.scripts ?? [])
+      .filter((s) => s.name === 'app')
+      .map((s) => s.file)
+      .join(', ')
+    throw new Error(
+      `manifest.json must include ${vendorExpected} and ${appExpected} (buildId=${buildId}). ` +
+        `Found vendor=[${vendorCandidates || 'none'}], app=[${appCandidates || 'none'}]`,
+    )
+  }
+
+  if (!appCss?.file) {
+    throw new Error(`manifest.json must include ${appCssExpected} for buildId ${buildId}`)
+  }
+
+  for (const [label, file] of [
+    ['vendor', vendor.file],
+    ['app', app.file],
+    ['app css', appCss.file],
+  ]) {
+    if (!cdnArtifactMatchesBuildId(buildId, file)) {
+      throw new Error(`manifest ${label} file ${file} does not match buildId ${buildId}`)
+    }
+  }
+
+  return { buildId, vendorFile: vendor.file, appFile: app.file, appCssFile: appCss.file }
+}

package/scripts/cdn-release-artifacts.test.mjs

@@ -0,0 +1,20 @@
+import assert from 'node:assert/strict'
+import test from 'node:test'
+
+import { resolveCdnPrimaryScripts } from './cdn-release-artifacts.mjs'
+
+test('resolveCdnPrimaryScripts picks scripts for manifest buildId, not lexicographically first vendor', () => {
+  const manifest = {
+    buildId: '5.0.2-beta.802',
+    scripts: [
+      { name: 'vendor', file: 'vendor.5.0.2-beta.800.js' },
+      { name: 'vendor', file: 'vendor.5.0.2-beta.802.js' },
+      { name: 'app', file: 'app.5.0.2-beta.802.js' },
+    ],
+    styles: [{ name: 'app', file: 'app.5.0.2-beta.802.css' }],
+  }
+
+  const resolved = resolveCdnPrimaryScripts(manifest)
+  assert.equal(resolved.vendorFile, 'vendor.5.0.2-beta.802.js')
+  assert.equal(resolved.appFile, 'app.5.0.2-beta.802.js')
+})

package/scripts/generate-cdn-manifest.mjs

@@ -2,13 +2,21 @@
 /**
  * Write dist/cdn/manifest.json after vendor + app builds.
  */
-import { readdirSync, writeFileSync, statSync } from 'node:fs'
-import { resolve, dirname } from 'node:path'
-import { fileURLToPath } from 'node:url'
-import { findProjectRoot } from './project-root.mjs'
+import { readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { resolve } from 'node:path'
 import { gzipSync } from 'node:zlib'
-import { readFileSync } from 'node:fs'
-import { resolveCdnBaseUrl, portalBuildId } from './resolve-cdn-base-url.mjs'
+
+import {
+  cdnArtifactMatchesBuildId,
+  expectedCdnAppCssBasename,
+  expectedCdnScriptBasename,
+} from './cdn-release-artifacts.mjs'
+import { findProjectRoot } from './project-root.mjs'
+import { clearPortalBuildIdCache, resolveCdnBaseUrl, portalBuildId } from './resolve-cdn-base-url.mjs'
+
+if (process.env.MODULE_BUILD_ID?.trim() || process.env.PORTAL_BUILD_ID?.trim()) {
+  clearPortalBuildIdCache()
+}
 
 const root = findProjectRoot()
 const cdnDir = resolve(root, 'dist/cdn')
@@ -37,10 +45,23 @@ function scriptEntry(file) {
   return { name: file, order: 99, preload: false }
 }
 
-const jsFiles = readdirSync(cdnDir, { recursive: true })
+const allJsRelPaths = readdirSync(cdnDir, { recursive: true })
   .filter((f) => String(f).endsWith('.js'))
-  .map((rel) => {
-    const file = String(rel)
+  .map(String)
+
+const staleJs = allJsRelPaths.filter((file) => !cdnArtifactMatchesBuildId(buildId, file))
+if (staleJs.length > 0) {
+  console.warn(
+    `[cdn-manifest] removing ${staleJs.length} stale .js artifact(s) for buildId ${buildId}: ${staleJs.join(', ')}`,
+  )
+  for (const file of staleJs) {
+    rmSync(resolve(cdnDir, file), { force: true })
+  }
+}
+
+const jsFiles = allJsRelPaths
+  .filter((file) => cdnArtifactMatchesBuildId(buildId, file))
+  .map((file) => {
     const metrics = fileMetrics(file)
     const entry = scriptEntry(file)
     return {
@@ -50,8 +71,19 @@ const jsFiles = readdirSync(cdnDir, { recursive: true })
   })
   .sort((a, b) => a.order - b.order || a.file.localeCompare(b.file))
 
-const cssFiles = readdirSync(cdnDir)
-  .filter((f) => f.endsWith('.css'))
+const allCssFiles = readdirSync(cdnDir).filter((f) => f.endsWith('.css'))
+const staleCss = allCssFiles.filter((file) => !cdnArtifactMatchesBuildId(buildId, file))
+if (staleCss.length > 0) {
+  console.warn(
+    `[cdn-manifest] removing ${staleCss.length} stale .css artifact(s) for buildId ${buildId}: ${staleCss.join(', ')}`,
+  )
+  for (const file of staleCss) {
+    rmSync(resolve(cdnDir, file), { force: true })
+  }
+}
+
+const cssFiles = allCssFiles
+  .filter((file) => cdnArtifactMatchesBuildId(buildId, file))
   .map((file) => {
     const metrics = fileMetrics(file)
     return {
@@ -61,15 +93,22 @@ const cssFiles = readdirSync(cdnDir)
     }
   })
 
-const appCss = cssFiles.find((f) => f.name === 'app') ?? cssFiles[0]
+const vendorExpected = expectedCdnScriptBasename('vendor', buildId)
+const appExpected = expectedCdnScriptBasename('app', buildId)
+const appCssExpected = expectedCdnAppCssBasename(buildId)
 
-if (!jsFiles.some((f) => f.name === 'vendor') || !jsFiles.some((f) => f.name === 'app')) {
-  console.error('[cdn-manifest] expected vendor.*.js and app.*.js in dist/cdn/')
+if (!jsFiles.some((f) => f.file === vendorExpected) || !jsFiles.some((f) => f.file === appExpected)) {
+  console.error(
+    `[cdn-manifest] expected ${vendorExpected} and ${appExpected} in dist/cdn/ (buildId=${buildId})`,
+  )
+  console.error(`[cdn-manifest] found js: ${jsFiles.map((f) => f.file).join(', ') || '(none)'}`)
   process.exit(1)
 }
 
+const appCss = cssFiles.find((f) => f.file === appCssExpected) ?? cssFiles.find((f) => f.name === 'app')
+
 if (!appCss) {
-  console.error('[cdn-manifest] expected app.*.css in dist/cdn/ — component styles load from CDN')
+  console.error(`[cdn-manifest] expected ${appCssExpected} in dist/cdn/ — component styles load from CDN`)
   process.exit(1)
 }
 

package/scripts/hubspot-module-postbuild.mjs

@@ -13,6 +13,7 @@ import {
   writeFileSync,
 } from 'node:fs'
 import { resolve } from 'node:path'
+import { resolveCdnPrimaryScripts } from './cdn-release-artifacts.mjs'
 
 /** Substrings that break when HubSpot tokenizes module.js (Jinja/HubL). */
 export const FORBIDDEN_HUBL_IN_MODULE_JS = ['{{', '{%', '<%', '%>']
@@ -54,14 +55,70 @@ export function assertValidJavaScriptSyntax(jsPath) {
   execSync(`node --check ${JSON.stringify(jsPath)}`, { stdio: 'pipe' })
 }
 
+/**
+ * CodeBuild sets MODULE_BUILD_ID; never let a leftover manifest.buildId win.
+ * @param {{ buildId?: string }} manifest
+ * @param {NodeJS.ProcessEnv} [env]
+ */
+export function resolveInjectBuildId(manifest, env = process.env) {
+  const envId = env.MODULE_BUILD_ID?.trim() || env.PORTAL_BUILD_ID?.trim()
+  const manifestId = manifest.buildId?.trim()
+  const buildId = envId || manifestId
+  if (!buildId) {
+    throw new Error('module.html inject needs manifest.buildId or MODULE_BUILD_ID')
+  }
+  return buildId
+}
+
+/**
+ * Pin HubL/JS CDN fields even when a stale worker already baked an older build id.
+ * @param {string} html
+ * @param {{ baseUrl: string, buildId: string, vendorFile: string, appFile: string, appCssFile: string }} pins
+ */
+export function pinModuleHtmlCdnUrls(html, pins) {
+  const { baseUrl, buildId, vendorFile, appFile, appCssFile } = pins
+  let out = html
+    .replaceAll('__PORTAL_CDN_BASE__', baseUrl)
+    .replaceAll('__PORTAL_BUILD_ID__', buildId)
+    .replaceAll('__PORTAL_VENDOR_FILE__', vendorFile)
+    .replaceAll('__PORTAL_APP_FILE__', appFile)
+    .replaceAll('__PORTAL_APP_CSS_FILE__', appCssFile)
+
+  out = out.replace(/assetBaseUrl:\s*"[^"]*"/g, `assetBaseUrl: "${baseUrl}"`)
+  out = out.replace(/buildId:\s*"[^"]*"/g, `buildId: "${buildId}"`)
+  out = out.replace(
+    /\{% set portal_cdn_base = "[^"]*" %\}/g,
+    `{% set portal_cdn_base = "${baseUrl}" %}`,
+  )
+  out = out.replace(
+    /\{% set portal_vendor_script = "[^"]*" %\}/g,
+    `{% set portal_vendor_script = "${vendorFile}" %}`,
+  )
+  out = out.replace(
+    /\{% set portal_app_script = "[^"]*" %\}/g,
+    `{% set portal_app_script = "${appFile}" %}`,
+  )
+
+  if (!out.includes(buildId) || !out.includes(vendorFile) || !out.includes(appFile)) {
+    throw new Error(
+      `module.html inject failed: expected ${vendorFile} and ${appFile} for buildId ${buildId}`,
+    )
+  }
+  if (out.includes('__PORTAL_')) {
+    throw new Error('module.html still has CDN placeholders after inject')
+  }
+  return out
+}
+
 /**
  * Replace CDN placeholders in module.html from dist/cdn/manifest.json.
  * @param {string} html
  * @param {string} manifestPath
+ * @param {NodeJS.ProcessEnv} [env]
  */
-export function injectCdnManifestIntoModuleHtml(html, manifestPath) {
+export function injectCdnManifestIntoModuleHtml(html, manifestPath, env = process.env) {
   if (!existsSync(manifestPath)) {
-    if (html.includes('__PORTAL_CDN_BASE__')) {
+    if (html.includes('__PORTAL_CDN_BASE__') || /vendor\.\d/.test(html) || html.includes('portal_vendor_script')) {
       throw new Error(
         `Missing ${manifestPath} — run yarn build:cdn:dev or yarn build:cdn:prod before hubspot post-build`,
       )
@@ -70,24 +127,16 @@ export function injectCdnManifestIntoModuleHtml(html, manifestPath) {
   }
 
   const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'))
-  const vendor = manifest.scripts?.find((s) => s.name === 'vendor')
-  const app = manifest.scripts?.find((s) => s.name === 'app')
-  const appCss = manifest.styles?.find((s) => s.name === 'app') ?? manifest.styles?.[0]
-
-  if (!vendor?.file || !app?.file) {
-    throw new Error('manifest.json must include vendor and app scripts')
-  }
-
-  if (!appCss?.file) {
-    throw new Error('manifest.json must include app styles (app.*.css from yarn build:cdn:dev or build:cdn:prod)')
-  }
-
-  return html
-    .replaceAll('__PORTAL_CDN_BASE__', manifest.baseUrl)
-    .replaceAll('__PORTAL_BUILD_ID__', manifest.buildId)
-    .replaceAll('__PORTAL_VENDOR_FILE__', vendor.file)
-    .replaceAll('__PORTAL_APP_FILE__', app.file)
-    .replaceAll('__PORTAL_APP_CSS_FILE__', appCss.file)
+  const buildId = resolveInjectBuildId(manifest, env)
+  const { vendorFile, appFile, appCssFile } = resolveCdnPrimaryScripts({ ...manifest, buildId })
+
+  return pinModuleHtmlCdnUrls(html, {
+    baseUrl: manifest.baseUrl,
+    buildId,
+    vendorFile,
+    appFile,
+    appCssFile,
+  })
 }
 
 /**
@@ -100,12 +149,10 @@ export function mergeCdnAppStylesIntoModuleCss(moduleDir, manifestPath) {
   }
 
   const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'))
-  const appCss = manifest.styles?.find((s) => s.name === 'app') ?? manifest.styles?.[0]
-  if (!appCss?.file) {
-    throw new Error('manifest.json must include app styles for module.css merge')
-  }
+  const buildId = resolveInjectBuildId(manifest)
+  const { appCssFile } = resolveCdnPrimaryScripts({ ...manifest, buildId })
 
-  const cdnCssPath = resolve(moduleDir, '../cdn', appCss.file)
+  const cdnCssPath = resolve(moduleDir, '../cdn', appCssFile)
   if (!existsSync(cdnCssPath)) {
     throw new Error(
       `Missing ${cdnCssPath} — run build:cdn before hubspot post-build (needed for module.css)`,

package/scripts/hubspot-module-postbuild.test.mjs

@@ -0,0 +1,86 @@
+import assert from 'node:assert/strict'
+import { mkdtempSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { describe, it } from 'node:test'
+
+import {
+  injectCdnManifestIntoModuleHtml,
+  pinModuleHtmlCdnUrls,
+  resolveInjectBuildId,
+} from './hubspot-module-postbuild.mjs'
+
+const placeholders = `        assetBaseUrl: "__PORTAL_CDN_BASE__",
+        buildId: "__PORTAL_BUILD_ID__",
+{% set portal_cdn_base = "__PORTAL_CDN_BASE__" %}
+{% set portal_vendor_script = "__PORTAL_VENDOR_FILE__" %}
+{% set portal_app_script = "__PORTAL_APP_FILE__" %}
+`
+
+const baked800 = `        assetBaseUrl: "https://cdn.example/cdn",
+        buildId: "5.0.2-beta.800",
+{% set portal_cdn_base = "https://cdn.example/cdn" %}
+{% set portal_vendor_script = "vendor.5.0.2-beta.800.js" %}
+{% set portal_app_script = "app.5.0.2-beta.800.js" %}
+`
+
+describe('resolveInjectBuildId', () => {
+  it('prefers MODULE_BUILD_ID over a stale manifest.buildId', () => {
+    assert.equal(
+      resolveInjectBuildId({ buildId: '5.0.2-beta.800' }, { MODULE_BUILD_ID: '5.0.2-beta.804' }),
+      '5.0.2-beta.804',
+    )
+  })
+})
+
+describe('pinModuleHtmlCdnUrls', () => {
+  it('rewrites leftover baked 800 pins to the current build id', () => {
+    const out = pinModuleHtmlCdnUrls(baked800, {
+      baseUrl: 'https://cdn.example/cdn',
+      buildId: '5.0.2-beta.804',
+      vendorFile: 'vendor.5.0.2-beta.804.js',
+      appFile: 'app.5.0.2-beta.804.js',
+      appCssFile: 'app.5.0.2-beta.804.css',
+    })
+    assert.match(out, /buildId: "5\.0\.2-beta\.804"/)
+    assert.match(out, /vendor\.5\.0\.2-beta\.804\.js/)
+    assert.match(out, /app\.5\.0\.2-beta\.804\.js/)
+    assert.doesNotMatch(out, /5\.0\.2-beta\.800/)
+  })
+})
+
+describe('injectCdnManifestIntoModuleHtml', () => {
+  it('pins vendor/app from MODULE_BUILD_ID even when the manifest still lists 800 first', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'wp-mod-html-'))
+    const manifestPath = join(dir, 'manifest.json')
+    writeFileSync(
+      manifestPath,
+      JSON.stringify({
+        baseUrl: 'https://cdn.example/cdn',
+        buildId: '5.0.2-beta.800',
+        scripts: [
+          { name: 'vendor', file: 'vendor.5.0.2-beta.800.js' },
+          { name: 'vendor', file: 'vendor.5.0.2-beta.804.js' },
+          { name: 'app', file: 'app.5.0.2-beta.800.js' },
+          { name: 'app', file: 'app.5.0.2-beta.804.js' },
+        ],
+        styles: [
+          { name: 'app', file: 'app.5.0.2-beta.800.css' },
+          { name: 'app', file: 'app.5.0.2-beta.804.css' },
+        ],
+      }),
+    )
+
+    const fromPlaceholders = injectCdnManifestIntoModuleHtml(placeholders, manifestPath, {
+      MODULE_BUILD_ID: '5.0.2-beta.804',
+    })
+    assert.match(fromPlaceholders, /vendor\.5\.0\.2-beta\.804\.js/)
+    assert.doesNotMatch(fromPlaceholders, /5\.0\.2-beta\.800/)
+
+    const fromBaked = injectCdnManifestIntoModuleHtml(baked800, manifestPath, {
+      MODULE_BUILD_ID: '5.0.2-beta.804',
+    })
+    assert.match(fromBaked, /vendor\.5\.0\.2-beta\.804\.js/)
+    assert.doesNotMatch(fromBaked, /5\.0\.2-beta\.800/)
+  })
+})

package/scripts/portal-build-id.test.mjs

@@ -20,6 +20,16 @@ import {
 import { wphsPaths } from './wphs-paths.mjs'
 
 const roots = []
+/** CI sets GITHUB_REF_NAME; local bump tests must not inherit it (legacy override is tested separately). */
+function localBuildIdEnv(overrides = {}) {
+  const env = { ...process.env }
+  delete env.GITHUB_REF_NAME
+  delete env.GITHUB_REF
+  delete env.PORTAL_BUILD_ID
+  delete env.MODULE_BUILD_ID
+  return { ...env, ...overrides }
+}
+
 
 function makeProject() {
   const root = mkdtempSync(join(tmpdir(), 'wp-build-id-'))
@@ -100,11 +110,11 @@ describe('bumpModuleBuildId', () => {
     const root = makeProject()
     writeFileSync(join(root, '.wphs', 'config', 'developer.json'), JSON.stringify({ slug: 'manab' }))
 
-    const first = bumpModuleBuildId({ projectRoot: root, tier: 'dev' })
+    const first = bumpModuleBuildId({ projectRoot: root, tier: 'dev', env: localBuildIdEnv() })
     assert.equal(first.id, 'v0.0.1-dev.manab.1')
     assert.equal(first.bumped, true)
 
-    const second = bumpModuleBuildId({ projectRoot: root, tier: 'dev' })
+    const second = bumpModuleBuildId({ projectRoot: root, tier: 'dev', env: localBuildIdEnv() })
     assert.equal(second.id, 'v0.0.1-dev.manab.2')
 
     const statePath = join(wphsPaths(root).stateDir, 'module-build-id.json')
@@ -112,6 +122,19 @@ describe('bumpModuleBuildId', () => {
     assert.equal(state.seq, 2)
   })
 
+  it('uses GITHUB_REF_NAME when set (legacy resolvePortalBuildId CI pin)', () => {
+    const root = makeProject()
+    writeFileSync(join(root, '.wphs', 'config', 'developer.json'), JSON.stringify({ slug: 'manab' }))
+
+    const result = bumpModuleBuildId({
+      projectRoot: root,
+      env: localBuildIdEnv({ GITHUB_REF_NAME: '5.0.2-beta.802' }),
+    })
+    assert.equal(result.id, '5.0.2-beta.802')
+    assert.equal(result.bumped, false)
+    assert.equal(result.source, 'github-ref')
+  })
+
   it('respects env override without bumping', () => {
     const root = makeProject()
     const result = bumpModuleBuildId({

package/scripts/resolve-cdn-base-url.mjs

@@ -2,9 +2,9 @@
  * Resolve CDN base URL from env (jsDelivr GitHub, custom, or local).
  */
 import { loadPortalCdnConfig } from './load-portal-cdn-config.mjs'
-import { portalBuildId, resolvePortalBuildId } from './resolve-portal-build-id.mjs'
+import { clearPortalBuildIdCache, portalBuildId, resolvePortalBuildId } from './resolve-portal-build-id.mjs'
 
-export { portalBuildId, resolvePortalBuildId }
+export { clearPortalBuildIdCache, portalBuildId, resolvePortalBuildId }
 
 export function resolveCdnBaseUrl(env = process.env) {
   const config = loadPortalCdnConfig(env)