@woodsportal/hubspot-kit 1.0.31 → 1.0.34

package/scripts/portal-build-id.mjs

@@ -0,0 +1,346 @@
+/**
+ * Module build ID: per-developer CDN pins, auto-increment, and layered resolution.
+ */
+import { spawnSync } from 'node:child_process'
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+import { resolveProjectConfigPath } from './config-files.mjs'
+import { findProjectRoot } from './project-root.mjs'
+import { wphsPaths } from './wphs-paths.mjs'
+
+export const LEGACY_BUILD_ID_FILE = '.portal-build-id'
+export const DEFAULT_BUILD_ID_FILE = '.module-build-id'
+export const MODULE_BUILD_ID_STATE_FILE = 'module-build-id.json'
+export const DEVELOPER_CONFIG_FILE = 'developer.json'
+
+const SLUG_MAX_LEN = 12
+const SLUG_PATTERN = /^[a-z0-9](?:[a-z0-9-]{0,10}[a-z0-9])?$/
+
+/**
+ * @param {string} input
+ */
+export function sanitizeDevSlug(input) {
+  if (!input?.trim()) return undefined
+  const slug = input
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, SLUG_MAX_LEN)
+  if (!slug || !SLUG_PATTERN.test(slug)) return undefined
+  return slug
+}
+
+/**
+ * @param {string} baseline
+ * @param {string} slug
+ * @param {number} seq
+ */
+export function formatBuildId(baseline, slug, seq) {
+  const base = baseline?.trim()
+  const devSlug = sanitizeDevSlug(slug)
+  const n = Number(seq)
+  if (!base) {
+    throw new Error('module build id baseline is required')
+  }
+  if (!devSlug) {
+    throw new Error('module build id dev slug is required')
+  }
+  if (!Number.isInteger(n) || n < 1) {
+    throw new Error(`module build id seq must be a positive integer (got ${seq})`)
+  }
+  const id = `${base}.${devSlug}.${n}`
+  if (!isGitTagSafe(id)) {
+    throw new Error(`module build id is not git-tag safe: ${id}`)
+  }
+  return id
+}
+
+/**
+ * @param {string} value
+ */
+export function isGitTagSafe(value) {
+  if (!value?.trim()) return false
+  if (value.includes(' ') || value.includes('..')) return false
+  return /^[A-Za-z0-9._-]+$/.test(value)
+}
+
+/**
+ * Strip legacy numeric or per-dev suffixes to recover channel baseline.
+ * @param {string} raw
+ */
+export function stripToBaseline(raw) {
+  const line = raw?.trim()
+  if (!line) return undefined
+
+  const perDev = line.match(/^(v\d+\.\d+\.\d+(?:-[a-z0-9]+)?)\.[a-z0-9-]{1,12}\.\d+$/i)
+  if (perDev) return perDev[1]
+
+  const numericSuffix = line.match(/^(v\d+\.\d+\.\d+(?:-[a-z0-9]+)?)\.\d+$/)
+  if (numericSuffix) return numericSuffix[1]
+
+  return line
+}
+
+/**
+ * @param {string} projectRoot
+ */
+export function getBuildIdFilePath(projectRoot) {
+  const configPath = resolveProjectConfigPath(projectRoot)
+  if (configPath) {
+    try {
+      const config = JSON.parse(readFileSync(configPath, 'utf8'))
+      if (config.cdn?.buildIdFile) {
+        return resolve(projectRoot, config.cdn.buildIdFile)
+      }
+    } catch {
+      // ignore invalid config
+    }
+  }
+  return resolve(projectRoot, DEFAULT_BUILD_ID_FILE)
+}
+
+/**
+ * @param {string} projectRoot
+ */
+export function getLegacyBuildIdFilePath(projectRoot) {
+  return resolve(projectRoot, LEGACY_BUILD_ID_FILE)
+}
+
+/**
+ * @param {string} filePath
+ */
+function readFirstLine(filePath) {
+  if (!existsSync(filePath)) return undefined
+  const line = readFileSync(filePath, 'utf8')
+    .split('\n')
+    .map((l) => l.trim())
+    .find((l) => l.length > 0 && !l.startsWith('#'))
+  return line || undefined
+}
+
+/**
+ * @param {string} projectRoot
+ */
+export function readBaselineBuildId(projectRoot) {
+  const primary = getBuildIdFilePath(projectRoot)
+  const fromPrimary = readFirstLine(primary)
+  if (fromPrimary) return stripToBaseline(fromPrimary)
+
+  const legacy = getLegacyBuildIdFilePath(projectRoot)
+  const fromLegacy = readFirstLine(legacy)
+  if (fromLegacy) return stripToBaseline(fromLegacy)
+
+  return undefined
+}
+
+/**
+ * @param {string} projectRoot
+ */
+export function moduleBuildIdStatePath(projectRoot) {
+  return resolve(wphsPaths(projectRoot).stateDir, MODULE_BUILD_ID_STATE_FILE)
+}
+
+/**
+ * @param {string} projectRoot
+ */
+export function developerConfigPath(projectRoot) {
+  return resolve(wphsPaths(projectRoot).configDir, DEVELOPER_CONFIG_FILE)
+}
+
+/**
+ * @typedef {{ slug?: string, seq?: number, baseline?: string, tier?: string, updatedAt?: string }} ModuleBuildIdState
+ */
+
+/**
+ * @param {string} projectRoot
+ * @returns {ModuleBuildIdState | undefined}
+ */
+export function readModuleBuildIdState(projectRoot) {
+  const path = moduleBuildIdStatePath(projectRoot)
+  if (!existsSync(path)) return undefined
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'))
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * @param {string} projectRoot
+ * @param {ModuleBuildIdState} state
+ * @param {boolean} [dryRun]
+ */
+export function writeModuleBuildIdState(projectRoot, state, dryRun = false) {
+  const path = moduleBuildIdStatePath(projectRoot)
+  if (!dryRun) {
+    mkdirSync(resolve(path, '..'), { recursive: true })
+    writeFileSync(path, `${JSON.stringify(state, null, 2)}\n`)
+  }
+  return path
+}
+
+/**
+ * @param {NodeJS.ProcessEnv} [env]
+ */
+export function readEnvBuildIdOverride(env = process.env) {
+  const explicit = env.PORTAL_BUILD_ID?.trim() || env.MODULE_BUILD_ID?.trim()
+  if (explicit) {
+    return { id: explicit, source: 'env' }
+  }
+  const ref = env.GITHUB_REF_NAME?.trim()
+  if (ref) {
+    return { id: ref, source: 'github-ref' }
+  }
+  return undefined
+}
+
+/**
+ * @param {NodeJS.ProcessEnv} [env]
+ */
+export function hasExplicitBuildIdOverride(env = process.env) {
+  return Boolean(readEnvBuildIdOverride(env))
+}
+
+/**
+ * @param {NodeJS.ProcessEnv} [env]
+ * @param {string} [projectRoot]
+ */
+export function resolveDevSlug(env = process.env, projectRoot = findProjectRoot()) {
+  const fromEnv = sanitizeDevSlug(env.PORTAL_CDN_DEV_SLUG) ?? sanitizeDevSlug(env.MODULE_CDN_DEV_SLUG)
+  if (fromEnv) return fromEnv
+
+  const devConfigPath = developerConfigPath(projectRoot)
+  if (existsSync(devConfigPath)) {
+    try {
+      const raw = JSON.parse(readFileSync(devConfigPath, 'utf8'))
+      const fromFile = sanitizeDevSlug(raw?.slug)
+      if (fromFile) return fromFile
+    } catch {
+      // ignore
+    }
+  }
+
+  const gitName = spawnSync('git', ['config', 'user.name'], {
+    encoding: 'utf8',
+    cwd: projectRoot,
+  })
+  if (gitName.status === 0) {
+    const fromGit = sanitizeDevSlug(gitName.stdout)
+    if (fromGit) return fromGit
+  }
+
+  return undefined
+}
+
+/**
+ * @typedef {'env' | 'github-ref' | 'state' | 'baseline' | 'fallback'} BuildIdSource
+ */
+
+/**
+ * @param {NodeJS.ProcessEnv} [env]
+ * @param {string} [projectRoot]
+ */
+export function resolveModuleBuildIdMeta(env = process.env, projectRoot = findProjectRoot()) {
+  const override = readEnvBuildIdOverride(env)
+  if (override) {
+    return { id: override.id, source: override.source, slug: undefined, seq: undefined, baseline: undefined }
+  }
+
+  const baseline = readBaselineBuildId(projectRoot)
+  const state = readModuleBuildIdState(projectRoot)
+  const slug = sanitizeDevSlug(state?.slug) ?? resolveDevSlug(env, projectRoot)
+
+  if (baseline && slug && state?.seq && Number.isInteger(state.seq) && state.seq >= 1) {
+    const stateBaseline = state.baseline ? stripToBaseline(state.baseline) : baseline
+    return {
+      id: formatBuildId(stateBaseline ?? baseline, slug, state.seq),
+      source: 'state',
+      slug,
+      seq: state.seq,
+      baseline: stateBaseline ?? baseline,
+    }
+  }
+
+  if (baseline) {
+    return { id: baseline, source: 'baseline', slug, seq: undefined, baseline }
+  }
+
+  return { id: 'dev', source: 'fallback', slug, seq: undefined, baseline: undefined }
+}
+
+/**
+ * @param {NodeJS.ProcessEnv} [env]
+ * @param {string} [projectRoot]
+ */
+export function resolveModuleBuildId(env = process.env, projectRoot = findProjectRoot()) {
+  return resolveModuleBuildIdMeta(env, projectRoot).id
+}
+
+/**
+ * @param {{ projectRoot?: string, tier?: string, dryRun?: boolean, env?: NodeJS.ProcessEnv }} [options]
+ */
+export function bumpModuleBuildId(options = {}) {
+  const projectRoot = options.projectRoot ?? findProjectRoot()
+  const env = options.env ?? process.env
+  const dryRun = options.dryRun ?? false
+
+  if (hasExplicitBuildIdOverride(env)) {
+    const override = readEnvBuildIdOverride(env)
+    return { id: override.id, bumped: false, source: override.source }
+  }
+
+  const baseline = readBaselineBuildId(projectRoot)
+  if (!baseline) {
+    throw new Error(
+      `${DEFAULT_BUILD_ID_FILE} missing — run wp setup or add a channel baseline (e.g. v0.0.1-dev)`,
+    )
+  }
+
+  const slug = resolveDevSlug(env, projectRoot)
+  if (!slug) {
+    throw new Error(
+      'CDN dev slug not configured — set PORTAL_CDN_DEV_SLUG, run wp setup, or configure git user.name',
+    )
+  }
+
+  const state = readModuleBuildIdState(projectRoot) ?? {}
+  const stateBaseline = state.baseline ? stripToBaseline(state.baseline) : baseline
+  const nextSeq =
+    state.slug === slug && stateBaseline === baseline && Number.isInteger(state.seq)
+      ? state.seq + 1
+      : 1
+
+  const id = formatBuildId(baseline, slug, nextSeq)
+  const nextState = {
+    slug,
+    seq: nextSeq,
+    baseline,
+    tier: options.tier,
+    updatedAt: new Date().toISOString(),
+  }
+  writeModuleBuildIdState(projectRoot, nextState, dryRun)
+
+  return { id, bumped: true, source: 'state', slug, seq: nextSeq, baseline }
+}
+
+let cached
+
+export function clearPortalBuildIdCache() {
+  cached = undefined
+}
+
+/** Cached build id for the current Node process (file + env read once). */
+export function portalBuildId() {
+  if (cached === undefined) {
+    cached = resolveModuleBuildId()
+  }
+  return cached
+}
+
+/** Inject resolved id into env for child processes (vite, etc.). */
+export function envWithPortalBuildId(baseEnv = process.env, projectRoot = findProjectRoot()) {
+  const buildId = resolveModuleBuildId(baseEnv, projectRoot)
+  return { ...baseEnv, PORTAL_BUILD_ID: buildId, MODULE_BUILD_ID: buildId }
+}

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

@@ -0,0 +1,132 @@
+import assert from 'node:assert/strict'
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, it } from 'node:test'
+
+import {
+  bumpModuleBuildId,
+  clearPortalBuildIdCache,
+  formatBuildId,
+  hasExplicitBuildIdOverride,
+  readBaselineBuildId,
+  resolveDevSlug,
+  resolveModuleBuildId,
+  resolveModuleBuildIdMeta,
+  sanitizeDevSlug,
+  stripToBaseline,
+  writeModuleBuildIdState,
+} from './portal-build-id.mjs'
+import { wphsPaths } from './wphs-paths.mjs'
+
+const roots = []
+
+function makeProject() {
+  const root = mkdtempSync(join(tmpdir(), 'wp-build-id-'))
+  roots.push(root)
+  mkdirSync(join(root, '.wphs', 'config'), { recursive: true })
+  mkdirSync(join(root, '.wphs', 'state'), { recursive: true })
+  writeFileSync(
+    join(root, 'woodscli.json'),
+    JSON.stringify({
+      configVersion: 1,
+      projectType: 'module-hybrid-cdn',
+      module: { name: 'test', uploadPath: 'x.module', outDir: 'dist' },
+      cdn: { mode: 'jsdelivr', buildIdFile: '.module-build-id', mirror: 'portal.cdn.json' },
+    }),
+  )
+  writeFileSync(join(root, '.module-build-id'), '# baseline\nv0.0.1-dev\n')
+  return root
+}
+
+afterEach(() => {
+  clearPortalBuildIdCache()
+  for (const root of roots.splice(0)) {
+    rmSync(root, { recursive: true, force: true })
+  }
+})
+
+describe('sanitizeDevSlug', () => {
+  it('normalizes names', () => {
+    assert.equal(sanitizeDevSlug('Manab Roy'), 'manab-roy')
+    assert.equal(sanitizeDevSlug('  JDoe  '), 'jdoe')
+  })
+})
+
+describe('stripToBaseline', () => {
+  it('strips numeric legacy suffix', () => {
+    assert.equal(stripToBaseline('v0.0.1-dev.10'), 'v0.0.1-dev')
+  })
+  it('strips per-dev suffix', () => {
+    assert.equal(stripToBaseline('v0.0.1-dev.manab.3'), 'v0.0.1-dev')
+  })
+})
+
+describe('formatBuildId', () => {
+  it('formats slugged ids', () => {
+    assert.equal(formatBuildId('v0.0.1-dev', 'manab', 1), 'v0.0.1-dev.manab.1')
+  })
+})
+
+describe('resolveModuleBuildId', () => {
+  it('prefers env override', () => {
+    const root = makeProject()
+    const id = resolveModuleBuildId({ PORTAL_BUILD_ID: 'ci-abc' }, root)
+    assert.equal(id, 'ci-abc')
+    assert.equal(hasExplicitBuildIdOverride({ PORTAL_BUILD_ID: 'ci-abc' }), true)
+  })
+
+  it('uses state when present', () => {
+    const root = makeProject()
+    writeFileSync(join(root, '.wphs', 'config', 'developer.json'), JSON.stringify({ slug: 'manab' }))
+    writeModuleBuildIdState(root, { slug: 'manab', seq: 4, baseline: 'v0.0.1-dev' })
+    const meta = resolveModuleBuildIdMeta({}, root)
+    assert.equal(meta.id, 'v0.0.1-dev.manab.4')
+    assert.equal(meta.source, 'state')
+  })
+
+  it('falls back to baseline without state', () => {
+    const root = makeProject()
+    writeFileSync(join(root, '.wphs', 'config', 'developer.json'), JSON.stringify({ slug: 'manab' }))
+    assert.equal(readBaselineBuildId(root), 'v0.0.1-dev')
+    const meta = resolveModuleBuildIdMeta({}, root)
+    assert.equal(meta.id, 'v0.0.1-dev')
+    assert.equal(meta.source, 'baseline')
+  })
+})
+
+describe('bumpModuleBuildId', () => {
+  it('increments seq for same slug and baseline', () => {
+    const root = makeProject()
+    writeFileSync(join(root, '.wphs', 'config', 'developer.json'), JSON.stringify({ slug: 'manab' }))
+
+    const first = bumpModuleBuildId({ projectRoot: root, tier: 'dev' })
+    assert.equal(first.id, 'v0.0.1-dev.manab.1')
+    assert.equal(first.bumped, true)
+
+    const second = bumpModuleBuildId({ projectRoot: root, tier: 'dev' })
+    assert.equal(second.id, 'v0.0.1-dev.manab.2')
+
+    const statePath = join(wphsPaths(root).stateDir, 'module-build-id.json')
+    const state = JSON.parse(readFileSync(statePath, 'utf8'))
+    assert.equal(state.seq, 2)
+  })
+
+  it('respects env override without bumping', () => {
+    const root = makeProject()
+    const result = bumpModuleBuildId({
+      projectRoot: root,
+      env: { PORTAL_BUILD_ID: 'release-1' },
+    })
+    assert.equal(result.id, 'release-1')
+    assert.equal(result.bumped, false)
+  })
+})
+
+describe('resolveDevSlug', () => {
+  it('reads slug from developer.json', () => {
+    const root = makeProject()
+    writeFileSync(join(root, '.wphs', 'config', 'developer.json'), JSON.stringify({ slug: 'alice' }))
+    assert.equal(resolveDevSlug({}, root), 'alice')
+  })
+})

