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

package/dist/commands/deploy-cartridge.js

@@ -1,50 +1,91 @@
-import { i as SFNEXT_BASE_CARTRIDGE_OUTPUT_DIR, r as SFNEXT_BASE_CARTRIDGE_NAME, t as CARTRIDGES_BASE_DIR } from "../config.js";
+import { i as SFNEXT_BASE_CARTRIDGE_OUTPUT_DIR, t as CARTRIDGES_BASE_DIR } from "../config.js";
+import { Flags } from "@oclif/core";
 import path from "path";
 import fs from "fs-extra";
-import { InstanceCommand } from "@salesforce/b2c-tooling-sdk/cli";
-import { uploadCartridges } from "@salesforce/b2c-tooling-sdk/operations/code";
+import { CartridgeCommand } from "@salesforce/b2c-tooling-sdk/cli";
+import { deleteCartridges, getActiveCodeVersion, reloadCodeVersion, uploadCartridges } from "@salesforce/b2c-tooling-sdk/operations/code";
 
 //#region src/commands/deploy-cartridge.ts
 /**
-* Deploy cartridge command - deploys the Page Designer metadata cartridge to a B2C instance.
+* Deploy cartridge command - deploys cartridges to a B2C instance.
 *
-* Inherits all B2C instance flags from InstanceCommand:
-* - --server/-s: B2C instance hostname (env: SFCC_SERVER)
-* - --code-version/-v: Code version (env: SFCC_CODE_VERSION)
-* - --username/-u: Basic auth username (env: SFCC_USERNAME)
-* - --password/-p: Basic auth password (env: SFCC_PASSWORD)
-* - --client-id: OAuth client ID (env: SFCC_CLIENT_ID)
-* - --client-secret: OAuth client secret (env: SFCC_CLIENT_SECRET)
-* - --webdav-server: Separate WebDAV hostname (env: SFCC_WEBDAV_SERVER)
-* - --config: Path to dw.json config file (env: SFCC_CONFIG)
-* - --instance/-i: Named instance from config (env: SFCC_INSTANCE)
+* Extends CartridgeCommand which provides:
+* - All B2C instance flags (--server, --code-version, --username, --password, etc.)
+* - Cartridge filtering flags (-c/--cartridge, -x/--exclude-cartridge)
+* - Cartridge discovery with plugin provider support
+* - Config-driven cartridge filtering via dw.json `cartridges` option
+*
+* Additional flags:
+* - --delete: Delete existing cartridges before upload
+* - --reload/-r: Reload (re-activate) code version after deploy (requires OAuth)
 */
