From bcbcbd12f2e2da819926a58564455d6ee95b99e7 Mon Sep 17 00:00:00 2001
From: Kevin Brown <kevin@webstackbuilders.com>
Date: Tue, 24 Mar 2026 00:53:23 +0300
Subject: [PATCH 1/3] Fix Sentry release number

---
 .github/workflows/deployment-preview.yml      |  2 +
 .github/workflows/deployment-production.yml   |  2 +
 astro.config.ts                               | 11 ++-
 .../Pwa/PrefetchOfflinePage/index.astro       | 46 ++++++++++++-
 .../scripts/errors/__tests__/handler.spec.ts  |  8 +++
 src/components/scripts/errors/handler.ts      |  4 ++
 src/integrations/PackageRelease/index.ts      | 68 ++++++++++++++++---
 7 files changed, 126 insertions(+), 15 deletions(-)

diff --git a/.github/workflows/deployment-preview.yml b/.github/workflows/deployment-preview.yml
index 3d03a850c..397a11329 100644
--- a/.github/workflows/deployment-preview.yml
+++ b/.github/workflows/deployment-preview.yml
@@ -26,6 +26,7 @@ jobs:
       PUBLIC_GOOGLE_MAPS_API_KEY: ${{ vars.PUBLIC_GOOGLE_MAPS_API_KEY }}
       PUBLIC_GOOGLE_MAP_ID: ${{ vars.PUBLIC_GOOGLE_MAP_ID }}
       PUBLIC_SENTRY_DSN: ${{ vars.PUBLIC_SENTRY_DSN }}
+      SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
       PUBLIC_UPSTASH_SEARCH_REST_URL: ${{ vars.PUBLIC_UPSTASH_SEARCH_REST_URL }}
       PUBLIC_UPSTASH_SEARCH_READONLY_TOKEN: ${{ vars.PUBLIC_UPSTASH_SEARCH_READONLY_TOKEN }}
       VERCEL_ORG_ID: ${{ vars.VERCEL_ORG_ID }}
@@ -69,6 +70,7 @@ jobs:
       - name: Vercel build (preview)
         env:
           VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
+          SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
         run: vercel build --token=${VERCEL_TOKEN}
 
       - name: Deploy to Vercel (preview)
diff --git a/.github/workflows/deployment-production.yml b/.github/workflows/deployment-production.yml
index d9e787ac5..c6de0b8f9 100644
--- a/.github/workflows/deployment-production.yml
+++ b/.github/workflows/deployment-production.yml
@@ -23,6 +23,7 @@ jobs:
       PUBLIC_GOOGLE_MAPS_API_KEY: ${{ vars.PUBLIC_GOOGLE_MAPS_API_KEY }}
       PUBLIC_GOOGLE_MAP_ID: ${{ vars.PUBLIC_GOOGLE_MAP_ID }}
       PUBLIC_SENTRY_DSN: ${{ vars.PUBLIC_SENTRY_DSN }}
+      SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
       PUBLIC_UPSTASH_SEARCH_REST_URL: ${{ vars.PUBLIC_UPSTASH_SEARCH_REST_URL }}
       PUBLIC_UPSTASH_SEARCH_READONLY_TOKEN: ${{ vars.PUBLIC_UPSTASH_SEARCH_READONLY_TOKEN }}
       VERCEL_ORG_ID: ${{ vars.VERCEL_ORG_ID }}
@@ -63,6 +64,7 @@ jobs:
         env:
           VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
           NODE_ENV: production
+          SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
         run: vercel build --prod --token=${VERCEL_TOKEN}
 
       ##
diff --git a/astro.config.ts b/astro.config.ts
index d32bb9fd1..e5cf7d74f 100644
--- a/astro.config.ts
+++ b/astro.config.ts
@@ -33,6 +33,7 @@ import { callToActionValidator } from './src/integrations/CtaValidator'
 import { faviconGenerator } from './src/integrations/FaviconGenerator'
 import { packageRelease } from './src/integrations/PackageRelease'
 import { privacyPolicyVersion } from './src/integrations/PrivacyPolicyVersion'
