@salesforce/storefront-next-dev 1.1.0 → 1.2.0-alpha.1

package/README.md

@@ -102,7 +102,7 @@ pnpm sfnext create-instructions --project-directory /path/to/your/project --exte
 
 #### Cartridge generation and deployment instructions
 
-Run these commands from your project directory (e.g., `template-retail-rsc-app`):
+Run these commands from your project directory:
 
 ```bash
 # Generate cartridge metadata for your site

package/dist/cartridge-services/index.d.ts

@@ -11,7 +11,7 @@ interface GenerateMetadataOptions {
    */
   filePaths?: string[];
   /**
-   * Whether to run ESLint with --fix on generated JSON files to format them according to project settings.
+   * Whether to format generated JSON files with Biome so they match the project's formatting.
    * Defaults to true.
    */
   lintFix?: boolean;

package/dist/cartridge-services/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/cartridge-services/generate-cartridge.ts"],"sourcesContent":[],"mappings":";;AA21BA;;;AAIG,UA1Ec,uBAAA,CA0Ed;EAAO;;;;;;;;;;;;;;;;;;;;UAlDO,sBAAA;;;;;;iBA8CK,gBAAA,gEAGR,0BACX,QAAQ"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/cartridge-services/generate-cartridge.ts"],"sourcesContent":[],"mappings":";;AAk8BA;;;AAIG,UA/Cc,uBAAA,CA+Cd;EAAO;;;;;;;;;;;;;;;;;;;;UAvBO,sBAAA;;;;;;iBAmBK,gBAAA,gEAGR,0BACX,QAAQ"}

package/dist/cartridge-services/index.js

@@ -1,12 +1,16 @@
 import { access, mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
 import { basename, extname, join, resolve } from "node:path";
-import { execSync } from "node:child_process";
 import { Node, Project } from "ts-morph";
 import { existsSync, readFileSync, unlinkSync } from "node:fs";
+import { execSync } from "node:child_process";
 import { tmpdir } from "node:os";
 import { randomUUID } from "node:crypto";
 import { npmRunPathEnv } from "npm-run-path";
 import chalk from "chalk";
+import { createRequire } from "module";
+import { spawnSync } from "child_process";
+import { dirname, join as join$1 } from "path";
+import { fileURLToPath } from "url";
 
 //#region src/utils/logger.ts
 const LEVEL_PRIORITY = {
@@ -174,6 +178,59 @@ function flattenRoutes(routes, parentPath = "") {
 	return result;
 }
 
+//#endregion
+//#region src/utils/format-with-project-biome.ts
+/** This module's own path — the resolution root for the SDK-bundled Biome fallback. */
+const HERE = fileURLToPath(import.meta.url);
+/**
+* Format every file Biome recognizes under `directory` in place with the consuming project's
+* Biome, so generated files (e.g. cartridge metadata JSON) match `biome format` / `pnpm lint:fix`.
+*
+* Unlike {@link formatWithProjectBiome} (single file via stdin), this runs `biome format --write`
+* against the directory so Biome discovers the project's `biome.json` by walking up from it and
+* applies the project's formatting to the written files directly.
+*
+* Fail-safe: when Biome can't be resolved or the run fails, the files are left as written (valid,
+* just unformatted) and a warning is logged — generation never breaks over formatting.
+*
+* @param directory - Directory whose Biome-recognized files should be formatted in place.
+*/
+function formatDirectoryWithProjectBiome(directory) {
+	const biomeBin = resolveBiomeBin(join$1(directory, "biome-resolution-root.js"));
+	if (!biomeBin) {
+		logger.warn(`⚠️  Biome could not be resolved; generated files in ${directory} were left unformatted.`);
+		return;
+	}
+	const result = spawnSync(process.execPath, [
+		biomeBin,
+		"format",
+		"--write",
+		"."
+	], {
+		cwd: directory,
+		encoding: "utf8"
+	});
+	if (result.status !== 0) {
+		const detail = result.stderr?.trim() || `exit code ${result.status}`;
+		logger.warn(`⚠️  Some generated files in ${directory} could not be formatted by Biome: ${detail}`);
+		return;
+	}
+	logger.debug(`✅ Formatted generated files in ${directory} with Biome`);
+}
+/**
+* Resolve a Biome CLI binary path, preferring the consuming project's install and falling back
+* to the SDK-bundled copy (available pre-install). Returns null when neither resolves.
+*/
+function resolveBiomeBin(filePath) {
+	for (const fromPath of [filePath, HERE]) try {
+		const req = createRequire(fromPath);
+		const biomePkgJson = req.resolve("@biomejs/biome/package.json");
+		const { bin } = req(biomePkgJson);
+		return join$1(dirname(biomePkgJson), bin.biome);
+	} catch {}
+	return null;
+}
+
 //#endregion
 //#region src/cartridge-services/generate-cartridge.ts
 const SKIP_DIRECTORIES = [
@@ -224,6 +281,62 @@ function resolveAttributeType(decoratorType, tsMorphType, fieldName) {
 	if (tsMorphType && TYPE_MAPPING[tsMorphType]) return TYPE_MAPPING[tsMorphType];
 	return "string";
 }
+const SEARCHING_FORBIDDEN_TYPES = new Set([
+	"integer",
+	"boolean",
+	"file",
+	"page",
+	"image",
+	"url",
+	"enum"
+]);
+/**
+* Validate an authored `searching` config against the resolved attribute type and map it to the
+* snake_case schema shape. The metadefinition schema gates `searching` by type; an invalid
+* combination fails cartridge generation (matching the strict behavior of `resolveAttributeType`).
+*
+* Rules (from attributedefinition.json):
+*  - Forbidden entirely on integer/boolean/file/page/image/url/enum.
+*  - `markup`: `sortable` must be false.
+*  - `custom`/`cms_record`: `refinable` must be false; `boost_factor`/`sortable` not allowed.
+*  - `string`/`text`/`product`/`category`: all fields allowed.
+*/
+function mapAttributeSearching(searching, resolvedType, fieldName) {
+	const fail = (reason) => {
+		logger.error(`Invalid 'searching' config for attribute '${fieldName}' (type '${resolvedType}'): ${reason}`);
+		process.exit(1);
+	};
+	if (SEARCHING_FORBIDDEN_TYPES.has(resolvedType)) fail(`the '${resolvedType}' attribute type does not support searching.`);
+	const { searchable, refinable, boostFactor, sortable } = searching;
+	if (typeof searchable !== "boolean" || typeof refinable !== "boolean") fail(`'searchable' and 'refinable' are required booleans.`);
+	if (resolvedType === "markup" && sortable === true) fail(`'sortable' must be false for markup attributes.`);
+	if (resolvedType === "custom" || resolvedType === "cms_record") {
+		if (refinable === true) fail(`'refinable' must be false for ${resolvedType} attributes.`);
+		if (boostFactor !== void 0) fail(`'boostFactor' is not supported for ${resolvedType} attributes.`);
+		if (sortable === true) fail(`'sortable' must be false for ${resolvedType} attributes.`);
+	}
+	const mapped = {
+		searchable,
+		refinable
+	};
+	if (boostFactor !== void 0) mapped.boost_factor = boostFactor;
+	if (sortable !== void 0) mapped.sortable = sortable;
+	return mapped;
+}
+/**
+* Validate an authored `dynamicLookup` config and map it to the snake_case schema shape.
+* The metadefinition schema allows `dynamic_lookup` on all attribute types but requires a
+* single `aspect_attribute_alias` field (`additionalProperties: false`); a missing alias fails
+* cartridge generation (matching the strict behavior of `resolveAttributeType`).
+*/
+function mapAttributeDynamicLookup(dynamicLookup, fieldName) {
+	const { aspectAttributeAlias } = dynamicLookup;
+	if (typeof aspectAttributeAlias !== "string" || aspectAttributeAlias.length === 0) {
+		logger.error(`Invalid 'dynamicLookup' config for attribute '${fieldName}': 'aspectAttributeAlias' is required and must be a non-empty string.`);
+		process.exit(1);
+	}
+	return { aspect_attribute_alias: aspectAttributeAlias };
+}
 function toHumanReadableName(fieldName) {
 	return fieldName.replace(/([A-Z])/g, " $1").replace(/^./, (str) => str.toUpperCase()).trim();
 }
@@ -375,6 +488,8 @@ function extractAttributesFromSource(sourceFile, className) {
 			if (config.values) attribute.values = config.values;
 			if (config.defaultValue !== void 0) attribute.default_value = config.defaultValue;
 			if (config.editorDefinition !== void 0) attribute.editor_definition = config.editorDefinition;
+			if (config.searching !== void 0) attribute.searching = mapAttributeSearching(config.searching, attribute.type, String(attribute.id));
+			if (config.dynamicLookup !== void 0) attribute.dynamic_lookup = mapAttributeDynamicLookup(config.dynamicLookup, String(attribute.id));
 			attributes.push(attribute);
 		}
 	} catch (error) {
@@ -404,13 +519,19 @@ function extractRegionDefinitionsFromSource(sourceFile, className, defaultCompon
 							id: regionConfig.id || "region",
 							name: regionConfig.name || "Region"
 						};
+						if (regionConfig.description !== void 0) regionDefinition.description = regionConfig.description;
 						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;
+						if (Array.isArray(regionConfig.defaultComponentConstructors)) regionDefinition.default_component_constructors = regionConfig.defaultComponentConstructors.map((constructor) => {
+							const { typeId, name } = constructor;
+							const mapped = { type_id: normalizeComponentTypeId(String(typeId), defaultComponentGroup) };
+							if (name !== void 0) mapped.name = name;
+							return mapped;
+						});
 						regionDefinitions.push(regionDefinition);
 					}
 				}
@@ -491,7 +612,8 @@ async function processPageTypeFile(filePath, projectRoot) {
 					regionDefinitions,
 					supportedAspectTypes: pageTypeConfig.supportedAspectTypes || [],
 					attributes,
-					route
+					route,
+					...pageTypeConfig.preview !== void 0 && { preview: pageTypeConfig.preview }
 				};
 				pageTypes.push(pageTypeMetadata);
 			}
@@ -578,6 +700,7 @@ async function generatePageTypeCartridge(pageType, outputDir, dryRun = false) {
 		}];
 		if (pageType.supportedAspectTypes) cartridgeData.supported_aspect_types = pageType.supportedAspectTypes;
 		if (pageType.route) cartridgeData.route = pageType.route;
+		if (pageType.preview !== void 0) cartridgeData.preview = pageType.preview;
 		await writeFile(outputPath, JSON.stringify(cartridgeData, null, 2));
 	}
 	const prefix = dryRun ? "   - [DRY RUN]" : "   -";
@@ -600,26 +723,14 @@ async function generateAspectCartridge(aspect, outputDir, dryRun = false) {
 	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.
+* Formats the generated JSON files in place so they match the project's `biome format` output
+* (and therefore pass `pnpm lint` out of the box). Delegates to the shared Biome helper, which
+* prefers the consuming project's Biome and is fail-safe (logs and leaves files valid-but-
+* unformatted rather than throwing) when Biome can't run.
 */
-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");
-	}
+function lintGeneratedFiles(metadataDir) {
+	logger.debug("🔧 Formatting generated JSON files with Biome...");
+	formatDirectoryWithProjectBiome(metadataDir);
 }
 async function generateMetadata(projectDirectory, metadataDirectory, options) {
 	try {
@@ -734,7 +845,7 @@ async function generateMetadata(projectDirectory, metadataDirectory, options) {
 			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);
+		if (!dryRun && shouldLintFix && (allComponents.length > 0 || allPageTypes.length > 0 || allAspects.length > 0)) lintGeneratedFiles(metadataDir);
 		return {
 			componentsGenerated: allComponents.length,
 			pageTypesGenerated: allPageTypes.length,