package/scripts/publish-cdn-github.mjs

@@ -32,13 +32,14 @@ import {
   isQuietBuild,
   portalSubprocessStdio,
 } from './portal-subprocess-stdio.mjs'
-import { resolvePortalBuildId } from './resolve-portal-build-id.mjs'
+import { resolveModuleBuildIdMeta } from './portal-build-id.mjs'
 
 const root = findProjectRoot()
 
 const args = new Set(process.argv.slice(2))
 const dryRun = args.has('--dry-run')
 const skipJsDelivrCheck = args.has('--skip-jsdelivr-check')
+const forceTag = args.has('--force-tag')
 
 function log(msg) {
   if (isQuietBuild()) {
@@ -106,7 +107,7 @@ function copyCdnArtifacts(sourceDir, targetDir) {
 
 function writeCdnReadme(repoRoot, buildId, config) {
   const readmePath = join(repoRoot, 'README.md')
-  const base = jsDelivrBaseUrl(config.github, buildId, config.cdnPathInRepo)
+  const base = jsDelivrBaseUrl(config.github, config.cdnPathInRepo, config.defaultBranch)
   const body = `# woodsportal-client-frontend-cdn
 
 Public CDN assets for the WoodsPortal HubSpot module (**Strategy B — Hybrid CDN**).
@@ -116,10 +117,10 @@ Public CDN assets for the WoodsPortal HubSpot module (**Strategy B — Hybrid CD
 | | |
 |---|---|
 | Latest tag | \`${buildId}\` |
-| jsDelivr base | ${base} |
+| jsDelivr base | ${base} (@${config.defaultBranch}) |
 | Source repo | [digitalwoods.io-woodsportal-client-frontend](https://github.com/Digital-Woods/digitalwoods.io-woodsportal-client-frontend) (private) |
 
-## jsDelivr URLs (tag \`${buildId}\`)
+## jsDelivr URLs (build \`${buildId}\` on \`${config.defaultBranch}\`)
 
 - \`${base}/vendor.${buildId}.js\`
 - \`${base}/app.${buildId}.js\`
@@ -130,8 +131,29 @@ Published at ${new Date().toISOString()}.
   writeFileSync(readmePath, body, 'utf8')
 }
 
-async function checkJsDelivr(config, buildId, vendorFile, appFile, appCssFile) {
-  const base = jsDelivrBaseUrl(config.github, buildId, config.cdnPathInRepo)
+async function assertGithubRepoPublic(github) {
+  const res = await fetch(`https://api.github.com/repos/${github}`, {
+    headers: { Accept: 'application/vnd.github+json' },
+  })
+  if (res.status === 404) {
+    fail(
+      `GitHub repo ${github} not found or not visible — jsDelivr requires a public CDN mirror repo.`,
+    )
+  }
+  if (!res.ok) {
+    fail(`Could not verify GitHub repo ${github} (HTTP ${res.status}).`)
+  }
+  const data = await res.json()
+  if (data.private === true) {
+    fail(
+      `CDN mirror ${github} is private — jsDelivr only serves public GitHub repos. ` +
+        'Make the repo public (Settings → Danger zone → Change visibility) or use a public mirror.',
+    )
+  }
+}
+
+async function checkJsDelivr(config, vendorFile, appFile, appCssFile) {
+  const base = jsDelivrBaseUrl(config.github, config.cdnPathInRepo, config.defaultBranch)
   for (const file of [appCssFile, vendorFile, appFile]) {
     const url = `${base}/${file}`
     log(`Checking jsDelivr (may take a minute on first publish): ${url}`)
@@ -149,7 +171,8 @@ async function checkJsDelivr(config, buildId, vendorFile, appFile, appCssFile) {
 }
 
 const config = loadPortalCdnConfig()
-const buildId = resolvePortalBuildId()
+const buildMeta = resolveModuleBuildIdMeta()
+const buildId = buildMeta.id
 const sourceCdn = resolve(root, 'dist/cdn')
 const token = process.env.PORTAL_CDN_PUBLISH_TOKEN ?? process.env.GITHUB_TOKEN
 
@@ -174,12 +197,12 @@ if (!appCssFile) {
 
 if (!vendorFile.includes(buildId) || !appFile.includes(buildId) || !appCssFile.includes(buildId)) {
   fail(
-    `Build id mismatch: .portal-build-id is "${buildId}" but chunks are ${vendorFile}, ${appFile}, ${appCssFile}. ` +
-      'Update .portal-build-id and rebuild with `yarn build:cdn:prod` or `yarn build:cdn:dev`.',
+    `Build id mismatch: module build id is "${buildId}" but chunks are ${vendorFile}, ${appFile}, ${appCssFile}. ` +
+      'Run `wp deploy` (auto-bumps id) or rebuild CDN after aligning `.module-build-id`.',
   )
 }
 
-const jsdelivrBase = jsDelivrBaseUrl(config.github, buildId, config.cdnPathInRepo)
+const jsdelivrBase = jsDelivrBaseUrl(config.github, config.cdnPathInRepo, config.defaultBranch)
 
 const appSource = readFileSync(join(sourceCdn, appFile), 'utf8')
 const bakedApis = [
@@ -196,12 +219,20 @@ if (bakedApis.length === 1 && bakedApis[0] === 'https://api.woodsportal.com') {
 
 log('Configuration')
 log(`  config file:     ${config.configPath ?? '(defaults)'}`)
-log(`  build id / tag:  ${buildId}`)
+log(`  build id / tag:  ${buildId} (source: ${buildMeta.source})`)
+if (buildMeta.slug) {
+  log(`  dev slug:        ${buildMeta.slug}${buildMeta.seq ? ` · seq ${buildMeta.seq}` : ''}`)
+}
+if (config.usingLocalMirror) {
+  log('  CDN mirror:      portal.cdn.local.json override')
+}
 log(`  GitHub (jsDelivr): ${config.github}`)
 log(`  git remote:      ${config.gitRemote}`)
 log(`  target path:     ${config.cdnPathInRepo}/`)
 log(`  jsDelivr base:   ${jsdelivrBase}`)
 
+await assertGithubRepoPublic(config.github)
+
 if (dryRun) {
   log('Dry run — would copy:')
   for (const f of readdirSync(sourceCdn)) {
@@ -257,6 +288,14 @@ if (!status) {
   )
 }
 
+const remoteTag = runCapture('git', ['ls-remote', 'origin', `refs/tags/${buildId}`], { cwd: workDir })
+if (remoteTag && !forceTag) {
+  fail(
+    `Tag ${buildId} already exists on remote CDN repo — run wp deploy to auto-bump the module build id, ` +
+      'or pass --force-tag only if you intend to overwrite that release.',
+  )
+}
+
 const existingTag = spawnSync('git', ['rev-parse', buildId], {
   cwd: workDir,
   stdio: 'pipe',
@@ -264,13 +303,19 @@ const existingTag = spawnSync('git', ['rev-parse', buildId], {
 })
 
 if (existingTag.status === 0) {
-  log(`Tag ${buildId} already exists locally — deleting and recreating on current commit.`)
+  if (!forceTag) {
+    fail(
+      `Tag ${buildId} already exists locally — run wp deploy to bump .module-build-id or pass --force-tag.`,
+    )
+  }
+  log(`Tag ${buildId} already exists locally — deleting and recreating on current commit (--force-tag).`)
   run('git', ['tag', '-d', buildId], { cwd: workDir })
 }
 
 run('git', ['tag', '-a', buildId, '-m', `WoodsPortal CDN ${buildId}`], { cwd: workDir })
 run('git', ['push', '-u', 'origin', branch], { cwd: workDir })
-run('git', ['push', 'origin', `refs/tags/${buildId}`, '--force'], { cwd: workDir })
+const tagPushArgs = ['push', 'origin', `refs/tags/${buildId}`, ...(forceTag ? ['--force'] : [])]
+run('git', tagPushArgs, { cwd: workDir })
 
 log('')
 log('Published successfully.')
@@ -280,12 +325,12 @@ log(`  jsDelivr app:    ${jsdelivrBase}/${appFile}`)
 log(`  jsDelivr css:    ${jsdelivrBase}/${appCssFile}`)
 log('')
 log('Next steps:')
-log('  1. Wait ~5–15 minutes for jsDelivr to index the new tag (first publish can be slower).')
+log(`  1. jsDelivr serves from @${config.defaultBranch} (versioned chunk filenames include ${buildId}).`)
 log('  2. yarn build:hubspot:dev   # dev API + jsDelivr URLs')
 log('     yarn build:hubspot:prod   # prod API')
 log('  3. yarn upload:hubspot')
 log('  Or: yarn deploy:dev  |  yarn deploy:prod')
 
 if (!skipJsDelivrCheck) {
-  await checkJsDelivr(config, buildId, vendorFile, appFile, appCssFile)
+  await checkJsDelivr(config, vendorFile, appFile, appCssFile)
 }

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

@@ -28,5 +28,6 @@ export function resolveCdnBaseUrl(env = process.env) {
   }
 
   const cdnPath = config.cdnPathInRepo.replace(/^\//, '').replace(/\/$/, '')
-  return `https://cdn.jsdelivr.net/gh/${config.github}@${buildId}/${cdnPath}`
+  const branch = config.defaultBranch.replace(/^@/, '').trim() || 'main'
+  return `https://cdn.jsdelivr.net/gh/${config.github}@${branch}/${cdnPath}`
 }

package/scripts/resolve-module-build-id-meta.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { clearPortalBuildIdCache, resolveModuleBuildIdMeta } from './portal-build-id.mjs'
+import { findProjectRoot } from './project-root.mjs'
+
+clearPortalBuildIdCache()
+const meta = resolveModuleBuildIdMeta(process.env, findProjectRoot())
+process.stdout.write(`${JSON.stringify(meta)}\n`)