+import { getPackageRelease, packageRelease } from './src/integrations/PackageRelease'
 import { testimonialsLengthWarning } from './src/integrations/TestimonialsLengthWarning'
 import { fixContentAssetPropagation } from './src/lib/plugins/fixContentAssetPropagation'
 import { pwaDevAssetServer } from './src/lib/plugins/pwaDevAssetServer'
@@ -41,6 +42,9 @@ import { createSerializeFunction, pagesJsonWriter } from './src/integrations/sit
 // Ensure Vite's HMR websocket connects through the same exposed dev server port used by Astro.
 const devServerPort = Number(process.env['DEV_SERVER_PORT'] ?? 4321)
 const viteLogger = createLogger(undefined, { allowClearScreen: false })
+const sentryAuthToken = process.env['SENTRY_AUTH_TOKEN']
+const sentryRelease = getPackageRelease()
+const shouldEnableSentryIntegration = Boolean(sentryAuthToken)
 
 const shouldSuppressViteWarning = (message: string): boolean => {
   return (
@@ -82,11 +86,12 @@ const standardIntegrations = [
   privacyPolicyVersion(),
   /** Warn when testimonial bodies are too short/too long (helps keep carousel cards consistent) */
   testimonialsLengthWarning({ min: 300, max: 400 }),
-  /** Only include Sentry integration in Vercel environments */
-  ...(isVercel() ? [sentry({
+  /** Enable Sentry build integration when CI provides upload credentials. */
+  ...(shouldEnableSentryIntegration ? [sentry({
     project: "webstack-builders-corporate-website",
     org: "webstack-builders",
-    authToken: getSentryAuthToken(),
+    authToken: sentryAuthToken,
+    release: sentryRelease,
   })] : []),
   sitemap({
     serialize: createSerializeFunction({
diff --git a/src/components/Pwa/PrefetchOfflinePage/index.astro b/src/components/Pwa/PrefetchOfflinePage/index.astro
index 16245f543..08ee08013 100644
--- a/src/components/Pwa/PrefetchOfflinePage/index.astro
+++ b/src/components/Pwa/PrefetchOfflinePage/index.astro
@@ -7,6 +7,25 @@
 <script>
   import { handleScriptError } from '@components/scripts/errors/handler'
 
+  const BODY_PREVIEW_LENGTH = 240
+
+  const getHeaderValue = (response: Response, headerName: string) =>
+    response.headers.get(headerName) ?? 'missing'
+
+  const getBodyPreview = async (response: Response) => {
+    try {
+      const bodyText = await response.text()
+
+      if (!bodyText) {
+        return 'empty'
+      }
+
+      return bodyText.slice(0, BODY_PREVIEW_LENGTH).replace(/\s+/g, ' ')
+    } catch {
+      return 'unavailable'
+    }
+  }
+
   const prefetch = (url: string) => {
     try {
       fetch(url, {
@@ -15,14 +34,35 @@
           'x-prefetch-source': 'PrefetchOfflinePage',
         },
       })
-        .then(response => {
+        .then(async response => {
           if (response.ok) {
             return response
           }
 
-          throw new Error(
-            `Prefetch failed for ${url}: ${response.status} ${response.statusText || 'Unknown Status'} (content-type: ${response.headers.get('content-type') ?? 'unknown'})`
+          const contentType = getHeaderValue(response, 'content-type')
+          const bodyPreview = await getBodyPreview(response)
+          const statusText = response.statusText || 'Unknown Status'
+          const error = new Error(
+            `Prefetch failed for ${url}: ${response.status} ${statusText} (content-type: ${contentType})`
           )
+
+          handleScriptError(error, {
+            scriptName: 'BaseLayout',
+            operation: `prefetch ${url}`,
+            extra: {
+              prefetchUrl: url,
+              requestStatus: response.status,
+              statusText,
+              contentType,
+              bodyPreview,
+              xPrefetchSource: 'PrefetchOfflinePage',
+              xVercelId: getHeaderValue(response, 'x-vercel-id'),
+              xMatchedPath: getHeaderValue(response, 'x-matched-path'),
+              cacheControl: getHeaderValue(response, 'cache-control'),
+            },
+          })
+
+          return response
         })
         .catch(error => {
           handleScriptError(error, { scriptName: 'BaseLayout', operation: `prefetch ${url}` })
diff --git a/src/components/scripts/errors/__tests__/handler.spec.ts b/src/components/scripts/errors/__tests__/handler.spec.ts
index 97566fda8..677321729 100644
--- a/src/components/scripts/errors/__tests__/handler.spec.ts
+++ b/src/components/scripts/errors/__tests__/handler.spec.ts
@@ -30,6 +30,10 @@ describe('handleScriptError', () => {
     const result = handleScriptError(new TestError('boom'), {
       scriptName: 'AppBootstrap',
       operation: 'init',
+      extra: {
+        requestStatus: 500,
+        contentType: 'text/html',
+      },
     })
 
     expect(result).toBeInstanceOf(ClientScriptError)
@@ -38,6 +42,10 @@ describe('handleScriptError', () => {
         scriptName: 'AppBootstrap',
         operation: 'init',
       },
+      extra: {
+        requestStatus: 500,
+        contentType: 'text/html',
+      },
     })
     expect(consoleErrorSpy).not.toHaveBeenCalled()
   })
diff --git a/src/components/scripts/errors/handler.ts b/src/components/scripts/errors/handler.ts
index b1f859f08..d6f767240 100644
--- a/src/components/scripts/errors/handler.ts
+++ b/src/components/scripts/errors/handler.ts
@@ -2,9 +2,12 @@ import { captureException } from '@sentry/browser'
 import { ClientScriptError } from './ClientScriptError'
 import { isProd } from '@components/scripts/utils/environmentClient'
 
+type ScriptErrorExtraValue = string | number | boolean | null
+
 export interface ScriptErrorContext {
   scriptName: string
   operation?: string
+  extra?: Record<string, ScriptErrorExtraValue>
 }
 
 /**
@@ -35,6 +38,7 @@ export function handleScriptError(error: unknown, context: ScriptErrorContext):
         scriptName: context.scriptName,
         ...(context.operation && { operation: context.operation }),
       },
+      ...(context.extra && { extra: context.extra }),
     })
   } else {
     // Log it for debugging
diff --git a/src/integrations/PackageRelease/index.ts b/src/integrations/PackageRelease/index.ts
index 5f1cbee05..de51952a7 100644
--- a/src/integrations/PackageRelease/index.ts
+++ b/src/integrations/PackageRelease/index.ts
@@ -1,17 +1,16 @@
 /**
  * Package Release Integration
  *
- * Automatically injects the package name and version at build time from package.json.
- * This provides a release identifier for tracking regressions between numbered releases
- * in monitoring services like Sentry.
+ * Automatically injects a build-time release identifier for monitoring systems like Sentry.
  *
  * The release is injected as PACKAGE_RELEASE_VERSION environment variable in the format
- * "name@version" and is available throughout the app as import.meta.env.PACKAGE_RELEASE_VERSION
+ * "name@commitSha" when CI metadata is available, with a local fallback to "name@version".
+ * It is available throughout the app as import.meta.env.PACKAGE_RELEASE_VERSION.
  *
  * Fallback order:
- * 1. Manual env var (PACKAGE_RELEASE_VERSION in .env)
+ * 1. Explicit release env / CI commit SHA
  * 2. package.json name@version
- * 3. "unknown@0.0.0" (if package.json cannot be read)
+ * 3. BuildError if package.json cannot be read
  */
 
 import { readFileSync } from 'node:fs'
@@ -24,16 +23,67 @@ interface PackageJson {
   version?: string
 }
 
+function readPackageJson(): PackageJson {
+  const packageJsonPath = resolve(process.cwd(), 'package.json')
+  const packageJsonContent = readFileSync(packageJsonPath, 'utf-8')
+
+  return JSON.parse(packageJsonContent) as PackageJson
+}
+
+function getPackageName(): string {
+  try {
+    const packageJsonPath = resolve(process.cwd(), 'package.json')
+    const packageJson = readPackageJson()
+    const name = packageJson.name
+
+    if (!name) {
+      throw new BuildError('package.json is missing required field. name: missing', {
+        phase: 'config-setup',
+        filePath: packageJsonPath,
+      })
+    }
+
+    return name
+  } catch (error) {
+    if (error instanceof BuildError) {
+      throw error
+    }
+
+    const packageJsonPath = resolve(process.cwd(), 'package.json')
+    throw new BuildError(
+      `Could not read package.json for package name: ${error instanceof Error ? error.message : String(error)}`,
+      { phase: 'config-setup', filePath: packageJsonPath, cause: error }
+    )
+  }
+}
+
+function getBuildRelease(): string | undefined {
+  const releaseCandidate = process.env['PACKAGE_RELEASE_VERSION'] ||
+    process.env['GITHUB_SHA'] ||
+    process.env['VERCEL_GIT_COMMIT_SHA'] ||
+    process.env['PUBLIC_VERCEL_GIT_COMMIT_SHA']
+
+  if (!releaseCandidate) {
+    return undefined
+  }
+
+  return `${getPackageName()}@${releaseCandidate}`
+}
+
 /**
  * Get package release from package.json
  * @returns Release string in format "name@version"
  * @throws {BuildError} If package.json cannot be read or parsed
  */
-function getPackageRelease(): string {
+export function getPackageRelease(): string {
+  const buildRelease = getBuildRelease()
+  if (buildRelease) {
+    return buildRelease
+  }
+
   try {
     const packageJsonPath = resolve(process.cwd(), 'package.json')
-    const packageJsonContent = readFileSync(packageJsonPath, 'utf-8')
-    const packageJson = JSON.parse(packageJsonContent) as PackageJson
+    const packageJson = readPackageJson()
 
     const name = packageJson.name
     const version = packageJson.version

From e2c5a2eb1dcabfe205bd3368971a86d2be56c3e7 Mon Sep 17 00:00:00 2001
From: Kevin Brown <kevin@webstackbuilders.com>
Date: Tue, 24 Mar 2026 01:10:28 +0300
Subject: [PATCH 2/3] Fix lint and test errors

---
 astro.config.ts                          |  9 +++------
 src/integrations/PackageRelease/index.ts | 10 +++++-----
 src/layouts/BaseLayout.astro             |  2 +-
 3 files changed, 9 insertions(+), 12 deletions(-)

diff --git a/astro.config.ts b/astro.config.ts
index e5cf7d74f..e30a187fd 100644
--- a/astro.config.ts
+++ b/astro.config.ts
@@ -21,17 +21,14 @@ import { createLogger, type LogOptions, type PluginOption } from 'vite'
  */
 import {
   environmentalVariablesConfig,
-  getSentryAuthToken,
   getSiteUrl,
   isE2eTest,
-  isVercel,
   markdownConfig,
   pwaConfig,
   vercelConfig,
 } from './src/lib/config'
 import { callToActionValidator } from './src/integrations/CtaValidator'
 import { faviconGenerator } from './src/integrations/FaviconGenerator'
-import { packageRelease } from './src/integrations/PackageRelease'
 import { privacyPolicyVersion } from './src/integrations/PrivacyPolicyVersion'
 import { getPackageRelease, packageRelease } from './src/integrations/PackageRelease'
 import { testimonialsLengthWarning } from './src/integrations/TestimonialsLengthWarning'
@@ -87,9 +84,9 @@ const standardIntegrations = [
   /** Warn when testimonial bodies are too short/too long (helps keep carousel cards consistent) */
   testimonialsLengthWarning({ min: 300, max: 400 }),
   /** Enable Sentry build integration when CI provides upload credentials. */
-  ...(shouldEnableSentryIntegration ? [sentry({
-    project: "webstack-builders-corporate-website",
-    org: "webstack-builders",
+  ...(shouldEnableSentryIntegration && sentryAuthToken ? [sentry({
+    project: 'webstack-builders-corporate-website',
+    org: 'webstack-builders',
     authToken: sentryAuthToken,
     release: sentryRelease,
   })] : []),
diff --git a/src/integrations/PackageRelease/index.ts b/src/integrations/PackageRelease/index.ts
index de51952a7..ed5eb0494 100644
--- a/src/integrations/PackageRelease/index.ts
+++ b/src/integrations/PackageRelease/index.ts
@@ -8,7 +8,7 @@
  * It is available throughout the app as import.meta.env.PACKAGE_RELEASE_VERSION.
  *
  * Fallback order:
- * 1. Explicit release env / CI commit SHA
+ * 1. CI/Vercel commit SHA
  * 2. package.json name@version
  * 3. BuildError if package.json cannot be read
  */
@@ -16,6 +16,7 @@
 import { readFileSync } from 'node:fs'
 import { resolve } from 'node:path'
 import type { AstroIntegration } from 'astro'
+import { getOptionalEnv } from '../../lib/config/environmentServer'
 import { BuildError } from '../../lib/errors/BuildError'
 
 interface PackageJson {
@@ -58,10 +59,9 @@ function getPackageName(): string {
 }
 
 function getBuildRelease(): string | undefined {
-  const releaseCandidate = process.env['PACKAGE_RELEASE_VERSION'] ||
-    process.env['GITHUB_SHA'] ||
-    process.env['VERCEL_GIT_COMMIT_SHA'] ||
-    process.env['PUBLIC_VERCEL_GIT_COMMIT_SHA']
+  const releaseCandidate = getOptionalEnv('GITHUB_SHA') ||
+    getOptionalEnv('VERCEL_GIT_COMMIT_SHA') ||
+    getOptionalEnv('PUBLIC_VERCEL_GIT_COMMIT_SHA')
 
   if (!releaseCandidate) {
     return undefined
diff --git a/src/layouts/BaseLayout.astro b/src/layouts/BaseLayout.astro
index 8e2d0e6fa..45556a687 100644
--- a/src/layouts/BaseLayout.astro
+++ b/src/layouts/BaseLayout.astro
@@ -70,7 +70,7 @@ const {
 } = Astro.props
 
 const requestUrl = Astro.url?.href
-const requestHeaders = Astro.request?.headers
+const requestHeaders = Astro.isPrerendered ? undefined : Astro.request.headers
 
 applyRenderSentryContext({
   contextName: 'pageRender',

From 0e062e990316e5e545052eeb5ef5cc6f6760ce80 Mon Sep 17 00:00:00 2001
From: Kevin Brown <kevin@webstackbuilders.com>
Date: Tue, 24 Mar 2026 01:47:10 +0300
Subject: [PATCH 3/3] Fix test error and on SHA release test

---
 src/integrations/PackageRelease/index.ts | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/src/integrations/PackageRelease/index.ts b/src/integrations/PackageRelease/index.ts
index ed5eb0494..5be5d2e15 100644
--- a/src/integrations/PackageRelease/index.ts
+++ b/src/integrations/PackageRelease/index.ts
@@ -16,7 +16,7 @@
 import { readFileSync } from 'node:fs'
 import { resolve } from 'node:path'
 import type { AstroIntegration } from 'astro'
-import { getOptionalEnv } from '../../lib/config/environmentServer'
+import { getOptionalEnv, isTest } from '../../lib/config/environmentServer'
 import { BuildError } from '../../lib/errors/BuildError'
 
 interface PackageJson {
@@ -59,6 +59,10 @@ function getPackageName(): string {
 }
 
 function getBuildRelease(): string | undefined {
+  if (isTest()) {
+    return undefined
+  }
+
   const releaseCandidate = getOptionalEnv('GITHUB_SHA') ||
     getOptionalEnv('VERCEL_GIT_COMMIT_SHA') ||
     getOptionalEnv('PUBLIC_VERCEL_GIT_COMMIT_SHA')