@salesforce/storefront-next-dev 0.4.1 → 1.0.0-alpha.0

package/dist/index.js

@@ -1,40 +1,19 @@
-import path, { basename, extname, join, resolve } from "node:path";
+import path from "node:path";
 import fs from "fs-extra";
 import chalk from "chalk";
-import path$1, { dirname, join as join$1, relative, resolve as resolve$1 } from "path";
+import path$1, { dirname, join, relative, resolve } from "path";
 import { fileURLToPath, pathToFileURL } from "url";
 import { parse } from "@babel/parser";
 import { booleanLiteral, identifier, importDeclaration, importSpecifier, isArrayPattern, isClassDeclaration, isExportSpecifier, isFunctionDeclaration, isIdentifier, isJSXAttribute, isJSXElement, isJSXFragment, isJSXIdentifier, isMemberExpression, isObjectPattern, isObjectProperty, isRestElement, isStringLiteral, isVariableDeclaration, jsxAttribute, jsxClosingElement, jsxClosingFragment, jsxElement, jsxExpressionContainer, jsxFragment, jsxIdentifier, jsxOpeningElement, jsxOpeningFragment, jsxText, stringLiteral } from "@babel/types";
 import { generate } from "@babel/generator";
 import traverseModule from "@babel/traverse";
-import fs$1, { existsSync, readFileSync, writeFileSync } from "fs";
+import { existsSync, readFileSync, writeFileSync } from "fs";
 import { glob } from "glob";
 import { Node, Project, ts } from "ts-morph";
-import fs$2, { existsSync as existsSync$1, readFileSync as readFileSync$1, unlinkSync } from "node:fs";
+import fs$1 from "node:fs";
 import { deadCodeElimination, findReferencedIdentifiers } from "babel-dead-code-elimination";
 import httpProxy from "http-proxy";
 import { brotliDecompressSync, gunzipSync, inflateSync } from "zlib";
