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

package/dist/commands/create-storefront.js

@@ -0,0 +1,210 @@
+import { c as warn, n as error } from "../logger.js";
+import { t as generateEnvFile } from "../utils.js";
+import { a as trimExtensions, i as validateNoCycles, n as resolveDependenciesForMultiple } from "../dependency-utils.js";
+import { t as prepareForLocalDev } from "../local-dev-setup.js";
+import { Command, Flags } from "@oclif/core";
+import { execFileSync, execSync } from "child_process";
+import path from "path";
+import fs from "fs-extra";
+import dotenv from "dotenv";
+import prompts from "prompts";
+
+//#region src/create-storefront.ts
+const DEFAULT_STOREFRONT = "sfcc-storefront";
+const STOREFRONT_NEXT_GITHUB_URL = "https://github.com/SalesforceCommerceCloud/storefront-next-template";
+const createStorefront = async (options = {}) => {
+	try {
+		execSync("git --version", { stdio: "ignore" });
+	} catch (e) {
+		error(`❌ git isn't installed or found in your PATH. Install git before running this command: ${String(e)}`);
+		process.exit(1);
+	}
+	let storefront = options.name;
+	if (!storefront) storefront = (await prompts({
+		type: "text",
+		name: "storefront",
+		message: "🏪 What would you like to name your storefront?\n",
+		initial: DEFAULT_STOREFRONT
+	})).storefront;
+	if (!storefront) {
+		error("Storefront name is required.");
+		process.exit(1);
+	}
+	console.log("\n");
+	let template = options.template;
+	if (!template) {
+		template = (await prompts({
+			type: "select",
+			name: "template",
+			message: "📄 Which template would you like to use for your storefront?\n",
+			choices: [{
+				title: "Salesforce B2C Commerce Retail Storefront",
+				value: STOREFRONT_NEXT_GITHUB_URL
+			}, {
+				title: "A different template (I will provide the Github URL)",
+				value: "custom"
+			}]
+		})).template;
+		console.log("\n");
+		if (template === "custom") {
+			const { githubUrl } = await prompts({
+				type: "text",
+				name: "githubUrl",
+				message: "🌐 What is the Github URL for your template?\n"
+			});
+			if (!githubUrl) {
+				error("Github URL is required.");
+				process.exit(1);
+			}
+			template = githubUrl;
+		}
+	}
+	if (!template) {
+		error("Template is required.");
+		process.exit(1);
+	}
+	if (options.templateBranch !== void 0 && options.templateBranch.trim() === "") {
+		error("--template-branch cannot be empty.");
+		process.exit(1);
+	}
+	const cloneArgs = [
+		"clone",
+		"--depth",
+		"1"
+	];
+	if (options.templateBranch) cloneArgs.push("--branch", options.templateBranch);
+	cloneArgs.push(template, storefront);
+	execFileSync("git", cloneArgs);
+	const gitDir = path.join(storefront, ".git");
+	if (fs.existsSync(gitDir)) fs.rmSync(gitDir, {
+		recursive: true,
+		force: true
+	});
+	if (template.startsWith("file://") || options.localPackagesDir) {
+		const templatePath = template.replace("file://", "");
+		const sourcePackagesDir = options.localPackagesDir || path.dirname(templatePath);
+		await prepareForLocalDev({
+			projectDirectory: storefront,
+			sourcePackagesDir
+		});
+	}
+	console.log("\n");
+	if (fs.existsSync(path.join(storefront, "src", "extensions", "config.json"))) {
+		const extensionConfigText = fs.readFileSync(path.join(storefront, "src", "extensions", "config.json"), "utf8");
+		const extensionConfig = JSON.parse(extensionConfigText);
+		if (extensionConfig.extensions) {
+			try {
+				validateNoCycles(extensionConfig);
+			} catch (e) {
+				error(`Extension configuration error: ${e.message}`);
+				process.exit(1);
+			}
+			const { selectedExtensions } = await prompts({
+				type: "multiselect",
+				name: "selectedExtensions",
+				message: "🔌 Which extension would you like to enable? (Use arrow keys to select, space to toggle, and enter to confirm.)\n",
+				choices: Object.keys(extensionConfig.extensions).map((extension) => ({
+					title: `${extensionConfig.extensions[extension].name} - ${extensionConfig.extensions[extension].description}`,
+					value: extension,
+					selected: extensionConfig.extensions[extension].defaultOn ?? true
+				})),
+				instructions: false
+			});
+			const resolvedExtensions = resolveDependenciesForMultiple(selectedExtensions, extensionConfig);
+			const selectedSet = new Set(selectedExtensions);
+			const autoAdded = resolvedExtensions.filter((ext) => !selectedSet.has(ext));
+			if (autoAdded.length > 0) for (const addedExt of autoAdded) {
+				const dependentExts = selectedExtensions.filter((selected) => {
+					return (extensionConfig.extensions[selected]?.dependencies || []).includes(addedExt) || resolvedExtensions.indexOf(addedExt) < resolvedExtensions.indexOf(selected);
+				});
+				if (dependentExts.length > 0) {
+					const addedName = extensionConfig.extensions[addedExt]?.name || addedExt;
+					warn(`${dependentExts.map((ext) => extensionConfig.extensions[ext]?.name || ext).join(", ")} requires ${addedName}. ${addedName} has been automatically added.`);
+				}
+			}
+			const enabledExtensions = Object.fromEntries(resolvedExtensions.map((ext) => [ext, true]));
+			trimExtensions(storefront, enabledExtensions, { extensions: extensionConfig.extensions }, options?.verbose || false);
+		}
+	}
+	const configMeta = JSON.parse(fs.readFileSync(path.join(storefront, "src", "config", "config-meta.json"), "utf8"));
+	const envDefaultPath = path.join(storefront, ".env.default");
+	let envDefaultValues = {};
+	if (fs.existsSync(envDefaultPath)) envDefaultValues = dotenv.parse(fs.readFileSync(envDefaultPath, "utf8"));
+	console.log("\n⚙️ We will now configure your storefront before it will be ready to run.\n");
+	const configOverrides = {};
+	for (const config of configMeta.configs) {
+		const answer = await prompts({
+			type: "text",
+			name: config.key,
+			message: `What is the value for ${config.name}? (default: ${envDefaultValues[config.key]})\n`,
+			initial: envDefaultValues[config.key] ?? ""
+		});
+		configOverrides[config.key] = answer[config.key];
+	}
+	generateEnvFile(storefront, configOverrides);
+	const BANNER = `
+    ╔══════════════════════════════════════════════════════════════════╗
+    ║                       CONGRATULATIONS                            ║
+    ╚══════════════════════════════════════════════════════════════════╝
+
+        🎉 Congratulations! Your storefront is ready to use! 🎉
+        What's next:
+        - Navigate to the storefront directory: cd ${storefront}
+        - Install dependencies: pnpm install
+        - Build the storefront: pnpm run build
+        - Run the development server: pnpm run dev
+    `;
+	console.log(BANNER);
+};
+
+//#endregion
+//#region src/commands/create-storefront.ts
+/**
+* Create storefront command - creates a new storefront project from template.
+*/
+var CreateStorefront = class CreateStorefront extends Command {
+	static description = "Create a storefront project";
+	static examples = [
+		"<%= config.bin %> <%= command.id %>",
+		"<%= config.bin %> <%= command.id %> -v",
+		"<%= config.bin %> <%= command.id %> -n my-storefront -t https://github.com/org/template -b release-0.2.x",
+		"<%= config.bin %> <%= command.id %> -n my-storefront -t /path/to/local/template",
+		"<%= config.bin %> <%= command.id %> -l /path/to/monorepo/packages"
+	];
+	static flags = {
+		verbose: Flags.boolean({
+			char: "v",
+			description: "Verbose mode",
+			default: false
+		}),
+		name: Flags.string({
+			char: "n",
+			description: "Storefront project name"
+		}),
+		template: Flags.string({
+			char: "t",
+			description: "Template repository to use for the storefront (GitHub URL or local path)"
+		}),
+		"template-branch": Flags.string({
+			char: "b",
+			description: "Branch or tag to clone from the template repository"
+		}),
+		"local-packages-dir": Flags.string({
+			char: "l",
+			description: "Local monorepo packages directory for file:// templates (pre-fills dependency paths)"
+		})
+	};
+	async run() {
+		const { flags } = await this.parse(CreateStorefront);
+		await createStorefront({
+			verbose: flags.verbose,
+			name: flags.name,
+			template: flags.template,
+			templateBranch: flags["template-branch"],
+			localPackagesDir: flags["local-packages-dir"]
+		});
+	}
+};
+
+//#endregion
+export { CreateStorefront as default };

