@adobe/aio-commerce-lib-app 2.0.0 → 2.1.0-alpha-20260923164312

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @adobe/aio-commerce-lib-app
 
+## 2.1.0-alpha-20260923164312
+
+### Minor Changes
+
+- [#701](https://github.com/adobe/aio-commerce-sdk/pull/701) [`e63e960`](https://github.com/adobe/aio-commerce-sdk/commit/e63e96013a3592556c531ea27a334090b01e4269) Thanks [@iivvaannxx](https://github.com/iivvaannxx)! - Run your own code in the generated `pre-app-build`, `pre-app-run`, `pre-app-dev` and `post-app-deploy` hooks by adding a `hooks/<hook>` file at the project root, or under an extension point folder to override it for that extension point.
+
+### Patch Changes
+
+- [#701](https://github.com/adobe/aio-commerce-sdk/pull/701) [`64f0db4`](https://github.com/adobe/aio-commerce-sdk/commit/64f0db432cc70824955fe208b510e47bce7b7938) Thanks [@iivvaannxx](https://github.com/iivvaannxx)! - Apps now use the correct `NODE_ENV` on every `aio app run`, `aio app dev` and `aio app build`, and a failing hook stops the command. The hooks in generated `ext.config.yaml` files now point to generated JavaScript files.
+
 ## 2.0.0
 
 ### Major Changes

package/README.md

@@ -14,6 +14,10 @@ npm install @adobe/aio-commerce-lib-app
 
 See the [Usage Guide](./docs/usage.md) for more information.
 
+## Internal Entrypoints
+
+The `@adobe/aio-commerce-lib-app/cli` entrypoint is internal. It only exists for the code this package generates (the App Builder hook files under `.generated/hooks/`), so don't import it directly. Changes to it do not follow semantic versioning.
+
 ## Contributing
 
 This package is part of the Adobe Commerce SDK monorepo. Refer to the [Contributing Guide](https://github.com/adobe/aio-commerce-sdk/blob/main/.github/CONTRIBUTING.md) and [Development Guide](https://github.com/adobe/aio-commerce-sdk/blob/main/.github/DEVELOPMENT.md) for information on development setup and guidelines.

package/dist/cjs/actions/app-config/index.cjs

@@ -15,13 +15,13 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 const require_rolldown_runtime = require('../../rolldown-runtime-CDQd2xEI.cjs');
 const require_environment = require('../../environment-B6533pAY.cjs');
-const require_validate = require('../../validate-CwWYtRsS.cjs');
+const require_validate = require('../../validate-DkmBVWFX.cjs');
 const require_router = require('../../router-CxDTb6r1.cjs');
 let _adobe_aio_commerce_lib_config = require("@adobe/aio-commerce-lib-config");
+let _adobe_aio_commerce_lib_core_responses = require("@adobe/aio-commerce-lib-core/responses");
 let valibot = require("valibot");
 valibot = require_rolldown_runtime.__toESM(valibot, 1);
 let _adobe_aio_commerce_lib_core_commerce = require("@adobe/aio-commerce-lib-core/commerce");
-let _adobe_aio_commerce_lib_core_responses = require("@adobe/aio-commerce-lib-core/responses");
 let crypto = require("crypto");
 
 //#region source/actions/app-config/openapi.ts
@@ -80,7 +80,7 @@ function pruneUnusedTags(spec) {
 * @param domains - The active config domains.
 */
 function getOpenApiCacheKey(domains) {
-	const input = `2.0.0:${[...domains].sort().join(",")}:3.0.0`;
+	const input = `2.1.0-alpha-20260923164312:${[...domains].sort().join(",")}:3.0.0`;
 	return (0, crypto.createHash)("sha256").update(input).digest("hex").slice(0, 8);
 }
 /** Returns the server URL to be set in the OpenAPI spec, based on the current namespace. */

package/dist/cjs/actions/association/index.cjs

@@ -16,10 +16,10 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 const require_rolldown_runtime = require('../../rolldown-runtime-CDQd2xEI.cjs');
 const require_repository = require('../../repository-CbceYZqc.cjs');
 const require_router = require('../../router-CxDTb6r1.cjs');
+let _adobe_aio_commerce_lib_core_responses = require("@adobe/aio-commerce-lib-core/responses");
 let valibot = require("valibot");
 valibot = require_rolldown_runtime.__toESM(valibot, 1);
 let _adobe_aio_commerce_lib_core_commerce = require("@adobe/aio-commerce-lib-core/commerce");
-let _adobe_aio_commerce_lib_core_responses = require("@adobe/aio-commerce-lib-core/responses");
 
 //#region source/actions/association/schema.ts
 /** Request body for POST / — store association data. */

package/dist/cjs/actions/config/index.cjs

@@ -18,10 +18,10 @@ const require_schemas = require('../../schemas-3e49M8zz.cjs');
 const require_environment = require('../../environment-B6533pAY.cjs');
 const require_router = require('../../router-CxDTb6r1.cjs');
 let _adobe_aio_commerce_lib_config = require("@adobe/aio-commerce-lib-config");
+let _adobe_aio_commerce_lib_core_responses = require("@adobe/aio-commerce-lib-core/responses");
 let valibot = require("valibot");
 valibot = require_rolldown_runtime.__toESM(valibot, 1);
 let _adobe_aio_commerce_lib_core_commerce = require("@adobe/aio-commerce-lib-core/commerce");
-let _adobe_aio_commerce_lib_core_responses = require("@adobe/aio-commerce-lib-core/responses");
 
 //#region source/actions/config/schema.ts
 const AcceptedConfigurationValuesSchema = valibot.union([

package/dist/cjs/actions/installation/index.cjs

@@ -15,15 +15,15 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 const require_rolldown_runtime = require('../../rolldown-runtime-CDQd2xEI.cjs');
 const require_repository = require('../../repository-CbceYZqc.cjs');
+const require_common = require('../../common-B3KrOG-h.cjs');
+const require_management = require('../../management-DplOGozL.cjs');
 const require_schemas = require('../../schemas-3e49M8zz.cjs');
-const require_validate = require('../../validate-CwWYtRsS.cjs');
-const require_common = require('../../common-VSsQEHDv.cjs');
-const require_management = require('../../management-Bki3hlxL.cjs');
+const require_validate = require('../../validate-DkmBVWFX.cjs');
 const require_router = require('../../router-CxDTb6r1.cjs');
+let _adobe_aio_commerce_lib_core_responses = require("@adobe/aio-commerce-lib-core/responses");
 let valibot = require("valibot");
 valibot = require_rolldown_runtime.__toESM(valibot, 1);
 let _adobe_aio_commerce_lib_core_commerce = require("@adobe/aio-commerce-lib-core/commerce");
-let _adobe_aio_commerce_lib_core_responses = require("@adobe/aio-commerce-lib-core/responses");
 let openwhisk = require("openwhisk");
 openwhisk = require_rolldown_runtime.__toESM(openwhisk, 1);
 

package/dist/cjs/actions/scope-tree/index.cjs

@@ -15,14 +15,15 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 const require_rolldown_runtime = require('../../rolldown-runtime-CDQd2xEI.cjs');
 const require_schemas = require('../../schemas-3e49M8zz.cjs');
-const require_logging = require('../../logging-Br3xfBNe.cjs');
+const require_constants = require('../../constants-tQUzmimN.cjs');
+const require_logging = require('../../logging-QTsrSwPc.cjs');
 const require_router = require('../../router-CxDTb6r1.cjs');
 let _adobe_aio_commerce_lib_api = require("@adobe/aio-commerce-lib-api");
 let _adobe_aio_commerce_lib_config = require("@adobe/aio-commerce-lib-config");
+let _adobe_aio_commerce_lib_core_responses = require("@adobe/aio-commerce-lib-core/responses");
 let valibot = require("valibot");
 valibot = require_rolldown_runtime.__toESM(valibot, 1);
 let _adobe_aio_commerce_lib_core_commerce = require("@adobe/aio-commerce-lib-core/commerce");
-let _adobe_aio_commerce_lib_core_responses = require("@adobe/aio-commerce-lib-core/responses");
 
 //#region source/actions/scope-tree/schema.ts
 const CustomScopeInputSchema = valibot.object({
@@ -104,7 +105,7 @@ router.post("/commerce", {
 		};
 		const commerceConfig = (0, _adobe_aio_commerce_lib_api.resolveCommerceHttpClientParams)(paramsWithCommerceConfig, { tryForwardAuthProvider: true });
 		commerceConfig.fetchOptions ??= {};
-		commerceConfig.fetchOptions.timeout = require_logging.LIFECYCLE_HTTP_CLIENT_TIMEOUT_MS;
+		commerceConfig.fetchOptions.timeout = require_constants.LIFECYCLE_HTTP_CLIENT_TIMEOUT_MS;
 		const result = await (0, _adobe_aio_commerce_lib_config.syncCommerceScopes)(commerceConfig);
 		if (result.error) {
 			logger.error(`Error syncing commerce scopes: ${require_logging.inspect(result.error)}`);

package/dist/cjs/cli/index.cjs

@@ -0,0 +1,447 @@
+/**
+ * @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.
+ */
+
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_rolldown_runtime = require('../rolldown-runtime-CDQd2xEI.cjs');
+const require_index_node = require('../index.node-De5ENMF8.cjs');
+const require_web_src = require('../web-src-DvGBiJI5.cjs');
+const require_common = require('../common-B3KrOG-h.cjs');
+const require_webhooks = require('../webhooks-zXjrg32x.cjs');
+let _adobe_aio_commerce_lib_core_error = require("@adobe/aio-commerce-lib-core/error");
+let fs = require("fs");
+let path = require("path");
+path = require_rolldown_runtime.__toESM(path, 1);
+let consola = require("consola");
+consola = require_rolldown_runtime.__toESM(consola, 1);
+let _adobe_aio_lib_ims = require("@adobe/aio-lib-ims");
+_adobe_aio_lib_ims = require_rolldown_runtime.__toESM(_adobe_aio_lib_ims, 1);
+let _adobe_aio_lib_core_config = require("@adobe/aio-lib-core-config");
+_adobe_aio_lib_core_config = require_rolldown_runtime.__toESM(_adobe_aio_lib_core_config, 1);
+let consola_utils = require("consola/utils");
+let ky = require("ky");
+ky = require_rolldown_runtime.__toESM(ky, 1);
+let valibot = require("valibot");
+valibot = require_rolldown_runtime.__toESM(valibot, 1);
+let timers_promises = require("timers/promises");
+let dotenv = require("dotenv");
+dotenv = require_rolldown_runtime.__toESM(dotenv, 1);
+
+//#region ../../packages-private/scripting-utils/source/aio/auth.ts
+const { context: context$1, getToken } = _adobe_aio_lib_ims.default;
+/** Gets an IMS access token for the current CLI IMS context. */
+async function getUserToken() {
+	const contextName = await context$1.getCurrent() ?? "cli";
+	return getToken(contextName, {});
+}
+
+//#endregion
+//#region ../../packages-private/scripting-utils/source/aio/context.ts
+/**
+* Reads the current App Builder project and Runtime namespace from the local AIO CLI config.
+* @throws If either the project or the runtime namespace is not configured.
+*/
+function getAioProjectContext() {
+	const project = _adobe_aio_lib_core_config.default.get("project");
+	const namespace = _adobe_aio_lib_core_config.default.get("runtime.namespace");
+	if (!(project && namespace)) throw new Error("The current App Builder project and Runtime namespace are required");
+	return {
+		namespace,
+		project
+	};
+}
+/** Reads the configured AIO CLI environment, defaulting to `"prod"`. */
+function getAioCliEnv() {
+	return _adobe_aio_lib_core_config.default.get("cli.env") === "stage" ? "stage" : "prod";
+}
+
+//#endregion
+//#region source/commands/hooks/post-app-deploy/polling.ts
+const POLL_INTERVAL_MS = 1e3;
+const UpgradeStateSchema = valibot.object({
+	failure: valibot.optional(valibot.object({
+		key: valibot.string(),
+		message: valibot.optional(valibot.string())
+	})),
+	id: valibot.string(),
+	status: valibot.picklist([
+		"pending",
+		"in-progress",
+		"succeeded",
+		"failed"
+	])
+});
+/** Reads the latest upgrade state from the installation action. */
+async function getUpgradeState(request) {
+	try {
+		const response = await ky.default.get(request.endpoint, { headers: request.headers });
+		if (response.status === 204) return null;
+		const parsed = valibot.safeParse(UpgradeStateSchema, await response.json());
+		return parsed.success ? parsed.output : null;
+	} catch (error) {
+		consola.consola.debug("Unable to read upgrade status; stopping upgrade polling.", { error });
+		return null;
+	}
+}
+/** Waits for an automatic upgrade when its status remains available. */
+async function waitForAutomaticUpgrade(request) {
+	const state = await getUpgradeState(request);
+	if (!state) return;
+	if (state.status === "succeeded") {
+		consola.consola.success("App upgrade completed.\n");
+		return;
+	}
+	if (state.status === "failed") {
+		const reason = state.failure?.message ?? state.failure?.key ?? "The lifecycle attempt failed";
+		throw new Error(`App upgrade failed: ${reason}`);
+	}
+	consola.consola.start("App upgrade is in progress...");
+	await (0, timers_promises.setTimeout)(POLL_INTERVAL_MS);
+	return waitForAutomaticUpgrade(request);
+}
+
+//#endregion
+//#region source/commands/hooks/post-app-deploy/main.ts
+/** Returns true for a no-op reason defined by the upgrade API contract. */
+function isSkippedReason(reason) {
+	return reason === "already-current" || reason === "not-associated" || reason === "not-installed";
+}
+/** Returns true if the result indicates that the upgrade was skipped. */
+function isSkippedResult(result) {
+	return "skipped" in result;
+}
+/** Invokes the upgrade action. */
+async function createUpgradeRequest() {
+	const { project, namespace } = getAioProjectContext();
+	const token = await getUserToken();
+	const endpoint = `https://${namespace}.adobeioruntime.net/api/v1/web/app-management/installation`;
+	const ioEventsEnv = getAioCliEnv();
+	const ioEventsUrl = ioEventsEnv === "stage" ? "https://events-stage.adobe.io" : "https://events.adobe.io";
+	return {
+		body: {
+			appData: {
+				consumerOrgId: project.org.id,
+				orgName: project.org.name,
+				projectId: project.id,
+				projectName: project.name,
+				projectTitle: project.title,
+				workspaceId: project.workspace.id,
+				workspaceName: project.workspace.name,
+				workspaceTitle: project.workspace.title
+			},
+			ioEventsEnv,
+			ioEventsUrl
+		},
+		endpoint,
+		headers: {
+			Authorization: `Bearer ${token}`,
+			[require_common.INSTALLATION_INVOCATION_SOURCE_HEADER]: require_common.POST_APP_DEPLOY_INVOCATION_SOURCE,
+			"x-gw-ims-org-id": project.org.ims_org_id
+		}
+	};
+}
+/** Invokes the upgrade action. */
+async function invokeAction(request) {
+	consola.consola.debug(`Upgrade endpoint: ${request.endpoint}`);
+	try {
+		return await ky.default.post(request.endpoint, {
+			headers: request.headers,
+			json: request.body
+		}).json();
+	} catch (error) {
+		if (error instanceof ky.HTTPError) {
+			const details = await error.response.json();
+			if (error.response.status === 409 && isSkippedReason(details.reason)) return {
+				reason: details.reason,
+				skipped: true
+			};
+			throw new Error(`Failed to trigger app upgrade (HTTP ${error.response.status}): ${JSON.stringify(details, null, 2)}`, { cause: error });
+		}
+		throw error;
+	}
+}
+/** Invokes the deployed app's upgrade endpoint. */
+async function run$3() {
+	const { upgradeMode } = (await require_index_node.parseCommerceAppConfig()).metadata;
+	consola.consola.log("");
+	consola.consola.start("Checking for app upgrades...");
+	const request = await createUpgradeRequest();
+	const result = await invokeAction(request);
+	if (isSkippedResult(result)) {
+		consola.consola.info(`No upgrade was run: ${result.reason}.\n`);
+		return result;
+	}
+	if (upgradeMode === "manual") consola.consola.success(`You have set ${consola_utils.colors.cyan("metadata.upgradeMode")} to ${consola_utils.colors.cyan("manual")}. The upgrade plan has been created but will not be executed.`);
+	else consola.consola.success(`You have set ${consola_utils.colors.cyan("metadata.upgradeMode")} to ${consola_utils.colors.cyan("auto")}. The upgrade plan has been created. Execution will begin shortly.`);
+	consola.consola.box(["Upgrade plan", JSON.stringify(result.plan, null, 2)].join("\n\n"));
+	if (upgradeMode === "auto") await waitForAutomaticUpgrade(request);
+	return result;
+}
+
+//#endregion
+//#region ../../packages-private/scripting-utils/source/env.ts
+/**
+* This module exports shared environment utilities for the AIO Commerce SDK.
+* @packageDocumentation
+*/
+const { context } = _adobe_aio_lib_ims.default;
+const IMS_KEYS = {
+	client_id: "AIO_COMMERCE_AUTH_IMS_CLIENT_ID",
+	client_secrets: "AIO_COMMERCE_AUTH_IMS_CLIENT_SECRETS",
+	ims_org_id: "AIO_COMMERCE_AUTH_IMS_ORG_ID",
+	scopes: "AIO_COMMERCE_AUTH_IMS_SCOPES",
+	technical_account_email: "AIO_COMMERCE_AUTH_IMS_TECHNICAL_ACCOUNT_EMAIL",
+	technical_account_id: "AIO_COMMERCE_AUTH_IMS_TECHNICAL_ACCOUNT_ID"
+};
+/**
+* Replaces or creates an environment variable in a .env file and sets it in the
+* current process.
+* @param filePath - The path to the .env file
+* @param key - The environment variable key to replace or create
+* @param value - The new value for the environment variable
+*/
+function replaceEnvVar(filePath, key, value) {
+	const envPath = path.default.resolve(filePath);
+	const envLines = (0, fs.readFileSync)(envPath, "utf8").split("\n");
+	const formattedValue = value.includes(" ") ? `"${value}"` : value;
+	let keyExists = false;
+	const updatedLines = envLines.map((line) => {
+		if (line.trim().startsWith("#") || !line.includes("=")) return line;
+		const [currentKey] = line.split("=");
+		if (currentKey === key) {
+			keyExists = true;
+			return `${key}=${formattedValue}`;
+		}
+		return line;
+	});
+	if (!keyExists) updatedLines.push(`${key}=${formattedValue}`);
+	(0, fs.writeFileSync)(envPath, updatedLines.join("\n"), "utf8");
+	process.env[key] = value;
+}
+/**
+* Sets the `NODE_ENV` environment variable in the current process and in the app
+* `.env` file, so the web bundler (Parcel) ships the matching React build.
+* Creates the `.env` if absent.
+* @param mode - The environment mode to set in `NODE_ENV`.
+* @param projectRoot - Resolved project root containing the `.env` file.
+*/
+function setNodeEnv(mode, projectRoot) {
+	const envPath = path.default.join(projectRoot, ".env");
+	if (!(0, fs.existsSync)(envPath)) (0, fs.writeFileSync)(envPath, "", "utf8");
+	replaceEnvVar(envPath, "NODE_ENV", mode);
+}
+/** Resolves the IMS server to server context from the project workspace credentials. */
+function resolveImsS2SContext() {
+	const [credential] = (_adobe_aio_lib_core_config.default.get("project.workspace.details.credentials") ?? []).filter(({ integration_type }) => integration_type === "oauth_server_to_server").map(({ name }) => name);
+	if (!credential) return Promise.resolve(null);
+	return context.get(credential);
+}
+/**
+* Syncs the IMS credentials environment variables from the configured IMS context in
+* the .env file, in a way that is compatible with `@adobe/aio-commerce-lib-auth`.
+* @param projectRoot - Resolved project root containing the `.env` file.
+*/
+async function syncImsCredentials(projectRoot) {
+	const envPath = path.default.join(projectRoot, ".env");
+	if (!(0, fs.existsSync)(envPath)) return {
+		ok: false,
+		reason: "missing-env"
+	};
+	const envVars = dotenv.default.parse((0, fs.readFileSync)(envPath, "utf8"));
+	const imsContext = await resolveImsS2SContext();
+	if (!imsContext) return {
+		ok: false,
+		reason: "no-ims-context"
+	};
+	const { data } = imsContext;
+	for (const [key, value] of Object.entries(data)) {
+		const oauthKey = IMS_KEYS[key];
+		if (!oauthKey) continue;
+		if (!envVars[oauthKey] || envVars[oauthKey] !== value) replaceEnvVar(envPath, oauthKey, value);
+	}
+	return { ok: true };
+}
+
+//#endregion
+//#region source/commands/hooks/pre-app-build.ts
+/**
+* Runs the pre-app-build hook for the given extension.
+* @param extension - The extension to run the hook for.
+* @param projectRoot - Resolved project root containing extension files.
+* @param templatesDir - Directory containing action templates.
+* @param options - Hook options.
+* @param options.isDevSession - Whether the build runs within `aio app run` or `aio app dev`, which keeps `NODE_ENV` untouched.
+*/
+async function run$2(extension, projectRoot, templatesDir = require_web_src.TEMPLATES_DIR, { isDevSession = false } = {}) {
+	const appManifest = await require_web_src.loadAppManifest(projectRoot);
+	await require_web_src.prepareRuntimeAppConfigModule(appManifest, projectRoot);
+	if (extension === "extensibility/1") {
+		const { doc: extensibilityExtConfig } = await require_web_src.readExtConfig(require_web_src.EXTENSIBILITY_EXTENSION_POINT_ID, projectRoot);
+		await require_web_src.run$1(appManifest, projectRoot);
+		await require_web_src.generateActionFiles(appManifest, require_web_src.getRuntimeActions(extensibilityExtConfig.toJS(), "app-management"), require_web_src.EXTENSIBILITY_EXTENSION_POINT_ID, templatesDir, projectRoot);
+		consola.default.info("Syncing IMS credentials...");
+		await syncImsCredentials(projectRoot);
+		return;
+	}
+	if (extension === "configuration/1") {
+		const { doc: businessConfigExtConfig } = await require_web_src.readExtConfig(require_web_src.CONFIGURATION_EXTENSION_POINT_ID, projectRoot);
+		await require_web_src.run(appManifest, projectRoot);
+		await require_web_src.generateActionFiles(appManifest, require_web_src.getRuntimeActions(businessConfigExtConfig.toJS(), "business-configuration"), require_web_src.CONFIGURATION_EXTENSION_POINT_ID, templatesDir, projectRoot);
+		return;
+	}
+	if (extension === "backend-ui/2") {
+		if (require_webhooks.hasBackendUiV2Components(appManifest)) {
+			const extConfig = await require_web_src.updateExtConfig(appManifest, require_web_src.BACKEND_UI_V2_EXTENSION_POINT_ID, projectRoot);
+			if (extConfig.operations?.view) {
+				await require_web_src.prepareWebSourceImportAlias(extConfig, projectRoot);
+				await require_web_src.generateWebSrc(extConfig, appManifest.metadata.displayName, projectRoot, templatesDir);
+				if (!isDevSession) await setNodeEnv("production", projectRoot);
+			}
+		}
+		return;
+	}
+	throw new Error(`Unsupported extension: ${extension}`);
+}
+
+//#endregion
+//#region source/commands/hooks/pre-app-dev.ts
+/**
+* Resets the web build back to development by setting `NODE_ENV` in the process and the project `.env`.
+* @param projectRoot - Resolved project root containing the `.env` file.
+*/
+async function run$1(projectRoot) {
+	await setNodeEnv("development", projectRoot);
+}
+
+//#endregion
+//#region source/commands/hooks/pre-app-run.ts
+/**
+* Resets the web build back to development by setting `NODE_ENV` in the process and the project `.env`.
+* @param projectRoot - Resolved project root containing the `.env` file.
+*/
+async function run(projectRoot) {
+	await setNodeEnv("development", projectRoot);
+}
+
+//#endregion
+//#region source/cli/index.ts
+/**
+* Internal App Builder hook handlers, loaded by the hook files that
+* `@adobe/aio-commerce-lib-app` generates. Not part of the public API.
+* @packageDocumentation
+*/
+const USER_HOOKS_DIR = "hooks";
+const USER_HOOK_FILE_EXTENSIONS = [
+	".ts",
+	".mts",
+	".cts",
+	".js",
+	".mjs",
+	".cjs"
+];
+let isDevSession = false;
+/**
+* Finds the user hook file for a hook, looking in the extension point's `hooks`
+* folder first and then in the project root `hooks` folder.
+*
+* @param projectRoot - Resolved project root.
+* @param extensionPointId - The extension point ID, e.g. "commerce/backend-ui/2".
+* @param hookName - The hook name, e.g. "pre-app-build".
+*/
+function findUserHook(projectRoot, extensionPointId, hookName) {
+	const dirs = [(0, path.join)(projectRoot, require_web_src.getExtensionPointFolderPath(extensionPointId), USER_HOOKS_DIR), (0, path.join)(projectRoot, USER_HOOKS_DIR)];
+	for (const dir of dirs) {
+		const matches = USER_HOOK_FILE_EXTENSIONS.map((extension) => (0, path.join)(dir, `${hookName}${extension}`)).filter((file) => (0, fs.existsSync)(file));
+		if (matches.length > 1) throw new Error(`Found more than one "${hookName}" hook file in ${dir}: ${matches.join(", ")}. Keep only one.`);
+		if (matches.length === 1) return matches[0];
+	}
+	return null;
+}
+/**
+* Runs the user hook file for a hook, if there is one.
+*
+* @param projectRoot - Resolved project root.
+* @param hookName - The hook name, e.g. "pre-app-build".
+* @param extension - The extension the hook is registered for.
+* @param hookArgs - The argument the aio CLI passed to the hook.
+*/
+async function runUserHook(projectRoot, hookName, extension, hookArgs) {
+	const extensionPoint = `commerce/${extension}`;
+	const file = findUserHook(projectRoot, extensionPoint, hookName);
+	if (!file) return;
+	const { createJiti } = await import("jiti");
+	const hook = await createJiti(require("url").pathToFileURL(__filename).href).import(file, { default: true });
+	if (typeof hook !== "function") throw new Error(`${file} must export a function as its default export.`);
+	await hook(hookArgs, { extensionPoint });
+}
+/**
+* Creates an async App Builder hook that runs the given function and then the
+* user hook file, logging any error and exiting the process with code 1.
+*
+* @param hookName - The hook name, e.g. "pre-app-build".
+* @param extension - The extension the hook is registered for.
+* @param fn - The hook implementation.
+*/
+function createHook(hookName, extension, fn) {
+	return async (hookArgs) => {
+		try {
+			const projectRoot = await require_index_node.getProjectRootDirectory();
+			await fn(projectRoot);
+			await runUserHook(projectRoot, hookName, extension, hookArgs);
+		} catch (error) {
+			if (error instanceof _adobe_aio_commerce_lib_core_error.CommerceSdkValidationError) consola.default.error(error.display());
+			else consola.default.error(error);
+			process.exit(1);
+		}
+	};
+}
+/**
+* Creates the `pre-app-build` hook for the given extension.
+* @param extension - The extension the hook is registered for.
+*/
+function preAppBuild(extension) {
+	return createHook("pre-app-build", extension, (projectRoot) => run$2(extension, projectRoot, require_web_src.TEMPLATES_DIR, { isDevSession }));
+}
+/**
+* Creates the `pre-app-run` hook for the given extension.
+* @param extension - The extension the hook is registered for.
+*/
+function preAppRun(extension) {
+	return createHook("pre-app-run", extension, (projectRoot) => {
+		isDevSession = true;
+		return run(projectRoot);
+	});
+}
+/**
+* Creates the `pre-app-dev` hook for the given extension.
+* @param extension - The extension the hook is registered for.
+*/
+function preAppDev(extension) {
+	return createHook("pre-app-dev", extension, (projectRoot) => {
+		isDevSession = true;
+		return run$1(projectRoot);
+	});
+}
+/**
+* Creates the `post-app-deploy` hook for the given extension.
+* @param extension - The extension the hook is registered for.
+*/
+function postAppDeploy(extension) {
+	return createHook("post-app-deploy", extension, () => run$3());
+}
+
+//#endregion
+exports.postAppDeploy = postAppDeploy;
+exports.preAppBuild = preAppBuild;
+exports.preAppDev = preAppDev;
+exports.preAppRun = preAppRun;

package/dist/cjs/cli/index.d.cts

@@ -0,0 +1,40 @@
+/**
+ * @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.
+ */
+
+//#region source/commands/hooks/pre-app-build.d.ts
+/** The extensions that register a `pre-app-build` hook. */
+type Extension = "extensibility/1" | "configuration/1" | "backend-ui/2";
+//#endregion
+//#region source/cli/index.d.ts
+/**
+ * Creates the `pre-app-build` hook for the given extension.
+ * @param extension - The extension the hook is registered for.
+ */
+export declare function preAppBuild(extension: Extension): (hookArgs?: unknown) => Promise<void>;
+/**
+ * Creates the `pre-app-run` hook for the given extension.
+ * @param extension - The extension the hook is registered for.
+ */
+export declare function preAppRun(extension: Extension): (hookArgs?: unknown) => Promise<void>;
+/**
+ * Creates the `pre-app-dev` hook for the given extension.
+ * @param extension - The extension the hook is registered for.
+ */
+export declare function preAppDev(extension: Extension): (hookArgs?: unknown) => Promise<void>;
+/**
+ * Creates the `post-app-deploy` hook for the given extension.
+ * @param extension - The extension the hook is registered for.
+ */
+export declare function postAppDeploy(extension: Extension): (hookArgs?: unknown) => Promise<void>;
+//#endregion