@salesforce/storefront-next-dev 0.2.0-alpha.2 → 0.3.0-alpha.0

package/dist/generate-cartridge.js

@@ -1,3 +1,4 @@
+import { t as logger } from "./logger.js";
 import { existsSync, readFileSync, unlinkSync } from "node:fs";
 import { basename, extname, join, resolve } from "node:path";
 import { access, mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
@@ -76,7 +77,7 @@ function filePathToRoute(filePath, projectRoot) {
 		const routeFileNormalized = routeFilePosix.replace(/^\.\//, "");
 		if (filePathPosix.endsWith(routeFileNormalized) || filePathPosix.endsWith(`/${routeFileNormalized}`)) return route.path;
 	}
-	console.warn(`Warning: Could not find route for file: ${filePath}`);
+	logger.warn(`Could not find route for file: ${filePath}`);
 	return "/unknown";
 }
 /**
@@ -151,7 +152,7 @@ const TYPE_MAPPING = {
 function resolveAttributeType(decoratorType, tsMorphType, fieldName) {
 	if (decoratorType) {
 		if (!VALID_ATTRIBUTE_TYPES.includes(decoratorType)) {
-			console.error(`Error: Invalid attribute type '${decoratorType}' for field '${fieldName || "unknown"}'. Valid types are: ${VALID_ATTRIBUTE_TYPES.join(", ")}`);
+			logger.error(`Invalid attribute type '${decoratorType}' for field '${fieldName || "unknown"}'. Valid types are: ${VALID_ATTRIBUTE_TYPES.join(", ")}`);
 			process.exit(1);
 		}
 		return decoratorType;
@@ -176,6 +177,30 @@ function getTypeFromTsMorph(property, _sourceFile) {
 	} 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();
@@ -183,7 +208,26 @@ function parseExpression(expression) {
 	else if (Node.isFalseLiteral(expression)) return false;
 	else if (Node.isObjectLiteralExpression(expression)) return parseNestedObject(expression);
 	else if (Node.isArrayLiteralExpression(expression)) return parseArrayLiteral(expression);
-	else return expression.getText();
+	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 = {};
@@ -195,7 +239,7 @@ function parseNestedObject(objectLiteral) {
 			if (initializer) result[name] = parseExpression(initializer);
 		}
 	} catch (error) {
-		console.warn(`Warning: Could not parse nested object: ${error.message}`);
+		logger.warn(`Could not parse nested object: ${error.message}`);
 		return result;
 	}
 	return result;
@@ -206,7 +250,7 @@ function parseArrayLiteral(arrayLiteral) {
 		const elements = arrayLiteral.getElements();
 		for (const element of elements) result.push(parseExpression(element));
 	} catch (error) {
-		console.warn(`Warning: Could not parse array literal: ${error.message}`);
+		logger.warn(`Could not parse array literal: ${error.message}`);
 	}
 	return result;
 }
@@ -239,7 +283,8 @@ function parseDecoratorArgs(decorator) {
 		}
 		return result;
 	} catch (error) {
-		console.warn(`Warning: Could not parse decorator arguments: ${error.message}`);
+		if (error instanceof UnresolvedConstantReferenceError) throw error;
+		logger.warn(`Could not parse decorator arguments: ${error.message}`);
 		return result;
 	}
 }
@@ -268,11 +313,15 @@ function extractAttributesFromSource(sourceFile, className) {
 			attributes.push(attribute);
 		}
 	} catch (error) {
-		console.warn(`Warning: Could not extract attributes from class ${className}: ${error.message}`);
+		if (error instanceof UnresolvedConstantReferenceError) throw error;
+		logger.warn(`Could not extract attributes from class ${className}: ${error.message}`);
 	}
 	return attributes;
 }
-function extractRegionDefinitionsFromSource(sourceFile, className) {
+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);
@@ -291,8 +340,8 @@ function extractRegionDefinitionsFromSource(sourceFile, className) {
 							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: incl }));
-						if (Array.isArray(regionConfig.componentTypeExclusions)) regionDefinition.component_type_exclusions = regionConfig.componentTypeExclusions.map((excl) => ({ type_id: excl }));
+						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;
@@ -303,7 +352,7 @@ function extractRegionDefinitionsFromSource(sourceFile, className) {
 			}
 		}
 	} catch (error) {
-		console.warn(`Warning: Could not extract region definitions from class ${className}: ${error.message}`);
+		logger.warn(`Warning: Could not extract region definitions from class ${className}: ${error.message}`);
 	}
 	return regionDefinitions;
 }
@@ -324,12 +373,13 @@ async function processComponentFile(filePath, _projectRoot) {
 				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);
+				const regionDefinitions = extractRegionDefinitionsFromSource(sourceFile, className, componentGroup);
 				const componentMetadata = {
 					typeId: componentConfig.id || className.toLowerCase(),
 					name: componentConfig.name || toHumanReadableName(className),
-					group: componentConfig.group || DEFAULT_COMPONENT_GROUP,
+					group: componentGroup,
 					description: componentConfig.description || `Custom component: ${className}`,
 					regionDefinitions,
 					attributes
@@ -337,11 +387,13 @@ async function processComponentFile(filePath, _projectRoot) {
 				components.push(componentMetadata);
 			}
 		} catch (error) {
-			console.warn(`Warning: Could not process file ${filePath}:`, error.message);
+			if (error instanceof UnresolvedConstantReferenceError) throw error;
+			logger.warn(`Could not process file ${filePath}:`, error.message);
 		}
 		return components;
 	} catch (error) {
-		console.warn(`Warning: Could not read file ${filePath}:`, error.message);
+		if (error instanceof UnresolvedConstantReferenceError) throw error;
+		logger.warn(`Could not read file ${filePath}:`, error.message);
 		return [];
 	}
 }
@@ -377,11 +429,11 @@ async function processPageTypeFile(filePath, projectRoot) {
 				pageTypes.push(pageTypeMetadata);
 			}
 		} catch (error) {
-			console.warn(`Warning: Could not process file ${filePath}:`, error.message);
+			logger.warn(`Could not process file ${filePath}:`, error.message);
 		}
 		return pageTypes;
 	} catch (error) {
-		console.warn(`Warning: Could not read file ${filePath}:`, error.message);
+		logger.warn(`Could not read file ${filePath}:`, error.message);
 		return [];
 	}
 }
@@ -404,11 +456,11 @@ async function processAspectFile(filePath, _projectRoot) {
 			};
 			aspects.push(aspectMetadata);
 		} catch (parseError) {
-			console.warn(`Warning: Could not parse JSON in file ${filePath}:`, parseError.message);
+			logger.warn(`Could not parse JSON in file ${filePath}:`, parseError.message);
 		}
 		return aspects;
 	} catch (error) {
-		console.warn(`Warning: Could not read file ${filePath}:`, error.message);
+		logger.warn(`Could not read file ${filePath}:`, error.message);
 		return [];
 	}
 }
@@ -437,7 +489,7 @@ async function generateComponentCartridge(component, outputDir, dryRun = false)
 		await writeFile(outputPath, JSON.stringify(cartridgeData, null, 2));
 	}
 	const prefix = dryRun ? "   - [DRY RUN]" : "   -";
-	console.log(`${prefix} ${String(component.typeId)}: ${String(component.name)} (${String(component.attributes.length)} attributes) → ${fileName}.json`);
+	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);
@@ -460,7 +512,7 @@ async function generatePageTypeCartridge(pageType, outputDir, dryRun = false) {
 		await writeFile(outputPath, JSON.stringify(cartridgeData, null, 2));
 	}
 	const prefix = dryRun ? "   - [DRY RUN]" : "   -";
-	console.log(`${prefix} ${String(pageType.name)}: ${String(pageType.description)} (${String(pageType.attributes.length)} attributes) → ${fileName}.json`);
+	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);
@@ -476,7 +528,7 @@ async function generateAspectCartridge(aspect, outputDir, dryRun = false) {
 		await writeFile(outputPath, JSON.stringify(cartridgeData, null, 2));
 	}
 	const prefix = dryRun ? "   - [DRY RUN]" : "   -";
-	console.log(`${prefix} ${String(aspect.name)}: ${String(aspect.description)} (${String(aspect.attributeDefinitions.length)} attributes) → ${fileName}.json`);
+	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.
@@ -484,20 +536,20 @@ async function generateAspectCartridge(aspect, outputDir, dryRun = false) {
 */
 function lintGeneratedFiles(metadataDir, projectRoot) {
 	try {
-		console.log("🔧 Running ESLint --fix on generated JSON files...");
+		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"
 		});
-		console.log("✅ JSON files formatted successfully");
+		logger.debug("✅ JSON files formatted successfully");
 	} catch (error) {
 		const execError = error;
 		if (execError.status === 2) {
 			const errMsg = execError.stderr || execError.stdout || "Unknown error";
-			console.warn(`⚠️  Warning: Could not run ESLint --fix: ${errMsg}`);
-		} else if (execError.stderr && execError.stderr.includes("error")) console.warn(`⚠️  Warning: Some linting issues could not be auto-fixed. Run ESLint manually to review.`);
-		else console.log("✅ JSON files formatted successfully");
+			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) {
@@ -505,9 +557,9 @@ async function generateMetadata(projectDirectory, metadataDirectory, options) {
 		const filePaths = options?.filePaths;
 		const isIncrementalMode = filePaths && filePaths.length > 0;
 		const dryRun = options?.dryRun || false;
-		if (dryRun) console.log("🔍 [DRY RUN] Scanning for decorated components and page types...");
-		else if (isIncrementalMode) console.log(`🔍 Generating metadata for ${filePaths.length} specified file(s)...`);
-		else console.log("🔍 Generating metadata for decorated components and page types...");
+		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);
@@ -516,7 +568,7 @@ async function generateMetadata(projectDirectory, metadataDirectory, options) {
 		const aspectsOutputDir = join(metadataDir, "aspects");
 		if (!dryRun) {
 			if (!isIncrementalMode) {
-				console.log("🗑️  Cleaning existing output directories...");
+				logger.debug("🗑️  Cleaning existing output directories...");
 				for (const outputDir of [
 					componentsOutputDir,
 					pagesOutputDir,
@@ -526,12 +578,12 @@ async function generateMetadata(projectDirectory, metadataDirectory, options) {
 						recursive: true,
 						force: true
 					});
-					console.log(`   - Deleted: ${outputDir}`);
+					logger.debug(`   - Deleted: ${outputDir}`);
 				} catch {
-					console.log(`   - Directory not found (skipping): ${outputDir}`);
+					logger.debug(`   - Directory not found (skipping): ${outputDir}`);
 				}
-			} else console.log("📝 Incremental mode: existing cartridge files will be preserved/overwritten");
-			console.log("📁 Creating output directories...");
+			} else logger.debug("📝 Incremental mode: existing cartridge files will be preserved/overwritten");
+			logger.debug("Creating output directories...");
 			for (const outputDir of [
 				componentsOutputDir,
 				pagesOutputDir,
@@ -542,16 +594,18 @@ async function generateMetadata(projectDirectory, metadataDirectory, options) {
 				try {
 					await access(outputDir);
 				} catch {
-					console.error(`❌ Error: Failed to create output directory ${outputDir}: ${error.message}`);
+					const err = error;
+					logger.error(`❌ Failed to create output directory ${outputDir}: ${err.message}`);
 					process.exit(1);
+					throw err;
 				}
 			}
-		} else if (isIncrementalMode) console.log(`📝 [DRY RUN] Would process ${filePaths.length} specific file(s)`);
-		else console.log("📝 [DRY RUN] Would clean and regenerate all metadata files");
+		} 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));
-			console.log(`📂 Processing ${files.length} specified file(s)...`);
+			logger.debug(`📂 Processing ${files.length} specified file(s)...`);
 		} else {
 			const scanDirectory = async (dir) => {
 				const entries = await readdir(dir, { withFileTypes: true });
@@ -576,7 +630,7 @@ async function generateMetadata(projectDirectory, metadataDirectory, options) {
 			allAspects.push(...aspects);
 		}
 		if (allComponents.length === 0 && allPageTypes.length === 0 && allAspects.length === 0) {
-			console.log("⚠️  No decorated components, page types, or aspect files found.");
+			logger.info("⚠️  No decorated components, page types, or aspect files found.");
 			return {
 				componentsGenerated: 0,
 				pageTypesGenerated: 0,
@@ -585,22 +639,22 @@ async function generateMetadata(projectDirectory, metadataDirectory, options) {
 			};
 		}
 		if (allComponents.length > 0) {
-			console.log(`✅ Found ${allComponents.length} decorated component(s):`);
+			logger.debug(`✅ Found ${allComponents.length} decorated component(s)`);
 			for (const component of allComponents) await generateComponentCartridge(component, componentsOutputDir, dryRun);
-			if (dryRun) console.log(`📄 [DRY RUN] Would generate ${allComponents.length} component metadata file(s) in: ${componentsOutputDir}`);
-			else console.log(`📄 Generated ${allComponents.length} component metadata file(s) in: ${componentsOutputDir}`);
+			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) {
-			console.log(`✅ Found ${allPageTypes.length} decorated page type(s):`);
+			logger.debug(`✅ Found ${allPageTypes.length} decorated page type(s)`);
 			for (const pageType of allPageTypes) await generatePageTypeCartridge(pageType, pagesOutputDir, dryRun);
-			if (dryRun) console.log(`📄 [DRY RUN] Would generate ${allPageTypes.length} page type metadata file(s) in: ${pagesOutputDir}`);
-			else console.log(`📄 Generated ${allPageTypes.length} page type metadata file(s) in: ${pagesOutputDir}`);
+			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) {
-			console.log(`✅ Found ${allAspects.length} decorated aspect(s):`);
+			logger.debug(`✅ Found ${allAspects.length} decorated aspect(s)`);
 			for (const aspect of allAspects) await generateAspectCartridge(aspect, aspectsOutputDir, dryRun);
-			if (dryRun) console.log(`📄 [DRY RUN] Would generate ${allAspects.length} aspect metadata file(s) in: ${aspectsOutputDir}`);
-			else console.log(`📄 Generated ${allAspects.length} aspect metadata file(s) in: ${aspectsOutputDir}`);
+			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);
@@ -611,8 +665,10 @@ async function generateMetadata(projectDirectory, metadataDirectory, options) {
 			totalFiles: allComponents.length + allPageTypes.length + allAspects.length
 		};
 	} catch (error) {
-		console.error("❌ Error:", error.message);
+		const err = error;
+		logger.error("❌ Error:", err.message);
 		process.exit(1);
+		throw err;
 	}
 }
 

package/dist/index.d.ts

@@ -31,11 +31,6 @@ interface StaticRegistryPluginConfig {
    * @default true
    */
   failOnError?: boolean;
-  /**
-   * Enable verbose logging
-   * @default false
-   */
-  verbose?: boolean;
 }
 //#endregion
 //#region src/plugins/eventInstrumentationValidator.d.ts
@@ -59,11 +54,6 @@ interface EventInstrumentationValidatorConfig {
    * @default false (warning only)
    */
   failOnMissing?: boolean;
-  /**
-   * Enable verbose logging
-   * @default false
-   */
-  verbose?: boolean;
 }
 //#endregion
 //#region src/storefront-next-targets.d.ts
@@ -148,6 +138,131 @@ declare function transformTargetPlaceholderPlugin(): {
   } | null;
 };
 //#endregion
