@powerlines/plugin-webpack 0.5.240 → 0.5.241

package/dist/powerlines/src/api.mjs

@@ -0,0 +1,566 @@
+import { version } from "../package.mjs";
+import { emitBuiltinTypes, formatTypes } from "./internal/helpers/generate-types.mjs";
+import { callHook } from "./internal/helpers/hooks.mjs";
+import { installDependencies } from "./internal/helpers/install-dependencies.mjs";
+import { getParsedTypeScriptConfig, isIncludeMatchFound } from "./lib/typescript/tsconfig.mjs";
+import { getTsconfigDtsPath, initializeTsconfig, resolveTsconfig } from "./internal/helpers/resolve-tsconfig.mjs";
+import { checkDedupe, findInvalidPluginConfig, isPlugin, isPluginConfig, isPluginConfigObject, isPluginConfigTuple } from "./plugin-utils/helpers.mjs";
+import { formatFolder } from "./lib/utilities/format.mjs";
+import { writeMetaFile } from "./lib/utilities/meta.mjs";
+import { PowerlinesAPIContext } from "./lib/contexts/api-context.mjs";
+import { getFileHeader } from "./lib/utilities/file-header.mjs";
+import { omit } from "@stryke/helpers/omit";
+import { joinPaths } from "@stryke/path/join-paths";
+import { formatLogMessage } from "@storm-software/config-tools/logger/console";
+import { toArray } from "@stryke/convert/to-array";
+import { createDirectory } from "@stryke/fs/helpers";
+import { install } from "@stryke/fs/install";
+import { listFiles } from "@stryke/fs/list-files";
+import { isPackageExists } from "@stryke/fs/package-fns";
+import { resolvePackage } from "@stryke/fs/resolve";
+import { appendPath } from "@stryke/path/append";
+import { replacePath } from "@stryke/path/replace";
+import { isError } from "@stryke/type-checks/is-error";
+import { isFunction } from "@stryke/type-checks/is-function";
+import { isNumber } from "@stryke/type-checks/is-number";
+import { isObject } from "@stryke/type-checks/is-object";
+import { isPromiseLike } from "@stryke/type-checks/is-promise";
+import { isSet } from "@stryke/type-checks/is-set";
+import { isSetObject } from "@stryke/type-checks/is-set-object";
+import { isSetString } from "@stryke/type-checks/is-set-string";
+import { isString } from "@stryke/type-checks/is-string";
+import chalk from "chalk";
+import Handlebars from "handlebars";
+
+//#region ../powerlines/src/api.ts
+/**
+* The Powerlines API class
+*
+* @remarks
+* This class is responsible for managing the Powerlines project lifecycle, including initialization, building, and finalization.
+*
+* @public
+*/
+var PowerlinesAPI = class PowerlinesAPI {
+	/**
+	* The Powerlines context
+	*/
+	#context;
+	/**
+	* The Powerlines context
+	*/
+	get context() {
+		return this.#context;
+	}
+	/**
+	* Create a new Powerlines API instance
+	*
+	* @param context - The Powerlines context
+	*/
+	constructor(context) {
+		this.#context = context;
+	}
+	/**
+	* Initialize a Powerlines API instance
+	*
+	* @param workspaceRoot - The directory of the underlying workspace the Powerlines project exists in
+	* @param config - An object containing the configuration required to run Powerlines tasks.
+	* @returns A new instance of the Powerlines API
+	*/
+	static async from(workspaceRoot, config) {
+		const api = new PowerlinesAPI(await PowerlinesAPIContext.from(workspaceRoot, config));
+		api.#context.$$internal = {
+			api,
+			addPlugin: api.#addPlugin.bind(api)
+		};
+		api.context.info(`🔌 The Powerlines Engine v${version} has started`);
+		for (const plugin of api.context.config.plugins ?? []) await api.#addPlugin(plugin);
+		if (api.context.plugins.length === 0) api.context.warn("No Powerlines plugins were specified in the options. Please ensure this is correct, as it is generally not recommended.");
+		const pluginConfig = await api.callHook("config", {
+			environment: await api.context.getEnvironment(),
+			sequential: true,
+			result: "merge"
+		});
+		await api.context.withUserConfig(pluginConfig, { isHighPriority: false });
+		return api;
+	}
+	/**
+	* Prepare the Powerlines API
+	*
+	* @remarks
+	* This method will prepare the Powerlines API for use, initializing any necessary resources.
+	*
+	* @param inlineConfig - The inline configuration for the prepare command
+	*/
+	async prepare(inlineConfig = { command: "prepare" }) {
+		this.context.info(" 🏗️  Preparing the Powerlines project");
+		this.context.debug(" Aggregating configuration options for the Powerlines project");
+		await this.context.withInlineConfig(inlineConfig);
+		await this.#executeEnvironments(async (context) => {
+			context.debug(`Initializing the processing options for the Powerlines project.`);
+			await this.callHook("configResolved", {
+				environment: context,
+				order: "pre"
+			});
+			await initializeTsconfig(context);
+			await this.callHook("configResolved", {
+				environment: context,
+				order: "normal"
+			});
+			if (context.entry.length > 0) context.debug(`The configuration provided ${toArray(context.config.entry).length} entry point(s), Powerlines has found ${context.entry.length} entry files(s) for the ${context.config.title} project${context.entry.length > 0 && context.entry.length < 10 ? `: \n${context.entry.map((entry) => `- ${entry.file}${entry.output ? ` -> ${entry.output}` : ""}`).join(" \n")}` : ""}`);
+			else context.warn(`No entry files were found for the ${context.config.title} project. Please ensure this is correct. Powerlines plugins generally require at least one entry point to function properly.`);
+			await resolveTsconfig(context);
+			await installDependencies(context);
+			await this.callHook("configResolved", {
+				environment: context,
+				order: "post"
+			});
+			context.trace(`Powerlines configuration has been resolved: \n\n${formatLogMessage({
+				...context.config,
+				userConfig: isSetObject(context.config.userConfig) ? omit(context.config.userConfig, ["plugins"]) : void 0,
+				inlineConfig: isSetObject(context.config.inlineConfig) ? omit(context.config.inlineConfig, ["plugins"]) : void 0,
+				plugins: context.plugins.map((plugin) => plugin.plugin.name)
+			})}`);
+			if (!context.fs.existsSync(context.cachePath)) await createDirectory(context.cachePath);
+			if (!context.fs.existsSync(context.dataPath)) await createDirectory(context.dataPath);
+			await this.callHook("prepare", {
+				environment: context,
+				order: "pre"
+			});
+			await this.callHook("prepare", {
+				environment: context,
+				order: "normal"
+			});
+			if (context.config.output.dts !== false) {
+				context.debug(`Preparing the TypeScript definitions for the Powerlines project.`);
+				if (context.fs.existsSync(context.dtsPath)) await context.fs.remove(context.dtsPath);
+				if (!await resolvePackage("typescript")) throw new Error("Could not resolve TypeScript package location. Please ensure TypeScript is installed.");
+				context.debug("Running TypeScript compiler for built-in runtime module files.");
+				let types = await emitBuiltinTypes(context, (await context.getBuiltins()).reduce((ret, builtin) => {
+					const formatted = replacePath(builtin.path, context.workspaceConfig.workspaceRoot);
+					if (!ret.includes(formatted)) ret.push(formatted);
+					return ret;
+				}, []));
+				context.debug(`Generating TypeScript declaration file ${context.dtsPath}.`);
+				const directives = [];
+				const asNextParam = (previousResult) => isObject(previousResult) ? previousResult.code : previousResult;
+				let result = await this.callHook("types", {
+					environment: context,
+					sequential: true,
+					order: "pre",
+					result: "merge",
+					asNextParam
+				}, types);
+				if (result) {
+					if (isSetObject(result)) {
+						types = result.code;
+						if (Array.isArray(result.directives) && result.directives.length > 0) directives.push(...result.directives);
+					} else if (isSetString(result)) types = result;
+				}
+				result = await this.callHook("types", {
+					environment: context,
+					sequential: true,
+					order: "normal",
+					result: "merge",
+					asNextParam
+				}, types);
+				if (result) {
+					if (isSetObject(result)) {
+						types = result.code;
+						if (Array.isArray(result.directives) && result.directives.length > 0) directives.push(...result.directives);
+					} else if (isSetString(result)) types = result;
+				}
+				result = await this.callHook("types", {
+					environment: context,
+					sequential: true,
+					order: "post",
+					result: "merge",
+					asNextParam
+				}, types);
+				if (result) {
+					if (isSetObject(result)) {
+						types = result.code;
+						if (Array.isArray(result.directives) && result.directives.length > 0) directives.push(...result.directives);
+					} else if (isSetString(result)) types = result;
+				}
+				if (isSetString(types?.trim()) || directives.length > 0) await context.fs.write(context.dtsPath, `${directives.length > 0 ? `${directives.map((directive) => `/// <reference types="${directive}" />`).join("\n")}
+
+` : ""}${getFileHeader(context, {
+					directive: null,
+					prettierIgnore: false
+				})}
+
+${formatTypes(types)}
+`);
+				else {
+					const dtsRelativePath = getTsconfigDtsPath(context);
+					if (context.tsconfig.tsconfigJson.include && isIncludeMatchFound(dtsRelativePath, context.tsconfig.tsconfigJson.include)) {
+						const normalizedDtsRelativePath = dtsRelativePath.startsWith("./") ? dtsRelativePath.slice(2) : dtsRelativePath;
+						context.tsconfig.tsconfigJson.include = context.tsconfig.tsconfigJson.include.filter((includeValue) => includeValue?.toString() !== normalizedDtsRelativePath);
+						await context.fs.write(context.tsconfig.tsconfigFilePath, JSON.stringify(context.tsconfig.tsconfigJson, null, 2));
+					}
+				}
+			}
+			context.tsconfig = getParsedTypeScriptConfig(context.workspaceConfig.workspaceRoot, context.config.projectRoot, context.config.tsconfig);
+			if (!context.tsconfig) throw new Error("Failed to parse the TypeScript configuration file.");
+			this.context.debug("Formatting files generated during the prepare step.");
+			await Promise.all([formatFolder(context, context.builtinsPath), formatFolder(context, context.entryPath)]);
+			await this.callHook("prepare", {
+				environment: context,
+				order: "post"
+			});
+			await writeMetaFile(context);
+			context.persistedMeta = context.meta;
+		});
+		this.context.debug("✔ Powerlines preparation has completed successfully");
+	}
+	/**
+	* Create a new Powerlines project
+	*
+	* @remarks
+	* This method will create a new Powerlines project in the current directory.
+	*
+	* @param inlineConfig - The inline configuration for the new command
+	* @returns A promise that resolves when the project has been created
+	*/
+	async new(inlineConfig) {
+		this.context.info("🆕 Creating a new Powerlines project");
+		await this.prepare(inlineConfig);
+		await this.#executeEnvironments(async (context) => {
+			context.debug("Initializing the processing options for the Powerlines project.");
+			await this.callHook("new", {
+				environment: context,
+				order: "pre"
+			});
+			const files = await listFiles(joinPaths(context.powerlinesPath, "files/common/**/*.hbs"));
+			for (const file of files) {
+				context.trace(`Adding template file to project: ${file}`);
+				const template = Handlebars.compile(file);
+				await context.fs.write(joinPaths(context.config.projectRoot, file.replace(".hbs", "")), template(context));
+			}
+			await this.callHook("new", {
+				environment: context,
+				order: "normal"
+			});
+			if (context.config.projectType === "application") {
+				const files$1 = await listFiles(joinPaths(context.powerlinesPath, "files/application/**/*.hbs"));
+				for (const file of files$1) {
+					context.trace(`Adding application template file: ${file}`);
+					const template = Handlebars.compile(file);
+					await context.fs.write(joinPaths(context.config.projectRoot, file.replace(".hbs", "")), template(context));
+				}
+			} else {
+				const files$1 = await listFiles(joinPaths(context.powerlinesPath, "files/library/**/*.hbs"));
+				for (const file of files$1) {
+					context.trace(`Adding library template file: ${file}`);
+					const template = Handlebars.compile(file);
+					await context.fs.write(joinPaths(context.config.projectRoot, file.replace(".hbs", "")), template(context));
+				}
+			}
+			await this.callHook("new", {
+				environment: context,
+				order: "post"
+			});
+		});
+		this.context.debug("✔ Powerlines new command completed successfully");
+	}
+	/**
+	* Clean any previously prepared artifacts
+	*
+	* @remarks
+	* This method will remove the previous Powerlines artifacts from the project.
+	*
+	* @param inlineConfig - The inline configuration for the clean command
+	* @returns A promise that resolves when the clean command has completed
+	*/
+	async clean(inlineConfig = { command: "clean" }) {
+		this.context.info("🧹 Cleaning the previous Powerlines artifacts");
+		await this.prepare(inlineConfig);
+		await this.#executeEnvironments(async (context) => {
+			context.debug("Cleaning the project's dist and artifacts directories.");
+			await context.fs.remove(joinPaths(context.workspaceConfig.workspaceRoot, context.config.output.buildPath));
+			await context.fs.remove(joinPaths(context.workspaceConfig.workspaceRoot, context.config.projectRoot, context.config.output.artifactsPath));
+			await this.callHook("clean", {
+				environment: context,
+				sequential: false
+			});
+		});
+		this.context.debug("✔ Powerlines cleaning completed successfully");
+	}
+	/**
+	* Lint the project
+	*
+	* @param inlineConfig - The inline configuration for the lint command
+	* @returns A promise that resolves when the lint command has completed
+	*/
+	async lint(inlineConfig = { command: "lint" }) {
+		this.context.info("📋 Linting the Powerlines project");
+		await this.prepare(inlineConfig);
+		await this.#executeEnvironments(async (context) => {
+			if (context.config.lint !== false) await this.callHook("lint", {
+				environment: context,
+				sequential: false
+			});
+		});
+		this.context.debug("✔ Powerlines linting completed successfully");
+	}
+	/**
+	* Build the project
+	*
+	* @remarks
+	* This method will build the Powerlines project, generating the necessary artifacts.
+	*
+	* @param inlineConfig - The inline configuration for the build command
+	* @returns A promise that resolves when the build command has completed
+	*/
+	async build(inlineConfig = { command: "build" }) {
+		this.context.info("📦  Building the Powerlines project");
+		await this.prepare(inlineConfig);
+		if (this.context.config.singleBuild) await this.#handleBuild(await this.#context.toEnvironment());
+		else await this.#executeEnvironments(async (context) => {
+			await this.#handleBuild(context);
+		});
+		this.context.debug("✔ Powerlines build completed successfully");
+	}
+	/**
+	* Prepare the documentation for the project
+	*
+	* @param inlineConfig - The inline configuration for the docs command
+	* @returns A promise that resolves when the documentation generation has completed
+	*/
+	async docs(inlineConfig = { command: "docs" }) {
+		this.context.info("📓 Generating documentation for the Powerlines project");
+		await this.prepare(inlineConfig);
+		await this.#executeEnvironments(async (context) => {
+			context.debug("Writing documentation for the Powerlines project artifacts.");
+			await this.prepare(inlineConfig);
+			await this.#executeEnvironments(async (context$1) => {
+				await this.callHook("docs", { environment: context$1 });
+			});
+		});
+		this.context.debug("✔ Powerlines documentation generation completed successfully");
+	}
+	/**
+	* Deploy the project source code
+	*
+	* @remarks
+	* This method will prepare and build the Powerlines project, generating the necessary artifacts for the deployment.
+	*
+	* @param inlineConfig - The inline configuration for the deploy command
+	*/
+	async deploy(inlineConfig = { command: "deploy" }) {
+		this.context.info("🚀 Deploying the Powerlines project");
+		await this.prepare(inlineConfig);
+		await this.#executeEnvironments(async (context) => {
+			await this.callHook("deploy", { environment: context });
+		});
+		this.context.debug("✔ Powerlines deploy completed successfully");
+	}
+	/**
+	* Finalization process
+	*
+	* @remarks
+	* This step includes any final processes or clean up required by Powerlines. It will be run after each Powerlines command.
+	*
+	* @returns A promise that resolves when the finalization process has completed
+	*/
+	async finalize() {
+		this.context.info("🏁 Powerlines finalization processes started");
+		await this.#executeEnvironments(async (context) => {
+			await this.callHook("finalize", { environment: context });
+			await context.fs.dispose();
+		});
+		this.context.debug("✔ Powerlines finalization completed successfully");
+	}
+	/**
+	* Invokes the configured plugin hooks
+	*
+	* @remarks
+	* By default, it will call the `"pre"`, `"normal"`, and `"post"` ordered hooks in sequence
+	*
+	* @param hook - The hook to call
+	* @param options - The options to provide to the hook
+	* @param args - The arguments to pass to the hook
+	* @returns The result of the hook call
+	*/
+	async callHook(hook, options, ...args) {
+		return callHook(isSetObject(options?.environment) ? options.environment : await this.#context.getEnvironment(options?.environment), hook, {
+			sequential: true,
+			...options
+		}, ...args);
+	}
+	/**
+	* Dispose of the Powerlines API instance
+	*
+	* @remarks
+	* This method will finalize the Powerlines API instance, cleaning up any resources used.
+	*/
+	async [Symbol.asyncDispose]() {
+		await this.finalize();
+	}
+	async #handleBuild(context) {
+		await this.callHook("build", {
+			environment: context,
+			order: "pre"
+		});
+		context.debug("Formatting the generated entry files before the build process starts.");
+		await formatFolder(context, context.entryPath);
+		await this.callHook("build", {
+			environment: context,
+			order: "normal"
+		});
+		if (context.config.output.buildPath !== context.config.output.outputPath) {
+			const sourcePath = appendPath(context.config.output.buildPath, context.workspaceConfig.workspaceRoot);
+			const destinationPath = joinPaths(appendPath(context.config.output.outputPath, context.workspaceConfig.workspaceRoot), "dist");
+			if (context.fs.existsSync(sourcePath) && sourcePath !== destinationPath) {
+				context.debug(`Copying build output files from project's build directory (${context.config.output.buildPath}) to the workspace's output directory (${context.config.output.outputPath}).`);
+				await context.fs.copy(sourcePath, destinationPath);
+			}
+		}
+		await Promise.all(context.config.output.assets.map(async (asset) => {
+			context.trace(`Copying asset(s): ${chalk.redBright(context.workspaceConfig.workspaceRoot === asset.input ? asset.glob : joinPaths(replacePath(asset.input, context.workspaceConfig.workspaceRoot), asset.glob))} -> ${chalk.greenBright(joinPaths(replacePath(asset.output, context.workspaceConfig.workspaceRoot), asset.glob))} ${Array.isArray(asset.ignore) && asset.ignore.length > 0 ? ` (ignoring: ${asset.ignore.map((i) => chalk.yellowBright(i)).join(", ")})` : ""}`);
+			await context.fs.copy(asset, asset.output);
+		}));
+		await this.callHook("build", {
+			environment: context,
+			order: "post"
+		});
+	}
+	/**
+	* Get the configured environments
+	*
+	* @returns The configured environments
+	*/
+	async #getEnvironments() {
+		if (!this.context.config.environments || Object.keys(this.context.config.environments).length <= 1) {
+			this.context.debug("No environments are configured for this Powerlines project. Using the default environment.");
+			return [await this.context.getEnvironment()];
+		}
+		this.context.debug(`Found ${Object.keys(this.context.config.environments).length} configured environment(s) for this Powerlines project.`);
+		return (await Promise.all(Object.entries(this.context.config.environments).map(async ([name, config]) => {
+			if (!await this.context.getEnvironmentSafe(name)) {
+				const resolvedEnvironment = await this.callHook("configEnvironment", { environment: name }, name, config);
+				if (resolvedEnvironment) this.context.environments[name] = await this.context.in(resolvedEnvironment);
+			}
+			return this.context.environments[name];
+		}))).filter((context) => isSet(context));
+	}
+	/**
+	* Execute a handler function for each environment
+	*
+	* @param handle - The handler function to execute for each environment
+	*/
+	async #executeEnvironments(handle) {
+		await Promise.all((await this.#getEnvironments()).map(async (context) => {
+			return Promise.resolve(handle(context));
+		}));
+	}
+	/**
+	* Add a Powerlines plugin used in the build process
+	*
+	* @param config - The import path of the plugin to add
+	*/
+	async #addPlugin(config) {
+		if (config) {
+			const result = await this.#initPlugin(config);
+			if (!result) return;
+			for (const plugin of result) {
+				this.context.debug(`Successfully initialized the ${chalk.bold.cyanBright(plugin.name)} plugin`);
+				await this.context.addPlugin(plugin);
+			}
+		}
+	}
+	/**
+	* Initialize a Powerlines plugin
+	*
+	* @param config - The configuration for the plugin
+	* @returns The initialized plugin instance, or null if the plugin was a duplicate
+	* @throws Will throw an error if the plugin cannot be found or is invalid
+	*/
+	async #initPlugin(config) {
+		let awaited = config;
+		if (isPromiseLike(config)) awaited = await Promise.resolve(config);
+		if (!isPluginConfig(awaited)) {
+			const invalid = findInvalidPluginConfig(awaited);
+			throw new Error(`Invalid ${invalid && invalid.length > 1 ? "plugins" : "plugin"} specified in the configuration - ${invalid && invalid.length > 0 ? JSON.stringify(awaited) : invalid?.join("\n\n")} \n\nPlease ensure the value is one of the following: \n - an instance of \`Plugin\` \n - a plugin name \n - an object with the \`plugin\` and \`options\` properties \n - a tuple array with the plugin and options \n - a factory function that returns a plugin or array of plugins \n - an array of plugins or plugin configurations`);
+		}
+		let plugins;
+		if (isPlugin(awaited)) plugins = [awaited];
+		else if (isFunction(awaited)) plugins = toArray(await Promise.resolve(awaited()));
+		else if (isString(awaited)) {
+			const resolved = await this.#resolvePlugin(awaited);
+			if (isFunction(resolved)) plugins = toArray(await Promise.resolve(resolved()));
+			else plugins = toArray(resolved);
+		} else if (Array.isArray(awaited) && awaited.every(isPlugin)) plugins = awaited;
+		else if (Array.isArray(awaited) && awaited.every(isPluginConfig)) {
+			plugins = [];
+			for (const pluginConfig of awaited) {
+				const initialized = await this.#initPlugin(pluginConfig);
+				if (initialized) plugins.push(...initialized);
+			}
+		} else if (isPluginConfigTuple(awaited) || isPluginConfigObject(awaited)) {
+			let pluginConfig;
+			let pluginOptions;
+			if (isPluginConfigTuple(awaited)) {
+				pluginConfig = awaited[0];
+				pluginOptions = awaited?.length === 2 ? awaited[1] : void 0;
+			} else {
+				pluginConfig = awaited.plugin;
+				pluginOptions = awaited.options;
+			}
+			if (isSetString(pluginConfig)) {
+				const resolved = await this.#resolvePlugin(pluginConfig);
+				if (isFunction(resolved)) plugins = toArray(await Promise.resolve(pluginOptions ? resolved(pluginOptions) : resolved()));
+				else plugins = toArray(resolved);
+			} else if (isFunction(pluginConfig)) plugins = toArray(await Promise.resolve(pluginConfig(pluginOptions)));
+			else if (Array.isArray(pluginConfig) && pluginConfig.every(isPlugin)) plugins = pluginConfig;
+			else if (isPlugin(pluginConfig)) plugins = toArray(pluginConfig);
+		}
+		if (!plugins) throw new Error(`The plugin configuration ${JSON.stringify(awaited)} is invalid. This configuration must point to a valid Powerlines plugin module.`);
+		if (plugins.length > 0 && !plugins.every(isPlugin)) throw new Error(`The plugin option ${JSON.stringify(plugins)} does not export a valid module. This configuration must point to a valid Powerlines plugin module.`);
+		const result = [];
+		for (const plugin of plugins) if (checkDedupe(plugin, this.context.plugins)) this.context.trace(`Duplicate ${chalk.bold.cyanBright(plugin.name)} plugin dependency detected - Skipping initialization.`);
+		else {
+			result.push(plugin);
+			this.context.trace(`Initializing the ${chalk.bold.cyanBright(plugin.name)} plugin...`);
+		}
+		return result;
+	}
+	async #resolvePlugin(pluginPath) {
+		if (pluginPath.startsWith("@") && pluginPath.split("/").filter(Boolean).length > 2) {
+			const splits = pluginPath.split("/").filter(Boolean);
+			pluginPath = `${splits[0]}/${splits[1]}`;
+		}
+		const isInstalled = isPackageExists(pluginPath, { paths: [this.context.workspaceConfig.workspaceRoot, this.context.config.projectRoot] });
+		if (!isInstalled && this.context.config.autoInstall) {
+			this.#context.warn(`The plugin package "${pluginPath}" is not installed. It will be installed automatically.`);
+			const result = await install(pluginPath, { cwd: this.context.config.projectRoot });
+			if (isNumber(result.exitCode) && result.exitCode > 0) {
+				this.#context.error(result.stderr);
+				throw new Error(`An error occurred while installing the build plugin package "${pluginPath}" `);
+			}
+		}
+		try {
+			const module = await this.context.resolver.plugin.import(this.context.resolver.plugin.esmResolve(joinPaths(pluginPath, "plugin")));
+			const result = module.plugin ?? module.default;
+			if (!result) throw new Error(`The plugin package "${pluginPath}" does not export a valid module.`);
+			return result;
+		} catch (error) {
+			try {
+				const module = await this.context.resolver.plugin.import(this.context.resolver.plugin.esmResolve(pluginPath));
+				const result = module.plugin ?? module.default;
+				if (!result) throw new Error(`The plugin package "${pluginPath}" does not export a valid module.`);
+				return result;
+			} catch {
+				if (!isInstalled) throw new Error(`The plugin package "${pluginPath}" is not installed. Please install the package using the command: "npm install ${pluginPath} --save-dev"`);
+				else throw new Error(`An error occurred while importing the build plugin package "${pluginPath}":
+${isError(error) ? error.message : String(error)}
+
+Note: Please ensure the plugin package's default export is a class that extends \`Plugin\` with a constructor that excepts a single arguments of type \`PluginOptions\`.`);
+			}
+		}
+	}
+};
+
+//#endregion
+export {  };