-var Deploy = class Deploy extends InstanceCommand {
-	static description = "Deploy cartridge to B2C Commerce Cloud instance";
+var Deploy = class Deploy extends CartridgeCommand {
+	static description = "Deploy cartridges to B2C Commerce Cloud instance";
 	static examples = [
 		"<%= config.bin %> <%= command.id %>",
 		"<%= config.bin %> <%= command.id %> --project-directory ./my-project",
 		"<%= config.bin %> <%= command.id %> -s my-sandbox.dx.commercecloud.salesforce.com",
-		"<%= config.bin %> <%= command.id %> --code-version staging"
+		"<%= config.bin %> <%= command.id %> --code-version staging",
+		"<%= config.bin %> <%= command.id %> --delete",
+		"<%= config.bin %> <%= command.id %> --delete --reload",
+		"<%= config.bin %> <%= command.id %> -c app_storefrontnext_base",
+		"<%= config.bin %> <%= command.id %> -x test_cartridge"
 	];
-	static flags = { ...InstanceCommand.baseFlags };
+	static flags = {
+		...CartridgeCommand.baseFlags,
+		...CartridgeCommand.cartridgeFlags,
+		reload: Flags.boolean({
+			char: "r",
+			description: "Reload (re-activate) code version after deploy",
+			default: false
+		}),
+		delete: Flags.boolean({
+			description: "Delete existing cartridges before upload",
+			default: false
+		})
+	};
 	async run() {
 		const { flags } = await this.parse(Deploy);
 		const projectDirectory = flags["project-directory"] || process.cwd();
 		if (!fs.existsSync(projectDirectory)) this.error(`Project directory doesn't exist: ${projectDirectory}`);
+		const cartridgesDir = path.join(projectDirectory, CARTRIDGES_BASE_DIR);
 		const metadataDir = path.join(projectDirectory, CARTRIDGES_BASE_DIR, SFNEXT_BASE_CARTRIDGE_OUTPUT_DIR);
 		if (!fs.existsSync(metadataDir)) this.error(`Metadata directory doesn't exist: ${metadataDir}. Run 'sfnext generate-cartridge' first.`);
 		this.requireServer();
-		this.requireCodeVersion();
 		this.requireWebDavCredentials();
-		const cartridges = [{
-			name: SFNEXT_BASE_CARTRIDGE_NAME,
-			src: path.join(projectDirectory, CARTRIDGES_BASE_DIR, SFNEXT_BASE_CARTRIDGE_NAME),
-			dest: SFNEXT_BASE_CARTRIDGE_NAME
-		}];
-		this.log(`Deploying cartridge "${SFNEXT_BASE_CARTRIDGE_NAME}" to code version "${this.resolvedConfig.values.codeVersion}"...`);
+		let version = this.resolvedConfig.values.codeVersion;
+		if ((!version || flags.reload) && !this.hasOAuthCredentials()) {
+			const reason = version ? "The --reload flag requires OAuth credentials to reload the code version via OCAPI." : "No code version specified. OAuth credentials are required to auto-discover the active code version.";
+			this.error(`${reason}\n\nProvide --code-version to use basic auth only, or configure OAuth credentials (--client-id and --client-secret).`);
+		}
+		if (!version) {
+			this.warn("No code version specified, discovering active code version...");
+			let activeVersion;
+			try {
+				activeVersion = await getActiveCodeVersion(this.instance);
+			} catch (error) {
+				this.error(`Failed to discover active code version: ${error instanceof Error ? error.message : String(error)}\n\nSpecify one explicitly with --code-version or in your dw.json config.`);
+			}
+			if (!activeVersion?.id) this.error("No active code version found. Specify one with --code-version or in your dw.json config.");
+			version = activeVersion.id;
+			this.instance.config.codeVersion = version;
+		}
+		const cartridges = await this.findCartridgesWithProviders(cartridgesDir);
+		if (cartridges.length === 0) this.error(`No cartridges found in ${cartridgesDir}`);
+		this.log(`Deploying to code version "${version}"...`);
+		for (const c of cartridges) this.log(`  ${c.name} (${c.src})`);
+		if (flags.delete) {
+			this.log("Deleting existing cartridges...");
+			await deleteCartridges(this.instance, cartridges);
+		}
 		await uploadCartridges(this.instance, cartridges);
-		this.log(`Code deployed to version "${this.resolvedConfig.values.codeVersion}" successfully!`);
+		if (flags.reload) try {
+			await reloadCodeVersion(this.instance, version);
+			this.log("Code version reloaded.");
+		} catch (error) {
+			this.warn(`Could not reload code version: ${error instanceof Error ? error.message : String(error)}`);
+		}
+		this.log(`Deployed ${cartridges.length} cartridge(s) to version "${version}" successfully!`);
 	}
 };
 

package/dist/commands/dev.js

@@ -1,6 +1,8 @@
-import { a as printServerInfo, i as printServerConfig, o as printShutdownMessage } from "../logger.js";
+import { i as printShutdownMessage, n as printServerConfig, r as printServerInfo } from "../logger.js";
+import "../logger2.js";
 import { c as loadEnvFile } from "../utils.js";
-import { n as getCommerceCloudApiUrl, r as loadProjectConfig, t as createServer$2 } from "../server.js";
+import { i as loadProjectConfig, n as initBasePathEnv, r as getCommerceCloudApiUrl, t as createServer$2 } from "../server.js";
+import "../config.js";
 import { t as commonFlags } from "../flags.js";
 import { Command, Flags } from "@oclif/core";
 import path from "path";
@@ -48,6 +50,7 @@ async function dev(options = {}) {
 	const port = options.port || 5173;
 	process.env.NODE_ENV = process.env.NODE_ENV ?? "development";
 	loadEnvFile(projectDir);
+	await initBasePathEnv(projectDir);
 	process.env.EXTERNAL_DOMAIN_NAME = process.env.EXTERNAL_DOMAIN_NAME ?? `localhost:${port}`;
 	const config = await loadProjectConfig(projectDir);
 	const httpServer = createServer();
@@ -79,8 +82,7 @@ async function dev(options = {}) {
 			proxyHost: getCommerceCloudApiUrl(config.commerce.api.shortCode, config.commerce.api.proxyHost),
 			shortCode: config.commerce.api.shortCode,
 			organizationId: config.commerce.api.organizationId,
-			clientId: config.commerce.api.clientId,
-			siteId: config.commerce.api.siteId
+			clientId: config.commerce.api.clientId
 		});
 	});
 	["SIGTERM", "SIGINT"].forEach((signal) => {

package/dist/commands/extensions/create.js

@@ -1,3 +1,5 @@
+import "../../logger.js";
+import "../../logger2.js";
 import "../../dependency-utils.js";
 import { t as createExtension } from "../../manage-extensions.js";
 import { Command, Flags } from "@oclif/core";

package/dist/commands/extensions/install.js

@@ -1,3 +1,5 @@
+import "../../logger.js";
+import "../../logger2.js";
 import "../../dependency-utils.js";
 import { t as commonFlags } from "../../flags.js";
 import { r as manageExtensions } from "../../manage-extensions.js";
@@ -21,11 +23,6 @@ var Install = class Install extends Command {
 			char: "s",
 			description: "Git URL of the source template project",
 			default: DEFAULT_TEMPLATE_GIT_URL
-		}),
-		verbose: Flags.boolean({
-			char: "v",
-			description: "Verbose mode",
-			default: false
 		})
 	};
 	async run() {
@@ -34,8 +31,7 @@ var Install = class Install extends Command {
 			projectDirectory: flags["project-directory"],
 			install: true,
 			extensions: flags.extension ? [flags.extension] : void 0,
-			sourceGitUrl: flags["source-git-url"],
-			verbose: flags.verbose
+			sourceGitUrl: flags["source-git-url"]
 		});
 	}
 };