+//#region src/plugins/hybridProxy.d.ts
+
+interface HybridProxyPluginOptions {
+  /** Whether hybrid proxying is enabled */
+  enabled: boolean;
+  /** SFCC origin URL to proxy non-matching routes to */
+  targetOrigin: string;
+  /** Cloudflare routing expression (routes matching go to Next) */
+  routingRules: string;
+  /**
+   * Callback that decides if a pathname should be handled by Storefront Next.
+   * Called for every request that isn't a Vite internal or SFCC path.
+   * Receives the pathname and the raw `routingRules` string; returns true to
+   * let React Router handle it, false to proxy to SFCC.
+   *
+   * @example
+   * import { shouldRouteToNext } from './src/lib/ecdn-matcher';
+   * hybridProxyPlugin({ routeMatcher: shouldRouteToNext, ... })
+   */
+  routeMatcher: (pathname: string, routingRules: string) => boolean;
+  /** SFCC Site ID (e.g., 'RefArchGlobal') */
+  siteId: string;
+  /** Locale for SFRA paths (e.g., 'en-GB'). Defaults to 'default' if not provided. */
+  locale?: string;
+}
+/**
+ * Vite plugin for hybrid proxying between Storefront Next and legacy SFRA.
+ *
+ * Uses http-proxy to silently forward non-matching requests to SFCC without visible
+ * redirects. Rewrites Set-Cookie headers, Location headers, and HTML/JSON response
+ * bodies to keep all navigation within the localhost proxy.
+ *
+ * Routing decisions are delegated to the `routeMatcher` callback injected via options,
+ * keeping the SDK free of template-specific routing logic.
+ *
+ * @param options - Plugin configuration
+ * @returns Vite plugin
+ */
+declare function hybridProxyPlugin(options: HybridProxyPluginOptions): Plugin;
+//#endregion
+//#region src/plugins/ecdnMatcher.d.ts
+/**
+ * Copyright 2026 Salesforce, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Extracts regex patterns from a Cloudflare routing expression.
+ *
+ * Parses Cloudflare "matches" expressions like:
+ *   (http.request.uri.path matches "^/$" or http.request.uri.path matches "^/category.*")
+ *
+ * And extracts the regex patterns: ["^/$", "^/category.*"]
+ *
+ * @param expression - Cloudflare expression string
+ * @returns Array of regex pattern strings
+ *
+ * @example
+ * ```typescript
+ * extractPatterns('(http.request.uri.path matches "^/$")');
+ * // Returns: ["^/$"]
+ *
+ * extractPatterns('(http.request.uri.path matches "^/$" or http.request.uri.path matches "^/search.*")');
+ * // Returns: ["^/$", "^/search.*"]
+ * ```
+ */
+declare function extractPatterns(expression: string): string[];
+/**
+ * Tests if a pathname matches any of the provided regex patterns (logical OR).
+ * Uses caching to optimize repeated pattern compilations.
+ *
+ * @param pathname - URL pathname to test (e.g., "/search", "/category/shoes")
+ * @param patterns - Array of regex pattern strings
+ * @returns true if pathname matches any pattern, false otherwise
+ *
+ * @example
+ * ```typescript
+ * testPatterns('/category/shoes', ['^/category.*', '^/search.*']);
+ * // Returns: true (matches first pattern)
+ *
+ * testPatterns('/checkout', ['^/category.*', '^/search.*']);
+ * // Returns: false (matches no patterns)
+ * ```
+ */
+declare function testPatterns(pathname: string, patterns: string[]): boolean;
+/**
+ * Main function: Determines if a pathname should route to Storefront Next
+ * or be proxied/redirected to SFRA/legacy backend.
+ *
+ * @param pathname - URL pathname (e.g., "/search", "/checkout")
+ * @param routingRules - Cloudflare routing expression string (optional)
+ * @returns true if should route to Storefront Next, false if should proxy to SFRA
+ *
+ * @example
+ * ```typescript
+ * const rules = '(http.request.uri.path matches "^/$" or http.request.uri.path matches "^/category.*")';
+ *
+ * shouldRouteToNext('/', rules);              // true - route to Next
+ * shouldRouteToNext('/category/mens', rules); // true - route to Next
+ * shouldRouteToNext('/checkout', rules);      // false - proxy to SFRA
+ * shouldRouteToNext('/any-path', undefined);  // true - no rules = default to Next
+ * ```
+ */
+declare function shouldRouteToNext(pathname: string, routingRules?: string): boolean;
+/**
+ * Clears the regex cache. Useful for testing or when routing rules change.
+ *
+ * @example
+ * ```typescript
+ * clearCache();
+ * // All cached regex patterns are removed
+ * ```
+ */
+declare function clearCache(): void;
+//#endregion
 //#region src/server/config.d.ts
 /**
  * Server configuration extracted from environment variables
@@ -158,7 +273,6 @@ interface ServerConfig {
       shortCode: string;
       organizationId: string;
       clientId: string;
-      siteId: string;
       proxy: string;
       proxyHost?: string;
     };
@@ -268,7 +382,7 @@ declare const ExtensionConfig: {
 //#endregion
 //#region src/extensibility/trim-extensions.d.ts
 type ExtensionsSelection = Record<string, boolean>;
-declare function trimExtensions(directory: string, selectedExtensions?: Partial<ExtensionsSelection>, extensionConfig?: typeof ExtensionConfig, verboseOverride?: boolean): void;
+declare function trimExtensions(directory: string, selectedExtensions?: Partial<ExtensionsSelection>, extensionConfig?: typeof ExtensionConfig): void;
 //#endregion
 //#region src/cartridge-services/generate-cartridge.d.ts
 /**
@@ -303,5 +417,5 @@ interface GenerateMetadataResult {
 }
 declare function generateMetadata(projectDirectory: string, metadataDirectory: string, options?: GenerateMetadataOptions): Promise<GenerateMetadataResult>;
 //#endregion
-export { type GenerateMetadataOptions, type GenerateMetadataResult, type StorefrontNextTargetsConfig, createServer, storefrontNextTargets as default, generateMetadata, loadConfigFromEnv, loadProjectConfig, transformTargetPlaceholderPlugin, trimExtensions };
+export { type GenerateMetadataOptions, type GenerateMetadataResult, type HybridProxyPluginOptions, type StorefrontNextTargetsConfig, clearCache, createServer, storefrontNextTargets as default, extractPatterns, generateMetadata, hybridProxyPlugin, loadConfigFromEnv, loadProjectConfig, shouldRouteToNext, testPatterns, transformTargetPlaceholderPlugin, trimExtensions };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":["ExtensionMeta","ExtensionConfig","Record","default"],"sources":["../src/plugins/staticRegistry.ts","../src/plugins/eventInstrumentationValidator.ts","../src/storefront-next-targets.ts","../src/plugins/transformTargets.ts","../src/server/config.ts","../src/server/modes.ts","../src/server/index.ts","../src/extensibility/extension-config.d.ts","../src/extensibility/trim-extensions.ts","../src/cartridge-services/generate-cartridge.ts"],"sourcesContent":["/**\n * Copyright 2026 Salesforce, Inc.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\nexport type ExtensionMeta = {\n    name: string;\n    description: string;\n    installationInstructions: string;\n    uninstallationInstructions: string;\n    folder: string;\n    dependencies: string[];\n    defaultOn?: boolean;\n};\n\ndeclare const ExtensionConfig: {\n    extensions: Record<string, ExtensionMeta>;\n};\n\nexport default ExtensionConfig;\n"],"mappings":";;;;;;;AMkDA;;;AAQa,UNLI,0BAAA,CMKJ;EAMF;;;;EAYW,aAAA,CAAA,EAAY,MAAA;EAAU;;;;;;;EC7DhCA;AAQV;;;;ECGG;AAA4B;;;EAWJ,WAAA,CAAA,EAAA,OAAA;EAAe;;;;ECmpB3B,OAAA,CAAA,EAAA,OAAA;AAwBjB;;;;;;;ANtrBgB,UFFC,mCAAA,CEWc;;;;ACb/B;EAqBgB,UAAA,CAAA,EAAA,MAAA;EAyDM;;;;ECrFV,SAAA,CAAA,EAAA,MAAU,EAAA;EAKL;;;;EC8BA,aAAA,CAAA,EAAc,OAAA;EAAgB;;;;EAiBnC,OAAA,CAAA,EAAA,OAAA;;;;;;AHzCZ;;UDQiB,2BAAA;;AEZjB;AAqBA;AAyDA;;;;ACrFA;AAKA;;;;AC8BA;;;;;;;;AA0BA;;;EAA4D,kBAAA,CAAA,EAAA,OAAA;EAAO;;;;AC7DnE;AAQE;;;mBL6CmB;EM1ChB;AAA4B;;;;;;;kCNoDG;AO0mBpC;AAwBA;AA8CA;;;;;;;;;;;;;;;;;;iBP1pBgB,qBAAA,UAA8B,8BAAmC;;;iBC1EjE,gCAAA,CAAA;;;yBASe;;EHkBd,SAAA,CAAA,IAAA,EAAA,MAAA,EAAA,EAAA,EAAA,MAA0B,CAAA,EAAA;;;;AC7B3C,CAAA;;;;;;UGFiB,YAAA;;;MJ+BA,SAAA,EAAA,MAAA;;;;MC7BA,KAAA,EAAA,MAAA;;;;ACUjB;AAkEA;;;;AC1EA;;;;ACJiB,iBAqBD,iBAAA,CAAA,CArBa,EAqBQ,YArBR;AAqB7B;AAyDA;;;;ACrFA;AAKA;iBDgFsB,iBAAA,4BAA6C,QAAQ;;;;;;;;;AJ/C3E;;;;AC7BA;;;;ACUA;AAkEgB,KGrFJ,UAAA,GHqFI,aAAqB,GAAS,SAAA,GAAA,YAAA;;;;AC1E9B,UENC,kBAAA,CFMD;;;;ECJC,mBAAY,EAAA,OAAA;EAqBb;EAyDM,iBAAA,EAAA,OAAiB;;;;ECrF3B,sBAAU,EAAA,OAAA;AAKtB;;;UC8BiB,aAAA,SAAsB,QAAQ;;QAErC;EF9BO;EAqBD,gBAAA,CAAA,EAAA,MAAiB;EAyDX;WE1CT;;;ED3CD;EAKK,IAAA,CAAA,EC4CN,aD5CM;;UC+CL;;EAjBK,SAAA,CAAA,EAAA,OAAc;;;;;AAiBnB,iBASU,YAAA,CATV,OAAA,EASgC,aAThC,CAAA,EASgD,OAThD,CASwD,OATxD,CAAA;;;;;;;;;ANdZ;;;;AC7BA;;;;ACUA;AAkEgB,KKrFJA,aAAAA,GLqFyB;;;;EC1ErB,0BAAA,EAAA,MAAA;;;;ACJhB,CAAA;AA8EA,cG3EcC,eH2EyB,EAAA;cG1EvBC,eAAeF;;;;KCA1B,mBAAA,GAAsB;iBAQH,cAAA,yCAEC,QAAQ,+CACJ;;;;;;ARgBZ,USmoBA,uBAAA,CTnoB0B;;;;AC7B3C;;;;ACUA;AAkEA;;;;AC1EA;;;;ACJA;AAqBA;AAyDA;;UK4mBiB,sBAAA;;EJjsBL,kBAAU,EAAA,MAAA;EAKL,gBAAA,EAAA,MAAkB;;;iBI0uBb,gBAAA,gEAGR,0BACX,QAAQ"}
+{"version":3,"file":"index.d.ts","names":["ExtensionMeta","ExtensionConfig","Record","default"],"sources":["../src/plugins/staticRegistry.ts","../src/plugins/eventInstrumentationValidator.ts","../src/storefront-next-targets.ts","../src/plugins/transformTargets.ts","../src/plugins/hybridProxy.ts","../src/plugins/ecdnMatcher.ts","../src/server/config.ts","../src/server/modes.ts","../src/server/index.ts","../src/extensibility/extension-config.d.ts","../src/extensibility/trim-extensions.ts","../src/cartridge-services/generate-cartridge.ts"],"sourcesContent":["/**\n * Copyright 2026 Salesforce, Inc.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\nexport type ExtensionMeta = {\n    name: string;\n    description: string;\n    installationInstructions: string;\n    uninstallationInstructions: string;\n    folder: string;\n    dependencies: string[];\n    defaultOn?: boolean;\n};\n\ndeclare const ExtensionConfig: {\n    extensions: Record<string, ExtensionMeta>;\n};\n\nexport default ExtensionConfig;\n"],"mappings":"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"}