package/dist/powerlines/src/internal/helpers/environment.cjs

@@ -0,0 +1,50 @@
+const require_rolldown_runtime = require('../../../../_virtual/rolldown_runtime.cjs');
+const require_environments = require('../../lib/constants/environments.cjs');
+let defu = require("defu");
+defu = require_rolldown_runtime.__toESM(defu);
+let __stryke_string_format_title_case = require("@stryke/string-format/title-case");
+
+//#region ../powerlines/src/internal/helpers/environment.ts
+function createEnvironment(name, userConfig) {
+	return (0, defu.default)(userConfig.environments?.[name] ?? {}, {
+		name,
+		title: userConfig.title || (0, __stryke_string_format_title_case.titleCase)(userConfig.name),
+		ssr: false,
+		mainFields: userConfig.build?.platform === "browser" ? [
+			"browser",
+			"module",
+			"jsnext:main",
+			"jsnext"
+		] : [
+			"module",
+			"jsnext:main",
+			"jsnext"
+		],
+		extensions: [
+			".mjs",
+			".js",
+			".mts",
+			".ts",
+			".jsx",
+			".tsx",
+			".json"
+		],
+		consumer: userConfig.build?.platform === "browser" ? "client" : "server",
+		preview: userConfig.build?.platform === "browser" ? {
+			port: 5173,
+			open: true,
+			strictPort: false,
+			host: "localhost",
+			allowedHosts: ["."],
+			cors: true,
+			headers: {}
+		} : void 0
+	}, userConfig);
+}
+function createDefaultEnvironment(userConfig) {
+	return createEnvironment(require_environments.DEFAULT_ENVIRONMENT, userConfig);
+}
+
+//#endregion
+exports.createDefaultEnvironment = createDefaultEnvironment;
+exports.createEnvironment = createEnvironment;