-import express from "express";
-import { createRequestHandler } from "@react-router/express";
-import { pathToFileURL as pathToFileURL$1 } from "node:url";
-import { createProxyMiddleware } from "http-proxy-middleware";
-import compression from "compression";
-import zlib from "node:zlib";
-import morgan from "morgan";
-import { minimatch } from "minimatch";
-import { SpanStatusCode, context, trace } from "@opentelemetry/api";
-import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
-import { ConsoleSpanExporter, SimpleSpanProcessor } from "@opentelemetry/sdk-trace-base";
-import { ExportResultCode, hrTimeToTimeStamp } from "@opentelemetry/core";
-import { Resource } from "@opentelemetry/resources";
-import { ATTR_SERVICE_NAME } from "@opentelemetry/semantic-conventions";
-import { registerInstrumentations } from "@opentelemetry/instrumentation";
-import { UndiciInstrumentation } from "@opentelemetry/instrumentation-undici";
-import { access, mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
-import { execSync } from "node:child_process";
-import { tmpdir } from "node:os";
-import { randomUUID } from "node:crypto";
-import { npmRunPathEnv } from "npm-run-path";
 
 //#region src/utils/logger.ts
 const LEVEL_PRIORITY = {
@@ -159,49 +138,6 @@ function fixReactRouterManifestUrlsPlugin() {
 function toPosixPath(filePath) {
 	return filePath.replace(/\\/g, "/");
 }
-/**
-* Get the Commerce Cloud API URL from a short code
-*/
-function getCommerceCloudApiUrl(shortCode, proxyHost) {
-	return proxyHost || `https://${shortCode}.api.commercecloud.salesforce.com`;
-}
-/**
-* Get the configurable base path for the application.
-* Reads from MRT_ENV_BASE_PATH environment variable.
-*
-* The base path is used for CDN routing to the correct MRT environment.
-* It is prepended to all URLs: page routes, /mobify/bundle/ assets, and /mobify/proxy/api.
-*
-* Validation rules:
-* - Must be a single path segment starting with '/'
-* - Max 63 characters after the leading slash
-* - Only URL-safe characters allowed
-* - Returns empty string if not set
-*
-* @returns The sanitized base path (e.g., '/site-a' or '')
-*
-* @example
-* // No base path configured
-* getBasePath() // → ''
-*
-* // With base path '/storefront'
-* getBasePath() // → '/storefront'
-*
-* // Automatically sanitizes
-* // MRT_ENV_BASE_PATH='storefront/' → '/storefront'
-*/
-function getBasePath() {
-	const basePath = process.env.MRT_ENV_BASE_PATH?.trim();
-	if (!basePath) return "";
-	if (!/^\/[a-zA-Z0-9_.+$~"'@:-]{1,63}$/.test(basePath)) throw new Error(`Invalid base path: "${basePath}". Base path must be a single segment starting with '/' (e.g., '/site-a'), contain only URL-safe characters, and be at most 63 characters after the leading slash.`);
-	return basePath;
-}
-/**
-* Get the bundle path for static assets
-*/
-function getBundlePath(bundleId) {
-	return `${getBasePath()}/mobify/bundle/${bundleId}/client/`;
-}
 
 //#endregion
 //#region src/plugins/readableChunkFileNames.ts
@@ -364,8 +300,11 @@ const managedRuntimeBundlePlugin = () => {
 					defaultHandler(level, log);
 				} } },
 				environments: { ssr: { resolve: { noExternal: true } } },
-				experimental: { renderBuiltUrl(filename, { type }) {
-					if (mode !== "preview" && (type === "asset" || type === "public")) return { runtime: `(typeof window !== 'undefined' ? window._BUNDLE_PATH : ((process.env.MRT_ENV_BASE_PATH??'')+'/mobify/bundle/'+(process.env.BUNDLE_ID??'local')+'/client/')) + ${JSON.stringify(filename)}` };
+				experimental: { renderBuiltUrl(filename, { type, hostType }) {
+					if (mode !== "preview" && (type === "asset" || type === "public")) {
+						if (hostType === "css") return { relative: true };
+						return { runtime: `(typeof window !== 'undefined' ? window._BUNDLE_PATH : ((process.env.MRT_ENV_BASE_PATH??'')+'/mobify/bundle/'+(process.env.BUNDLE_ID??'local')+'/client/')) + ${JSON.stringify(filename)}` };
+					}
 				} }
 			};
 		},
@@ -580,13 +519,14 @@ function transformTargets(code, targetRegistry, contextProviders) {
 function buildTargetRegistry(rootDir, options = {}) {
 	const componentRegistry = {};
 	const contextProviders = [];
+	const actionHookRegistry = {};
 	const extensionDirPath = path$1.join(rootDir, "extensions");
 	const extensionDirs = fs.readdirSync(extensionDirPath, { withFileTypes: true });
 	const getNamespaceAndComponentName = (dir, filePath) => {
 		const namespace = dir.name.split("-").map((word) => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase()).join("");
 		return {
 			namespace,
-			componentName: `${namespace}_${(filePath.split("/").pop()?.replace(".tsx", ""))?.split("-").map((word) => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase()).join("")}`
+			componentName: `${namespace}_${(filePath.split("/").pop()?.replace(/\.(tsx|ts|jsx|js)$/, ""))?.split(/[-.]/).map((word) => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase()).join("")}`
 		};
 	};
 	const TARGET_CONFIG_FILENAME = "target-config.json";
@@ -596,6 +536,7 @@ function buildTargetRegistry(rootDir, options = {}) {
 			const extensionConfig = fs.readJsonSync(configPath);
 			if (options.isProduction && extensionConfig.devOnly === true) continue;
 			if (extensionConfig && extensionConfig.components) for (const component of extensionConfig.components) {
+				if (component.enabled === false) continue;
 				const { targetId, path: componentPath, order = 0 } = component;
 				if (targetId && componentPath) {
 					if (!componentRegistry[targetId]) componentRegistry[targetId] = [];
@@ -621,13 +562,47 @@ function buildTargetRegistry(rootDir, options = {}) {
 					});
 				}
 			}
+			if (extensionConfig && extensionConfig.actionHooks) for (const hook of extensionConfig.actionHooks) {
+				const { hookId, handler, order = 0 } = hook;
+				if (hookId && handler) {
+					if (!actionHookRegistry[hookId]) actionHookRegistry[hookId] = [];
+					const { namespace, componentName: handlerName } = getNamespaceAndComponentName(dir, handler);
+					actionHookRegistry[hookId].push({
+						hookId,
+						path: handler,
+						order,
+						namespace,
+						handlerName
+					});
+				}
+			}
 		}
 	}
 	for (const targetId in componentRegistry) componentRegistry[targetId].sort((a, b) => a.order - b.order);
 	contextProviders.sort((a, b) => a.order - b.order);
+	for (const hookId in actionHookRegistry) actionHookRegistry[hookId].sort((a, b) => a.order - b.order);
+	for (const targetId in componentRegistry) {
+		const entries = componentRegistry[targetId];
+		const seen = /* @__PURE__ */ new Map();
+		for (const entry of entries) {
+			const existing = seen.get(entry.order);
+			if (existing) logger.warn(`[storefront-next] UITarget "${targetId}": components "${existing}" and "${entry.componentName}" have the same order (${entry.order}). Execution order between them is non-deterministic. Assign distinct order values.`);
+			seen.set(entry.order, entry.componentName);
+		}
+	}
+	for (const hookId in actionHookRegistry) {
+		const entries = actionHookRegistry[hookId];
+		const seen = /* @__PURE__ */ new Map();
+		for (const entry of entries) {
+			const existing = seen.get(entry.order);
+			if (existing) logger.warn(`[storefront-next] Action hook "${hookId}": handlers "${existing}" and "${entry.handlerName}" have the same order (${entry.order}). Execution order between them is non-deterministic. Assign distinct order values.`);
+			seen.set(entry.order, entry.handlerName);
+		}
+	}
 	return {
 		componentRegistry,
-		contextProviders
+		contextProviders,
+		actionHookRegistry
 	};
 }
 
@@ -665,6 +640,96 @@ function transformTargetPlaceholderPlugin() {
 	};
 }
 
+//#endregion
+//#region src/plugins/actionHooks.ts
+const ACTION_HOOKS_VIRTUAL_ID = "virtual:action-hooks";
+const ACTION_HOOKS_RESOLVED_ID = `\0${ACTION_HOOKS_VIRTUAL_ID}`;
+/**
+* Generate the virtual module code for the action hook registry.
+*
+* The generated module exports a `hookRegistry` map of hookId → handler[],
+* and a `runHook` function that executes registered handlers in order.
+*/
+function generateActionHooksModule(actionHookRegistry) {
+	const imports = [];
+	const registryEntries = [];
+	for (const [hookId, handlers] of Object.entries(actionHookRegistry)) {
+		const handlerNames = [];
+		for (const handler of handlers) {
+			const importPath = `@/${handler.path.replace(/\.(ts|tsx|js|jsx)$/, "")}`;
+			imports.push(`import ${handler.handlerName} from '${importPath}';`);
+			handlerNames.push(handler.handlerName);
+		}
+		registryEntries.push(`  '${hookId}': [${handlerNames.join(", ")}]`);
+	}
+	return `${imports.join("\n")}
+
+const HANDLER_TIMEOUT_MS = 5000;
+
+const hookRegistry = {
+${registryEntries.join(",\n")}
+};
+
+function withTimeout(promise, ms, label) {
+  return Promise.race([
+    promise,
+    new Promise((_, reject) =>
+      setTimeout(() => reject(new Error(\`Action hook handler timed out after \${ms}ms: \${label}\`)), ms)
+    ),
+  ]);
+}
+
+export async function runHook(hookId, context, options = {}) {
+  const handlers = hookRegistry[hookId];
+  if (!handlers || handlers.length === 0) {
+    return context;
+  }
+  let currentContext = context;
+  for (const handler of handlers) {
+    try {
+      const result = await withTimeout(handler(currentContext), HANDLER_TIMEOUT_MS, hookId);
+      currentContext = result ?? currentContext;
+    } catch (error) {
+      if (error && error.name === 'ActionHookError') {
+        throw error;
+      }
+      if (options.blocking) {
+        throw error;
+      }
+      console.error(\`[action-hooks] handler for "\${hookId}" failed, skipping to next handler\`, error);
+    }
+  }
+  return currentContext;
+}
+`;
+}
+/**
+* Vite plugin that resolves `virtual:action-hooks` to a generated module
+* mapping hookIds to their registered handlers.
+*/
+function actionHooksPlugin() {
+	let actionHookRegistry;
+	let sourceDir;
+	let isProduction = false;
+	return {
+		name: "storefront-next:action-hooks",
+		enforce: "pre",
+		configResolved(config) {
+			sourceDir = config.resolve.alias.find((alias) => alias.find === "@")?.replacement || path$1.resolve(__dirname, "./src");
+			isProduction = config.mode === "production";
+		},
+		buildStart() {
+			actionHookRegistry = buildTargetRegistry(sourceDir, { isProduction }).actionHookRegistry;
+		},
+		resolveId(id) {
+			if (id === ACTION_HOOKS_VIRTUAL_ID) return ACTION_HOOKS_RESOLVED_ID;
+		},
+		load(id) {
+			if (id === ACTION_HOOKS_RESOLVED_ID) return generateActionHooksModule(actionHookRegistry);
+		}
+	};
+}
+
 //#endregion
 //#region src/plugins/watchConfigFiles.ts
 const watchConfigFilesPlugin = () => {
@@ -694,7 +759,7 @@ const watchConfigFilesPlugin = () => {
 
 //#endregion
 //#region src/plugins/staticRegistry.ts
-const DEFAULT_COMPONENT_GROUP$1 = "storefrontnext_base";
+const DEFAULT_COMPONENT_GROUP = "storefrontnext_base";
 /**
 * Extracts component ID and group from @Component decorator using ts-morph AST parsing
 */
@@ -709,7 +774,7 @@ function extractComponentInfo(decorator) {
 	else if (Node.isNoSubstitutionTemplateLiteral(firstArg)) baseComponentId = firstArg.getText().slice(1, -1);
 	else if (Node.isTemplateExpression(firstArg)) throw new Error(`@Component id must be a simple string literal or backtick string without interpolation. Found: ${firstArg.getText()}`);
 	else return null;
-	let group = DEFAULT_COMPONENT_GROUP$1;
+	let group = DEFAULT_COMPONENT_GROUP;
 	if (args.length > 1) {
 		const secondArg = args[1];
 		if (Node.isObjectLiteralExpression(secondArg)) {
@@ -768,7 +833,7 @@ async function scanComponents(project, projectRoot, componentPath, registryPath)
 	});
 	logger.debug(`🔍 Scanning ${componentFiles.length} files in ${componentPath}...`);
 	const components = [];
-	const registryDir = dirname(resolve$1(projectRoot, registryPath));
+	const registryDir = dirname(resolve(projectRoot, registryPath));
 	for (const filePath of componentFiles) try {
 		const content = readFileSync(filePath, "utf-8");
 		const sourceFile = project.createSourceFile(filePath, content, { overwrite: true });
@@ -925,7 +990,7 @@ const staticRegistryPlugin = (config = {}) => {
 		} }), projectRoot, componentPath, registryPath);
 		logger.debug(`📦 Found ${components.length} components with @Component decorators`);
 		const generatedCode = generateRegistryCode(components, registryIdentifier);
-		const registryFilePath = resolve$1(projectRoot, registryPath);
+		const registryFilePath = resolve(projectRoot, registryPath);
 		const changed = updateRegistryFile(registryFilePath, generatedCode);
 		logger.debug("✅ Static registry generation complete!");
 		return {
@@ -974,7 +1039,7 @@ const staticRegistryPlugin = (config = {}) => {
 * Load the engagement config from config.server.ts
 */
 async function loadEngagementConfig(projectRoot, configPath) {
-	const absoluteConfigPath = resolve$1(projectRoot, configPath);
+	const absoluteConfigPath = resolve(projectRoot, configPath);
 	try {
 		const config = (await import(pathToFileURL(absoluteConfigPath).href)).default;
 		logger.debug(`📄 Loaded config from ${configPath}`);
@@ -1001,7 +1066,7 @@ async function scanForInstrumentedEvents(projectRoot, scanPaths) {
 	const sendViewPagePattern = /sendViewPageEvent\s*\(/g;
 	const createEventPattern = /createEvent\s*\(\s*['"]([^'"]+)['"]/g;
 	for (const scanPath of scanPaths) {
-		const files = await glob(join$1(resolve$1(projectRoot, scanPath), "**/*.{ts,tsx}"), { ignore: [
+		const files = await glob(join(resolve(projectRoot, scanPath), "**/*.{ts,tsx}"), { ignore: [
 			"**/*.test.ts",
 			"**/*.test.tsx",
 			"**/*.spec.ts",
@@ -1153,17 +1218,17 @@ const buildMiddlewareRegistryPlugin = () => {
 		configResolved(config) {
 			resolvedConfig = config;
 			const rr = config.__reactRouterPluginContext?.reactRouterConfig ?? {};
-			buildDirectory = rr.buildDirectory ?? resolve$1(config.root, "build");
+			buildDirectory = rr.buildDirectory ?? resolve(config.root, "build");
 			appDirectory = rr.appDirectory ?? "src";
 		},
 		buildApp: {
 			order: "post",
 			handler: async () => {
 				const projectRoot = resolvedConfig.root;
-				const middlewareRegistryPath = resolve$1(projectRoot, appDirectory, SERVER_OUT_SUBDIR, MIDDLEWARE_REGISTRY_SOURCE_FILE);
+				const middlewareRegistryPath = resolve(projectRoot, appDirectory, SERVER_OUT_SUBDIR, MIDDLEWARE_REGISTRY_SOURCE_FILE);
 				if (!existsSync(middlewareRegistryPath)) return;
 				const { build } = await import("tsdown");
-				const serverOutDir = resolve$1(projectRoot, buildDirectory, SERVER_OUT_SUBDIR);
+				const serverOutDir = resolve(projectRoot, buildDirectory, SERVER_OUT_SUBDIR);
 				await build({
 					cwd: projectRoot,
 					entry: { [MIDDLEWARE_REGISTRY_SOURCE_FILE.replace(/\.ts$/, "")]: middlewareRegistryPath },
@@ -1213,10 +1278,10 @@ const PASSTHROUGH_QUERY = "?platform-passthrough";
 * Finds a user-ejected entry file in the app directory.
 * Returns the absolute path if found, undefined otherwise.
 */
-function findUserEntry(appDirectory, basename$1) {
+function findUserEntry(appDirectory, basename) {
 	for (const ext of ENTRY_EXTENSIONS) {
-		const filePath = path.resolve(appDirectory, basename$1 + ext);
-		if (fs$2.existsSync(filePath)) return filePath;
+		const filePath = path.resolve(appDirectory, basename + ext);
+		if (fs$1.existsSync(filePath)) return filePath;
 	}
 }
 /**
@@ -1316,8 +1381,8 @@ function platformEntryPlugin() {
 			const watcher = server.watcher;
 			const checkEntryChange = (filePath) => {
 				const relative$1 = path.relative(appDir, filePath);
-				const basename$1 = path.basename(relative$1, path.extname(relative$1));
-				if (path.dirname(relative$1) !== "." || basename$1 !== "entry.server" && basename$1 !== "entry.client") return;
+				const basename = path.basename(relative$1, path.extname(relative$1));
+				if (path.dirname(relative$1) !== "." || basename !== "entry.server" && basename !== "entry.client") return;
 				const ext = path.extname(relative$1);
 				if (!ENTRY_EXTENSIONS.includes(ext)) return;
 				const nowHasServer = findUserEntry(appDir, "entry.server") !== void 0;
@@ -1715,6 +1780,56 @@ function i18nPlugin(config) {
 	};
 }
 
+//#endregion
+//#region src/plugins/baseConfig.ts
+/**
+* Vite plugin contributing the baseline Vite config required by the
+* Storefront Next framework. These settings are uniform across every
+* customer project and are not intended to be customized.
+*
+* Additional framework-level Vite defaults should be added here rather
+* than in the template's vite.config.ts or in a new single-purpose plugin.
+*
+* Current defaults:
+* - `resolve.dedupe`: prevents duplicate React / React Router copies on the
+*   client. Duplicate React instances cause hooks to throw "Invalid hook call".
+* - `optimizeDeps.include`: forces Vite's dep optimizer to pre-bundle
+*   `react-router` and its `/internal/react-server-client` entry so the
+*   React Router dev plugin resolves a single shared instance on the client.
+* - `ssr.noExternal`: forces the SDK through Vite's SSR transform pipeline
+*   in dev. The SDK exports module-level singletons (router contexts, etc.)
+*   whose object identity is load-bearing — they're used as `Map` keys, so
+*   reads and writes must reference the same object. In dev SSR, Vite can
+*   externalize a package for some import sites (loaded by Node's native
+*   ESM resolver) while transforming it for others (loaded by Vite's SSR
+*   transform pipeline), producing two distinct module records for the
+*   same file on disk. When that happens, the singletons are constructed
+*   twice and the keys no longer match — context lookups silently return
+*   the default value. `noExternal` collapses both paths into Vite's
+*   transform cache so there is exactly one module record. Production
+*   builds inline the SDK into the SSR bundle and are unaffected. We
+*   don't blanket-`noExternal` every dependency because most third-party
+*   packages are identity-agnostic (two copies work fine) and externalizing
+*   keeps dev startup fast — only packages exporting identity-sensitive
+*   singletons need this treatment.
+*
+* @returns {Plugin} A Vite plugin contributing the framework's base config.
+*/
+const baseConfigPlugin = () => ({
+	name: "storefront-next:base-config",
+	config() {
+		return {
+			resolve: { dedupe: [
+				"react",
+				"react-dom",
+				"react-router"
+			] },
+			optimizeDeps: { include: ["react-router", "react-router/internal/react-server-client"] },
+			ssr: { noExternal: ["@salesforce/storefront-next-runtime"] }
+		};
+	}
+});
+
 //#endregion
 //#region src/storefront-next-targets.ts
 /**
@@ -1746,6 +1861,7 @@ function storefrontNextTargets(config = {}) {
 		failOnMissing: false
 	} } = config;
 	const plugins = [
+		baseConfigPlugin(),
 		...process.env.SCAPI_PROXY_HOST ? [workspacePlugin()] : [],
 		i18nPlugin(),
 		managedRuntimeBundlePlugin(),
@@ -1753,6 +1869,7 @@ function storefrontNextTargets(config = {}) {
 		patchReactRouterPlugin(),
 		platformEntryPlugin(),
 		transformTargetPlaceholderPlugin(),
+		actionHooksPlugin(),
 		watchConfigFilesPlugin(),
 		buildMiddlewareRegistryPlugin(),
 		ssrSourcemapFixPlugin()
@@ -1959,6 +2076,55 @@ function escapeRegExp(str) {
 	return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 /**
+* Rewrite an SFCC Location header so the user stays on the proxy origin AND so
+* any query params from the original request survive an SFCC redirect.
+*
+* SFCC frequently redirects bare paths like `/cart` to a canonical SFRA URL
+* (`/s/{siteId}/{locale}/Cart-Show`) without echoing the user's query string in
+* the Location header. Without this merge step, params like `?foo=bar` set by
+* the storefront — including ones the destination page expects — get dropped on
+* the cross-app hop.
+*
+* Resolution rules:
+* - Off-origin Location → `{ kind: 'off-origin' }` so the caller leaves the
+*   header unchanged and the browser navigates as SFCC intended.
+* - Same-origin Location → rewrite the origin to the proxy host, then merge the
+*   original request's query params into the redirect target's URL. Multi-value
+*   keys (e.g. SFRA's `pmid=...&pmid=...`) are preserved on both sides. The
+*   redirect target wins on collision so SFCC can intentionally override a key.
+* - Malformed Location → `{ kind: 'malformed' }` so the caller can warn.
+*
+* @param locationHeader - Raw Location header value from the SFCC response.
+* @param requestUrl - Original request URL on the proxy (e.g. `/cart?foo=bar`).
+* @param targetOrigin - SFCC origin used as the base for relative Location values.
+* @param proxyOrigin - Proxy origin (e.g. `http://localhost:5173`) the caller wants the user to stay on.
+*/
+function rewriteLocationForProxy({ locationHeader, requestUrl, targetOrigin, proxyOrigin }) {
+	let locationUrl;
+	try {
+		locationUrl = new URL(locationHeader, targetOrigin);
+	} catch {
+		return { kind: "malformed" };
+	}
+	if (locationUrl.origin !== targetOrigin) return { kind: "off-origin" };
+	let requestQuery;
+	try {
+		requestQuery = new URL(requestUrl, proxyOrigin).searchParams;
+	} catch {
+		requestQuery = new URLSearchParams();
+	}
+	const targetKeys = new Set(locationUrl.searchParams.keys());
+	for (const [key, value] of requestQuery) if (!targetKeys.has(key)) locationUrl.searchParams.append(key, value);
+	return {
+		kind: "rewritten",
+		url: `${proxyOrigin}${locationUrl.pathname}${locationUrl.search}${locationUrl.hash}`
+	};
+}
+/** Cap loud values in debug logs so a long URL doesn't drown the dev console. */
+function truncateForLog(value, max = 120) {
+	return value.length > max ? `${value.slice(0, max)}…` : value;
+}
+/**
 * Vite plugin for hybrid proxying between Storefront Next and legacy SFRA.
 *
 * Uses http-proxy to silently forward non-matching requests to SFCC without visible
@@ -1980,10 +2146,12 @@ function hybridProxyPlugin(options) {
 		logger.warn("Hybrid proxy: no target origin configured (SFCC_ORIGIN required)");
 		return { name: "hybrid-proxy" };
 	}
+	if (!options.defaultSiteId) throw new Error("Hybrid proxy is enabled but no default site ID was provided.\n\nSet PUBLIC__app__defaultSiteId in your .env file:\n  PUBLIC__app__defaultSiteId=RefArchGlobal\n\nSee docs/README-HYBRID-PROXY.md for the full reference.");
 	logger.info(`Hybrid proxy enabled → ${options.targetOrigin}`);
 	logger.debug(`Hybrid proxy routing rules: ${options.routingRules.slice(0, 100)}...`);
 	const locale = options.locale || "default";
-	logger.debug(`Hybrid proxy path transformation: / → /s/${options.siteId}, /path → /s/${options.siteId}/${locale}/path`);
+	const defaultSiteId = options.defaultSiteId;
+	logger.debug(`Hybrid proxy path transformation: / → /s/${defaultSiteId}, /path → /s/${defaultSiteId}/${locale}/path`);
 	const targetOriginPattern = new RegExp(escapeRegExp(options.targetOrigin), "g");
 	const proxy = httpProxy.createProxyServer({
 		changeOrigin: true,
@@ -2000,8 +2168,8 @@ function hybridProxyPlugin(options) {
 			* This would simply proxy to SFCC hostname (eg.: https://zzrf-001.dx.commercecloud.salesforce.com/s/{siteId}/{locale}/) which is not a valid storefront URL.
 			* We need to rewrite the path to /s/{siteId} so that it can be proxied to the correct SFCC URL.
 			*/
-			if (pathname === "/") proxyReq.path = `/s/${options.siteId}${url.search}`;
-			else proxyReq.path = `/s/${options.siteId}/${locale}${pathname}${url.search}`;
+			if (pathname === "/") proxyReq.path = `/s/${defaultSiteId}${url.search}`;
+			else proxyReq.path = `/s/${defaultSiteId}/${locale}${pathname}${url.search}`;
 			logger.debug(`Hybrid proxy path rewrite: ${originalPath} → ${proxyReq.path}`);
 		}
 	});
@@ -2009,7 +2177,7 @@ function hybridProxyPlugin(options) {
 		const clientRes = res;
 		const locationHeader = proxyRes.headers.location;
 		const statusCode = proxyRes.statusCode || 200;
-		if (statusCode >= 300 && statusCode < 400 && typeof locationHeader === "string" && /\/404\b/.test(locationHeader)) {
+		if (typeof locationHeader === "string" && /\/404\b/.test(locationHeader) && (statusCode >= 300 && statusCode < 400 || statusCode === 200)) {
 			logger.warn(`⚠️  SFCC returned a redirect to 404 for ${req.url}. This usually means your HYBRID_ROUTING_RULES are missing a pattern for this path. Stripping Set-Cookie headers to prevent session cookie corruption. Fix: add a matching pattern to HYBRID_ROUTING_RULES (e.g., "^${req.url?.split("?")[0]}.*")`);
 			delete proxyRes.headers["set-cookie"];
 		}
@@ -2019,15 +2187,28 @@ function hybridProxyPlugin(options) {
 			logger.debug(`Hybrid proxy cookie rewrite: ${cookie.slice(0, 50)}... → ${rewritten.slice(0, 50)}...`);
 			return rewritten;
 		});
-		if (locationHeader && typeof locationHeader === "string") try {
-			const locationUrl = new URL(locationHeader, options.targetOrigin);
-			if (locationUrl.origin === options.targetOrigin) {
-				const localUrl = `http://${req.headers.host}${locationUrl.pathname}${locationUrl.search}${locationUrl.hash}`;
-				proxyRes.headers.location = localUrl;
-				logger.debug(`Hybrid proxy location rewrite: ${locationHeader} → ${localUrl}`);
-			}
-		} catch {
-			logger.warn(`Hybrid proxy: invalid Location header: ${locationHeader}`);
+		if (locationHeader && typeof locationHeader === "string") {
+			const proxyOrigin = `http://${req.headers.host}`;
+			const result = rewriteLocationForProxy({
+				locationHeader,
+				requestUrl: req.url ?? "",
+				targetOrigin: options.targetOrigin,
+				proxyOrigin
+			});
+			if (result.kind === "rewritten") {
+				proxyRes.headers.location = result.url;
+				logger.debug(`Hybrid proxy location rewrite: ${truncateForLog(locationHeader)} → ${truncateForLog(result.url)}`);
+				if (statusCode === 200) {
+					proxyRes.resume();
+					const redirectHeaders = { location: result.url };
+					const setCookie = proxyRes.headers["set-cookie"];
+					if (setCookie) redirectHeaders["set-cookie"] = setCookie;
+					clientRes.writeHead(302, redirectHeaders);
+					clientRes.end();
+					logger.debug(`Hybrid proxy normalized 200+Location → 302 for ${req.url} (Location: ${truncateForLog(result.url)})`);
+					return;
+				}
+			} else if (result.kind === "malformed") logger.warn(`Hybrid proxy: invalid Location header: ${truncateForLog(locationHeader)}`);
 		}
 		const contentType = (proxyRes.headers["content-type"] || "").split(";")[0].trim();
 		if (!(contentType === "text/html" || contentType === "application/json")) {
@@ -2212,1481 +2393,7 @@ function shouldRouteToNext(pathname, routingRules) {
 	}
 	return testPatterns(pathname, patterns);
 }
-/**
-* Clears the regex cache. Useful for testing or when routing rules change.
-*
-* @example
-* ```typescript
-* clearCache();
-* // All cached regex patterns are removed
-* ```
-*/
-function clearCache() {
-	regexCache.clear();
-}
-
-//#endregion
-//#region src/server/ts-import.ts
-/**
-* Parse TypeScript paths from tsconfig.json and convert to jiti alias format.
-*
-* @param tsconfigPath - Path to tsconfig.json
-* @param projectDirectory - Project root directory for resolving relative paths
-* @returns Record of alias mappings for jiti
-*
-* @example
-* // tsconfig.json: { "compilerOptions": { "paths": { "@/*": ["./src/*"] } } }
-* // Returns: { "@/": "/absolute/path/to/src/" }
-*/
-function parseTsconfigPaths(tsconfigPath, projectDirectory) {
-	const alias = {};
-	if (!existsSync$1(tsconfigPath)) return alias;
-	try {
-		const tsconfigContent = readFileSync$1(tsconfigPath, "utf-8");
-		const tsconfig = JSON.parse(tsconfigContent);
-		const paths = tsconfig.compilerOptions?.paths;
-		const baseUrl = tsconfig.compilerOptions?.baseUrl || ".";
-		if (paths) {
-			for (const [key, values] of Object.entries(paths)) if (values && values.length > 0) {
-				const aliasKey = key.replace(/\/\*$/, "/");
-				alias[aliasKey] = resolve(projectDirectory, baseUrl, values[0].replace(/\/\*$/, "/").replace(/^\.\//, ""));
-			}
-		}
-	} catch {}
-	const sortedAlias = {};
-	Object.keys(alias).sort((a, b) => b.length - a.length).forEach((key) => {
-		sortedAlias[key] = alias[key];
-	});
-	return sortedAlias;
-}
-/**
-* Import a TypeScript file using jiti with proper path alias resolution.
-* This is a cross-platform alternative to tsx that works on Windows.
-*
-* @param filePath - Absolute path to the TypeScript file to import
-* @param options - Import options including project directory
-* @returns The imported module
-*/
-async function importTypescript(filePath, options) {
-	const { projectDirectory, tsconfigPath = resolve(projectDirectory, "tsconfig.json") } = options;
-	const { createJiti } = await import("jiti");
-	const alias = parseTsconfigPaths(tsconfigPath, projectDirectory);
-	return createJiti(import.meta.url, {
-		fsCache: false,
-		interopDefault: true,
-		alias
-	}).import(filePath);
-}
-
-//#endregion
-//#region src/server/config.ts
-/**
-* This is a temporary function before we move the config implementation from
-* template-retail-rsc-app to the SDK.
-*
-* @ TODO: Remove this function after we move the config implementation from
-* template-retail-rsc-app to the SDK.
-*
-*/
-function loadConfigFromEnv() {
-	const shortCode = process.env.PUBLIC__app__commerce__api__shortCode;
-	const organizationId = process.env.PUBLIC__app__commerce__api__organizationId;
-	const clientId = process.env.PUBLIC__app__commerce__api__clientId;
-	const proxy = process.env.PUBLIC__app__commerce__api__proxy || "/mobify/proxy/api";
-	const proxyHost = process.env.SCAPI_PROXY_HOST;
-	if (!shortCode && !proxyHost) throw new Error("Missing PUBLIC__app__commerce__api__shortCode environment variable.\nPlease set it in your .env file or environment.");
-	if (!organizationId) throw new Error("Missing PUBLIC__app__commerce__api__organizationId environment variable.\nPlease set it in your .env file or environment.");
-	if (!clientId) throw new Error("Missing PUBLIC__app__commerce__api__clientId environment variable.\nPlease set it in your .env file or environment.");
-	return { commerce: { api: {
-		shortCode: shortCode || "",
-		organizationId,
-		clientId,
-		proxy,
-		proxyHost
-	} } };
-}
-/**
-* Load storefront-next project configuration from config.server.ts.
-* Requires projectDirectory to be provided.
-*
-* @param projectDirectory - Project directory to load config.server.ts from
-* @throws Error if config.server.ts is not found or invalid
-*/
-async function loadProjectConfig(projectDirectory) {
-	const configPath = resolve(projectDirectory, "config.server.ts");
-	const tsconfigPath = resolve(projectDirectory, "tsconfig.json");
-	if (!existsSync$1(configPath)) throw new Error(`config.server.ts not found at ${configPath}.\nPlease ensure config.server.ts exists in your project root.`);
-	const config = (await importTypescript(configPath, {
-		projectDirectory,
-		tsconfigPath
-	})).default;
-	if (!config?.app?.commerce?.api) throw new Error("Invalid config.server.ts: missing app.commerce.api configuration.\nPlease ensure your config.server.ts has the commerce API configuration.");
-	const api = config.app.commerce.api;
-	const proxyHost = process.env.SCAPI_PROXY_HOST;
-	if (!api.shortCode && !proxyHost) throw new Error("Missing shortCode in config.server.ts commerce.api configuration");
-	if (!api.organizationId) throw new Error("Missing organizationId in config.server.ts commerce.api configuration");
-	if (!api.clientId) throw new Error("Missing clientId in config.server.ts commerce.api configuration");
-	return { commerce: { api: {
-		shortCode: api.shortCode || "",
-		organizationId: api.organizationId,
-		clientId: api.clientId,
-		proxy: api.proxy || "/mobify/proxy/api",
-		proxyHost
-	} } };
-}
-
-//#endregion
-//#region src/config.ts
-const SFNEXT_BASE_CARTRIDGE_NAME = "app_storefrontnext_base";
-const SFNEXT_BASE_CARTRIDGE_OUTPUT_DIR = `${SFNEXT_BASE_CARTRIDGE_NAME}/cartridge/experience`;
-
-//#endregion
-//#region src/server/middleware/proxy.ts
-/**
-* Create proxy middleware for Commerce Cloud API
-* Proxies requests from /mobify/proxy/api to the Commerce Cloud API
-*/
-function createCommerceProxyMiddleware(config) {
-	return createProxyMiddleware({
-		target: getCommerceCloudApiUrl(config.commerce.api.shortCode, config.commerce.api.proxyHost),
-		changeOrigin: true,
-		secure: !config.commerce.api.proxyHost
-	});
-}
-
-//#endregion
-//#region src/server/middleware/static.ts
-/**
-* Create static file serving middleware for client assets
-* Serves files from build/client at /mobify/bundle/{BUNDLE_ID}/client/
-*/
-function createStaticMiddleware(bundleId, projectDirectory) {
-	const bundlePath = getBundlePath(bundleId);
-	const clientBuildDir = path$1.join(projectDirectory, "build", "client");
-	logger.info(`Serving static assets from ${clientBuildDir} at ${bundlePath}`);
-	return express.static(clientBuildDir, { setHeaders: (res) => {
-		res.setHeader("Cache-Control", "public, max-age=31536000, immutable");
-		res.setHeader("x-local-static-cache-control", "1");
-	} });
-}
-
-//#endregion
-//#region src/server/middleware/compression.ts
-/**
-* Parse and validate COMPRESSION_LEVEL environment variable
-* @returns Valid compression level (0-9) or default compression level
-*/
-function getCompressionLevel() {
-	const raw = process.env.COMPRESSION_LEVEL;
-	const DEFAULT = zlib.constants.Z_DEFAULT_COMPRESSION;
-	if (raw == null || raw.trim() === "") return DEFAULT;
-	const level = Number(raw);
-	if (!(Number.isInteger(level) && level >= 0 && level <= 9)) {
-		logger.warn(`[compression] Invalid COMPRESSION_LEVEL="${raw}". Using default (${DEFAULT}).`);
-		return DEFAULT;
-	}
-	return level;
-}
-/**
-* Create compression middleware for gzip/brotli compression
-* Used in preview mode to optimize response sizes
-*/
-function createCompressionMiddleware() {
-	return compression({
-		filter: (req, res) => {
-			if (req.headers["x-no-compression"]) return false;
-			return compression.filter(req, res);
-		},
-		level: getCompressionLevel()
-	});
-}
-
-//#endregion
-//#region src/server/middleware/logging.ts
-/**
-* Patterns for URLs to skip logging (static assets and Vite internals)
-*/
-const SKIP_PATTERNS = [
-	"/@vite/**",
-	"/@id/**",
-	"/@fs/**",
-	"/@react-router/**",
-	"/src/**",
-	"/node_modules/**",
-	"**/*.js",
-	"**/*.css",
-	"**/*.ts",
-	"**/*.tsx",
-	"**/*.js.map",
-	"**/*.css.map"
-];
-/**
-* Create request logging middleware
-* Used in dev and preview modes for request visibility
-*/
-function createLoggingMiddleware() {
-	morgan.token("status-colored", (req, res) => {
-		const status = res.statusCode;
-		let color = chalk.green;
-		if (status >= 500) color = chalk.red;
-		else if (status >= 400) color = chalk.yellow;
-		else if (status >= 300) color = chalk.cyan;
-		return color(String(status));
-	});
-	morgan.token("method-colored", (req) => {
-		const method = req.method;
-		const colors = {
-			GET: chalk.green,
-			POST: chalk.blue,
-			PUT: chalk.yellow,
-			DELETE: chalk.red,
-			PATCH: chalk.magenta
-		};
-		return (method && colors[method] || chalk.white)(method);
-	});
-	return morgan((tokens, req, res) => {
-		return [
-			tokens["method-colored"](req, res),
-			tokens.url(req, res),
-			"-",
-			tokens["status-colored"](req, res),
-			chalk.gray(`(${tokens["response-time"](req, res)}ms)`)
-		].join(" ");
-	}, { skip: (req) => {
-		return SKIP_PATTERNS.some((pattern) => minimatch(req.url, pattern, { dot: true }));
-	} });
-}
-
-//#endregion
-//#region src/server/middleware/host-header.ts
-/**
-* Normalizes the X-Forwarded-Host header to support React Router's CSRF validation features.
-*
-* NOTE: This middleware performs header manipulation as a temporary, internal
-* solution for MRT/Lambda environments. It may be updated or removed if React Router
-* introduces a first-class configuration for validating against forwarded headers.
-*
-* React Router v7.12+ uses the X-Forwarded-Host header (preferring it over Host)
-* to validate request origins for security. In Managed Runtime (MRT) with a vanity
-* domain, the eCDN automatically sets the X-Forwarded-Host to the vanity domain.
-* React Router handles cases where this header contains multiple comma-separated
-* values by prioritizing the first entry.
-*
-* This middleware ensures that X-Forwarded-Host is always present by falling back
-* to a configured public domain if the header is missing (e.g., local development).
-* By only modifying X-Forwarded-Host, we provide a consistent environment for
-* React Router's security checks without modifying the internal 'Host' header,
-* which is required for environment-specific routing logic (e.g., Hybrid Proxy).
-*
-* Priority order:
-* 1. X-Forwarded-Host: Automatically set by eCDN for vanity domains.
-* 2. EXTERNAL_DOMAIN_NAME: Fallback environment variable for the public domain
-*    used when no forwarded headers are present (e.g., local development).
-*/
-function createHostHeaderMiddleware() {
-	return (req, _res, next) => {
-		if (!req.get("x-forwarded-host") && process.env.EXTERNAL_DOMAIN_NAME) req.headers["x-forwarded-host"] = process.env.EXTERNAL_DOMAIN_NAME;
-		next();
-	};
-}
-
-//#endregion
-//#region src/server/utils.ts
-/**
-* Patch React Router build to rewrite asset URLs with the correct bundle path
-* This is needed because the build output uses /assets/ but we preview at /mobify/bundle/{BUNDLE_ID}/client/assets/
-*/
-function patchReactRouterBuild(build, bundleId) {
-	const bundlePath = getBundlePath(bundleId);
-	const basePath = getBasePath();
-	const patchedAssetsJson = JSON.stringify(build.assets).replace(/"\/assets\//g, `"${bundlePath}assets/`);
-	const newAssets = JSON.parse(patchedAssetsJson);
-	return Object.assign({}, build, {
-		publicPath: bundlePath,
-		assets: newAssets,
-		...basePath && { basename: basePath }
-	});
-}
-
-//#endregion
-//#region src/server/modes.ts
-/**
-* Default feature configuration for each server mode
-*/
-const ServerModeFeatureMap = {
-	development: {
-		enableProxy: true,
-		enableStaticServing: false,
-		enableCompression: false,
-		enableLogging: true,
-		enableAssetUrlPatching: false
-	},
-	preview: {
-		enableProxy: true,
-		enableStaticServing: true,
-		enableCompression: true,
-		enableLogging: true,
-		enableAssetUrlPatching: true
-	},
-	production: {
-		enableProxy: false,
-		enableStaticServing: false,
-		enableCompression: true,
-		enableLogging: true,
-		enableAssetUrlPatching: true
-	}
-};
-
-//#endregion
-//#region src/otel/mrt-console-span-exporter.ts
-var MrtConsoleSpanExporter = class extends ConsoleSpanExporter {
-	export(spans, resultCallback) {
-		for (const span of spans) try {
-			const ctx = span.spanContext();
-			const spanData = {
-				traceId: ctx.traceId,
-				parentId: span.parentSpanId,
-				name: span.name,
-				id: ctx.spanId,
-				kind: span.kind,
-				timestamp: hrTimeToTimeStamp(span.startTime),
-				duration: span.duration,
-				attributes: span.attributes,
-				status: span.status,
-				events: span.events,
-				links: span.links,
-				start_time: span.startTime,
-				end_time: span.endTime,
-				forwardTrace: process.env.SFNEXT_OTEL_ENABLED === "true"
-			};
-			console.info(JSON.stringify(spanData));
-		} catch {}
-		resultCallback({ code: ExportResultCode.SUCCESS });
-	}
-};
-
-//#endregion
-//#region src/otel/setup.ts
-const SERVICE_NAME = "storefront-next";
-/**
-* Initializes OpenTelemetry and returns a Tracer from the provider directly.
-*
-* Returns the tracer via `provider.getTracer()` instead of the global
-* `trace.getTracer()` API. In the Vite SSR module runner, the built
-* dist/entry/server.js and the externalized @opentelemetry/sdk-trace-node
-* resolve @opentelemetry/api to different module instances (different paths
-* through pnpm's strict node_modules). Each instance has its own
-* ProxyTracerProvider singleton, so `provider.register()` sets the delegate
-* on sdk-trace-node's API instance while our code's `trace.getTracer()`
-* reads from a separate API instance with no delegate — returning a tracer
-* backed by a bare BasicTracerProvider with NoopSpanProcessor.
-*
-* Getting the tracer directly from the provider bypasses the global registry
-* entirely, guaranteeing the tracer uses our configured span processors.
-*/
-let cachedTracer = null;
-const UNDICI_REGISTERED_KEY = Symbol.for("sfnext.otel.undici_registered");
-function initTelemetry() {
-	if (cachedTracer) return cachedTracer;
-	try {
-		const provider = new NodeTracerProvider({ resource: new Resource({ [ATTR_SERVICE_NAME]: SERVICE_NAME }) });
-		provider.addSpanProcessor(new SimpleSpanProcessor(new MrtConsoleSpanExporter()));
-		provider.register();
-		if (!globalThis[UNDICI_REGISTERED_KEY]) {
-			globalThis[UNDICI_REGISTERED_KEY] = true;
-			registerInstrumentations({
-				tracerProvider: provider,
-				instrumentations: [new UndiciInstrumentation({ requestHook(span, request) {
-					try {
-						const method = request.method.toUpperCase();
-						const url = `${request.origin}${request.path}`;
-						span.updateName(`${method} ${url}`);
-					} catch {}
-				} })]
-			});
-		}
-		cachedTracer = provider.getTracer(SERVICE_NAME);
-		return cachedTracer;
-	} catch (error) {
-		logger.error("[otel] Failed to initialize OpenTelemetry:", error);
-		return null;
-	}
-}
-
-//#endregion
-//#region src/otel/express/middleware.ts
-function createOtelExpressMiddleware() {
-	const maybeTracer = initTelemetry();
-	if (!maybeTracer) return (_req, _res, next) => next();
-	const tracer = maybeTracer;
-	return (req, res, next) => {
-		try {
-			const url = new URL(req.originalUrl || req.url, "http://localhost").pathname;
-			const method = req.method;
-			tracer.startActiveSpan(`[sfnext] server ${method} ${url}`, { attributes: {
-				"http.request.method": method,
-				"url.path": url
-			} }, (serverSpan) => {
-				try {
-					const spanContext = trace.getSpan(context.active())?.spanContext();
-					if (spanContext) {
-						const flags = spanContext.traceFlags.toString(16).padStart(2, "0");
-						const traceparent = `00-${spanContext.traceId}-${spanContext.spanId}-${flags}`;
-						res.setHeader("traceparent", traceparent);
-					}
-				} catch {}
-				const serverCtx = context.active();
-				const startTime = performance.now();
-				let streamingSpan = null;
-				let ttfbMs = 0;
-				let ended = false;
-				function recordTTFB() {
-					if (streamingSpan) return;
-					try {
-						ttfbMs = Math.round(performance.now() - startTime);
-						serverSpan.setAttribute("sfnext.ttfb_ms", ttfbMs);
-						streamingSpan = tracer.startSpan(`[sfnext] response streaming ${method} ${url}`, { attributes: {
-							"http.request.method": method,
-							"url.path": url,
-							"sfnext.ttfb_ms": ttfbMs
-						} }, serverCtx);
-					} catch {}
-				}
-				const origWriteHead = res.writeHead.bind(res);
-				res.writeHead = ((...args) => {
-					recordTTFB();
-					return origWriteHead(...args);
-				});
-				const origWrite = res.write.bind(res);
-				res.write = ((...args) => {
-					recordTTFB();
-					return origWrite(...args);
-				});
-				function endSpans() {
-					if (ended) return;
-					ended = true;
-					try {
-						const totalMs = Math.round(performance.now() - startTime);
-						const statusCode = res.statusCode;
-						if (streamingSpan) {
-							streamingSpan.setAttribute("http.streaming_duration_ms", totalMs - ttfbMs);
-							streamingSpan.setAttribute("http.response.status_code", statusCode);
-							if (statusCode >= 500) streamingSpan.setStatus({ code: SpanStatusCode.ERROR });
-							streamingSpan.end();
-						}
-						serverSpan.setAttribute("http.response.status_code", statusCode);
-						serverSpan.setAttribute("http.total_duration_ms", totalMs);
-						if (statusCode >= 500) serverSpan.setStatus({ code: SpanStatusCode.ERROR });
-						serverSpan.end();
-					} catch {}
-				}
-				res.once("close", endSpans);
-				res.once("finish", endSpans);
-				next();
-			});
-		} catch {
-			next();
-		}
-	};
-}
-
-//#endregion
-//#region src/server/handlers/health-check.ts
-const DEFAULT_HEALTH_DESCRIPTION = "storefront-next-dev server health";
-const PACKAGE_JSON_NAME = "package.json";
-const RUNTIME_PACKAGE_NAME = "@salesforce/storefront-next-runtime";
-const DEV_PACKAGE_NAME = "@salesforce/storefront-next-dev";
-const BUILD_FOLDER_NAME = "build";
-const LOCAL_BUNDLE_ID = "local";
-const HEALTH_ENDPOINT_PATH = "/sfdc-health";
-/**
-* Reads a package.json file and returns selected metadata.
-*
-* @param path - Absolute path to a package.json file
-* @returns Parsed metadata, or null if missing/unreadable
-*
-* @example
-* ```ts
-* const metadata = readPackageMetadata('/app/package.json');
-* console.log(metadata?.version);
-* ```
-*/
-function readPackageMetadata(path$2) {
-	if (!existsSync$1(path$2)) return null;
-	try {
-		return JSON.parse(readFileSync$1(path$2, "utf8"));
-	} catch (error) {
-		logger.debug(`Health check: failed to parse package.json at ${path$2}`, error);
-		return null;
-	}
-}
-/**
-* Creates an Express handler that returns Health+JSON for the project.
-*
-* @param options - Handler options
-* @returns Express request handler for the health endpoint
-*
-* @example
-* ```ts
-* app.get(HEALTH_ENDPOINT_PATH, createHealthCheckHandler({
-*     projectDirectory: process.cwd(),
-*     bundleId: LOCAL_BUNDLE_ID,
-* }));
-* ```
-*/
-function createHealthCheckHandler(options) {
-	const { projectDirectory, bundleId } = options;
-	const projectPackage = readPackageMetadata(bundleId === LOCAL_BUNDLE_ID ? resolve(projectDirectory, PACKAGE_JSON_NAME) : resolve(projectDirectory, BUILD_FOLDER_NAME, PACKAGE_JSON_NAME));
-	const allDependencies = {
-		...projectPackage?.dependencies,
-		...projectPackage?.devDependencies
-	};
-	const devVersion = allDependencies?.[DEV_PACKAGE_NAME];
-	const runtimeVersion = allDependencies?.[RUNTIME_PACKAGE_NAME];
-	const notes = [devVersion ? `Built using ${DEV_PACKAGE_NAME}@${devVersion}.` : null, runtimeVersion ? `Running ${RUNTIME_PACKAGE_NAME}@${runtimeVersion}.` : null].filter(Boolean);
-	return (_req, res) => {
-		const healthResponse = {
-			status: "pass",
-			version: projectPackage?.version,
-			bundleId,
-			description: projectPackage?.description ?? DEFAULT_HEALTH_DESCRIPTION,
-			notes: notes.length > 0 ? notes : void 0
-		};
-		res.status(200).type("application/health+json").json(healthResponse);
-	};
-}
-
-//#endregion
-//#region src/server/index.ts
-/** Relative path to the middleware registry TypeScript source (development). Must match appDirectory + server dir + filename used by buildMiddlewareRegistry plugin. */
-const RELATIVE_MIDDLEWARE_REGISTRY_SOURCE = "src/server/middleware-registry.ts";
-/** Extensions to try for the built middlewares module (ESM first, then CJS for backwards compatibility). */
-const MIDDLEWARE_REGISTRY_BUILT_EXTENSIONS = [
-	".mjs",
-	".js",
-	".cjs"
-];
-/** All paths to try when loading the built middlewares (base + extension). */
-const RELATIVE_MIDDLEWARE_REGISTRY_BUILT_PATHS = ["bld/server/middleware-registry", "build/server/middleware-registry"].flatMap((base) => MIDDLEWARE_REGISTRY_BUILT_EXTENSIONS.map((ext) => `${base}${ext}`));
-const DEFAULT_BUNDLE_ID = "local";
-/**
-* Create a unified Express server for development, preview, or production mode
-*/
-async function createServer(options) {
-	const { mode, projectDirectory = process.cwd(), config: providedConfig, vite, build, streaming = false, enableProxy = ServerModeFeatureMap[mode].enableProxy, enableStaticServing = ServerModeFeatureMap[mode].enableStaticServing, enableCompression = ServerModeFeatureMap[mode].enableCompression, enableLogging = ServerModeFeatureMap[mode].enableLogging, enableAssetUrlPatching = ServerModeFeatureMap[mode].enableAssetUrlPatching } = options;
-	if (mode === "development" && !vite) throw new Error("Vite dev server instance is required for development mode");
-	if ((mode === "preview" || mode === "production") && !build) throw new Error("React Router server build is required for preview/production mode");
-	const config = providedConfig ?? loadConfigFromEnv();
-	const bundleId = process.env.BUNDLE_ID ?? DEFAULT_BUNDLE_ID;
-	const app = express();
-	app.disable("x-powered-by");
-	if (process.env.SFNEXT_OTEL_ENABLED === "true") app.use(createOtelExpressMiddleware());
-	app.get(HEALTH_ENDPOINT_PATH, createHealthCheckHandler({
-		projectDirectory,
-		bundleId
-	}));
-	if (enableLogging) app.use(createLoggingMiddleware());
-	if (enableCompression && !streaming) app.use(createCompressionMiddleware());
-	if (enableStaticServing && build) {
-		const bundlePath = getBundlePath(bundleId);
-		app.use(bundlePath, createStaticMiddleware(bundleId, projectDirectory));
-	}
-	let registry = null;
-	if (mode === "development") {
-		const middlewareRegistryPath = resolve(projectDirectory, RELATIVE_MIDDLEWARE_REGISTRY_SOURCE);
-		if (existsSync$1(middlewareRegistryPath)) registry = await importTypescript(middlewareRegistryPath, { projectDirectory });
-	} else {
-		const possiblePaths = RELATIVE_MIDDLEWARE_REGISTRY_BUILT_PATHS.map((p) => resolve(projectDirectory, p));
-		let builtRegistryPath = null;
-		for (const path$2 of possiblePaths) if (existsSync$1(path$2)) {
-			builtRegistryPath = path$2;
-			break;
-		}
-		if (builtRegistryPath) registry = await import(pathToFileURL$1(builtRegistryPath).href);
-	}
-	if (registry?.customMiddlewares && Array.isArray(registry.customMiddlewares)) registry.customMiddlewares.forEach((entry) => {
-		app.use(entry.handler);
-	});
-	if (mode === "development" && vite) app.use(vite.middlewares);
-	if (enableProxy) app.use(config.commerce.api.proxy, createCommerceProxyMiddleware(config));
-	const basePath = getBasePath();
-	if (basePath) app.use((req, res, next) => {
-		if (req.path.startsWith(`${basePath}/`) || req.path === basePath) return next();
-		if (req.path.startsWith("/mobify/")) return next();
-		res.redirect(`${basePath}${req.originalUrl}`);
-	});
-	app.use(createHostHeaderMiddleware());
-	app.all("*splat", await createSSRHandler(mode, bundleId, vite, build, enableAssetUrlPatching));
-	return app;
-}
-/**
-* Create the SSR request handler based on mode
-*/
-async function createSSRHandler(mode, bundleId, vite, build, enableAssetUrlPatching) {
-	if (mode === "development" && vite) {
-		const { isRunnableDevEnvironment } = await import("vite");
-		return async (req, res, next) => {
-			try {
-				const ssrEnvironment = vite.environments.ssr;
-				if (!isRunnableDevEnvironment(ssrEnvironment)) {
-					next(/* @__PURE__ */ new Error("SSR environment is not runnable. Please ensure:\n  1. \"@salesforce/storefront-next-dev\" plugin is added to vite.config.ts\n  2. React Router config uses the Storefront Next preset"));
-					return;
-				}
-				await createRequestHandler({
-					build: await ssrEnvironment.runner.import("virtual:react-router/server-build"),
-					mode: process.env.NODE_ENV
-				})(req, res, next);
-			} catch (error) {
-				vite.ssrFixStacktrace(error);
-				next(error);
-			}
-		};
-	} else if (build) {
-		let patchedBuild = build;
-		if (enableAssetUrlPatching) patchedBuild = patchReactRouterBuild(build, bundleId);
-		const requestHandlerMode = process.env.NODE_OPTIONS?.includes("--enable-source-maps") ? "development" : process.env.NODE_ENV;
-		return createRequestHandler({
-			build: patchedBuild,
-			mode: requestHandlerMode
-		});
-	} else throw new Error("Invalid server configuration: no vite or build provided");
-}
-
-//#endregion
-//#region src/extensibility/path-util.ts
-const FILE_EXTENSIONS = [
-	".tsx",
-	".ts",
-	".d.ts"
-];
-function isSupportedFileExtension(fileName) {
-	return FILE_EXTENSIONS.some((ext) => fileName.endsWith(ext));
-}
-
-//#endregion
-//#region src/extensibility/trim-extensions.ts
-const SINGLE_LINE_MARKER = "@sfdc-extension-line";
-const BLOCK_MARKER_START = "@sfdc-extension-block-start";
-const BLOCK_MARKER_END = "@sfdc-extension-block-end";
-const FILE_MARKER = "@sfdc-extension-file";
-function trimExtensions(directory, selectedExtensions, extensionConfig) {
-	const startTime = Date.now();
-	const configuredExtensions = extensionConfig?.extensions || {};
-	const extensions = {};
-	Object.keys(configuredExtensions).forEach((targetKey) => {
-		extensions[targetKey] = Boolean(selectedExtensions?.[targetKey]) || false;
-	});
-	if (Object.keys(extensions).length === 0) {
-		logger.debug("No targets found, skipping trim");
-		return;
-	}
-	const processDirectory = (dir) => {
-		fs$1.readdirSync(dir).forEach((file) => {
-			const filePath = path$1.join(dir, file);
-			const stats = fs$1.statSync(filePath);
-			if (!filePath.includes("node_modules")) {
-				if (stats.isDirectory()) processDirectory(filePath);
-				else if (isSupportedFileExtension(file)) processFile(filePath, extensions);
-			}
-		});
-	};
-	processDirectory(directory);
-	if (extensionConfig?.extensions) {
-		deleteExtensionFolders(directory, extensions, extensionConfig);
-		updateExtensionConfig(directory, extensions);
-	}
-	const endTime = Date.now();
-	logger.debug(`Trim extensions took ${endTime - startTime}ms`);
-}
-/**
-* Update the extension config file to only include the selected extensions.
-* @param projectDirectory - The project directory
-* @param extensionSelections - The selected extensions
-*/
-function updateExtensionConfig(projectDirectory, extensionSelections) {
-	const extensionConfigPath = path$1.join(projectDirectory, "src", "extensions", "config.json");
-	const extensionConfig = JSON.parse(fs$1.readFileSync(extensionConfigPath, "utf8"));
-	Object.keys(extensionConfig.extensions).forEach((extensionKey) => {
-		if (!extensionSelections[extensionKey]) delete extensionConfig.extensions[extensionKey];
-	});
-	fs$1.writeFileSync(extensionConfigPath, JSON.stringify({ extensions: extensionConfig.extensions }, null, 4), "utf8");
-}
-/**
-* Process a file to trim extension-specific code based on markers.
-* @param filePath - The file path to process
-* @param extensions - The extension selections
-*/
-function processFile(filePath, extensions) {
-	const source = fs$1.readFileSync(filePath, "utf-8");
-	if (source.includes(FILE_MARKER)) {
-		const markerLine = source.split("\n").find((line) => line.includes(FILE_MARKER));
-		const extMatch = Object.keys(extensions).find((ext) => markerLine.includes(ext));
-		if (!extMatch) logger.warn(`File ${filePath} is marked with ${markerLine} but it does not match any known extensions`);
-		else if (extensions[extMatch] === false) {
-			try {
-				fs$1.unlinkSync(filePath);
-				logger.debug(`Deleted file ${filePath}`);
-			} catch (e) {
-				const error = e;
-				logger.error(`Error deleting file ${filePath}: ${error.message}`);
-				throw e;
-			}
-			return;
-		}
-	}
-	const extKeys = Object.keys(extensions);
-	if (new RegExp(extKeys.join("|"), "g").test(source)) {
-		const lines = source.split("\n");
-		const newLines = [];
-		const blockMarkers = [];
-		let skippingBlock = false;
-		let i = 0;
-		while (i < lines.length) {
-			const line = lines[i];
-			if (line.includes(SINGLE_LINE_MARKER)) {
-				const matchingExtension = Object.keys(extensions).find((extension) => line.includes(extension));
-				if (matchingExtension && extensions[matchingExtension] === false) {
-					i += 2;
-					continue;
-				}
-			} else if (line.includes(BLOCK_MARKER_START)) {
-				const matchingExtension = Object.keys(extensions).find((extension) => line.includes(extension));
-				if (matchingExtension) {
-					blockMarkers.push({
-						extension: matchingExtension,
-						line: i
-					});
-					skippingBlock = extensions[matchingExtension] === false;
-				} else logger.warn(`Unknown marker found in ${filePath} at line ${i}: \n${line}`);
-			} else if (line.includes(BLOCK_MARKER_END)) {
-				if (Object.keys(extensions).find((extension) => line.includes(extension))) {
-					const extension = Object.keys(extensions).find((p) => line.includes(p));
-					if (blockMarkers.length === 0) throw new Error(`Block marker mismatch in ${filePath}, encountered end marker ${extension} without a matching start marker at line ${i}:\n${lines[i]}`);
-					const startMarker = blockMarkers.pop();
-					if (!extension || startMarker.extension !== extension) throw new Error(`Block marker mismatch in ${filePath}, expected end marker for ${startMarker.extension} but got ${extension} at line ${i}:\n${lines[i]}`);
-					if (extensions[extension] === false) {
-						skippingBlock = false;
-						i++;
-						continue;
-					}
-				}
-			}
-			if (!skippingBlock) newLines.push(line);
-			i++;
-		}
-		if (blockMarkers.length > 0) throw new Error(`Unclosed end marker found in ${filePath}: ${blockMarkers[blockMarkers.length - 1].extension}`);
-		const newSource = newLines.join("\n");
-		if (newSource !== source) try {
-			fs$1.writeFileSync(filePath, newSource);
-			logger.debug(`Updated file ${filePath}`);
-		} catch (e) {
-			const error = e;
-			logger.error(`Error updating file ${filePath}: ${error.message}`);
-			throw e;
-		}
-	}
-}
-/**
-* Delete extension folders for disabled extensions.
-* @param projectRoot - The project root directory
-* @param extensions - The extension selections
-* @param extensionConfig - The extension configuration
-*/
-function deleteExtensionFolders(projectRoot, extensions, extensionConfig) {
-	const extensionsDir = path$1.join(projectRoot, "src", "extensions");
-	if (!fs$1.existsSync(extensionsDir)) return;
-	const configuredExtensions = extensionConfig.extensions;
-	Object.keys(extensions).filter((ext) => extensions[ext] === false).forEach((extKey) => {
-		const extensionMeta = configuredExtensions[extKey];
-		if (extensionMeta?.folder) {
-			const extensionFolderPath = path$1.join(extensionsDir, extensionMeta.folder);
-			if (fs$1.existsSync(extensionFolderPath)) try {
-				fs$1.rmSync(extensionFolderPath, {
-					recursive: true,
-					force: true
-				});
-				logger.debug(`Deleted extension folder: ${extensionFolderPath}`);
-			} catch (err) {
-				const error = err;
-				if (error.code === "EPERM") logger.error(`Permission denied - cannot delete ${extensionFolderPath}. You may need to run with sudo or check permissions.`);
-				else logger.error(`Error deleting ${extensionFolderPath}: ${error.message}`);
-			}
-		}
-	});
-}
-
-//#endregion
-//#region src/cartridge-services/react-router-config.ts
-let isCliAvailable = null;
-function checkReactRouterCli(projectDirectory) {
-	if (isCliAvailable !== null) return isCliAvailable;
-	try {
-		execSync("react-router --version", {
-			cwd: projectDirectory,
-			env: npmRunPathEnv(),
-			stdio: "pipe"
-		});
-		isCliAvailable = true;
-	} catch {
-		isCliAvailable = false;
-	}
-	return isCliAvailable;
-}
-/**
-* Get the fully resolved routes from React Router by invoking its CLI.
-* This ensures we get the exact same route resolution as React Router uses internally,
-* including all presets, file-system routes, and custom route configurations.
-* @param projectDirectory - The project root directory
-* @returns Array of resolved route config entries
-* @example
-* const routes = getReactRouterRoutes('/path/to/project');
-* // Returns the same structure as `react-router routes --json`
-*/
-function getReactRouterRoutes(projectDirectory) {
-	if (!checkReactRouterCli(projectDirectory)) throw new Error("React Router CLI is not available. Please make sure @react-router/dev is installed and accessible.");
-	const tempFile = join(tmpdir(), `react-router-routes-${randomUUID()}.json`);
-	try {
-		execSync(`react-router routes --json > "${tempFile}"`, {
-			cwd: projectDirectory,
-			env: npmRunPathEnv(),
-			encoding: "utf-8",
-			stdio: [
-				"pipe",
-				"pipe",
-				"pipe"
-			]
-		});
-		const output = readFileSync$1(tempFile, "utf-8");
-		return JSON.parse(output);
-	} catch (error) {
-		throw new Error(`Failed to get routes from React Router CLI: ${error.message}`);
-	} finally {
-		try {
-			if (existsSync$1(tempFile)) unlinkSync(tempFile);
-		} catch {}
-	}
-}
-/**
-* Convert a file path to its corresponding route path using React Router's CLI.
-* This ensures we get the exact same route resolution as React Router uses internally.
-* @param filePath - Absolute path to the route file
-* @param projectRoot - The project root directory
-* @returns The route path (e.g., '/cart', '/product/:productId')
-* @example
-* const route = filePathToRoute('/path/to/project/src/routes/_app.cart.tsx', '/path/to/project');
-* // Returns: '/cart'
-*/
-function filePathToRoute(filePath, projectRoot) {
-	const filePathPosix = filePath.replace(/\\/g, "/");
-	const canonicalRoutes = flattenRoutes(getReactRouterRoutes(projectRoot)).filter((route) => !route.id.endsWith("--root-duplicate"));
-	for (const route of canonicalRoutes) {
-		const routeFilePosix = route.file.replace(/\\/g, "/");
-		const routeFileNormalized = routeFilePosix.replace(/^\.\//, "");
-		if (filePathPosix.endsWith(routeFilePosix) || filePathPosix.endsWith(`/${routeFilePosix}`) || filePathPosix.endsWith(routeFileNormalized) || filePathPosix.endsWith(`/${routeFileNormalized}`)) return route.path;
-	}
-	logger.warn(`Could not find route for file: ${filePath}`);
-	return "/unknown";
-}
-/**
-* Flatten a nested route tree into a flat array with computed paths.
-* Each route will have its full path computed from parent paths.
-* @param routes - The nested route config entries
-* @param parentPath - The parent path prefix (used internally for recursion)
-* @returns Flat array of routes with their full paths
-*/
-function flattenRoutes(routes, parentPath = "") {
-	const result = [];
-	for (const route of routes) {
-		let fullPath;
-		if (route.index) fullPath = parentPath || "/";
-		else if (route.path) {
-			const pathSegment = route.path.startsWith("/") ? route.path : `/${route.path}`;
-			fullPath = parentPath ? `${parentPath}${pathSegment}`.replace(/\/+/g, "/") : pathSegment;
-		} else fullPath = parentPath || "/";
-		if (route.id) result.push({
-			id: route.id,
-			path: fullPath,
-			file: route.file,
-			index: route.index
-		});
-		if (route.children && route.children.length > 0) {
-			const childPath = route.path ? fullPath : parentPath;
-			result.push(...flattenRoutes(route.children, childPath));
-		}
-	}
-	return result;
-}
-
-//#endregion
-//#region src/cartridge-services/generate-cartridge.ts
-const SKIP_DIRECTORIES = [
-	"build",
-	"dist",
-	"node_modules",
-	".git",
-	".next",
-	"coverage"
-];
-const DEFAULT_COMPONENT_GROUP = "storefrontnext_base";
-const ARCH_TYPE_HEADLESS = "headless";
-const VALID_ATTRIBUTE_TYPES = [
-	"string",
-	"text",
-	"markup",
-	"integer",
-	"boolean",
-	"product",
-	"category",
-	"file",
-	"page",
-	"image",
-	"url",
-	"enum",
-	"custom",
-	"cms_record"
-];
-const TYPE_MAPPING = {
-	String: "string",
-	string: "string",
-	Number: "integer",
-	number: "integer",
-	Boolean: "boolean",
-	boolean: "boolean",
-	Date: "string",
-	URL: "url",
-	CMSRecord: "cms_record"
-};
-function resolveAttributeType(decoratorType, tsMorphType, fieldName) {
-	if (decoratorType) {
-		if (!VALID_ATTRIBUTE_TYPES.includes(decoratorType)) {
-			logger.error(`Invalid attribute type '${decoratorType}' for field '${fieldName || "unknown"}'. Valid types are: ${VALID_ATTRIBUTE_TYPES.join(", ")}`);
-			process.exit(1);
-		}
-		return decoratorType;
-	}
-	if (tsMorphType && TYPE_MAPPING[tsMorphType]) return TYPE_MAPPING[tsMorphType];
-	return "string";
-}
-function toHumanReadableName(fieldName) {
-	return fieldName.replace(/([A-Z])/g, " $1").replace(/^./, (str) => str.toUpperCase()).trim();
-}
-function toCamelCaseFileName(name) {
-	if (!/[\s-]/.test(name)) return name;
-	return name.split(/[\s-]+/).map((word, index) => {
-		if (index === 0) return word.toLowerCase();
-		return word.charAt(0).toUpperCase() + word.slice(1).toLowerCase();
-	}).join("");
-}
-function getTypeFromTsMorph(property, _sourceFile) {
-	try {
-		const typeNode = property.getTypeNode();
-		if (typeNode) return typeNode.getText().split("|")[0].split("&")[0].trim();
-	} catch {}
-	return "string";
-}
-/**
-* Resolve a variable's initializer expression from the same source file,
-* unwrapping `as const` type assertions.
-*/
-function resolveVariableInitializer(sourceFile, name) {
-	const varDecl = sourceFile.getVariableDeclaration(name);
-	if (!varDecl) return void 0;
-	let initializer = varDecl.getInitializer();
-	if (initializer && Node.isAsExpression(initializer)) initializer = initializer.getExpression();
-	return initializer;
-}
-/**
-* Check whether an AST node is a type that `parseExpression` can resolve to a
-* concrete JS value (as opposed to falling through to `getText()`).
-*/
-function isResolvableLiteral(node) {
-	return Node.isStringLiteral(node) || Node.isNumericLiteral(node) || Node.isTrueLiteral(node) || Node.isFalseLiteral(node) || Node.isObjectLiteralExpression(node) || Node.isArrayLiteralExpression(node);
-}
-var UnresolvedConstantReferenceError = class extends Error {
-	constructor(reference) {
-		super(`Cannot resolve constant reference '${reference}'. Ensure the variable is declared in the same file as a literal value.`);
-		this.name = "UnresolvedConstantReferenceError";
-	}
-};
-function parseExpression(expression) {
-	if (Node.isStringLiteral(expression)) return expression.getLiteralValue();
-	else if (Node.isNumericLiteral(expression)) return expression.getLiteralValue();
-	else if (Node.isTrueLiteral(expression)) return true;
-	else if (Node.isFalseLiteral(expression)) return false;
-	else if (Node.isObjectLiteralExpression(expression)) return parseNestedObject(expression);
-	else if (Node.isArrayLiteralExpression(expression)) return parseArrayLiteral(expression);
-	else if (Node.isPropertyAccessExpression(expression)) {
-		const obj = expression.getExpression();
-		const propName = expression.getName();
-		if (Node.isIdentifier(obj)) {
-			const resolved = resolveVariableInitializer(expression.getSourceFile(), obj.getText());
-			if (resolved && Node.isObjectLiteralExpression(resolved)) {
-				const prop = resolved.getProperty(propName);
-				if (prop && Node.isPropertyAssignment(prop)) {
-					const propInit = prop.getInitializer();
-					if (propInit) return parseExpression(propInit);
-				}
-			}
-			throw new UnresolvedConstantReferenceError(expression.getText());
-		}
-		return expression.getText();
-	} else if (Node.isIdentifier(expression)) {
-		const resolved = resolveVariableInitializer(expression.getSourceFile(), expression.getText());
-		if (resolved && isResolvableLiteral(resolved)) return parseExpression(resolved);
-		return expression.getText();
-	} else return expression.getText();
-}
-function parseNestedObject(objectLiteral) {
-	const result = {};
-	try {
-		const properties = objectLiteral.getProperties();
-		for (const property of properties) if (Node.isPropertyAssignment(property)) {
-			const name = property.getName();
-			const initializer = property.getInitializer();
-			if (initializer) result[name] = parseExpression(initializer);
-		}
-	} catch (error) {
-		logger.warn(`Could not parse nested object: ${error.message}`);
-		return result;
-	}
-	return result;
-}
-function parseArrayLiteral(arrayLiteral) {
-	const result = [];
-	try {
-		const elements = arrayLiteral.getElements();
-		for (const element of elements) result.push(parseExpression(element));
-	} catch (error) {
-		logger.warn(`Could not parse array literal: ${error.message}`);
-	}
-	return result;
-}
-function parseDecoratorArgs(decorator) {
-	const result = {};
-	try {
-		const args = decorator.getArguments();
-		if (args.length === 0) return result;
-		const firstArg = args[0];
-		if (Node.isObjectLiteralExpression(firstArg)) {
-			const properties = firstArg.getProperties();
-			for (const property of properties) if (Node.isPropertyAssignment(property)) {
-				const name = property.getName();
-				const initializer = property.getInitializer();
-				if (initializer) result[name] = parseExpression(initializer);
-			}
-		} else if (Node.isStringLiteral(firstArg)) {
-			result.id = parseExpression(firstArg);
-			if (args.length > 1) {
-				const secondArg = args[1];
-				if (Node.isObjectLiteralExpression(secondArg)) {
-					const properties = secondArg.getProperties();
-					for (const property of properties) if (Node.isPropertyAssignment(property)) {
-						const name = property.getName();
-						const initializer = property.getInitializer();
-						if (initializer) result[name] = parseExpression(initializer);
-					}
-				}
-			}
-		}
-		return result;
-	} catch (error) {
-		if (error instanceof UnresolvedConstantReferenceError) throw error;
-		logger.warn(`Could not parse decorator arguments: ${error.message}`);
-		return result;
-	}
-}
-function extractAttributesFromSource(sourceFile, className) {
-	const attributes = [];
-	try {
-		const classDeclaration = sourceFile.getClass(className);
-		if (!classDeclaration) return attributes;
-		const properties = classDeclaration.getProperties();
-		for (const property of properties) {
-			const attributeDecorator = property.getDecorator("AttributeDefinition");
-			if (!attributeDecorator) continue;
-			const fieldName = property.getName();
-			const config = parseDecoratorArgs(attributeDecorator);
-			const isRequired = !property.hasQuestionToken();
-			const inferredType = config.type || getTypeFromTsMorph(property, sourceFile);
-			const attribute = {
-				id: config.id || fieldName,
-				name: config.name || toHumanReadableName(fieldName),
-				type: resolveAttributeType(config.type, inferredType, fieldName),
-				required: config.required !== void 0 ? config.required : isRequired,
-				description: config.description || `Field: ${fieldName}`
-			};
-			if (config.values) attribute.values = config.values;
-			if (config.defaultValue !== void 0) attribute.default_value = config.defaultValue;
-			attributes.push(attribute);
-		}
-	} catch (error) {
-		if (error instanceof UnresolvedConstantReferenceError) throw error;
-		logger.warn(`Could not extract attributes from class ${className}: ${error.message}`);
-	}
-	return attributes;
-}
-function normalizeComponentTypeId(typeId, defaultGroup) {
-	return typeId.includes(".") ? typeId : `${defaultGroup}.${typeId}`;
-}
-function extractRegionDefinitionsFromSource(sourceFile, className, defaultComponentGroup = DEFAULT_COMPONENT_GROUP) {
-	const regionDefinitions = [];
-	try {
-		const classDeclaration = sourceFile.getClass(className);
-		if (!classDeclaration) return regionDefinitions;
-		const classRegionDecorator = classDeclaration.getDecorator("RegionDefinition");
-		if (classRegionDecorator) {
-			const args = classRegionDecorator.getArguments();
-			if (args.length > 0) {
-				const firstArg = args[0];
-				if (Node.isArrayLiteralExpression(firstArg)) {
-					const elements = firstArg.getElements();
-					for (const element of elements) if (Node.isObjectLiteralExpression(element)) {
-						const regionConfig = parseDecoratorArgs({ getArguments: () => [element] });
-						const regionDefinition = {
-							id: regionConfig.id || "region",
-							name: regionConfig.name || "Region"
-						};
-						if (regionConfig.componentTypes) regionDefinition.component_types = regionConfig.componentTypes;
-						if (Array.isArray(regionConfig.componentTypeInclusions)) regionDefinition.component_type_inclusions = regionConfig.componentTypeInclusions.map((incl) => ({ type_id: normalizeComponentTypeId(String(incl), defaultComponentGroup) }));
-						if (Array.isArray(regionConfig.componentTypeExclusions)) regionDefinition.component_type_exclusions = regionConfig.componentTypeExclusions.map((excl) => ({ type_id: normalizeComponentTypeId(String(excl), defaultComponentGroup) }));
-						if (regionConfig.maxComponents !== void 0) regionDefinition.max_components = regionConfig.maxComponents;
-						if (regionConfig.minComponents !== void 0) regionDefinition.min_components = regionConfig.minComponents;
-						if (regionConfig.allowMultiple !== void 0) regionDefinition.allow_multiple = regionConfig.allowMultiple;
-						if (regionConfig.defaultComponentConstructors) regionDefinition.default_component_constructors = regionConfig.defaultComponentConstructors;
-						regionDefinitions.push(regionDefinition);
-					}
-				}
-			}
-		}
-	} catch (error) {
-		logger.warn(`Warning: Could not extract region definitions from class ${className}: ${error.message}`);
-	}
-	return regionDefinitions;
-}
-async function processComponentFile(filePath, _projectRoot) {
-	try {
-		const content = await readFile(filePath, "utf-8");
-		const components = [];
-		if (!content.includes("@Component")) return components;
-		try {
-			const sourceFile = new Project({
-				useInMemoryFileSystem: true,
-				skipAddingFilesFromTsConfig: true
-			}).createSourceFile(filePath, content);
-			const classes = sourceFile.getClasses();
-			for (const classDeclaration of classes) {
-				const componentDecorator = classDeclaration.getDecorator("Component");
-				if (!componentDecorator) continue;
-				const className = classDeclaration.getName();
-				if (!className) continue;
-				const componentConfig = parseDecoratorArgs(componentDecorator);
-				const componentGroup = String(componentConfig.group || DEFAULT_COMPONENT_GROUP);
-				const attributes = extractAttributesFromSource(sourceFile, className);
-				const regionDefinitions = extractRegionDefinitionsFromSource(sourceFile, className, componentGroup);
-				const componentMetadata = {
-					typeId: componentConfig.id || className.toLowerCase(),
-					name: componentConfig.name || toHumanReadableName(className),
-					group: componentGroup,
-					description: componentConfig.description || `Custom component: ${className}`,
-					regionDefinitions,
-					attributes
-				};
-				components.push(componentMetadata);
-			}
-		} catch (error) {
-			if (error instanceof UnresolvedConstantReferenceError) throw error;
-			logger.warn(`Could not process file ${filePath}:`, error.message);
-		}
-		return components;
-	} catch (error) {
-		if (error instanceof UnresolvedConstantReferenceError) throw error;
-		logger.warn(`Could not read file ${filePath}:`, error.message);
-		return [];
-	}
-}
-async function processPageTypeFile(filePath, projectRoot) {
-	try {
-		const content = await readFile(filePath, "utf-8");
-		const pageTypes = [];
-		if (!content.includes("@PageType")) return pageTypes;
-		try {
-			const sourceFile = new Project({
-				useInMemoryFileSystem: true,
-				skipAddingFilesFromTsConfig: true
-			}).createSourceFile(filePath, content);
-			const classes = sourceFile.getClasses();
-			for (const classDeclaration of classes) {
-				const pageTypeDecorator = classDeclaration.getDecorator("PageType");
-				if (!pageTypeDecorator) continue;
-				const className = classDeclaration.getName();
-				if (!className) continue;
-				const pageTypeConfig = parseDecoratorArgs(pageTypeDecorator);
-				const attributes = extractAttributesFromSource(sourceFile, className);
-				const regionDefinitions = extractRegionDefinitionsFromSource(sourceFile, className);
-				const route = filePathToRoute(filePath, projectRoot);
-				const pageTypeMetadata = {
-					typeId: pageTypeConfig.id || className.toLowerCase(),
-					name: pageTypeConfig.name || toHumanReadableName(className),
-					description: pageTypeConfig.description || `Custom page type: ${className}`,
-					regionDefinitions,
-					supportedAspectTypes: pageTypeConfig.supportedAspectTypes || [],
-					attributes,
-					route
-				};
-				pageTypes.push(pageTypeMetadata);
-			}
-		} catch (error) {
-			logger.warn(`Could not process file ${filePath}:`, error.message);
-		}
-		return pageTypes;
-	} catch (error) {
-		logger.warn(`Could not read file ${filePath}:`, error.message);
-		return [];
-	}
-}
-async function processAspectFile(filePath, _projectRoot) {
-	try {
-		const content = await readFile(filePath, "utf-8");
-		const aspects = [];
-		if (!filePath.endsWith(".json") || !content.trim().startsWith("{")) return aspects;
-		if (!filePath.includes("/aspects/") && !filePath.includes("\\aspects\\")) return aspects;
-		try {
-			const aspectData = JSON.parse(content);
-			const fileName = basename(filePath, ".json");
-			if (!aspectData.name || !aspectData.attribute_definitions) return aspects;
-			const aspectMetadata = {
-				id: fileName,
-				name: aspectData.name,
-				description: aspectData.description || `Aspect type: ${aspectData.name}`,
-				attributeDefinitions: aspectData.attribute_definitions || [],
-				supportedObjectTypes: aspectData.supported_object_types || []
-			};
-			aspects.push(aspectMetadata);
-		} catch (parseError) {
-			logger.warn(`Could not parse JSON in file ${filePath}:`, parseError.message);
-		}
-		return aspects;
-	} catch (error) {
-		logger.warn(`Could not read file ${filePath}:`, error.message);
-		return [];
-	}
-}
-async function generateComponentCartridge(component, outputDir, dryRun = false) {
-	const fileName = toCamelCaseFileName(component.typeId);
-	const groupDir = join(outputDir, component.group);
-	const outputPath = join(groupDir, `${fileName}.json`);
-	if (!dryRun) {
-		try {
-			await mkdir(groupDir, { recursive: true });
-		} catch {}
-		const attributeDefinitionGroups = [{
-			id: component.typeId,
-			name: component.name,
-			description: component.description,
-			attribute_definitions: component.attributes
-		}];
-		const cartridgeData = {
-			name: component.name,
-			description: component.description,
-			group: component.group,
-			arch_type: ARCH_TYPE_HEADLESS,
-			region_definitions: component.regionDefinitions || [],
-			attribute_definition_groups: attributeDefinitionGroups
-		};
-		await writeFile(outputPath, JSON.stringify(cartridgeData, null, 2));
-	}
-	const prefix = dryRun ? "   - [DRY RUN]" : "   -";
-	logger.debug(`${prefix} ${String(component.typeId)}: ${String(component.name)} (${String(component.attributes.length)} attributes) → ${fileName}.json`);
-}
-async function generatePageTypeCartridge(pageType, outputDir, dryRun = false) {
-	const fileName = toCamelCaseFileName(pageType.name);
-	const outputPath = join(outputDir, `${fileName}.json`);
-	if (!dryRun) {
-		const cartridgeData = {
-			name: pageType.name,
-			description: pageType.description,
-			arch_type: ARCH_TYPE_HEADLESS,
-			region_definitions: pageType.regionDefinitions || []
-		};
-		if (pageType.attributes && pageType.attributes.length > 0) cartridgeData.attribute_definition_groups = [{
-			id: pageType.typeId || fileName,
-			name: pageType.name,
-			description: pageType.description,
-			attribute_definitions: pageType.attributes
-		}];
-		if (pageType.supportedAspectTypes) cartridgeData.supported_aspect_types = pageType.supportedAspectTypes;
-		if (pageType.route) cartridgeData.route = pageType.route;
-		await writeFile(outputPath, JSON.stringify(cartridgeData, null, 2));
-	}
-	const prefix = dryRun ? "   - [DRY RUN]" : "   -";
-	logger.debug(`${prefix} ${String(pageType.name)}: ${String(pageType.description)} (${String(pageType.attributes.length)} attributes) → ${fileName}.json`);
-}
-async function generateAspectCartridge(aspect, outputDir, dryRun = false) {
-	const fileName = toCamelCaseFileName(aspect.id);
-	const outputPath = join(outputDir, `${fileName}.json`);
-	if (!dryRun) {
-		const cartridgeData = {
-			name: aspect.name,
-			description: aspect.description,
-			arch_type: ARCH_TYPE_HEADLESS,
-			attribute_definitions: aspect.attributeDefinitions || []
-		};
-		if (aspect.supportedObjectTypes) cartridgeData.supported_object_types = aspect.supportedObjectTypes;
-		await writeFile(outputPath, JSON.stringify(cartridgeData, null, 2));
-	}
-	const prefix = dryRun ? "   - [DRY RUN]" : "   -";
-	logger.debug(`${prefix} ${String(aspect.name)}: ${String(aspect.description)} (${String(aspect.attributeDefinitions.length)} attributes) → ${fileName}.json`);
-}
-/**
-* Runs ESLint with --fix on the specified directory to format JSON files.
-* This ensures generated JSON files match the project's Prettier/ESLint configuration.
-*/
-function lintGeneratedFiles(metadataDir, projectRoot) {
-	try {
-		logger.debug("🔧 Running ESLint --fix on generated JSON files...");
-		execSync(`npx eslint "${metadataDir}/**/*.json" --fix --no-error-on-unmatched-pattern`, {
-			cwd: projectRoot,
-			stdio: "pipe",
-			encoding: "utf-8"
-		});
-		logger.debug("✅ JSON files formatted successfully");
-	} catch (error) {
-		const execError = error;
-		if (execError.status === 2) {
-			const errMsg = execError.stderr || execError.stdout || "Unknown error";
-			logger.warn(`⚠️  Could not run ESLint --fix: ${errMsg}`);
-		} else if (execError.stderr && execError.stderr.includes("error")) logger.warn(`⚠️  Some linting issues could not be auto-fixed. Run ESLint manually to review.`);
-		else logger.debug("✅ JSON files formatted successfully");
-	}
-}
-async function generateMetadata(projectDirectory, metadataDirectory, options) {
-	try {
-		const filePaths = options?.filePaths;
-		const isIncrementalMode = filePaths && filePaths.length > 0;
-		const dryRun = options?.dryRun || false;
-		if (dryRun) logger.debug("🔍 [DRY RUN] Scanning for decorated components and page types...");
-		else if (isIncrementalMode) logger.debug(`🔍 Generating metadata for ${filePaths.length} specified file(s)...`);
-		else logger.debug("🔍 Generating metadata for decorated components and page types...");
-		const projectRoot = resolve(projectDirectory);
-		const srcDir = join(projectRoot, "src");
-		const metadataDir = resolve(metadataDirectory);
-		const componentsOutputDir = join(metadataDir, "components");
-		const pagesOutputDir = join(metadataDir, "pages");
-		const aspectsOutputDir = join(metadataDir, "aspects");
-		if (!dryRun) {
-			if (!isIncrementalMode) {
-				logger.debug("🗑️  Cleaning existing output directories...");
-				for (const outputDir of [
-					componentsOutputDir,
-					pagesOutputDir,
-					aspectsOutputDir
-				]) try {
-					await rm(outputDir, {
-						recursive: true,
-						force: true
-					});
-					logger.debug(`   - Deleted: ${outputDir}`);
-				} catch {
-					logger.debug(`   - Directory not found (skipping): ${outputDir}`);
-				}
-			} else logger.debug("📝 Incremental mode: existing cartridge files will be preserved/overwritten");
-			logger.debug("Creating output directories...");
-			for (const outputDir of [
-				componentsOutputDir,
-				pagesOutputDir,
-				aspectsOutputDir
-			]) try {
-				await mkdir(outputDir, { recursive: true });
-			} catch (error) {
-				try {
-					await access(outputDir);
-				} catch {
-					const err = error;
-					logger.error(`❌ Failed to create output directory ${outputDir}: ${err.message}`);
-					process.exit(1);
-					throw err;
-				}
-			}
-		} else if (isIncrementalMode) logger.debug(`📝 [DRY RUN] Would process ${filePaths.length} specific file(s)`);
-		else logger.debug("📝 [DRY RUN] Would clean and regenerate all metadata files");
-		let files = [];
-		if (isIncrementalMode && filePaths) {
-			files = filePaths.map((fp) => resolve(projectRoot, fp));
-			logger.debug(`📂 Processing ${files.length} specified file(s)...`);
-		} else {
-			const scanDirectory = async (dir) => {
-				const entries = await readdir(dir, { withFileTypes: true });
-				for (const entry of entries) {
-					const fullPath = join(dir, entry.name);
-					if (entry.isDirectory()) {
-						if (!SKIP_DIRECTORIES.includes(entry.name)) await scanDirectory(fullPath);
-					} else if (entry.isFile() && (extname(entry.name) === ".ts" || extname(entry.name) === ".tsx" || extname(entry.name) === ".json")) files.push(fullPath);
-				}
-			};
-			await scanDirectory(srcDir);
-			const configMetadataDir = join(projectRoot, "config-metadata");
-			try {
-				await access(configMetadataDir);
-				await scanDirectory(configMetadataDir);
-			} catch (error) {
-				if (error.code === "ENOENT") logger.debug(`   - Directory not found (skipping): ${configMetadataDir}`);
-				else logger.warn(`   - Unable to access ${configMetadataDir}:`, error.message);
-			}
-		}
-		const allComponents = [];
-		const allPageTypes = [];
-		const allAspects = [];
-		for (const file of files) {
-			const components = await processComponentFile(file, projectRoot);
-			allComponents.push(...components);
-			const pageTypes = await processPageTypeFile(file, projectRoot);
-			allPageTypes.push(...pageTypes);
-			const aspects = await processAspectFile(file, projectRoot);
-			allAspects.push(...aspects);
-		}
-		if (allComponents.length === 0 && allPageTypes.length === 0 && allAspects.length === 0) {
-			logger.info("⚠️  No decorated components, page types, or aspect files found.");
-			return {
-				componentsGenerated: 0,
-				pageTypesGenerated: 0,
-				aspectsGenerated: 0,
-				totalFiles: 0
-			};
-		}
-		if (allComponents.length > 0) {
-			logger.debug(`✅ Found ${allComponents.length} decorated component(s)`);
-			for (const component of allComponents) await generateComponentCartridge(component, componentsOutputDir, dryRun);
-			if (dryRun) logger.info(`[DRY RUN] Would generate ${allComponents.length} component metadata file(s)`);
-			else logger.info(`Generated ${allComponents.length} component metadata file(s)`);
-		}
-		if (allPageTypes.length > 0) {
-			logger.debug(`✅ Found ${allPageTypes.length} decorated page type(s)`);
-			for (const pageType of allPageTypes) await generatePageTypeCartridge(pageType, pagesOutputDir, dryRun);
-			if (dryRun) logger.info(`[DRY RUN] Would generate ${allPageTypes.length} page type metadata file(s)`);
-			else logger.info(`Generated ${allPageTypes.length} page type metadata file(s)`);
-		}
-		if (allAspects.length > 0) {
-			logger.debug(`✅ Found ${allAspects.length} decorated aspect(s)`);
-			for (const aspect of allAspects) await generateAspectCartridge(aspect, aspectsOutputDir, dryRun);
-			if (dryRun) logger.info(`[DRY RUN] Would generate ${allAspects.length} aspect metadata file(s)`);
-			else logger.info(`Generated ${allAspects.length} aspect metadata file(s)`);
-		}
-		const shouldLintFix = options?.lintFix !== false;
-		if (!dryRun && shouldLintFix && (allComponents.length > 0 || allPageTypes.length > 0 || allAspects.length > 0)) lintGeneratedFiles(metadataDir, projectRoot);
-		return {
-			componentsGenerated: allComponents.length,
-			pageTypesGenerated: allPageTypes.length,
-			aspectsGenerated: allAspects.length,
-			totalFiles: allComponents.length + allPageTypes.length + allAspects.length
-		};
-	} catch (error) {
-		const err = error;
-		logger.error("❌ Error:", err.message);
-		process.exit(1);
-		throw err;
-	}
-}
 
 //#endregion
-export { clearCache, createServer, storefrontNextTargets as default, extractPatterns, generateMetadata, hybridProxyPlugin, loadConfigFromEnv, loadProjectConfig, shouldRouteToNext, testPatterns, transformTargetPlaceholderPlugin, trimExtensions, uiTargetDevModePlugin };
+export { storefrontNextTargets as default, hybridProxyPlugin, shouldRouteToNext, transformTargetPlaceholderPlugin, uiTargetDevModePlugin };
 //# sourceMappingURL=index.js.map