@adobe/aio-commerce-lib-app 2.0.0 → 2.0.1-alpha-20260923160203

package/dist/es/web-src-CM_09qwk.mjs

@@ -0,0 +1,1345 @@
+/**
+ * @license
+ *
+ * Copyright 2026 Adobe. All rights reserved.
+ * This file is licensed to you 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 REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import { _ as makeOutputDirFor, a as resolveCommerceAppConfig, c as getExecCommand, d as getPackageExecutionCommand, f as getProjectInstallCommand, g as loadPackageJson, l as getInstallCommand, m as getRunScriptCommand, n as isTypeScriptConfig, o as appendCommand, p as getProjectRootDirectory, r as parseCommerceAppConfig, s as detectPackageManager, t as hasNamedCommerceAppConfigExports, u as getPackageDependencyInstallPlan, v as mergePackageJsonDependencies } from "./index.node-DPiidKGS.mjs";
+import { f as hasCustomInstallationSteps } from "./webhooks-BMBfTqwi.mjs";
+import { u as hasBusinessConfigSchema } from "./validate-Pd7RIA_3.mjs";
+import { hasDynamicSchema } from "@adobe/aio-commerce-lib-config";
+import { CommerceSdkValidationError } from "@adobe/aio-commerce-lib-core/error";
+import { stringify as stringify$1 } from "safe-stable-stringify";
+import { constants, existsSync } from "fs";
+import { access, copyFile, mkdir, readFile, readdir, rm, writeFile } from "fs/promises";
+import { basename, dirname, extname, join, relative, sep } from "path";
+import consola$1, { consola } from "consola";
+import { fileURLToPath } from "url";
+import { formatTree } from "consola/utils";
+import { execSync, spawnSync } from "child_process";
+import * as prettier from "prettier";
+import { Document, YAMLMap, YAMLSeq, isMap, isPair, isSeq, parseDocument } from "yaml";
+
+//#region source/commands/generate/actions/constants.ts
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+/** The path to the action templates directory, sibling to this file. */
+const TEMPLATES_DIR = join(__dirname, "templates");
+/** The list of Commerce variables that are required for the runtime actions. */
+const COMMERCE_VARIABLES = [
+	"AIO_COMMERCE_AUTH_IMS_CLIENT_ID",
+	"AIO_COMMERCE_AUTH_IMS_CLIENT_SECRETS",
+	"AIO_COMMERCE_AUTH_IMS_TECHNICAL_ACCOUNT_ID",
+	"AIO_COMMERCE_AUTH_IMS_TECHNICAL_ACCOUNT_EMAIL",
+	"AIO_COMMERCE_AUTH_IMS_ORG_ID",
+	"AIO_COMMERCE_AUTH_IMS_SCOPES"
+];
+/** The inputs for the generated runtime actions. */
+const COMMERCE_ACTION_INPUTS = Object.fromEntries(COMMERCE_VARIABLES.map((variable) => [variable, `$${variable}`]));
+const CUSTOM_IMPORTS_PLACEHOLDER = "// {{CUSTOM_SCRIPTS_IMPORTS}}";
+const CUSTOM_SCRIPTS_MAP_PLACEHOLDER = "// {{CUSTOM_SCRIPTS_MAP}}";
+const CUSTOM_SCRIPTS_LOADER_PLACEHOLDER = "// {{CUSTOM_SCRIPTS_LOADER}}";
+
+//#endregion
+//#region source/commands/constants.ts
+/** The name of the package containing all the generated runtime actions */
+const PACKAGE_NAME = "app-management";
+/** The path to the directory containing the generated files */
+const GENERATED_PATH = ".generated";
+/** The folder name containing the runtime actions */
+const ACTIONS_FOLDER = `actions/${PACKAGE_NAME}`;
+/** The path to the directory containing the generated actions */
+const GENERATED_ACTIONS_PATH = `${GENERATED_PATH}/${ACTIONS_FOLDER}`;
+/** The path to the directory containing the generated App Builder hook files */
+const GENERATED_HOOKS_PATH = `${GENERATED_PATH}/hooks`;
+/** The name of the extension point for extensibility. */
+const EXTENSIBILITY_EXTENSION_POINT_ID = "commerce/extensibility/1";
+/** The name of the extension point for configuration. */
+const CONFIGURATION_EXTENSION_POINT_ID = "commerce/configuration/1";
+/** The name of the extension point for Admin UI. */
+const BACKEND_UI_V2_EXTENSION_POINT_ID = "commerce/backend-ui/2";
+/** The name of the configuration schema file */
+const APP_MANIFEST_FILE = "app.commerce.manifest.json";
+/** The name of the generated runtime-safe app config module (dynamic schemas only). */
+const RUNTIME_APP_CONFIG_FILE = "app.commerce.config.js";
+/** Package import alias for the generated runtime-safe app config module. */
+const APP_CONFIG_IMPORT_ALIAS = "#app.commerce.config";
+/** The name of the commerce app configuration file */
+const COMMERCE_APP_CONFIG_FILE = "app.commerce.config";
+/** TypeScript development dependencies shared by root and web-src scaffolding. */
+const SHARED_TYPESCRIPT_DEV_DEPENDENCIES = [{
+	name: "@tsconfig/bases",
+	version: "^1.0.26"
+}, {
+	name: "typescript",
+	version: "^6.0.3"
+}];
+/** Node.js type definitions required only by root Runtime action scaffolding. */
+const TYPESCRIPT_NODE_DEV_DEPENDENCY = {
+	name: "@types/node",
+	version: "^24.12.0"
+};
+/** TypeScript loader required only by root Runtime action scaffolding. */
+const TYPESCRIPT_WEBPACK_DEV_DEPENDENCY = {
+	name: "ts-loader",
+	version: "^9.6.2"
+};
+/** The name of the configuration schema file */
+const CONFIG_SCHEMA_FILE_NAME = "configuration-schema.json";
+/** The name of the project package file */
+const PACKAGE_JSON_FILE = "package.json";
+/** The name of the app configuration file */
+const APP_CONFIG_FILE = "app.config.yaml";
+/** The name of the install configuration file */
+const INSTALL_YAML_FILE = "install.yaml";
+/** Get the path to the extension point folder */
+function getExtensionPointFolderPath(extensionPointId) {
+	return `src/${extensionPointId.replaceAll("/", "-")}`;
+}
+
+//#endregion
+//#region source/commands/utils.ts
+/** Format file content using prettier, inferring the parser from the file path. */
+function prettierFormat(content, filepath) {
+	return prettier.format(content, {
+		arrowParens: "always",
+		bracketSameLine: true,
+		bracketSpacing: true,
+		filepath,
+		printWidth: 80,
+		quoteStyle: "double",
+		semi: true,
+		tabWidth: 2,
+		trailingComma: "all",
+		useTabs: false
+	});
+}
+/**
+* Load the app commerce config.
+* @param projectRoot - Resolved project root containing the app configuration.
+*/
+async function loadAppManifest(projectRoot) {
+	const appConfig = await parseCommerceAppConfig(projectRoot);
+	consola$1.debug("Loaded app commerce config");
+	return appConfig;
+}
+/**
+* Install the given dependencies.
+* @param packageManager - The detected package manager.
+* @param dependencies - Package specifiers to install; no-op when empty.
+* @param cwd - Working directory for the install command.
+* @param options - Install command options.
+*/
+function runInstall(packageManager, dependencies, cwd = process.cwd(), options = {}) {
+	if (dependencies.length === 0) return;
+	const dependencyListString = dependencies.map((dependency) => `  - ${dependency}`).join("\n");
+	consola$1.start([`Installing the following dependencies with ${packageManager}:\n${dependencyListString}\n`, "This may take a few seconds...\n"].join("\n"));
+	const { command, args } = getInstallCommand(packageManager, dependencies, options);
+	const displayCommand = [command, ...args].join(" ");
+	const result = spawnSync(command, args, {
+		cwd,
+		stdio: "inherit"
+	});
+	if (result.error || result.status !== 0) throw new Error(`Failed to install dependencies automatically. Please install manually: ${displayCommand}`, { cause: result.error ?? /* @__PURE__ */ new Error(`Install exited with code ${result.status}`) });
+	consola$1.log("");
+	consola$1.success("Dependencies installed successfully");
+}
+/**
+* Install dependencies declared in package.json.
+* @param packageManager - The detected package manager.
+* @param cwd - Working directory for the install command.
+*/
+function runProjectInstall(packageManager, cwd = process.cwd()) {
+	consola$1.start([`Installing project dependencies with ${packageManager}...`, "This may take a few seconds...\n"].join("\n"));
+	const { command, args } = getProjectInstallCommand(packageManager);
+	const displayCommand = [command, ...args].join(" ");
+	const result = spawnSync(command, args, {
+		cwd,
+		stdio: "inherit"
+	});
+	if (result.error || result.status !== 0) throw new Error(`Failed to install dependencies automatically. Please install manually: ${displayCommand}`, { cause: result.error ?? /* @__PURE__ */ new Error(`Install exited with code ${result.status}`) });
+	consola$1.log("");
+	consola$1.success("Dependencies installed successfully");
+}
+/**
+* Whether the app config contains anything that can't be JSON-serialized as-is
+* and therefore requires generating a runtime-safe ESM config module.
+*/
+function hasDynamicAppConfig(appConfig) {
+	const schema = appConfig.businessConfig?.schema;
+	return Array.isArray(schema) && hasDynamicSchema(schema);
+}
+/**
+* Whether preserving the app config requires generating a JavaScript module.
+* @param appConfig - The parsed app config.
+* @param projectRoot - Resolved project root containing the source config.
+*/
+async function requiresJavaScriptAppConfig(appConfig, projectRoot) {
+	return hasDynamicAppConfig(appConfig) || await hasNamedCommerceAppConfigExports(projectRoot);
+}
+/**
+* Path to an extension point's `.generated` directory, relative to the project root.
+* @param extensionPointId - The extension point ID, e.g. "commerce/extensibility/1"
+*/
+function getGeneratedDir(extensionPointId) {
+	return join(getExtensionPointFolderPath(extensionPointId), GENERATED_PATH);
+}
+/**
+* Path to an extension point's generated actions directory, relative to the project root.
+* @param extensionPointId - The extension point ID, e.g. "commerce/extensibility/1"
+*/
+function getActionsDir(extensionPointId) {
+	return join(getExtensionPointFolderPath(extensionPointId), GENERATED_ACTIONS_PATH);
+}
+/**
+* Path to a specific generated action file, relative to the project root.
+* @param extensionPointId - The extension point ID, e.g. "commerce/extensibility/1"
+* @param actionName - The name of the action, e.g. "my-action"
+*/
+function getActionPath(extensionPointId, actionName) {
+	return join(getActionsDir(extensionPointId), `${actionName}.js`);
+}
+/**
+* Path to the generated file of an App Builder hook, relative to the project root.
+* @param extensionPointId - The extension point ID, e.g. "commerce/extensibility/1"
+* @param hookName - The name of the hook, e.g. "pre-app-build"
+*/
+function getHookPath(extensionPointId, hookName) {
+	return `${getExtensionPointFolderPath(extensionPointId)}/${GENERATED_HOOKS_PATH}/${hookName}.cjs`;
+}
+/**
+* Path to an extension point's `ext.config.yaml`, relative to the project root.
+* @param extensionPointId - The extension point ID, e.g. "commerce/extensibility/1"
+*/
+function getExtConfigPath(extensionPointId) {
+	return join(getExtensionPointFolderPath(extensionPointId), "ext.config.yaml");
+}
+/** Path to the generated app manifest JSON file, relative to the project root. */
+function getManifestPath() {
+	return join(getGeneratedDir(EXTENSIBILITY_EXTENSION_POINT_ID), APP_MANIFEST_FILE);
+}
+/**
+* Path to the generated runtime-safe app config ESM module, relative to the
+* project root. Used when the business config schema contains dynamic options.
+*/
+function getRuntimeAppConfigPath() {
+	return join(getGeneratedDir(EXTENSIBILITY_EXTENSION_POINT_ID), RUNTIME_APP_CONFIG_FILE);
+}
+/** Path to the generated configuration schema file, relative to the project root. */
+function getSchemaPath() {
+	return join(getGeneratedDir(CONFIGURATION_EXTENSION_POINT_ID), CONFIG_SCHEMA_FILE_NAME);
+}
+
+//#endregion
+//#region source/commands/generate/actions/config.ts
+/**
+* Creates a runtime action configuration.
+* @param actionName - The name of the action.
+* @param config - Action generation options.
+* @param options - Optional configuration options.
+*/
+function createActionDefinition(actionName, config = {}, options = {}) {
+	const def = {
+		...options,
+		annotations: {
+			final: true,
+			"require-adobe-auth": true
+		},
+		function: `${GENERATED_ACTIONS_PATH}/${actionName}.js`,
+		runtime: "nodejs:24",
+		web: options.web ?? "yes"
+	};
+	if (config.requiresEncryptionKey) def.inputs = {
+		...def.inputs,
+		AIO_COMMERCE_CONFIG_ENCRYPTION_KEY: "$AIO_COMMERCE_CONFIG_ENCRYPTION_KEY"
+	};
+	return def;
+}
+/**
+* Gets the runtime actions to be generated from the ext.config.yaml configuration.
+* @param extConfig - The ext.config.yaml configuration.
+* @param dir - Directory containing the runtime action templates.
+*/
+function getRuntimeActions(extConfig, dir) {
+	return Object.entries(extConfig.runtimeManifest?.packages?.["app-management"]?.actions ?? {}).map(([name]) => ({
+		name,
+		templateFile: join(dir, `${name}.js.template`)
+	}));
+}
+/**
+* Builds the ext.config.yaml configuration for the extensibility extension.
+* @param appConfig - Parsed app configuration.
+*/
+function buildAppManagementExtConfig(appConfig) {
+	const extConfig = {
+		hooks: {
+			"post-app-deploy": getHookPath(EXTENSIBILITY_EXTENSION_POINT_ID, "post-app-deploy"),
+			"pre-app-build": getHookPath(EXTENSIBILITY_EXTENSION_POINT_ID, "pre-app-build")
+		},
+		operations: { workerProcess: [{
+			impl: `${PACKAGE_NAME}/app-config`,
+			type: "action"
+		}, {
+			impl: `${PACKAGE_NAME}/association`,
+			type: "action"
+		}] },
+		runtimeManifest: { packages: { [PACKAGE_NAME]: {
+			actions: {
+				"app-config": createActionDefinition("app-config"),
+				association: createActionDefinition("association")
+			},
+			license: "Apache-2.0"
+		} } }
+	};
+	const hasPasswordFieldsInSchema = hasBusinessConfigSchema(appConfig) && appConfig.businessConfig.schema.some((field) => field.type === "password");
+	extConfig.operations.workerProcess.push({
+		impl: `${PACKAGE_NAME}/installation`,
+		type: "action"
+	});
+	extConfig.runtimeManifest.packages[PACKAGE_NAME].actions.installation = createActionDefinition("installation", { requiresEncryptionKey: hasPasswordFieldsInSchema }, {
+		inputs: {
+			...COMMERCE_ACTION_INPUTS,
+			LOG_LEVEL: "$LOG_LEVEL"
+		},
+		limits: { timeout: 6e5 }
+	});
+	return extConfig;
+}
+/** Builds the ext.config.yaml configuration for the business configuration extension. */
+function buildBusinessConfigurationExtConfig() {
+	const actions = [{
+		name: "config",
+		requiresEncryptionKey: true,
+		templateFile: "config.js.template"
+	}, {
+		name: "scope-tree",
+		templateFile: "scope-tree.js.template"
+	}];
+	return {
+		hooks: { "pre-app-build": getHookPath(CONFIGURATION_EXTENSION_POINT_ID, "pre-app-build") },
+		operations: { workerProcess: actions.map((action) => ({
+			impl: `${PACKAGE_NAME}/${action.name}`,
+			type: "action"
+		})) },
+		runtimeManifest: { packages: { [PACKAGE_NAME]: {
+			actions: Object.fromEntries(actions.map((action) => [action.name, createActionDefinition(action.name, action)])),
+			license: "Apache-2.0"
+		} } }
+	};
+}
+/** Collects unique `runtimeAction` strings from all worker entries in an `adminUi` config. */
+function collectUniqueRuntimeActions(adminUi) {
+	const entities = [
+		"order",
+		"product",
+		"customer"
+	].map((key) => adminUi?.[key]);
+	const gridRuntimeActions = entities.map((entity) => entity?.gridColumns?.runtimeAction).filter((action) => action !== void 0);
+	const massActionRuntimeActions = entities.flatMap((entity) => entity?.massActions ?? []).filter((action) => action.type === "worker").map((action) => action.runtimeAction);
+	const viewButtonRuntimeActions = (adminUi?.order?.viewButtons ?? []).filter((button) => button.type === "worker").map((button) => button.runtimeAction);
+	return [.../* @__PURE__ */ new Set([
+		...gridRuntimeActions,
+		...massActionRuntimeActions,
+		...viewButtonRuntimeActions
+	])];
+}
+/** Returns true if the `adminUi` config requires a `view` operation and `web` source in ext.config.yaml. */
+function requiresWebSource(adminUi) {
+	if (adminUi?.menu !== void 0) return true;
+	if ((adminUi?.order?.viewButtons ?? []).some((button) => button.type === "view")) return true;
+	return [
+		"order",
+		"product",
+		"customer"
+	].map((key) => adminUi?.[key]).flatMap((entity) => entity?.massActions ?? []).some((action) => action.type === "view");
+}
+/**
+* Builds the ext.config.yaml for the Admin UI v2 extension (`commerce/backend-ui/2`).
+* Derives `workerProcess` and `view` operation declarations from `adminUi` config.
+* Adds a `view` operation and `web` source when view-type entries or `adminUi.menu` is configured.
+* @param appConfig - Parsed app configuration.
+*/
+function buildAdminUiV2ExtConfig(appConfig) {
+	const { adminUi } = appConfig;
+	const runtimeActions = collectUniqueRuntimeActions(adminUi);
+	const requiresWeb = requiresWebSource(adminUi);
+	return {
+		hooks: {
+			"pre-app-build": getHookPath(BACKEND_UI_V2_EXTENSION_POINT_ID, "pre-app-build"),
+			"pre-app-dev": getHookPath(BACKEND_UI_V2_EXTENSION_POINT_ID, "pre-app-dev"),
+			"pre-app-run": getHookPath(BACKEND_UI_V2_EXTENSION_POINT_ID, "pre-app-run")
+		},
+		operations: {
+			...requiresWeb && { view: [{
+				impl: "index.html",
+				type: "web"
+			}] },
+			...runtimeActions.length > 0 && { workerProcess: runtimeActions.map((impl) => ({
+				impl,
+				type: "action"
+			})) }
+		},
+		...requiresWeb && { web: "web-src" }
+	};
+}
+
+//#endregion
+//#region ../../packages-private/scripting-utils/source/yaml/helpers.ts
+/**
+* Read a YAML file and return a {@link Document}
+* @param path - The path to the YAML file
+*/
+async function readYamlFile(path) {
+	let doc = new Document();
+	if (existsSync(path)) try {
+		const fileContent = await readFile(path, "utf-8");
+		doc = parseDocument(fileContent, { keepSourceTokens: true });
+	} catch (err) {
+		const file = basename(path);
+		throw new Error(`Failed to parse ${file}`, { cause: err });
+	}
+	if (doc.contents === null) doc.contents = new YAMLMap();
+	return doc;
+}
+/**
+* Generic helper to get or create a YAML node at the given path
+* @param doc - The YAML document
+* @param path - The path to the node
+* @param options - The options for the node
+* @param typeConfig - Configuration for the node type
+* @returns The existing or newly created node
+*/
+function getOrCreateNode(doc, path, options, typeConfig) {
+	const node = doc.getIn(path);
+	if (node) {
+		if (!typeConfig.typeGuard(node)) throw new Error(`Expected ${typeConfig.typeName} at path "${path.join(".")}".`);
+		return node;
+	}
+	if (doc.hasIn(path)) doc.deleteIn(path);
+	const pair = doc.createPair(path.at(-1), typeConfig.createNode());
+	options.onBeforeCreate?.(pair);
+	if (path.length === 1) doc.add(pair);
+	else doc.addIn(path.slice(0, -1), pair);
+	return doc.getIn(path);
+}
+/**
+* Get or create a sequence at the given path
+* @param doc - The YAML document
+* @param path - The path to the sequence
+* @param options - The options for the sequence
+*/
+function getOrCreateSeq(doc, path, options) {
+	return getOrCreateNode(doc, path, options ?? {}, {
+		createNode: () => new YAMLSeq(),
+		typeGuard: isSeq,
+		typeName: "sequence"
+	});
+}
+/**
+* Get or create a map at the given path
+* @param doc - The YAML document
+* @param path - The path to the map
+* @param options - The options for the map
+*/
+function getOrCreateMap(doc, path, options) {
+	return getOrCreateNode(doc, path, options ?? {}, {
+		createNode: () => new YAMLMap(),
+		typeGuard: isMap,
+		typeName: "map"
+	});
+}
+/**
+* Read the `inputs` map from an existing YAML action definition into a plain
+* object. Used by codegen to merge developer-added inputs with the ones the
+* generator manages, so regeneration does not strip user-added entries.
+*
+* @param existingAction - The YAML map representing the existing action.
+*/
+function getExistingInputs(existingAction) {
+	const inputs = existingAction?.get("inputs");
+	if (!isMap(inputs)) return {};
+	return Object.fromEntries(inputs.items.map((item) => {
+		if (!isPair(item)) return [];
+		return [String(item.key), item.value];
+	}));
+}
+/**
+* Read a string field from an existing YAML action definition. Used by codegen
+* to preserve developer-set values (e.g. `runtime`) across regeneration
+* instead of overwriting them.
+*
+* @param key - The field to read.
+* @param existingAction - The YAML map representing the existing action.
+*/
+function getExistingString(key, existingAction) {
+	const value = existingAction?.get(key);
+	return typeof value === "string" ? value : void 0;
+}
+
+//#endregion
+//#region ../../packages-private/scripting-utils/source/yaml/codegen.ts
+/**
+* Create an ext.config.yaml file
+* @param path - The path to the ext.config.yaml file
+* @param config - The config to build
+* @param doc - The document to modify (a new one is created if not provided)
+*/
+async function createOrUpdateExtConfig(path, config, doc) {
+	const extConfigDoc = doc ?? new Document({});
+	if (config.web !== void 0) buildWeb(extConfigDoc, config.web);
+	config.hooks ??= {};
+	buildHooks(extConfigDoc, config.hooks);
+	if (config.operations !== void 0) buildOperations(extConfigDoc, config.operations);
+	if (config.runtimeManifest !== void 0) buildRuntimeManifest(extConfigDoc, config.runtimeManifest);
+	await writeExtConfig(path, extConfigDoc);
+	return extConfigDoc;
+}
+/**
+* Set the top-level `web` scalar only if it's missing.
+* Preserves any user-customized value already present.
+*/
+function buildWeb(extConfig, web) {
+	if (!extConfig.hasIn(["web"])) extConfig.add(extConfig.createPair("web", web));
+}
+/**
+* Build the definition for a runtime action.
+*
+* Developer-added `inputs` keys (anything not in the generator-managed set) on
+* `existingAction` are preserved so that hand-written entries — for example
+* factory credentials for `dynamicList` fields — survive regeneration.
+*
+* A `runtime` already set on `existingAction` is likewise preserved, so a
+* developer can pin a different Node runtime (e.g. `nodejs:24`) in
+* `ext.config.yaml` once without codegen reverting it on the next run.
+*
+* @param action - The action definition to build.
+* @param existingAction - The action's previous YAML definition, if any.
+*/
+function buildActionDefinition(action, existingAction) {
+	const actionDef = new YAMLMap();
+	const existingInputs = getExistingInputs(existingAction);
+	const existingRuntime = getExistingString("runtime", existingAction);
+	const managedInputs = { LOG_LEVEL: "$LOG_LEVEL" };
+	actionDef.set("function", action.function);
+	actionDef.set("web", action.web ?? "yes");
+	actionDef.set("runtime", existingRuntime ?? action.runtime ?? "nodejs:24");
+	actionDef.set("inputs", {
+		...existingInputs,
+		...managedInputs,
+		...action.inputs ?? {}
+	});
+	actionDef.set("annotations", { ...action.annotations ?? {
+		final: true,
+		"require-adobe-auth": true
+	} });
+	const includes = action.include ?? [];
+	if (includes.length > 0) {
+		const itemSeq = new YAMLSeq();
+		itemSeq.flow = true;
+		for (const [source, target] of includes) itemSeq.items.push(source, target);
+		const seq = new YAMLSeq();
+		seq.items.push(itemSeq);
+		actionDef.set("include", seq);
+	}
+	if (action.limits !== void 0) actionDef.set("limits", action.limits);
+	return actionDef;
+}
+/**
+* Build the `operations` section of the `ext.config.yaml` file
+* @param extConfig - The ext.config.yaml file
+* @param operations - The operations to build
+*/
+function buildOperations(extConfig, operations) {
+	const ourOps = operations.workerProcess ?? [];
+	if (ourOps.length > 0) {
+		getOrCreateMap(extConfig, ["operations"], { onBeforeCreate: (pair) => {
+			pair.key.spaceBefore = true;
+		} });
+		const workerProcess = getOrCreateSeq(extConfig, ["operations", "workerProcess"], { onBeforeCreate: (pair) => {
+			pair.key.commentBefore = " These worker processes definitions are auto-generated. Do not remove or manually edit.";
+		} });
+		workerProcess.items = [];
+		workerProcess.items.push(...ourOps.map((op) => {
+			const map = new YAMLMap();
+			map.set("type", op.type);
+			map.set("impl", op.impl);
+			return map;
+		}));
+	} else if (extConfig.hasIn(["operations", "workerProcess"])) extConfig.deleteIn(["operations", "workerProcess"]);
+	if (operations.view !== void 0) {
+		getOrCreateMap(extConfig, ["operations"], { onBeforeCreate: (pair) => {
+			pair.key.spaceBefore = true;
+		} });
+		const view = getOrCreateSeq(extConfig, ["operations", "view"]);
+		if (view.items.length === 0) view.items.push(...operations.view.map((v) => {
+			const map = new YAMLMap();
+			map.set("type", v.type);
+			map.set("impl", v.impl);
+			return map;
+		}));
+	}
+	const operationsMap = extConfig.getIn(["operations"]);
+	if (operationsMap instanceof YAMLMap && operationsMap.items.length === 0) extConfig.deleteIn(["operations"]);
+}
+/**
+* Build the `runtimeManifest` section of the `ext.config.yaml` file
+* @param extConfig - The ext.config.yaml file
+* @param packages - The packages to build
+*/
+function buildRuntimeManifest(extConfig, manifest) {
+	const packages = manifest.packages ?? {};
+	if (Object.keys(packages).length === 0) return;
+	getOrCreateMap(extConfig, ["runtimeManifest"], { onBeforeCreate: (pair) => {
+		pair.key.spaceBefore = true;
+	} });
+	getOrCreateMap(extConfig, ["runtimeManifest", "packages"]);
+	for (const [name, pkg] of Object.entries(packages)) {
+		const packageDef = getOrCreateMap(extConfig, [
+			"runtimeManifest",
+			"packages",
+			name
+		], { onBeforeCreate: (pair) => {
+			pair.key.commentBefore = " This package definition is auto-generated. Do not remove or manually edit.";
+		} });
+		const existingActions = packageDef.get("actions");
+		const actions = new YAMLMap();
+		packageDef.set("license", pkg.license ?? "Apache-2.0");
+		packageDef.set("actions", actions);
+		for (const [actionName, action] of Object.entries(pkg.actions ?? {})) {
+			const existingAction = isMap(existingActions) ? existingActions.get(actionName) : void 0;
+			const actionDef = buildActionDefinition(action, isMap(existingAction) ? existingAction : void 0);
+			actions.set(actionName, actionDef);
+		}
+	}
+}
+/**
+* Build the `hooks` section of the `ext.config.yaml` file. Each given hook
+* replaces any previous value, while other hooks are left untouched.
+* @param extConfig - The ext.config.yaml file
+* @param hooks - The hooks to build, mapping hook names to JavaScript file paths
+*/
+function buildHooks(extConfig, hooks) {
+	const generatedHooks = `[${Object.keys(hooks).join(", ")}]`;
+	const hooksMap = getOrCreateMap(extConfig, ["hooks"], { onBeforeCreate: (pair) => {
+		pair.key.spaceBefore = true;
+		pair.key.commentBefore = ` The ${generatedHooks} hooks are auto-generated. Do not remove or manually edit.`;
+	} });
+	for (const [name, path] of Object.entries(hooks)) hooksMap.set(name, path);
+}
+/**
+* Write the ext.config.yaml file
+* @param configPath - The path to the ext.config.yaml file
+* @param config - The config to write
+*/
+async function writeExtConfig(configPath, doc) {
+	const yamlContent = doc.toString({
+		defaultStringType: "PLAIN",
+		indent: 2,
+		lineWidth: 0
+	});
+	await writeFile(configPath, yamlContent, "utf-8");
+}
+
+//#endregion
+//#region source/commands/generate/actions/lib.ts
+const ESBUILD_PACKAGE = "esbuild@0.28.0";
+const LEADING_DOT_SLASH_PATTERN$1 = /^\.\//u;
+/** The `@adobe/aio-commerce-lib-app/cli` call exported by each generated hook file. */
+const HOOK_HANDLER_CALLS = {
+	"post-app-deploy": () => "postAppDeploy()",
+	"pre-app-build": (extension) => `preAppBuild(${JSON.stringify(extension)})`,
+	"pre-app-dev": () => "preAppDev()",
+	"pre-app-run": () => "preAppRun()"
+};
+/** Normalize a path for use as an ESM import specifier. */
+function normalizeImportPath(path) {
+	const normalizedPath = path.split(sep).join("/");
+	return normalizedPath.startsWith(".") ? normalizedPath : `./${normalizedPath}`;
+}
+/** Normalize a generated file path for package.json imports. */
+function normalizePackageJsonPath$1(path) {
+	return normalizeImportPath(path).replace(LEADING_DOT_SLASH_PATTERN$1, "./");
+}
+/** Add or update the package import alias used by dynamic generated actions. */
+async function updateAppConfigImportAlias(projectRoot, runtimeConfigPath) {
+	const pkg = await loadPackageJson(projectRoot);
+	if (pkg === null) throw new Error("Could not find package.json.");
+	const existingImports = typeof pkg.content.imports === "object" && pkg.content.imports !== null ? pkg.content.imports : {};
+	pkg.update({ imports: {
+		...existingImports,
+		[APP_CONFIG_IMPORT_ALIAS]: normalizePackageJsonPath$1(runtimeConfigPath)
+	} });
+	await pkg.save();
+}
+/** Write an ESM passthrough module that re-exports an app config file. */
+async function writeJavaScriptAppConfigModule(configFilePath, outputPath) {
+	const configImportPath = normalizeImportPath(relative(dirname(outputPath), configFilePath));
+	const isJson = extname(configFilePath) === ".json";
+	const importAttributes = isJson ? " with { type: \"json\" }" : "";
+	const defaultExport = isJson ? `export default /** @type {import("@adobe/aio-commerce-lib-app/config").CommerceAppConfig} */ (appConfig);` : "export default appConfig;";
+	await writeFile(outputPath, [
+		"// This file has been auto-generated by `@adobe/aio-commerce-lib-app`",
+		"// Do not modify this file directly",
+		"",
+		`import appConfig from "${configImportPath}"${importAttributes};`,
+		"",
+		isJson ? null : `export * from "${configImportPath}";`,
+		defaultExport,
+		""
+	].filter((item) => item !== null).join("\n"), "utf-8");
+}
+/**
+* Bundles a TypeScript app config file into runtime-safe ESM.
+* @param configFilePath - Source TypeScript app config path.
+* @param outputPath - Generated ESM module path.
+* @param projectRoot - Resolved project root used to run the bundler.
+*/
+async function bundleTypeScriptAppConfigModule(configFilePath, outputPath, projectRoot) {
+	const packageManager = await detectPackageManager(projectRoot);
+	const { command, args } = getPackageExecutionCommand(packageManager, [
+		ESBUILD_PACKAGE,
+		configFilePath,
+		"--bundle",
+		"--format=esm",
+		"--log-level=silent",
+		`--outfile=${outputPath}`,
+		"--packages=external",
+		"--platform=node",
+		"--target=node22"
+	], { allowBuild: "esbuild" });
+	const result = spawnSync(command, args, {
+		cwd: projectRoot,
+		stdio: "inherit"
+	});
+	if (result.error || result.status !== 0) throw new Error(`Could not bundle the TypeScript app config with ${ESBUILD_PACKAGE}.`, { cause: result.error ?? /* @__PURE__ */ new Error(`Bundle command exited with code ${result.status}`) });
+}
+/**
+* Write an ESM module that re-exports the static app manifest JSON so generated
+* actions can import it via the alias without needing a JSON import attribute.
+* @param projectRoot - Resolved project root where the module is generated.
+*/
+async function prepareStaticAppConfigImportAlias(projectRoot) {
+	const runtimeConfigPath = getRuntimeAppConfigPath();
+	const outputPath = join(projectRoot, runtimeConfigPath);
+	await makeOutputDirFor(dirname(runtimeConfigPath), projectRoot);
+	await writeJavaScriptAppConfigModule(join(projectRoot, getManifestPath()), outputPath);
+}
+/**
+* Prepare the runtime config module consumed by generated actions and its
+* `#app.commerce.config` package import alias.
+*
+* TypeScript configs are bundled into a generated runtime module. JavaScript
+* configs use a passthrough module, while serializable default-only configs use
+* a re-export of the validated JSON manifest.
+* @param appManifest - App configuration used to select the module format.
+* @param projectRoot - Resolved project root where the module is generated.
+*/
+async function prepareRuntimeAppConfigModule(appManifest, projectRoot) {
+	const configFilePath = await resolveCommerceAppConfig(projectRoot);
+	if (await requiresJavaScriptAppConfig(appManifest, projectRoot)) {
+		if (configFilePath === null) throw new Error("Generating a runtime config module requires an app.commerce.config.* file.");
+		await makeOutputDirFor(dirname(getRuntimeAppConfigPath()), projectRoot);
+		const outputPath = join(projectRoot, getRuntimeAppConfigPath());
+		if (isTypeScriptConfig(configFilePath)) await bundleTypeScriptAppConfigModule(configFilePath, outputPath, projectRoot);
+		else await writeJavaScriptAppConfigModule(configFilePath, outputPath);
+	} else await prepareStaticAppConfigImportAlias(projectRoot);
+	await updateAppConfigImportAlias(projectRoot, getRuntimeAppConfigPath());
+}
+/**
+* Reads an extension point's ext.config.yaml document and path.
+* @param extensionPointId - The extension point ID to read the config for.
+* @param projectRoot - Resolved project root containing the extension config.
+*/
+async function readExtConfig(extensionPointId, projectRoot) {
+	const extConfigPath = join(projectRoot, getExtConfigPath(extensionPointId));
+	try {
+		return {
+			doc: await readYamlFile(extConfigPath),
+			path: extConfigPath
+		};
+	} catch (error) {
+		const reason = error instanceof Error ? error.message : "Unexpected error while reading the file.";
+		throw new Error([
+			`Could not read ext.config.yaml for ${extensionPointId} at ${extConfigPath}.`,
+			`Make sure the file exists and is valid YAML. You can regenerate it with "aio-commerce-lib-app generate actions".`,
+			`Reason: ${reason}`
+		].join("\n"), { cause: error });
+	}
+}
+/**
+* Updates an extension point's ext.config.yaml with generated configuration.
+* @param appConfig - App configuration used to build the extension config.
+* @param extensionPointId - Extension point whose config is updated.
+* @param projectRoot - Resolved project root containing the extension config.
+*/
+async function updateExtConfig(appConfig, extensionPointId, projectRoot) {
+	consola.info(`Updating ext.config.yaml for ${extensionPointId}...`);
+	await makeOutputDirFor(getExtensionPointFolderPath(extensionPointId), projectRoot);
+	const { path: extConfigPath, doc: extConfigDoc } = await readExtConfig(extensionPointId, projectRoot);
+	let extConfig;
+	switch (extensionPointId) {
+		case EXTENSIBILITY_EXTENSION_POINT_ID:
+			extConfig = buildAppManagementExtConfig(appConfig);
+			break;
+		case CONFIGURATION_EXTENSION_POINT_ID:
+			extConfig = buildBusinessConfigurationExtConfig();
+			break;
+		case BACKEND_UI_V2_EXTENSION_POINT_ID:
+			extConfig = buildAdminUiV2ExtConfig(appConfig);
+			break;
+		default: throw new Error(`Unsupported extension point: ${extensionPointId}`);
+	}
+	await createOrUpdateExtConfig(extConfigPath, extConfig, extConfigDoc);
+	await writeHookFiles(Object.keys(extConfig.hooks ?? {}), extensionPointId, projectRoot);
+	return extConfig;
+}
+/**
+* Writes the CommonJS files that an extension point's `ext.config.yaml` hooks point to.
+* @param hookNames - Names of the hooks registered for the extension point.
+* @param extensionPointId - Extension point that owns the hooks.
+* @param projectRoot - Resolved project root where the files are generated.
+*/
+async function writeHookFiles(hookNames, extensionPointId, projectRoot) {
+	const extension = extensionPointId.replace("commerce/", "");
+	await Promise.all(hookNames.map(async (hookName) => {
+		const hookPath = getHookPath(extensionPointId, hookName);
+		const handlerCall = HOOK_HANDLER_CALLS[hookName](extension);
+		await makeOutputDirFor(dirname(hookPath), projectRoot);
+		await writeFile(join(projectRoot, hookPath), [
+			"// This file has been auto-generated by `@adobe/aio-commerce-lib-app`",
+			"// Do not modify this file directly",
+			"",
+			`module.exports = require("@adobe/aio-commerce-lib-app/cli").${handlerCall};`,
+			""
+		].join("\n"), "utf-8");
+	}));
+}
+/**
+* Generates runtime action files from templates.
+* @param appManifest - App configuration used to populate action templates.
+* @param actions - Runtime actions to generate.
+* @param extensionPointId - Extension point receiving the generated actions.
+* @param templatesDir - Directory containing action templates.
+* @param projectRoot - Resolved project root where actions are generated.
+*/
+async function generateActionFiles(appManifest, actions, extensionPointId, templatesDir, projectRoot) {
+	consola.start("Generating runtime actions...");
+	await makeOutputDirFor(getActionsDir(extensionPointId), projectRoot);
+	const outputFiles = await Promise.all(actions.map(async (action) => {
+		const templatePath = join(templatesDir, action.templateFile);
+		let template = await readFile(templatePath, "utf-8");
+		if (action.name === "installation") {
+			const customScriptsTemplatePath = join(templatesDir, "app-management", "custom-scripts.js.template");
+			const scriptsTemplate = await generateCustomScriptsTemplate(await readFile(customScriptsTemplatePath, "utf-8"), appManifest, projectRoot);
+			template = applyCustomScripts(template, scriptsTemplate);
+		}
+		const actionPath = join(projectRoot, getActionPath(extensionPointId, action.name));
+		await writeFile(actionPath, template, "utf-8");
+		return ` ${relative(projectRoot, actionPath)}`;
+	}));
+	consola.success(`Generated ${actions.length} action(s)`);
+	consola.log.raw(formatTree(outputFiles));
+}
+/**
+* Applies the given custom scripts template code to the given installation template.
+* @param installationTemplate - The installation code runtime action template
+* @param customScriptsTemplate - The custom scripts dynamically generated template.
+*/
+function applyCustomScripts(installationTemplate, customScriptsTemplate) {
+	if (customScriptsTemplate !== null) return installationTemplate.replace(CUSTOM_SCRIPTS_LOADER_PLACEHOLDER, customScriptsTemplate).replace("const args = { appConfig };", "const args = { appConfig, customScriptsLoader };");
+	consola.debug("No custom installation steps found, skipping custom-scripts.js generation...");
+	return installationTemplate.replace(CUSTOM_SCRIPTS_LOADER_PLACEHOLDER, "// No custom installation scripts configured");
+}
+/**
+* Generates installation code that imports configured custom scripts.
+* @param template - Custom scripts template content.
+* @param appManifest - App configuration containing custom installation steps.
+* @param projectRoot - Resolved project root used to resolve script paths.
+*/
+async function generateCustomScriptsTemplate(template, appManifest, projectRoot) {
+	if (!hasCustomInstallationSteps(appManifest)) return null;
+	const installationActionDir = join(projectRoot, getActionsDir(EXTENSIBILITY_EXTENSION_POINT_ID));
+	const customSteps = appManifest.installation.customInstallationSteps;
+	const importStatements = customSteps.map((step, index) => {
+		const absoluteScriptPath = join(projectRoot, step.script);
+		let relativeImportPath = relative(installationActionDir, absoluteScriptPath);
+		if (!relativeImportPath.startsWith(".")) relativeImportPath = `./${relativeImportPath}`;
+		relativeImportPath = relativeImportPath.replace(/\\/g, "/");
+		return `import * as ${`customScript${index}`} from "${relativeImportPath}";`;
+	}).join("\n");
+	const scriptMap = customSteps.map((step, index) => {
+		const entry = `"${step.script}": ${`customScript${index}`},`;
+		return entry.padStart(entry.length + 6);
+	}).join("\n");
+	return template.replace(CUSTOM_IMPORTS_PLACEHOLDER, importStatements).replace(CUSTOM_SCRIPTS_MAP_PLACEHOLDER, scriptMap);
+}
+
+//#endregion
+//#region source/commands/generate/manifest/main.ts
+/**
+* Generates or removes the static app manifest as required by the app config.
+* @param appConfig - Validated app configuration to serialize.
+* @param projectRoot - Resolved project root where the manifest is generated.
+*/
+async function run$1(appConfig, projectRoot) {
+	if (await requiresJavaScriptAppConfig(appConfig, projectRoot)) {
+		const stalePath = join(projectRoot, getManifestPath());
+		if (await access(stalePath).then(() => true, () => false)) {
+			await rm(stalePath, { force: true });
+			consola.success(`Removed stale ${APP_MANIFEST_FILE}`);
+		}
+		return;
+	}
+	consola.info("Generating app manifest...");
+	const contents = stringify$1(appConfig, null, 2);
+	const outputDir = await makeOutputDirFor(getGeneratedDir(EXTENSIBILITY_EXTENSION_POINT_ID), projectRoot);
+	const manifestPath = join(outputDir, APP_MANIFEST_FILE);
+	await writeFile(manifestPath, contents, "utf-8");
+	consola.success(`Generated ${APP_MANIFEST_FILE}\n`);
+}
+/** Run the generate manifest command */
+async function exec$1() {
+	try {
+		const projectRoot = await getProjectRootDirectory();
+		await run$1(await loadAppManifest(projectRoot), projectRoot);
+	} catch (error) {
+		if (error instanceof CommerceSdkValidationError) consola.error(error.display());
+		else consola.error(error);
+		process.exit(1);
+	}
+}
+
+//#endregion
+//#region ../../packages-private/scripting-utils/source/filesystem/helpers.ts
+/**
+* Touch a file, creating it if it doesn't exist.
+* @param filePath The path of the file to touch
+*/
+async function touch(filePath) {
+	await writeFile(filePath, "", { flag: "wx" }).catch((e) => {
+		if (e.code !== "EEXIST") throw e;
+	});
+}
+
+//#endregion
+//#region source/commands/generate/schema/main.ts
+/**
+* Generates the business configuration schema and prepares encryption when needed.
+* @param appConfig - Validated app configuration containing the schema.
+* @param projectRoot - Resolved project root where schema files are managed.
+*/
+async function run(appConfig, projectRoot) {
+	if (!hasBusinessConfigSchema(appConfig)) {
+		consola.debug("Business configuration schema not found in application configuration. Nothing to do.");
+		return;
+	}
+	const envPath = join(projectRoot, ".env");
+	await touch(envPath);
+	process.loadEnvFile(envPath);
+	if (appConfig.businessConfig.schema.some((field) => field.type === "password")) {
+		const packageExec = getExecCommand(await detectPackageManager(projectRoot));
+		if ("AIO_COMMERCE_CONFIG_ENCRYPTION_KEY" in process.env && String(process.env.AIO_COMMERCE_CONFIG_ENCRYPTION_KEY).trim().length > 0) execSync(`${packageExec} aio-commerce-lib-config encryption validate`);
+		else execSync(`${packageExec} aio-commerce-lib-config encryption setup`);
+	}
+	if (hasDynamicAppConfig(appConfig)) {
+		const stalePath = join(projectRoot, getSchemaPath());
+		if (await access(stalePath).then(() => true, () => false)) {
+			await rm(stalePath, { force: true });
+			consola.success(`Removed stale ${CONFIG_SCHEMA_FILE_NAME}`);
+		}
+		return;
+	}
+	consola.info("Generating configuration schema...");
+	const outputDir = await makeOutputDirFor(getGeneratedDir(CONFIGURATION_EXTENSION_POINT_ID), projectRoot);
+	const contents = stringify$1(appConfig.businessConfig.schema, null, 2);
+	const schemaPath = join(outputDir, CONFIG_SCHEMA_FILE_NAME);
+	await writeFile(schemaPath, contents, "utf-8");
+	consola.success(`Generated ${CONFIG_SCHEMA_FILE_NAME}\n`);
+}
+/** Run the generate schema command */
+async function exec() {
+	try {
+		const projectRoot = await getProjectRootDirectory();
+		await run(await loadAppManifest(projectRoot), projectRoot);
+	} catch (error) {
+		if (error instanceof CommerceSdkValidationError) consola.error(error.display());
+		else consola.error(error);
+		process.exit(1);
+	}
+}
+
+//#endregion
+//#region source/commands/typescript.ts
+const WEBPACK_CONFIG_PATTERN = /^webpack-config\.(?:cjs|js)$/u;
+const WEBPACK_CONFIG_FILE = "webpack-config.cjs";
+const TSCONFIG_FILE = "tsconfig.json";
+const ROOT_TYPESCRIPT_CONFIG = {
+	compilerOptions: {
+		allowJs: true,
+		checkJs: true,
+		module: "esnext",
+		moduleResolution: "bundler",
+		noEmit: true
+	},
+	exclude: ["src/**/web-src/**"],
+	extends: [
+		"@tsconfig/bases/recommended",
+		"@tsconfig/bases/node-ts",
+		"@tsconfig/bases/node24"
+	],
+	include: [
+		"src/**/.generated/actions/**/*.js",
+		"app.commerce.config.ts",
+		"app.commerce.config.mts",
+		"app.commerce.config.cts",
+		"src/**/*.ts",
+		"src/**/*.mts",
+		"src/**/*.cts"
+	]
+};
+const TYPESCRIPT_DEV_DEPENDENCIES = [
+	...SHARED_TYPESCRIPT_DEV_DEPENDENCIES,
+	TYPESCRIPT_NODE_DEV_DEPENDENCY,
+	TYPESCRIPT_WEBPACK_DEV_DEPENDENCY
+];
+const ACTIONS_TYPECHECK_SCRIPT = "typecheck:actions";
+const WEB_SOURCE_TYPECHECK_SCRIPT = "typecheck:web-src";
+const ACTIONS_TYPECHECK_COMMAND = "tsc --noEmit -p tsconfig.json";
+const WEB_SOURCE_TYPECHECK_COMMAND = `tsc --noEmit -p ${`${getExtensionPointFolderPath(BACKEND_UI_V2_EXTENSION_POINT_ID)}/web-src/tsconfig.json`}`;
+/**
+* Create the default Webpack configuration when the project has none.
+* @param projectRoot Project root directory.
+*/
+async function scaffoldWebpackConfig(projectRoot) {
+	const existingConfig = (await readdir(projectRoot, { withFileTypes: true })).find((entry) => entry.isFile() && WEBPACK_CONFIG_PATTERN.test(entry.name));
+	if (existingConfig !== void 0) {
+		consola.info(`Found ${existingConfig.name}; leaving it unchanged.`);
+		return;
+	}
+	await copyFile(join(TEMPLATES_DIR, "typescript", WEBPACK_CONFIG_FILE), join(projectRoot, WEBPACK_CONFIG_FILE));
+}
+/**
+* Create the Runtime actions TypeScript configuration when it does not exist.
+* @param projectRoot Project root directory.
+*/
+async function scaffoldTypeScriptConfig(projectRoot) {
+	const rootConfigPath = join(projectRoot, TSCONFIG_FILE);
+	if (!existsSync(rootConfigPath)) await writeFile(rootConfigPath, `${JSON.stringify(ROOT_TYPESCRIPT_CONFIG, null, 2)}\n`, "utf-8");
+}
+/**
+* Install missing TypeScript tooling after validating installed versions.
+* @param packageManager Package manager used by the project.
+* @param projectRoot Project root directory.
+*/
+async function installTypeScriptDependencies(packageManager, projectRoot) {
+	const installPlan = await getPackageDependencyInstallPlan(TYPESCRIPT_DEV_DEPENDENCIES, projectRoot);
+	if (installPlan.incompatible.length > 0) {
+		const dependencies = installPlan.incompatible.map(({ name, version, installedVersion }) => `${name}@${installedVersion} does not satisfy ${version}`).join("\n");
+		throw new Error(`Cannot configure TypeScript because installed dependencies are incompatible:\n${dependencies}`);
+	}
+	runInstall(packageManager, installPlan.missing.map(({ name, version }) => `${name}@${version}`), projectRoot, { dev: true });
+}
+/**
+* Scaffold the files and dependencies for a new TypeScript Commerce project.
+* @param packageManager Package manager used by the initialized project.
+* @param projectRoot Resolved project root.
+*/
+async function scaffoldTypeScriptProject(packageManager, projectRoot) {
+	await scaffoldWebpackConfig(projectRoot);
+	await scaffoldTypeScriptConfig(projectRoot);
+	await installTypeScriptDependencies(packageManager, projectRoot);
+}
+/**
+* Add a generated typecheck script and compose it into the root typecheck script.
+* @param scriptName Generated package script name.
+* @param command TypeScript command run by the generated script.
+* @param projectRoot Resolved project root.
+*/
+async function syncTypecheckScript(scriptName, command, projectRoot) {
+	const pkg = await loadPackageJson(projectRoot);
+	if (pkg === null) throw new Error("Could not find package.json.");
+	const scripts = {
+		...pkg.content.scripts,
+		[scriptName]: command
+	};
+	const packageManager = await detectPackageManager(projectRoot);
+	const typecheck = appendCommand(scripts.typecheck, getRunScriptCommand(packageManager, scriptName));
+	pkg.update({ scripts: {
+		...scripts,
+		typecheck
+	} });
+	await pkg.save();
+}
+/**
+* Add the Runtime actions typecheck script to a project.
+* @param projectRoot Resolved project root.
+*/
+async function syncActionsTypecheckScript(projectRoot) {
+	await syncTypecheckScript(ACTIONS_TYPECHECK_SCRIPT, ACTIONS_TYPECHECK_COMMAND, projectRoot);
+}
+/**
+* Add the web-src typecheck script to a project.
+* @param projectRoot Resolved project root.
+*/
+async function syncWebSourceTypecheckScript(projectRoot) {
+	await syncTypecheckScript(WEB_SOURCE_TYPECHECK_SCRIPT, WEB_SOURCE_TYPECHECK_COMMAND, projectRoot);
+}
+
+//#endregion
+//#region source/commands/generate/web-src.ts
+const JSX_FILE_EXTENSION = ".jsx";
+const TSX_FILE_EXTENSION = ".tsx";
+const APP_TITLE_PLACEHOLDER = "APP_TITLE";
+const WEB_SOURCE_ENTRYPOINT_FILE = "index.html";
+const WEB_SOURCE_IMPORT_ALIAS = "#web/*";
+const WEB_SOURCE_REQUIRED_FILES = [".babelrc"];
+const WEB_SOURCE_TSCONFIG_FILE = "tsconfig.json";
+const LEADING_DOT_SLASH_PATTERN = /^\.\//u;
+/** Runtime dependencies required by the generated web-src app. */
+const WEB_SOURCE_DEPENDENCIES = [
+	{
+		name: "@adobe/aio-commerce-lib-admin-ui",
+		version: "^1.1.0"
+	},
+	{
+		name: "react",
+		version: "^19.2.7"
+	},
+	{
+		name: "react-dom",
+		version: "^19.2.7"
+	},
+	{
+		name: "@react-spectrum/s2",
+		version: "^1.5.1"
+	}
+];
+const WEB_SOURCE_BABEL_DEV_DEPENDENCIES = [{
+	name: "@babel/core",
+	version: "^7.29.7"
+}, {
+	name: "@babel/preset-react",
+	version: "^7.29.7"
+}];
+/** Development dependencies required by the generated web-src app. */
+const WEB_SOURCE_DEV_DEPENDENCIES = [
+	...WEB_SOURCE_BABEL_DEV_DEPENDENCIES,
+	{
+		name: "@types/react",
+		version: "^19.2.17"
+	},
+	{
+		name: "@types/react-dom",
+		version: "^19.2.3"
+	}
+];
+const WEB_SOURCE_REQUIRED_DEV_DEPENDENCIES = WEB_SOURCE_BABEL_DEV_DEPENDENCIES;
+const WEB_SOURCE_SHARED_BUNDLES = [{
+	assets: ["**/@react-spectrum/s2/**", "src/commerce-backend-ui-2/web-src/*.{js,jsx,ts,tsx}"],
+	name: "s2-styles",
+	types: ["css"]
+}];
+const WEB_SOURCE_TYPESCRIPT_CONFIG = {
+	compilerOptions: {
+		allowImportingTsExtensions: true,
+		allowJs: true,
+		checkJs: true,
+		jsx: "react-jsx",
+		jsxImportSource: "react",
+		module: "esnext",
+		moduleResolution: "bundler",
+		noEmit: true,
+		rewriteRelativeImportExtensions: false
+	},
+	extends: ["@tsconfig/bases/recommended"],
+	include: [
+		"src/**/*.js",
+		"src/**/*.ts",
+		"src/**/*.tsx",
+		"src/**/*.jsx"
+	]
+};
+/** Normalize a generated file path for package.json imports. */
+function normalizePackageJsonPath(path) {
+	const normalizedPath = path.split(sep).join("/");
+	return (normalizedPath.startsWith(".") ? normalizedPath : `./${normalizedPath}`).replace(LEADING_DOT_SLASH_PATTERN, "./");
+}
+/**
+* Resolve the generated web-src entrypoint path from an extension config.
+* @param extConfig - Extension config containing the view operation.
+*/
+function getWebSourceEntrypoint(extConfig) {
+	const viewEntrypoint = extConfig.operations?.view?.[0]?.impl;
+	if (viewEntrypoint === void 0) return null;
+	return join(getExtensionPointFolderPath(BACKEND_UI_V2_EXTENSION_POINT_ID), extConfig.web ?? "web-src", viewEntrypoint);
+}
+/**
+* Ensure package.json has the dependencies and Parcel config needed by web-src.
+* @param projectRoot - Resolved project root containing package.json.
+* @param extension - Web source extension whose tooling is configured.
+*/
+async function prepareWebSourcePackage(projectRoot, extension, scaffoldRequired) {
+	const pkg = await loadPackageJson(projectRoot);
+	if (pkg === null) throw new Error("Could not find package.json.");
+	const dependencies = scaffoldRequired ? WEB_SOURCE_DEPENDENCIES : [];
+	const requiredDevDependencies = scaffoldRequired ? [...WEB_SOURCE_DEV_DEPENDENCIES, ...extension === "tsx" ? SHARED_TYPESCRIPT_DEV_DEPENDENCIES : []] : WEB_SOURCE_REQUIRED_DEV_DEPENDENCIES;
+	const installPlan = await getPackageDependencyInstallPlan([...dependencies, ...requiredDevDependencies], projectRoot);
+	if (installPlan.incompatible.length > 0) {
+		const incompatibleDependencies = installPlan.incompatible.map(({ name, version, installedVersion }) => `${name}@${installedVersion} does not satisfy ${version}`).join("\n");
+		throw new Error(`Cannot scaffold web-src because installed dependencies are incompatible:\n${incompatibleDependencies}`);
+	}
+	const existingDependencies = pkg.content.dependencies ?? {};
+	const devDependencies = pkg.content.devDependencies ?? {};
+	const dependencyMaps = [existingDependencies, devDependencies];
+	const declaredDependencyNames = new Set(dependencyMaps.flatMap((depMap) => Object.keys(depMap)));
+	const dependenciesToDeclare = [...dependencies, ...requiredDevDependencies].filter(({ name }) => !declaredDependencyNames.has(name));
+	if (dependenciesToDeclare.length > 0) {
+		consola.info("Adding web-src dependencies in package.json:");
+		consola.log.raw(formatTree(dependenciesToDeclare.map(({ name, version }) => ` ${name}@${version}`)));
+	} else consola.info("web-src dependencies are already declared in package.json.");
+	pkg.update({
+		...scaffoldRequired && {
+			"@parcel/bundler-default": {
+				...pkg.content["@parcel/bundler-default"],
+				manualSharedBundles: WEB_SOURCE_SHARED_BUNDLES
+			},
+			"@parcel/resolver-default": {
+				...pkg.content["@parcel/resolver-default"],
+				packageExports: true
+			},
+			dependencies: mergePackageJsonDependencies(existingDependencies, WEB_SOURCE_DEPENDENCIES, dependencyMaps)
+		},
+		devDependencies: mergePackageJsonDependencies(devDependencies, requiredDevDependencies, dependencyMaps)
+	});
+	await pkg.save();
+	if (installPlan.missing.length === 0) {
+		consola.info("web-src dependencies are already installed.");
+		return;
+	}
+	consola.info("Installing missing web-src dependencies from package.json:");
+	consola.log.raw(formatTree(installPlan.missing.map(({ name, version }) => ` ${name}@${version}`)));
+	const packageManager = await detectPackageManager(projectRoot);
+	runProjectInstall(packageManager, projectRoot);
+}
+/**
+* Copies required web-src support files that are not already present.
+* @param sourceDir - Directory containing required web source files.
+* @param targetDir - Generated or existing web source directory.
+* @param projectRoot - Resolved project root used to format output paths.
+*/
+async function copyMissingWebSourceFiles(sourceDir, targetDir, projectRoot) {
+	return (await Promise.all(WEB_SOURCE_REQUIRED_FILES.map(async (file) => {
+		const targetPath = join(targetDir, file);
+		if (existsSync(targetPath)) return null;
+		await copyFile(join(sourceDir, file), targetPath, constants.COPYFILE_EXCL);
+		return ` ${relative(projectRoot, targetPath)}`;
+	}))).filter((path) => path !== null);
+}
+/**
+* Add the package import alias for an existing or generated web-src.
+* @param extConfig - Extension config containing the view operation.
+* @param projectRoot - Resolved project root containing package.json.
+*/
+async function prepareWebSourceImportAlias(extConfig, projectRoot) {
+	const entrypoint = getWebSourceEntrypoint(extConfig);
+	if (entrypoint === null) return;
+	const pkg = await loadPackageJson(projectRoot);
+	if (pkg === null) throw new Error("Could not find package.json.");
+	const existingImports = typeof pkg.content.imports === "object" && pkg.content.imports !== null ? pkg.content.imports : {};
+	const webSourceSrcPath = join(dirname(entrypoint), "src");
+	pkg.update({ imports: {
+		...existingImports,
+		[WEB_SOURCE_IMPORT_ALIAS]: `${normalizePackageJsonPath(webSourceSrcPath)}/*`
+	} });
+	await pkg.save();
+}
+/** Resolve the generated web-src file extension from the app config file type. */
+async function resolveWebSourceExtension(projectRoot) {
+	const configFilePath = await resolveCommerceAppConfig(projectRoot);
+	return configFilePath !== null && isTypeScriptConfig(configFilePath) ? "tsx" : "jsx";
+}
+async function writeWebSourceTypeScriptConfig(targetDir) {
+	const tsconfigPath = join(targetDir, WEB_SOURCE_TSCONFIG_FILE);
+	await writeFile(tsconfigPath, `${JSON.stringify(WEB_SOURCE_TYPESCRIPT_CONFIG, null, 2)}\n`, "utf-8");
+	return tsconfigPath;
+}
+/**
+* Resolve the destination path for a web-src template file.
+* @param templatePath - Template file path relative to its source directory.
+* @param extension - Web source extension to generate.
+*/
+function getWebSourceTemplateTargetPath(templatePath, extension) {
+	if (extension === "jsx" || !templatePath.endsWith(JSX_FILE_EXTENSION)) return templatePath;
+	return `${templatePath.slice(0, -4)}${TSX_FILE_EXTENSION}`;
+}
+/**
+* Copy web-src templates directly to the final file extension and entrypoint.
+* @param sourceDir - Template web-src directory.
+* @param targetDir - Generated web-src directory.
+* @param extension - Web source extension to generate.
+* @param appTitle - Application title used by the entrypoint template.
+* @param projectRoot - Resolved project root used to format output paths.
+*/
+async function copyWebSourceTemplates(sourceDir, targetDir, extension, appTitle, projectRoot) {
+	await mkdir(targetDir, { recursive: true });
+	const entries = await readdir(sourceDir, { withFileTypes: true });
+	return (await Promise.all(entries.map(async (entry) => {
+		const sourcePath = join(sourceDir, entry.name);
+		const targetPath = join(targetDir, getWebSourceTemplateTargetPath(entry.name, extension));
+		if (entry.isDirectory()) return await copyWebSourceTemplates(sourcePath, targetPath, extension, appTitle, projectRoot);
+		let content = await readFile(sourcePath, "utf-8");
+		if (extension === "tsx") content = content.replaceAll(`${JSX_FILE_EXTENSION}"`, `${TSX_FILE_EXTENSION}"`);
+		if (targetPath.endsWith(WEB_SOURCE_ENTRYPOINT_FILE)) content = content.replaceAll(APP_TITLE_PLACEHOLDER, appTitle);
+		await writeFile(targetPath, content, {
+			encoding: "utf-8",
+			flag: "wx"
+		});
+		return ` ${relative(projectRoot, targetPath)}`;
+	}))).flat();
+}
+/**
+* Generates the web source scaffold for an iframe-based Admin UI extension.
+* @param extConfig - Extension config containing the web entrypoint.
+* @param appName - Application name inserted into the generated entrypoint.
+* @param projectRoot - Resolved project root where web source is generated.
+* @param templatesDir - Directory containing web source templates.
+*/
+async function generateWebSrc(extConfig, appName, projectRoot, templatesDir = TEMPLATES_DIR) {
+	const entrypoint = getWebSourceEntrypoint(extConfig);
+	if (entrypoint === null) return;
+	const entrypointPath = join(projectRoot, entrypoint);
+	const scaffoldRequired = !existsSync(entrypointPath);
+	const targetDir = dirname(entrypointPath);
+	const extension = await resolveWebSourceExtension(projectRoot);
+	const sourceDir = join(templatesDir, "admin-ui", "web-src");
+	let outputFiles = [];
+	if (scaffoldRequired) {
+		consola.start(`Scaffolding web-src for ${BACKEND_UI_V2_EXTENSION_POINT_ID}...`);
+		outputFiles = await copyWebSourceTemplates(sourceDir, targetDir, extension, appName, projectRoot);
+		if (extension === "tsx") {
+			const tsconfigPath = await writeWebSourceTypeScriptConfig(targetDir);
+			outputFiles.push(` ${relative(projectRoot, tsconfigPath)}`);
+			await syncWebSourceTypecheckScript(projectRoot);
+		}
+	} else consola.info(`web-src entrypoint already exists, skipping scaffold: ${relative(projectRoot, entrypointPath)}`);
+	const requiredFiles = await copyMissingWebSourceFiles(sourceDir, targetDir, projectRoot);
+	if (scaffoldRequired || requiredFiles.length > 0) await prepareWebSourcePackage(projectRoot, extension, scaffoldRequired);
+	if (scaffoldRequired) {
+		consola.success(`Scaffolded ${relative(projectRoot, targetDir)}`);
+		consola.log.raw(formatTree([...outputFiles, ...requiredFiles]));
+	} else if (requiredFiles.length > 0) {
+		consola.success(`Added required files to ${relative(projectRoot, targetDir)}`);
+		consola.log.raw(formatTree(requiredFiles));
+	}
+}
+
+//#endregion
+export { COMMERCE_APP_CONFIG_FILE as C, PACKAGE_JSON_FILE as D, INSTALL_YAML_FILE as E, TEMPLATES_DIR as O, BACKEND_UI_V2_EXTENSION_POINT_ID as S, EXTENSIBILITY_EXTENSION_POINT_ID as T, getExtConfigPath as _, exec as a, runInstall as b, run$1 as c, readExtConfig as d, updateExtConfig as f, getRuntimeActions as g, readYamlFile as h, syncActionsTypecheckScript as i, generateActionFiles as l, getOrCreateSeq as m, prepareWebSourceImportAlias as n, run as o, getOrCreateMap as p, scaffoldTypeScriptProject as r, exec$1 as s, generateWebSrc as t, prepareRuntimeAppConfigModule as u, loadAppManifest as v, CONFIGURATION_EXTENSION_POINT_ID as w, APP_CONFIG_FILE as x, prettierFormat as y };