package/dist/powerlines/src/internal/helpers/environment.mjs

@@ -0,0 +1,47 @@
+import { DEFAULT_ENVIRONMENT } from "../../lib/constants/environments.mjs";
+import defu$1 from "defu";
+import { titleCase } from "@stryke/string-format/title-case";
+
+//#region ../powerlines/src/internal/helpers/environment.ts
+function createEnvironment(name, userConfig) {
+	return defu$1(userConfig.environments?.[name] ?? {}, {
+		name,
+		title: userConfig.title || titleCase(userConfig.name),
+		ssr: false,
+		mainFields: userConfig.build?.platform === "browser" ? [
+			"browser",
+			"module",
+			"jsnext:main",
+			"jsnext"
+		] : [
+			"module",
+			"jsnext:main",
+			"jsnext"
+		],
+		extensions: [
+			".mjs",
+			".js",
+			".mts",
+			".ts",
+			".jsx",
+			".tsx",
+			".json"
+		],
+		consumer: userConfig.build?.platform === "browser" ? "client" : "server",
+		preview: userConfig.build?.platform === "browser" ? {
+			port: 5173,
+			open: true,
+			strictPort: false,
+			host: "localhost",
+			allowedHosts: ["."],
+			cors: true,
+			headers: {}
+		} : void 0
+	}, userConfig);
+}
+function createDefaultEnvironment(userConfig) {
+	return createEnvironment(DEFAULT_ENVIRONMENT, userConfig);
+}
+
+//#endregion
+export { createDefaultEnvironment, createEnvironment };