package/dist/commands/deploy-cartridge.js

@@ -0,0 +1,52 @@
+import { i as SFNEXT_BASE_CARTRIDGE_OUTPUT_DIR, r as SFNEXT_BASE_CARTRIDGE_NAME, t as CARTRIDGES_BASE_DIR } from "../config.js";
+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";
+
+//#region src/commands/deploy-cartridge.ts
+/**
+* Deploy cartridge command - deploys the Page Designer metadata cartridge 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)
+*/
+var Deploy = class Deploy extends InstanceCommand {
+	static description = "Deploy cartridge 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"
+	];
+	static flags = { ...InstanceCommand.baseFlags };
+	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 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}"...`);
+		await uploadCartridges(this.instance, cartridges);
+		this.log(`Code deployed to version "${this.resolvedConfig.values.codeVersion}" successfully!`);
+	}
+};
+
+//#endregion
+export { Deploy as default };

package/dist/commands/dev.js

@@ -0,0 +1,122 @@
+import { a as printServerInfo, i as printServerConfig, o as printShutdownMessage } from "../logger.js";
+import { c as loadEnvFile } from "../utils.js";
+import { n as getCommerceCloudApiUrl, r as loadProjectConfig, t as createServer$2 } from "../server.js";
+import { t as commonFlags } from "../flags.js";
+import { Command, Flags } from "@oclif/core";
+import path from "path";
+import { createServer } from "node:http";
+import { createServer as createServer$1 } from "vite";
+
+//#region src/plugins/workspace.ts
+/**
+* Returns workspace-specific HMR configuration when running behind a workspace proxy.
+*
+* In workspace environments the OAuth2 proxy for the dev server's port is already
+* authenticated, so routing HMR WebSocket through the same HTTP server means it
+* shares the same proxy port and OAuth2 session. A separate port (e.g. port-8000)
+* would require its own OAuth2 login and return a 302 redirect that WebSocket
+* clients cannot follow.
+*
+* This is exported separately from the plugin because it requires the `httpServer`
+* reference created in `dev.ts`.
+*
+* @param httpServer - The Node HTTP server to attach the HMR WebSocket to.
+*
+* Environment variables:
+* - `EXTERNAL_DOMAIN_NAME` — The external hostname for the workspace proxy.
+*    When it does not start with "localhost", workspace proxy mode is assumed.
+*/
+function getWorkspaceHmrConfig(httpServer) {
+	const externalDomain = process.env.EXTERNAL_DOMAIN_NAME;
+	if (!externalDomain || externalDomain.startsWith("localhost")) return void 0;
+	return {
+		protocol: "wss",
+		host: externalDomain,
+		clientPort: 443,
+		server: httpServer
+	};
+}
+
+//#endregion
+//#region src/lib/dev.ts
+/**
+* Start the development server with Vite in middleware mode
+*/
+async function dev(options = {}) {
+	const startTime = Date.now();
+	const projectDir = path.resolve(options.projectDirectory || process.cwd());
+	const port = options.port || 5173;
+	process.env.NODE_ENV = process.env.NODE_ENV ?? "development";
+	loadEnvFile(projectDir);
+	process.env.EXTERNAL_DOMAIN_NAME = process.env.EXTERNAL_DOMAIN_NAME ?? `localhost:${port}`;
+	const config = await loadProjectConfig(projectDir);
+	const httpServer = createServer();
+	const hmr = getWorkspaceHmrConfig(httpServer);
+	const vite = await createServer$1({
+		root: projectDir,
+		server: {
+			middlewareMode: true,
+			...hmr && { hmr }
+		}
+	});
+	const app = await createServer$2({
+		mode: "development",
+		projectDirectory: projectDir,
+		config,
+		port,
+		vite
+	});
+	httpServer.on("request", app);
+	httpServer.listen(port, () => {
+		printServerInfo("development", port, startTime, projectDir);
+		printServerConfig({
+			mode: "development",
+			port,
+			enableProxy: true,
+			enableStaticServing: false,
+			enableCompression: false,
+			proxyPath: config.commerce.api.proxy,
+			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
+		});
+	});
+	["SIGTERM", "SIGINT"].forEach((signal) => {
+		process.once(signal, () => {
+			printShutdownMessage();
+			httpServer.close(() => {
+				vite.close();
+				process.exit(0);
+			});
+		});
+	});
+}
+
+//#endregion
+//#region src/commands/dev.ts
+/**
+* Dev server command - starts the Vite development server with SSR.
+*/
+var Dev = class Dev extends Command {
+	static description = "Start Vite development server with SSR";
+	static examples = ["<%= config.bin %> <%= command.id %>", "<%= config.bin %> <%= command.id %> -d ./my-project -p 3000"];
+	static flags = {
+		...commonFlags,
+		port: Flags.integer({
+			char: "p",
+			description: "Port number (default: 5173)"
+		})
+	};
+	async run() {
+		const { flags } = await this.parse(Dev);
+		await dev({
+			projectDirectory: flags["project-directory"],
+			port: flags.port
+		});
+	}
+};
+
+//#endregion
+export { Dev as default };