package/dist/commands/extensions/list.js

@@ -1,3 +1,5 @@
+import "../../logger.js";
+import "../../logger2.js";
 import "../../dependency-utils.js";
 import { t as commonFlags } from "../../flags.js";
 import { n as listExtensions } from "../../manage-extensions.js";

package/dist/commands/extensions/remove.js

@@ -1,3 +1,5 @@
+import "../../logger.js";
+import "../../logger2.js";
 import "../../dependency-utils.js";
 import { t as commonFlags } from "../../flags.js";
 import { r as manageExtensions } from "../../manage-extensions.js";
@@ -15,11 +17,6 @@ var Remove = class Remove extends Command {
 		extensions: Flags.string({
 			char: "e",
 			description: "Comma-separated list of extension marker values (e.g. SFDC_EXT_STORE_LOCATOR,SFDC_EXT_THEME_SWITCHER)"
-		}),
-		verbose: Flags.boolean({
-			char: "v",
-			description: "Verbose mode",
-			default: false
 		})
 	};
 	async run() {
@@ -28,8 +25,7 @@ var Remove = class Remove extends Command {
 		await manageExtensions({
 			projectDirectory: flags["project-directory"],
 			uninstall: true,
-			extensions,
-			verbose: flags.verbose
+			extensions
 		});
 	}
 };

package/dist/commands/generate-cartridge.js

@@ -1,9 +1,13 @@
-import { t as commonFlags } from "../flags.js";
+import "../logger.js";
+import "../logger2.js";
 import { i as SFNEXT_BASE_CARTRIDGE_OUTPUT_DIR, t as CARTRIDGES_BASE_DIR } from "../config.js";
+import { t as commonFlags } from "../flags.js";
 import { t as generateMetadata } from "../generate-cartridge.js";
+import { t as validateCartridgeMetadata } from "../validate-cartridge.js";
 import { Command } from "@oclif/core";
 import path from "path";
 import fs from "fs-extra";
