@salesforce/storefront-next-dev 1.3.2 → 1.4.0-alpha.0

package/README.md

@@ -149,18 +149,31 @@ Run `pnpm sfnext push --help` to see all available options:
 
 - `-b, --build-directory <dir>`: Build directory to push (default: auto-detected)
 - `-m, --message <message>`: Bundle message (default: git branch:commit)
-- `-p, --project <slug>`: Project slug - the unique identifier for your project on Managed Runtime
-- `-e, --environment <target>`: Deploy target environment on Managed Runtime
+- `-p, --project <slug>` (alias `-s, --storefront`): Project slug on Managed Runtime (env: `MRT_PROJECT`)
+- `-e, --environment <env>` (alias `-t, --target`): Environment to deploy to (env: `MRT_ENVIRONMENT`; `MRT_TARGET` also accepted)
 - `-w, --wait`: Wait for deployment to complete
-- `--cloud-origin <origin>`: API origin (default: https://cloud.mobify.com)
-- `--credentials-file <file>`: Credentials file location
-- `--api-key <api-key>`: MRT API key
+- `--mrt-backend <legacy|scapi|auto>`: MRT API to use (env: `MRT_BACKEND`, default `legacy`). See [MRT backends](#mrt-backends).
+- `--api-key <api-key>`: MRT API key (legacy backend; env: `MRT_API_KEY`)
+- `-u, --cloud-origin <origin>` (alias `-o`): MRT API origin (legacy backend; default: https://cloud.mobify.com)
+- `-c, --credentials-file <file>`: Credentials file location (legacy backend; default: `~/.mobify`)
 
-Backward compatibility:
+`--project-slug` is still accepted as a deprecated alias for `--project`.
 
-- `--project-slug` is supported as a deprecated alias for `--project`
-- `--target` is supported as a deprecated alias for `--environment`
-- `MRT_PROJECT` and `MRT_TARGET` are supported as fallback env vars for `project` and `environment`
+#### MRT backends
+
+`push` and `config inspect` can talk to Managed Runtime through either API:
+
+| `--mrt-backend` | Behavior |
+| --- | --- |
+| `legacy` (default) | MRT Cloud API with an MRT API key. |
+| `scapi` | SCAPI with Account Manager OAuth. Errors if the prerequisites are missing. |
+| `auto` | SCAPI when its prerequisites are configured, otherwise legacy. Falls back to legacy on safe pre-request errors. |
+
+The SCAPI backend needs `SFCC_CLIENT_ID`, `SFCC_CLIENT_SECRET`, `SFCC_SHORTCODE`, and `SFCC_TENANT_ID`, and an API client with the `sfcc.storefront.deployments.rw` scope (`push`) or `sfcc.storefront.environments` (`config inspect`). See [MRT Backends](https://salesforcecommercecloud.github.io/b2c-developer-tooling/cli/mrt.html#mrt-backends).
+
+#### Deploy cartridge
+
+`deploy-cartridge` looks up and reloads the active code version through SCAPI (`sfcc.scripts` / `sfcc.scripts.rw` scopes) when `SFCC_SHORTCODE` and `SFCC_TENANT_ID` are set, and falls back to OCAPI otherwise. Force one with `--api-backend scapi|ocapi` (env: `SFCC_API_BACKEND`).
 
 #### Manage extensions
 

package/dist/bundle.js

@@ -9,6 +9,20 @@ import archiver from "archiver";
 /**
 * Create a bundle from the build directory
 */
+/**
+* Dependencies recorded in bundle metadata: the project's declared dependencies
+* plus the resolved versions of PWA Kit / Storefront Next packages.
+*/
+const getBundleDependencies = (projectDirectory) => {
+	const { dependencies = {}, devDependencies = {} } = getProjectPkg(projectDirectory);
+	const dependencyTree = getProjectDependencyTree(projectDirectory);
+	const pwaKitDeps = dependencyTree ? getPwaKitDependencies(dependencyTree) : {};
+	return {
+		...dependencies,
+		...devDependencies,
+		...pwaKitDeps
+	};
+};
 const createBundle = async (options) => {
 	const { message, ssr_parameters, ssr_only, ssr_shared, buildDirectory, projectDirectory, projectSlug } = options;
 	const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "storefront-next-dev-push-"));
@@ -38,14 +52,7 @@ const createBundle = async (options) => {
 		archive.on("error", reject);
 		output.on("finish", () => {
 			try {
-				const { dependencies = {}, devDependencies = {} } = getProjectPkg(projectDirectory);
-				const dependencyTree = getProjectDependencyTree(projectDirectory);
-				const pwaKitDeps = dependencyTree ? getPwaKitDependencies(dependencyTree) : {};
-				const bundle_metadata = { dependencies: {
-					...dependencies,
-					...devDependencies,
-					...pwaKitDeps
-				} };
+				const bundle_metadata = { dependencies: getBundleDependencies(projectDirectory) };
 				const data = fs.readFileSync(destination);
 				const encoding = "base64";
 				fs.rmSync(tmpDir, { recursive: true });
@@ -80,4 +87,4 @@ const createBundle = async (options) => {
 };
 
 //#endregion
-export { createBundle as t };
+export { getBundleDependencies as n, createBundle as t };

package/dist/cartridge-services/index.js

@@ -19,6 +19,27 @@ const LEVEL_PRIORITY = {
 	info: 2,
 	debug: 3
 };
+/**
+* Type guard for a {@link LogLevel} name. Uses `Object.hasOwn` (not `in`) so
+* inherited properties like `toString` don't falsely validate an env value.
+*/
+function isLogLevel(value) {
+	return Object.hasOwn(LEVEL_PRIORITY, value);
+}
+/**
+* Managed Runtime injects `MRT_LOG_LEVEL` as a numeric string from its own
+* `LogLevel` enum (`0=TRACE, 1=DEBUG, 2=INFO, 3=WARN, 4=ERROR, 5=FATAL`), not a
+* level name — so it must be mapped, not matched against {@link LEVEL_PRIORITY}'s
+* keys. `TRACE` and `FATAL` clamp to the closest level this logger supports.
+*/
+const MRT_NUMERIC_TO_LEVEL = {
+	"0": "debug",
+	"1": "debug",
+	"2": "info",
+	"3": "warn",
+	"4": "error",
+	"5": "error"
+};
 let overrideLevel;
 /**
 * Returns true when the `DEBUG` env var targets sfnext or is a general enable flag.
@@ -42,8 +63,10 @@ function debugEnablesSfnext() {
 }
 function resolveLevel() {
 	if (overrideLevel) return overrideLevel;
-	const envLevel = process.env.MRT_LOG_LEVEL ?? process.env.SFCC_LOG_LEVEL;
-	if (envLevel && envLevel in LEVEL_PRIORITY) return envLevel;
+	const mrtLevel = process.env.MRT_LOG_LEVEL;
+	if (mrtLevel && mrtLevel in MRT_NUMERIC_TO_LEVEL) return MRT_NUMERIC_TO_LEVEL[mrtLevel];
+	const sfccLevel = process.env.SFCC_LOG_LEVEL;
+	if (sfccLevel && isLogLevel(sfccLevel)) return sfccLevel;
 	if (debugEnablesSfnext()) return "debug";
 	if (process.env.NODE_ENV === "production") return "warn";
 	return "info";
@@ -79,6 +102,23 @@ const logger = {
 //#endregion
 //#region src/cartridge-services/react-router-config.ts
 let isCliAvailable = null;
+function filePathEndsWithRoute(filePath, routeFile) {
+	const routeFileNormalized = routeFile.replace(/^\.\//, "");
+	return filePath === routeFileNormalized || filePath.endsWith(`/${routeFileNormalized}`);
+}
+/**
+* Match the selected vertical route shadow to its canonical route module.
+*
+* `VERTICAL` is optional and selects the overlay directory reported by React Router,
+* for example `furniture` for `verticals/furniture/routes/_app._index.tsx`.
+*/
+function routeFileMatches(filePath, routeFile) {
+	if (filePathEndsWithRoute(filePath, routeFile)) return true;
+	const vertical = process.env.VERTICAL;
+	const verticalRoutePrefix = vertical ? `verticals/${vertical}/routes/` : void 0;
+	if (!verticalRoutePrefix || !routeFile.startsWith(verticalRoutePrefix)) return false;
+	return filePathEndsWithRoute(filePath, `routes/${routeFile.slice(verticalRoutePrefix.length)}`);
+}
 function checkReactRouterCli(projectDirectory) {
 	if (isCliAvailable !== null) return isCliAvailable;
 	try {
@@ -132,7 +172,7 @@ function getReactRouterRoutes(projectDirectory) {
 * 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')
+* @returns The route path (e.g., '/cart', '/p/*')
 * @example
 * const route = filePathToRoute('/path/to/project/src/routes/_app.cart.tsx', '/path/to/project');
 * // Returns: '/cart'
@@ -140,10 +180,13 @@ function getReactRouterRoutes(projectDirectory) {
 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;
+	for (const route of canonicalRoutes) if (routeFileMatches(filePathPosix, route.file.replace(/\\/g, "/"))) {
+		const seoAliases = canonicalRoutes.filter((candidate) => candidate.id.startsWith(`${route.id}--seo-alias--`)).sort((left, right) => left.path.localeCompare(right.path));
+		if (seoAliases.length > 0) {
+			if (seoAliases.length > 1) logger.warn(`Multiple SEO route aliases match ${filePath}; using ${seoAliases[0].path} for Page Designer metadata.`);
+			return seoAliases[0].path;
+		}
+		return route.path;
 	}
 	logger.warn(`Could not find route for file: ${filePath}`);
 	return "/unknown";