package/dist/commands/extensions/create.js

@@ -0,0 +1,38 @@
+import "../../dependency-utils.js";
+import { t as createExtension } from "../../manage-extensions.js";
+import { Command, Flags } from "@oclif/core";
+
+//#region src/commands/extensions/create.ts
+/**
+* Create extension command - creates a new extension scaffold in a storefront project.
+*/
+var Create = class Create extends Command {
+	static description = "Create a new extension scaffold in a storefront project";
+	static examples = ["<%= config.bin %> <%= command.id %> -n \"My Extension\"", "<%= config.bin %> <%= command.id %> -p ./my-project -n \"Store Locator\" -d \"Adds store locator functionality\""];
+	static flags = {
+		"project-directory": Flags.string({
+			char: "p",
+			description: "Target project directory",
+			default: process.cwd()
+		}),
+		name: Flags.string({
+			char: "n",
+			description: "Name of the extension to create (e.g., \"My Extension\")"
+		}),
+		description: Flags.string({
+			char: "d",
+			description: "Description of the extension"
+		})
+	};
+	async run() {
+		const { flags } = await this.parse(Create);
+		await createExtension({
+			projectDirectory: flags["project-directory"],
+			name: flags.name ?? "",
+			description: flags.description ?? ""
+		});
+	}
+};
+
+//#endregion
+export { Create as default };