+import chalk from "chalk";
 
 //#region src/commands/generate-cartridge.ts
 /**
@@ -27,7 +31,24 @@ var Generate = class Generate extends Command {
 		}
 		this.log("Generating Page Designer metadata...");
 		await generateMetadata(projectDirectory, metadataDir);
-		this.log("Page Designer metadata generated successfully!");
+		this.log("Page Designer metadata generated successfully!\n");
+		this.log("Validating generated metadata...\n");
+		const summary = await validateCartridgeMetadata(metadataDir);
+		for (const skipped of summary.skippedFiles) this.warn(`Skipping unrecognized file: ${skipped}`);
+		for (const result of summary.results) {
+			const relativePath = path.relative(metadataDir, result.filePath ?? "");
+			const typeInfo = result.schemaType ? ` (${result.schemaType})` : "";
+			if (result.valid) this.log(`${chalk.green("PASS")}: ${relativePath}${typeInfo}`);
+			else {
+				this.log(`${chalk.red("FAIL")}: ${relativePath}${typeInfo}`);
+				for (const error of result.errors) {
+					const location = error.path && error.path !== "/" ? ` at ${error.path}` : "";
+					this.log(`  ${chalk.red("ERROR")}${location}: ${error.message}`);
+				}
+			}
+		}
+		this.log(`\n${summary.validFiles}/${summary.totalFiles} file(s) valid, ${summary.totalErrors} error(s)`);
+		if (summary.totalErrors > 0) this.error("Generated metadata has validation errors", { exit: 1 });
 	}
 };
 

package/dist/commands/preview.js

@@ -1,6 +1,8 @@
-import { a as printServerInfo, c as warn, i as printServerConfig, n as error, o as printShutdownMessage, r as info } from "../logger.js";
+import { i as printShutdownMessage, n as printServerConfig, r as printServerInfo, t as logger } from "../logger.js";
+import "../logger2.js";
 import { c as loadEnvFile } from "../utils.js";
-import { n as getCommerceCloudApiUrl, r as loadProjectConfig, t as createServer } from "../server.js";
+import { i as loadProjectConfig, n as initBasePathEnv, r as getCommerceCloudApiUrl, t as createServer } from "../server.js";
+import "../config.js";
 import { t as commonFlags } from "../flags.js";
 import { Command, Flags } from "@oclif/core";
 import { execSync } from "child_process";
@@ -13,32 +15,36 @@ import { pathToFileURL } from "url";
 * Start the preview server with production build
 */
 async function preview(options = {}) {
+	process.setSourceMapsEnabled(true);
+	process.env.NODE_OPTIONS = [process.env.NODE_OPTIONS, "--enable-source-maps"].filter(Boolean).join(" ");
 	const startTime = Date.now();
 	const projectDir = path.resolve(options.projectDirectory || process.cwd());
 	const port = options.port || 3e3;
 	process.env.NODE_ENV = process.env.NODE_ENV ?? "production";
 	process.env.EXTERNAL_DOMAIN_NAME = process.env.EXTERNAL_DOMAIN_NAME ?? `localhost:${port}`;
 	loadEnvFile(projectDir);
+	await initBasePathEnv(projectDir);
 	const buildPath = path.join(projectDir, "build", "server", "index.js");
 	if (!fs.existsSync(buildPath)) {
-		warn("Production build not found. Building project...");
-		info("Running: pnpm build");
+		logger.warn("Production build not found. Building project...");
+		logger.info("Running: pnpm build");
 		try {
 			execSync("pnpm build", {
 				cwd: projectDir,
 				stdio: "inherit"
 			});
-			info("Build completed successfully");
+			logger.info("Build completed successfully");
 		} catch (err) {
-			error(`Build failed: ${err instanceof Error ? err.message : String(err)}`);
+			const errorMsg = err instanceof Error ? err.message : String(err);
+			logger.error(`Build failed: ${errorMsg}`);
 			process.exit(1);
 		}
 		if (!fs.existsSync(buildPath)) {
-			error(`Build still not found at ${buildPath} after running build command`);
+			logger.error(`Build still not found at ${buildPath} after running build command`);
 			process.exit(1);
 		}
 	}
-	info(`Loading production build from ${buildPath}`);
+	logger.info(`Loading production build from ${buildPath}`);
 	const build = (await import(pathToFileURL(buildPath).href)).default;
 	const config = await loadProjectConfig(projectDir);
 	const server = (await createServer({
@@ -59,8 +65,7 @@ async function preview(options = {}) {
 			proxyHost: getCommerceCloudApiUrl(config.commerce.api.shortCode),
 			shortCode: config.commerce.api.shortCode,
 			organizationId: config.commerce.api.organizationId,
-			clientId: config.commerce.api.clientId,
-			siteId: config.commerce.api.siteId
+			clientId: config.commerce.api.clientId
 		});
 	});
 	["SIGTERM", "SIGINT"].forEach((signal) => {

package/dist/commands/push.js

@@ -1,13 +1,13 @@
 import "../logger.js";
+import "../logger2.js";
 import { n as getDefaultBuildDir, r as getDefaultMessage } from "../utils.js";
-import { t as createBundle } from "../bundle.js";
 import { a as buildMrtConfig, i as SFNEXT_BASE_CARTRIDGE_OUTPUT_DIR, n as GENERATE_AND_DEPLOY_CARTRIDGE_ON_MRT_PUSH, r as SFNEXT_BASE_CARTRIDGE_NAME, t as CARTRIDGES_BASE_DIR } from "../config.js";
+import { t as createBundle } from "../bundle.js";
 import { t as generateMetadata } from "../generate-cartridge.js";
 import { Flags } from "@oclif/core";
 import path from "path";
 import fs from "fs-extra";
 import { MrtCommand } from "@salesforce/b2c-tooling-sdk/cli";
-import { resolveConfig } from "@salesforce/b2c-tooling-sdk/config";
 import { uploadCartridges } from "@salesforce/b2c-tooling-sdk/operations/code";
 import { uploadBundle, waitForEnv } from "@salesforce/b2c-tooling-sdk/operations/mrt";
 import { DEFAULT_MRT_ORIGIN, createMrtClient } from "@salesforce/b2c-tooling-sdk/clients";
@@ -17,10 +17,10 @@ import { DEFAULT_MRT_ORIGIN, createMrtClient } from "@salesforce/b2c-tooling-sdk
 * MRT Push command - builds and pushes bundle to Managed Runtime.
 *
 * Inherits MRT flags from MrtCommand:
-* - --api-key: MRT API key (env: SFCC_MRT_API_KEY)
-* - --project/-p: MRT project slug (env: SFCC_MRT_PROJECT)
-* - --environment/-e: MRT target environment (env: SFCC_MRT_ENVIRONMENT)
-* - --cloud-origin: MRT cloud origin URL (env: SFCC_MRT_CLOUD_ORIGIN)
+* - --api-key: MRT API key (env: MRT_API_KEY, fallback: SFCC_MRT_API_KEY)
+* - --project/-p: MRT project slug (env: MRT_PROJECT, fallback: SFCC_MRT_PROJECT)
+* - --environment/-e: MRT target environment (env: MRT_TARGET, fallback: SFCC_MRT_ENVIRONMENT)
+* - --cloud-origin: MRT cloud origin URL (env: MRT_CLOUD_ORIGIN, fallback: SFCC_MRT_CLOUD_ORIGIN)
 * - --credentials-file: Path to MRT credentials file (env: MRT_CREDENTIALS_FILE)
 * - --config: Path to dw.json config file (env: SFCC_CONFIG)
 * - --instance/-i: Named instance from config (env: SFCC_INSTANCE)
@@ -65,16 +65,16 @@ var Push = class Push extends MrtCommand {
 		if (flags["project-slug"]) this.warn("Flag --project-slug is deprecated. Use --project instead.");
 		if (flags.target) this.warn("Flag --target is deprecated. Use --environment instead.");
 		const target = flags.environment || flags.target || this.resolvedConfig.values.mrtEnvironment;
-		if (flags.wait && !target) this.error("You must provide a target environment when using --wait (via --environment flag, SFCC_MRT_ENVIRONMENT env var, or dw.json)");
+		if (flags.wait && !target) this.error("You must provide a target environment when using --wait (via --environment flag, MRT_TARGET env var, or dw.json)");
 		if (!fs.existsSync(projectDirectory)) this.error(`Project directory "${projectDirectory}" does not exist!`);
 		const projectSlug = flags.project || flags["project-slug"] || this.resolvedConfig.values.mrtProject;
-		if (!projectSlug || projectSlug.trim() === "") this.error("Project slug is required. Provide --project, set SFCC_MRT_PROJECT env var, or configure mrtProject in dw.json");
+		if (!projectSlug || projectSlug.trim() === "") this.error("Project slug is required. Provide --project, set MRT_PROJECT env var, or configure mrtProject in dw.json");
 		const buildDirectory = flags["build-directory"] ?? getDefaultBuildDir(projectDirectory);
 		if (!fs.existsSync(buildDirectory)) this.error(`Build directory "${buildDirectory}" does not exist!`);
 		if (GENERATE_AND_DEPLOY_CARTRIDGE_ON_MRT_PUSH) await this.generateAndDeployCartridge(projectDirectory);
 		if (target) process.env.DEPLOY_TARGET = target;
 		this.requireMrtCredentials();
-		const config = buildMrtConfig(buildDirectory, projectDirectory);
+		const config = await buildMrtConfig(buildDirectory, projectDirectory);
 		const message = flags.message ?? getDefaultMessage(projectDirectory);
 		this.log(`Creating bundle for project: ${projectSlug}`);
 		if (target) this.log(`Target environment: ${target}`);
@@ -89,18 +89,25 @@ var Push = class Push extends MrtCommand {
 		});
 		const origin = this.resolvedConfig.values.mrtOrigin || DEFAULT_MRT_ORIGIN;
 		const client = createMrtClient({ origin }, this.getMrtAuth());
-		this.log(`Beginning upload to ${origin}`);
+		this.log(`Uploading bundle to ${origin}`);
 		const result = await uploadBundle(client, projectSlug, bundle, target);
+		this.log(`Bundle ${result.bundleId} uploaded`);
 		if (flags.wait && target) {
-			this.log("Bundle uploaded - waiting for deployment to complete");
+			this.log(`Waiting for deployment to ${target}...`);
+			let lastState = "";
 			await waitForEnv({
 				projectSlug,
 				slug: target,
-				origin
+				origin,
+				onPoll: (info) => {
+					if (info.state !== lastState) {
+						lastState = info.state;
+						this.log(`  ${target}: ${info.state} (${info.elapsedSeconds}s)`);
+					}
+				}
 			}, this.getMrtAuth());
-			this.log("Deployment complete!");
-		} else this.log("Bundle uploaded successfully!");
-		this.log(`Bundle ID: ${result.bundleId}`);
+			this.log(`Deployment complete — bundle ${result.bundleId} is live on ${target}`);
+		}
 	}
 	/**
 	* Generate and deploy cartridge metadata to B2C instance.
@@ -114,16 +121,15 @@ var Push = class Push extends MrtCommand {
 			await generateMetadata(projectDirectory, metadataDir);
 			this.log("Cartridge metadata generated successfully!");
 			this.log("Deploying cartridge to Commerce Cloud...");
-			const b2cConfig = resolveConfig({}, { workingDirectory: projectDirectory });
-			if (!b2cConfig.hasB2CInstanceConfig()) {
+			if (!this.resolvedConfig.hasB2CInstanceConfig()) {
 				this.warn("B2C instance not configured, skipping cartridge deployment");
 				return;
 			}
-			if (!b2cConfig.values.codeVersion) {
+			if (!this.resolvedConfig.values.codeVersion) {
 				this.warn("Code version not configured, skipping cartridge deployment");
 				return;
 			}
-			await uploadCartridges(b2cConfig.createB2CInstance(), [{
+			await uploadCartridges(this.resolvedConfig.createB2CInstance(), [{
 				name: SFNEXT_BASE_CARTRIDGE_NAME,
 				src: path.join(projectDirectory, CARTRIDGES_BASE_DIR, SFNEXT_BASE_CARTRIDGE_NAME),
 				dest: SFNEXT_BASE_CARTRIDGE_NAME

package/dist/commands/validate-cartridge.js

@@ -0,0 +1,51 @@
+import { i as SFNEXT_BASE_CARTRIDGE_OUTPUT_DIR, t as CARTRIDGES_BASE_DIR } from "../config.js";
+import { t as commonFlags } from "../flags.js";
+import { t as validateCartridgeMetadata } from "../validate-cartridge.js";
+import { Command } from "@oclif/core";
+import path from "path";
+import fs from "fs-extra";
+import chalk from "chalk";
+
+//#region src/commands/validate-cartridge.ts
+/**
+* Validate cartridge metadata command.
+*
+* Validates all Page Designer metadata JSON files in the cartridge
+* directory against their metadefinition schemas.
+*/
+var ValidateCartridge = class ValidateCartridge extends Command {
+	static description = "Validate Page Designer metadata JSON files against schemas";
+	static examples = ["<%= config.bin %> <%= command.id %>", "<%= config.bin %> <%= command.id %> -d ./my-project"];
+	static flags = { ...commonFlags };
+	async run() {
+		const { flags } = await this.parse(ValidateCartridge);
+		const projectDirectory = flags["project-directory"];
+		if (!fs.existsSync(projectDirectory)) this.error(`Project directory doesn't exist: ${projectDirectory}`);
+		const metadataDir = path.join(projectDirectory, CARTRIDGES_BASE_DIR, SFNEXT_BASE_CARTRIDGE_OUTPUT_DIR);
+		if (!fs.existsSync(metadataDir)) this.error(`Metadata directory doesn't exist: ${metadataDir}\nRun "sfnext generate-cartridge" first to generate metadata files.`);
+		this.log("Validating Page Designer metadata...\n");
+		const summary = await validateCartridgeMetadata(metadataDir);
+		if (summary.totalFiles === 0) {
+			this.warn("No metadata files found to validate.");
+			return;
+		}
+		for (const skipped of summary.skippedFiles) this.warn(`Skipping unrecognized file: ${skipped}`);
+		for (const result of summary.results) {
+			const relativePath = path.relative(metadataDir, result.filePath ?? "");
+			const typeInfo = result.schemaType ? ` (${result.schemaType})` : "";
+			if (result.valid) this.log(`${chalk.green("PASS")}: ${relativePath}${typeInfo}`);
+			else {
+				this.log(`${chalk.red("FAIL")}: ${relativePath}${typeInfo}`);
+				for (const error of result.errors) {
+					const location = error.path && error.path !== "/" ? ` at ${error.path}` : "";
+					this.log(`  ${chalk.red("ERROR")}${location}: ${error.message}`);
+				}
+			}
+		}
+		this.log(`\n${summary.validFiles}/${summary.totalFiles} file(s) valid, ${summary.totalErrors} error(s)`);
+		if (summary.totalErrors > 0) this.error("Validation failed", { exit: 1 });
+	}
+};
+
+//#endregion
+export { ValidateCartridge as default };

package/dist/config.js

@@ -1,3 +1,6 @@
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+
 //#region src/mrt/utils.ts
 const MRT_BUNDLE_TYPE_SSR = "ssr";
 const MRT_STREAMING_ENTRY_FILE = "streamingHandler";
@@ -29,59 +32,83 @@ const SFNEXT_BASE_CARTRIDGE_OUTPUT_DIR = `${SFNEXT_BASE_CARTRIDGE_NAME}/cartridg
 */
 const GENERATE_AND_DEPLOY_CARTRIDGE_ON_MRT_PUSH = false;
 /**
-* Build MRT SSR configuration for bundle deployment
+* Merge override patterns with defaults while preserving required defaults.
+*
+* Overrides are prepended so they can add additional globs or exclusions, while
+* defaults remain in the list to prevent breaking essential artifacts.
 *
-* Defines which files should be:
-* - Server-only (ssrOnly): Deployed only to Lambda functions
-* - Shared (ssrShared): Deployed to both Lambda and CDN
+* @example
+* const defaults = ['server/**', 'loader.js'];
+* const overrides = ['custom/**', '!static/**'];
+* mergePatterns(defaults, overrides);
+* // => ['custom/**', '!static/**', 'server/**', 'loader.js']
+*/
+const mergePatterns = (defaults, overrides) => {
+	if (!overrides?.length) return defaults;
+	return Array.from(new Set([...overrides, ...defaults]));
+};
+/**
+* Load runtime config from config.server.ts for MRT bundle settings.
 *
-* @param buildDirectory - Path to the build output directory
-* @param projectDirectory - Path to the project root (reserved for future use)
-* @returns MRT SSR configuration with glob patterns
+* Keep in sync with @salesforce/storefront-next-runtime/src/config/load-config.ts.
 */
-const buildMrtConfig = (_buildDirectory, _projectDirectory) => {
+async function loadRuntimeConfig(projectDirectory) {
+	if (!projectDirectory) return;
+	const configPath = resolve(projectDirectory, "config.server.ts");
+	if (!existsSync(configPath)) return;
+	try {
+		const { createJiti } = await import("jiti");
+		const mod = await createJiti(import.meta.url, {
+			fsCache: false,
+			interopDefault: true
+		}).import(configPath);
+		return (mod.default ?? mod).runtime;
+	} catch (error) {
+		throw new Error(`[storefront-next-dev] Found config.server.ts at ${configPath} but failed to import it.`, { cause: error });
+	}
+}
+const buildMrtConfig = async (_buildDirectory, projectDirectory) => {
 	const ssrEntryPoint = getMrtEntryFile("production");
+	const defaultSsrOnly = [
+		"server/**/*",
+		"package.json",
+		"loader.js",
+		`${ssrEntryPoint}.{js,mjs,cjs}`,
+		`${ssrEntryPoint}.{js,mjs,cjs}.map`,
+		"!static/**/*",
+		"sfnext-server-*.mjs",
+		"sfnext-server-*.mjs.map"
+	];
+	const defaultSsrShared = [
+		"client/**/*",
+		"static/**/*",
+		"**/*.css",
+		"**/*.png",
+		"**/*.jpg",
+		"**/*.jpeg",
+		"**/*.gif",
+		"**/*.svg",
+		"**/*.ico",
+		"**/*.woff",
+		"**/*.woff2",
+		"**/*.ttf",
+		"**/*.eot"
+	];
+	const defaultSsrParameters = { ssrFunctionNodeVersion: "24.x" };
+	const runtimeConfig = await loadRuntimeConfig(projectDirectory);
+	const ssrOnly = mergePatterns(defaultSsrOnly, runtimeConfig?.ssrOnly);
+	const ssrShared = mergePatterns(defaultSsrShared, runtimeConfig?.ssrShared);
+	const ssrParameters = {
+		...defaultSsrParameters,
+		...runtimeConfig?.ssrParameters ?? {}
+	};
+	if (!ssrParameters.envBasePath) delete ssrParameters.envBasePath;
 	return {
-		ssrOnly: [
-			"server/**/*",
-			"loader.js",
-			`${ssrEntryPoint}.{js,mjs,cjs}`,
-			`${ssrEntryPoint}.{js,mjs,cjs}.map`,
-			"!static/**/*",
-			"sfnext-server-*.mjs",
-			"!**/*.stories.tsx",
-			"!**/*.stories.ts",
-			"!**/*-snapshot.tsx",
-			"!.storybook/**/*",
-			"!storybook-static/**/*",
-			"!**/__mocks__/**/*",
-			"!**/__snapshots__/**/*"
-		],
-		ssrShared: [
-			"client/**/*",
-			"static/**/*",
-			"**/*.css",
-			"**/*.png",
-			"**/*.jpg",
-			"**/*.jpeg",
-			"**/*.gif",
-			"**/*.svg",
-			"**/*.ico",
-			"**/*.woff",
-			"**/*.woff2",
-			"**/*.ttf",
-			"**/*.eot",
-			"!**/*.stories.tsx",
-			"!**/*.stories.ts",
-			"!**/*-snapshot.tsx",
-			"!.storybook/**/*",
-			"!storybook-static/**/*",
-			"!**/__mocks__/**/*",
-			"!**/__snapshots__/**/*"
-		],
-		ssrParameters: { ssrFunctionNodeVersion: "24.x" }
+		ssrOnly,
+		ssrShared,
+		ssrParameters
 	};
 };
 
 //#endregion
-export { buildMrtConfig as a, SFNEXT_BASE_CARTRIDGE_OUTPUT_DIR as i, GENERATE_AND_DEPLOY_CARTRIDGE_ON_MRT_PUSH as n, SFNEXT_BASE_CARTRIDGE_NAME as r, CARTRIDGES_BASE_DIR as t };
+export { buildMrtConfig as a, SFNEXT_BASE_CARTRIDGE_OUTPUT_DIR as i, GENERATE_AND_DEPLOY_CARTRIDGE_ON_MRT_PUSH as n, loadRuntimeConfig as o, SFNEXT_BASE_CARTRIDGE_NAME as r, CARTRIDGES_BASE_DIR as t };

package/dist/configs/react-router.config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"react-router.config.d.ts","names":[],"sources":["../../src/configs/react-router.config.ts"],"sourcesContent":[],"mappings":";;;;;;;;;iBAsBgB,oBAAA,CAAA,GAAwB"}
+{"version":3,"file":"react-router.config.d.ts","names":[],"sources":["../../src/configs/react-router.config.ts"],"sourcesContent":[],"mappings":";;;;;;;;;iBAuBgB,oBAAA,CAAA,GAAwB"}