package/dist/commands/extensions/install.js

@@ -0,0 +1,44 @@
+import "../../dependency-utils.js";
+import { t as commonFlags } from "../../flags.js";
+import { r as manageExtensions } from "../../manage-extensions.js";
+import { Command, Flags } from "@oclif/core";
+
+//#region src/commands/extensions/install.ts
+const DEFAULT_TEMPLATE_GIT_URL = process.env.DEFAULT_TEMPLATE_GIT_URL || "https://github.com/SalesforceCommerceCloud/storefront-next-template.git";
+/**
+* Install extension command - installs an extension into a storefront project.
+*/
+var Install = class Install extends Command {
+	static description = "Install an extension into a storefront project";
+	static examples = ["<%= config.bin %> <%= command.id %> -e SFDC_EXT_STORE_LOCATOR", "<%= config.bin %> <%= command.id %> -d ./my-project -e SFDC_EXT_THEME_SWITCHER"];
+	static flags = {
+		...commonFlags,
+		extension: Flags.string({
+			char: "e",
+			description: "Extension marker value (e.g. SFDC_EXT_STORE_LOCATOR)"
+		}),
+		"source-git-url": Flags.string({
+			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() {
+		const { flags } = await this.parse(Install);
+		await manageExtensions({
+			projectDirectory: flags["project-directory"],
+			install: true,
+			extensions: flags.extension ? [flags.extension] : void 0,
+			sourceGitUrl: flags["source-git-url"],
+			verbose: flags.verbose
+		});
+	}
+};
+
+//#endregion
+export { Install as default };

package/dist/commands/extensions/list.js

@@ -0,0 +1,21 @@
+import "../../dependency-utils.js";
+import { t as commonFlags } from "../../flags.js";
+import { n as listExtensions } from "../../manage-extensions.js";
+import { Command } from "@oclif/core";
+
+//#region src/commands/extensions/list.ts
+/**
+* List extensions command - lists all installed extensions in a storefront project.
+*/
+var List = class List extends Command {
+	static description = "List all installed extensions in a storefront project";
+	static examples = ["<%= config.bin %> <%= command.id %>", "<%= config.bin %> <%= command.id %> -d ./my-project"];
+	static flags = { ...commonFlags };
+	async run() {
+		const { flags } = await this.parse(List);
+		listExtensions({ projectDirectory: flags["project-directory"] });
+	}
+};
+
+//#endregion
+export { List as default };

package/dist/commands/extensions/remove.js

@@ -0,0 +1,38 @@
+import "../../dependency-utils.js";
+import { t as commonFlags } from "../../flags.js";
+import { r as manageExtensions } from "../../manage-extensions.js";
+import { Command, Flags } from "@oclif/core";
+
+//#region src/commands/extensions/remove.ts
+/**
+* Remove extension command - removes one or more extensions from a storefront project.
+*/
+var Remove = class Remove extends Command {
+	static description = "Remove one or more installed extensions from a storefront project";
+	static examples = ["<%= config.bin %> <%= command.id %> -e SFDC_EXT_STORE_LOCATOR", "<%= config.bin %> <%= command.id %> -e SFDC_EXT_STORE_LOCATOR,SFDC_EXT_THEME_SWITCHER"];
+	static flags = {
+		...commonFlags,
+		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() {
+		const { flags } = await this.parse(Remove);
+		const extensions = flags.extensions ? flags.extensions.split(",").map((e) => e.trim()) : void 0;
+		await manageExtensions({
+			projectDirectory: flags["project-directory"],
+			uninstall: true,
+			extensions,
+			verbose: flags.verbose
+		});
+	}
+};
+
+//#endregion
+export { Remove as default };

package/dist/commands/generate-cartridge.js

@@ -0,0 +1,35 @@
+import { t as commonFlags } from "../flags.js";
+import { i as SFNEXT_BASE_CARTRIDGE_OUTPUT_DIR, t as CARTRIDGES_BASE_DIR } from "../config.js";
+import { t as generateMetadata } from "../generate-cartridge.js";
+import { Command } from "@oclif/core";
+import path from "path";
+import fs from "fs-extra";
+
+//#region src/commands/generate-cartridge.ts
+/**
+* Generate cartridge metadata command.
+*
+* Scans the project for decorated components and generates Page Designer
+* metadata files in the cartridge directory.
+*/
+var Generate = class Generate extends Command {
+	static description = "Generate Page Designer component metadata from decorated components";
+	static examples = ["<%= config.bin %> <%= command.id %>", "<%= config.bin %> <%= command.id %> -d ./my-project"];
+	static flags = { ...commonFlags };
+	async run() {
+		const { flags } = await this.parse(Generate);
+		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.log(`Creating metadata directory: ${metadataDir}`);
+			fs.mkdirSync(metadataDir, { recursive: true });
+		}
+		this.log("Generating Page Designer metadata...");
+		await generateMetadata(projectDirectory, metadataDir);
+		this.log("Page Designer metadata generated successfully!");
+	}
+};
+
+//#endregion
+export { Generate as default };

package/dist/commands/prepare-local.js

@@ -0,0 +1,30 @@
+import "../logger.js";
+import { t as prepareForLocalDev } from "../local-dev-setup.js";
+import { t as commonFlags } from "../flags.js";
+import { Command, Flags } from "@oclif/core";
+
+//#region src/commands/prepare-local.ts
+/**
+* Prepare local command - prepares a storefront project for local development with file-linked packages.
+*/
+var PrepareLocal = class PrepareLocal extends Command {
+	static description = "Prepare a storefront project for local development with file-linked packages. Converts workspace:* dependencies to file: references and patches vite.config.ts.";
+	static examples = ["<%= config.bin %> <%= command.id %> -d ./my-storefront", "<%= config.bin %> <%= command.id %> -d . -s /path/to/monorepo/packages"];
+	static flags = {
+		...commonFlags,
+		"source-packages-dir": Flags.string({
+			char: "s",
+			description: "Source monorepo packages directory (for default path suggestions)"
+		})
+	};
+	async run() {
+		const { flags } = await this.parse(PrepareLocal);
+		await prepareForLocalDev({
+			projectDirectory: flags["project-directory"],
+			sourcePackagesDir: flags["source-packages-dir"]
+		});
+	}
+};
+
+//#endregion
+export { PrepareLocal as default };